@shanyucoder/flowgrid 0.1.9 → 0.1.10

package/templates/project-skeleton/architecture/{03-business-process → 03-user-flows}/FLOW-login.md

@@ -12,7 +12,7 @@ status: "approved"
 
 ---
 
-## 1. Bối cảnh & Ma trận Phân quyền Nghiệp vụ
+## 1. Context & role matrix
 
 * **Bối cảnh kích hoạt:** Quản trị viên truy cập vào cổng quản trị để quản lý hệ thống. Phiên đăng nhập hiện tại chưa có hoặc đã hết hạn.
 * **Ma trận Vai trò & Quyền hạn:**
@@ -22,7 +22,7 @@ status: "approved"
 
 ---
 
-## 2. Chuỗi User Stories Đa Tầng
+## 2. User stories (multi-tier)
 
 ### Story 1: Xác thực & Truy cập Hệ thống (Primary Action Story)
 > **Là một** Quản trị viên hệ thống,  
@@ -38,7 +38,7 @@ status: "approved"
 
 ---
 
-## 3. Quy tắc Nghiệp vụ (Business Rules) & Vòng đời Trạng thái
+## 3. Business rules & state lifecycle
 
 ### Danh mục Quy tắc Nghiệp vụ
 * **BR-01 (Giới hạn thử lại):** Cho phép nhập sai tối đa 5 lần liên tiếp. Nếu vượt quá, khóa tài khoản tạm thời trong 15 phút.
@@ -53,7 +53,7 @@ status: "approved"
 
 ---
 
-## 4. Đặc tả Chi tiết Hành trình Từng Chặng
+## 4. Step-by-step journey
 
 ### Chặng 1: Nhập thông tin trên `[W-AD-AUTH-01]`
 1. **Thao tác:** Quản trị viên mở trang đăng nhập, điền `username` và `password`.
@@ -64,7 +64,7 @@ status: "approved"
 
 ---
 
-## 5. Ma trận Đối chiếu (Traceability Matrix)
+## 5. Traceability matrix
 
 | Bước trong User Story | Màn hình liên quan | Hành động trên Sequence Diagram | Thành phần kỹ thuật đảm nhiệm |
 | :--- | :--- | :--- | :--- |
@@ -74,7 +74,7 @@ status: "approved"
 
 ---
 
-## 6. Sơ đồ Tuần tự Nghiệp vụ Liên Màn hình (Screen-to-Screen Sequence Diagram)
+## 6. Screen-to-screen sequence diagram
 
 ```mermaid
 sequenceDiagram

package/templates/project-skeleton/architecture/{03-business-process → 03-user-flows}/FLOW-template.md

@@ -11,11 +11,10 @@ status: "draft"
 
 ---
 
-## 1. Bối cảnh & Ma trận Phân quyền Nghiệp vụ (Context & Role Matrix)
+## 1. Context & role matrix
 
 * **Bối cảnh kích hoạt (Trigger Context):** [Mô tả hoàn cảnh hoặc sự kiện nào khiến quy trình này diễn ra. Ví dụ: Khách hàng yêu cầu đặt hàng, hoặc quản trị viên khởi tạo chiến dịch khuyến mãi...]
 * **Mục tiêu kinh doanh (Business Goal):** [Giá trị kinh doanh hoặc bài toán mà quy trình này giải quyết...]
-* **Chỉ số thành công (Success metrics):** [Đo được nếu có — VD: thời gian xử lý, tỷ lệ lỗi, SLA phản hồi]
 * **Phạm vi không làm (Non-goals):** [Quy trình/phase này cố ý không bao gồm — tránh trùng FLOW khác]
 * **Ma trận Vai trò & Quyền hạn (Role & Permission Matrix):**
   | Tác nhân (Actor) | Vai trò trong Quy trình | Quyền hạn trên Màn hình |
@@ -28,7 +27,7 @@ status: "draft"
 
 ---
 
-## 2. Chuỗi User Stories Đa Tầng (Multi-tiered User Stories)
+## 2. User stories (multi-tier)
 
 ### Story 1: Thao tác Chuẩn bị / Cấu hình (Setup Story - Tùy chọn)
 > **Là một** [Vai trò chuẩn bị, vd: Quản trị viên],  
@@ -52,7 +51,7 @@ status: "draft"
 
 ---
 
-## 3. Quy tắc Nghiệp vụ (Business Rules) & Vòng đời Trạng thái
+## 3. Business rules & state lifecycle
 
 ### Danh mục Quy tắc Nghiệp vụ (Business Rules)
 * **BR-01 (Quy tắc thẩm định dữ liệu):** [Mô tả điều kiện hợp lệ để cho phép đi tiếp sang bước kế tiếp...]
@@ -70,7 +69,7 @@ status: "draft"
 
 ---
 
-## 4. Đặc tả Chi tiết Hành trình Từng Chặng (Step-by-step Journey)
+## 4. Step-by-step journey
 
 ### Chặng 1: Thao tác & Nhập liệu trên Màn hình `[W-ACTION-01]`
 1. **Thao tác người dùng:** Người dùng truy cập form, điền các thông tin bắt buộc.
@@ -96,7 +95,7 @@ status: "draft"
 
 ---
 
-## 5. Ma trận Đối chiếu (Traceability Matrix)
+## 5. Traceability matrix
 
 | Bước trong User Story | Màn hình liên quan | Hành động trên Sequence Diagram | Thành phần kỹ thuật đảm nhiệm |
 | :--- | :--- | :--- | :--- |
@@ -107,7 +106,7 @@ status: "draft"
 
 ---
 
-## 6. Sơ đồ Tuần tự Nghiệp vụ Liên Màn hình (Screen-to-Screen Business Sequence Diagram)
+## 6. Screen-to-screen sequence diagram
 
 ```mermaid
 sequenceDiagram

