@shanyucoder/flowgrid 0.1.0

package/templates/schemas/testcase.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Portal E2E Testcase",
+  "type": "object",
+  "required": ["id", "feature", "title", "route", "steps", "assertions"],
+  "properties": {
+    "id": { "type": "string" },
+    "feature": { "type": "string" },
+    "title": { "type": "string" },
+    "type": { "type": "string" },
+    "priority": { "type": "string" },
+    "requirementIds": { "type": "array", "items": { "type": "string" } },
+    "route": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "path": { "type": "string" },
+        "auth": { "type": "string" }
+      }
+    },
+    "testIds": { "type": "object" },
+    "setup": { "type": "object" },
+    "data": { "type": "object" },
+    "steps": { "type": "array", "items": { "type": "object" } },
+    "assertions": { "type": "object" },
+    "expected": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/templates/shared/AUTHORING-COMMON.md

@@ -0,0 +1,109 @@
+# Hướng dẫn tạo Common Function / Pattern
+
+Tài liệu này hướng dẫn quy trình tiêu chuẩn để định nghĩa và thiết kế các thành phần dùng chung (Common) trong hệ thống FlowGrid bộ docs, bao gồm: UI Patterns, Backend Middlewares, API Functions, và các Business Rules.
+
+## 1. Phạm vi Common (bắt buộc)
+
+Đọc `.cursor/extracts/common-scope.md`. Đặt `common/` tại **thư mục thấp nhất mà mọi consumer dùng chung** (cluster → module → surface → `surfaces/common`). Nội bộ một module → `CMP-*/common/` (hoặc `CMP-*/NN/common/` nếu chỉ một cluster). Không dump hết vào `surfaces/common`.
+
+## 2. Phân loại các tầng Common
+
+Hệ thống hỗ trợ định nghĩa Common ở nhiều tầng khác nhau, phục vụ cho mọi loại Surface (Web Portal, HMI, Mobile, Gateway):
+
+- **UI / UX Patterns:** Các mẫu giao diện và tương tác (vd: `confirm-dialog`, `breadcrumb-flow`, `step-navigation`).
+- **Middlewares:** Các logic đánh chặn/xử lý trung gian (vd: `auth-guard`, `rate-limiter`, `tenant-context`).
+- **API Functions:** Các API dùng chung không phụ thuộc nghiệp vụ cụ thể (vd: `health-check`, `file-upload`, `master-data`).
+- **Business Rules:** Các quy tắc nghiệp vụ toàn cục (vd: quy tắc tính thuế, quy tắc làm tròn số).
+
+> **Lưu ý:** Thư mục template hiện tại (`templates/project-skeleton/surfaces/common/yaml/`) chủ yếu chứa các seed mẫu cho **UI Patterns** (Web CRUD). Hệ thống **chưa** có sẵn các seed mẫu cho tầng **Middlewares** hay **API Functions** (ngoại trừ pilot `API-CMN-HEALTH-001` trong thư mục `code/`). Bạn có thể tự do tạo mới chúng theo nhu cầu dự án bằng công cụ AI có sẵn.
+
+## 2. Quy trình thiết kế Common
+
+### Bước 1: Chọn LCA rồi scaffold `common/`
+- Nội bộ module: `/module CMP-… common` (hoặc `/module CMP-… 02 common` cho cluster).
+- Nhiều module một surface: `/surfaces <surface> common`.
+- Nhiều surface: `/surfaces common` → `surfaces/common`.
+
+### Bước 2: Định nghĩa Quy tắc Nghiệp vụ (Markdown)
+Dành cho BA / QA / Dev để thống nhất logic trên giấy tờ (Human-readable).
+```bash
+# Trong màn hình chat với Agent:
+/common
+```
+- **Mô tả yêu cầu:** "Tạo tài liệu common cho Middleware Auth, yêu cầu check token và tenant id."
+- **Kết quả:** `…/<LCA>/common/patterns/auth-middleware.md`.
+
+### Bước 3: Định nghĩa Kỹ thuật (YAML Bundle)
+Dành cho Dev để khai báo cấu trúc kỹ thuật, chuẩn bị cho CodeGen (Machine-readable).
+```bash
+# Trong màn hình chat với Agent:
+/common-spec
+```
+- **Mô tả yêu cầu:** "Viết technical bundle cho auth middleware vừa tạo."
+- **Kết quả:** `…/<LCA>/common/yaml/auth-middleware/auth-middleware.bundle.yaml`.
+
+### Bước 4: Kiểm duyệt Kỹ thuật (Audit)
+Trước khi sinh code, bạn có thể yêu cầu AI kiểm tra lại bundle:
+```bash
+/grill-common-spec
+```
+
+### Bước 5: Render và Tích hợp
+Sau khi có file YAML, chạy lệnh để sinh tài liệu Markdown cho toàn team đọc:
+```bash
+flowgrid split -- surfaces/<surface>/common/yaml/auth-middleware/auth-middleware.bundle.yaml
+---
+
+## 2.1 Quy tắc Chuẩn hóa Chất lượng khi Tạo Common
+Khi định nghĩa các Common Function / Pattern, BẮT BUỘC phải tuân thủ các chuẩn mới của hệ thống:
+- **Tầng UI / UX Pattern:** Mọi element (trường nhập, nút bấm, cột bảng) trong bundle BẮT BUỘC khai báo cả `meaning` (**Ý nghĩa nghiệp vụ**) và `purpose` (**Mục đích thao tác**). Nếu pattern có điều hướng, phải ghi rõ `screenAccess` (Direct, Sidebar Menu hay Contextual Button Action).
+- **Tầng Middleware / Backend API:** Phải có `sla` (`rateLimit`, `timeoutMs`) và `meaning` / `purpose` trên từng tham số request/response payload.
+- **Tầng Integration / Webhook:** Phải có `resilience` (`retryPolicy`, `dlqTopic`) và bảng `dataMapping` ánh xạ dữ liệu đối tác sang platform.
+
+---
+
+## 3. Quy trình thiết kế Common
+
+Khi bạn thiết kế một màn hình hoặc API cụ thể, bạn (hoặc AI) có thể tái sử dụng các Common đã định nghĩa:
+
+### Kế thừa UI Pattern
+Khai báo trong file `bundle.yaml` của màn hình (`design.patterns`):
+```yaml
+design:
+  patterns:
+    - "#pattern: confirm-dialog"
+```
+
+### Kế thừa API / Middleware
+Khai báo thẻ `#reuse-api` hoặc `#middleware` trong API spec để CodeGen tự động map route thay vì sinh code duplicate:
+```yaml
+spec:
+  api:
+    endpoints:
+      - id: get-profile
+        path: /api/v1/profile
+        tags:
+          - "#middleware: auth-middleware"
+```
+
+## 4. Tạo Project-Level Pattern Archetype (Tùy chọn)
+
+Nếu dự án có một nhóm các common thường xuyên đi chung với nhau (ví dụ: mọi webhook đều cần rate-limit, circuit-breaker, retry), bạn có thể tạo một file archetype:
+
+**File:** `surfaces/<surface>/common/patterns/webhook.pattern.yaml`
+```yaml
+schema: surface-pattern/v1
+id: gateway-webhook
+appliesWhen:
+  - webhook
+
+commonSpecs:
+  - yaml/common/rate-limit/common-rate-limit
+  - yaml/common/circuit-breaker/common-circuit-breaker
+  - yaml/common/webhook-retry/common-webhook-retry
+
+defaultTags:
+  - "#pattern: Webhook"
+  - "#shell: OtAdapter"
+```
+Khi dùng `/spec` để tạo webhook mới, AI sẽ tự động đọc file này và gợi ý chèn đầy đủ các common specs cần thiết.

