# Hai ứng dụng và phạm vi tính năng SSA

**Sản phẩm gồm hai UI: Web Admin cho nhân sự SSA và Zalo Mini App cho phụ huynh.** Hai UI dùng chung backend nghiệp vụ và dữ liệu đã phân quyền, nhưng đăng nhập, quyền thao tác và phạm vi dữ liệu riêng. Bốn mục Tổng quan / Kiến trúc / Sơ đồ / Vận hành là website tài liệu, không phải bốn ứng dụng.

Bản đối chiếu cập nhật ngày 12/11/2026. [Kiến trúc toàn cảnh](archify/overview.html) / [Phạm vi module](archify/modules.html) / [Đặc tả và tiêu chí FR](index.html#chapter-3).

## 1. Phân biệt mock và phạm vi phải triển khai

| Trạng thái | Ý nghĩa |
|---|---|
| Có trong mock | Có giao diện hoặc tương tác trong HTML được cung cấp; chưa chứng minh backend thật |
| Có mã, chưa hoạt động đầy đủ | Có nhánh giao diện/handler nhưng bị bỏ qua, thiếu cấu hình hoặc dùng stub |
| Phải xây theo kế hoạch | Có trong PLAN nhưng chưa có màn hình trong mock này |
| Cần chốt | Không được coi mock là quyết định sản phẩm đã duyệt |

Nguồn mock: `SSA Phụ Huynh Mobile (Copy).html`, 311475 bytes; SHA-256 `810d72984a2ac551600fb4832842781d183dc44a1f7d4e036e584aeb9dc44087`, trùng L03 trong [manifest](input-manifest.json). Đã đọc source và chạy bốn tab, kiểm tra chọn biến thể, validation size, tạo đơn mẫu và reload; kết quả ở [mock-review.json](mock-review.json). Mạng ngoài bị chặn khi kiểm tra; không xác nhận SDK Zalo hay nhà cung cấp hoạt động thật. Tên, giá và số liệu trong mock là dữ liệu minh họa.

## 2. Tính năng Mini App

Bốn tab giữ theo mock: **Trang chủ / Kết quả / Cửa hàng / Thông báo**. Một phụ huynh có thể chọn nhiều con đã được SSA xác minh; mọi truy vấn và hành động đều phải kiểm quyền lại ở backend.

| ID / màn hình | Tính năng thấy trong mock | Khi triển khai thật |
|---|---|---|
| MP-01: Truy cập | Có mã chào, giải thích chia sẻ số điện thoại, loading, chưa tìm thấy hồ sơ, lỗi và thử lại; demo tự vào app | Xác minh token Zalo tại backend, tra liên kết verified, tạo/thu hồi session. Số điện thoại không tự cấp quyền giám hộ; có hướng dẫn hỗ trợ nếu không khớp |
| MP-02: Chọn con | Chuyển con ở Trang chủ và Kết quả; chọn trẻ khi đăng ký sản phẩm | Không lẫn dữ liệu giữa trẻ; một trẻ nhiều người giám hộ; quyền revoked có hiệu lực với cả request và file |
| MP-03: Hồ sơ tóm tắt | Họ tên, lớp, Coach, lịch học, cụm sân | Hiển thị dữ liệu đã duyệt theo nguồn và thời điểm; không tự cho phụ huynh sửa nguồn MISA |
| MP-04: Gói học | Số buổi còn lại/tổng buổi, thanh tiến độ; cảnh báo khi còn ≤3 buổi, hạn gói trong cảnh báo | Ngưỡng ≤3 là hành vi mock, cần SSA chốt. Null khác 0; không tự tính lại số dư từ attendance nếu chưa chốt quy tắc bảo lưu/học bù |
| MP-05: Chuyên cần | Tổng có mặt/tháng; 5 buổi gần đây, ngày/giờ, Có mặt/Vắng/Có phép | Giữ đúng grain trẻ/buổi, xử lý hủy/học bù và sửa nguồn có lịch sử; chưa có lịch đầy đủ hay chức năng tự xin nghỉ trong mock |
| MP-06: Trang chủ | Mở phiếu mới nhất; 3 thông báo gần đây theo trẻ hoặc thông báo chung; thời điểm cập nhật và Tải lại | API trả freshness/generation, loading/error/empty/stale rõ; reload không làm mất dữ liệu đã lưu |
| MP-07: Kết quả theo kỳ | Chọn tháng từ mới tới cũ; chuyên cần của kỳ; trạng thái chưa có phiếu | Chỉ trả bản published đúng trẻ/kỳ/revision; lớp và Coach phải phản ánh lịch sử của kỳ, không áp lớp hiện tại cho mọi phiếu |
| MP-08: Năng lực | 6 kỹ năng: Dẫn bóng, Chuyền bóng, Ném rổ, Phòng thủ, Thể lực, Tinh thần đội; 5 mức và chênh lệch kỳ trước | So sánh cùng rubric version. Mock bỏ dòng thiếu điểm; bản thật phải hiện Chưa đánh giá, không đổi null thành 0 |
| MP-09: Nhận xét/PDF | Nhận xét Coach, mục tiêu tháng tới, tên Coach, ngày đánh giá; mở PDF nếu có link | Chỉ PDF đã duyệt, đúng revision; quyền được kiểm lại khi mở. Helper Drive trong mock không thay thế thiết kế R2 private / file có kiểm quyền |
| MP-10: Danh mục | Ảnh hoặc hình minh họa fallback, tên, giá, mô tả, còn hàng/tạm hết; sản phẩm hết hàng không có form mua | Catalog/variant do SSA quản lý; giá và việc hiển thị giá phụ thuộc quyết định G1. Cờ conHang trong mock chưa phải hệ thống tồn kho |
| MP-11: Đăng ký mua | Chọn size/màu, số lượng 1 đến 10, trẻ; ghi chú tối đa 300 ký tự; tạm tính; validation và trạng thái đang gửi | Mock đăng ký từng sản phẩm, không có giỏ nhiều sản phẩm. Backend kiểm variant, scope, giới hạn số lượng, giá và idempotency; lưu yêu cầu + outbox atomic |
| MP-12: Sau đăng ký | Mã đơn, tạm tính, thông báo Sale gọi xác nhận và thu tiền; xem Đơn của tôi | Không thanh toán online trong mock. Trạng thái mẫu gồm Mới, Đã liên hệ, Đã thu tiền, Đã giao, Huỷ; cần SSA chốt chuyển trạng thái và người được đổi |
| MP-13: Thông báo | Badge chưa đọc; Tất cả/Chưa đọc; mở chi tiết tự đánh dấu; đánh dấu toàn bộ; nhóm điểm danh, học phí, lịch học, sự kiện, kết quả, thông báo | Đã đọc phải lưu theo guardian/recipient ở server, không dùng trạng thái của cha cho mẹ; chỉ nhận nội dung đúng audience |
| MP-14: Chi tiết tin | Nội dung, ngày, trẻ hoặc thông báo chung; tệp đính kèm nếu có; tin kết quả mở đúng trẻ/kỳ | Backend cung cấp resource/period ID, không suy kỳ từ tên tiêu đề như mock; file private kiểm quyền |
| MP-15: Liên hệ SSA | Có mã CTA Báo lý do nghỉ và Nhắn SSA gia hạn nhưng phụ thuộc OA ID; hiện OA ID rỗng và hàm gửi rỗng | Chốt kênh hỗ trợ, cấu hình và quyền; mở hội thoại không đồng nghĩa đã ghi nhận nghỉ/gia hạn. Có task để nhân sự xử lý nếu nghiệp vụ yêu cầu |
| MP-16: Khảo sát | **Chưa có UI hoặc handler khảo sát trong file** | Vẫn thuộc MVP theo FR-07: 8 câu 1 đến 5, 2 câu mở, validation, đúng trẻ/đợt, chống trùng, trạng thái đóng/đã gửi; entry từ Trang chủ/Thông báo là đề xuất cần thiết kế |
| MP-17: Quyền riêng tư/hỗ trợ | Chưa thấy màn hình chính sách, consent, rút quyền/yêu cầu sửa dữ liệu, quản lý phiên | Phải bổ sung theo PLAN §§6,13; định vị entry UI khi thiết kế. Không xem việc đồng ý lấy số là consent cho mọi dữ liệu trẻ |

Yêu cầu ngày 12/11/2026 bổ sung thanh toán online vào kế hoạch; chưa có trong mã chạy. Không suy từ mock rằng đã có: thanh toán online, giỏ hàng, tự đổi/hủy đơn, tự đổi thông tin học viên, tự đăng ký/hủy buổi, chat nội bộ, quản trị hoặc API MISA trực tiếp.

## 3. Tính năng Web Admin

**Đây là phạm vi phải xây để vận hành sản phẩm; chưa có ứng dụng Web Admin trong repo.** Web responsive cho nhân sự, đăng nhập riêng với MFA/SSO; menu theo role và sân/lớp. Coach, Sale và người duyệt là các vai trò trong cùng Web Admin, không mặc định là ứng dụng riêng. Dashboard điều hành không đồng nghĩa tất cả nhân sự có quyền xem dữ liệu trẻ.

| ID / module Admin | Người dùng chính | Thao tác và đầu ra | Giới hạn bắt buộc |
|---|---|---|---|
| AD-01: Tổng quan công việc | Vận hành, người quản lý đúng scope | Xem batch lỗi/chờ duyệt, nguồn quá hạn, phiếu nháp/chờ duyệt, yêu cầu Sale chưa xử lý, care task và gửi tin thất bại; đi vào chi tiết | Chỉ số lấy từ dữ liệu thật có định nghĩa; không coi số mẫu là KPI. Dashboard kỹ thuật có thể liên kết công cụ quan sát riêng |
| AD-02: Học viên/lớp/sân | Vận hành | Tra hồ sơ, enrollment lịch sử, lịch, gói và điểm danh; xem nguồn/generation; tiếp nhận yêu cầu sửa | Sửa ở đúng nguồn có authority; không ghi đè MISA bằng thao tác tùy ý trên dashboard |
| AD-03: Phụ huynh/liên kết | Vận hành được giao, người xác minh | Xem candidate, đối chiếu evidence, verify/revoke liên kết, xử lý đổi số, xem lịch sử và thu hồi session liên quan | Excel trùng số không tự verified; lưu actor/reason/evidence; không tự phục hồi link revoked |
| AD-04: Import/đối soát | Vận hành nhập; người duyệt publish | Nhận file MISA/Coach, mapping version, validate, preview diff/count/checksum, xem dòng lỗi/quarantine, duyệt hoặc từ chối | Publish generation bằng CAS, lỗi giữ bản đang phục vụ; có truy vết file→batch→row và rollback được kiểm soát |
| AD-05: Phiếu Coach | Coach soạn, người duyệt công bố | Nhập/import 6 kỹ năng, nhận xét, mục tiêu, rubric, kỳ và revision; preview, yêu cầu sửa, duyệt, tạo PDF private | Coach không mặc nhiên tự publish; chỉ published xuất hiện ở Mini App; AI gợi ý là tùy chọn sau duyệt |
| AD-06: Thông báo | Vận hành nội dung, người duyệt | Soạn, chọn audience theo trẻ/lớp/sân, preview recipient, đính kèm, hẹn giờ, duyệt/phát hành/hủy; xem đã đọc | Snapshot recipient khi publish; kiểm quyền/consent hiện hành khi gửi ngoài; nội dung sửa có revision |
| AD-07: Khảo sát/chăm sóc | Vận hành, người chăm sóc đúng scope | Tạo đợt/câu hỏi versioned, mở/đóng, xem tiến độ và kết quả; tạo/phân công/theo dõi task điểm thấp | Không sửa schema đợt đã có câu trả lời; giữ grain theo trẻ/gia đình đã chốt, bảo vệ câu trả lời tự do |
| AD-08: Catalog | Sale/quản trị catalog | Quản lý sản phẩm, ảnh, mô tả, SKU/size/màu, trạng thái có hàng và giá nếu được duyệt | Không suy ra cần ERP/tồn kho đầy đủ; thay đổi có version. C1/C2 phải đồng bộ với UI phụ huynh |
| AD-09: Đơn/nhu cầu tư vấn | Sale | Nhận task bền vững, phân công, xem nhu cầu/biến thể/trẻ và liên hệ tối thiểu; ghi nhận gọi lại, kết quả, trạng thái, lịch sử | Không tự suy đã thu tiền từ gửi form. Chốt quyền sửa/hủy, lý do, bằng chứng và cập nhật ngược cho phụ huynh; Sale không được xem điểm/survey tự do |
| AD-10: Gửi tin và hỗ trợ | Vận hành kỹ thuật đúng quyền | Tra event/delivery/provider ID, retry, DLQ, ambiguous outcome; liên kết request với batch và màn hình | Không retry mù gây gửi trùng; không đưa token/phone/raw nhận xét vào log; ZBS cần được duyệt quyền/chi phí |
| AD-11: Nhân sự/quyền/audit | Admin kỹ thuật, người kiểm soát | Gán role và scope, quản lý vòng đời tài khoản, tra audit thay đổi/phê duyệt, xử lý quyền tạm break-glass | Backend deny-by-default; admin kỹ thuật không mặc nhiên đọc nội dung trẻ; không đưa secret thành trường hiển thị thông thường |
| AD-12: Riêng tư/phục hồi | Người phụ trách dữ liệu + kỹ thuật | Tiếp nhận rút consent/chỉnh sửa/xóa; theo dõi SLA và evidence; quản lý yêu cầu rollback/restore và đối soát sau khôi phục | Backup/deploy/Airflow không bắt buộc nhúng toàn bộ console vào Admin; thao tác nguy hiểm qua runbook, phân quyền và audit |

## 4. Tính năng hai UI phối hợp như thế nào?

| Web Admin / hệ thống thực hiện | Mini App nhận được | Điều kiện trước khi hiển thị |
|---|---|---|
| Xác minh giữa guardian và student | Chọn đúng các con được liên kết | Verified, còn hiệu lực; kiểm scope mỗi lần gọi |
| Đối soát và publish file MISA | Hồ sơ, lịch, gói, chuyên cần và freshness | Cùng generation đã duyệt, field authority đúng |
| Duyệt phiếu và PDF | Kết quả kỳ, nhận xét, mục tiêu, PDF | Published, đúng trẻ/kỳ/revision |
| Phát hành thông báo | Danh sách, badge, nội dung và đính kèm | Đúng recipient; đã đọc riêng từng người |
| Mở đợt khảo sát | Form đúng trẻ/đợt, xác nhận đã gửi | Chưa đóng, không trùng, version cố định |
| Sale xử lý đăng ký | Yêu cầu của mình và trạng thái xử lý | Lưu bền vững, idempotency; phân biệt nhu cầu và giao dịch |

Airflow, Jobs/Queues, D1/R2 và VPS là thành phần nền hỗ trợ hai UI, không phải thêm app cho phụ huynh. [Quyền và liên kết](archify/access.html) / [Import](archify/import.html) / [Gửi tin](archify/messaging.html).

## 5. Khoảng trống cần thiết kế và nghiệm thu

1. **Triển khai phạm vi thương mại mới:** yêu cầu ngày 12/11 chọn hướng giá/đơn + Checkout SDK. G1 còn phải chốt provider, merchant, settlement và điều kiện phát hành; C2 chỉ là phương án dự phòng khi được SSA quyết định lại.
2. **Bổ sung UI còn thiếu:** Web Admin, khảo sát, chính sách/consent/hỗ trợ và trạng thái liên kết/session. Cần luồng duyệt cho từng module Admin.
3. **Thay stub bằng backend:** Qv/Jv dữ liệu mẫu; Yv tạo đơn trong bộ nhớ; zc/Ed rỗng. Đơn và đã đọc phải tồn tại sau reload và giữa các thiết bị hợp lệ.
4. **Chốt quy tắc nghiệp vụ:** ngưỡng hết gói, học bù/bảo lưu, rubric, survey grain, chuyển trạng thái đơn, quyền sửa/hủy và bằng chứng thu tiền.
5. **Nghiệm thu liên UI:** phụ huynh không thấy draft; revoke chặn cả PDF; publish mới đổi dữ liệu coherent; Sale không xem điểm; gửi lại yêu cầu không sinh đơn thứ hai; đã đọc không ảnh hưởng người giám hộ khác.

## 6. Dấu vết đối chiếu source mock

File là bundle minified; tên hàm dùng để định vị trong đúng artifact theo hash, không phải tên component nên giữ khi rebuild.

| Vị trí source | Điều đã kiểm tra |
|---|---|
| C0 / Il / I0 | 4 tab; chọn con; trang chủ, cảnh báo ≤3, 3 tin và 5 buổi gần đây |
| O0 | Chọn kỳ, 6 kỹ năng/5 mức, delta kỳ trước, nhận xét/mục tiêu/PDF; thiếu điểm bị bỏ qua |
| y0 / _0 / v0 | Danh mục, mua từng sản phẩm, form, size/màu, lượng 1 đến 10, ghi chú 300, đơn và nhãn trạng thái |
| A0 / gh / P0 | Lọc/chưa đọc, mở chi tiết, attachment, parse kỳ từ tiêu đề và CTA liên hệ có điều kiện |
| w0 / N0 / k0 / x0 / h0 | Mã onboarding và lỗi; w0 tự vào dữ liệu mẫu, chưa xác minh đăng nhập thực |
| Qv / Jv / Yv / zc / Ed / fo | Session mau, clone dữ liệu, đơn trong bộ nhớ, hai stub rỗng, OA ID rỗng |
| fh | Helper mở Drive/URL; không chứng minh quyền private file đúng thiết kế đích |

FR-01…FR-12 là baseline; FR-13…FR-18 bổ sung theo yêu cầu ngày 12/11/2026. Mã trong `apps/miniapp` hiện chỉ có UI và dữ liệu mock cục bộ, chưa có backend, SDK checkout hay gửi tin thật.


## 7. Bổ sung module thông báo, thương mại và thanh toán

**Phạm vi đã được yêu cầu, chưa triển khai.** Yêu cầu ngày 12/11/2026 mở rộng kế hoạch cũ vốn chỉ nhận đăng ký và để Sale liên hệ. Phần này là đặc tả bổ sung có ưu tiên khi khác với giới hạn thương mại trước đây; không biến dữ liệu mock thành giao dịch thật.

### 7.1 Đã có gì và còn thiếu gì?

| Nhóm được yêu cầu | Tài liệu/mã hiện tại | Phần bổ sung phải xây |
|---|---|---|
| ZNS + Notification Mini App | MP-13/14 có inbox/badge/đã đọc mock; PLAN có outbox và ZBS | MP-18: gửi theo sự kiện, template, deep link, lịch sử delivery và preference |
| Payment gateway + SDK checkout merchandise | PLAN C1 từng nêu như lựa chọn; mã chỉ tạo đăng ký mẫu | MP-19: checkout qua SDK, backend payment adapter, xác nhận server, xử lý pending/retry |
| Đơn hàng + thanh toán phụ huynh | MP-12 có lịch sử đơn mẫu; chưa tách trạng thái tiền/giao hàng | MP-20: chi tiết đơn, lịch sử thanh toán/hoàn tiền, yêu cầu hủy/hỗ trợ |
| Quản lý merchandise | AD-08 mới mô tả catalog/variant | Mở rộng AD-08: xuất bản sản phẩm, giá, tồn khả dụng, giữ hàng và điều chỉnh có lý do |
| Quản lý thanh toán | AD-09 chỉ có ghi nhận trạng thái Sale | AD-13: giao dịch, pending, hoàn tiền, ngoại lệ và phân quyền tài chính |
| Audit nguồn tiền thanh toán | AD-11 có audit thao tác chung; AD-04 là đối soát file học viên | AD-14: đối soát tài chính, nguồn thu, settlement, phí, thực nhận và evidence |

**Thuật ngữ:** “ZNS” trong yêu cầu được ánh xạ sang **ZBS Template Message** theo tài liệu Zalo hiện hành. Inbox trong Mini App là dữ liệu ứng dụng; tin gửi qua Zalo/OA là kênh bên ngoài. Không mặc định có quyền push tự do vào Mini App. SDK Checkout điều phối trải nghiệm thanh toán; cổng thanh toán xử lý giao dịch, còn đối soát xác nhận khoản tiền thực nhận. Ba phần này không thay thế nhau. [Nguồn Zalo](https://zalo.solutions/news/thong-bao-hop-nhat-dinh-nghia-tin-uid-va-zns-thanh-zbs-template-message/cp1zx4bq8mzhhszgz0br1ocd), [Checkout SDK](https://docs.zaloplatforms.com/docs/MA/checkoutSdk/intro).

### 7.2 Mini App phụ huynh

| ID | Màn hình và hành vi | Điều kiện nghiệm thu |
|---|---|---|
| MP-18 / FR-13 | Inbox theo người nhận; tin đơn mới, thanh toán được xác nhận, giao/nhận hàng, hủy/hoàn tiền; ZBS dẫn về đúng đơn hoặc nội dung; quản lý lựa chọn kênh trong phạm vi nền tảng cho phép | Quyền/template/audience hợp lệ; người không có quyền mở deep link bị từ chối. Delivered bên Zalo không đồng nghĩa đã đọc inbox. Gửi tin lỗi không làm mất đơn hay đảo trạng thái thanh toán |
| MP-19 / FR-14 | Từ sản phẩm → chọn biến thể/số lượng/trẻ → xem giá cuối, cách nhận hàng và phí nếu có → xác nhận → SDK Checkout → xem kết quả do server xác nhận | Server định giá, kiểm tồn và tạo payment attempt. Hủy SDK, mất mạng, app đóng, pending, timeout và retry đều có màn hình. Không ghi “đã thanh toán” từ callback phía client. Đổi giá/tồn phải yêu cầu phụ huynh xác nhận lại |
| MP-20 / FR-15 | Đơn của tôi → chi tiết dòng hàng, giá chốt, cách nhận, trạng thái xử lý, trạng thái tiền riêng, lần thanh toán, hoàn tiền và liên hệ hỗ trợ | Chỉ người đặt hoặc người được cấp quyền xem; cùng con không tự cho mọi guardian xem đơn. Chỉ cho thanh toán lại sau xác minh lần trước; yêu cầu hủy/hoàn cần xử lý nghiệp vụ, không tự hoàn chỉ vì bấm nút |

Giữ bốn tab hiện tại: checkout/chi tiết đơn nằm dưới **Cửa hàng**, inbox ở **Thông báo**; không cần thêm một app. Giai đoạn đầu giữ mua từng sản phẩm như mock; giỏ nhiều sản phẩm chưa nằm trong yêu cầu. Checkout merchandise không tự mở rộng sang thu học phí. Cách nhận tại sân hay giao hàng, phí vận chuyển và chính sách hủy/đổi trả phải được SSA chốt trước tích hợp thật.

### 7.3 Trang vận hành Web Admin

| ID | Màn hình/chức năng | Vai trò và kiểm soát |
|---|---|---|
| AD-08 / FR-16: Merchandise | Danh mục; chi tiết SKU/size/màu/ảnh; giá và lịch sử; nháp/xuất bản/ẩn; tồn khả dụng/đang giữ; nhập/điều chỉnh; lịch sử biến động; danh sách gần hết | Nhân sự catalog soạn; người được giao quyền duyệt giá/xuất bản. Không xóa SKU đã có đơn; đơn giữ snapshot. Sổ tồn có tham chiếu đơn/điều chỉnh; ERP nhiều kho nằm ngoài phạm vi hiện tại |
| AD-09 mở rộng: Đơn hàng | Tìm/lọc theo mã, người đặt, ngày, trạng thái; xử lý xác nhận, chuẩn bị, giao/nhận, yêu cầu hủy; xem lịch sử và liên kết giao dịch | Sale/fulfillment theo scope. Không có quyền tự đánh dấu đã trả tiền hoặc hoàn tiền. Chỉnh đơn sau thanh toán phải qua quy trình chênh lệch/hoàn và audit |
| AD-13 / FR-17: Thanh toán | Danh sách payment/attempt; chi tiết provider transaction; hàng đợi pending/unknown; tra cứu provider; thu ngoài cổng nếu được bật; yêu cầu/duyệt hoàn; theo dõi kết quả hoàn | Kế toán/tài chính; người lập khác người duyệt thu thủ công, hoàn tiền và điều chỉnh. Không cho sửa trực tiếp số tiền giao dịch đã xác nhận; dùng bản ghi điều chỉnh liên kết |
| AD-14 / FR-18: Audit nguồn tiền | Nhập/nhận báo cáo cổng và sao kê; matching; đối soát theo ngày/kỳ; tiền thu, phí, hoàn, net thực nhận; unmatched/thiếu/thừa/trùng; duyệt xử lý lệch; xuất hồ sơ truy vết | Người đối soát, người duyệt và kiểm soát viên có quyền riêng. Bằng chứng hạn chế truy cập, thông tin tài khoản được che; mọi thay đổi có actor/time/reason và trước/sau |
| AD-06/10 mở rộng: Notification | Template/version, loại sự kiện, audience preview, phát hành, delivery log, quota/chi phí và retry/DLQ | Quyền biên tập khác quyền cấu hình gửi. Chỉ gửi sau sự kiện nghiệp vụ được commit, chống gửi trùng theo event/recipient/channel |

“Audit nguồn tiền” ở đây là **truy vết nguồn thu và đối soát khoản thực nhận**, không phải kết luận pháp lý về nguồn gốc tài sản hoặc hệ thống AML. Phải trả lời: đơn nào → ai đặt → phương thức/kênh nào → giao dịch nào → đơn vị/tài khoản merchant nào thu → settlement/sao kê nào → phí/hoàn/điều chỉnh nào → tiền ròng bao nhiêu → ai xác nhận. Người chuyển tiền có thể khác người đặt; chứng từ không tự chứng minh quan hệ giám hộ.

### 7.4 Luồng và trạng thái cần tách

1. **Catalog → đơn:** backend chốt snapshot tên/SKU/giá/quantity/currency, kiểm tồn, tạo đơn và giữ hàng có TTL nếu dùng tồn kho. Server dùng số nguyên VND; không tin tổng tiền client.
2. **Đơn → checkout:** tạo payment attempt với idempotency key; gọi SDK bằng dữ liệu server. Một đơn có thể có nhiều lần thử, nhưng không được ghi nhận thu hai lần như một giao dịch bình thường.
3. **Provider → backend:** xác minh chữ ký, merchant, transaction, amount/currency và order; lưu event chống trùng; cập nhật payment + outbox atomic. Callback trễ/đảo thứ tự không được hạ `paid` thành `failed`. Unknown phải truy vấn trước khi thu lại.
4. **Tiền → xử lý đơn:** xác nhận thu tiền mới kích hoạt bước fulfillment được quy định. Gửi ZBS/inbox từ outbox; tin lỗi vẫn giữ công việc vận hành. Hết thời gian giữ hàng nhưng tiền tới muộn chuyển ngoại lệ để giao/hoàn có người duyệt.
5. **Settlement → đối soát:** khớp giao dịch với báo cáo cổng/sao kê; tiền thu gộp trừ hoàn, phí và điều chỉnh giải thích được phải bằng net thực nhận theo kỳ, kể cả khoản chuyển kỳ. Provider báo paid chưa có nghĩa tiền đã về ngân hàng.

| Đối tượng | Trạng thái đề xuất | Quy tắc |
|---|---|---|
| Đơn | chờ xác nhận, xác nhận, chuẩn bị, sẵn sàng nhận/đang giao, hoàn tất, hủy | Độc lập trạng thái tiền; hủy không tự đồng nghĩa đã hoàn |
| Payment attempt | created, pending, succeeded, failed, cancelled, expired, unknown | Retry cùng attempt dùng cùng key; thành công từ server evidence |
| Thanh toán của đơn | unpaid, pending, paid, partially_refunded, refunded | Thu thừa/trùng là ngoại lệ, không âm thầm bỏ; hoàn không vượt phần đã thu còn có thể hoàn |
| Refund | requested, approved, processing, succeeded, failed, unknown | SDK/client không tự xác nhận; retry chống hoàn hai lần |
| Đối soát | unmatched, matched, discrepancy, resolved | Lưu kết quả matching và lý do điều chỉnh; khóa kỳ đã duyệt, mở lại có quyền/audit |

### 7.5 Dữ liệu, API và bằng chứng

**Các thực thể bổ sung:** `order_items` snapshot; `inventory_reservations` và `stock_movements`; `payment_attempts`; `payment_transactions`; `payment_events`; `refunds`; `settlement_batches/lines`; `reconciliation_cases`; `financial_adjustments`; `notification_recipients/deliveries`. Một order có nhiều attempts, một transaction có thể có nhiều refunds trong giới hạn; settlement line liên kết transaction hoặc được đưa vào unmatched. Ràng buộc unique `(provider, merchant, transaction_id)` và event ID chống xử lý lặp.

**API dự kiến, chưa tồn tại:** tạo đơn/checkout attempt; đọc đơn/payment status; yêu cầu hủy/hoàn; payment webhook; Admin CRUD catalog, fulfillment, refund approval, import settlement và reconcile. Parent endpoint kiểm order ownership; webhook không dùng session phụ huynh mà xác minh provider; endpoint tài chính yêu cầu role và scope riêng. Secret chỉ ở server. CSV import cũng có preview, kiểm trùng và audit; không cho import tự đánh dấu tất cả paid.

**Bằng chứng một khoản thu:** order ID, attempt ID, provider transaction ID, merchant/phương thức, amount/currency, thời điểm nghiệp vụ/nhận event, reference chứng từ, settlement ID, gross/fee/refund/net, người nhập/duyệt, lý do và correlation ID. Không lưu PAN/CVV; không đưa token hoặc thông tin tài khoản đầy đủ vào log. Hạch toán ERP/MISA và hóa đơn điện tử chưa được coi là tích hợp đã có.

### 7.6 Điều kiện triển khai và nghiệm thu

| Mã kiểm thử mới | Phải chứng minh |
|---|---|
| T17 Notification | Inbox đúng recipient; read riêng; deep link kiểm quyền; template bị từ chối/quota/retry không làm gửi trùng nghiệp vụ hoặc mất đơn |
| T18 Checkout | Client giả success không đổi paid; webhook giả/sai tiền/sai merchant bị từ chối; duplicate và out-of-order an toàn; đóng app rồi mở lại thấy trạng thái server |
| T19 Orders/stock | Hai người mua SKU cuối không bán vượt; giá thay đổi cần xác nhận; giữ hàng hết hạn/tiền tới muộn được xử lý; không xem được đơn người khác |
| T20 Refund | Maker không tự duyệt; gửi lại không hoàn hai lần; partial refund không vượt số thu; lỗi provider giữ trạng thái thật và hồ sơ xử lý |
| T21 Reconciliation | Bộ mẫu có thiếu/thừa/trùng, phí, hoàn và chuyển kỳ; truy nguyên tới đơn và khoản nhận; tổng khớp hoặc lệch có owner, evidence, người duyệt; phát lại file không nhân đôi |

**Phụ thuộc cần cung cấp khi bắt đầu tích hợp:** OA/App đã liên kết và được cấp quyền, template được duyệt, merchant/provider sandbox và production, tài khoản nhận tiền, phương thức thanh toán, phí/chu kỳ settlement, quy trình nhận hàng/hủy/hoàn, kế toán lập/duyệt và retention bằng chứng. Chưa chọn cổng cụ thể; không mặc định Checkout SDK đồng nghĩa bắt buộc chỉ dùng ZaloPay. [Cấu hình chính thức](https://docs.zaloplatforms.com/docs/MA/checkoutSdk/integration-process/overview/setting).

**Thứ tự:** chốt nghiệp vụ/provider → thiết kế schema/quyền/state → backend/Admin merchandise và đơn → sandbox Checkout/webhook → notification → refund/đối soát → UAT liên UI và thử trên Zalo iOS/Android → duyệt phát hành. Tính lại effort/chi phí; không dùng ước tính baseline làm cam kết cho scope mới. Bộ sơ đồ bổ sung dưới đây mô tả scope mới. commerce-data giữ baseline survey/outbox; payment-data và settlement-data bổ sung quan hệ tiền, không phải migration vật lý.


## 8. Bản đồ sơ đồ cho buổi trình bày

| Câu hỏi | Sơ đồ Archify | Dùng khi |
|---|---|---|
| Từ mua hàng đến tiền thực nhận? | [Tổng quan thương mại](archify/commerce.html) | Giới thiệu luồng cho quản lý |
| Ai quản lý hàng và giữ tồn? | [Merchandise](archify/merchandise.html) | Phân công vận hành |
| Khi nào được ghi nhận đã trả tiền? | [Sequence Checkout](archify/checkout.html) | Review kỹ thuật/backend |
| Inbox khác tin Zalo thế nào? | [Notification/ZNS–ZBS](archify/notification-delivery.html) | Giải thích kênh nhận tin |
| Ai có quyền hoàn, lúc nào đã hoàn? | [Hủy và hoàn tiền](archify/refund.html) | Chính sách và phân quyền tài chính |
| Tiền về thiếu/thừa xử lý ra sao? | [Đối soát nguồn thu](archify/reconciliation.html) | Kế toán/kiểm soát |
| Đơn, lần thử, giao dịch, hoàn liên hệ thế nào? | [ERD payment](archify/payment-data.html) | Thiết kế dữ liệu logic |
| Khoản tiền về khớp giao dịch nào? | [ERD settlement](archify/settlement-data.html) | Thiết kế đối soát logic |

Mọi sơ đồ mới là thiết kế đề xuất theo yêu cầu đã ghi, không xác nhận tích hợp chạy thật. Các ERD chỉ chọn trường khóa và nghiệp vụ quan trọng; schema vật lý/migration sẽ được thiết kế khi triển khai.