@shanyucoder/flowgrid 0.1.0

package/templates/project-skeleton/surfaces/common/yaml/data-table/ir/spec.yaml

@@ -0,0 +1,56 @@
+# Generated from common-data-table.bundle.yaml — pnpm spec:split
+id: common-data-table
+title: Common data table
+status: draft
+owner: portal-team
+summary: Chuẩn table dữ liệu cho admin portal, tối ưu màn nhiều cột, giữ row cân bằng và action dễ thao tác.
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+layout:
+  container:
+    - Table phải nằm trong container có horizontal overflow khi nhiều cột.
+    - Không ép table co cột quá nhỏ khiến text wrap tự do.
+  table:
+    density: compact
+    minWidth: page hoặc component quyết định theo số cột
+    header: background muted nhẹ, text semibold
+    row:
+      height: 40-48px mặc định
+      hover: background muted/nhẹ
+      striped: optional, chỉ dùng khi page spec yêu cầu hoặc table nhiều dòng dễ đọc hơn
+  cell:
+    padding: px-3 py-2
+    defaultOverflow: truncate-tooltip
+    defaultAlign: left
+columns:
+  reserved:
+    action:
+      width: fixed
+      overflow: nowrap
+      sticky: optional khi table rất rộng
+    status:
+      width: compact
+      renderer: status-chip
+    id:
+      overflow: nowrap
+    date:
+      overflow: nowrap
+    numeric:
+      align: right
+overflowModes:
+  nowrap: Không xuống dòng, dùng cho ID/code/date/status/action.
+  truncate-tooltip: Một dòng, ellipsis, hover/focus xem full text; default cho name/email/url/title ngắn.
+  wrap-2-lines: Tối đa 2 dòng, dùng cho subject/title cần đọc thêm nhưng không phá row.
+  wrap-free: Chỉ dùng cho nội dung dài thật sự như message body/note/report detail, không dùng mặc định trong list.
+testIds:
+  table: "{module}-table"
+  row: "{module}-row"
+  cell: optional "{module}-{column}-cell"
+acceptance:
+  - Text dài không làm row cao bất thường nếu column không khai báo wrap.
+  - Cell bị truncate có title/tooltip hoặc cơ chế xem full text khi hover/focus.
+  - Table nhiều cột ưu tiên horizontal scroll hơn wrap làm vỡ layout.

package/templates/project-skeleton/surfaces/common/yaml/delete-flow/common-delete-flow.bundle.yaml

@@ -0,0 +1,59 @@
+schema: portal-feature-bundle/v1
+id: common-delete-flow
+title: Common delete flow
+status: draft
+owner: portal-team
+summary: Delete và bulk delete luôn dùng confirm dialog chặn + result dialog — không toast-only.
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+spec:
+  principles:
+    - Confirm trước delete — blocking modal, user phải chọn cancel hoặc confirm.
+    - Sau delete — success hoặc error đều qua result dialog blocking; user acknowledge trước khi tiếp tục.
+    - Không dùng toast/inline alert làm phản hồi duy nhất cho delete.
+  references:
+    - docs/features/common/common-confirm-dialog.spec.yaml
+    - docs/features/common/common-feedback.spec.yaml
+    - .cursor/extracts/common-delete-flow.md
+  flow:
+    - step: confirm
+      ui: AlertDialog blocking
+      copy: theo object (single / bulk)
+    - step: api
+      onSuccess: result dialog success
+      onError: result dialog error
+  grill:
+    bqa: copy confirm, button labels, navigation sau delete
+    dev: endpoint, bulk vs single, wire-only nếu API chưa có
+legacy:
+  legacyRef:
+    module: common/common
+    function: common-delete-flow
+    slice: slices.common-delete-flow
+  behaviors: []
+  fields: []
+  ui: []
+  evidence: []
+  refs: {}
+design:
+  inherits: admin-crud
+  shell:
+    tag: "#shell: DataPage"
+    overrideCommonPattern: false
+  patterns:
+    - "#pattern: CRUD"
+  zones:
+    - id: main
+      label: Nội dung chính
+  behavior: {}
+  actions: []
+review:
+  summary: Delete và bulk delete luôn dùng confirm dialog chặn + result dialog — không toast-only.
+  layoutNotes: []
+_meta:
+  generatedBy: archived-legacy-converter
+  sourceRevision: null

package/templates/project-skeleton/surfaces/common/yaml/delete-flow/ir/design.yaml

