Nền tảng - User Requirement Document

Module: CORE-16 · Version: v1.0 · Last reviewed: 2026-06-15

Mục đích

Nền tảng là backbone real-time xuyên suốt của KICKO. Nó biến một hoạt động nghiệp vụ đáng chú ý - tạo ra ở bất kỳ đâu trong hệ thống - thành một thông báo bền vững theo từng người và đẩy nó tới màn hình của đúng user ngay khi nó xảy ra, qua một kênh riêng tư, được mã hóa. Các service tạo ra hoạt động; nền tảng quyết định ai cần biết về chúng và gửi chúng live.

Nền tảng cũng là backbone media dùng chung của KICKO. Nó cho mọi service một cách để lưu một nhị phân trên object storage tương thích S3, lấy lại một link ổn định, và giữ một bản ghi meta-link bền vững gắn object với thực thể nó minh họa - cộng media tham chiếu dùng chung (một bundle bản địa hóa và một registry ngân hàng Việt Nam kèm logo) mà cả nền tảng đọc từ một nguồn.

Phạm vi

Bao gồm	Loại trừ
Pipeline activity-notification hướng sự kiện (tiêu thụ → phân giải → render → lưu → đẩy)	Kênh email / SMS / push-notification
Phân giải recipient theo phạm vi tổ chức / merchant / danh sách user	Mô hình tùy chọn, tắt, hoặc đăng ký thông báo theo từng user
Read API thông báo tự-giới-hạn (list, count, mark-one-read, mark-all-read)	Logic hoạt động của chính các service tạo sự kiện
Gửi WebSocket real-time được xác thực, mã hóa đầu-cuối	Tạo kiểu UI chuông / activity-feed
Hợp đồng gửi room + topic theo từng recipient ổn định, fan-out xuyên-instance	Tăng cường ủy quyền room chống xuyên-tenant (follow-up đã biết)
Điều khiển transport quản trị (trạng thái, list, send, broadcast, disconnect)	Biến đổi ảnh / tạo thumbnail / resize động
Object storage dùng chung: upload được xác thực, phục vụ inline / attachment, liệt kê, xóa	Cô lập bucket theo từng merchant hoặc lưu trữ giới hạn theo tenant
Bản ghi meta-link cho mỗi object với ràng buộc principal và một API CRUD meta-link	Một UI duyệt thư viện media được quản lý (màn hình gallery)
Bundle bản địa hóa dùng chung + registry ngân hàng Việt Nam chỉ-đọc kèm phục vụ logo	Tác giả / sửa registry ngân hàng (dữ liệu tham chiếu chỉ-đọc)

Mô hình khái niệm

5. Feature Catalog

Feature ID	Tính năng	Phase	Trạng thái	Ưu tiên
platform/ACT	Activity Notifications	P2	Built	HIGH
platform/WSS	Realtime WebSocket Stream	P2	Built	HIGH
platform/AST	Asset & Object Storage	P2	Built	HIGH
platform/MTL	Meta-Link Binding	P2	Built	HIGH
platform/BNK	Vietnamese Banks Reference Data	P2	Built	MED
platform/IDX	Search Indexing & CDC Sync	P2	Built	HIGH
platform/SCH	Unified Search Query API	P2	Built	HIGH

Tính năng

ACT - Activity Notifications Built

Feature ID: platform/ACT · Phase: P2 · PRDs: PRD-ACT-001 · Dev: @nx/signal

Làm gì cho người dùng: một hoạt động đáng chú ý ở bất kỳ đâu trong KICKO (ví dụ thanh toán thành công) trở thành một thông báo gửi đến đúng người - tất cả trong một tổ chức, tất cả trong một merchant, hoặc một danh sách có tên - được render thành một thông điệp dễ đọc và giữ bền vững để mỗi người đọc và xóa theo điều kiện của riêng mình.

Yêu cầu

