# Build và kiểm chứng bộ tài liệu SSA 2.2

## Phạm vi

Bốn trang HTML, bản trình bày Tổng quan, 20 brief nối về đặc tả, 26 sơ đồ Archify và 18 slide. Kiểm thử này kiểm chứng **tài liệu và tương tác của bộ đọc**, không kiểm chứng ứng dụng SSA, Zalo account, Airflow, VPS hoặc Cloudflare production.

## Build từ source

Cần Node.js 18+ (lần chạy này dùng 24.19.0), npm, uv, Chrome/Chromium. Đặt CHROME_PATH nếu executable không ở vị trí chuẩn. Không cần file proposal gốc hoặc credentials SSA.

```bash
rtk proxy npm ci
rtk proxy npm run build:docs
rtk proxy npm run verify:docs
rtk proxy npm run verify:presentation
rtk proxy npm run verify:atlas
```

`build:docs` dùng Python Markdown 3.10.2 qua uv, sinh bốn HTML, GUIDE.md, ATLAS.md và build-manifest.json. `verify:presentation` tạo lại presentation.pdf từ HTML bằng Chrome print.

Khi sửa JSON Archify:

```bash
rtk proxy npm run build:atlas
rtk proxy npm run build:docs
rtk proxy npm run verify:presentation
rtk proxy npm run verify:atlas
```

`build:atlas` finalize tuần tự vì Archify có delivery lock theo thư mục. Mỗi lần build dùng thư mục receipt riêng trong archify/checks để không ghi đè evidence cũ. Sau finalize, capture light/dark và ghi hash preview. Không sửa HTML Archify bằng tay: sửa sẽ làm mất liên kết provenance.

## Nguồn chuẩn và đầu ra