@@ -0,0 +1,13 @@
+# Generated from common-delete-flow.bundle.yaml — pnpm spec:split
+id: common-delete-flow
+inherits: admin-crud
+shell:
+  tag: "#shell: DataPage"
+  overrideCommonPattern: false
+patterns:
+  - "#pattern: CRUD"
+zones:
+  - id: main
+    label: Nội dung chính
+behavior: {}
+actions: []

package/templates/project-skeleton/surfaces/common/yaml/delete-flow/ir/legacy.yaml

@@ -0,0 +1,11 @@
+# Generated from common-delete-flow.bundle.yaml — pnpm spec:split
+id: common-delete-flow
+legacyRef:
+  module: common/common
+  function: common-delete-flow
+  slice: slices.common-delete-flow
+behaviors: []
+fields: []
+ui: []
+evidence: []
+refs: {}

package/templates/project-skeleton/surfaces/common/yaml/delete-flow/ir/spec.yaml

@@ -0,0 +1,30 @@
+# Generated from common-delete-flow.bundle.yaml — pnpm spec:split
+id: common-delete-flow
+title: Common delete flow
+status: draft
+owner: portal-team
+summary: Delete và bulk delete luôn dùng confirm dialog chặn + result dialog — không toast-only.
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+principles:
+  - Confirm trước delete — blocking modal, user phải chọn cancel hoặc confirm.
+  - Sau delete — success hoặc error đều qua result dialog blocking; user acknowledge trước khi tiếp tục.
+  - Không dùng toast/inline alert làm phản hồi duy nhất cho delete.
+references:
+  - docs/features/common/common-confirm-dialog.spec.yaml
+  - docs/features/common/common-feedback.spec.yaml
+  - .cursor/extracts/common-delete-flow.md
+flow:
+  - step: confirm
+    ui: AlertDialog blocking
+    copy: theo object (single / bulk)
+  - step: api
+    onSuccess: result dialog success
+    onError: result dialog error
+grill:
+  bqa: copy confirm, button labels, navigation sau delete
+  dev: endpoint, bulk vs single, wire-only nếu API chưa có

package/templates/project-skeleton/surfaces/common/yaml/design-system.bundle.yaml

@@ -0,0 +1,29 @@
+id: design-system-spec
+name: Common Design System (SSOT)
+specOrigin: requirement
+summary:
+  - Global SSOT for UI Metrics and Design Tokens (Typography, Colors, Radii, Spacing).
+  - All feature specs must inherit from these defaults unless an explicit override is requested by Business/BQA.
+  - "Devs: Use Shadcn/Tailwind global config to implement these tokens."
+  - "Testers: Use this document to validate default UI sizes and colors when not explicitly stated in feature specs."
+design:
+  visual:
+    typography:
+      baseFontSize: "16px"
+      smallFontSize: "14px"
+      heading1: "32px"
+      heading2: "24px"
+      fontFamily: "Inter, sans-serif"
+    colors:
+      primary: "Tailwind Blue 600 (#2563eb)"
+      secondary: "Tailwind Slate 500 (#64748b)"
+      background: "White (#ffffff)"
+      textPrimary: "Tailwind Slate 900 (#0f172a)"
+      textSecondary: "Tailwind Slate 500 (#64748b)"
+    spacing:
+      base: "16px"
+      small: "8px"
+      large: "24px"
+    radius:
+      base: "8px"
+      small: "4px"

package/templates/project-skeleton/surfaces/common/yaml/feedback/common-feedback.bundle.yaml

