@shanyucoder/flowgrid 0.1.0

package/templates/project-skeleton/architecture/10-quality/index.md

@@ -0,0 +1,27 @@
+# 10 — Quality
+
+status: active
+
+Architecture quality concerns for this docs hub and its described systems.
+
+**Not** E2E/`TC-*` plans — those stay on **`base-tests`** (link from scenarios → `FLOW-*` where useful).
+
+## Architecture quality (docs)
+
+| Concern | Expectation |
+|---------|-------------|
+| Link integrity | Prefer flowgrid `validate_links` / CI later; avoid orphan `FLOW-*`/`ADR-*` |
+| ID consistency | Same keys across FE schema, API, BE when contract group exists |
+| Journey density | Core / cross-system only — quality over coverage |
+| Render UX | Mermaid readable in VitePress (`vitepress-mermaid-renderer`); no Kroki |
+
+## Runtime quality (product — stub)
+
+Fill when SLOs exist: availability, latency, auth failure rates, observability coverage.
+
+Until then see §08 [security](../08-cross-cutting/security) / [observability](../08-cross-cutting/observability).
+
+## See also
+
+- [08 Cross-cutting](/architecture/08-cross-cutting/)
+- [11 Risks](/architecture/11-risks/)

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

@@ -0,0 +1,25 @@
+# 11 — Risks
+
+status: active
+
+Risks and mitigations for the docs hub migration and for relying on curated architecture docs.
+
+## Docs hub
+
+| 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 |
+
+## Product / domain (stub)
+
+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)

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

@@ -0,0 +1,31 @@
+# 12 — Glossary
+
+status: active
+
+## ID legend
+
+| Prefix | Meaning |
+|--------|---------|
+| `LND-*` | Landscape |
+| `DEP-*` | Deployment node |
+| `CTR-*` | Container |
+| `CMP-*` | Component (product) |
+| `W-*` / `API-*` | Screen / API Code |
+| `FLOW-*` | Product journey (runtime) |
+| `DEP-*` | Deployment (optional) |
+| `ADR-*` | Architecture decision |
+| `SC-*` / `TC-*` | Test hub scenarios/cases |
+| `_legacy.dynamics*` | Legacy archaeology (not `FLOW-*`) |
+
+## Terms
+
+| Term | Meaning |
+|------|---------|
+| Journey | Curated product runtime flow `FLOW-*` under §06 |
+| 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 |
+| FlowGrid bộ docs | Optional local index over architecture and product Markdown IDs |
+| Docs hub layers | arc42 (why) → C4 views (what) → Product Spec (detail) |
+
+Product/domain vocabulary — TBD with MES/IoT owners.

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

@@ -0,0 +1 @@
+

package/templates/project-skeleton/architecture/model/workspace.dsl

@@ -0,0 +1,71 @@
+/*
+ * Structurizr DSL — pilot skeleton (Phase B).
+ * SSOT for prose/IDs remains MD under architecture/ + surfaces/ (see MODEL.md).
+ * IDs mirror docs hub: admin, web, CMP-01.
+ */
+workspace "base-docs platform" "arc42 × C4 pilot model" {
+
+    !identifiers hierarchical
+
+    model {
+        op = person "Admin operator" "Uses Admin web to manage platform/tenant data"
+
+        admin = softwareSystem "Admin Product" "Admin product boundary" {
+            web = container "Admin Web" "Admin SPA / FE" "Nuxt/Next" {
+                auth = component "CMP-01 Auth" "Authentication module" "Vue/React"
+            }
+            api = container "Admin API" "Admin HTTP API" "Nest/FastAPI" {
+                authApi = component "CMP-01 Auth API" "Auth endpoints" "Node"
+            }
+            db = container "Admin DB" "Storage" "PostgreSQL" "Database"
+        }
+
+        idp = softwareSystem "IdP / session" "External identity / session issuer" {
+            tags "External"
+        }
+
+        op -> web "Uses"
+        web -> api "HTTPS JSON"
+        api -> idp "Authenticates"
+        authUi -> authApi "POST login"
+    }
+
+    views {
+        systemLandscape "LND-base" {
+            include *
+            autoLayout lr
+        }
+
+        systemContext admin "Landscape" {
+            include *
+            autoLayout lr
+        }
+
+        container admin "Containers" {
+            include *
+            autoLayout tb
+        }
+
+        component web "CMP-01-web" {
+            include *
+            autoLayout lr
+        }
+
+        component api "CMP-01-api" {
+            include *
+            autoLayout lr
+        }
+
+        dynamic admin "FLOW-login" {
+            op -> web "Open login W-AD-AUTH-001"
+            web -> api "POST login API-AD-AUTH-001"
+            api -> idp "Validate credentials"
+            api -> web "session / token"
+            web -> op "Authenticated shell"
+            autoLayout
+        }
+
+        themes default
+    }
+
+}

