PRD: Tín hiệu & thông báo thiết bị

Module	Thiết bị	PRD ID	PRD-MON-001
Trạng thái	Sẵn sàng dev	FEAT	MON
Epic	—	Plane	BANA-1540
Ngày	2026-07-17	Phiên bản	v0.2
Gói	@nx/commerce · @nx/signal	URD	MON
Surface	Backend
Phụ trách	Phát Nguyễn

Một nền tảng thông báo thời gian thực phía server

Một nền tảng activity-notification phía server: worker xác định đúng người nhận trong scope organizer/merchant, lưu một notification, rồi đẩy trực tiếp tới các client đang kết nối - kèm giao diện lấy / đánh dấu đã đọc đứng sau UI chuông. Hai lưu ý hiện tại: consumer thu nhận đã có nhưng chưa có producer nào nạp vào, nên pipeline chưa chạy trọn vẹn đầu-cuối; và use case trực tiếp duy nhất tới giờ (inquiry-submitted) chạy qua một WebSocket outreach riêng, bỏ qua pipeline và không lưu gì.

Vấn đề mà gia tăng này giải quyết

Giám sát Tình trạng & Thông báo Thiết bị (MON) cần nền tảng ghi nhận hoạt động và hiển thị cho quản trị viên gần như tức thời. Hiện chưa có nền tảng thông báo phía server: sự kiện diễn ra khắp nền tảng nhưng không có gì phát chúng tới đúng người dùng hay đẩy lên giao diện trực tiếp, nên quản trị viên không thể theo dõi hoạt động ngay khi nó xảy ra.

Gia tăng này xây nền tảng đó trong lớp tín hiệu thời gian thực - một pipeline trọn vẹn (thu nhận sự kiện → worker → bản ghi được lưu → đẩy trực tiếp) cùng việc xác định người nhận theo scope organizer/merchant và một transport thời gian thực ổn định. Việc giám sát và hiển thị hoạt động dựa trên transport đó; phần báo cáo heartbeat / tình trạng (URD-MON-001/002) và các thao tác thiết bị từ xa (URD-MON-004/005) được theo dõi riêng. Đây cũng là kênh mà cảnh báo hư hỏng thiết bị của PRD-DEV-001 sẽ đi qua một khi có producer đầu tiên.

1. Mục tiêu & Ngoài mục tiêu

Mục tiêu

• Một pipeline activity-notification chạy bằng sự kiện: thu nhận → worker → bản ghi được lưu → đẩy trực tiếp.
• Xác định người nhận - thông báo phát tới đúng người dùng trong scope organizer/merchant.
• Một transport thời gian thực ổn định (room + topic + dịch vụ phát) với cách đặt tên kênh cố định, để client đăng ký theo một hợp đồng ổn định.
• Trạng thái đã đọc của notification: một giao diện để lấy notification và đánh dấu đã đọc.
• Một use case trọn vẹn đầu tiên: thông báo trực tiếp inquiry-submitted từ miền outreach.

Ngoài mục tiêu

• Phát heartbeat và ngưỡng offline 15 phút (URD-MON-001/002).
• Hủy kích hoạt từ xa / xóa dữ liệu từ xa (URD-MON-004/005).
• Giao diện dashboard tình trạng theo từng thiết bị (bề mặt client tiêu thụ).
• Tách bộ công cụ notification khỏi lớp tín hiệu sang một package dùng chung.

2. Chỉ số Thành công

Chỉ số	Mục tiêu / tín hiệu
Độ trễ phát	Sự kiện hoạt động → đẩy trực tiếp tới client gần như tức thời (dưới một giây ở tải thông thường)
Độ chính xác người nhận	Thông báo tới đúng người dùng trong scope organizer/merchant; không rò rỉ chéo tenant
Độ bền	Mọi notification đã phát đều có bản ghi được lưu; trạng thái đã đọc sống sót qua kết nối lại
Phạm vi	Ping trực tiếp inquiry-submitted đã kiểm chứng (qua WS outreach riêng, không qua pipeline); pipeline chờ producer đầu tiên trước khi tái dùng được trọn vẹn

3. Đối tượng & Tình huống sử dụng

Đối tượng	Mục tiêu trong tính năng này
Quản trị viên / Chủ sở hữu	Thấy hoạt động nền tảng & thiết bị trực tiếp, không cần polling
Client đang kết nối (web/app)	Nhận thông báo qua kết nối trực tiếp và phản ánh trạng thái đã đọc
Người xử lý outreach	Được báo ngay khi có inquiry được gửi