@@ -0,0 +1,126 @@
+schema: portal-feature-bundle/v1
+id: common-feedback
+title: Common feedback and alerts
+status: draft
+owner: portal-team
+summary: Chuẩn loading, empty, error, success feedback trong admin portal.
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+spec:
+  principles:
+    - Không lạm dụng modal/alert lớn; ưu tiên inline feedback gần nơi xảy ra action.
+    - Giao diện phẳng: border + background nhạt, không gradient/shadow.
+    - Feedback phải đến từ service/composable state, không chỉ đổi text local.
+    - Legacy dùng alert/dialog tùy hứng thì chỉ xem là evidence; project mới ưu tiên common placement.
+  terminology:
+    inlineAlert:
+      definition: Thông báo nằm trong page/block, không tự mất.
+      dismissal: Giữ nguyên cho đến khi user có action khác như submit lại, clear, refresh hoặc đổi route.
+      useFor:
+        - lỗi validation/global form
+        - lỗi tải dữ liệu page
+        - cảnh báo cần user đọc trước khi thao tác tiếp
+    alertToast:
+      definition: Thông báo nổi không có action confirm/cancel, tự biến mất sau timeout.
+      defaultDuration: 5s
+      stacking:
+        topPlacement: alert mới xuất hiện phía dưới hoặc tại đầu stack, alert cũ được đẩy lên theo animation.
+        bottomPlacement: không dùng mặc định; nếu override thì alert cũ bị đẩy xuống.
+      useFor:
+        - success sau mutation nhẹ
+        - thông báo hệ thống không cần chặn thao tác
+    actionModal:
+      definition: Dialog có button action hoặc close, chặn tương tác background cho đến khi user bấm confirm/cancel/close.
+      ownerSpec: common-confirm-dialog
+  placement:
+    defaultPageAlert:
+      position: ngay dưới page title/page header
+      surface: nền phẳng cùng content, border + background nhạt
+      useFor:
+        - lỗi tải dữ liệu page
+        - success/error sau mutation khi user vẫn ở cùng page
+        - cảnh báo điều kiện thao tác không destructive
+    contextualAlert:
+      position: gần block phát sinh lỗi
+      useFor:
+        - table list error
+        - form global error
+        - import file error
+    alertDialog:
+      useOnlyWhen:
+        - page dài phải scroll và inline alert có thể khuất khỏi viewport
+        - thông báo không cần confirm/cancel action
+      placement: top-right of viewport/page
+      avoid:
+        - center modal cho alert thông thường không có action
+        - bottom modal/toast kiểu legacy nếu không có lý do mới
+      note: Nếu dialog có button hành động như confirm/delete/overwrite/cancel thì dùng `common-confirm-dialog` và hiển thị giữa màn hình.
+  patterns:
+    loading:
+      list: skeleton rows hoặc skeleton cards trong table body area
+      form: disable submit và đổi label pending nếu cần
+    empty:
+      list: empty state trong table body, không xóa toolbar/search
+      copy: "{entity}が見つかりません。"
+    error:
+      list: alert trên table body area
+      formGlobal: alert trên form/card
+      importFile: alert trên import card, giữ message cụ thể từ validation
+    success:
+      mutation: inline success alert hoặc toast global, chọn một theo page; không dùng modal success.
+  alertStyle:
+    error:
+      border: destructive/30
+      background: destructive/10
+      text: destructive
+    success:
+      border: success/30 hoặc primary/30
+      background: success/10 hoặc primary/10
+    warning:
+      border: warning/30
+      background: warning/10
+  testIds:
+    loading: "{module}-loading"
+    empty: "{module}-empty"
+    errorAlert: "{module}-error-alert"
+    successAlert: "{module}-success-alert"
+  acceptance:
+    - Empty/error/loading states không làm layout nhảy mất search/toolbar.
+    - Alert copy là tiếng Nhật UI, spec/note có thể tiếng Việt.
+    - Không dùng modal cho lỗi validation thông thường.
+    - Alert thông thường xuất hiện dưới page title/page header hoặc trong block liên quan, không đẩy vào dialog.
+    - Alert dialog không có action nếu bắt buộc phải ở góc phải phía trên và có reason trong page spec.
+    - Dialog có action confirm/cancel không theo alert placement; dùng common confirm dialog ở giữa màn hình.
+    - Alert toast tự mất sau timeout mặc định 5s; inline alert không tự mất.
+legacy:
+  legacyRef:
+    module: common/common
+    function: common-feedback
+    slice: slices.common-feedback
+  behaviors: []
+  fields: []
+  ui: []
+  evidence: []
+  refs: {}
+design:
+  inherits: admin-crud
+  shell:
+    tag: "#shell: DataPage"
+    overrideCommonPattern: false
+  patterns:
+    - "#pattern: CRUD"
+  zones:
+    - id: main
+      label: Nội dung chính
+  behavior: {}
+  actions: []
+review:
+  summary: Chuẩn loading, empty, error, success feedback trong admin portal.
+  layoutNotes: []
+_meta:
+  generatedBy: archived-legacy-converter
+  sourceRevision: null

package/templates/project-skeleton/surfaces/common/yaml/feedback/ir/design.yaml

@@ -0,0 +1,13 @@
+# Generated from common-feedback.bundle.yaml — pnpm spec:split
+id: common-feedback
+inherits: admin-crud
+shell:
+  tag: "#shell: DataPage"
+  overrideCommonPattern: false
+patterns:
+  - "#pattern: CRUD"
+zones:
+  - id: main
+    label: Nội dung chính
+behavior: {}
+actions: []

