PRD: Activity notifications & realtime push
| Module | Nền tảng (CORE-16) | PRD ID | PRD-ACT-001 |
| Status | Shipped | Owner | Phát Nguyễn |
| Date | 2026-06-15 | Version | v1.0 |
| Năng lực | Thông báo · gửi real-time | URD | ACT · WSS |
TL;DR
Một hoạt động nghiệp vụ đáng chú ý lập tức trở thành thông báo gửi đến đúng người: nền tảng phát một hoạt động tới đúng đối tượng - cả một organizer, cả một merchant, hay một danh sách user cụ thể - lưu một bản ghi cho mỗi người nhận và đẩy từng thông báo qua kênh real-time đã xác thực, mã hóa đầu cuối. Mỗi user chỉ đọc và xóa thông báo của riêng mình; kênh có rớt thì bản ghi vẫn còn nên không mất gì, và người vận hành có một bộ điều khiển tinh gọn để theo dõi và điều phối các kết nối đang mở.
1. Bối cảnh & Vấn đề
BANA liên tục tạo ra những khoảnh khắc đáng chú ý - một thanh toán hoàn tất, một đơn hàng xong - nhưng mỗi sự kiện đều mắc kẹt trong service đã sinh ra nó. Chưa có cách nào ở tầm nền tảng biến một hoạt động thành thông báo bền vững theo từng người rồi đưa lên màn hình ngay lúc nó xảy ra; nhân viên phải refresh và truy vấn lại mới biết có gì thay đổi.
Cái còn thiếu là một backbone tách việc sinh ra hoạt động khỏi việc gửi nó đi: một seam sự kiện mà service nào cũng phát lên được, một worker phân phát một hoạt động tới đúng người nhận trong đúng phạm vi tenant, một bản ghi bền vững sống sót qua sự cố mất kết nối, và một transport live đẩy mỗi thông báo tới đúng chủ của nó - và chỉ chủ của nó.
Increment này đưa backbone đó thành một năng lực nền tảng hạng nhất: pipeline activity-notification (ACT) và luồng real-time (WSS) nó chạy trên đó, cùng một read API giới hạn theo từng người dùng và một hợp đồng gửi đã mã hóa, ổn định.
2. Mục tiêu & Ngoài mục tiêu
Mục tiêu
- Một pipeline hướng sự kiện: nhận một hoạt động → phân giải người nhận → render nội dung → lưu một bản ghi cho mỗi người → đẩy live.
- Phân giải người nhận theo phạm vi - phát một hoạt động tới một organizer, một merchant, hay một danh sách user, quay về actor khi không có đối tượng nào.
- Một read API riêng theo từng người dùng bền vững - mỗi user chỉ liệt kê, đếm (kể cả chưa đọc) và đánh dấu đã đọc một hoặc tất cả thông báo của riêng mình.
- Một push live, được xác thực và mã hóa đầu cuối tới kênh riêng của từng người nhận, theo hợp đồng kênh/topic cố định.
- Khả năng phục hồi - lưu trữ luôn thành công; kênh thiếu hoặc lỗi không bao giờ làm hỏng pipeline hay chặn người nhận khác.
- Điều khiển kết nối cho quản trị tinh gọn - trạng thái, liệt kê client, gửi đích danh, broadcast, ngắt kết nối - nằm sau lớp permission.
Ngoài mục tiêu
- Kênh email / SMS / push-notification - increment này chỉ làm kênh real-time trong ứng dụng.
- Mô hình tùy chọn / tắt / đăng ký thông báo theo từng user.
- Logic của chính các producer - phát hoạt động là việc của producer; năng lực này tiêu thụ nó.
- Siết ủy quyền kênh để chống truy cập chéo tenant trên transport (follow-up đã biết, xem §11).
- Thiết kế giao diện chuông / activity-feed - PRD này đặc tả API và hợp đồng gửi để client render.
3. Chỉ số thành công
| Chỉ số | Mục tiêu / tín hiệu |
|---|---|
| Độ trễ gửi | Activity event → push live tới recipient gần như tức thời (dưới một giây ở tải bình thường) |
| Độ chính xác recipient | Một thông báo đến đúng các user trong phạm vi của hoạt động; không rò rỉ chéo tenant |
| Độ bền | Mỗi recipient có một bản ghi được lưu kể cả khi kết nối của họ đứt; read-state vẫn còn sau khi kết nối lại |
| Giới hạn theo người dùng | Một user chỉ có thể đọc hoặc thay đổi thông báo của chính mình |
| Khả năng phục hồi | Một sự cố real-time hoặc một push lỗi đơn lẻ tụt xuống chế độ chỉ lưu, không gây lỗi pipeline nào |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Chủ / Quản lý | Thấy hoạt động của organizer hoặc merchant hiện live, không cần refresh |
| Nhân viên / Thu ngân | Nhận các thông báo gửi tới mình và xóa chúng khi đã đọc |
| Client kết nối (web / POS) | Giữ một kết nối live và phản ánh thông báo mới + read-state tức thì |
| Người vận hành nền tảng | Kiểm tra các kết nối live và điều phối hoặc cắt một phiên khi cần |
Kịch bản cốt lõi: một thanh toán thành công, service thanh toán phát một hoạt động thanh toán thành công kèm actor và đơn hàng. Worker phân giải người nhận cho phạm vi đó, render một thông điệp dễ đọc, và ghi mỗi người một thông báo. Người nhận đang giữ kết nối live thấy nó hiện tức thì trên kênh riêng; người đang offline thấy nó chờ sẵn ở lần tải sau. Người dùng có thể đánh dấu đã đọc - hoặc xóa tất cả một lần - và read-state giữ nguyên qua các phiên.
5. User Stories
- Là một chủ, tôi muốn hoạt động xuất hiện ngay khi nó xảy ra, để tôi theo dõi việc kinh doanh mà không refresh.
- Là nhân viên, tôi chỉ muốn các thông báo gửi cho tôi, để feed của tôi luôn liên quan và không bao giờ hiện hoạt động của người khác.
- Là một client kết nối, tôi muốn nhận thông báo qua một kênh live đã mã hóa, để cập nhật tức thì và riêng tư khi truyền.
- Là một user, tôi muốn đếm thông báo chưa đọc và đánh dấu đã đọc - một hoặc tất cả, để feed phản ánh những gì tôi đã thấy.
- Là nền tảng, tôi muốn một thông báo sống sót qua một kết nối bị rớt, để một user offline không bao giờ bỏ lỡ nó.
- Là một người vận hành, tôi muốn thấy và điều phối các kết nối live, để chẩn đoán hoặc cắt một phiên.
6. Yêu cầu chức năng
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Một activity event trên luồng nền tảng được tiêu thụ và biến thành một thông báo cho mỗi recipient được phân giải | URD-ACT-001 |
| FR-2 | Recipient được phân giải theo phạm vi - cả organizer, cả merchant, hoặc một danh sách user cụ thể - quay về actor khi không có ai | URD-ACT-002 |
| FR-3 | Mỗi thông báo lưu recipient, type, organizer, nội dung văn bản thuần + văn bản định dạng đã render, một liên kết hành động tùy chọn, dữ liệu có cấu trúc (kể cả actor), và một cờ đọc kèm timestamp | URD-ACT-003 |
| FR-4 | Nội dung được render từ event type thành một thông điệp dễ đọc (một chuỗi văn bản thuần + văn bản định dạng đã render cho mỗi thông báo, giống nhau cho mọi recipient); chỉ các event type được nhận diện mới tạo thông báo, type lạ bị bỏ qua không lỗi. Hiện tại type live duy nhất render một chuỗi tiếng Việt cố định - bản địa hóa theo ngôn ngữ từng user chưa được hiện thực | URD-ACT-004 · URD-ACT-005 |
| FR-5 | Một user đã đăng nhập liệt kê thông báo của riêng mình (phân trang / lọc) kèm tổng số và số chưa đọc | URD-ACT-006 |
| FR-6 | Một user có thể đếm thông báo của mình (ví dụ chưa đọc) và đánh dấu đã đọc một hoặc tất cả, mỗi cái mang một timestamp đọc | URD-ACT-007 · URD-ACT-008 |
| FR-7 | Mọi thao tác đọc và ghi đề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 người khác | URD-ACT-009 |
| FR-8 | Khi tạo, mỗi thông báo được đẩy live tới kênh riêng của recipient qua transport real-time | URD-WSS-001 |
| FR-9 | Client kết nối qua một kênh đã xác thực và hoàn tất một handshake trao đổi khóa mã hóa; payload sau handshake được mã hóa đầu cuối | URD-WSS-002 |
| FR-10 | Việc gửi dùng một hợp đồng kênh/topic cố định và fan-out giữa các instance; kênh thiếu hoặc một push lỗi sẽ tụt xuống chế độ chỉ lưu mà không chặn các recipient khác | URD-WSS-003 · URD-WSS-004 · URD-WSS-005 |
| FR-11 | Các điều khiển kết nối cho quản trị - trạng thái, list client, get client, broadcast, send-to-channel, send-to-client, disconnect - có sẵn sau lớp permission | URD-WSS-006 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong Platform URD - ACT và WSS. PRD này tham chiếu chúng thay vì lặp lại.
7. Yêu cầu phi chức năng
| Lĩnh vực | Yêu cầu |
|---|---|
| Tenancy & cô lập | Phân giải recipient giới hạn theo organizer / merchant; read API của user giới hạn trong chính tài khoản của họ - không rò rỉ chéo tenant hay chéo user |
| Độ bền | Mỗi push đều dựa trên một bản ghi đã lưu; read-state truy được sau khi kết nối lại |
| Tách rời & quy mô | Seam sự kiện tách producer khỏi fan-out; một worker hấp thụ các đợt bùng tải mà không chặn producer |
| Khả năng phục hồi | Lưu trữ độc lập với kênh real-time; push tới từng recipient được xử lý độc lập nên một lỗi không bao giờ chặn phần còn lại |
| Bảo mật | Kênh live được xác thực và mã hóa đầu cuối sau một handshake trao đổi khóa mã hóa |
| Hợp đồng đăng ký ổn định | Một kênh riêng cố định cho từng recipient và một topic thông báo cố định, để client đăng ký theo một hợp đồng ổn định |
| Gửi liên instance | Một fan-out liên instance gửi tới một recipient bất kể kết nối của họ được thiết lập ở đâu |
| i18n | Bản ghi thông báo lưu một chuỗi văn bản thuần + văn bản định dạng đã render; seam nội dung được điều khiển theo event type nên về sau một renderer có thể bản địa hóa, nhưng type live duy nhất hiện phát ra một chuỗi tiếng Việt cố định chứ không phải nội dung theo ngôn ngữ từng recipient |
8. UX & Luồng
Client giữ một kết nối đã xác thực, đã mã hóa và đăng ký kênh riêng của mình; trên topic thông báo, chuông hoạt động được thiết kế để hiện mỗi thông báo mới. Người nhận offline thấy nó chờ sẵn qua read API ở lần tải sau, và việc đánh dấu một - hoặc tất cả - là đã đọc giúp số chưa đọc nhất quán qua các phiên.
Trạng thái phía client: pipeline backend, read API và hợp đồng gửi real-time đều đã chạy, nhưng chuông thông báo trong ứng dụng ở footer client hiện đang tắt - chưa hiển thị cho user merchant. Thành phần này đã có sẵn (một chuông ở góc footer bên trái, mở ra notification sheet) nhưng được ship ở trạng thái tắt, nên người dùng cuối hôm nay chưa thấy thông báo trong ứng dụng; surface dành cho merchant là một follow-up sẽ dùng lại backbone đã ship sẵn này.
9. Dữ liệu & Miền
| Thực thể | Vai trò |
|---|---|
| Bản ghi thông báo | Bản ghi theo từng recipient được lưu - recipient, type, organizer, nội dung (văn bản thuần + định dạng), liên kết hành động, dữ liệu có cấu trúc, cờ đọc + timestamp |
| Activity event | Thông điệp đầu vào trên luồng hoạt động - event type, recipient scope, actor, organizer / merchant, recipient cụ thể tùy chọn, payload |
| Phân giải recipient | Tra cứu các user trong phạm vi organizer hoặc merchant của hoạt động; danh sách chỉ định cụ thể và fallback về actor đều được tôn trọng |
| Kênh + topic theo từng recipient | Kênh real-time riêng của recipient và topic notification-created - hợp đồng gửi live |
Chỉ mang tính khái niệm - schema và bất biến đầy đủ nằm trong developer domain model.
10. Phụ thuộc & Giả định
Phụ thuộc vào
- Lõi nền tảng - sở hữu định nghĩa bản ghi thông báo, registry event-type được nhận diện, topic + hợp đồng thông điệp của luồng hoạt động, và việc phân giải recipient từ dữ liệu membership.
- Luồng sự kiện hoạt động - seam ingest giữa producer hoạt động và notification worker.
- Transport real-time + fan-out liên instance - kênh gửi live được xác thực, mã hóa và chạy liên instance.
- Các service tạo sự kiện - phát activity event (ví dụ luồng thanh toán phát một hoạt động thanh toán thành công).
Giả định
- Producer phát các activity event đúng định dạng lên topic luồng đã thỏa thuận.
- Dữ liệu membership organizer / merchant có sẵn cho việc phân giải recipient.
- Client duy trì một kết nối live và đăng ký kênh riêng của từng recipient.
11. Rủi ro & Câu hỏi mở
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Một recipient đang offline khi hoạt động phát | Bản ghi vẫn được lưu bất kể; client đọc lại nó qua read API giới hạn theo người dùng ở lần tải tiếp theo |
| Kênh real-time không khả dụng hoặc một push lỗi | Pipeline tụt xuống chế độ chỉ lưu; push tới từng recipient được xử lý độc lập nên một lỗi không bao giờ chặn các push khác |
| Rò rỉ chéo user trong read API | Mọi thao tác đọc / ghi giới hạn theo user đã xác thực - một user không thể chạm tới thông báo của người khác |
| Đăng ký kênh chéo tenant trên transport | Follow-up tăng cường đã biết - ủy quyền kênh hiện còn dễ dãi; kênh admin / global không được phát tới |
| Trôi tên kênh / topic giữa producer và client | Cố định một kênh riêng cho từng recipient và một topic thông báo cố định, xem như một hợp đồng ổn định |
| Hiện chỉ có một event type live (một thanh toán thành công) | Pipeline được điều khiển theo type và tái dùng được; event type mới chỉ cần thêm một renderer mà không phải làm lại backbone |
| Surface client trong ứng dụng chưa live | Chuông thông báo ở footer được ship ở trạng thái tắt - backbone (gửi, lưu trữ, read API) đã ship, nhưng user merchant chưa thấy thông báo trong ứng dụng cho tới khi surface client được bật ở một follow-up |
12. Kế hoạch phát hành & Tiêu chí ra mắt
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 - ACT và WSS trong URD feature catalog |
| Triển khai | Tất cả merchant; không feature flag |
| Di trú | Kho bản ghi thông báo mới; không cần di trú dữ liệu |
| Tiêu chí ra mắt | Activity event → phân giải recipient → bản ghi đã lưu → push live được kiểm chứng end-to-end; list / count / mark-read / mark-all-read giới hạn theo người dùng hoạt động đúng; một sự cố real-time tụt xuống chế độ chỉ lưu; điều khiển kết nối quản trị được permission bảo vệ |
| Giám sát | Lượng thông báo, độ trễ gửi, sức khỏe kết nối live, độ đúng của việc phân giải recipient, tỷ lệ push lỗi |
13. FAQ
Đối tượng của một thông báo được chọn thế nào? Theo phạm vi người nhận của hoạt động - cả organizer, cả merchant, hay một danh sách user cụ thể. Nếu không phân giải ra ai, actor của hoạt động sẽ nhận nó.
Người nhận offline thì sao? Thông báo vẫn được lưu; client đọc lại nó qua read API giới hạn theo người dùng ở lần tải sau, và read-state giữ nguyên qua các phiên.
Kênh live có an toàn không? Có - client xác thực lúc kết nối và hoàn tất một lần trao đổi khóa mã hóa; mọi payload sau handshake đều mã hóa đầu cuối.
Một user có thấy thông báo của người khác không? Không - mọi thao tác list, count, mark-read đều giới hạn theo user đã xác thực.
Push real-time lỗi thì sao? Việc gửi tụt xuống chế độ chỉ lưu - bản ghi đã ghi rồi, và lỗi của một người nhận không bao giờ chặn người khác.
Hiện chỉ có thanh toán? Pipeline được điều khiển theo event type. Một thanh toán thành công là type live đầu tiên; loại mới chỉ cần cắm thêm một content renderer và tái dùng toàn bộ backbone.
Tham khảo
- URD: Platform - ACT · WSS
- PRD liên quan: Device signal & notifications - increment giám sát thiết bị chạy trên cùng backbone này
- Module: Nền tảng - URD
- Developer: @nx/signal · @nx/core