R3 — Brief viết FS as-built (dùng chung cho mọi người viết)

Tác giả: lane ba/ (AI điều phối) · Ngày: 2026-09-30 · Mode: B – As-built · Commit: e77c47aDành cho: các agent viết FS song song ở bước R3, và người review sau này muốn biết quy ước. Mọi FS của project này tuân theo đúng brief này — lệch brief = lỗi.

1. Đọc trước khi viết

1. ba/.claude/skills/document-existing/SKILL.md — mục "Luật riêng của Mode B" và R3.
2. ba/.claude/skills/generate-fs/SKILL.md — Giai đoạn B, Template Conformance Check, "Quy tắc bắt buộc".
3. ba/_workflow/templates/fs/Overview.md và ba/_workflow/templates/fs/User-Story.md — cấu trúc bắt buộc.
4. ba/_workflow/checklists/document-existing.md + ba/_workflow/checklists/generate-fs.md — tự kiểm trước khi xong.
5. Inventory của nhóm mình trong thư mục này + us-backlog-r2-20260930.md (danh sách US đã confirm) + gate-r1-summary-20260930.md (câu hỏi G-01…G-10 — chưa có trả lời).
6. ../../project-decisions.md.

Nguồn Fact duy nhất về hành vi là inventory (đã qua Gate R1). Cần chi tiết hơn (field UI, text lỗi, điều kiện) → đọc code tại đúng file:dòng inventory đã trích; không đi truy vết lại từ đầu.

2. Quy ước