package/templates/project-skeleton/surfaces/common/yaml/feedback/ir/legacy.yaml

@@ -0,0 +1,11 @@
+# Generated from common-feedback.bundle.yaml — pnpm spec:split
+id: common-feedback
+legacyRef:
+  module: common/common
+  function: common-feedback
+  slice: slices.common-feedback
+behaviors: []
+fields: []
+ui: []
+evidence: []
+refs: {}

package/templates/project-skeleton/surfaces/common/yaml/feedback/ir/spec.yaml

@@ -0,0 +1,97 @@
+# Generated from common-feedback.bundle.yaml — pnpm spec:split
+id: common-feedback
+title: Common feedback and alerts
+status: draft
+owner: portal-team
+summary: Chuẩn loading, empty, error, success feedback trong admin portal.
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+principles:
+  - Không lạm dụng modal/alert lớn; ưu tiên inline feedback gần nơi xảy ra action.
+  - Giao diện phẳng: border + background nhạt, không gradient/shadow.
+  - Feedback phải đến từ service/composable state, không chỉ đổi text local.
+  - Legacy dùng alert/dialog tùy hứng thì chỉ xem là evidence; project mới ưu tiên common placement.
+terminology:
+  inlineAlert:
+    definition: Thông báo nằm trong page/block, không tự mất.
+    dismissal: Giữ nguyên cho đến khi user có action khác như submit lại, clear, refresh hoặc đổi route.
+    useFor:
+      - lỗi validation/global form
+      - lỗi tải dữ liệu page
+      - cảnh báo cần user đọc trước khi thao tác tiếp
+  alertToast:
+    definition: Thông báo nổi không có action confirm/cancel, tự biến mất sau timeout.
+    defaultDuration: 5s
+    stacking:
+      topPlacement: alert mới xuất hiện phía dưới hoặc tại đầu stack, alert cũ được đẩy lên theo animation.
+      bottomPlacement: không dùng mặc định; nếu override thì alert cũ bị đẩy xuống.
+    useFor:
+      - success sau mutation nhẹ
+      - thông báo hệ thống không cần chặn thao tác
+  actionModal:
+    definition: Dialog có button action hoặc close, chặn tương tác background cho đến khi user bấm confirm/cancel/close.
+    ownerSpec: common-confirm-dialog
+placement:
+  defaultPageAlert:
+    position: ngay dưới page title/page header
+    surface: nền phẳng cùng content, border + background nhạt
+    useFor:
+      - lỗi tải dữ liệu page
+      - success/error sau mutation khi user vẫn ở cùng page
+      - cảnh báo điều kiện thao tác không destructive
+  contextualAlert:
+    position: gần block phát sinh lỗi
+    useFor:
+      - table list error
+      - form global error
+      - import file error
+  alertDialog:
+    useOnlyWhen:
+      - page dài phải scroll và inline alert có thể khuất khỏi viewport
+      - thông báo không cần confirm/cancel action
+    placement: top-right of viewport/page
+    avoid:
+      - center modal cho alert thông thường không có action
+      - bottom modal/toast kiểu legacy nếu không có lý do mới
+    note: Nếu dialog có button hành động như confirm/delete/overwrite/cancel thì dùng `common-confirm-dialog` và hiển thị giữa màn hình.
+patterns:
+  loading:
+    list: skeleton rows hoặc skeleton cards trong table body area
+    form: disable submit và đổi label pending nếu cần
+  empty:
+    list: empty state trong table body, không xóa toolbar/search
+    copy: "{entity}が見つかりません。"
+  error:
+    list: alert trên table body area
+    formGlobal: alert trên form/card
+    importFile: alert trên import card, giữ message cụ thể từ validation
+  success:
+    mutation: inline success alert hoặc toast global, chọn một theo page; không dùng modal success.
+alertStyle:
+  error:
+    border: destructive/30
+    background: destructive/10
+    text: destructive
+  success:
+    border: success/30 hoặc primary/30
+    background: success/10 hoặc primary/10
+  warning:
+    border: warning/30
+    background: warning/10
+testIds:
+  loading: "{module}-loading"
+  empty: "{module}-empty"
+  errorAlert: "{module}-error-alert"
+  successAlert: "{module}-success-alert"
+acceptance:
+  - Empty/error/loading states không làm layout nhảy mất search/toolbar.
+  - Alert copy là tiếng Nhật UI, spec/note có thể tiếng Việt.
+  - Không dùng modal cho lỗi validation thông thường.
+  - Alert thông thường xuất hiện dưới page title/page header hoặc trong block liên quan, không đẩy vào dialog.
+  - Alert dialog không có action nếu bắt buộc phải ở góc phải phía trên và có reason trong page spec.
+  - Dialog có action confirm/cancel không theo alert placement; dùng common confirm dialog ở giữa màn hình.
+  - Alert toast tự mất sau timeout mặc định 5s; inline alert không tự mất.

