@shanyucoder/flowgrid 0.1.0

package/stacks/nuxt4.json

@@ -0,0 +1,148 @@
+{
+  "stack": "nuxt4",
+  "mode": "brownfield",
+  "commands": {
+    "genDry": [
+      "flowgrid",
+      "gen:dry",
+      "--adapter=nuxt4",
+      "--",
+      "--id",
+      "{spec}"
+    ],
+    "gen": [
+      "flowgrid",
+      "gen",
+      "--adapter=nuxt4",
+      "--",
+      "--id",
+      "{spec}"
+    ],
+    "unitGenDry": [
+      "flowgrid",
+      "unit-gen:dry",
+      "--adapter=nuxt4",
+      "--",
+      "--id",
+      "{spec}"
+    ],
+    "unitGen": [
+      "flowgrid",
+      "unit-gen",
+      "--adapter=nuxt4",
+      "--",
+      "--id",
+      "{spec}"
+    ],
+    "testcaseGenDry": [
+      "flowgrid",
+      "testcase:gen:dry",
+      "--",
+      "--id",
+      "{spec}"
+    ],
+    "testcaseGen": [
+      "flowgrid",
+      "testcase:gen",
+      "--",
+      "--id",
+      "{spec}"
+    ],
+    "registryValidate": [
+      "flowgrid",
+      "registry",
+      "--adapter=nuxt4"
+    ],
+    "unitRegistry": [
+      "flowgrid",
+      "unit-registry",
+      "--adapter=nuxt4"
+    ],
+    "e2eRegistry": [
+      "flowgrid",
+      "e2e-registry"
+    ],
+    "commonRegistry": [
+      "flowgrid",
+      "common-registry"
+    ]
+  },
+  "registries": [
+    "registries/design.registry.json",
+    "registries/common.registry.json",
+    "registries/unit-test.registry.json",
+    "registries/e2e-test.registry.json",
+    "registries/page-lifecycle.registry.json"
+  ],
+  "gapSources": [
+    "**/generated/HANDOFF.md",
+    "**/generated/UNIT-HANDOFF.md",
+    "**/generated/codegen.manifest.json"
+  ],
+  "specRoots": [],
+  "templates": {
+    "root": "adapters/nuxt4/codegen/templates",
+    "engine": "hbs",
+    "note": "SSOT in FlowGrid bộ code; product has no root codegen/"
+  },
+  "dsl": {
+    "ssot": "product-repo",
+    "lanes": {
+      "fe": {
+        "registries": [
+          "registries/design.registry.json",
+          "registries/common.registry.json"
+        ],
+        "genKeys": [
+          "genDry",
+          "gen"
+        ],
+        "needsTags": [
+          "#needs-component",
+          "#needs-ui",
+          "#shell:",
+          "#widget:"
+        ],
+        "note": "Review OK → promote design/common registry in product repo; rebuild index"
+      },
+      "unit": {
+        "registries": [
+          "registries/unit-test.registry.json"
+        ],
+        "genKeys": [
+          "unitGenDry",
+          "unitGen"
+        ],
+        "needsTags": [
+          "#needs-unit-test"
+        ],
+        "note": "Promote unit-test.registry.json after pattern OK"
+      },
+      "e2e": {
+        "registries": [
+          "registries/e2e-test.registry.json"
+        ],
+        "genKeys": [
+          "testcaseGenDry",
+          "testcaseGen"
+        ],
+        "needsTags": [
+          "#needs-testcase",
+          "#needs-e2e"
+        ],
+        "note": "{spec} = hub id (W-|TC-|CMP-|suite) for --id"
+      },
+      "lifecycle": {
+        "registries": [
+          "registries/page-lifecycle.registry.json"
+        ],
+        "genKeys": [],
+        "needsTags": [],
+        "note": "Updated by flowgrid gen; no separate lifecycle CLI"
+      }
+    }
+  },
+  "vocabularies": {
+    "registryTags": "artifactgraph/lexicon/registry-tags.en.txt"
+  }
+}

package/templates/project-skeleton/architecture/01-introduction/index.md