package/templates/project-skeleton/architecture/11-risks/index.md

@@ -2,24 +2,14 @@
 
 status: active
 
-Risks and mitigations for the docs hub migration and for relying on curated architecture docs.
+Risks live **only** in the central register — not on feature bundles.
 
-## Docs hub
+## Register (member-facing)
 
-| Risk | Mitigation |
-|------|------------|
-| Stale paths after arc42 migrate | Redirect stubs on old flat paths; skills + start-now / SYSTEM-DOC-STRUCTURE |
-| Orphan / wrong IDs in MD | FlowGrid bộ docs MCP orphans + validate_links; add FLOW-* only with lead IDs |
-| “Full sequence every story” pressure | Principle: curated ~10–20%; skill `/journey` refusal |
-| Mermaid render confusion | Reader = VitePress only; no Mermaid MCP; Structurizr only if C4 hierarchy pain |
-| Invented deployment topology | §07 stub-first; `/deployment` refuses fiction |
+**[risk-register.md](./risk-register.md)** — bảng `RISK-*`, hạn mức vs nhu cầu peak.
 
-## Product / domain (stub)
+```bash
+flowgrid audit risks architecture/11-risks/risk-register.md
+```
 
-New MES / IoT / ERP journeys only when lead assigns real `CTR-*`/`API-*` ownership — do not invent draft FLOW SSOT.
-
-## See also
-
-- [10 Quality](/architecture/10-quality/)
-- [Start now](/platform/guide/start-now)
-- [Doc structure](/platform/guide/SYSTEM-DOC-STRUCTURE)
+Skill: `/risk-register`

package/templates/project-skeleton/architecture/11-risks/risk-register.md

@@ -0,0 +1,34 @@
+---
+status: draft
+owner: product-team
+contentLocale: vi
+---
+
+# Risk register
+
+**SSOT** for project risks — members edit this file only. **Do not** use `risks:` on `*.bundle.yaml`.
+
+Add a row when **limit** (quota, SLA, license) differs from **need** (peak, campaign).
+
+## Summary
+
+| Metric | Value |
+| --- | --- |
+| Open risks | 0 |
+| Quota / capacity gaps | 0 |
+| With mitigation | 0 |
+
+## Risk table
+
+| ID | Type | Description | Limit | Need | Gap | Impact | Mitigation | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| RISK-QUOTA-EMAIL-001 | Quota / infra | System notification email | 500 emails/day (SMTP) | ~700 emails/day (month start, reminders) | +200 (~40%) | Users miss timely email | (1) Spread queue (2) Upgrade plan (3) SMS for critical | Open |
+
+### Suggested types
+
+Quota / infra · Vendor · Data / compliance · Operations capacity · Product / scope
+
+## Links
+
+- Open questions: `qa/index.md`
+- Skill: `/risk-register` · `flowgrid audit risks architecture/11-risks/risk-register.md`