ID	P	Yêu cầu
URD-ACT-001	M	Một activity event trên luồng nền tảng được tiêu thụ và biến thành một bản ghi thông báo cho mỗi recipient được phân giải.
URD-ACT-002	M	Recipient được phân giải theo phạm vi của hoạt động - cả tổ chức, cả merchant, hoặc một danh sách user cụ thể - và fallback về actor của hoạt động khi không có ai.
URD-ACT-003	M	Mỗi thông báo lưu recipient, type, organizer, nội dung đã render (text + HTML), một action URL tùy chọn, dữ liệu có cấu trúc (bao gồm actor), và một cờ đọc với timestamp đọc.
URD-ACT-004	M	Nội dung thông báo được render từ event type thành một thông điệp bản địa hóa, dễ đọc.
URD-ACT-005	M	Chỉ các event type được nhận diện mới tạo thông báo; một event type lạ bị bỏ qua mà không phát lỗi.
URD-ACT-006	M	Một user đã đăng nhập có thể list thông báo của riêng mình (phân trang / lọc), trả về kèm tổng số và số chưa đọc.
URD-ACT-007	M	Một user có thể yêu cầu một số đếm thông báo của mình (ví dụ chưa đọc) để hiển thị badge.
URD-ACT-008	M	Một user có thể đánh dấu một thông báo đã đọc và đánh dấu tất cả thông báo của mình đã đọc; mỗi cái mang một timestamp đọc.
URD-ACT-009	M	Mọi đọc và ghi thông báo đều giới hạn theo recipient đã xác thực - một user không bao giờ thấy hoặc thay đổi thông báo của user khác.

Chấp nhận

AC-ACT-01: Một hoạt động có phạm vi fan-out thành một bản ghi cho mỗi recipient

Given	When	Then
Một activity event với recipient scope merchant và ba thành viên trong merchant đó	Sự kiện được tiêu thụ	Ba bản ghi thông báo được tạo, một cho mỗi thành viên, mỗi cái với nội dung đã render, type, organizer, và isRead = false

AC-ACT-02: Không có audience thì fallback về actor

Given	When	Then
Một hoạt động mà phạm vi không phân giải ra thành viên nào	Sự kiện được tiêu thụ	Đúng một thông báo được tạo, gửi tới actor của hoạt động

AC-ACT-03: Event type lạ bị bỏ qua

Given	When	Then
Một activity event có type không được nhận diện	Sự kiện được tiêu thụ	Không thông báo nào được tạo và không lỗi nào phát ra; sự kiện bị bỏ qua

AC-ACT-04: Một user list chỉ thông báo của riêng mình kèm số đếm

Given	When	Then
Một user đã đăng nhập có thông báo, một số chưa đọc	Họ list thông báo của mình	Chỉ bản ghi của riêng họ trả về, kèm một tổng số và một số chưa đọc

AC-ACT-05: Mark-all-read làm sạch số chưa đọc

Given	When	Then
Một user có vài thông báo chưa đọc	Họ đánh dấu tất cả đã đọc	Tất cả thông báo của họ thành đã đọc với một timestamp đọc, và một số đếm sau đó trả về zero chưa đọc

AC-ACT-06: Read API là tự-giới-hạn

Given	When	Then
User A và user B mỗi người có thông báo	User A list, đếm, hoặc đánh dấu đọc	Chỉ bản ghi của user A được trả về hoặc thay đổi; của user B không bao giờ thấy hoặc thay đổi được với A

WSS - Realtime WebSocket Stream Built

Feature ID: platform/WSS · Phase: P2 · PRDs: PRD-ACT-001 · Dev: @nx/signal

Làm gì cho người dùng: ống dẫn live, riêng tư mang một thông báo tới màn hình của chủ sở hữu ngay khi nó được tạo - được xác thực, mã hóa đầu-cuối, và đủ ổn định để client đăng ký theo một hợp đồng cố định, kèm các điều khiển tinh gọn để người vận hành kiểm tra và điều phối các kết nối.

Yêu cầu

ID	P	Yêu cầu
URD-WSS-001	M	Khi một thông báo được tạo nó được đẩy live tới recipient qua WebSocket, tới kênh-theo-từng-recipient riêng của recipient đó.
URD-WSS-002	M	Client kết nối qua một socket được xác thực (JWT bearer) và hoàn tất một trao đổi khóa ECDH; tất cả payload sau handshake được mã hóa đầu-cuối.
URD-WSS-003	M	Gửi dùng một hợp đồng room/topic cố định - một room theo từng recipient và một topic notification-created - để client đăng ký theo một kênh ổn định.
URD-WSS-004	M	Gửi đến được một recipient bất kể socket của họ kết nối ở đâu, fan-out giữa các instance máy chủ.
URD-WSS-005	M	Nếu kênh real-time không khả dụng, lưu thông báo vẫn thành công và push live bị bỏ qua mà không làm hỏng pipeline; một push lỗi cho một recipient không bao giờ chặn các recipient khác.
URD-WSS-006	M	Các điều khiển transport quản trị - trạng thái kết nối, list client kết nối, get một client, broadcast, send-to-room, send-to-client, và disconnect - có sẵn sau permission.
URD-WSS-007	S	Một client kết nối chỉ nhận thông báo của kênh riêng mình và không nhận của các user khác.