@@ -0,0 +1,33 @@
+# 01 — Introduction
+
+status: active
+
+## Purpose
+
+Goals and scope of this **docs hub** architecture narrative (*why* we document) — not a product marketing intro.
+
+## Goals
+
+1. **Navigate** — arc42 chapters as TOC so humans and AI skills land on the right layer.
+2. **Describe** — C4 views (`LND`/`CTX`/`CTR`) + product `CMP-*` without duplicating Code.
+3. **Curate** — only high-value runtime journeys (`FLOW-*`), not every agile story.
+
+## Audience
+
+| Reader | Use |
+|--------|-----|
+| Platform / product engineers | Context → containers → component → journey |
+| AI skills (`/architecture`, `/journey`, …) | Chapter + ID routing |
+| New joiners | Start §03 + `FLOW-login`; deepen via §05 / product |
+
+## Out of scope
+
+- Feature Code (`W-*`/`API-*`) and grill/codegen detail → `surfaces/`
+- Day-to-day toolchain how-to → `platform/`
+- Full E2E/`TC-*` plans → `base-tests`
+
+## See also
+
+- People entry: [Start now](/platform/guide/start-now)
+- Tree: [System doc structure](/platform/guide/SYSTEM-DOC-STRUCTURE)
+- [03 Context](/architecture/03-context/)

package/templates/project-skeleton/architecture/02-constraints/index.md

@@ -0,0 +1,34 @@
+# 02 — Constraints
+
+status: active
+
+## Purpose
+
+Constraints that shape how we write and structure architecture docs (and what we refuse to invent).
+
+## Technical
+
+| Constraint | Implication |
+|------------|-------------|
+| Docs live in git as Markdown | Diagrams = Mermaid in MD; no proprietary SSOT |
+| Product IDs (`CMP-*`/`W-*`/`API-*`) are stable | Architecture migrate must not rename L3 schemas |
+| VitePress Mermaid 11 | Prefer `sequenceDiagram` / `flowchart`; avoid Mermaid `C4Context` |
+| Multi-repo workspace | Cross-repo links via `platform-repos`; FE↔BE contract only when mapped |
+
+## Organizational
+
+| Constraint | Implication |
+|------------|-------------|
+| Stub-first §07 | No invented prod topology — `DEP-*` only when placement matters |
+| Curated journeys (~10–20%) | `/journey` refuses backlog-dump sequences |
+| AI author + human review | Skills + optional flowgrid MCP validate IDs; humans own ADRs |
+
+## Legal / security (docs)
+
+No secrets, tokens, or real prod endpoints in architecture MD. Local IDE/WSL tips are out of scope for this hub.
+
+## See also
+
+- [04 Solution strategy](/architecture/04-solution-strategy/)
+- [09 Decisions](/architecture/09-decisions/)
+- [ADR-001](/architecture/09-decisions/ADR-001-arc42-toc)

package/templates/project-skeleton/architecture/03-business-process/FLOW-login.md

