[CLAUDE] Scaffold: khoi tao SOLUTION_ERP Phase 0

- .NET 10 Clean Architecture: Domain/Application/Infrastructure/Api (4 project) - 2 React + Vite + TS app: fe-admin (:8082), fe-user (:8080) voi proxy /api - Node engines >=20, .nvmrc = 20 cho CI (bai hoc NamGroup) - SQL Server 2022 qua docker-compose (dev) - Parse 8 FORM -> docs/forms-spec.md (catalog + ma HD format RG-001) - Parse QUY_TRINH -> docs/workflow-contract.md (9 phase state machine + role matrix) - docs: CLAUDE.md, STATUS.md, PROJECT-MAP.md, migration-todos.md (roadmap 5 phase) - .claude/skills: 3 placeholder (contract-workflow, form-engine, permission-matrix) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 10:37:34 +07:00
commit 25dad7f36f
69 changed files with 3616 additions and 0 deletions
--- a/.claude/skills/README.md
+++ b/.claude/skills/README.md
@ -0,0 +1,55 @@
+# Skill Library — SOLUTION_ERP
+
+Skill này là tài liệu chuyên biệt để Claude (và developer khác) dùng khi cần deep-dive 1 domain area. Claude tự động invoke qua Skill tool dựa trên semantic matching với `description` trong từng `SKILL.md`.
+
+## Skills hiện có
+
+| Skill | Mục đích | Trigger ví dụ | Trạng thái |
+|---|---|---|---|
+| `contract-workflow` | State machine 9 phase, role × phase guard, SLA timer, auto-approve | "approve contract", "chuyển phase", "auto-approve quá hạn" | 📝 Placeholder (Phase 3) |
+| `form-engine` | Render template docx/xlsx, parse 8 form, field mapping, PO generator | "export contract as word", "điền form", "render template" | 📝 Placeholder (Phase 2) |
+| `permission-matrix` | Role × MenuKey × CRUD, seed, reset password, 3-layer resolution | "permission denied", "gán role", "menu không hiện" | 📝 Placeholder (Phase 1) |
+
+## Format chuẩn 1 skill
+
+Mỗi skill là 1 folder với ít nhất `SKILL.md` + optional `examples/` + `references/`:
+
+```
+.claude/skills/<skill-name>/
+├── SKILL.md                  ← Entry point: description, when-to-use, workflow
+├── examples/                 ← Code snippets mẫu
+│   └── *.cs | *.tsx
+└── references/               ← Link đến file code thật, docs
+```
+
+**Frontmatter `SKILL.md`:**
+
+```markdown
+---
+name: contract-workflow
+description: State machine 9 phase cho hợp đồng — guard rule, SLA, auto-approve
+when-to-use:
+  - "approve contract"
+  - "state machine bug"
+  - "SLA expired"
+---
+
+# Contract Workflow Skill
+
+## Context
+...
+
+## Workflow
+...
+
+## Code pointers
+- `src/Backend/SolutionErp.Domain/Contracts/ContractPhase.cs`
+- `src/Backend/SolutionErp.Application/Contracts/Commands/TransitionContractCommand.cs`
+```
+
+## Tạo skill mới — checklist
+
+1. Tạo folder `.claude/skills/<kebab-case-name>/`
+2. Viết `SKILL.md` với frontmatter + sections: Context / Workflow / Code pointers / Common pitfalls
+3. Add row vào bảng "Skills hiện có" phía trên
+4. Commit `[CLAUDE] Skill: add <name>`
--- a/.claude/skills/contract-workflow/SKILL.md
+++ b/.claude/skills/contract-workflow/SKILL.md
@ -0,0 +1,34 @@
+---
+name: contract-workflow
+description: State machine 9 phase cho hợp đồng TP/NCC/Tổ đội — guard rule, SLA auto-approve, role × phase matrix. Dùng khi debug transition, approve HĐ, xử lý HĐ quá hạn.
+when-to-use:
+  - "transition contract"
+  - "chuyển phase hợp đồng"
+  - "HĐ quá hạn auto-approve"
+  - "role không duyệt được"
+  - "reject contract về draft"
+---
+
+# Contract Workflow Skill
+
+> **Phase 3 deliverable.** Hiện tại skill này là PLACEHOLDER — sẽ được expand khi implement Phase 3.
+
+## Context
+
+Xem đầy đủ ở [`docs/workflow-contract.md`](../../../docs/workflow-contract.md):
+- 9 state: `DangChon` → `DangSoanThao` → `DangGopY` → `DangDamPhan` → `DangInKy` → `DangKiemTraCCM` → `DangTrinhKy` → `DangDongDau` → `DaPhatHanh` (+ `TuChoi`)
+- SLA mỗi phase: Draft 7d, GópÝ 7d, ĐàmPhán 7d, InKý 1d, CCMCheck 3d, BOD 1d
+- Role × Phase matrix (Drafter, TBP/TPB, PD/PM, PRO/EQU/FIN/ACT, CCM, BOD/NĐUQ, HRA)
+
+## Code pointers (sẽ có sau Phase 3)
+
+- `src/Backend/SolutionErp.Domain/Contracts/ContractPhase.cs` (enum)
+- `src/Backend/SolutionErp.Domain/Contracts/Contract.cs` (aggregate root)
+- `src/Backend/SolutionErp.Application/Contracts/Services/IContractWorkflowService.cs`
+- `src/Backend/SolutionErp.Infrastructure/HostedServices/SlaExpiryJob.cs`
+
+## Common pitfalls (dự kiến — update khi build)
+
+- Không check bypass flag khi HĐ với Chủ đầu tư → sẽ reject oan ở CCM phase
+- Gen mã HĐ trước khi BOD approve → có thể waste số thứ tự nếu reject sau đó
+- Auto-approve chạy trong transaction dài → lock table → timeout
--- a/.claude/skills/form-engine/SKILL.md
+++ b/.claude/skills/form-engine/SKILL.md
@ -0,0 +1,34 @@
+---
+name: form-engine
+description: Template engine render 8 form hợp đồng ra .docx/.xlsx giống 100% mẫu gốc. Gen mã HĐ theo RG-001. Dùng khi export HĐ, upload template mới, debug render lỗi format.
+when-to-use:
+  - "export contract to word"
+  - "render template docx"
+  - "xuất đơn đặt hàng excel"
+  - "gen mã hợp đồng"
+  - "upload template mới"
+---
+
+# Form Engine Skill
+
+> **Phase 2 deliverable.** Hiện tại skill này là PLACEHOLDER.
+
+## Context
+
+Xem đầy đủ ở [`docs/forms-spec.md`](../../../docs/forms-spec.md):
+- 8 form (6 .docx/.doc + 1 .xlsx + 1 .docx quy định)
+- Mã HĐ format theo SOL-CCM-RG-001: `{Project}/{Type}/SOL&{Partner}/{Seq}` và biến thể
+- 3 file `.doc` cần convert qua Word COM / LibreOffice headless trước khi parse
+
+## Tech stack dự kiến
+
+- **.docx render:** DocumentFormat.OpenXml (free, verbose) hoặc Aspose.Words (phí, dễ)
+- **.xlsx render:** EPPlus (free non-commercial) hoặc ClosedXML (free)
+- **PDF preview:** wkhtmltopdf hoặc LibreOffice `--convert-to pdf`
+
+## Code pointers (sẽ có sau Phase 2)
+
+- `src/Backend/SolutionErp.Application/Forms/Services/IFormRenderer.cs`
+- `src/Backend/SolutionErp.Infrastructure/Forms/DocxRenderer.cs`
+- `src/Backend/SolutionErp.Infrastructure/Forms/XlsxRenderer.cs`
+- `src/Backend/SolutionErp.Infrastructure/Services/ContractCodeGenerator.cs`
--- a/.claude/skills/permission-matrix/SKILL.md
+++ b/.claude/skills/permission-matrix/SKILL.md
@ -0,0 +1,41 @@
+---
+name: permission-matrix
+description: Hệ thống phân quyền Role × MenuKey × CRUD. Sidebar gating, permission guard, seed default, reset password. Dùng khi debug access denied, gán role, menu không hiện.
+when-to-use:
+  - "permission denied"
+  - "access denied"
+  - "menu không hiện"
+  - "gán role cho user"
+  - "reset password"
+  - "seed permission"
+---
+
+# Permission Matrix Skill
+
+> **Phase 1 deliverable.** Hiện tại skill này là PLACEHOLDER.
+
+## Context
+
+Pattern copy từ **NamGroup** skill `permission-system` nhưng đơn giản hóa:
+- 1 User có N Role
+- 1 Role có ma trận (MenuKey, CRUD flags) — `Permission` table
+- Không có per-user override (giữ đơn giản cho Phase 1)
+- Menu tree flat 2 cấp, hardcode `MenuKey`
+
+## Tech
+
+- BE: `[Authorize(Policy = "Menu.Read")]` attribute
+- FE: `<PermissionGuard menuKey="Contracts" action="Update">` + `usePermission().can("Contracts", "Update")`
+- Resolution: API `/api/menus/me` trả về tree + permissions đã resolved theo user's roles
+
+## Code pointers (sẽ có sau Phase 1)
+
+- `src/Backend/SolutionErp.Domain/Identity/Permission.cs`
+- `src/Backend/SolutionErp.Application/Permissions/Queries/GetMyMenuTreeQuery.cs`
+- `fe-admin/src/components/PermissionGuard.tsx`
+- `fe-admin/src/hooks/usePermission.ts`
+
+## Common pitfalls (dự kiến)
+
+- Quên refresh token sau khi admin update permission → user phải logout/login mới thấy
+- MenuKey hardcode dễ typo → tập trung vào file `src/lib/menuKeys.ts` (FE) + `MenuKeys.cs` (BE const)