Chấp nhận

AC-WSS-01: Một thông báo mới đến live trên kênh của recipient

Given	When	Then
Một recipient đang giữ một socket được xác thực, mã hóa, đăng ký kênh của mình	Một thông báo được tạo cho họ	Họ nhận nó live trên topic notification-created, được mã hóa khi truyền

AC-WSS-02: Socket không xác thực hoặc chưa handshake không nhận gì

Given	When	Then
Một socket không có JWT hợp lệ hoặc không hoàn tất handshake ECDH	Một thông báo lẽ ra được đẩy	Kết nối bị từ chối hoặc không payload giải mã được nào được gửi

AC-WSS-03: Sự cố real-time tụt xuống chỉ-lưu

Given	When	Then
Kênh real-time không khả dụng	Một hoạt động được xử lý	Các bản ghi thông báo vẫn được lưu và pipeline hoàn tất không lỗi; push live bị bỏ qua

AC-WSS-04: Một push lỗi không chặn các push khác

Given	When	Then
Một hoạt động fan-out tới vài recipient và một push của một recipient lỗi	Worker đẩy tới tất cả recipient	Các recipient còn lại vẫn nhận thông báo của mình; lỗi được cô lập

AC-WSS-05: Điều khiển transport quản trị cần permission

Given	When	Then
Một user không có permission transport	Họ gọi một điều khiển broadcast / send / disconnect	Yêu cầu bị từ chối; một người vận hành có quyền có thể kiểm tra trạng thái và điều phối kết nối

AST - Asset & Object Storage Built

Feature ID: platform/AST · Phase: P2 · PRDs: PRD-AST-001 · Dev: @nx/asset

Làm gì cho người dùng: một cách dùng chung để đặt một tệp nhị phân - một ảnh sản phẩm, một logo tổ chức, một tài liệu - vào object storage và lấy lại một link ổn định, rồi stream nó lại inline hoặc tải nó theo tên. Upload được xác thực; đọc công khai; một bucket liệt kê được và một object xóa được; một bundle bản địa hóa dùng chung chạy trên cùng bề mặt.

Yêu cầu

ID	P	Yêu cầu
URD-AST-001	M	Một upload multipart được xác thực lưu một hoặc nhiều tệp trong bucket cấu hình, gán cho mỗi cái một object name duy nhất, an toàn URL, và trả về object name cùng link định địa chỉ của nó.
URD-AST-002	M	Một upload có thể mang một folder path tùy chọn (được kiểm tra, giới hạn hai cấp) và một ràng buộc principal (principalType / principalId / variant) áp cho mỗi object đã lưu.
URD-AST-003	M	Một object đã lưu stream được inline theo object name của nó, hỗ trợ đường dẫn object lồng tới hai cấp thư mục.
URD-AST-004	M	Một object đã lưu tải về được dạng attachment (content-disposition) theo object name của nó.
URD-AST-005	M	Một delete được xác thực xóa object khỏi lưu trữ và dọn các bản ghi meta-link của nó cho bucket + object đó.
URD-AST-006	M	Một list được xác thực trả về các object của một bucket lọc theo prefix, recursion, và một giới hạn max-keys.
URD-AST-007	M	Một bundle bản địa hóa dùng chung lấy được inline và tải về được dạng attachment từ bucket cấu hình.
URD-AST-008	M	Object name và folder segment được kiểm tra trước khi lưu hoặc lấy; chỉ các header metadata trong danh sách trắng được phản chiếu lên phản hồi và nosniff được đặt trên mọi stream.

Chấp nhận

AC-AST-01: Upload lưu một object và trả về link của nó