| Nguồn | Đầu ra |
|---|---|
| PLAN.md + CHAPTERS.json | 20 chương có brief, owner/evidence, đặc tả; GUIDE.md |
| PRESENTATION.md | presentation.html và presentation.pdf |
| OPERATIONS.md | operations.html |
| ATLAS.json + archify/*.json | Atlas, link chương, 26 Viewer và ATLAS.md |
| DIAGRAMS.md | Bản lưu SVG lịch sử; marker được map sang Archify |
| ssa_document.css + ssa_reader.js | Theme, focus, responsive, disclosure, filter và trình chiếu |

PLAN.md bản 1.3 bổ sung scope thương mại theo yêu cầu 12/11. Các sơ đồ baseline giữ source references pin commit `05bb7ca2dfe249d1bfb325b901ee8d7d2958d19e`, chứng minh thiết kế ở baseline đó. Bộ đọc 2.0 là thay đổi chưa commit trong working tree; không trình bày source mới như bytes đã có ở commit baseline.

## Evidence hiện hành

- [build-manifest.json](build-manifest.json): hash nguồn, danh sách chương, SVG, map, slide và trang.
- [browser-checks.json](browser-checks.json): SVG và trang tham chiếu ở 375/1280/1920px, tắt JavaScript.
- [presentation-checks.json](presentation-checks.json): 24 tổ hợp trang/theme/viewport, tương tác deck, theme persistence, tìm chương, offline, no-JS và in đủ slide.
- [atlas-checks.json](atlas-checks.json): 24 tổ hợp cho cả bốn trang, ảnh, liên kết nội bộ, filter, deep-link, disclosure và hash 19 artifact.
- [archify/acceptance.json](archify/acceptance.json): chỉ các finalize receipt khớp cả specification SHA-256 và artifact SHA-256 hiện tại. Mỗi sơ đồ phải qua validate, deliver, check và browser-check.
- [archify/previews/manifest.json](archify/previews/manifest.json): 34 ảnh light/dark; gắn hash screenshot với HTML nguồn.

Các tệp `*.visual-check.*` cũ của runtime/lineage/audit/hybrid là lịch sử trước rebuild. Receipt gốc `overview.finalize-summary.json` cũng là bố cục trước lần sửa giao tuyến. **Không chọn receipt chỉ vì tên file**: dùng acceptance hiện hành và đối chiếu hash.

## Kiểm tra thiết kế và nội dung

Hallmark chạy static + render trên bốn trang reader, scope app/document. So sánh kept kiểm đường dẫn và hook với trang baseline. Long labels/source URLs được phép wrap; bảng/SVG tham chiếu có scroll cục bộ và focus. Cảnh báo giảm chữ/thiếu số đo trong phần hiển thị được đánh giá theo disclosure: đặc tả vẫn nằm trong HTML và mở được, không bị xóa khỏi PLAN.

Kiểm tra thủ công tập trung vào trang đầu, atlas, bản trình bày, mobile và sơ đồ overview/import. Không gọi toàn bộ 19 sơ đồ là đã được review thị giác riêng; chúng có automated browser gates và preview được tạo từ artifact hiện hành. Viewer Archify upstream không thuộc phạm vi Hallmark của bốn trang đọc.

## Giới hạn

- Cần đọc nguồn provider lại trước triển khai/nộp duyệt; đợt rebuild không xác nhận lại mọi quota/giá/chính sách.
- G0/G1 vẫn mở. Con số dự toán, SLO, retention, RPO/RTO trong PLAN là đề xuất/baseline, chưa phải kết quả đo.
- Giao diện Viewer cố định dùng tiếng Anh; nội dung sơ đồ dùng tiếng Việt.
- Preview là ảnh: mở link HTML để zoom, tìm node và theo đường đi.
- Nội dung SVG tham chiếu được cuộn ngang trên màn hình nhỏ; điểm chính nằm ngoài hình/bảng.

## Kết quả baseline trước bổ sung 12/11 (lịch sử)

- `verify:docs`: đạt 6 viewport checks, không có SVG inline; 26 vị trí preview trong Kiến trúc và 19 trong thư viện, không overflow hoặc broken anchor.
- `verify:presentation`: đạt 24 viewport/theme checks và các thao tác reader/deck. PDF đã đối chiếu bằng pypdf: đúng 13 trang, không có trang tràn chỉ chứa phần cuối slide.
- `verify:atlas`: đạt 19 artifact/38 preview; cả bốn trang có link và ảnh hợp lệ; 20 disclosure, deep-link, print restoration và mọi filter hoạt động; không có request mạng ngoài.
- Contrast: 16 cặp token sáng/tối đạt ngưỡng trong contrast-checks.json.
- Hallmark: xem hallmark-checks.json; các cảnh báo kept về số chữ/số liệu được giải thích bởi lớp đặc tả thu gọn, không có mất nội dung nguồn.

Review nội dung độc lập đã xử lý ba nhóm lỗi: phạm vi phục hồi, source ranges của giao dịch/phiếu và G4 phát hành. Review ảnh trong lượt này bao gồm overview, import, trang đầu desktop/mobile, atlas và slide module. Các sơ đồ còn lại chỉ được xác nhận automated gates và provenance, không khẳng định đã nhìn thủ công tất cả.

## Cập nhật giao diện 2.1

- Light mặc định trên cả bốn trang kể cả OS dark; lựa chọn mới được giữ qua reload.
- Nunito nhúng trong HTML đã tải thành công khi offline; font và giấy phép lưu tại assets/fonts.
- `npm run verify:theme`: pass; gồm lựa chọn cũ, không JavaScript và mục lục mobile.
- `verify:docs`, `verify:presentation`, `verify:atlas`: pass sau đổi bố cục/font; PDF vẫn 13 trang.
- 18 cặp tương phản pass; Hallmark: 0 FAIL, 0 open REFLEX, 4 WARN do heuristic ghép sai nền cho chữ logo. Cặp màu thực tế được kiểm tra trong contrast-checks.json.
- Kiểm tra ảnh desktop 1280px và mobile 375px trong .hallmark/shots/light-refresh-*.png.

## Chuyển diagram hoàn toàn sang Archify

`verify:atlas` kiểm tra cả bốn trang không chứa SVG inline, mọi preview có ID trong ATLAS.json và đúng cặp ảnh light/dark, mọi artifact có finalize receipt khớp hash. Hai ERD data-core/commerce-data đã qua cả bốn gate và được xem ảnh trực tiếp. Các anchor diagram-* cũ vẫn hợp lệ. PDF Tổng quan giữ 13 trang.

## Danh mục tính năng hai UI

FEATURES.md được nhúng trong chương 3 của Kiến trúc, liên kết từ Tổng quan, Vận hành và README. Gồm 17 nhóm Mini App và 12 module Admin, có trạng thái mock/chưa có/cần chốt. `verify:atlas` kiểm tra số nhóm và deep-link tự mở bảng Admin. `mock-review.json` ghi kiểm tra file L03 qua bốn tab và luồng đăng ký mẫu; không có request mạng ngoài được cho phép.


## Bổ sung 12/11/2026: thương mại và trình bày

- Thêm 7 Archify: merchandise, checkout, refund, reconciliation, notification-delivery, payment-data, settlement-data. Cập nhật overview/modules/commerce, tổng 26 artifact và 52 preview light/dark.
- Tất cả artifact mới/sửa qua finalize (validate, deliver, strict check, browser-check). Các thiết kế mới dẫn bản làm việc FEATURES/PLAN; ATLAS.json lưu SHA-256 cơ sở thiết kế, không gán giả cho commit baseline. Mô hình ERD logic chưa là migration/schema vật lý.
- Review độc lập nội dung và ảnh đã sửa: ma trận tài chính, T17–T21, phí provider và giới hạn effort; nhánh hủy đơn chưa thu; pending/unknown tra provider; giữ tồn chỉ nhả khi hết TTL/đã hủy; trạng thái order/payment/settlement độc lập.
- Năm slide nghiệp vụ mới dùng sơ đồ toàn chiều rộng, kết luận nằm trên hình. Ảnh thực chế độ Trình chiếu 1440×900 xác nhận title/point/preview/link đều trong viewport; kiểm tra đã đưa vào verify:presentation.
- Reviewer đã xem preview 7 sơ đồ mới, thêm dark notification, và 5 slide trình chiếu. Không còn finding material mở trong phạm vi review này. Sequence checkout và ERD để hỏi đáp tương tác/zoom; không cam kết mọi sublabel đọc rõ từ xa trên máy chiếu.
- Nội dung tiếng Việt; một số nút/chú giải mặc định của Archify vẫn tiếng Anh. Không đổi backend/app hoặc tích hợp provider trong lượt tài liệu.
- [Gợi ý trình bày](PRESENTATION-NOTES.md). [Review độc lập](PRESENTATION-REVIEW.md).

Kết quả cuối ngày 12/11: verify:docs đạt 6 viewport; verify:presentation đạt 24 tổ hợp cùng 5 kiểm tra khung trình chiếu mới; verify:atlas đạt 26 artifact/52 preview. PDF tái sinh có đúng 18 trang và đủ tiêu đề slide (kiểm tra cấu trúc/text bằng pypdf; review hình trực tiếp thực hiện trên HTML, không tuyên bố đã nhìn mọi trang PDF). Không có external request, broken link hoặc overflow trong các kiểm tra này.