@@ -0,0 +1,101 @@
+---
+id: FLOW-LOGIN
+title: "Quy trình Đăng nhập Quản trị viên"
+domain: "Admin Operations"
+surface: "Admin Web Portal"
+actors: ["Quản trị viên (Admin User)"]
+has_background_logic: false
+status: "approved"
+---
+
+# FLOW-LOGIN: Quy trình Đăng nhập Quản trị viên
+
+---
+
+## 1. Bối cảnh & Ma trận Phân quyền Nghiệp vụ
+
+* **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:**
+  | Tác nhân (Actor) | Vai trò trong Quy trình | Quyền hạn trên Màn hình |
+  | :--- | :--- | :--- |
+  | **Quản trị viên (Admin)** | Đăng nhập tài khoản | Nhập thông tin trên `[W-AD-AUTH-01]`, truy cập `[W-AD-DASH-01]` |
+
+---
+
+## 2. Chuỗi User Stories Đa Tầng
+
+### 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,  
+> **Tôi muốn** nhập tên đăng nhập và mật khẩu hợp lệ trên màn hình đăng nhập `[W-AD-AUTH-01]`,  
+> **Để** hệ thống xác thực danh tính và cấp quyền truy cập vào trang tổng quan `[W-AD-DASH-01]`.
+
+### Story 2: Xử lý Sai Thông tin & Khóa Tài khoản (Security Fallback Story)
+> **Là một** Quản trị viên hệ thống,  
+> **Tôi muốn** nhận được thông báo lỗi rõ ràng nếu nhập sai thông tin đăng nhập,  
+> **Để** tôi biết và điều chỉnh lại, đồng thời hệ thống tự động khóa tạm thời nếu nhập sai quá số lần quy định nhằm bảo mật thông tin.
+
+*(Quy trình này thuần tương tác màn hình xác thực, không có tác vụ background job ngầm).*
+
+---
+
+## 3. Quy tắc Nghiệp vụ (Business Rules) & Vòng đời Trạng thái
+
+### 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.
+* **BR-02 (Thời hạn phiên làm việc):** Phiên làm việc (Session) duy trì tối đa 8 giờ hoặc tự động đăng xuất sau 30 phút không có thao tác.
+* **BR-03 (Bảo mật thông báo):** Khi đăng nhập thất bại, chỉ hiển thị thông báo chung: "Tên đăng nhập hoặc mật khẩu không chính xác", không tiết lộ tài khoản có tồn tại hay không.
+
+### Ma trận Chuyển đổi Trạng thái
+| Thực thể | Trạng thái Bắt đầu | Hành động kích hoạt | Trạng thái Kết thúc | Điều kiện |
+| :--- | :--- | :--- | :--- | :--- |
+| **Phiên làm việc** | `UNAUTHENTICATED` | Nhập đúng thông tin & bấm "Đăng nhập" | `AUTHENTICATED` | Tài khoản hợp lệ, chưa bị khóa |
+| **Tài khoản** | `ACTIVE` | Nhập sai liên tiếp 5 lần | `LOCKED_TEMPORARY` | Vi phạm BR-01 |
+
+---
+
+## 4. Đặc tả Chi tiết Hành trình Từng Chặng
+
+### 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`.
+2. **Bấm "Đăng nhập":**
+   * Hệ thống kiểm tra xác thực thông tin đối soát với cơ sở dữ liệu tài khoản.
+   * **Nếu hợp lệ:** Khởi tạo phiên làm việc an toàn, điều hướng sang `[W-AD-DASH-01] Dashboard`.
+   * **Nếu sai thông tin:** Giữ nguyên màn hình đăng nhập, xóa trắng trường mật khẩu và hiển thị cảnh báo đỏ theo BR-03.
+
+---
+
+## 5. Ma trận Đối chiếu (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 |
+| :--- | :--- | :--- | :--- |
+| **Story 1 (Đăng nhập)** | `[W-AD-AUTH-01]` | `Admin ->> W_Auth ->> Core: Xác thực` | Auth Service, User Table |
+| **Story 1 (Điều hướng)** | `[W-AD-DASH-01]` | `W_Auth -->> W_Dash: Mở Dashboard` | Router & Session Storage |
+| **Story 2 (Sai mật khẩu)** | `[W-AD-AUTH-01]` | `W_Auth -->> Admin: Báo lỗi` | Form State & Error Alert |
+
+---
+
+## 6. Sơ đồ Tuần tự Nghiệp vụ Liên Màn hình (Screen-to-Screen Sequence Diagram)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Admin as Quản trị viên
+    participant W_Auth as [W-AD-AUTH-01] Màn hình Đăng nhập
+    participant Core as Dịch vụ Xác thực (Auth Service)
+    participant Storage as Cơ sở dữ liệu Người dùng
+    participant W_Dash as [W-AD-DASH-01] Bàn làm việc (Dashboard)
+
+    Admin->>W_Auth: 1. Mở trang đăng nhập
+    Admin->>W_Auth: 2. Nhập tên tài khoản, mật khẩu & bấm "Đăng nhập"
+    W_Auth->>Core: Gửi yêu cầu xác thực thông tin
+    Core->>Storage: Kiểm tra tài khoản và trạng thái khóa
+    
+    alt Thông tin đăng nhập chính xác & tài khoản hoạt động
+        Core-->>W_Auth: Xác thực thành công & cấp phiên làm việc
+        W_Auth-->>W_Dash: 3. Tự động điều hướng vào Dashboard
+        W_Dash-->>Admin: Hiển thị thông tin tổng quan và menu quản trị
+    else Sai thông tin hoặc tài khoản bị khóa
+        Core-->>W_Auth: Phản hồi từ chối đăng nhập (Kèm lý do bảo mật)
+        W_Auth-->>Admin: Hiển thị cảnh báo lỗi & yêu cầu nhập lại
+    end
+```

package/templates/project-skeleton/architecture/03-business-process/FLOW-template.md

@@ -0,0 +1,149 @@
+---
+id: FLOW-TEMPLATE
+title: "Tên quy trình nghiệp vụ chuẩn"
+surface: "Tên Surface (vd: Admin Portal / Customer Web / Mobile App)"
+actors: ["Tác nhân chính", "Tác nhân thụ hưởng"]
+has_background_logic: true
+status: "draft"
+---
+
+# FLOW-TEMPLATE: [Tên Quy Trình Nghiệp Vụ]
+
+---
+
+## 1. Bối cảnh & Ma trận Phân quyền Nghiệp vụ (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...]
+* **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 |
+  | :--- | :--- | :--- |
+  | **[Tác nhân chính]** | [Thực hiện thao tác chính] | [Quyền CRUD trên màn hình W-*] |
+  | **[Tác nhân phụ/phê duyệt]** | [Xem xét / phê duyệt / thụ hưởng] | [Xem báo cáo / nhận thông báo] |
+  | **[Background Job Worker]* | [Tự động xử lý ngầm sau khi lưu] | [Tự động đọc dữ liệu & gửi thông điệp] |
+
+*(Ghi chú: Nếu quy trình KHÔNG có background logic, có thể lược bỏ dòng Background Job Worker).*
+
+---
+
+## 2. Chuỗi User Stories Đa Tầng (Multi-tiered User Stories)
+
+### 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],  
+> **Tôi muốn** [Hành động cấu hình trên màn hình W-SET-01],  
+> **Để** [Mục đích chuẩn bị cho các bước giao dịch tiếp theo].
+
+### Story 2: Thao tác Nghiệp vụ Chính (Primary Action Story)
+> **Là một** [Vai trò người dùng, vd: Nhân viên vận hành / Khách hàng],  
+> **Tôi muốn** [Nhập liệu và gửi yêu cầu trên màn hình W-ACTION-01],  
+> **Để** [Hoàn tất thủ tục giao dịch nghiệp vụ].
+
+### Story 3: Xử lý Tự động Ngầm (Automated System Story - Khi có Background Logic)
+> **Là một** Hệ thống Tự động (Background Job Worker),  
+> **Tôi muốn** tự động bắt sự kiện lưu đơn, so khớp điều kiện và điều phối lệnh xử lý tới [Kênh đích / Cổng đối tác],  
+> **Để** tự động hóa quy trình, giảm thiểu độ trễ và tránh sai sót thao tác thủ công, đồng thời đảm bảo không xử lý lặp lại (Idempotency).
+
+### Story 4: Giám sát Trạng thái & Xử lý Ngoại lệ (Tracking & Fallback Story)
+> **Là một** [Vai trò người dùng / Quản lý],  
+> **Tôi muốn** theo dõi tiến độ và trạng thái xử lý trên màn hình chi tiết `[W-DETAIL-01]`,  
+> **Để** nắm bắt kết quả tức thì và can thiệp xử lý thủ công (Fallback) nếu hệ thống gặp sự cố.
+
+---
+
+## 3. Quy tắc Nghiệp vụ (Business Rules) & Vòng đời Trạng thái
+
+### 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...]
+* **BR-02 (Quy tắc ưu tiên / giới hạn):** [Ví dụ: Thứ tự ưu tiên bộ lọc, hạn mức giao dịch tối đa...]
+* **BR-03 (Chính sách Retry khi xử lý ngầm):** [Nếu có Job: Số lần thử lại (vd: tối đa 3 lần), khoảng cách thời gian giữa các lần, và điều kiện hủy bỏ khi gặp lỗi client 4xx.]
+* **BR-04 (Bảo mật & Lưu trữ):** [Quy tắc lưu trữ file trên S3, thời hạn link presigned URL hoặc chính sách bảo mật dữ liệu cá nhân.]
+
+### Ma trận Chuyển đổi Trạng thái (State Transitions)
+| Thực thể (Entity) | Trạng thái Bắt đầu | Hành động / Sự kiện kích hoạt | Trạng thái Kết thúc | Điều kiện chuyển trạng thái |
+| :--- | :--- | :--- | :--- | :--- |
+| **[Thực thể chính]** | `DRAFT` / `NONE` | Bấm "Lưu" trên `[W-ACTION-01]` | `CREATED` | Dữ liệu form hợp lệ |
+| **[Tác vụ ngầm/Job]** | `PENDING_TRIGGER` | Backend bắn sự kiện kích hoạt | `PROCESSING` | Worker nhận job từ queue |
+| **[Tác vụ ngầm/Job]** | `PROCESSING` | Xử lý thành công (cổng trả 200) | `COMPLETED` / `SENT` | Khách nhận tin / Đơn cập nhật |
+| **[Tác vụ ngầm/Job]** | `PROCESSING` | Thất bại sau tối đa lượt retry | `FAILED` | Bật cảnh báo lỗi trên màn hình |
+
+---
+
+## 4. Đặc tả Chi tiết Hành trình Từng Chặng (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.
+2. **Dữ liệu nhập (Key fields):**
+   * Field A: `[Tên trường]` = `[Giá trị mẫu]`
+   * Field B: `[Tên trường]` = `[Giá trị mẫu]`
+3. **Bấm "Lưu & Xác nhận":**
+   * *Kiểm tra tại chỗ:* Hệ thống validate dữ liệu giao diện.
+   * *Lưu trữ:* Ghi nhận thông tin vào Database (Table: `[tên_table]`), tải file đính kèm lên S3 Bucket `[tên_bucket]`.
+   * *Chuyển màn hình:* Điều hướng người dùng sang `[W-DETAIL-01]`.
+
+### Chặng 2: Xử lý Ngầm Phía Sau (Background Logic Execution - Nếu có)
+1. **Kích hoạt sự kiện:** Backend bắn sự kiện `[EventName]` kèm ID thực thể.
+2. **Worker xử lý:** Background Job quét điều kiện so khớp:
+   * *Kiểm tra Idempotency:* Đảm bảo chưa từng xử lý sự kiện này trước đó.
+   * *So khớp quy tắc:* Đối chiếu với BR-01 và BR-02.
+3. **Thực thi giao tiếp:** Gọi cổng ngoại vi / dịch vụ thứ 3 (Zalo/SMS/Email/Partner Webhook).
+4. **Cập nhật kết quả:** Ghi nhận log vào table `[tên_log_table]`, cập nhật trạng thái đơn thành `COMPLETED` (hoặc `FAILED` nếu vượt quá số lần retry).
+
+### Chặng 3: Phản hồi Trạng thái trên Màn hình `[W-DETAIL-01]`
+1. **Hiển thị kết quả:** Màn hình cập nhật badge trạng thái (Xanh: Thành công / Đỏ: Thất bại kèm lý do).
+2. **Cơ chế phục hồi (Fallback):** Nếu trạng thái là thất bại, hiển thị nút bấm `[Thử lại thủ công]` để người dùng kích hoạt lại mà không cần nhập lại form.
+
+---
+
+## 5. Ma trận Đối chiếu (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 |
+| :--- | :--- | :--- | :--- |
+| **Story 1 (Setup)** | `[W-SET-01]` | `Admin ->> W_Set ->> Core: Lưu cấu hình` | Table cấu hình |
+| **Story 2 (Primary Action)** | `[W-ACTION-01]` | `User ->> W_Action ->> Core: Gửi dữ liệu` | Core Service, Table chính, S3 |
+| **Story 3 (Background Job)** | N/A (Chạy ngầm) | `Core ->> Job ->> Gateway: Xử lý ngầm` | Background Worker, Message Queue |
+| **Story 4 (Tracking)** | `[W-DETAIL-01]` | `Job -->> W_Detail: Push trạng thái` | UI Detail Screen, Log Table |
+
+---
+
+## 6. Sơ đồ Tuần tự Nghiệp vụ Liên Màn hình (Screen-to-Screen Business Sequence Diagram)
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Người dùng / Nhân viên
+    participant W_Action as [W-ACTION-01] Màn hình Nhập liệu
+    participant W_Detail as [W-DETAIL-01] Chi tiết Giao dịch
+    participant Core as Core Service
+    participant Storage as Database (table) & S3 (bucket)
+    participant Job as Background Worker (Job)
+    participant Gateway as Kênh Bên Ngoài (Gateway)
+    actor Beneficiary as Người thụ hưởng / Đối tác
+
+    %% BƯỚC 1: THAO TÁC MÀN HÌNH
+    rect rgb(255, 250, 240)
+    Note over User, Storage: Giai đoạn 1: Thao tác trên giao diện người dùng
+    User->>W_Action: 1. Nhập thông tin giao dịch & đính kèm tài liệu
+    User->>W_Action: 2. Nhấn nút "Lưu & Xác nhận"
+    W_Action->>Core: Gửi dữ liệu giao dịch
+    Core->>Storage: Lưu dữ liệu vào Database & tải file lên S3
+    Core-->>W_Action: Phản hồi tạo giao dịch thành công (ID: REC-001)
+    W_Action-->>User: Điều hướng sang [W-DETAIL-01] Chi tiết Giao dịch
+    end
+
+    %% BƯỚC 2: XỬ LÝ NGẦM (NẾU CÓ)
+    rect rgb(245, 255, 245)
+    Note over Core, Beneficiary: Giai đoạn 2: Xử lý ngầm (Background Logic)
+    Core->>Job: Trigger sự kiện 'TransactionCreated' (mã: REC-001)
+    Job->>Storage: Kiểm tra điều kiện nghiệp vụ & chống trùng lặp
+    alt Khớp điều kiện & Xử lý thành công
+        Job->>Gateway: Gửi thông điệp / dữ liệu qua cổng ngoại vi
+        Gateway-->>Beneficiary: Người thụ hưởng nhận thông báo
+        Gateway-->>Job: Báo phản hồi thành công
+        Job->>Storage: Ghi log lịch sử & cập nhật trạng thái COMPLETED
+        Job-->>W_Detail: Push cập nhật trạng thái: "Hoàn tất thành công"
+    else Thất bại sau khi thử lại (Retry exhausted)
+        Job->>Storage: Ghi nhận log lỗi & cập nhật trạng thái FAILED
+        Job-->>W_Detail: Push cảnh báo lỗi (kèm nút Thử lại thủ công)
+    end
+    end
+```

