@shanyucoder/flowgrid 0.1.0

package/templates/project-skeleton/surfaces/common/md/data-table/common-data-table.md

@@ -0,0 +1,91 @@
+# Common data table
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+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.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## layout
+
+```yaml
+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
+
+```yaml
+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
+
+```yaml
+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
+
+```yaml
+table: "{module}-table"
+row: "{module}-row"
+cell: optional "{module}-{column}-cell"
+```
+
+
+## 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/delete-flow/common-delete-flow.md

@@ -0,0 +1,68 @@
+# Common delete flow
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Delete và bulk delete luôn dùng confirm dialog chặn + result dialog — không toast-only.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## principles
+
+```yaml
+- 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
+
+```yaml
+- docs/features/common/common-confirm-dialog.spec.yaml
+- docs/features/common/common-feedback.spec.yaml
+- .cursor/extracts/common-delete-flow.md
+```
+
+## flow
+
+```yaml
+- step: confirm
+  ui: AlertDialog blocking
+  copy: theo object (single / bulk)
+- step: api
+  onSuccess: result dialog success
+  onError: result dialog error
+```
+
+## grill
+
+```yaml
+bqa: copy confirm, button labels, navigation sau delete
+dev: endpoint, bulk vs single, wire-only nếu API chưa có
+```
+
+
+## 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/feedback/common-feedback.md

@@ -0,0 +1,140 @@
+# Common feedback and alerts
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn loading, empty, error, success feedback trong admin portal.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## principles
+
+```yaml
+- 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
+
+```yaml
+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
+
+```yaml
+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
+
+```yaml
+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
+
+```yaml
+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
+
+```yaml
+loading: "{module}-loading"
+empty: "{module}-empty"
+errorAlert: "{module}-error-alert"
+successAlert: "{module}-success-alert"
+```
+
+
+## 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/flat-design/common-flat-design.md

@@ -0,0 +1,78 @@
+# Common flat design foundation
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+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.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## principles
+
+```yaml
+- Ư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
+
+```yaml
+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
+
+```yaml
+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
+```
+
+
+## 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/form-validation/common-form-validation.md

@@ -0,0 +1,74 @@
+# Common form validation
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn vị trí, copy và state validation cho form admin portal.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## fieldErrors
+
+```yaml
+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
+
+```yaml
+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
+
+```yaml
+default: optional
+whenUsed: dấu `*` đỏ cạnh label, không thêm text dài.
+```
+
+## pendingState
+
+```yaml
+submitDisabled: true
+labelCanChange: true
+fieldsDisabled: chỉ khi action cần lock form để tránh double submit
+```
+
+## copy
+
+```yaml
+source: Ưu tiên message Laravel ja/validation.php khi đã có legacy/API source.
+language: Japanese UI copy.
+```
+
+
+## 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/import-csv/common-import-csv.md

@@ -0,0 +1,89 @@
+# Common CSV import flow
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn flow CSV upload, validate, preview, store và sample download.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## routes
+
+```yaml
+upload: /{module}/import
+validateApi: POST /{module}/import/validate
+preview: /{module}/import/preview/{uuid}
+storeApi: POST /{module}/import/store/{uuid}
+```
+
+## flow
+
+```yaml
+- Upload page tự render form bằng SPA, không dùng API init page.
+- Validate API nhận file multipart, parse/validate và trả uuid/preview URL.
+- Preview page đọc data từ cache/session import qua uuid.
+- Store là mutation nên API mới dùng POST, dù legacy có thể dùng GET.
+- Sample CSV là endpoint download rõ nghĩa.
+```
+
+## ui
+
+### ui (other)
+
+```yaml
+uploadLayout:
+  - Card phẳng, bên trái nếu legacy page là import nhỏ.
+  - Field file có label rõ và accept đúng extension.
+  - Button import primary/complete đứng trước sample download.
+previewLayout:
+  - Action group trên table: list link, total readonly, import confirm.
+  - Duplicate old row marker `-`, màu `#FFECEB`.
+  - New row marker `+`, màu `#DCFFF1`.
+```
+
+## errors
+
+```yaml
+invalidFile: hiển thị alert trên upload card.
+expiredPreview: 操作がタイムアウトしたか、CSVファイルが無効です。再度お試しください。
+```
+
+## confirm
+
+```yaml
+duplicateOverwrite: dùng common confirm dialog với copy `重複するデータが存在し、それは上書きされます。続行しますか？`
+```
+
+## testIds
+
+```yaml
+fileInput: "{module}-csv-file-input"
+uploadSubmit: "{module}-import-submit-btn"
+sampleDownload: "{module}-sample-download-btn"
+previewTable: "{module}-preview-table"
+```
+
+
+## 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/list-page/common-list-page.md

@@ -0,0 +1,102 @@
+# Common list page shell
+
+- **Testcase:** `#`
+- **Screen:** `#`
+
+Chuẩn layout chung cho các page danh sách trong admin portal, ưu tiên giao diện phẳng shadcn và giữ các phần legacy lặp lại có giá trị sử dụng.
+
+## status
+
+draft
+
+## owner
+
+portal-team
+
+## scope
+
+```yaml
+appliesTo:
+  - admin list page
+  - search/filter table page
+  - import/report list có pagination
+excludes:
+  - report preview đặc thù
+  - dashboard block
+  - form detail/edit page
+```
+
+## principles
+
+```yaml
+- UI phẳng: dùng border, background nhẹ, spacing rõ; không dùng gradient, shadow
+    nặng, hiệu ứng 3D.
+- Legacy evidence là input để nhận diện pattern lặp lại; không copy các page
+  legacy làm tùy hứng nếu trái common spec.
+- Page spec riêng chỉ mô tả phần khác biệt; mọi phần
+  list/search/toolbar/table/pagination mặc định dùng common specs.
+```
+
+## layout
+
+```yaml
+shell:
+  - Dashboard layout hiện tại là outer shell; không dựng lại legacy theme
+    wrapper.
+  - Content list dùng một khối phẳng có border nhẹ và background `bg-card` hoặc
+    `bg-white`.
+  - Search/filter nằm phía trên table.
+  - Toolbar action nằm dưới search/filter và phía trên table.
+  - Table body nằm trong vùng trắng, có horizontal overflow khi nhiều cột.
+  - Pagination nằm dưới table và căn giữa.
+density:
+  default: compact
+  rowHeight: 40-48px cho table thường
+  cellPadding: px-3 py-2
+  spacing: 4 hoặc 6 theo scale Tailwind, tránh khoảng trắng quá lớn trên list
+    nhiều dữ liệu.
+```
+
+## composition
+
+```yaml
+preferredComponents:
+  - DataListPage
+  - MoSearchForm
+  - MoDataTable
+  - MoPaginationBar
+overridePolicy:
+  - Chỉ tạo organism riêng khi `DataListPage` không thể giữ đúng layout của spec
+    hoặc page có table/report đặc thù.
+  - Nếu override common pattern, spec page phải ghi `overrideCommonPattern: true` và lý do.
+```
+
+## testIds
+
+```yaml
+required:
+  page: "{module}-page"
+  searchForm: "{module}-search-form"
+  toolbar: "{module}-toolbar"
+  table: "{module}-table"
+  pagination: "{module}-pagination"
+```
+
+
+## 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