Luồng cốt lõi: một sự kiện hoạt động đến pipeline → worker xác định người nhận trong scope organizer/merchant và lưu một notification → bản ghi được đẩy trực tiếp tới các client đang kết nối → client lấy notification của mình và đánh dấu đã đọc. Việc gửi inquiry phát một thông báo trực tiếp qua cùng transport này.

4. Câu chuyện Người dùng

• Là quản trị viên, tôi muốn hoạt động hiện trên giao diện ngay khi xảy ra, để giám sát nền tảng mà không cần làm mới.
• Là client đang kết nối, tôi muốn nhận thông báo qua kết nối trực tiếp, để thấy cập nhật ngay khoảnh khắc nó xảy ra.
• Là client đang kết nối, tôi muốn lấy notification của mình và đánh dấu đã đọc, để trạng thái đã đọc nhất quán qua các phiên.
• Là người xử lý outreach, tôi muốn có thông báo trực tiếp khi một inquiry được gửi, để phản hồi kịp thời.
• Là nền tảng, tôi muốn thông báo chỉ phát tới người dùng trong đúng scope organizer/merchant, để không tenant nào thấy hoạt động của tenant khác.

5. Yêu cầu Chức năng

#	Yêu cầu	Trạng thái	Tham chiếu URD
FR-1	Các sự kiện hoạt động đến được thu nhận vào pipeline notification	Một phần - consumer thu nhận + worker đã có, nhưng chưa có producer nào publish vào topic, nên pipeline chưa chạy trọn vẹn đầu-cuối	URD-MON-003
FR-2	Một worker xác định người nhận trong scope organizer/merchant	Đã dựng	URD-MON-003
FR-3	Mỗi notification được lưu thành một bản ghi notification	Đã dựng	URD-MON-003
FR-4	Một transport thời gian thực (room + topic + dịch vụ phát) đẩy notification tới các client đang kết nối trực tiếp, trên một kênh thông báo cố định	Đã dựng - WS mã hóa, room/topic cố định. Lưu ý: phân quyền đăng ký room đang là stub (mọi user đã xác thực đều đăng ký được mọi room)	URD-MON-003
FR-5	Một giao diện lấy notification của một người dùng và đánh dấu đã đọc	Đã dựng	URD-MON-003
FR-6	Việc gửi inquiry phát một thông báo trực tiếp tới các client quan tâm	Đã dựng, nhưng qua một WS outreach riêng (fire-and-forget) - không đi qua pipeline và không lưu bản ghi notification	URD-MON-003

Toàn văn yêu cầu và tiêu chí nghiệm thu nằm trong URD Thiết bị. PRD này tham chiếu chúng thay vì lặp lại.

6. Yêu cầu Phi Chức năng

Lĩnh vực	Yêu cầu
Tenancy & authz	Việc xác định người nhận theo scope organizer/merchant; thông báo không bao giờ vượt ranh giới tenant
Độ bền	Mọi lần đẩy trực tiếp đều có một bản ghi notification được lưu bảo chứng; trạng thái đã đọc lấy lại được sau khi kết nối lại
Performance / scale	Luồng sự kiện tách việc thu nhận khỏi việc phát; worker hấp thụ các đợt dồn dập mà không chặn producer
Độ ổn định transport	Tên kênh cố định, để client đăng ký theo một hợp đồng ổn định
i18n	Nhãn notification hiển thị cho người dùng song ngữ (Anh & Việt) khi xuất hiện

7. UX & Luồng

Các bề mặt chính: nền tảng notification nằm trong lớp tín hiệu thời gian thực (consumer thu nhận, worker, dịch vụ phát, rooms, topics) với giao diện đọc / đánh-dấu-đã-đọc; đường đi inquiry nằm trong miền outreach. Giao diện dashboard tiêu thụ nằm ngoài phạm vi gia tăng này.

8. Dữ liệu & Miền

Thực thể	Vai trò
Bản ghi notification	Notification được lưu (người nhận, payload, trạng thái đã đọc)
Nền tảng notification	Consumer thu nhận, worker, dịch vụ phát, rooms, topics trong lớp tín hiệu
Kênh notification	Room/topic cố định - kênh phát trực tiếp
Xác định người nhận	Tra cứu các user ID trong một organizer/merchant