Given	When	Then
Một caller được xác thực kèm một tệp	Họ upload nó	Tệp được lưu dưới một object name duy nhất, an toàn URL và phản hồi mang object name đó cùng một link định địa chỉ

AC-AST-02: Một object stream lại inline và tải theo tên

Given	When	Then
Một object đã lưu trước đó	Một client lấy nó theo object name, rồi theo đường dẫn download của nó	Nó stream inline ở cái đầu, và đến dạng attachment (content-disposition) ở cái sau; cả hai đặt nosniff

AC-AST-03: Delete xóa object và meta-link cùng nhau

Given	When	Then
Một object đã lưu kèm một bản ghi meta-link	Một caller được xác thực xóa nó theo object name	Object được xóa khỏi lưu trữ và các bản ghi meta-link của nó cho bucket + object đó được dọn

AC-AST-04: Đường dẫn object không hợp lệ bị từ chối

Given	When	Then
Một yêu cầu mà object name vượt độ sâu cho phép hoặc không qua kiểm tra	Object được lấy hoặc xóa	Yêu cầu bị từ chối với lỗi bad-request trước bất kỳ truy cập lưu trữ nào

MTL - Meta-Link Binding Built

Feature ID: platform/MTL · Phase: P2 · PRDs: PRD-AST-001 · Dev: @nx/asset

Làm gì cho người dùng: mỗi object đã lưu mang một bản ghi bền vững - tọa độ lưu trữ và các thuộc tính mô tả của nó - có thể ràng buộc với thực thể nghiệp vụ nó minh họa (một product, một variant, một organizer, một ledger, một category, một ticket), để một service tìm được "media cho bản ghi này" mà không phải quét bucket. Meta-link truy vấn được như một tài nguyên CRUD.

Yêu cầu

ID	P	Yêu cầu
URD-MTL-001	M	Mỗi object đã lưu có một meta-link bền vững giữ bucket, object name, link, mimetype, size, etag, metadata, storage type, và một cờ sync của nó.
URD-MTL-002	M	Một meta-link có thể tham chiếu một principal nghiệp vụ theo type + id và một variant tag tùy chọn, để một object tìm được theo thực thể nó thuộc về.
URD-MTL-003	M	Meta-link được phơi bày như một tài nguyên CRUD (find, find-by-id, find-one, count, create, update, delete) qua xác thực JWT / Basic.
URD-MTL-004	M	Xóa object nền tảng dọn các bản ghi meta-link của nó cho bucket + object đó.

Chấp nhận

AC-MTL-01: Upload ghi một meta-link với các thuộc tính của object

Given	When	Then
Một upload thành công	Lưu hoàn tất	Một meta-link được tạo ghi bucket, name, link, mimetype, size, etag, metadata, và storage type của object, với cờ sync được đặt

AC-MTL-02: Một object đã ràng buộc tìm được theo principal của nó

Given	When	Then
Một object upload kèm một principalType và principalId	Tài nguyên meta-link được truy vấn cho principal đó	Meta-link của object được trả về, định vị theo thực thể nó thuộc về

AC-MTL-03: Một meta-link ghi lỗi không làm mất object

Given	When	Then
Một upload mà bản ghi meta-link không ghi được	Upload hoàn tất	Object vẫn được lưu và được báo trong kết quả kèm một lỗi meta-link theo từng tệp; các tệp khác trong cùng upload không bị ảnh hưởng

BNK - Vietnamese Banks Reference Data Built

Feature ID: platform/BNK · Phase: P2 · PRDs: PRD-AST-001 · Dev: @nx/asset

Làm gì cho người dùng: một nguồn chỉ-đọc các ngân hàng và nhà cung cấp thanh toán Việt Nam - mỗi cái với tên ngắn và tên đầy đủ, cờ năng lực (VietQR, disburse, NAPAS), và một logo - để storefront và back office render lựa chọn và logo ngân hàng từ một registry thay vì bản sao cục bộ.

Yêu cầu

