@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/commands/define-product.tmpl

@@ -1,158 +1,163 @@
-# /define-product — Feature Discovery (8-Phase Q&A)
+# /define-product — Khám phá tính năng (Q&A 8 Phase)
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, there is no input file to resolve in Step 1. Skip to Step 2 (context load) and then ask: **"Ticket ID and feature name? (e.g., LOYAL-29 Loyalty Points)"***
+*Lưu ý: Với lệnh này, không có file input cần phân giải ở Bước 1. Bỏ qua sang Bước 2 (nạp context) rồi hỏi: **"Ticket ID và tên feature? (vd: LOYAL-29 Loyalty Points)"***
 
 ## Context
 {{include:steps/context-loader.md}}
 
 ---
 
-## Phase 0 — Knowledge Sync *(AI fills automatically, no PO input needed)*
+## Phase 0 — Knowledge Sync *(AI tự điền — bối cảnh hệ thống, KHÔNG phải yêu cầu nghiệp vụ; không cần input PO)*
 
-AI scans the project and writes:
+AI quét dự án và ghi:
 
-- **Related Entities** — list entities from existing PRDs/domain-knowledge that relate to this feature.
-- **Related Modules** — list affected modules/services.
-- **Existing Rules / Logic** — rules from existing PRDs that this feature must respect.
-- **Terminology Normalization** — map any terms found in PO input to canonical terms from business-dictionary.md.
+- **Khái niệm / dữ liệu nghiệp vụ liên quan** — liệt kê khái niệm từ các PRD/domain-knowledge có sẵn liên quan tới feature này.
+- **Phần hệ thống / feature liên quan** — liệt kê phần hệ thống/feature bị ảnh hưởng.
+- **Rule / Logic có sẵn** — các rule từ PRD có sẵn mà feature này phải tôn trọng.
+- **Chuẩn hoá thuật ngữ** — map mọi thuật ngữ trong input PO về thuật ngữ chuẩn từ business-dictionary.md.
 
 ```
-| Term in PO input | Canonical term (business-dictionary) |
-|------------------|--------------------------------------|
-| {original}       | {canonical}                          |
+| Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
+|--------------------------|---------------------------------------|
+| {thuật ngữ gốc}          | {thuật ngữ chuẩn}                     |
 ```
 
-Store this terminology map in the output product-definition file under a `## Terminology Map` section — `/generate-prd` will reference it during its Terminology Rules step to ensure consistency.
+Lưu bản đồ thuật ngữ này vào file product-definition output dưới section `### Chuẩn hoá thuật ngữ` (trong Phase 0) — `/generate-prd` sẽ tham chiếu nó trong bước **Quy tắc thuật ngữ** để đảm bảo nhất quán.
 
 ---
 
 ## Phase 1 — Feature Definition *(CHECKPOINT 1)*
 
-Ask in order, one at a time:
+Hỏi **lần lượt từng câu một**, đợi PO trả lời rồi mới hỏi câu kế. Giữ giọng nghiệp vụ, thân thiện; nếu PO lúng túng, đưa một ví dụ ngắn để gợi ý. Tránh hỏi về giải pháp kỹ thuật ở phase này.
 
-1. **Context**: Background / reason why this feature is needed?
-2. **Problem**: Specific problem to solve?
-3. **Goal**: What objective does this feature achieve?
-4. **Actors**: Who are the users? (list roles, mark Primary/Secondary)
-5. **Scope**: What does this feature do? (one function per line — only what is in this ticket)
-6. **User Story**: Confirm in format:
-   ```
-   As a {User role}
-   I want to {User goal}
-   So that {Business value}
-   ```
+1. **Context**: Bối cảnh / lý do vì sao cần feature này?
+2. **Problem**: Vấn đề cụ thể cần giải quyết?
+3. **Goal**: Khi feature chạy ổn, kết quả nghiệp vụ bạn muốn thấy là gì? Mô tả *thành quả*, chưa cần cách làm.
+4. **Actors**: Những ai sẽ dùng feature này? Liệt kê từng vai trò, và đánh dấu ai là người dùng chính (Primary), ai phụ (Secondary).
+5. **In Scope**: Feature này làm gì? (mỗi dòng một chức năng — chỉ những gì thuộc ticket này)
+6. **Out of Scope**: Cái gì KHÔNG làm trong ticket này? Ghi rõ kèm lý do hoặc để dành pha/ticket sau — để tránh phình phạm vi.
+7. **User Story**: Xác nhận theo format (mỗi ý một bullet):
+   - **Là một (As a)** {vai trò}
+   - **Tôi muốn (I want to)** {mục tiêu}
+   - **Để (So that)** {giá trị nghiệp vụ}
+8. **Phụ thuộc liên service**: Để chạy được, feature có cần **dữ liệu hay năng lực** gì từ feature/team khác không? Mô tả ở mức nghiệp vụ (cần gì, từ ai, vì sao) — chưa cần nói API hay kỹ thuật. Nếu không có → trả lời "Không có".
 