Chỉ ở mức khái niệm - schema đầy đủ nằm trong developer domain model.

9. Phụ thuộc & Giả định

Phụ thuộc vào

• Nền tảng lõi - sở hữu bản ghi notification, event topic + types, và việc xác định người nhận qua tra cứu thành viên/phân quyền.
• Luồng sự kiện - đường nối thu nhận giữa các nguồn hoạt động và notification worker.
• Transport thời gian thực - kênh phát trực tiếp tới các client đang kết nối.
• Miền outreach - producer sự kiện đầu tiên (gửi inquiry).

Giả định

• Các nguồn hoạt động đẩy sự kiện lên event topic đã thống nhất.
• Dữ liệu thành viên organizer/merchant sẵn sàng cho việc xác định người nhận.
• Client duy trì một kết nối trực tiếp và đăng ký kênh notification.

10. Kế hoạch Phát hành & Tiêu chí Ra mắt

Khía cạnh	Kế hoạch
Phase	P2 (MON là một tính năng P2, Một phần)
Rollout	Tất cả merchant; không feature flag
Migration	Bản ghi notification mới; không cần migration dữ liệu
Launch criteria	(Còn chờ) sự kiện hoạt động → xác định người nhận → bản ghi được lưu → đẩy trực tiếp được kiểm chứng trọn vẹn - bị chặn cho tới khi có producer nạp vào topic thu nhận (một producer thật đầu tiên có thể tới từ cảnh báo hư hỏng thiết bị của PRD-DEV-001). (Đạt) ping trực tiếp inquiry-submitted (WS outreach riêng); lấy / đánh dấu đã đọc; trạng thái đã đọc sống sót qua kết nối lại
Monitoring	Lượng notification, độ trễ phát, tình trạng kết nối trực tiếp, độ đúng của việc xác định người nhận

Tham chiếu

• URD: Thiết bị - Giám sát Tình trạng & Thông báo Thiết bị - yêu cầu (mảng MON)
• PRD liên quan: Đăng ký, định danh, kích hoạt & thiết bị ngoại vi
• Module: Thiết bị - URD
• Developer: @nx/signal · @nx/outreach · @nx/core

Rủi ro & Câu hỏi mở

Rủi ro / câu hỏi	Giảm thiểu / trạng thái
Việc xác định người nhận có thể rò rỉ chéo tenant	Xác định theo scope organizer/merchant và kiểm chứng dựa trên tra cứu thành viên. Còn mở: phân quyền đăng ký room đang là stub - hiện mọi user đã xác thực đều đăng ký được room của bất kỳ người nhận nào
Mất kết nối trực tiếp có thể làm rơi thông báo	Mọi lần phát đều có một bản ghi được lưu bảo chứng; client lấy lại trạng thái đã đọc khi kết nối lại
Tên kênh lệch nhau giữa producer và client	Tên được cố định như một hợp đồng ổn định
Bộ công cụ notification nằm trong lớp tín hiệu, chưa dùng chung	Chấp nhận cho gia tăng này; tách sang package dùng chung là cân nhắc tương lai
Heartbeat/tình trạng của MON vẫn còn chờ	Ngoài phạm vi tại đây; gia tăng này chỉ giao transport (xem §1)

Câu hỏi thường gặp

Câu hỏi	Trả lời
Cái này có giao heartbeat / tình trạng thiết bị không?	Không - nó giao kênh truyền thông báo thời gian thực mà việc giám sát dựa vào. Phát heartbeat và ngưỡng offline (URD-MON-001/002) được theo dõi riêng.
Người nhận được chọn thế nào?	Worker xác định người dùng trong scope organizer/merchant liên quan; thông báo không bao giờ vượt ranh giới tenant.
Nếu một client mất kết nối khi sự kiện xảy ra thì sao?	Notification vẫn được lưu; client lấy lại notification và trạng thái đã đọc khi kết nối lại.
Client đăng ký kênh nào?	Một kênh thông báo cố định - một hợp đồng ổn định.
Vì sao đường đi inquiry-submitted nằm ở đây?	Đây là use case thời gian thực đầu tiên chứng minh việc phát trực tiếp. Lưu ý nó chạy qua một WebSocket outreach riêng (fire-and-forget) - không đi qua pipeline activity và không lưu bản ghi notification, nên không kiểm chứng pipeline trọn vẹn đầu-cuối.