package/templates/project-skeleton/index.md

@@ -0,0 +1,2 @@
+# Home
+Welcome to the documentation hub.

package/templates/project-skeleton/overview/.gitkeep

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+# Product Overview
+Welcome to the product overview.

package/templates/project-skeleton/qa/README.md

@@ -0,0 +1,11 @@
+# QA inbox (docs hub)
+
+Open customer / choice / tech-debt questions live here — **not** in `*.bundle.yaml`.
+
+- One file per open issue: `qa/open/QA-<bundle.id>-NNNN.yaml`
+- `bundle.id` is the screen leaf id from `/spec` (e.g. `cmp-adm-002-02-01-02`)
+- Sequence is **per screen** (`0001`, `0002`, …). Different screens never share a counter.
+- Close with **`/qa-resolve QA-<bundle.id>-NNNN`** plus the decision (skill deletes the file).
+
+Template: `.flowgrid/templates/qa-item.yaml`  
+Rules: `.cursor/extracts/qa-inbox.md`

package/templates/project-skeleton/surfaces/common/code/API-CMN-HEALTH-001/health.api.yaml

@@ -0,0 +1,12 @@
+id: API-CMN-HEALTH-001
+title: Health check
+kind: api-only
+method: GET
+path: /api/health
+
+response:
+  200:
+    body:
+      status: ok
+
+ui: null

package/templates/project-skeleton/surfaces/common/code/API-CMN-HEALTH-001/index.md

@@ -0,0 +1,12 @@
+# API-CMN-HEALTH-001 — Health check (API only)
+
+Common **API-only** pilot — no screen layout.
+
+```yaml
+ids:
+  apis:
+    - id: API-CMN-HEALTH-001
+  screens: []
+```
+
+Stub: [`health.api.yaml`](./health.api.yaml)

package/templates/project-skeleton/surfaces/common/code/UI-CMN-EMPTY-001/empty.ui.yaml

@@ -0,0 +1,14 @@
+id: UI-CMN-EMPTY-001
+title: Empty state pattern
+kind: ui-only
+summary: Shared empty-state copy + illustration slot for list shells.
+
+ui:
+  composition: EmptyState
+  props:
+    title: string
+    description: string
+    actionLabel: string | null
+
+api:
+  endpoints: []

package/templates/project-skeleton/surfaces/common/code/UI-CMN-EMPTY-001/index.md

@@ -0,0 +1,11 @@
+# UI-CMN-EMPTY-001 — Empty state (UI only)
+
+Common **UI-only** pilot — no API endpoints.
+
+```yaml
+ids:
+  screens: [UI-CMN-EMPTY-001]
+  apis: []
+```
+
+Stub: [`empty.ui.yaml`](./empty.ui.yaml)

package/templates/project-skeleton/surfaces/common/data-model/derived-data.md

@@ -0,0 +1,26 @@
+# Derived data (database)
+
+BE-only fields/tables for search, sort, compute, or snapshots — **not** a substitute for fixing wrong FE↔BE relationships.
+
+Tag: `#derived-data`
+
+## Requirements
+
+| Field | Meaning |
+|-------|---------|
+| `backendOnly: true` | Not owned by FE contract |
+| `sourceOfTruth` | Canonical source entity/query |
+| `refresh` | Strategy (sync job, trigger, on-write, …) |
+| `staleness` | If not realtime — document lag / TTL |
+
+## Rules
+
+- Do **not** hide bad relationship design behind derived tables.
+- Prefer documenting under this folder + feature Code `spec.entities` notes when shared.
+
+## Grill / platform-mark
+
+- Grill flags BE-only fields → ask member: add to contract · mark `#derived-data` · or remove.
+- Code lane detect table still in `platform-mark` extracts; **policy SSOT = this page**.
+
+Related: [`../data-model/`](./) · toolchain [`PLATFORM-MARK`](../../platform/toolchain/PLATFORM-MARK.md)

package/templates/project-skeleton/surfaces/common/data-model/index.md

@@ -0,0 +1,16 @@
+# Data model
+
+Shared domain notes (MD). Entity detail for a feature still belongs in that feature’s Code bundle `spec.entities`.
+
+## Topics
+
+- [Derived data (`#derived-data`)](./derived-data.md) — BE-only search/sort/compute/snapshot fields & tables
+
+## Journeys vs ER
+
+Runtime sequences live under [`architecture/06-runtime/journeys/`](/architecture/06-runtime/) (`FLOW-*`).  
+When a journey persists data, **link** the relevant entity here or in the owning `CMP-*/code` bundle — **do not** paste ER diagrams into every sequence.
+
+| Journey | Data notes |
+|---------|------------|
+| [FLOW-login](/architecture/06-runtime/journeys/FLOW-login) | Session/token — details TBD / ADR |