package/templates/project-skeleton/architecture/04-solution-strategy/index.md

@@ -0,0 +1,26 @@
+# 04 — Solution strategy
+
+status: active
+
+## Purpose
+
+High-level approach: docs hub as arc42 TOC + C4 views; product Code under `CMP-*`; curated journeys.
+
+## Content
+
+| Theme | Decision |
+|-------|----------|
+| Docs structure | [ADR-001](../09-decisions/ADR-001-arc42-toc) — arc42 TOC over flat C4 folders |
+| Admin runtime | Admin Web + Admin API ([§07](../07-deployment/)) |
+| Auth entry | [CMP-01](/surfaces/CMP-01-auth/) · [FLOW-login](../06-runtime/journeys/FLOW-login) |
+
+Further ADRs land in [§09](../09-decisions/).
+
+## Out of scope
+
+Per-feature UI/API DSL (`surfaces/**/code/`).
+
+## See also
+
+- [09 Decisions](/architecture/09-decisions/)
+- [05 Building blocks](/architecture/05-building-blocks/)

package/templates/project-skeleton/architecture/07-deployment/index.md

@@ -0,0 +1,26 @@
+# 07 — Deployment
+
+status: stub
+
+**Optional.** Write `DEP-*` only when runtime **placement** matters.  
+Do not invent prod topology. Local machine tips stay out of this repo.
+
+## DEP-local
+
+Local WSL / Docker compose style layout for platform bases.  
+Prod/staging: TBD.
+
+```mermaid
+flowchart LR
+  Dev[Developer machine]
+  Docs[base-docs VitePress]
+  FE[FE base :3000]
+  API[API base]
+  Dev --> Docs
+  Dev --> FE
+  FE --> API
+```
+
+## Notes
+
+- Redirect: [`/architecture/deployments/`](/architecture/deployments/)