package/templates/shared/api-contract-test.yaml

@@ -0,0 +1,33 @@
+# API contract test template (fast-api-base)
+
+# Round 1 — spec phase: đặt cạnh bundle `{id}.api-test.yaml`
+# Test phase: `testcases/{id}.api-test.yaml` (source of truth cho pytest)
+
+id: role-domain-function-contract
+title: Feature API contract
+type: api-contract
+feature: function-name
+
+contractRef:
+  portalIrSpec: surfaces/.../CMP-*/<slug>/code/W-*/ir/spec.yaml (or --id)
+
+backendSpec: backend/01-backend-spec.yaml
+
+assertions:
+  requestModel: FeatureRequest
+  responseModel: FeatureResponse
+
+expected:
+  - request/response field keys ⊆ portal entities
+
+# Optional HTTP smoke (pytest TestClient — sau /fast-code)
+# endpoint:
+#   method: POST
+#   path: /api/feature/action
+# setup:
+#   json:
+#     field: value
+# assertions:
+#   status: 200
+#   body:
+#     success: true

package/templates/shared/backend-api-integration.yaml

@@ -0,0 +1,152 @@
+feature:
+  id: integration-slug
+  title: Integration — Short title
+  status: draft
+  version: 0.1.0
+  source:
+    kind: webhook-inbound
+    # webhook-inbound | webhook-outbound | partner-api | public-api
+    base: none
+    updatedAt: YYYY-MM-DD
+    integrationRefs:
+      - id: provider-doc
+        type: provider-doc
+        path: docs/integrations/provider/events.md
+        syncedAt: null
+        status: pending
+      # - id: legacy-handler
+      #   type: legacy-code
+      #   path: <legacy-checkout>/app/Http/Controllers/WebhookController.php
+      #   syncedAt: null
+      #   status: pending
+    portalRefs: []
+    portalTestcaseRefs: []
+
+integrationBacklog: []
+# - id: IB-EVENT-002
+#   status: pending
+#   summary: Deferred event type
+#   expectedWhenDone:
+#     endpointIds: [integration.event-two]
+#     tags: ["#webhook-inbound"]
+
+beOnlyRequirements: []
+
+changeLog:
+  - id: CHG-INTEGRATION-001
+    source: integration-spec
+    summary: Initial partner/webhook contract.
+    impact:
+      - Define auth, endpoints, OpenAPI securitySchemes.
+    breaking: false
+
+decisions:
+  - id: DEC-INTEGRATION-001
+    summary: Verify HMAC before parsing body.
+    reason: Provider signature spec.
+
+tags: []
+# Round 1: domain only — #webhook-inbound, #call-external
+# Grill adds #gen:* — see api-codegen-readiness.md
+
+approval:
+  status: draft
+  reviewedBy: null
+  reviewedAt: null
+
+contexts:
+  portalLayout: none
+  routePrefixes: {}
+  actors:
+    - webhook-sender
+  auth:
+    - model: hmac-signature
+      header: X-Signature
+      notes: Document algorithm and secret env key in grill.
+
+modules:
+  - name: Integration
+    purpose: Inbound webhooks and partner-facing APIs.
+    entities:
+      - name: WebhookEvent
+        table: webhook_events
+        mode: Platform
+        aggregateRoot: false
+        fields:
+          - name: id
+            type: integer
+            readOnly: true
+          - name: external_id
+            type: string
+            purpose: Idempotency / dedup key from provider.
+
+api:
+  endpoints:
+    - id: integration.webhook
+      module: Integration
+      action: custom
+      method: POST
+      path: /webhooks/provider
+      purpose: "Hứng webhook kết quả sự kiện từ đối tác bên thứ 3 và đồng bộ vào hệ thống"
+      auth:
+        required: true
+        model: hmac-signature
+      idempotency:
+        required: true
+        key: external_event_id
+      sla:
+        rateLimit: "100req/min"
+        timeoutMs: 5000
+      asyncEvents:
+        - name: "ProviderWebhookReceived"
+          eventType: "integration.webhook.received"
+          topic: "webhooks.provider.events"
+      resilience:
+        timeoutMs: 5000
+        retryPolicy:
+          maxAttempts: 5
+          backoff: "exponential" # exponential | fixed
+          initialIntervalSec: 5
+        dlqTopic: "webhooks.provider.dlq"
+      dataMapping:
+        - externalField: "event_id"
+          internalField: "external_id"
+          meaning: "Mã định danh giao dịch duy nhất từ phía đối tác để chống trùng lặp"
+        - externalField: "status_code"
+          internalField: "payment_status"
+          meaning: "Trạng thái giao dịch phía đối tác được map sang enum hệ thống"
+          transformRule: "MAP: {'00': 'SUCCESS', '01': 'FAILED'}"
+      request: WebhookPayload
+      response: WebhookAck
+      onSpecificError:
+        - statusCode: 401
+          type: "UnauthorizedSignature"
+          action: "Từ chối request nếu HMAC signature không khớp"
+        - statusCode: 422
+          type: "InvalidPayload"
+          action: "Báo lỗi nếu thiếu trường bắt buộc event_id"
+      tags:
+        - "#webhook-inbound"
+
+externalCalls: []
+
+services: []
+
+requests:
+  WebhookPayload:
+    fields:
+      - name: id
+        type: string
+        meaning: "Mã sự kiện gửi từ đối tác"
+        purpose: "Định danh payload webhook"
+        rules:
+          - required
+
+responses:
+  WebhookAck:
+    fields:
+      - name: received
+        type: boolean
+        meaning: "Cờ xác nhận hệ thống đã nhận và lưu webhook thành công"
+        purpose: "Phản hồi HTTP 200 OK cho phía đối tác"
+

