# Đánh giá và rebuild tài liệu SSA

Ngày 11/11/2026. Phạm vi: toàn bộ bộ đọc SSA, nguồn tài liệu, sơ đồ, trình chiếu, PDF và công cụ build. Đây là đánh giá tài liệu thiết kế, không phải audit ứng dụng hoặc hệ thống production.

## Kết luận

Bản cũ có chiều sâu kỹ thuật nhưng thiếu thứ tự đọc. Quyết định, quy tắc nghiệp vụ, chi tiết triển khai và bằng chứng còn thiếu nằm cạnh nhau với trọng lượng gần như nhau. Người đọc phải tự rút ra điều quan trọng từ một trang 20 chương.

Bản 2.0 đưa câu hỏi và kết luận lên trước; sơ đồ giải thích luồng; người phụ trách và bằng chứng nghiệm thu theo ngay sau. Đặc tả đầy đủ tiếp tục tra cứu được, không mất contract, ma trận quyền hoặc quy tắc dữ liệu.

## Phát hiện và cách xử lý

| Phát hiện | Tác động | Thay đổi |
|---|---|---|
| Trang đầu chủ yếu là giới thiệu và mục lục | Chưa thấy hệ thống hoạt động theo thiết kế như thế nào | Đưa toàn cảnh kiến trúc ngay dưới tiêu đề; ba lối đọc theo vai trò |
| 20 chương cùng mức chi tiết | Khó chốt ý, khó tìm người chịu trách nhiệm | Mỗi chương có luận điểm, ba điểm chính, owner, evidence; đặc tả trong disclosure |
| 4 Archify chỉ bao phủ runtime, lineage, audit và B | Các luồng nghiệp vụ chưa có lối khám phá tương tác | 17 bản đồ, bổ sung quyền, import, Coach, survey, commerce, messaging, privacy, recovery, release, roadmap và phạm vi |
| Sơ đồ toàn cảnh cũ chỉ là một đường gọi | Dễ bỏ sót admin, Airflow và quyền sở hữu dữ liệu | Sơ đồ mới tách request, điều phối sync, người duyệt, DB/files và side effects |
| Director phải đọc nhiều bảng đặc tả | Khó nhận ra quyết định cần chốt | Viết lại 13 phần theo kết luận, điểm cần duyệt và đường dẫn về đặc tả |
| Runbook nằm rải rác trong kế hoạch | Người trực phải ghép lại bước xử lý | Trang vận hành riêng theo dấu hiệu, owner, evidence, cô lập, phục hồi và xác nhận |
| Thư viện sơ đồ thiếu nhóm và câu hỏi | Phải mở từng hình để tìm đúng luồng | Atlas có câu hỏi, ảnh preview thật, lọc theo chủ đề và link chương |
| Các con số dự toán dễ bị đọc thành cam kết | Có thể chốt lịch/ngân sách từ baseline cũ | Giữ nhãn baseline trước Airflow/VPS; không tự đưa dự toán mới |

## Phạm vi bằng chứng

- Repository chứa tài liệu và công cụ sinh/kiểm tra tài liệu. Các đường dẫn `apps/miniapp`, `workers/api` trong PLAN là cấu trúc dự kiến, không phải source hiện có.
- PLAN.md bản 1.2 là authority nghiệp vụ được giữ nguyên. CHAPTERS.json là lớp tóm lược; ATLAS.json là chỉ mục sơ đồ, không thay rule chi tiết.
- 17 sơ đồ trỏ về PLAN tại commit `05bb7ca2dfe249d1bfb325b901ee8d7d2958d19e`. Trích dẫn này chứng minh nội dung thiết kế, không chứng minh cấu hình đã triển khai.
- Nguồn chính sách, quota và giá giữ mốc kiểm tra ghi trong SOURCES.md; đợt rebuild này không phải một lần tái xác minh toàn bộ nhà cung cấp.
- G0/G1, owner có tên, thông số tải, giá và ngày live vẫn cần quyết định/bằng chứng triển khai. Không biến gate còn mở thành đạt.

## Bản đồ độ bao phủ