-Summarize → confirm → write `✅ PO Confirmed: Yes` → proceed.
+Sau câu 8 → **tóm tắt lại toàn bộ** cho PO → chờ xác nhận → ghi `✅ PO xác nhận: Có` → sang Phase 2.
 
 ---
 
 ## Phase 2 — User Flow Definition *(CHECKPOINT 2)*
 
-Ask:
-1. **Entry Point**: Where does the user start interacting with this feature?
-2. **Flow Steps**: Describe each step (use table):
+Hỏi:
+1. **Entry Point**: Người dùng bắt đầu tương tác với feature này ở đâu?
+2. **Flow Steps**: Mô tả từng bước (dùng bảng):
    ```
-   | Step | Action (user) | Screen / State | Notes |
+   | Bước | Hành động | Trạng thái/Kết quả nghiệp vụ | Ghi chú |
    ```
-3. **Exit Point**: What is the final result when the flow completes?
+3. **Exit Point**: Kết quả cuối khi flow hoàn thành là gì?
+4. **Edge Cases**: Các kịch bản thất bại nghiệp vụ ngoài happy path? (input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng → kết quả nghiệp vụ kỳ vọng)
 
-Confirm → write `✅ PO Confirmed: Yes` → proceed.
+Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
 ---
 
 ## Phase 3 — Clarification Log *(CHECKPOINT 3)*
 
-Based on Phases 1-2, AI identifies gaps and asks follow-up questions. Continue rounds until no Unresolved Items remain.
+Dựa trên Phase 1-2, AI xác định gap và hỏi các câu follow-up. Tiếp tục các vòng cho tới khi không còn Mục chưa giải quyết.
 
 ```
-### Round {N}
-| # | Category       | Question   | PO Answer  |
+### Vòng {N}
+| # | Nhóm           | Câu hỏi    | PO trả lời |
 |---|----------------|------------|------------|
-| 1 | Context/Flow/Logic | {question} | {answer} |
+| 1 | Context/Flow/Logic | {câu hỏi} | {trả lời} |
 ```
 
-**BLOCK**: If Unresolved Items remain → MUST NOT proceed to Phase 4.
+**BLOCK**: Nếu còn Mục chưa giải quyết → KHÔNG được sang Phase 4.
 
-### Unresolved Items
-- {item — or "None"}
+### Mục chưa giải quyết
+- {mục — hoặc "None"}
 
-When all Unresolved Items are resolved → write `✅ CHECKPOINT 3: No Unresolved Items` → proceed to Phase 4.
+Khi mọi Mục chưa giải quyết đã xử lý → ghi `✅ CHECKPOINT 3: Không còn mục tồn đọng` → sang Phase 4.
 
 ---
 
 ## Phase 4 — Business Rules *(CHECKPOINT 4)*
 
-Derive from Phases 1-3. Each BR = one rule (WHAT the system must/must not do):
+Suy ra từ Phase 1-3. Mỗi BR = một quy tắc (hệ thống PHẢI / KHÔNG được làm gì — WHAT):
 
 ```
-| Rule ID | Action / Trigger    | Rule                          | Condition           |
+| Rule ID | Hành động/Trigger   | Quy tắc                       | Điều kiện           |
 |---------|---------------------|-------------------------------|---------------------|
-| BR-1    | {action from flow}  | System MUST/MUST NOT...       | {applicable condition} |
+| BR-1    | {hành động từ flow} | System MUST/MUST NOT...       | {điều kiện áp dụng} |
 ```
 
-Confirm → write `✅ PO Confirmed: Yes` → proceed.
+Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
 ---
 
 ## Phase 5 — Business Logic *(CHECKPOINT 5)*
 