ID	P	Yêu cầu
URD-BNK-001	M	Một registry chỉ-đọc các ngân hàng / nhà cung cấp thanh toán Việt Nam phục vụ dạng JSON, mỗi entry mang một tên ngắn, một tên đầy đủ, và cờ năng lực (VietQR, disburse, NAPAS).
URD-BNK-002	M	Logo của mỗi registry entry được chiếu thành một URL tuyệt đối (nối với explorer base cấu hình) để client dùng trực tiếp.
URD-BNK-003	M	Mỗi logo ngân hàng phục vụ dạng PNG theo một tên tệp <code>.png kiểm tra theo một mẫu nghiêm ngặt, với caching immutable lâu dài.
URD-BNK-004	M	Phản hồi registry cacheable (max-age); một tên tệp logo không hợp lệ hoặc lạ trả về một lỗi bad-request / not-found có cấu trúc.

Chấp nhận

AC-BNK-01: Registry trả về entry kèm logo URL tuyệt đối

Given	When	Then
Explorer base URL cấu hình	Một client lấy registry ngân hàng	Mỗi entry được trả về với tên ngắn, tên đầy đủ, cờ năng lực, và một bankLogoUrl tuyệt đối, kèm một cache-control max-age

AC-BNK-02: Một logo ngân hàng phục vụ dạng PNG immutable

Given	When	Then
Một tên tệp logo <code>.png hợp lệ	Một client yêu cầu nó	PNG được stream với một content-type ảnh, nosniff, và một cache-control immutable lâu dài

AC-BNK-03: Một tên tệp logo không hợp lệ bị từ chối

Given	When	Then
Một tên tệp logo không qua mẫu <code>.png nghiêm ngặt, hoặc một code không có asset	Logo được yêu cầu	Một lỗi bad-request (không hợp lệ) hoặc not-found (thiếu) có cấu trúc được trả về trước bất kỳ traversal nào

IDX - Search Indexing & CDC Sync Built

Feature ID: platform/IDX · Phase: P2 · PRDs: PRD-IDX-001 · Dev: @nx/search

Làm gì cho người dùng: giữ một bề mặt tìm kiếm luôn-tươi-mới đồng bộ với cả nền tảng mà không service nào ghi vào search engine. Mọi thay đổi đã commit chảy ra thành một change-data event và một consumer duy nhất phản chiếu nó vào đúng search collection, join vào dữ liệu liên quan mỗi document cần, và fan một thay đổi bản ghi dùng chung (một đổi tên, một sửa giá, một mã dùng chung) ra mọi document phụ thuộc - để một kết quả tìm kiếm đầy đủ và hiện hành ngay khi đọc.

Yêu cầu

ID	P	Yêu cầu
URD-IDX-001	M	Mọi thay đổi đã commit của một bảng nguồn được index đều được bắt từ luồng change-data của nền tảng và phản chiếu vào đúng search collection, mà không service tạo sự kiện nào phải ghi vào search.
URD-IDX-002	M	Các bảng nguồn ánh xạ tới chín search collection (organizers, merchants, categories, devices, sale-channels, products, product-variants, inventories, users); mỗi collection có đúng một bảng-nguồn-document và các input còn lại là liên quan / dẫn xuất.
URD-IDX-003	M	Sự kiện create, update, và snapshot upsert document; một delete hoặc soft-delete ghi một tombstone để bản ghi rời khỏi kết quả trong khi giữ thứ tự phiên bản của nó.
URD-IDX-004	M	Trước khi index, mỗi document được enrich bằng cách join dữ liệu liên quan (tên merchant / organizer sở hữu, tập category, giá, ảnh, mã quét, tồn-theo-vị-trí, option facet, định danh / vai trò / organizer của user) để một kết quả tự-đầy-đủ.
URD-IDX-005	M	Một thay đổi của bản ghi dùng chung hoặc cha fan ra mọi document phụ thuộc (ví dụ đổi tên merchant hoặc organizer, đổi tên location, một mã dùng chung) qua các patch có đích, không bao giờ re-index toàn bộ.
URD-IDX-006	M	Mỗi document mang một dấu phiên bản (vị trí log nguồn) để sự kiện sai-thứ-tự hoặc replay không bao giờ ghi đè trạng thái mới hơn; patch một phần con→cha chỉ động vào trường của riêng nó và không bao giờ lật trạng thái sống / đã-xóa của cha.
URD-IDX-007	M	Sự kiện được xử lý theo lô từng-topic; một lô hỏng parse hoàn toàn, hoặc có ghi index lỗi, được báo là lỗi để retry - luồng không bao giờ âm thầm bỏ qua dữ liệu.
URD-IDX-008	M	Khi search engine hoặc một dependency enrich không khả dụng, một circuit breaker tạm dừng luồng và probe để hồi phục; các message không-route-được / poison chuyển sang một dead-letter topic thay vì chặn pipeline.
URD-IDX-009	S	Một enrich lỗi suy giảm an toàn - document vẫn được index với dữ liệu đã có trên nó; một cascade lỗi đơn lẻ không bao giờ chặn các fan-out khác trong lô.
URD-IDX-010	M	Định danh bản ghi nhúng trong filter của search engine được kiểm tra để một id sai định dạng không bao giờ làm thay đổi tập đích của một fan-out.