package/templates/project-skeleton/architecture/12-glossary/index.md

@@ -21,7 +21,8 @@ status: active
 
 | Term | Meaning |
 |------|---------|
-| Journey | Curated product runtime flow `FLOW-*` under §06 |
+| Journey / Luồng người dùng | `FLOW-*` under `architecture/03-user-flows` or `common/user-flows` |
+| `/user-flow` | Docs skill to author product `FLOW-*` |
 | business-process-trace | Brownfield process-through-code skill — **not** product journey `FLOW-*` |
 | flow-trace | Deprecated alias of business-process-trace |
 | `_legacy.dynamics*` | Extract/artifact name for old dynamics — keep filename; wording → FLOW/journey |

package/templates/project-skeleton/overview/index.md

@@ -1,68 +1,46 @@
 ---
 status: draft
 owner: product-team
+contentLocale: vi
 ---
 
-# Product overview (arc42 §1 — Introduction & Goals)
+# Product overview
 
-Tài liệu **sản phẩm** cho toàn docs hub: *vì sao* hệ thống tồn tại, *ai* dùng, *phạm vi* operational area. Chi tiết màn/API → `surfaces/`; kiến trúc kỹ thuật → `architecture/`.
+Product-level docs for this hub. Screen detail → `surfaces/` · technical architecture → `architecture/`.
 
-## Mục tiêu (Goals)
+> Section titles are **English** (global keys). Prose uses `contentLocale` in frontmatter / `docs-hub.locale.yaml`.
 
-1. **Giá trị nghiệp vụ** — [Một đoạn: bài toán chính product giải quyết.]
-2. **Đối tượng phục vụ** — [Vai trò / operational area chính.]
-3. **Nguyên tắc sản phẩm** — [VD: một SSOT docs, trace `W-*` / `API-*`, grill trước codegen.]
+## Goals {#goals}
 
-## Stakeholders
+1. **Business value** — [Main problem this product solves.]
+2. **Primary audience** — [Roles / channels — one line.]
+3. **Product principles** — [e.g. single SSOT, trace `W-*` / `API-*`.]
 
-| Vai trò | Mục đích đọc overview |
-| --- | --- |
-| PO / BA | Phạm vi, persona, operational area |
-| Dev / QA | Boundary module, link `CMP-*` |
-| Leadership | Goals + success metrics cấp product |
-
-## Top quality goals (arc42)
-
-| # | Thuộc tính | Mục tiêu (đo được nếu có) |
-| --- | --- | --- |
-| 1 | Khả dụng | [VD: uptime SLA nội bộ] |
-| 2 | Bảo mật | [VD: RBAC trên admin portal] |
-| 3 | Khả năng mở rộng | [VD: multi-tenant / module mới không phá SSOT] |
-| 4 | Khả năng bảo trì | [VD: spec bundle + split + audit] |
-| 5 | Trải nghiệm | [VD: affordance UX portal chuẩn] |
-
-## Personas (tóm tắt)
-
-- **[Persona A]** — [Một câu: nhu cầu chính trên surface nào.]
-- **[Persona B]** — […]
-
-Leaf `userStories.primary.asA` **tham chiếu** persona ở đây (không copy persona dài trên từng màn).
-
-## Phạm vi & không làm (product-level)
+## Background {#background}
 
-**In scope (overview):**
+[Short paragraph: current situation, why this product/phase exists. No infra deep-dive.]
 
-- [Operational area / surface được document trong hub này]
+## Scope {#scope}
 
-**Non-goals (product-level):**
+**In scope:**
 
-- [VD: không mô tả hạ tầng chi tiết — xem `architecture/`]
-- [VD: không thay quy trình UAT Excel deliverable — xem tests-docs]
+- [Operational areas / surfaces documented in this hub]
 
-## Success metrics (product-level)
+**Out of scope:**
 
-- [Chỉ số đo được cấp product — VD: thời gian onboard member đọc SSOT, % leaf có audit sạch trước test lane]
+- [e.g. deployment detail → `architecture/07-deployment/`]
+- [personas / KPIs managed outside the hub]
 
 ## Operational areas
 
-Mỗi area một file dưới `overview/operational-areas/` — dùng [`_template.md`](./operational-areas/_template.md).
+One file per area under `overview/operational-areas/` — see [`_template.md`](./operational-areas/_template.md).
 
 | Area | File |
 | --- | --- |