-Map each BR to HOW the system executes it:
+Map mỗi BR sang **logic nghiệp vụ** thực thi nó (rẽ nhánh / công thức / điều kiện — KHÔNG mô tả thay đổi dữ liệu hay hành vi UI; đó là kỹ thuật/design):
 
 ```
-| Rule ID | System Behavior                       | Data State Change   | UI Behavior             | Error Handling         |
-|---------|---------------------------------------|---------------------|-------------------------|------------------------|
-| BR-1    | {how system processes when triggers}  | {what data changes} | {enable/disable/show...}| {error message/action} |
+| Rule ID | Logic nghiệp vụ (rẽ nhánh / công thức / điều kiện) | Thông báo/kết quả nghiệp vụ khi lỗi |
+|---------|---------------------------------------------------|-------------------------------------|
+| BR-1    | {logic nghiệp vụ khi rule kích hoạt}              | {vd: báo "Số dư không đủ"}           |
 ```
 
-Confirm → write `✅ PO Confirmed: Yes` → proceed.
+Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
 ---
 
 ## Phase 6 — Acceptance Criteria *(CHECKPOINT 6)*
 
-Derive from BRs + User Story. Each AC must be testable (clear pass/fail):
+Suy ra từ BR + User Story. Mỗi AC phải testable (pass/fail rõ ràng):
 
 ```
-| AC ID | Description             | Expected Behavior         | Derived from |
-|-------|-------------------------|---------------------------|--------------|
-| AC-1  | {criterion description} | {what system should do}   | BR-{N}       |
+| AC ID | Mô tả                   | Hành vi kỳ vọng            | Bắt nguồn từ |
+|-------|-------------------------|----------------------------|--------------|
+| AC-1  | {mô tả tiêu chí}        | {hành vi hệ thống cần làm} | BR-{N}       |
 ```
 
-Confirm → write `✅ PO Confirmed: Yes` → proceed.
+Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
 ---
 
 ## Phase 7 — Validation Report
 
-Generate coverage matrix automatically:
+Tự sinh ma trận độ phủ:
 
 ```
-| Flow Action | Has Rule? | Has Logic? | Has AC? | Status  |
-|-------------|-----------|------------|---------|---------|
-| {Action 1}  | ✅/❌     | ✅/❌      | ✅/❌   | OK/GAP  |
+| Hành động Flow | Có Rule? | Có Logic? | Có AC? | Status |
+|----------------|----------|-----------|--------|--------|
+| {Hành động 1}  | ✅/❌    | ✅/❌     | ✅/❌  | OK/GAP |
 ```
 
-- **Conflicts Detected**: list any conflicting rules, or "None".
-- **Missing Items**: list gaps, or "None".
+- **Xung đột phát hiện**: liệt kê các rule xung đột, hoặc "None".
+- **Mục còn thiếu**: liệt kê gap, hoặc "None".
 
-If any GAP found → alert PO and resolve before marking completed.
+Nếu phát hiện GAP → cảnh báo PO và giải quyết trước khi đánh dấu completed.
 
 ---
 
 ## Output
 
-Write `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` following `templates/product-definition.template.md`.
+Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/product-definition.template.md`.
+
+Điền tất cả section bằng dữ liệu thu thập qua các phase.
 
-Fill all sections with data gathered across phases.
-Set `Status: completed` when Phase 7 passes with no GAPs.
+**Cập nhật Metadata theo tiến độ (cho phép resume):**
+- Sau mỗi CHECKPOINT phase được chốt (`✅ PO xác nhận: Có`, hoặc với Phase 3 là `✅ CHECKPOINT 3: Không còn mục tồn đọng`) → cập nhật `Completed Phase` = số phase vừa xong và giữ `Status: in-progress`.
+- Khi Phase 7 pass mà không còn GAP → đặt `Completed Phase: 7` và `Status: completed`.
+- Nếu discovery bị ngắt giữa chừng, file vẫn được ghi với `Completed Phase` phản ánh phase cao nhất đã xác nhận — buổi sau resume tiếp từ phase kế tiếp.
 
 {{include:steps/report-footer.md}}
 
 ```
-/define-product Complete ✅
+/define-product Hoàn tất ✅
 File: {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
 Next: /generate-prd {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
 ```