package/templates/project-skeleton/surfaces/common/index.md

@@ -0,0 +1,32 @@
+# Common (Code level)
+
+Same tier as feature Code — **not** C4 Context/Container.
+
+## Pilots (`code/`)
+
+| Kind | Example |
+|------|---------|
+| UI only | [`UI-CMN-EMPTY-001`](./code/UI-CMN-EMPTY-001/) |
+| API only | [`API-CMN-HEALTH-001`](./code/API-CMN-HEALTH-001/) |
+
+## Migrated patterns (from portal `docs/common`)
+
+| | |
+|-|-|
+| YAML | [`yaml/`](./yaml/) |
+| MD | [`md/`](./md/) |
+
+```bash
+flowgrid render
+flowgrid split -- <path>
+```
+
+## Patterns (UI / UX policy)
+
+| | |
+|-|-|
+| [Breadcrumb flow](./patterns/breadcrumb-flow.md) | Admin nav breadcrumb |
+| [Delete flow](./patterns/delete-flow.md) | Confirm / soft-delete patterns |
+| [Common UI spec](./patterns/ui-spec.md) | Grill/common UI rules |
+
+Integrations (BE marks): [`../shared/integrations/`](../shared/integrations/)

package/templates/project-skeleton/surfaces/common/md/breadcrumb-flow/common-breadcrumb-flow.md

@@ -0,0 +1,72 @@
+# Common breadcrumb flow
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Mọi dashboard page có breadcrumb khớp menu cha-con và action chain; breadcrumb trên page title.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## principles
+
+```yaml
+- Breadcrumb bắt buộc trên list, detail, edit, create khi có sidebar parent.
+- Thứ tự header — breadcrumb rồi page title rồi content.
+- Create không phải menu con — trail đi qua list (toolbar create).
+```
+
+## references
+
+```yaml
+- .cursor/extracts/common-breadcrumb-flow.md
+- docs/features/common/common-list-page.spec.yaml
+```
+
+## hierarchy
+
+```yaml
+- sidebarParent
+- sidebarChildOrList
+- actionPages
+```
+
+## examples
+
+```yaml
+hotelList: ホテル管理 > ホテル一覧
+hotelDetail: ホテル管理 > ホテル一覧 > {name}
+hotelEdit: ホテル管理 > ホテル一覧 > {name} > 編集
+hotelCreate: ホテル管理 > ホテル一覧 > 新規作成
+```
+
+## grill
+
+```yaml
+bqa: labels, entity display field, create label
+dev: ui.routes chain, route meta, wire-only menu API
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence

package/templates/project-skeleton/surfaces/common/md/buttons/common-buttons.md

@@ -0,0 +1,160 @@
+# Common buttons
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn button toàn admin portal để tránh chỗ chỉ text, chỗ icon + text không nhất quán.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## principles
+
+```yaml
+- Button nghiệp vụ mặc định dùng icon + text.
+- Nếu legacy thiếu icon, prototype chọn icon lucide hợp lý theo ý nghĩa action.
+- Icon không được là placeholder; phải phản ánh action/status.
+- Thiết kế phẳng: border/background rõ, không gradient, không shadow nặng.
+- Tránh button chỉ màu mà không có text/icon đủ nghĩa.
+```
+
+## defaultPattern
+
+```yaml
+businessAction:
+  content: icon + text
+  iconPosition: left
+  gap: 2
+  examples:
+    search:
+      text: 検索
+      icon: Search
+    clear:
+      text: クリア
+      icon: RotateCcw hoặc X
+    create:
+      text: 新規作成
+      icon: Plus
+    save:
+      text: 保存
+      icon: Save
+    update:
+      text: 更新
+      icon: Save
+    edit:
+      text: 編集
+      icon: Edit
+    duplicate:
+      text: 複製
+      icon: Copy
+    import:
+      text: インポート
+      icon: Upload
+    upload:
+      text: アップロード
+      icon: Upload
+    download:
+      text: ダウンロード
+      icon: Download
+    export:
+      text: エクスポート
+      icon: Download
+    backToList:
+      text: 一覧へ
+      icon: List
+    delete:
+      text: 削除
+      icon: Trash2
+      variant: destructive
+```
+
+## exceptions
+
+```yaml
+tableAction:
+  rule: icon-only
+  reason: Cột action trong table cần compact và đã có aria-label/title theo
+    `common-table-action-column`.
+paginationPrevNext:
+  rule: icon + text
+  icons:
+    previous: ChevronLeft
+    next: ChevronRight
+  text:
+    previous: 前へ
+    next: 次へ
+  reason: Pagination cần dễ hiểu hơn cho admin user, giữ icon để nhận diện nhanh
+    và text tiếng Nhật để rõ hành động.
+iconUtility:
+  rule: icon-only
+  appliesTo:
+    - close dialog
+    - collapse sidebar
+    - clear single chip
+  requirement: bắt buộc có aria-label/title.
+readonlyMetric:
+  rule: text-only allowed
+  examples:
+    - 合計 {count}
+  reason: Đây là indicator dạng button-style nhưng không phải action clickable.
+```
+
+## variants
+
+```yaml
+complete:
+  useFor: primary/complete action
+  background: "#48b0f7"
+  text: "#ffffff"
+outlinePrimary:
+  useFor: search/secondary positive action
+  border: "#4EAAFF"
+  text: "#4EAAFF"
+  background: "#FFFFFF"
+outlineSecondary:
+  useFor: clear/cancel/back neutral action
+  border: "#C2C2C2"
+  text: "#6B7280"
+  background: "#FFFFFF"
+destructive:
+  useFor: delete/destructive action
+  icon: Trash2
+```
+
+## accessibility
+
+```yaml
+- Button icon + text không cần aria-label riêng nếu text đủ rõ.
+- Button icon-only bắt buộc có `aria-label` và `title`.
+- Loading button giữ icon hoặc spinner bên trái, text vẫn mô tả action.
+```
+
+## testIds
+
+```yaml
+button: "{module}-{action}-btn"
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence

package/templates/project-skeleton/surfaces/common/md/confirm-dialog/common-confirm-dialog.md

@@ -0,0 +1,98 @@
+# Common confirm dialog
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn confirm dialog cho destructive/overwrite action, thay thế `window.confirm` trong prototype lâu dài.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## principles
+
+```yaml
+- Không lạm dụng modal; chỉ dùng khi action destructive, irreversible, overwrite
+  hoặc có side effect lớn.
+- Dialog phẳng, border rõ, không gradient/shadow nặng.
+- Non-destructive confirmation nên dùng inline confirmation hoặc disabled state
+  nếu đủ rõ.
+- Tránh tuyệt đối modal chồng modal; nếu modal đang mở thì action con phải xử lý
+  trong cùng modal hoặc đóng modal hiện tại trước khi mở flow mới.
+```
+
+## terminology
+
+```yaml
+actionModal:
+  definition: Dialog có button action hoặc close, chặn tương tác background.
+  dismissal: Chỉ đóng khi user bấm confirm, cancel, close, hoặc flow kết thúc theo spec.
+  interaction: User chỉ thao tác được trong modal trong lúc modal mở.
+alertToast:
+  definition: Thông báo nổi tự mất, không có confirm/cancel action.
+  ownerSpec: common-feedback
+```
+
+## layout
+
+```yaml
+placement:
+  default: center
+  reason: Dialog có button hành động cần focus và xác nhận rõ, nên hiển thị modal
+    giữa màn hình.
+  topRightNotAllowedFor:
+    - confirm delete
+    - confirm overwrite
+    - cancel/confirm action flow
+  topRightBelongsTo: alert dialog không có action confirm/cancel trong `common-feedback`.
+content:
+  maxWidth: sm
+  title: ngắn, rõ action
+  description: mô tả object/impact
+footer:
+  alignment: right
+  order:
+    - cancel secondary/outline gray
+    - confirm primary hoặc destructive
+```
+
+## copy
+
+```yaml
+deleteSingle: この要素を削除してよろしいですか？
+deleteMultiple: これらのレコードを削除しますか？
+overwriteImport: 重複するデータが存在し、それは上書きされます。続行しますか？
+```
+
+## testIds
+
+```yaml
+dialog: "{module}-{action}-dialog"
+title: "{module}-{action}-dialog-title"
+content: "{module}-{action}-dialog-content"
+confirm: "{module}-{action}-confirm-btn"
+cancel: "{module}-{action}-cancel-btn"
+```
+
+
+## Design intent
+
+**Inherits:** `admin-crud`
+
+**Shell:** #shell: DataPage
+
+**Patterns:**
+
+- #pattern: CRUD
+
+### Zones
+
+| ID | Nhãn | Vị trí | Container | Ghi chú |
+| --- | --- | --- | --- | --- |
+| main | Nội dung chính |  |  |  |
+
+## Legacy evidence