-| [Tên area] | `operational-areas/<slug>.md` |
+| [Area name] | `operational-areas/<slug>.md` |
 
 ## See also
 
-- Surfaces SSOT: `surfaces/`
-- Architecture: `architecture/01-introduction/`
-- Workflow Design: `platform` hoặc `docs/workflows/design.md` (khi publish site)
+- Surfaces: `surfaces/`
+- User flows catalog: `architecture/03-user-flows/`
+- Risk register: `architecture/11-risks/risk-register.md`

package/templates/project-skeleton/overview/operational-areas/_template.md

@@ -1,37 +1,30 @@
 ---
 id: OA-TEMPLATE
-title: "Tên operational area"
+title: "Operational area name"
 status: draft
 surfaces: ["admin-web"]
+contentLocale: vi
 ---
 
-# Operational area: [Tên]
+# Operational area: [Name]
 
-**Mục đích:** [Một đoạn — bối cảnh vận hành: ai làm việc gì, trên kênh nào.]
+> Section titles are **English**. Prose uses `contentLocale` / `docs-hub.locale.yaml`.
 
-## Personas trong area
+**Purpose:** [One paragraph — who does what, on which channel.]
 
-| Persona | Mô tả ngắn | Surface chính |
-| --- | --- | --- |
-| [VD: Nhân viên vận hành] | [Nhu cầu] | `admin-web` |
+## Scope {#scope}
 
-## Phạm vi nghiệp vụ
+- **In scope:** [Processes / modules in this area]
+- **Out of scope:** [Other area or later phase]
 
-- **In scope:** [Quy trình / module thuộc area]
-- **Out of scope:** [Chuyển sang area khác hoặc phase sau]
+## Module links
 
-## Success metrics (area)
-
-- [Metric 1 — đo được]
-- [Metric 2]
-
-## Liên kết module
-
-| CMP | Mô tả |
+| CMP | Summary |
 | --- | --- |
-| `CMP-XX-…` | [Boundary một dòng] |
+| `CMP-XX-…` | [One-line boundary] |
 
-## Non-goals
+## Related user flows
 
-- [Không document chi tiết deployment — `architecture/07-deployment/`]
-- [Không duplicate FLOW kỹ thuật — `architecture/03-business-process/`]
+| FLOW | Summary |
+| --- | --- |
+| `FLOW-…` | [Link under `architecture/03-user-flows/` or `common/user-flows/`] |

package/templates/project-skeleton/surfaces/_module-index.template.md

@@ -0,0 +1,40 @@
+---
+id: CMP-NN-slug
+title: "Module name"
+status: draft
+contentLocale: vi
+---
+
+# CMP-{NN} — [Name]
+
+> Section titles are **English**. Prose uses `contentLocale` / `docs-hub.locale.yaml`.
+
+## Goals {#goals}
+
+[Module value — one paragraph.]
+
+## Scope {#scope}
+
+- **In scope:** [Capabilities owned by this CMP on this surface.]
+- **Out of scope:** [Other CMP / phase / channel.]
+
+## Features overview {#features-overview}
+
+| Function | Screen / API | Notes |
+| --- | --- | --- |
+| `<slug>` | `W-…` / `API-…` | Leaf: `ir/generated/spec.md` |
+
+## Depends on {#depends-on}
+
+| ID / artifact | Reason |
+| --- | --- |
+| `CMP-…` / `FLOW-…` | [Upstream dependency] |
+
+## Module metadata
+
+| Field | Value |
+| --- | --- |
+| **ID** | `CMP-{NN}` |
+| **User flows** | `…/common/user-flows/FLOW-…` · [`architecture/03-user-flows/`](../../architecture/03-user-flows/) |
+| **Functions** | `<function-slug>`, … |
+| **Screens** | `W-…` |

package/templates/project-skeleton/surfaces/_surface-index.template.md