Mục	Quy ước
Thư mục FS	ba/projects/2026-SAPP-Works-tools/docs/fs/<folder>/ — tên ở bảng §4
File	00-overview.md + US-<mã>-<slug>.md — slug cố định ở bảng §4, không tự đặt
Doc ID	FS-SAPP-<NHÓM> (PLATFORM, HUBSPOT, 20603, 24395, 23954, 26878, 26297)
Overview metadata	Mode = B – As-built; As-built tại commit = e77c47a; Status = DRAFT; Author = AI (lane ba/); Reviewers = BA; Figma = N/A — as-built, không có Figma; Related BRD = ../../brd/brd-as-built-v0.1-20260930.md
Mã trong overview	NFR-<P/H/E/I/T/D/S>-NN, OQ-<…>-NN, DR-<…>-NN (ví dụ OQ-E-03) — mã có tiền tố nhóm để link chéo giữa FS không nhầm. Trong mỗi OQ/DR ghi mã gốc inventory (vd "inventory Q-02", "inventory DR-01")
Mã trong file US	BR-01…, màn M1…, action A1…, AC-M1.1…, EC-M1.1… — cục bộ trong US
Role	"Người dùng tool" + đánh dấu Assumption (OQ về G-01) ở US Statement; US-P03/P04 = "Admin CMS" (Fact)
"So that…"	Mục đích nghiệp vụ không suy từ code: lấy từ shared/external/sapp/** nếu có (trích nguồn), không thì ghi [Assumption]
Dependencies & DoR	N/A — đã triển khai (Mode B). Có thể liệt kê dependency runtime (env_systems key, route Ops…) nếu hữu ích
Figma frame / UI States	Không có Figma → cột Figma ghi N/A; UI States mô tả đúng màn thật theo code
Business Rules	Cột Nguồn code bắt buộc (đường/dẫn.ts:dòng). Câu Rule bằng ngôn ngữ nghiệp vụ, không tên class/biến
⚠️ Observed	Hành vi nghi bug / rủi ro (inventory đã gắn nhãn) → không viết thành BR. Mô tả ở AC/EC dạng "hành vi hiện tại" có tiền tố ⚠️ Observed, và tạo OQ ở overview §6 "cố ý hay bug?"
Ghi dữ liệu	Mỗi action ghi rõ ghi vào hệ thống nào, môi trường nào; action có đường ghi PROD → dòng cảnh báo ⚠️ Ghi PROD trong Behavior
Quyền	Không lặp chi tiết @Public() ở từng US — tham chiếu NFR-P-01 của FS nền tảng (link §5)
Dịch vụ dùng chung	Env, khoá tool, auto-login Ops, Ops passthrough, SQL runner, SAP log/quét → link sang US-P tương ứng (bảng §4), không mô tả lại
Drift	Overview §6b từ inventory §7, giữ bằng chứng hai phía
N/A	Section không áp dụng → giữ heading, ghi N/A — <lý do>. Không xoá section
Ngôn ngữ	Tiếng Việt, thuật ngữ kỹ thuật giữ tiếng Anh
HTML thô	Không viết thẻ HTML; placeholder dạng <tên> đặt trong backtick

3. Ranh giới (tuyệt đối)

• Chỉ tạo/sửa file trong thư mục FS của mình (và riêng người viết 26878-B: chỉ các file US được giao).
• Không sửa inventory, backlog, brief, overview của FS khác, file ngoài ba/projects/2026-SAPP-Works-tools/docs/fs/.
• Không chạy lệnh ghi (git, npm install, build, format). Không build site — điều phối viên build sau.
• Không Jira / Confluence / Atlassian / connector ngoài (quyết định dự án).
• Không gọi API, không chạy app.

4. Thư mục + tên file cố định (60 US)

FS nền tảng — sapp-platform-as-built-v0.1-20260930/

US	File
US-P01	US-P01-hub-mo-tool.md
US-P02	US-P02-khoa-tool.md
US-P03	US-P03-quan-tri-trang-thai-tool.md
US-P04	US-P04-cau-hinh-env-systems.md
US-P05	US-P05-sap-log-va-quet-doanh-thu.md
US-P06	US-P06-callback-sap.md
US-P07	US-P07-option-property-hubspot-dev.md
US-P08	US-P08-ops-passthrough.md
US-P09	US-P09-ops-sql-runner.md

FS HubSpot — sapp-hubspot-as-built-v0.1-20260930/

US-H01-get-property.md · US-H02-clone-property.md · US-H03-snapshot-property.md · US-H04-xem-pipeline.md · US-H05-clone-pipeline.md · US-H06-nhan-ban-pipeline.md

FS 20603 — sapp-20603-econtract-as-built-v0.1-20260930/

US-E01-kiem-tra-flow-process.md · US-E02-retry-flow-fail.md · US-E03-chia-se-ket-qua.md · US-E04-timeline-econtract.md · US-E05-thong-ke-loi.md · US-E06-danh-sach-deal-loi.md

FS 24395 — sapp-24395-as-built-v0.1-20260930/

US-I01-xem-contact-deal.md · US-I02-tao-contact.md · US-I03-tao-deal.md · US-I04-bulk-category.md · US-I05-bulk-subject.md · US-I06-bulk-product.md

FS 23954 — sapp-23954-as-built-v0.1-20260930/

US-T01-truy-van-ticket.md · US-T02-lam-moi-owner.md · US-T03-kiem-tra-thay-doi.md · US-T04-lich-su-lam-moi.md · US-T05-check-snapshot.md

FS 26878 — sapp-26878-as-built-v0.1-20260930/

US-D01-chay-flow-stepper.md · US-D02-lich-su-run-log-sap.md · US-D03-loai-buoc.md · US-D04-p1-hoc-phi-thuong.md · US-D05-p1-gia-han-bao-luu.md · US-D06-p1-cbe-cert-becker.md · US-D07-p1-chuyen-doi.md · US-D08-p1-chuyen-nhuong.md · US-D09-p2-dtth-theo-buoi.md · US-D10-p2-lop-online.md · US-D11-p2-chot-so.md · US-D12-p2-ghi-bu.md · US-D13-p2-roi-lop.md · US-D14-p2-dao-buoi.md · US-D15-p2-truong-chieu.md · US-D16-p2-dong-bo-lai.md · US-D17-p2-dong-bo-nguoc.md · US-D18-resync-va-gui-lai.md

FS 26297 — sapp-26297-as-built-v0.1-20260930/

US-S01-chay-case.md · US-S02-chuan-bi-don-du-lieu.md · US-S03-chuyen-nhuong.md · US-S04-huy-chuyen-nhuong.md · US-S05-chan-chuyen-nhuong.md · US-S06-chan-xoa-hoc-vien.md · US-S07-chan-huy-chuyen-nhuong.md · US-S08-lms-khoa-hoc.md · US-S09-hubspot-dong-bo-lai.md · US-S10-mail.md

5. Link chéo sang FS nền tảng

Từ một FS nhóm: ../sapp-platform-as-built-v0.1-20260930/US-P08-ops-passthrough.md (v.v.). NFR quyền truy cập: ../sapp-platform-as-built-v0.1-20260930/00-overview.md mục NFR-P-01. Người viết FS nền tảng phải đặt đúng mã NFR-P-01 = "Toàn bộ API /api/v1/sapp/* là @Public()".

6. Khi xong

• Chạy Template Conformance Check (bảng "US file | Section thiếu | Trạng thái") và đặt nó ở cuối 00-overview.md mục "Template Conformance Check" — mọi dòng ✅.
• US Index trong overview: Status = Draft (as-built chờ Gate R2).
• Báo cáo ≤ 250 từ: số file, số BR / AC, số OQ / DR / NFR, US nào còn chỗ Assumption lớn.