| Câu hỏi | Sơ đồ | Nguồn |
|---|---|---|
| Hệ thống gồm gì? | [Toàn cảnh](archify/overview.html), [đường request](archify/runtime.html) | PLAN §4 |
| Phạm vi cho ai? | [Module](archify/modules.html) | PLAN §3, §8 |
| Ai xem được trẻ? | [Access](archify/access.html) | PLAN §6 |
| File thành dữ liệu thế nào? | [Lineage](archify/lineage.html), [import](archify/import.html) | PLAN §4.4, §7 |
| Field thuộc ai? | [Ownership](archify/ownership.html), [ER lõi](diagrams.html#diagram-data-core), [ER nghiệp vụ](diagrams.html#diagram-commerce-data) | PLAN §5 |
| Phiếu/khảo sát xử lý ra sao? | [Coach](archify/report.html), [survey](archify/survey.html) | PLAN §11 |
| Cửa hàng còn gì phải chốt? | [Commerce](archify/commerce.html) | PLAN §8.1, §10 |
| Gửi lỗi hoặc trùng? | [Messaging](archify/messaging.html) | PLAN §10, §12 |
| Thu hồi/xóa có phạm vi nào? | [Privacy](archify/privacy.html) | PLAN §13 |
| Số sai hoặc hệ thống dừng? | [Audit](archify/audit.html), [recovery](archify/recovery.html) | PLAN §14, §15 |
| Khi nào được phát hành? | [Release](archify/release.html), [roadmap](archify/roadmap.html) | PLAN §16 tới §19 |
| Nếu G0 của A không đóng? | [B dự phòng](archify/hybrid.html) | PLAN §1.1, §4.3 |

Không tạo ER vật lý với cột/kiểu dữ liệu chưa có migration. Hai ER gốc là mô hình logic; khi có source ứng dụng phải đối chiếu lại với schema thật.

## Các đường đọc

1. Director: [bản trình bày](presentation.html), chốt phạm vi và G0/G1, đọc chi tiết theo liên kết khi cần.
2. Kỹ thuật: [kiến trúc](index.html), chọn chương, đọc điểm chính/sơ đồ rồi mở đặc tả và tiêu chí kiểm thử.
3. Vận hành: [tình huống và runbook](operations.html), chọn dấu hiệu, xác định owner và evidence trước thao tác.

## Giữ lại và giới hạn

Giữ 20 chương nguồn, 16 SVG tham chiếu, 13 anchor trình bày, các route HTML cũ và các liên kết đến đặc tả. Không xóa source/receipt lịch sử. Bốn bản capture Archify cũ thuộc artifact cũ; không dùng chúng để xác nhận HTML mới. Receipt hiện hành và phạm vi kiểm thử được ghi trong [VERIFICATION.md](VERIFICATION.md).

Hallmark áp dụng cho bốn trang đọc: token SSA, responsive, focus, nội dung offline và điều hướng. Viewer Archify là runtime upstream; không sửa CSS/runtime của skill để biến kết quả lint của bộ đọc thành kết quả cho Viewer.

## Review nội dung sau rebuild

Review độc lập phát hiện và đã sửa: sơ đồ phục hồi phải tách quay generation, redeploy artifact và restore DB biệt lập; nguồn cho idempotency/outbox và expectedVersion phải trỏ đúng đoạn PLAN; gate release phải có G4 cùng G0/G1. Liên kết nội bộ vận hành được kiểm trên anchor HTML thật.

## Rà soát diagram sau cập nhật UI

Phát hiện: 13 vị trí SVG trong Kiến trúc, 3 trong Tổng quan và 16 bản lặp trong thư viện. Vận hành đã dùng Archify. Link tới Archify bên cạnh SVG chưa làm hình đang hiển thị trở thành Archify.

Đã đổi renderer cho toàn bộ marker diagram sang preview Archify; bỏ phần gallery SVG trùng lặp và giữ anchor cũ. Các luồng dùng lại bản Archify cùng chủ đề đã có; data-core và commerce-data thêm ERD logic để không mất cardinality. Tổng cộng 19 artifact, 38 ảnh light/dark. Tên mục Cho Director đổi thành Tổng quan; vai trò Director trong nội dung nghiệp vụ vẫn giữ.

| Marker cũ | Bản Archify |
|---|---|
| context | [overview](archify/overview.html) |
| lineage | [lineage](archify/lineage.html) |
| audit | [audit](archify/audit.html) |
| hybrid | [hybrid](archify/hybrid.html) |
| data-core | [data-core](archify/data-core.html) |
| commerce-data | [commerce-data](archify/commerce-data.html) |
| auth | [access](archify/access.html) |
| order | [commerce](archify/commerce.html) |
| import | [import](archify/import.html) |
| report | [report](archify/report.html) |
| survey | [survey](archify/survey.html) |
| delivery | [messaging](archify/messaging.html) |
| deployment | [release](archify/release.html) |
| director-data | [import](archify/import.html) |
| director-parent | [access](archify/access.html) |
| director-control | [recovery](archify/recovery.html) |