package/templates/shared/backend-api.bundle.yaml

@@ -0,0 +1,177 @@
+schema: portal-feature-bundle/v1
+id: role-domain-function
+title: Feature API
+status: draft
+owner: fast-team
+summary: Backend API bundle — mirror portal contract keys
+specOrigin: requirement
+
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+
+contractRef:
+  portalIrSpec: surfaces/.../CMP-*/<slug>/code/W-*/ir/spec.yaml (or --id)
+
+spec:
+  feature:
+    id: role-domain-function
+    title: Feature API
+    status: draft
+    version: 0.1.0
+  approval:
+    status: draft
+  api:
+    endpoints:
+      - id: feature.action
+        module: feature
+        action: action
+        method: POST
+        path: /feature/action
+        purpose: "Tiếp nhận và thực thi thao tác nghiệp vụ chính từ giao diện hoặc dịch vụ khác"
+        sla:
+          rateLimit: "100/min"
+          timeoutMs: 3000
+        dataIntegrity:
+          transactional: true
+          concurrencyControl:
+            strategy: "optimistic_locking" # optimistic_locking | pessimistic_locking | none
+            versionField: "updated_at"
+            onConflictStatus: 409
+            conflictMessage: "Dữ liệu vừa được cập nhật bởi một phiên làm việc khác. Vui lòng thử lại."
+        asyncEvents:
+          - name: "FeatureActionExecutedEvent"
+            topic: "feature.events"
+            meaning: "Bắn sự kiện ngầm khi thao tác hoàn tất để xử lý đồng bộ dữ liệu và gửi thông báo"
+        request: FeatureRequest
+        response: FeatureResponse
+        errorStorming:
+          - code: 401
+            tag: "#err:unauthorized"
+            reason: "User not authenticated"
+          - code: 403
+            tag: "#err:idor-violation"
+            reason: "Tenant IDOR violation or insufficient role permission"
+          - code: 409
+            tag: "#err:conflict"
+            reason: "Concurrent edit conflict or unique constraint violation"
+          - code: 422
+            tag: "#err:validation"
+            reason: "Invalid payload or boundary validation failure"
+            fields: ["record_code", "record_name"]
+  requests:
+    FeatureRequest:
+      fields:
+        - name: record_code
+          type: string
+          meaning: "Mã định danh duy nhất của hồ sơ"
+          purpose: "Nhập mã định danh duy nhất"
+          validation:
+            prototype: "slug_uppercase"
+            required: true
+            rules:
+              - type: "regex"
+                pattern: "^[A-Z0-9_-]{5,20}$"
+              - type: "length"
+                min: 5
+                max: 20
+            uniqueCheck:
+              scope: "tenant_id"
+              table: "records"
+              column: "code"
+        - name: record_name
+          type: string
+          meaning: "Tên định danh hiển thị của hồ sơ"
+          purpose: "Nhập tên hồ sơ"
+          validation:
+            prototype: "text_clean"
+            required: true
+            rules:
+              - type: "length"
+                min: 3
+                max: 100
+  responses:
+    FeatureResponse:
+      fields:
+        - name: result
+          type: string
+          meaning: "Mã trạng thái hoặc kết quả đầu ra chính thức của giao dịch"
+          purpose: "Trả về kết quả phản hồi cho caller"
+
+gen:
+  codegen:
+    module: feature
+    entity: FeatureAction
+    profile: command-stub # REQUIRED: auth | select-item | free | setting | export | import | dashboard-stats | list | create | edit | detail | admin-crud | command-stub
+    skip: []
+
+legacy:
+  legacyRef: null
+  behaviors: []
+  fields: []
+  ui: []
+  evidence: []
+  refs: {}
+
+design:
+  inherits: null
+  shell:
+    tag: "#shell: ApiModule"
+  patterns: []
+  zones: []
+  behavior: {}
+  actions:
+    - id: feature.action
+      label: Execute Feature Action
+      trigger: button_click
+      apiRefs: [ feature.action ]
+      onSuccess:
+        - Show success toast
+      onCommonError:
+        override: false
+      onSpecificError:
+        - condition: "422 Validation"
+          notes: "Show inline validation errors"
+
+  # Đa ngôn ngữ (i18n): Danh sách các bản dịch của error/validation messages trả về từ Backend (nếu có).
+  # LƯU Ý: Email/SMS content lưu trong DB. Enum trả về số (1, 2) để FE tự dịch.
+  i18n: {}
+  #  "error_invalid_email":
+  #    vi: "Email không hợp lệ"
+  #    en: "Invalid email"
+
+review:
+  summary: Backend stub for portal wire
+  layoutNotes: []
+
+
+# --- platform-mark (member / grill — not /fast-spec) ---
+marks: []
+# - id: MK-AUTH-ROLES-001
+#   kind: common
+#   tag: "#common:auth-current-roles"
+#   registryId: auth.current-roles
+#   reason: "Promote role lookup"
+#   source: platform-mark
+
+technicalMarks: []
+# - kind: derived-data
+#   tag: "#derived-data"
+#   derivedData:
+#     backendOnly: true
+#     field: search_text
+#     sourceOfTruth: content
+#     refresh: on_write
+
+externalCalls: []
+# - id: mes.fetchDowntime
+#   provider: integration-base
+#   direction: outbound
+#   trigger: GET /maintenance/downtime
+
+services: []
+# - id: order.fulfillBoth
+#   reason: Two independent aggregates
+#   alternativesConsidered: []