Chấp nhận

AC-IDX-01: Một thay đổi đã commit đến collection của nó kèm enrich

Given	When	Then
Một product variant được tạo trong commerce	Change-data event của nó được tiêu thụ	Một document xuất hiện trong collection product-variants mang dữ liệu join (tên, giá, ảnh, mã quét, tồn-theo-vị-trí, option facet)

AC-IDX-02: Một đổi tên cha fan ra các phụ thuộc

Given	When	Then
Một merchant có products, categories, và sale-channels được đổi tên	Thay đổi merchant được tiêu thụ	Document merchants và mọi document product / category / sale-channel phụ thuộc hiện tên mới, cập nhật bằng patch có đích, không re-index

AC-IDX-03: Một delete tombstone document

Given	When	Then
Một bản ghi đã index bị xóa hoặc soft-delete	Thay đổi được tiêu thụ	Một tombstone được ghi để bản ghi không còn xuất hiện trong kết quả, với thứ tự phiên bản được giữ

AC-IDX-04: Một sự kiện replay không ghi đè trạng thái mới hơn

Given	When	Then
Một document đã phản ánh một thay đổi mới hơn	Một sự kiện cũ hơn hoặc replay cho cùng bản ghi đến	Sự kiện cũ bị bỏ qua; trạng thái mới hơn được giữ

AC-IDX-05: Sự cố engine tạm dừng và hồi phục không mất mát

Given	When	Then
Search engine không khả dụng giữa luồng	Một lô được xử lý	Circuit breaker trip và luồng tạm dừng; khi hồi phục nó tiếp tục từ chỗ dừng mà không mất sự kiện

AC-IDX-06: Lỗi enrich và cascade được cô lập

Given	When	Then
Một load enrich của một document lỗi, hoặc một fan-out cascade lỗi	Lô được xử lý	Document vẫn được index với dữ liệu trên nó, các cascade khác vẫn áp, và lô không bị báo lỗi toàn bộ

SCH - Unified Search Query API Built

Feature ID: platform/SCH · Phase: P2 · PRDs: PRD-IDX-001 · Dev: @nx/search

Làm gì cho người dùng: một cách nhất quán để bất kỳ app nào full-text search bất kỳ collection nào - theo tên, barcode, option facet, và hơn nữa - với cùng filter, phân trang, và hợp đồng phản hồi như mọi list endpoint khác, keyword hoặc semantic, và tự động giới hạn theo những gì caller được thấy.

Yêu cầu

ID	P	Yêu cầu
URD-SCH-001	M	Một caller có thể full-text search bất kỳ collection đã đăng ký nào theo tên với một query term và một filter kiểu Ignis (where / limit / skip / order / include / fields), trả về theo hình bao-hoặc-mảng của list endpoint nền tảng kèm range header.
URD-SCH-002	M	Một caller có thể yêu cầu một số đếm kết quả khớp cho một collection dưới cùng query và where.
URD-SCH-003	M	Search hỗ trợ khớp hybrid keyword + semantic (vector); endpoint chung chạy hybrid mặc định trong khi search gắn-theo-tài-nguyên mặc định keyword-only và cho caller opt-in.
URD-SCH-004	M	Một resource controller có thể gắn /search + /search/count có-giới-hạn riêng của nó tự động merge một caller-scope (ví dụ tenant) vào query, để một user chỉ search trong những gì họ được thấy.
URD-SCH-005	M	Một caller có thể chọn trường nào để text-search (queryBy); nếu không thì các trường search mặc định của collection áp dụng.
URD-SCH-006	M	Search và count được xác thực (JWT / Basic) và gated bằng permission.
URD-SCH-007	S	Truy vấn một collection chưa được tạo trả về một kết quả rỗng thay vì lỗi; một query không hợp lệ được báo là bad request.