package/templates/project-skeleton/surfaces/common/yaml/flat-design/common-flat-design.bundle.yaml

@@ -0,0 +1,77 @@
+schema: portal-feature-bundle/v1
+id: common-flat-design
+title: Common flat design foundation
+status: draft
+owner: portal-team
+summary: "Nền tảng visual chung: phẳng, rõ phân cấp, tránh hiệu ứng 3D và giữ cảm giác shadcn/admin hiện đại."
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+spec:
+  principles:
+    - Ưu tiên border, background nhạt, spacing và typography để tạo hierarchy.
+    - Không dùng gradient cho button/card/alert trong admin portal.
+    - Không dùng shadow nặng; shadow nhẹ chỉ dùng cho overlay nổi như dropdown/dialog nếu cần.
+    - Không lạm dụng modal/alert; dùng inline state gần ngữ cảnh.
+    - Không thiết kế modal chồng modal; flow phức tạp phải chuyển thành page/step/inline section hoặc đóng modal hiện tại trước.
+    - Màu semantic phải có ý nghĩa: success, danger, warning, info, muted.
+  surfaces:
+    pageBackground: neutral/muted nhẹ
+    card:
+      style: border + bg-card/bg-white
+      shadow: none hoặc very subtle
+      radius: md
+    table:
+      style: border hoặc background separation nhẹ
+    dialog:
+      style: phẳng, border, overlay tối nhẹ
+  buttons:
+    complete:
+      background: "#48b0f7"
+      text: "#ffffff"
+    outlinePrimary:
+      border: "#4EAAFF"
+      text: "#4EAAFF"
+      background: "#FFFFFF"
+    outlineSecondary:
+      border: "#C2C2C2"
+      text: "#C2C2C2"
+      background: "#FFFFFF"
+    destructive:
+      purpose: chỉ dùng cho delete/error/destructive
+  acceptance:
+    - Component mới không thêm gradient hoặc shadow nặng.
+    - Visual state dựa vào token/variant chung, không hardcode tùy hứng nếu đã có common variant.
+    - Page legacy tùy hứng về visual phải được normalize về flat design trừ khi có lý do nghiệp vụ.
+    - Spec/prototype không tạo nested modal.
+legacy:
+  legacyRef:
+    module: common/common
+    function: common-flat-design
+    slice: slices.common-flat-design
+  behaviors: []
+  fields: []
+  ui: []
+  evidence: []
+  refs: {}
+design:
+  inherits: admin-crud
+  shell:
+    tag: "#shell: DataPage"
+    overrideCommonPattern: false
+  patterns:
+    - "#pattern: CRUD"
+  zones:
+    - id: main
+      label: Nội dung chính
+  behavior: {}
+  actions: []
+review:
+  summary: "Nền tảng visual chung: phẳng, rõ phân cấp, tránh hiệu ứng 3D và giữ cảm giác shadcn/admin hiện đại."
+  layoutNotes: []
+_meta:
+  generatedBy: archived-legacy-converter
+  sourceRevision: null

package/templates/project-skeleton/surfaces/common/yaml/flat-design/ir/design.yaml

@@ -0,0 +1,13 @@
+# Generated from common-flat-design.bundle.yaml — pnpm spec:split
+id: common-flat-design
+inherits: admin-crud
+shell:
+  tag: "#shell: DataPage"
+  overrideCommonPattern: false
+patterns:
+  - "#pattern: CRUD"
+zones:
+  - id: main
+    label: Nội dung chính
+behavior: {}
+actions: []

package/templates/project-skeleton/surfaces/common/yaml/flat-design/ir/legacy.yaml

@@ -0,0 +1,11 @@
+# Generated from common-flat-design.bundle.yaml — pnpm spec:split
+id: common-flat-design
+legacyRef:
+  module: common/common
+  function: common-flat-design
+  slice: slices.common-flat-design
+behaviors: []
+fields: []
+ui: []
+evidence: []
+refs: {}

