@shanyucoder/flowgrid 0.1.4 → 0.1.8

package/templates/shared/tpl-api-contract.md

@@ -0,0 +1,133 @@
+# Template — Hợp đồng API (review & authoring)
+
+**Mục đích:** Cùng một ngôn ngữ cho BA / Dev BE / Dev FE / QA — **đọc trên site**, **ghi trên YAML**. SSOT codegen BE là `api/<seq>/01-backend-spec.yaml`; OpenAPI và Markdown là **bản render**, không sửa tay làm nguồn.
+
+**Workflow:** [docs/workflows/backend.md](../../docs/workflows/backend.md) · Skills: `/api-spec`, `/grill-api-spec`, `/openapi`, `/api-update`.
+
+---
+
+## Đọc trước khi viết (global)
+
+| Ai | Đọc gì trên VitePress / docs hub | Khi nào mở YAML `01` |
+|----|-----------------------------------|----------------------|
+| BA / PO | `ir/generated/spec.md` (hành vi màn) + `ir/generated/api.md` (bảng endpoint tóm tắt) | Không — delta nghiệp vụ qua `/update-spec` + Dev |
+| QA | `spec.md` + `api.md` (phạm vi API khớp scenario) | Chỉ khi trace lỗi `#err:*` / status code |
+| Dev FE | `ir/design.yaml` (`apiRefs`, `#reuse-api`) | Không — contract BE không phải input layout |
+| Dev BE | `api.md` → `01` → (preview) `02` sau `openapi_gen` | Author `/api-spec`, grill, codegen |
+
+Sau `flowgrid split` + `flowgrid render`: sidebar leaf **Spec · W-*** · **Data model** · **API summary** (`api.md`).
+
+---
+
+## Bộ trio trên function leaf
+
+```text
+surfaces/<surface>/CMP-*/<NN…>/<slug>/
+  <slug>.bundle.yaml          # FE/business — KHÔNG author spec.api
+  ir/design.yaml              # apiRefs, actions — FE + audit fe-be
+  ir/generated/api.md         # render từ 01 (đọc team)
+  api/<seq>/
+    01-backend-spec.yaml      # SSOT BE — mẫu: backend-api.yaml
+    02-openapi.yaml           # CHỈ gen từ 01 (flowgrid openapi_gen)
+    03-mock.yaml              # optional — copy from api-03-mock.stub.yaml
+```
+
+**Common API** (auth, dropdown dùng chung): `…/common/yaml/<slug>/` — cùng bộ file, một primary entity.
+
+**Quy tắc:**
+
+- Một file `01` = một **module** + một **primary entity** — không gộp cả CMP.
+- Action đã có API: `#reuse-api` + `reuseFrom` trên `ir/design.yaml` — **không** tạo `api/<seq>/` mới.
+- URI có **hậu tố hành động** (`/create`, `/{id}/update`, `/list`, `/{id}/detail`) — không REST mơ hồ `PUT /users/{id}`.
+
+---
+
+## Cấu trúc `01` (tóm tắt field)
+
+Mẫu đầy đủ: [`backend-api.yaml`](./backend-api.yaml) (sau `flowgrid init` → `.flowgrid/templates/backend-api.yaml`).
+
+| Khối | Vai trò |
+|------|---------|
+| `feature` | id, title, version, `source` (portal vs `base: none`) |
+| `approval` | `draft` → `approved` trước `api-gen` (policy team) |
+| `modules[].entities[]` | Bảng, field, quan hệ — khớp `design.sections[].db` / ERD |
+| `api.endpoints[]` | method, path, `purpose`, `errorStorming`, `#err:*` |
+| `requests` / `responses` | DTO — `meaning`/`purpose` khi có validation nghiệp vụ |
+| `codegen` | `profile`, `module`, `entity` — grill-api-spec bổ sung `#gen:*` |
+| `externalCalls` / `services` | Chỉ khi có `#call-external` / `#cross-entity-service` |
+
+**Không** dùng [`backend-api.bundle.yaml`](./backend-api.bundle.yaml) để sinh `01` mới — file legacy (bundle lồng `spec.api`); chỉ tham chiếu lịch sử.
+
+---
+
+## OpenAPI (01 → 02 → hub)
+
+Chuỗi **bắt buộc** sau mỗi lần sửa `01`:
+
+```text
+flowgrid api:check --spec …/01-backend-spec.yaml
+flowgrid openapi_gen --spec …/01-backend-spec.yaml    # ghi sibling 02-openapi.yaml
+flowgrid openapi_render                               # gộp → docs/openapi/api.yaml (hub)
+flowgrid render                                       # cập nhật ir/generated/api.md
+```
+
+| File | SSOT? | Ai sửa |
+|------|-------|--------|
+| `01-backend-spec.yaml` | **Có** | `/api-spec`, `/api-update`, `/grill-api-spec` |
+| `02-openapi.yaml` | Không — output gen | Vá thiếu bằng cách sửa `01`, gen lại |
+| `docs/openapi/api.yaml` | Không — merge hub | `openapi_render` |
+| `ir/generated/api.md` | Không — đọc | `flowgrid render` |
+
+**Cấm:** sửa `02` tay; dùng `nestjs --openapi` (hoặc stack tương đương) ghi đè docs hub; `flowgrid check` trên `01` (`check` chỉ cho `*.bundle.yaml`).
+
+Skill: `/openapi` · Redoc/Swagger UI: `openapi_build_ui` (tùy hub).
+
+---
+
+## Portal-backed vs BE-only
+
+| | Portal (`source.base` ≠ `none`) | BE-only (`base: none`) |
+|--|--------------------------------|-------------------------|
+| Input `/api-spec` | `ir/design.yaml` + actions | Requirement / partner doc — **không** `ir/design` làm contract |
+| Grill | `audit fe-be` + `audit api` | `audit api` only |
+| `feature.source` | `portalSpec`, `portalRefs` | `integrationRefs`, auth API key/HMAC |
+
+---
+
+## Error storming (review nhanh)
+
+| Tình huống endpoint | Tag / status gợi ý |
+|---------------------|-------------------|
+| Có `{id}` trong path | `#err:not-found` (404), `#err:idor-violation` (403) |
+| POST/PUT form body | `#err:validation` (422) + field rules |
+| Có permission | `#err:permission-denied` (403) |
+| Create/duplicate | `#err:conflict` (409) |
+| Partner/webhook | `#err:signature-invalid`, `#err:rate-limit`, `#err:unauthorized` |
+
+401/503/500 toàn cục: thường `$ref` OpenAPI components — không lặp từng endpoint.
+
+---
+
+## YAML an toàn
+
+- Chuỗi có `:` → bọc `"..."`.
+- Chạy `flowgrid api:check` trước handoff.
+- Thiếu fact → AskQuestion hoặc `qa/open/` — **không** `openQuestions` trong YAML.
+
+---
+
+## Liên kết bundle FE
+
+Trên bundle chỉ khai báo **hành vi UI** và `apiRefs`; chi tiết endpoint nằm trên `01`:
+
+```yaml
+design:
+  actions:
+    - id: submit_form
+      apiRefs: [ feature.create ]
+      onSpecificError:
+        - condition: "422 Validation"
+          notes: "Inline errors"
+```
+
+Xem [bundle-authoring.md § design.actions](./bundle-authoring.md#designactions-api-calls--ui-error-handling).

package/templates/shared/tpl-screen-data-model.md

@@ -0,0 +1,76 @@
+# Template — Mô tả bảng trên màn (review, multi-table)
+
+**Mục đích:** Member/BA review **vai trò từng bảng** trước khi đọc cột chi tiết. SSOT kỹ thuật vẫn là `design.sections[].db` + `01-backend-spec.yaml`.
+
+**Sau `flowgrid split`:** engine sinh `ir/generated/data-model.md` (tự động). Block YAML dưới đây **bổ sung** overview — author trên bundle `design.dataModel`.
+
+---
+
+## Author trên bundle (`design.dataModel`)
+
+```yaml
+design:
+  dataModel:
+    erdRef: "<LCA>/common/db-erd.md"
+    notes: |
+      Màn này ghi bảng chính `records` và đọc `record_attachments` cho sidebar.
+      Không tạo dòng mới trên bảng phụ.
+    tables:
+      - schema: records
+        erdEntity: Record
+        roleOnScreen: read-write   # read | write | read-write | join | aggregate
+        summary: "Hồ sơ chính — form create/update"
+      - schema: record_attachments
+        erdEntity: RecordAttachment
+        roleOnScreen: read
+        summary: "File đính kèm — chỉ list & download"
+```
+
+| `roleOnScreen` | Ý nghĩa review |
+|----------------|----------------|
+| `read-write` | Form/list ghi + đọc cột persisted |
+| `read` | Chỉ hiển thị / lookup |
+| `write` | Chỉ insert/update (ít gặp tách read) |
+| `join` | FK lookup từ bảng khác (select options) |
+| `aggregate` | KPI/count — thường `#derived-data`, không map `db` |
+
+---
+
+## Cột chi tiết (per table)
+
+Ghi trên từng control / list column trong bundle:
+
+```yaml
+bind:
+  field: record_code          # payload API / form state
+db:
+  schema: records             # khớp ERD + 01 entities[].table
+  field: code                 # khớp 01 entities[].fields[].name
+  enumMapping:                # optional
+    ACTIVE: "Đang hoạt động"
+```
+
+List nhiều bảng — **mỗi cột** khai `db` nếu sort/filter/search DB:
+
+```yaml
+spec:
+  ui:
+    list:
+      columns:
+        - key: attachment_name
+          title: "Tệp"
+          db:
+            schema: record_attachments
+            field: file_name
+```
+
+---
+
+## Checklist review (không chặn split)
+
+1. `flowgrid audit spec <bundle>` — `confirms[]` `CONFIRM_DB_*` → AskQuestion (`db-audit-wizard.md`).
+2. Mở `ir/generated/data-model.md` — một section `## Bảng \`...\`` per table.
+3. `01-backend-spec.yaml` — mỗi `db.schema` có entity; mỗi `db.field` có `fields[]`.
+4. ERD Phase 0 — entity mới đã có trên `db-erd.md`.
+
+Workflow: [bundle-authoring.md](./bundle-authoring.md#data-model--phase-0-erd-vs-screen-detail) · [architecture-data.md](../../docs/workflows/architecture-data.md).

package/templates/tests-skeleton/cases/README.md

@@ -3,3 +3,7 @@
 Đặt `TC-*.yaml` mirror path function trên docs-hub (bỏ prefix `surfaces/`).
 
 Ví dụ docs: `surfaces/admin/CMP-ADM-002/02/01/login/` → `cases/admin/CMP-ADM-002/02/01/login/TC-*.yaml`
+
+- SSOT ghi: `TC-*.yaml` (`schemaVersion: 2`) — copy mẫu từ `../_templates/TC.example.yaml` (init từ harness).
+- SSOT đọc QA/Dev: `pnpm cases:render` → `TC-*.md` cùng thư mục — **không sửa tay** MD.
+- Hướng dẫn: `../tpl-testcase-plan.md` · workflow `docs/workflows/test.md` (toolkit repo).

package/templates/tests-skeleton/catalog/locale.yaml

@@ -5,3 +5,12 @@ headings:
     cases: Testcase
     scenarios: Scenario
     plans: Kế hoạch kiểm thử
+    preconditions: Điều kiện tiên quyết
+    steps: Các bước thực hiện
+    expected: Kết quả mong đợi
+    traceability: Liên kết docs (traceability)
+    testMatrix: Ma trận kiểm thử
+    crossRefDocs: Đối chiếu docs hub
+    technical: Chi tiết kỹ thuật
+    testData: Dữ liệu kiểm thử
+    coverage: Phạm vi coverage

package/templates/tests-skeleton/tpl-testcase-plan.md

@@ -0,0 +1,9 @@
+# Testcase plan — hướng dẫn hub
+
+Bản đầy đủ (toolkit): sau `flowgrid init` copy từ package `harness/tests/templates/tpl-testcase-plan.md` hoặc xem repo FlowGrid `templates/tests-skeleton/tpl-testcase-plan.md` (sync với harness).
+
+- SSOT ghi: `cases/**/TC-*.yaml`
+- SSOT đọc team: `cases:render` → `TC-*.md` trên VitePress (`flowgrid dev` port 5174)
+- Đối chiếu nghiệp vụ: docs hub `FLOWGRID_DOCS_ROOT` — bundle + `ir/generated/spec.md`
+
+Mẫu vàng: `TC.example.yaml` (init / harness templates).

package/harness/docs/skills/api-integration/SKILL.md

@@ -1,110 +0,0 @@
----
-name: api-integration
-description: EXCLUSIVE /api-integration — ONLY for backend integration contracts (partner APIs, webhooks). DO NOT merge multiple integrations into single markdown files.
-disable-model-invocation: true
----
-
-> [!CRITICAL] MANDATORY PRE-FLIGHT
-> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
-
-# /api-integration — Integration Contract (no Portal FE)
-
-Shared extracts: `api-integration-spec.md`, `entity-relationship.md`, `call-external.md`, `agent-discipline.md`, `verify-gate.md`
-
----
-
-## Rule: When to Use (vs `/api-spec`)
-
-- **[MANDATORY]** Use `/api-integration` for: inbound/outbound webhooks, REST APIs exported to partners/3rd parties, public APIs with dedicated versioning, reverse-engineering legacy handlers or provider OpenAPI specs.
-- **[STRICTLY FORBIDDEN]** If a Portal FE spec exists for the same user journey → use `/api-spec`, not this command.
-
----
-
-## Rule: Audit Interlock
-
-- **[MANDATORY]** If an integration bundle already exists: run an audit before making modifications.
-  - ✅ Check for existing endpoints under `surfaces/integrations/` using `flowgrid_docs_route` or glob search before authoring a new contract trio.
-  - ❌ Never re-define routes that already exist; link and reuse them.
-
----
-
-## Rule: Missing Information Handling & Workload Threshold (Law 2)
-
-- **[MANDATORY]** When signature verification, retry policy, or retention policy is unknown, evaluate total missing volume:
-  - **Small Scope (≤5 questions):** Trigger `AskQuestion` wizard — one question at a time, **≥3 options**: (1) `(Recommended)`, (2) `Other` (free text), (3) `Log as Tech Debt (Pending)`.
-  - **Large Scope (≥10 gaps/endpoints):** **[MANDATORY HARD STOP IN CHAT]**. Do not spam single questions in chat. Generate an implementation plan / Plan Mode document partitioned into sequential Phases (3–5 endpoints/gaps per phase) with disk offloading at boundaries.
-  - ✅ If "Log as Tech Debt" is selected → create `qa/open/QA-<feature.id>-NNNN.yaml`. Set `integrationBacklog[]` (NOT portal `pendingTechDebt`).
-  - ❌ Never write `openQuestions` in YAML. Never invent HMAC secrets or partner-specific validation logic.
-
----
-
-## Rule: Folder Structure
-
-- **[MANDATORY]** Every integration contract must be placed under:
-  ```
-  surfaces/integrations/<provider>/<slug>/api/<seq>/
-  ├── 01-backend-spec.yaml    # feature.source.kind + integrationRefs (tech SSOT)
-  ├── 02-openapi.yaml         # generated by: flowgrid openapi_gen --spec <01>
-  └── 03-mock-data.yaml
-  ```
-- **[MANDATORY]** One `01` = one primary domain entity. Never dump all provider actions into one single file.
-- **[STRICTLY FORBIDDEN]** Never write `.md` directly. Never combine multiple integrations into one gross monolithic file.
-
----
-
-## Rule: Explicit URI Naming
-
-- **[MANDATORY]** All integration endpoints MUST use explicit action suffixes:
-  - Inbound webhook: `POST /api/v1/integrations/<provider>/webhook`
-  - Inbound event action: `POST /api/v1/integrations/<provider>/{id}/sync` (or `/receive`)
-  - Outbound partner API: `POST /…/create`, `PUT /…/{id}/update`
-- **[STRICTLY FORBIDDEN]** Never use ambiguous RESTful routes lacking explicit action semantics.
-
----
-
-## Rule: Integration Error Handling
-
-- **[MANDATORY]** Document explicit error responses using `#err:*` tags for:
-  - `#err:unauthorized` — invalid API key / expired token
-  - `#err:signature-invalid` — HMAC signature mismatch on webhook
-  - `#err:rate-limit` — partner throttling limit reached
-  - `#err:validation` — malformed payload
-  - `#err:system` — internal processing failure
-- **[RECOMMENDED]** Global errors (500/503/401) → delegate to OpenAPI `$ref` schemas; do NOT duplicate across each endpoint.
-- **[MANDATORY]** Provide partner-facing error code mappings in both `01-backend-spec.yaml` and `02-openapi.yaml`.
-
----
-
-## Rule: YAML & Tagging
-
-- **[MANDATORY]** Configure: `feature.source.kind`, `base: none`, `integrationRefs[]`, empty `portalRefs`, `contexts.portalLayout: none`, and `contexts.auth` (API key / HMAC / OAuth).
-- **[MANDATORY]** Use domain tags only: `#webhook-inbound`, `#webhook-outbound`, `#partner-api`, `#public-api`, `#call-external`, `#err:*`.
-- **[STRICTLY FORBIDDEN]** No `codegen`, no `#gen:*`, no `approval` beyond `draft` — specialized grill handles those downstream.
-- **[MANDATORY]** All strings with `:` in YAML must be double-quoted.
-
----
-
-## Workflow
-
-1. Configure source metadata: `feature.source.kind`, `base: none`, `integrationRefs[]`.
-2. Scan `surfaces/integrations/` for existing endpoints; apply reuse if found.
-3. Set `contexts.portalLayout: none`; document `contexts.auth`.
-4. Inventory events/endpoints from provider documentation or legacy source — mark `inferredFromCode` in `notes`.
-5. Specify entities, idempotency keys, deduplication, and raw payload retention policies in `decisions` / `beOnlyRequirements`.
-6. Author `api.endpoints` with explicit action URIs.
-7. Apply integration error storming `#err:*` tags.
-8. Run `flowgrid openapi_gen --spec …/api/<seq>/01-backend-spec.yaml` → generates `02-openapi.yaml`.
-9. Author mock data (representative webhook payload JSON + acknowledgement response).
-10. Run AskQuestion wizard for unresolved unknowns (signature, retry, retention).
-11. Update `.harness/progress.md`.
-
----
-
-## Verification Checklist
-
-- [ ] Folder structure: contract trio located under `surfaces/integrations/<provider>/<slug>/api/<seq>/`.
-- [ ] `01-backend-spec.yaml`, `02-openapi.yaml`, `03-mock-data.yaml` all generated and populated.
-- [ ] Partner-facing error codes and `#err:*` tags fully documented.
-- [ ] Explicit URI action suffixes strictly applied.
-- [ ] No `.md` authored directly. No gross monolithic files created.
-- [ ] All YAML strings containing `:` are double-quoted.

package/harness/docs/skills/grill-integration-spec/SKILL.md

@@ -1,51 +0,0 @@
----
-name: grill-integration-spec
-description: EXCLUSIVE /grill-integration-spec — ONLY for auditing backend integration contracts under surfaces/integrations/. DO NOT generate Markdown reports.
-disable-model-invocation: true
----
-
-> [!CRITICAL] MANDATORY PRE-FLIGHT
-> **[MANDATORY]** Re-read this entire `SKILL.md` via file-read tool. STRICTLY FORBIDDEN to rely on memory.
-
-# /grill-integration-spec — Integration Contract Audit
-
-After `/api-integration`. Before bộ code BE `/api`. No code on docs hub.
-
-Shared extracts: `api-integration-spec.md`, `api-codegen-readiness.md`, `api-codegen-tags.md`, `call-external.md`, `entity-relationship.md`, `agent-discipline.md`, `verify-gate.md`
-
----
-
-## Rule: Goal & Scope
-
-- **[MANDATORY]** Contract must be sufficient to implement webhook and partner APIs.
-- **[MANDATORY]** OpenAPI `securitySchemes` and mock definitions must match `01-backend-spec.yaml`.
-- **[MANDATORY]** Codegen-ready: `flowgrid check` + `flowgrid openapi_gen` / `openapi:render` must pass.
-- **[STRICTLY FORBIDDEN]** Do NOT use `ir/design.yaml` as BE input (integrations usually have no FE IR).
-- **[STRICTLY FORBIDDEN]** No BQA reports, no framework code snippets, no writing `ir/*`.
-
----
-
-## Rule: Workflow Steps
-
-- **[MANDATORY]** Step 1: Resolve `surfaces/integrations/<provider>/<slug>/api/<seq>/01-backend-spec.yaml`. Never a `01` directly on the slug leaf.
-- **[MANDATORY]** Step 2: Audit authentication, `securitySchemes`, idempotency keys, retry policies, and non-CRUD actions.
-- **[MANDATORY]** Step 3: Enrich `01` with codegen tags (`#gen:*`, `#manual-service`, `#call-external`), `codegen.profile|entity|module`, and `endpoints[].action`.
-- **[MANDATORY]** Step 4: Run gates:
-  - `flowgrid check --spec surfaces/integrations/<provider>/<slug>/api/<seq>/01-backend-spec.yaml`
-  - `flowgrid openapi_gen --spec …/01-backend-spec.yaml`
-  - `flowgrid openapi_render`
-- **[MANDATORY]** Step 5: Set `approval.status: reviewed` (or `approved`) in YAML.
-
----
-
-## Verification Checklist
-
-- [ ] Target: `01-backend-spec.yaml` under `…/integrations/…/api/<seq>/`.
-- [ ] Auth + idempotency keys + retry policy verified and populated.
-- [ ] Gates executed: `api:check` + `openapi:gen` + `openapi:render` exit 0.
-- [ ] `approval.status` set to `reviewed` or `approved`.
-- [ ] No `openQuestions` in YAML; no `.md` written directly.
-
-## Handoff
-
-- `approval.status: approved` → bộ code `--type=be` `/api` with `--spec …/01-backend-spec.yaml`