package/templates/project-skeleton/architecture/08-cross-cutting/configuration.md

@@ -0,0 +1,18 @@
+# Configuration
+
+| Field | Value |
+|-------|-------|
+| Owner | TBD |
+| Status | stub |
+
+## Intent
+
+How runtime config is supplied to admin FE/API bases (env, secrets boundary).
+
+## Approach
+
+TBD — do not put secrets in this repo.
+
+## Out of scope
+
+Developer machine / WSL setup notes — not part of this docs hub.

package/templates/project-skeleton/architecture/08-cross-cutting/index.md

@@ -0,0 +1,27 @@
+# 08 — Cross-cutting
+
+status: active
+
+Enterprise concerns that cut across containers/components. Skill: **`/cross-cutting`**.
+
+| Topic | Owner | Status | Doc |
+|-------|-------|--------|-----|
+| Security | TBD | stub | [security](./security) |
+| Observability | TBD | stub | [observability](./observability) |
+| Configuration | TBD | stub | [configuration](./configuration) |
+| Logging | TBD | stub | — |
+| Caching | TBD | stub | — |
+| Messaging | TBD | stub | — |
+| Exception handling | TBD | stub | — |
+| Validation | TBD | stub | — |
+| Localization | TBD | stub | — |
+| Authorization | TBD | stub | — |
+
+## Out of scope
+
+Full OpenAPI, UI DSL, E2E plans (`base-tests`).
+
+## See also
+
+- [09 Decisions](/architecture/09-decisions/)
+- Template: `.cursor/extracts/tpl-cross-cutting.md`