package/templates/shared/backend-api.yaml

@@ -0,0 +1,188 @@
+feature:
+  id: feature-slug
+  title: Feature Title
+  status: draft
+  version: 0.1.0
+  source:
+    portalSpec: surfaces/.../CMP-*/<NN…>/ir/design.yaml
+    portalTestcases: https://github.com/raintr91/base_test/tree/main/cases
+    updatedAt: YYYY-MM-DD
+    portalRefs: []
+    # - id: feature-list
+    #   path: surfaces/.../CMP-*/<slug>/code/W-*/ir/spec.yaml
+    #   syncedAt: YYYY-MM-DD
+    #   status: synced   # synced | stale | pending
+    portalTestcaseRefs: []
+
+pendingTechDebt: []
+# - id: TD-FEATURE-EXPORT
+#   status: pending
+#   source: portal
+#   portalRef: feature-export
+#   portalRequirementIds: [REQ-...]
+#   summary: POST /entities/export — deferred to api-update
+#   expectedWhenDone:
+#     endpointIds: [feature.export]
+#     tags: ["#manual-service:export-entities"]
+#     action: custom
+
+beOnlyRequirements: []
+# BE-only changes — /api-update --be-only; feImpact: none
+
+changeLog:
+  - id: CHG-FEATURE-001
+    source: initial-backend-analysis
+    summary: Initial backend API contract.
+    impact:
+      - Create initial endpoint, entity, OpenAPI, and mock data plan.
+    breaking: false
+
+decisions:
+  - id: DEC-FEATURE-001
+    summary: Reuse detail endpoint for detail page and edit initial form data.
+    reason: Same permission, response shape, and lifecycle.
+
+tags: []
+
+approval:
+  status: draft
+  reviewedBy: null
+  reviewedAt: null
+
+codegen:
+  module: Admin
+  entity: FeatureEntity
+  pathModel: Tenant
+  sharedModel: true
+  profile: crud-standard
+  wire:
+    search: true
+    detail: true
+    create: true
+    update: false
+    delete: false
+    selectItems: false
+  skip: []
+  commands: []
+
+contexts:
+  portalLayout: single-portal
+  routePrefixes:
+    admin: /admin
+  actors:
+    - admin
+
+modules:
+  - name: Admin
+    purpose: Feature APIs for admin users.
+    entities:
+      - name: FeatureEntity
+        table: feature_entities
+        mode: Tenant
+        aggregateRoot: true
+        fields:
+          - name: id
+            type: integer
+            readOnly: true
+          - name: name
+            type: string
+            required: true
+        relationships: []
+
+api:
+  endpoints:
+    - id: feature.search
+      module: Admin
+      action: search
+      method: GET
+      path: /admin/features/list
+      purpose: List feature entities for the index screen.
+      reusedBy:
+        - /features
+      auth:
+        required: true
+        permissions: []
+      query:
+        pagination: true
+        filters:
+          - name
+        sorts:
+          - created_at
+        includes: []
+      request: null
+      response: FeatureEntityCollection
+      errorStorming:
+        - code: 401
+          tag: "#err:unauthorized"
+          reason: "User not authenticated"
+        - code: 403
+          tag: "#err:permission-denied"
+          reason: "User lacks permission to search features"
+      tags: []
+      externalCallRefs: []
+      serviceRefs: []
+
+externalCalls: []
+# Use only with #call-external.
+# Example:
+# - id: payment.createIntent
+#   provider: Stripe
+#   direction: outbound
+#   trigger: POST /admin/orders/{id}/pay
+#   purpose: Create payment intent.
+#   service: Modules\Order\Services\Payment\CreatePaymentIntentService
+#   timeoutMs: 10000
+#   retry:
+#     enabled: false
+#     reason: Payment retry requires idempotency.
+#   idempotency:
+#     required: true
+#     key: order_payment_attempt_id
+#   secrets:
+#     - PAYMENT_PROVIDER_SECRET
+
+services: []
+# Use only with #cross-entity-service.
+# Example:
+# - id: chain.activateWithDefaultStore
+#   class: Modules\Chain\Services\ActivateChainWithDefaultStoreService
+#   reason: Chain and Store are independent aggregates but must be activated in one operation.
+#   alternativesConsidered:
+#     - Eloquent relationship: not applicable
+#     - Event/Observer/Job: rejected because FE needs synchronous result
+#     - Split APIs: rejected because operation must be atomic
+#   entities:
+#     - Chain
+#     - Store
+
+requests:
+  FeatureEntityCreateRequest:
+    fields:
+      - name: name
+        type: string
+        rules:
+          - required
+          - string
+          - max:255
+
+responses:
+  FeatureEntityResource:
+    fields:
+      - name: id
+        type: integer
+      - name: name
+        type: string
+
+implementationPlan:
+  deprecated: Use codegen.commands — populated by pnpm api:gen:dry --write-spec
+  notes:
+    - Generators run in the BE checkout, not this docs hub.
+    - Codegen tags: .cursor/extracts/codegen/tags.md
+
+# pending only until member answers via AskQuestion — never a self-written decision string
+# - id: OQ-ownership
+#   status: pending
+#   question: "Platform vs Tenant ownership?"
+#   options: ["Platform", "Tenant"]
+#   recommended: "Tenant"
+#   decision: null