package/templates/project-skeleton/surfaces/common/yaml/flat-design/ir/spec.yaml

@@ -0,0 +1,48 @@
+# Generated from common-flat-design.bundle.yaml — pnpm spec:split
+id: common-flat-design
+title: Common flat design foundation
+status: draft
+owner: portal-team
+summary: "Nền tảng visual chung: phẳng, rõ phân cấp, tránh hiệu ứng 3D và giữ cảm giác shadcn/admin hiện đại."
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+principles:
+  - Ưu tiên border, background nhạt, spacing và typography để tạo hierarchy.
+  - Không dùng gradient cho button/card/alert trong admin portal.
+  - Không dùng shadow nặng; shadow nhẹ chỉ dùng cho overlay nổi như dropdown/dialog nếu cần.
+  - Không lạm dụng modal/alert; dùng inline state gần ngữ cảnh.
+  - Không thiết kế modal chồng modal; flow phức tạp phải chuyển thành page/step/inline section hoặc đóng modal hiện tại trước.
+  - Màu semantic phải có ý nghĩa: success, danger, warning, info, muted.
+surfaces:
+  pageBackground: neutral/muted nhẹ
+  card:
+    style: border + bg-card/bg-white
+    shadow: none hoặc very subtle
+    radius: md
+  table:
+    style: border hoặc background separation nhẹ
+  dialog:
+    style: phẳng, border, overlay tối nhẹ
+buttons:
+  complete:
+    background: "#48b0f7"
+    text: "#ffffff"
+  outlinePrimary:
+    border: "#4EAAFF"
+    text: "#4EAAFF"
+    background: "#FFFFFF"
+  outlineSecondary:
+    border: "#C2C2C2"
+    text: "#C2C2C2"
+    background: "#FFFFFF"
+  destructive:
+    purpose: chỉ dùng cho delete/error/destructive
+acceptance:
+  - Component mới không thêm gradient hoặc shadow nặng.
+  - Visual state dựa vào token/variant chung, không hardcode tùy hứng nếu đã có common variant.
+  - Page legacy tùy hứng về visual phải được normalize về flat design trừ khi có lý do nghiệp vụ.
+  - Spec/prototype không tạo nested modal.

package/templates/project-skeleton/surfaces/common/yaml/form-validation/common-form-validation.bundle.yaml

@@ -0,0 +1,66 @@
+schema: portal-feature-bundle/v1
+id: common-form-validation
+title: Common form validation
+status: draft
+owner: portal-team
+summary: Chuẩn vị trí, copy và state validation cho form admin portal.
+specOrigin: legacy
+grillStatus:
+  bqaFacts: draft
+  bqaOpen: draft
+  dev: draft
+  full: not_required
+spec:
+  fieldErrors:
+    position: ngay dưới field/input liên quan
+    style: text destructive, cỡ nhỏ, không dùng alert global cho lỗi field đơn lẻ
+    testId: "{module}-{field}-error"
+  globalErrors:
+    position: trên form/card hoặc gần submit group
+    useFor:
+      - lỗi file import
+      - lỗi server không map được field
+      - timeout/expired session của flow import/preview
+    testId: "{module}-error-alert"
+  requiredMarker:
+    default: optional
+    whenUsed: dấu `*` đỏ cạnh label, không thêm text dài.
+  pendingState:
+    submitDisabled: true
+    labelCanChange: true
+    fieldsDisabled: chỉ khi action cần lock form để tránh double submit
+  copy:
+    source: Ưu tiên message Laravel ja/validation.php khi đã có legacy/API source.
+    language: Japanese UI copy.
+  acceptance:
+    - Field validation không gom hết lên đầu nếu field cụ thể đã xác định được.
+    - File/import/global validation được phép dùng alert trên card.
+    - Error testId đủ để E2E assert message quan trọng.
+legacy:
+  legacyRef:
+    module: common/common
+    function: common-form-validation
+    slice: slices.common-form-validation
+  behaviors: []
+  fields: []
+  ui: []
+  evidence: []
+  refs: {}
+design:
+  inherits: admin-crud
+  shell:
+    tag: "#shell: DataPage"
+    overrideCommonPattern: false
+  patterns:
+    - "#pattern: CRUD"
+  zones:
+    - id: main
+      label: Nội dung chính
+  behavior: {}
+  actions: []
+review:
+  summary: Chuẩn vị trí, copy và state validation cho form admin portal.
+  layoutNotes: []
+_meta:
+  generatedBy: archived-legacy-converter
+  sourceRevision: null