Chấp nhận

AC-SCH-01: Search trả về hợp đồng list chuẩn

Given	When	Then
Một collection có dữ liệu	Một caller search nó theo tên với một filter	Các kết quả khớp trả về theo hình bao-hoặc-mảng kèm range header, phân trang theo limit / skip của filter

AC-SCH-02: Count trả lời dưới cùng query

Given	When	Then
Một collection có dữ liệu	Một caller đếm nó với một query và where	Số lượng document khớp được trả về

AC-SCH-03: Search gắn-theo-tài-nguyên giới-hạn-tenant

Given	When	Then
Một resource controller gắn search có-giới-hạn của nó	Một user đã đăng nhập search tài nguyên đó	Caller-scope của họ được merge vào query và chỉ bản ghi trong scope của họ được trả về

AC-SCH-04: Collection thiếu trả về rỗng, query xấu báo lỗi

Given	When	Then
Một collection chưa được tạo, rồi một query không hợp lệ	Mỗi cái được search	Collection thiếu trả về một kết quả rỗng; query không hợp lệ được báo là bad request

Ràng buộc & Không-mục-tiêu

ID	Ràng buộc / Không-mục-tiêu
URD-CON-001	Năng lực này chỉ cung cấp kênh real-time trong ứng dụng - fan-out email / SMS / push-notification ngoài phạm vi.
URD-CON-002	Không có mô hình tùy chọn, tắt, hoặc đăng ký thông báo theo từng user; việc gửi được điều khiển bởi phạm vi của hoạt động.
URD-CON-003	Ủy quyền room trên transport hiện đang dễ dãi (client xác thực bất kỳ có thể đăng ký một room); tăng cường chống xuyên-tenant là một follow-up đã biết. Room admin / global collection không được emit tới.
URD-CON-004	Phát activity event là trách nhiệm của service tạo sự kiện; nền tảng tiêu thụ các sự kiện đúng định dạng.
URD-CON-005	Ủy quyền chi tiết theo-từng-action trên API CRUD meta-link hiện đang dễ dãi; siết nó về tập permission meta-link là một follow-up đã biết.
URD-CON-006	Lưu trữ được hậu thuẫn bởi một bucket cấu hình duy nhất cho mỗi service chủ; cô lập bucket theo-từng-merchant / theo-từng-tenant ngoài phạm vi.
URD-CON-007	Registry ngân hàng là dữ liệu tham chiếu chỉ-đọc đóng gói cùng service; không có bề mặt tác giả hoặc sửa.
URD-CON-008	Phát change-data event là trách nhiệm của hạ tầng CDC (Debezium) của nền tảng; search tiêu thụ các sự kiện topic nx.bana.cdc.<schema>.<Table> đúng định dạng và không sở hữu việc capture.
URD-CON-009	SaleOrder là một bảng nguồn CDC đã định nghĩa nhưng chưa được index vào một search collection; nó được dành cho một increment sau.
URD-CON-010	Re-index / backfill là một snapshot replay vận hành; không có UI re-index cho người dùng cuối.
URD-CON-011	Giới hạn xuyên-tenant trên search query dựa vào controller gắn cung cấp caller-scope; endpoint search chung thô được gated bằng permission collection, không bằng scope tenant theo-từng-bản-ghi.

Lịch sử phiên bản

Version	Date	Thay đổi
v1.0	2026-06-15	URD ban đầu - ACT activity notifications và WSS realtime WebSocket stream, cả hai Built. Hậu thuẫn PRD-ACT-001.
v1.1	2026-06-15	Thêm backbone media - AST asset & object storage, MTL meta-link binding, và BNK dữ liệu tham chiếu ngân hàng Việt Nam, đều Built. Hậu thuẫn PRD-AST-001.
v1.2	2026-06-15	Thêm backbone search - IDX search indexing & CDC sync và SCH unified search query API, cả hai Built. Hậu thuẫn PRD-IDX-001.

Trang liên quan

• Tổng quan Nền tảng - định danh module + traceability
• PRDs - PRD-ACT-001 · PRD-AST-001 · PRD-IDX-001
• Liên quan: Device signal & notifications - chạy trên backbone này
• Developer: @nx/signal · @nx/asset · @nx/search · @nx/core