@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/docs/02-guides/developer/scenarios.md

@@ -1,460 +0,0 @@
-[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › Tình huống thực tế
-
-# Tình Huống Thực Tế
-
-- [1. Nhận PRD + BDD mới và bắt đầu work](#tình-huống-1-nhận-prd--bdd-mới-và-bắt-đầu-work)
-- [2. Đọc và hiểu System BDD (BE dev)](#tình-huống-2-đọc-và-hiểu-system-bdd-be-dev)
-- [3. Đọc Web/App BDD (FE/App dev)](#tình-huống-3-đọc-webapp-bdd-feapp-dev)
-- [4. PRD thay đổi mid-sprint](#tình-huống-4-prd-thay-đổi-mid-sprint)
-- [4b. Chờ API design — BE + FE/App đồng thuận](#tình-huống-4b-chờ-api-design--be--feapp-đồng-thuận)
-- [5. Nhận bug report từ Tester](#tình-huống-5-nhận-bug-report-từ-tester)
-- [6. Nhận Design Spec + BDD từ PO (FE/App)](#tình-huống-6-nhận-design-spec--bdd-từ-po-feapp)
-- [7b. Brownfield — API đã tồn tại](#tình-huống-7b-brownfield--api-đã-tồn-tại-trên-hệ-thống-cũ)
-- [7. Setup service submodule (Umbrella)](#tình-huống-7-setup-service-submodule-umbrella-mode)
-- [8. Validate traces trước khi tạo PR lớn](#tình-huống-8-validate-traces-trước-khi-tạo-pr-lớn)
-
-## Tình huống 1: Nhận PRD + BDD mới và bắt đầu work
-
-**Bối cảnh:** PO thông báo PRD `FT-042-checkout.md` và BDD đã approved, sẵn sàng implement.
-```
-1. git submodule update --remote my-project-specs
-   (lấy PRD + BDD mới nhất từ PO)
-
-2. /review-context my-project-specs/specs/payment/checkout/{TICKET-ID}-checkout.md
-   → Kiểm tra Status = approved (bảng Metadata PRD; không code khi còn draft)
-   → Đọc kỹ AC, UC, BR
-
-3. Đọc BDD tương ứng theo platform của mình:
-   FE/Web:  my-project-specs/specs/payment/checkout/bdd/web/FT-042-UC*.feature
-   App:     my-project-specs/specs/payment/checkout/bdd/app/FT-042-UC*.feature
-   BE:      my-project-specs/specs/payment/checkout/bdd/system/FT-042-UC*.feature
-
-4. Nếu có thắc mắc về PRD hoặc BDD → hỏi PO ngay, không tự suy diễn
-   Ví dụ: "BR5 trong System BDD nói 'kiểm tra giới hạn thanh toán' — limit này
-           có khác nhau theo tier user không? BDD không chỉ rõ."
-
-5. Bắt đầu: /generate-tech-docs dựa trên BDD
-```
-**Lưu ý:** Nếu `/review-context` báo P0 warning (domain không match config) → **dừng lại**, báo PO/DevOps fix config trước.
-
-## Tình huống 2: Đọc và hiểu System BDD (BE dev)
-
-**Bối cảnh:** BE dev nhận thông báo BDD đã sẵn sàng tại `specs/auth/login/bdd/system/`.
-
-**System BDD tập trung vào:** API contracts được tổng hợp từ FE + App BDD · Business rule enforcement tại system level · Data contracts (request/response shape) · Cross-platform consistency.
-```
-# Đọc file BDD (không generate):
-my-project-specs/specs/auth/login/bdd/system/FT-001-UC1-login-system.feature
-```
-```gherkin
-# Ví dụ System BDD do PO gen (tổng hợp từ web + app BDD)
-Feature: User Authentication — System Contract
-  # @trace.prd: FT-001
-  # @trace.platform: system
-
-  Scenario: Successful login returns token and profile
-    Given a registered user with valid credentials
-    When the system receives a login request
-    Then the system returns an auth token
-    And the system returns the user profile
-    And the session is valid for 3600 seconds
-
-  Scenario: Account locked after 5 failed attempts
-    Given a user with 4 failed login attempts
-    When the system receives a 5th failed login
-    Then the system locks the account for 30 minutes
-    And the system signals the locked state with remaining time
-```
-BE dev dùng System BDD để: thiết kế API endpoint + response schema (`/generate-tech-docs`) · generate code skeleton (`/generate-code`) · viết integration tests (`/dev-gen-test`).
-
-> **Đọc annotation `@system.resolution:` ở header (nếu có).** Khi web & app kỳ vọng response khác nhau, PO đã chốt cách giải quyết lúc gen System BDD — build contract đúng kiểu đó, **đừng tự đổi**:
-> - `union` → trả tất cả field cho mọi client (`{ token, redirect_url, user_profile }`).
-> - `platform-hint` → đọc header `X-Platform: web|app`, tailor response (System BDD dùng `Scenario Outline` + Examples).
-> - `separate-endpoints` → mỗi platform một endpoint (`/auth/login/web` · `/auth/login/app`).
->
-> Thấy resolution bất hợp lý, hoặc cần field chưa có trong contract → phản hồi PO (contract decision), đừng sửa System BDD trực tiếp. Bối cảnh: [PO › Tình huống 12](../product-owner/scenarios.md#tình-huống-12--system-bdd-synthesis-outside-in--xử-lý-cross-platform-conflict).
-
-## Tình huống 3: Đọc Web/App BDD (FE/App dev)
-
-**Bối cảnh:** FE dev nhận thông báo BDD web đã sẵn sàng tại `specs/auth/login/bdd/web/`.
-```
-# Đọc file BDD (không generate):
-my-project-specs/specs/auth/login/bdd/web/FT-001-UC1-login-web.feature
-```
-```gherkin
-# Ví dụ Web BDD do PO gen (vocabulary: clicks, sees, navigates)
-Scenario: User sees error after wrong password
-  Given user is on the Login screen
-  When user submits login with wrong password
-  Then user sees "Sai mật khẩu" error
-  And the password field is cleared
-
-Scenario: Account locked — countdown shown
-  Given user has submitted wrong password 5 times
-  Then user sees "Tài khoản bị khoá. Thử lại sau 29:45"
-  And the countdown decrements every second
-```
-FE dev dùng Web BDD để:
-1. Thiết kế component spec + API integration plan (`/generate-tech-docs`)
-2. Gen UI + mock adapter (`/generate-code --phase=ui`) — mock **shape** từ BE contract nếu có, else System BDD + warn → Mock adapter trả về fixture data đúng với BDD `Then` clauses → Tester test toàn bộ FE flow ngay, không cần chờ BE
-3. [Trong khi đó — tham gia review API contract, sign-off T7 gate]
-4. Khi sign-off done → wire real API (`/generate-code --phase=integration`)
-5. Viết E2E tests với Playwright/Cypress (`/dev-gen-test`)
-
-## Tình huống 4: PRD thay đổi mid-sprint
-
-**Bối cảnh:** PO update PRD `FT-042` từ v1.0 → v1.1 khi dev đang code.
-```
-PO notify: "FT-042 updated — BR7 thay đổi giới hạn từ 5tr → 10tr"
-        │
-        ▼
-Dev chạy:
-/review-context specs/payment/checkout/{TICKET-ID}-checkout.md
-→ Xem diff từ v1.0 sang v1.1 (agent highlight thay đổi)
-        │
-        ▼
-Đánh giá impact:
-- BDD bị ảnh hưởng? → thông báo PO để PO update BDD trong spec repo, rồi pull lại
-- Tech Docs bị ảnh hưởng? → update API spec
-- Code bị ảnh hưởng? → update logic + tests
-        │
-        ▼
-/validate-traces
-→ Đảm bảo không có trace nào còn trỏ về spec cũ
-```
-**Nguyên tắc:** Không merge code khi traces broken. Fix traces trước.
-
-## Tình huống 4b: Chờ API design — BE + FE/App đồng thuận
-
-**Bối cảnh:** System BDD đã gen, BE dev bắt đầu `/generate-tech-docs` nhưng FE/App chưa confirm API contract. **Trạng thái tech docs trong thời gian này:** `@trace.status: in-review`.
-```
-BE dev: /generate-tech-docs auth/bdd/system/FT-001-UC1.feature   # trỏ System BDD → phần backend
-# Umbrella mode (có spec_source): output nằm trong SPEC REPO chung
-→ Output: free-trial-specs/specs/auth/login/tech-docs/FT-001-tech-design.md   (1 doc/PRD)
-# Single-service (không có spec_source): output nằm tại project root
-→ Output: specs/auth/login/tech-docs/FT-001-tech-design.md
-→ @trace.status: draft
-→ @trace.sign_off: { be_team: done, fe_team: pending, app_team: pending, sa: pending }
-→ Publish: commit + push file lên spec repo (2-layer) để FE/App `/sync` đọc được
-
-BE dev: /review-tech-docs free-trial-specs/specs/auth/login/tech-docs/FT-001-tech-design.md
-→ Chạy T1–T7 (bao gồm T7 cross-team contract check)
-→ Report: "Sign-off gate: 🔒 BLOCKED — pending: fe_team, app_team, sa"
-```
-**FE dev review API contract:**
-```
-# FE dev mở tech-design file → xem API contract section
-# Xác nhận: response fields có đủ cho web BDD expectations không?
-# Nếu ok → thêm comment hoặc báo BE dev cập nhật sign_off
-```
-Khi FE/App confirm xong → BE dev update header:
-```yaml
-# @trace.sign_off:
-#   be_team:  done
-#   fe_team:  done    ← FE đã confirm
-#   app_team: done    ← App đã confirm
-#   sa:       done    ← SA đã approve
-```
-```
-BE dev: /review-tech-docs --resume {tech-design-file}
-→ Sign-off gate: ✅ READY
-→ @trace.status: approved
-→ BE có thể chạy /generate-code
-→ FE chạy /generate-code --phase=integration để wire API thật
-```
-```
-# FE — sau khi sign-off gate approved:
-/generate-code --phase=integration auth/FT-001-UC1
-→ Reads existing mock adapter interface ({UC-ID}ApiPort)
-→ Generates real API adapter với calls đến endpoints trong tech-doc
-→ Flips DI/env flag: service dùng real adapter thay mock
-→ Mock adapter giữ lại cho unit test
-```
-**Nguyên tắc:**
-- `/generate-code` (không phase flag) cho BE trả về warning nếu tech docs status là `in-review` hoặc `draft`.
-- FE dùng `--phase=ui` được ngay sau khi đọc BDD — không cần chờ.
-- FE dùng `--phase=integration` chỉ sau khi sign-off gate `approved`.
-
-## Tình huống 5: Nhận bug report từ Tester
-
-**Bối cảnh:** Tester gửi bug report theo đúng format spec-driven, có đầy đủ spec context.
-```
-Bug ID   : BUG-20260605-003
-Feature  : FT-001 — User Login
-Service  : BE
-Severity : Major
-
-Spec context:
-  PRD      : specs/auth/login/{TICKET-ID}-login.md (v1.0)
-  BDD      : free-trial-specs/specs/auth/login/bdd/system/FT-001-login.feature
-             → Scenario: "Lock account after 5 failed attempts"
-  Tech Doc : free-trial-specs/specs/auth/login/tech-docs/FT-001-auth-api.md
-
-AC bị vi phạm:
-  AC3: "Sai password 5 lần liên tiếp → khoá tài khoản 30 phút"
-
-BDD Scenario bị fail:
-  Given : user has 0 failed attempts
-  When  : login with wrong password 5 times
-  Then  : 5th attempt returns 423 Locked AND retry_after = 1800
-
-Actual: 5th attempt trả 401, không có retry_after, tài khoản không bị khoá
-```
-
-**Bước 1 — Tìm code implement scenario bị fail:**
-```
-Đọc theo thứ tự: PRD → BDD → Code
-
-PRD AC3: "5 lần sai → khoá 30 phút"          → rõ ràng ✅
-BDD SC3: "Then 423 Locked, retry_after=1800"  → đúng theo PRD ✅
-Code: ???                                      → kiểm tra tiếp
-```
-Chạy:
-```
-/fix-bug "BUG-20260605-003: FT-001-UC2-BR3 — account not locked after 5 failures
-  PRD: specs/auth/login/{TICKET-ID}-login.md
-  BDD: free-trial-specs/specs/auth/login/bdd/system/FT-001-login.feature"
-```
-Agent sẽ: đọc BDD scenario được chỉ định · tìm code implement scenario đó (theo `@trace.bdd`) · so sánh logic thực tế vs spec · propose fix có giải thích.
-
-**Bước 2 — Xác định bug thuộc layer nào:** Đọc theo thứ tự PRD → BDD → Code để tìm chỗ lệch. Có 3 khả năng:
-
-| PRD | BDD | Code | → Fix ở đâu |
-|---|---|---|---|
-| ✅ rõ | ✅ đúng | ❌ sai | Fix code |
-| ✅ rõ | ❌ sai | ❌ sai | Fix BDD + code |
-| ❌ mơ hồ | bất kỳ | bất kỳ | Hỏi PO trước, không tự fix |
-
-> Flow đầy đủ cho cả 6 cases (bao gồm PRD change, Design Spec bug, env bug) và cách phối hợp với PO/Tester: xem [Operations › Bug Flow](../../04-operations/bug-flow.md).
-
-**Bước 3 — Sau khi fix:**
-```
-/validate-traces
-→ Đảm bảo @trace.bdd trong code vẫn trỏ đúng BDD scenario
-→ Không có trace broken
-
-/dev-run-test
-→ BDD pass = fix đúng theo spec
-
-Notify tester:
-  "BUG-20260605-003 fixed — deploy to staging [link commit/PR]
-   Root cause: Case A — code dùng > thay vì >=
-   BDD: không đổi (spec đã đúng)
-   Re-test: FT-001-UC2-SC3"
-```
-
-## Tình huống 6: Nhận Design Spec + BDD từ PO (FE/App)
-
-**Bối cảnh:** PO tạo Design Spec + BDD web cho tính năng checkout — FE cần implement.
-```
-PO thông báo: "FT-042 Design Spec + BDD đã sẵn sàng"
-        │
-        ▼
-git submodule update --remote my-project-specs
-
-FE dev đọc:
-- my-project-specs/specs/payment/checkout/{TICKET-ID}-checkout.md                   (business rules)
-- my-project-specs/specs/payment/checkout/design-spec/FT-042-*.md  (screens, components)
-- my-project-specs/specs/payment/checkout/bdd/web/FT-042-UC*.feature  (BDD đã gen sẵn)
-        │
-        ▼
-Bật Figma Dev Mode MCP (nếu dùng Figma — để FE codegen chính xác):
-→ Mở Figma DESKTOP app + enable Dev Mode MCP server (local, http://127.0.0.1:3845)
-→ `/generate-code` (FE/App UI) tự detect server local + prompt nếu chưa bật
-→ Dùng real tokens, components, Code Connect thay vì web link → codegen sát design hơn
-        │
-        ▼
-/generate-tech-docs payment/FT-042-UC1
-→ Gen component spec, API integration plan dựa trên Design Spec + BDD
-        │
-        ▼
-/generate-code payment/FT-042-UC1 --phase=ui
-→ Gen UI components + mock API adapter (fixture từ System BDD Then clauses)
-→ FE codegen đọc Figma Dev Mode MCP local nếu đang bật (tokens/components/Code Connect)
-→ Tester có thể test FE ngay
-        │  [trong khi đó: tham gia review API contract — T7 sign-off gate]
-        ▼
-[Nhận thông báo: sign-off gate approved]
-        │
-        ▼
-/generate-code payment/FT-042-UC1 --phase=integration
-→ Wire real API adapter thay thế mock
-→ /dev-gen-test payment/FT-042-UC1
-→ /review-code {files-changed}
-→ /dev-run-test
-```
-**Lưu ý:** BE không cần đọc Design Spec — chỉ đọc System BDD tại `specs/{domain}/{prd-slug}/bdd/system/`.
-
-## Tình huống 7b: Brownfield — API đã tồn tại trên hệ thống cũ
-
-**Bối cảnh:** PO viết PRD cho feature mới nhưng BE API đã có sẵn trên hệ thống cũ, chưa có tài liệu. PO khai báo luôn trong PRD thay vì thiết kế lại.
-
-**Dấu hiệu nhận ra:** PRD Metadata có `| **API Source** | existing |` · PRD có section "Existing API Contract" với bảng endpoint + response.
-
-**Dev workflow (đơn giản hơn greenfield):**
-```
-git submodule update --remote my-project-specs
-
-1. /review-context → đọc PRD + BDD
-   → BDD system đã dùng contract sẵn có từ PRD (không synthesis)
-   → @trace.api_source: existing trong BDD header
-
-2. /generate-tech-docs {feature-file}
-   → Mode: Reverse-document
-   → §2 API Endpoints: mô tả lại API đã tồn tại từ bảng PRD
-   → Ghi chú gaps nếu contract thực tế khác BDD expectations
-
-3. /review-tech-docs {tech-design-file}
-   → T7 sign-off gate: tự động SKIP (không có API design mới)
-   → Chỉ review T1–T6 (architecture, entity, BDD traceability, ...)
-   → Approved nhanh hơn
-
-4. /generate-code {feature-file}   ← không cần --phase
-   → API đã live, gen real adapter trực tiếp
-```
-
-**Điểm khác biệt so với greenfield:**
-
-| | Greenfield | Brownfield (API existing) |
-|---|---|---|
-| System BDD | Synthesize từ FE + App BDD | Dùng PRD contract trực tiếp |
-| T7 gate | Bắt buộc | Tự động skip |
-| `--phase=ui` | Cần nếu BE chưa ready | Không cần |
-| `generate-tech-docs` | Design mới | Reverse-document |
-
-## Tình huống 7: Setup service submodule (Umbrella mode)
-
-**Bối cảnh:** Project dùng umbrella repo. Dev được assign vào service `mass-product-be`.
-
-**Setup lần đầu:**
-```bash
-# 1. Clone umbrella repo
-git clone {umbrella-repo-url} mass-product
-cd mass-product
-
-# 2. Mở Claude Code TẠI umbrella root (QUAN TRỌNG)
-code .   ← hoặc claude .
-
-# 3. Chạy một lệnh duy nhất — setup toàn bộ
-/sync
-# → tự detect setup mode (submodule chưa init)
-# → git pull + git submodule update --init --recursive --remote
-# → validate service configs (cảnh báo nếu thiếu .agent/project-context.yaml)
-# → sync Living Docs panel
-
-# 4. Framework tự detect umbrella mode từ project-context.yaml
-# Khi chạy /review-context với PRD có Domain: be (bảng Metadata)
-# → CODE route tới mass-product-be/  ·  BDD đọc từ spec repo mass-product-spec/specs/{domain}/{prd-slug}/bdd/ (spec_source set)
-```
-
-**Update hằng ngày — cũng chỉ 1 lệnh:**
-```bash
-/sync
-# → git pull + submodule update --remote
-# → refresh Living Docs
-```
-
-**project-context.yaml của umbrella:**
-```yaml
-setup:
-  mode: umbrella
-  spec_source: "mass-product-spec"
-services:
-  be:
-    path: "mass-product-be"
-    module: "NestJS"
-    # specs_dir KHÔNG khai khi spec_source set — BDD đọc từ spec repo, không per-service
-  web:
-    path: "mass-product-web"
-    module: "NextJS"
-```
-
-> **BDD (specs_dir):** không khai trong `services` khi có `spec_source`. Tất cả BDD (web/app/system) nằm ở `{spec_source}/specs/bdd` (vd `mass-product-spec/specs/bdd`) — context-loader tự route `specs_dir` về đó; mọi `specs_dir` per-service đều bị **bỏ qua**. Per-service `specs_dir` **chỉ** dùng khi KHÔNG có `spec_source`.
->
-> **Tech-docs (API contract):** không khai trong `services`. Khi `setup.spec_source` được set, BE tech-design (API contract) **LUÔN** nằm tại `{spec_source}/specs/tech-docs` (vd `mass-product-spec/specs/tech-docs`) — context-loader tự route `tech_docs_dir` về đó. BE generate xong → commit + push lên spec repo; FE/App đọc qua `/sync` + `/generate-code --phase=integration`. Per-service tech-docs **chỉ** khi KHÔNG có `spec_source`.
->
-> **Bắt buộc:** Mỗi service submodule cũng cần file `.agent/project-context.yaml` riêng. Framework đọc file này (context-loader Step 1.6) để lấy đúng `test_command` và `build_command` khi `/dev-run-test` hoặc `/dev-gen-test` chạy từ umbrella root.
-
-**project-context.yaml của từng service submodule:**
-```yaml
-# mass-product-be/.agent/project-context.yaml
-tech_stack:
-  language: "TypeScript"
-  framework: "NestJS"
-  module: "nestjs"
-
-conventions:
-  test_command: "npm test"
-  build_command: "npm run build"
-
-paths:
-  trace_dir: ".trace"
-```
-```yaml
-# mass-product-web/.agent/project-context.yaml
-tech_stack:
-  language: "TypeScript"
-  framework: "Next.js 14"
-  module: "nextjs"
-
-conventions:
-  test_command: "npx vitest run"
-  build_command: "npm run build"
-
-paths:
-  trace_dir: ".trace"
-```
-
-Khi `/dev-run-test` chạy từ umbrella root cho một UC thuộc domain `be`:
-1. Step 1.5 detect `service_root = "mass-product-be"`
-2. Step 1.6 load `mass-product-be/.agent/project-context.yaml` → `test_command = "npm test"`
-3. Lệnh test chạy: `cd mass-product-be && npm test`
-
-**BDD + trace ở spec repo (1 tầng); code ở service (2 tầng):**
-```bash
-# BDD (.feature) + trace (.tsv) → SPEC repo (1 tầng — khi spec_source set)
-cd mass-product-specs
-git add specs/auth/login/bdd/FT-001-login.feature .trace/auth/login/FT-001.tsv
-git commit -m "feat(bdd): add login BDD scenarios — FT-001"
-git push
-
-# Code → service submodule (commit 2 lớp)
-cd ../mass-product-be
-git add src/
-git commit -m "feat(FT-001): login implementation"
-git push origin feature/ft-001-login
-cd ..   ← về umbrella root
-git add mass-product-be
-git commit -m "chore: update mass-product-be submodule pointer — FT-001"
-git push
-```
-**Không commit lớp 2 (pointer) → umbrella repo vẫn trỏ về commit cũ của service.**
-
-## Tình huống 8: Validate traces trước khi tạo PR lớn
-
-**Bối cảnh:** Dev refactor module Auth — đổi tên `AuthService` → `IdentityService`.
-```
-Sau khi refactor xong:
-
-/validate-traces
-        │
-        ▼
-Agent kiểm tra:
-- BDD có @trace.module: AuthService → BROKEN (class không còn tồn tại)
-- Code comments @trace.bdd: FT-001-UC1-SC1 → còn hợp lệ không?
-- Tech Docs mention "AuthService" → stale reference
-        │
-        ▼
-Report:
-  ❌ BROKEN  specs/auth/login/bdd/FT-001-login.feature  @trace.module: AuthService (not found)
-  ❌ BROKEN  specs/auth/login/tech-docs/FT-001-auth-api.md  "AuthService" referenced 7 times
-  ✅ OK      src/identity/identity.service.ts  @trace.bdd: FT-001-UC1-SC1
-        │
-        ▼
-Fix: Update @trace.module và references → re-run /validate-traces → all green → tạo PR
-```
-**Quy tắc:** PR không được merge khi còn broken traces.
-
----
-
-← [Workflow](workflow.md) · Tiếp theo: [Checklist trước khi tạo PR](pr-checklist.md)

package/docs/02-guides/developer/workflow.md

@@ -1,121 +0,0 @@
-[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › Workflow
-
-# Workflow Cơ Bản
-
-> Sơ đồ render thành flowchart trên GitHub (Mermaid). Bản text ASCII (mở mục bên dưới) là fallback cho viewer không hỗ trợ Mermaid.
-
-```mermaid
-flowchart TD
-    A([Nhận PRD + BDD mới từ PO]) --> B["/sync<br/>kéo specs + services · refresh Living Docs"]
-    B --> C["/review-context {prd}<br/>kiểm tra domain · status=approved<br/>đọc AC / UC / BR + BDD"]
-    C --> D["Đọc BDD web/app/system từ spec repo<br/>(dev KHÔNG tự generate BDD)"]
-    D --> TD
-
-    subgraph TD["TECH DESIGN + CODE — BE và FE làm SONG SONG"]
-      direction LR
-      subgraph BE["BE track (system) — trỏ System BDD → §4 API contract"]
-        direction TB
-        BE1["/generate-tech-docs {system}<br/>§4 API contract ← System BDD<br/>endpoint · data model · DB"] --> BE2["/review-tech-docs → approved<br/>§4 = API contract<br/>(client §4.5 map theo)"] --> BE3["/generate-code {system}<br/>code BE ← System BDD + §4"]
-      end
-      subgraph FE["FE/App track (web · app) — không chờ BE deploy"]
-        direction TB
-        FE1["① /generate-code {bdd} --phase=ui<br/>UI ← Web/App BDD + Design Spec<br/>mock ← §4 API contract (nếu có) · else System BDD<br/>emit test-id · Tester test ngay"] --> GATE{{"GATE — làm tiếp khi tech-doc<br/>đã có §4 API contract (approved)"}}
-        GATE --> FE2["② /generate-tech-docs {web|app}<br/>append §4.5 client ← Web/App BDD<br/>§4.5.4 map API · §4.5.6 test-id"] --> FE2b["/review-tech-docs → approved<br/>(bump revision)"] --> FE3["③ /generate-code --phase=integration<br/>thay mock bằng API thật theo §4.5.4"]
-      end
-      BE2 -. "§4 API contract" .-> GATE
-    end
-
-    TD --> E["/dev-gen-test → /dev-run-test<br/>dev tự kiểm (dev_selftest)<br/>ghi vào spec .trace"]
-    E --> F["/validate-traces<br/>cập nhật Living Docs (.living-docs)"]
-    F --> G["/review-code — 4 lăng kính:<br/>Traceability · Layer · Coding Standards · Spec Compliance"]
-    G --> H([Tạo PR → notify PO/SA review])
-```
-
-> **Full-stack / không tách mock:** chỉ cần BE track — chạy `/generate-code {bdd}` một lần (bỏ qua FE 2-phase).
-
-<details>
-<summary>Bản text (ASCII fallback — cho viewer không render Mermaid)</summary>
-
-```
-Nhận thông báo PRD + BDD mới từ PO
-        │
-        ▼
-/sync                                          # pull specs + services + refresh Living Docs (1 lệnh, preferred)
-(tương đương raw: git submodule update --remote my-project-specs — lấy spec mới nhất, gồm BDD PO đã gen)
-        │
-        ▼
-/review-context {prd-file}
-→ Kiểm tra Domain, Status = approved (bảng Metadata PRD)
-→ Đọc hiểu AC, UC, BR trong PRD
-→ Đọc BDD tương ứng trong specs/{domain}/{prd-slug}/bdd/{platform}/
-→ Nếu có gì không rõ: hỏi PO TRƯỚC khi tiếp tục
-        │
-        ▼
-(Đọc BDD từ spec submodule — KHÔNG tự generate BDD)
-FE/Web:  my-project-specs/specs/{domain}/{prd-slug}/bdd/web/{TICKET-ID}-UC*.feature
-App:     my-project-specs/specs/{domain}/{prd-slug}/bdd/app/{TICKET-ID}-UC*.feature
-BE:      my-project-specs/specs/{domain}/{prd-slug}/bdd/system/{TICKET-ID}-UC*.feature
-        │
-        ▼
-══════════ TECH DESIGN + CODE — BE track & FE track CHẠY SONG SONG ══════════
-(/generate-tech-docs là platform-aware: đọc @trace.platform → BE = API contract · FE/App = client design)
-
-BE track (system)   ── trỏ System BDD → §4 API contract ──
-  /generate-tech-docs {system}   → §4: endpoints · data model · DB · caching
-  /review-tech-docs → APPROVED   → §4 = API contract mà client §4.5 map theo
-  /generate-code {system}        → code theo BDD (@trace.bdd)
-  (full-stack / không tách mock: chỉ cần track này — /generate-code {bdd} một lần)
-
-
-FE/App track (web|app)   ── KHÔNG chặn chờ BE ──
-
-  ① BẮT ĐẦU NGAY (song song với BE):
-     /generate-code {bdd} --phase=ui      → UI + mock adapter
-        • UI ← Web/App BDD + Design Spec
-        • mock shape = §4 API contract nếu có, else System BDD (+warn)
-        • fixture values: LUÔN từ System BDD
-        • emit test-id (convention {uc}-{screen}-{element}-{type})
-        • Tester test FE NGAY (không cần BE deploy API)
-                            │
-        ╔═══════════════════▼═══════════ GATE ═══════════════════
-        ║  Làm tiếp khi tech-doc đã có §4 API contract (approved)
-        ╚═══════════════════╤════════════════════════════════════
-                            ▼
-     ② /generate-tech-docs {web|app}      → append §4.5 client vào tech-doc gộp
-          • components · state
-          • §4.5.4 API-integration map THEO §4.1 endpoints
-          • §4.5.6 Test Selectors (test-id cho element có action)
-        /review-tech-docs → approved (bump revision)
-                            ▼
-     ③ /generate-code {bdd} --phase=integration
-          → wire real API theo §4.5.4 tech-doc gộp (thay mock)
-        │
-        ▼
-/dev-gen-test {bdd-file}
-→ Gen unit test (dev self-check, không phải coverage chính thức)
-→ /dev-run-test để verify → ghi dev_selftest (pass/fail) + dev_selftest_at vào TSV authoritative {spec_source}/.trace (commit 1 tầng ở spec repo)
-→ /validate-traces (hoặc /sync) → regenerate report Living Docs {spec_source}/.living-docs/ (gitignored)
-        │
-        ▼
-/review-code {files}
-→ 4 lăng kính: Traceability / Layer Architecture / Coding Standards / Spec Compliance
-→ Fix issues trước khi tạo PR
-        │
-        ▼
-Tạo PR → notify PO/SA review
-```
-
-</details>
-
-> **Vì sao đúng thứ tự này? — Chuỗi outside-in.** Toàn bộ pipeline đi từ ngoài (client) vào trong (hệ thống):
-> 1. **PO gen BDD: web → app → System** — System BDD (BE) được **tổng hợp từ web+app BDD** (hành vi client định nghĩa trước, BE/system suy ra để phục vụ các flow đó). *(Project chỉ-BE: System BDD gen thẳng từ PRD.)*
-> 2. **BE tech-docs trước** — API contract dẫn xuất từ **System BDD**.
-> 3. **§4.5 client sau** — trỏ vào Web/App BDD → append §4.5 vào cùng doc; §4.5.4 map theo §4.1 endpoints (nên có §4 approved trước để khỏi rework).
->
-> FE **không** bị chặn chờ BE nhờ `--phase=ui` (mock shape: §4 API contract nếu có, else System BDD), rồi `--phase=integration` wire API thật khi §4.5.4 đã có. Chi tiết flow: [Concepts › Pipeline](../../03-concepts/pipeline.md).
-
-> **Commit ở đâu, push mấy tầng?** Code nằm trong service submodule → **commit 2 tầng** (service rồi umbrella pointer). Tech-docs + `.trace/` (dev_selftest/qc_status) đẩy lên **spec repo** (1 tầng, cross-repo). Sơ đồ git đầy đủ theo từng role: [Sync & Update — Git flow theo role](../../04-operations/sync-and-update.md#ai-commit-vào-repo-nào-git-flow-theo-role).
-
----
-
-← [BDD & Trace System](bdd-and-trace.md) · Tiếp theo: [Tình huống thực tế](scenarios.md)

package/docs/02-guides/prd-input-checklist.md

@@ -1,94 +0,0 @@
-[📚 Docs](../README.md) › [Guides](README.md) › Checklist Input PRD
-
-# Checklist Input PRD — Để PRD Chuẩn Ngay Lần Đầu
-
-> Muốn `/generate-prd` ra PRD tốt **ngay lần đầu**, đừng trông vào `/refine-prd` để vá — hãy chuẩn bị đúng đầu vào trước.
-
-## Hiểu trước cho đúng
-
-- **PRD sinh ra từ một file khảo sát (product-definition)** — output của `/define-product`. Bạn **không gõ thẳng** PRD.
-- **Không có "generate-prd cho BE" riêng.** PRD là tài liệu nghiệp vụ **dùng chung cho mọi platform** (một bản phục vụ cả FE/App/BE). Cái "system/BE" chỉ xuất hiện ở bước sau (`/generate-bdd`).
-- Vì vậy "PRD chuẩn ngay lần đầu" = **chuẩn bị tốt 7 thứ dưới đây trước khi chạy `/generate-prd`**.
-
----
-
-## 7 câu tự hỏi trước khi bấm `/generate-prd`
-
-**1. Bản khảo sát đã làm xong chưa?**
-Đã chạy `/define-product` đi hết 7 bước, không bỏ dở. Máy sẽ **không cho** sinh PRD nếu còn dang dở.
-→ *Vì PRD là tài liệu để ký duyệt — không dựng từ thứ chưa chốt.*
-
-**2. "Luật" và "cách xử lý" của tính năng đã viết rõ chưa?** *(quan trọng nhất)*
-Hệ thống **phải làm gì / không được làm gì** (Business Rules), và **xử lý ra sao** trong từng trường hợp (Business Logic). Viết cụ thể, đừng để câu chung chung kiểu "xử lý hợp lý".
-→ *Đây là phần dev dựa vào để code. Mơ hồ ở đây = code sai ở đó.*
-
-**3. Đã liệt kê các trường hợp hỏng chưa?**
-Không chỉ lúc chạy ngon, mà cả lúc lỗi: thiếu dữ liệu, điều kiện không thoả, hai người bấm cùng lúc, service khác chết.
-→ *Hệ thống sống nhờ xử lý đúng mấy ca lỗi này; quên là lỗ hổng.*
-
-**4. Tính năng này cần gì từ service/đội khác không?**
-Ghi rõ: **cần dữ liệu/khả năng gì, lấy từ ai, để làm gì**. Nếu không cần thì ghi "Không có".
-→ *Tính năng hiếm khi đứng một mình; thiếu mục này dễ tắc giữa chừng.*
-
-**5. API của tính năng thuộc loại nào? — phải quyết trước**
-Chọn 1 trong 3:
-- **Đã có sẵn** (API chạy production rồi) → **đưa đường dẫn tới tài liệu API thật** (file swagger/openapi, link, hoặc thư mục code BE) **mà máy mở được**. Mở không được → PRD sẽ ghi "còn thiếu", chưa chuẩn.
-- **Tự làm mới** → để trống, thiết kế sau ở `/generate-tech-docs`.
-- **Đối tác đang làm song song** → chọn loại này (đừng chọn "đã có sẵn").
-→ *Đây là chỗ quyết định độ chuẩn nhiều nhất cho tính năng BE.*
-
-**6. Mỗi tiêu chí nghiệm thu (AC) có kiểm được đúng/sai rõ ràng không?**
-Tránh kiểu "nhanh", "ổn". Phải đo được.
-→ *AC mơ hồ thì sau này không ai biết tính năng "đạt" hay "chưa".*
-
-**7. Tên gọi và dữ liệu đã dùng đúng từ điển chung chưa?**
-Đảm bảo `business-dictionary.md` (từ chuẩn) và `core-entities.md` (danh sách thực thể/trường dữ liệu) đã cập nhật cho tính năng này.
-→ *Gọi sai tên một bảng/trường là lệch cả chuỗi sau.*
-
----
-
-## Checklist nhanh
-
-- [ ] Khảo sát `/define-product` đã xong (7 bước, không gap)
-- [ ] Business Rules + cách xử lý viết rõ, không mơ hồ *(đòn bẩy lớn nhất)*
-- [ ] Đã liệt kê đủ các ca lỗi / trường hợp hỏng
-- [ ] Phụ thuộc service/đội khác ghi rõ (hoặc "Không có")
-- [ ] Đã quyết **loại API**; nếu "đã có sẵn" → đường dẫn contract **mở được**
-- [ ] Mỗi AC kiểm được đúng/sai rõ ràng
-- [ ] Từ điển chung + danh sách thực thể đã cập nhật
-- [ ] Định danh đúng: Domain (khớp cấu hình service), PO, mã Ticket
-
----
-
-## Riêng tính năng BE — chú ý nhất ở đâu?
-
-BE không có Design Spec / màn hình đỡ phía trước, nên **PRD chính là spec**. Hai thứ quyết định độ chuẩn:
-
-1. **Business Rules + Business Logic (câu 2)** — vì BE đọc PRD thẳng rồi sinh System BDD từ đây.
-2. **Loại API (câu 5)** — BE "đã có sẵn" mà đường dẫn contract mở không được thì PRD sẽ kẹt ở trạng thái "còn thiếu".
-
-> Tính năng BE thuần **không có màn hình** → phần Wireframe để trống/N/A là đúng; đừng để máy bịa màn hình.
-
----
-
-## Sau khi sinh PRD
-
-`/refine-prd` và `/review-context` là để **nhặt sạn** (làm rõ, bắt mâu thuẫn, thêm edge case) — **không phải** để vá cái thiếu từ khâu khảo sát. Chuẩn bị tốt 7 thứ trên thì hai bước này nhẹ tênh.
-
----
-
-## Map sang các bước của `/define-product` *(cho ai muốn chính xác)*
-
-| Câu hỏi | Nằm ở bước nào của discovery |
-|---|---|
-| 1. Khảo sát xong | toàn bộ Phase 1–7, `Status: completed` |
-| 2. Luật + cách xử lý | Phase 4 (Business Rules) + Phase 5 (Business Logic) |
-| 3. Ca lỗi | Phase 2 (Edge Cases) |
-| 4. Phụ thuộc liên service | Phase 1, câu 8 |
-| 5. Loại API | hỏi lúc `/generate-prd` (API Source) |
-| 6. AC kiểm được | Phase 6 (Acceptance Criteria) |
-| 7. Từ điển / thực thể | Phase 0 (Knowledge Sync) + `business-dictionary.md` / `core-entities.md` |
-
----
-
-← [Guides](README.md) · Liên quan: [Checklist Input BDD (System/BE)](bdd-input-checklist.md) · [Quy tắc viết PRD](product-owner/prd-writing-rules.md) · [Checklist handoff](product-owner/handoff-checklist.md)