@@ -0,0 +1,43 @@
+---
+id: SURFACE-TEMPLATE
+title: "Surface channel name"
+status: draft
+contentLocale: vi
+---
+
+# Surface: [Channel name]
+
+> Section titles are **English**. Prose uses `contentLocale` / `docs-hub.locale.yaml`.
+
+## Goals {#goals}
+
+[Value of this channel — one paragraph.]
+
+## Background {#background}
+
+[Who uses this channel and in what context.]
+
+## Scope {#scope}
+
+**In scope:**
+
+- [CMP modules on this surface]
+
+**Out of scope:**
+
+- [Other surface or integration-only scope]
+
+## Modules (CMP)
+
+| CMP | Summary | Primary flow |
+| --- | --- | --- |
+| `CMP-…` | […] | `FLOW-…` (if any) |
+
+## User flows on this surface
+
+- Catalog: [`architecture/03-user-flows/`](/architecture/03-user-flows/)
+- Shared on surface: `common/user-flows/FLOW-*.md` (when ≥2 modules share)
+
+## Features overview
+
+[1–2 paragraphs: how to read the hub — detail per screen in bundles and `ir/generated/spec.md`.]

package/templates/shared/bundle-authoring.md

@@ -8,8 +8,11 @@ Hub: `docs/templates/feature.bundle.yaml` · split: `pnpm spec:split`
 |-----|---------|
 | `page-id` | Screen identity (`cmp-adm-000-01`). Split copies this onto `ir/spec.yaml` as `page-id` (not `id`, so it does not collide with requirement/section ids). Legacy bundles may still use `id`. |
 | `summary` | Phải trình bày dạng bullet. Bắt buộc có các tiêu đề (chuẩn Arc42 business): **mục tiêu nghiệp vụ** (business_goals), **các bên liên quan** (stakeholders), **kịch bản người dùng** (user_journey), **bối cảnh** (description, input liên kết cross-page/module, output) và **cách giải quyết** (tùy chọn). Mục đích để 100% Non-tech Stakeholder hiểu và duyệt. |
-| `successMetrics` | **Tùy chọn** khi có thông tin — bullet (string multiline hoặc list). Chỉ số đo được / qualitative metric cấp **màn/feature**. Product-level → `overview/`. Split → `ir/spec.yaml`; render → section riêng trong `ir/generated/spec.md`. |
-| `nonGoals` | **Tùy chọn** — phạm vi **không làm** trên màn/phase (PRD non-goals). Tránh nhét vào `requirements` prose. |
+| `scopeIn` | **Khuyến nghị** — trong phạm vi màn/phase (PRD). Audit `WARN_NO_SCOPE_IN`. |
+| `nonGoals` | **Khuyến nghị** — ngoài phạm vi màn/phase (PRD). Audit `WARN_NO_NON_GOALS`. |
+| `userFlows` | **Khuyến nghị** — link `FLOW-*` (`03-user-flows` / `common/user-flows`) hoặc journey ngắn. Audit `WARN_NO_USER_FLOWS` khi multi-screen. |
+| `nfr` | **Khuyến nghị** — hiệu năng, bảo mật. Audit `WARN_NO_NFR`. |
+| _(rủi ro)_ | **Không** khai báo trên bundle. SSOT: `architecture/11-risks/risk-register.md` — `/risk-register`. Key `risks:` → audit `WARN_BUNDLE_RISKS_FORBIDDEN`. |
 | `userStories` | **Khối User Stories chuyên sâu cho màn hình:** `primary`, `contextAndHandoff` (+ `screenAccess`), `scenarios` (5 kịch bản chuẩn + **scenario thứ 6 “Affordances UX”** khi màn có delete/filter/breadcrumb/disabled/import — xem `feature.bundle.yaml`), `acceptanceCriteria` (kèm checkbox UX khi áp dụng). **Split:** `pnpm spec:split` copy nguyên khối sang `ir/spec.yaml` (business prose); **không** tự sinh từ `design` — Agent phải cập nhật `userStories` khi bổ sung DSL/`#needs-component`/audit `UX_*`. Render → `## User Stories & Screen Journey` trong Markdown. |
 | `spec` | Design v1 — **`entities`**, **`relationships`**, actors, requirements, `ui.routes`, **`ui.list` / `ui.form` / `ui.detail`**, `acceptance`. **Không** author `spec.api` — API SSOT là `api/<seq>/01-backend-spec.yaml`. |
 | `gen` | **Bắt buộc trước flowgrid gen:** `codegen.profile` (`auth` login/forgot/reset; `change-password`; `public`; `not-found`/`error`; `list`/`create`/`admin-crud`) + entity/module, `tags`, derived `ui.*`. `/grill-dev` ghi. Endpoint `action` ghi trên **01**, không trên bundle. |