package/templates/project-skeleton/architecture/08-cross-cutting/observability.md

@@ -0,0 +1,18 @@
+# Observability
+
+| Field | Value |
+|-------|-------|
+| Owner | TBD |
+| Status | stub |
+
+## Intent
+
+Logging, metrics, and tracing across Admin Web / Admin API (and future layers).
+
+## Approach
+
+TBD.
+
+## Out of scope
+
+APM vendor runbooks in `platform/` handbook may live separately.

package/templates/project-skeleton/architecture/08-cross-cutting/security.md

@@ -0,0 +1,18 @@
+# Security
+
+| Field | Value |
+|-------|-------|
+| Owner | TBD |
+| Status | stub |
+
+## Intent
+
+Authenticate admin operators and protect Admin API (session/token). Details evolve with product ADRs.
+
+## Approach
+
+TBD — link ADR / CMP-01 / FLOW-login when expanded.
+
+## Out of scope
+
+Full threat model docs, UI DSL, OpenAPI bodies.

package/templates/project-skeleton/architecture/09-decisions/ADR-001-arc42-toc.md

@@ -0,0 +1,31 @@
+# ADR-001 — Docs hub uses arc42 TOC over flat C4 folders
+
+| Field | Value |
+|-------|-------|
+| Status | accepted |
+| Date | 2026-07-15 |
+| Deciders | docs hub |
+
+## Context
+
+Flat `architecture/{landscape,context,containers,dynamics,deployments}` answered *what* (C4 views) but not *why*. AI-first docs need a stable TOC for narrative chapters (constraints, cross-cutting, quality, risks).
+
+## Decision
+
+- `architecture/01`…`12` follow **arc42** as TOC.
+- C4 IDs (`LND`/`CTX`/`CTR`/`FLOW`/`DEP`) live **inside** chapters.
+- Product Code (`CMP`/`W`/`API`) stays under `surfaces/`.
+- Journeys use `FLOW-*` + `/journey`; `DYN-*`/`/dynamics` are deprecated aliases.
+
+## Consequences
+
+- Migrate pilot content; keep redirect stubs on old paths.
+- Skills: Layer-1 chapter router later; Layer-2 `/journey` now.
+- Deployment chapter remains optional/stub by default.
+
+## Related
+
+- [Start now](/platform/guide/start-now)
+- [Doc structure](/platform/guide/SYSTEM-DOC-STRUCTURE)
+- [06 Runtime](/architecture/06-runtime/)
+- [FLOW-login](/architecture/06-runtime/journeys/FLOW-login)

package/templates/project-skeleton/architecture/09-decisions/index.md

@@ -0,0 +1,13 @@
+# 09 — Decisions (ADR)
+
+status: active
+
+Architecture Decision Records for the **product / system** (not platform handbook process).
+
+| ID | Title | Status |
+|----|-------|--------|
+| [ADR-001](./ADR-001-arc42-toc.md) | Docs hub uses arc42 TOC over flat C4 folders | accepted |
+
+Former path [`shared/adr`](/shared/adr/) redirects here.
+
+Template: `.cursor/extracts/tpl-adr.md`