[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/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@ -0,0 +1,139 @@
+# CLAUDE.md — Full Context (SOLUTION_ERP)
+
+## 1. Giới thiệu
+
+**SOLUTION_ERP** là hệ thống quản lý Hợp đồng Nhà cung cấp / Thầu phụ / Tổ đội / Dịch vụ cho **Công ty TNHH Xây dựng Solutions**, thay thế quy trình giấy / Word+Excel hiện tại.
+
+**Scope chính:**
+1. Số hóa 8 form hợp đồng (template engine điền field → export .docx/.xlsx)
+2. Workflow 9 phase trình ký (state machine + role guard + SLA auto-approve)
+3. Tự gen mã HĐ theo Quy định SOL-CCM-RG-001
+4. Dashboard báo cáo HĐ theo NCC, dự án, trạng thái, giá trị
+
+## 2. Kiến trúc tổng thể
+
+```
+┌────────────────┐  ┌────────────────┐
+│  fe-admin      │  │  fe-user       │    React 18 + Vite + TS + shadcn/ui
+│  :8082         │  │  :8080         │    TanStack Query, Tailwind
+└────────┬───────┘  └────────┬───────┘
+         │                   │
+         │   Vite proxy /api → :5443
+         ▼                   ▼
+┌──────────────────────────────────────┐
+│  SolutionErp.Api :5443               │    ASP.NET Core 10 + JWT
+│  Controllers / Middleware / Swagger  │
+└──────────────┬───────────────────────┘
+               │
+      ┌────────▼─────────┐
+      │ SolutionErp.     │    CQRS + MediatR
+      │ Application      │    FluentValidation + AutoMapper
+      └────────┬─────────┘
+               │
+      ┌────────▼─────────┐    ← SolutionErp.Infrastructure
+      │ SolutionErp.     │         (EF Core, Identity, Repos, External services)
+      │ Domain           │
+      └──────────────────┘
+               │
+               ▼
+       ┌────────────────┐
+       │  SQL Server    │    dbo schema, GUID PK
+       └────────────────┘
+```
+
+## 3. Project layout
+
+```
+SOLUTION_ERP/
+├── src/Backend/
+│   ├── SolutionErp.Domain/         Entities, ValueObjects, Enums, DomainEvents
+│   ├── SolutionErp.Application/    CQRS handlers, DTOs, Validators, Mappings, Interfaces
+│   ├── SolutionErp.Infrastructure/ EF DbContext, Identity, Repositories, External
+│   └── SolutionErp.Api/            Controllers, Middleware, Program.cs, appsettings
+├── fe-admin/                       (admin UI — CRUD master data, approve, dashboards)
+│   └── src/
+├── fe-user/                        (user UI — soạn thảo HĐ, comment, upload)
+│   └── src/
+├── docs/
+│   ├── CLAUDE.md                   (file này)
+│   ├── STATUS.md
+│   ├── PROJECT-MAP.md
+│   ├── forms-spec.md               ⭐ 8 form catalog + RG-001 code format
+│   ├── workflow-contract.md        ⭐ 9 phase state machine + role matrix
+│   ├── guides/                     setup, cicd, code-rules...
+│   ├── database/                   schema docs
+│   └── changelog/
+│       ├── migration-todos.md      Roadmap 5 phase
+│       └── sessions/               YYYY-MM-DD session logs
+├── .claude/skills/                 Skill library (contract-workflow, form-engine, ...)
+├── scripts/                        parse_forms.py, parse_workflow.py, seed, deploy
+├── SolutionErp.slnx                Solution file
+├── global.json                     .NET 10 SDK pin
+├── docker-compose.yml              SQL Server cho dev
+└── CLAUDE.md                       Pointer → docs/CLAUDE.md
+```
+
+## 4. Tech stack chi tiết
+
+| Layer | Tech | Version |
+|---|---|---|
+| .NET SDK | .NET | 10.0.104 |
+| ORM | EF Core | 10 |
+| DB | SQL Server | 2019+ (LocalDB dev) |
+| API | ASP.NET Core Web API | 10 |
+| Mediator | MediatR | latest |
+| Validation | FluentValidation | latest |
+| Mapping | AutoMapper | latest |
+| Auth | JWT Bearer + ASP.NET Identity | 10 |
+| Logging | Serilog | latest |
+| OpenAPI | Swashbuckle | latest |
+| FE Build | Vite | 8 |
+| FE Lib | React | 19 (auto-scaffolded) |
+| FE Lang | TypeScript | 6 |
+| FE Styling | Tailwind CSS + shadcn/ui | Phase 1 install |
+| FE Data | TanStack Query | Phase 1 install |
+| Node (local) | >= 20 | local có thể Node 22 |
+| Node (CI) | **pin 20.x** | bài học từ NamGroup |
+
+## 5. Reference projects
+
+- **NamGroup** (`D:\Dropbox\CONG_VIEC\NAMGROUP\SOURCECODE_CÔNG_TY\NAMGROUP\`) — template 2 FE + IIS deploy + permission matrix
+- **DH_Y_DUOC** (`D:\Dropbox\CONG_VIEC\DAI_Y_DUOC\DH_Y_DUOC_SOURCECODE\DH_Y_DUOC\`) — template backend hiện đại (Clean Arch + CQRS + EF migrations)
+
+## 6. Roadmap 5 phase (summary)
+
+| Phase | Tuần | Focus | Exit criteria |
+|---|---|---|---|
+| **0 Draft** | T1 | Scaffold, parse FORM + QUY_TRINH | Build pass, docs đủ |
+| **1 Alpha Core** | T2-4 | Auth + Permission + CRUD Supplier/Project/Contract | Admin tạo HĐ draft + gán role |
+| **2 Form Engine** | T5-6 | Template engine 8 form, export .docx/.xlsx | Export 1 HĐ giống mẫu 100% |
+| **3 Workflow** | T7-9 | State machine 9 phase + SLA + notify | HĐ đi hết quy trình → có mã số |
+| **4 Report + Polish** | T10-11 | Dashboard, Excel export, UX pass | UAT 5-10 HĐ thật |
+| **5 Production** | T12-13 | CI/CD IIS, security, runbook, UAT | Go-live |
+
+Chi tiết atomic tasks ở [`changelog/migration-todos.md`](changelog/migration-todos.md).
+
+## 7. Quy ước code
+
+- **Ngôn ngữ UI:** 100% tiếng Việt. Code + comment + tên DB table: **English**.
+- **Tên file:** PascalCase cho `.cs`, kebab-case cho TS/TSX (trừ React component = PascalCase).
+- **Null safety:** `.NET` bật nullable reference types. TS `strict: true`.
+- **Async/await** cho mọi I/O.
+- **Error handling BE:** `GlobalExceptionMiddleware` → map exception → ProblemDetails. KHÔNG try-catch ở controller.
+- **Error handling FE:** error boundary + toast. Dùng `useErrorHandler` hook.
+- **Logging:** Serilog structured. Không `Console.WriteLine`.
+
+## 8. Security baseline
+
+- HTTPS everywhere (IIS redirect HTTP → HTTPS)
+- JWT expiry 1h, refresh token 7d
+- Password hash: Identity default (PBKDF2)
+- CORS: whitelist chỉ 2 FE origin
+- Rate limit: 100 req/min/IP cho endpoint auth
+- SQL injection: EF Core parameterized (không raw SQL trừ khi cần)
+- Audit log: mọi write → `AuditLog` table
+
+## 9. Liên hệ
+
+- **Dev:** pqhuy1987@gmail.com (solo)
+- **Domain expert:** TBD (sẽ update sau UAT đầu tiên)
--- a/docs/PROJECT-MAP.md
+++ b/docs/PROJECT-MAP.md
@ -0,0 +1,154 @@
+# PROJECT-MAP — Bản đồ toàn cảnh
+
+> Đọc file này nếu cần deep context (~15 phút). Nếu chỉ cần snapshot → đọc [`STATUS.md`](STATUS.md).
+
+## Module map
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      SOLUTION_ERP                                │
+└─────────────────────────────────────────────────────────────────┘
+
+ ╔════════════════╗   ╔════════════════╗   ╔════════════════╗
+ ║  IDENTITY      ║   ║  DANH MỤC      ║   ║  QUẢN LÝ HĐ    ║
+ ║  (Phase 1)     ║   ║  (Phase 1)     ║   ║  (Phase 1-3)   ║
+ ╠════════════════╣   ╠════════════════╣   ╠════════════════╣
+ ║ User           ║   ║ Supplier       ║   ║ Contract       ║
+ ║ Role           ║   ║ Project        ║   ║ ContractType   ║
+ ║ Permission     ║   ║ Department     ║   ║ ContractForm   ║
+ ║ MenuKey        ║   ║ ContractClause ║   ║ Approval       ║
+ ║ AuditLog       ║   ║ (điều kiện     ║   ║ Comment        ║
+ ║                ║   ║  chung - 002.04)║   ║ Attachment     ║
+ ╚════════════════╝   ╚════════════════╝   ║ AuditTrail     ║
+                                           ╚════════════════╝
+
+ ╔════════════════╗   ╔════════════════╗   ╔════════════════╗
+ ║  FORM ENGINE   ║   ║  WORKFLOW      ║   ║  BÁO CÁO       ║
+ ║  (Phase 2)     ║   ║  (Phase 3)     ║   ║  (Phase 4)     ║
+ ╠════════════════╣   ╠════════════════╣   ╠════════════════╣
+ ║ Template       ║   ║ StateMachine   ║   ║ Dashboard      ║
+ ║ Renderer       ║   ║ Transition     ║   ║ ExcelExport    ║
+ ║ (DOCX/XLSX)    ║   ║ SlaTimer       ║   ║ FilterQuery    ║
+ ║ Field mapping  ║   ║ Notification   ║   ║                ║
+ ║ PO gen (F.07)  ║   ║ CodeGenerator  ║   ║                ║
+ ║                ║   ║ (RG-001)       ║   ║                ║
+ ╚════════════════╝   ╚════════════════╝   ╚════════════════╝
+```
+
+## Domain entities chính (dự kiến)
+
+```
+User ────< Role ────< Permission (Role × MenuKey × CRUD)
+User ────< AuditLog
+
+Supplier (NCC)
+Project (Dự án)
+Department (Phòng ban)
+
+Contract
+  ├── Type: HĐTP | HĐGK | NCC | HĐDV | HĐ Mua bán | ...
+  ├── Phase (9 state — xem workflow-contract.md)
+  ├── Supplier, Project, Drafter
+  ├── MaHopDong (gen theo RG-001)
+  ├── Approvals[] (audit ai ký phase nào)
+  ├── Comments[] (thread góp ý Phase 3 của workflow)
+  ├── Attachments[] (scan bản gốc, file export)
+  └── TemplateData (JSON — field đã điền khi render form)
+
+ContractTemplate (ánh xạ Type → File mẫu FO-002.xx)
+ContractClause (điều khoản chung FO-002.04 — rich text)
+PurchaseOrder (có thể đính với Contract hoặc standalone)
+```
+
+## API namespace dự kiến
+
+```
+/api/auth          — login, refresh, logout, register (admin gate)
+/api/users         — CRUD user, assign role, reset password
+/api/roles         — CRUD role, permission matrix
+/api/menus         — menu tree + permission resolution
+
+/api/suppliers     — CRUD NCC
+/api/projects      — CRUD dự án
+/api/departments   — CRUD phòng ban
+
+/api/contracts     — CRUD + query by phase/project/supplier
+/api/contracts/{id}/transitions  — state machine action
+/api/contracts/{id}/comments     — thread góp ý
+/api/contracts/{id}/attachments  — upload/download
+
+/api/forms         — template catalog
+/api/forms/{id}/render — render template → docx/xlsx (Phase 2)
+
+/api/reports/dashboard  — KPI tổng hợp
+/api/reports/export     — Excel download
+```
+
+## FE screens dự kiến
+
+### fe-admin (:8082) — cho Admin + Role quản lý
+
+- `/login`
+- `/dashboard` — KPI system
+- `/master/users` + `/master/roles` + `/master/permissions`
+- `/master/suppliers` + `/master/projects` + `/master/departments`
+- `/master/contract-templates` + `/master/contract-clauses`
+- `/contracts` — danh sách toàn bộ, filter phase/dự án
+- `/contracts/{id}` — detail + approval panel + audit log
+- `/reports` + `/system/audit-log`
+
+### fe-user (:8080) — cho Drafter, TBP, PD/PM, BOD, CCM, ...
+
+- `/login`
+- `/inbox` — HĐ đang chờ tôi xử lý (filter theo role × phase)
+- `/contracts/new` — chọn template + điền form + submit
+- `/contracts/{id}` — detail, comment, approve/reject
+- `/my-contracts` — HĐ tôi đã tạo/tham gia
+
+## Flow chính (Phase 3 — trình ký HĐ end-to-end)
+
+```
+Drafter (QS/NV.PB)
+  ├─ [POST /api/contracts] tạo draft + chọn template
+  ├─ [POST /api/forms/{id}/render] fill + preview
+  ├─ [POST /api/contracts/{id}/transitions] DangSoanThao → DangGopY
+  │
+PD/PM/PRO/CCM/FIN/ACT  (song song)
+  └─ [POST /api/contracts/{id}/comments] góp ý
+  
+Drafter
+  ├─ [PATCH /api/contracts/{id}] revise
+  ├─ [POST /api/contracts/{id}/transitions] DangGopY → DangDamPhan → DangInKy
+  │
+NTP/NCC/TĐ (external — Drafter update thay)
+  └─ upload scan có chữ ký đối tác
+
+Drafter
+  └─ [POST /api/contracts/{id}/transitions] → DangKiemTraCCM
+
+CCM
+  └─ [POST /api/contracts/{id}/transitions] → DangTrinhKy
+
+BOD/NĐUQ
+  └─ [POST /api/contracts/{id}/transitions] → DangDongDau (GEN mã HĐ ở đây!)
+
+HRA
+  └─ [POST /api/contracts/{id}/transitions] → DaPhatHanh (upload scan có dấu)
+```
+
+## External dependencies
+
+- **SQL Server** — chính thức, dev có thể LocalDB hoặc Docker (`docker-compose.yml`)
+- **IIS** — deploy target (Windows Server 2019+)
+- **Gitea** — git remote (URL chờ user cấp)
+- **Aspose.Words / DocumentFormat.OpenXml** — render .docx (Phase 2, quyết định khi đó)
+- **EPPlus hoặc ClosedXML** — render .xlsx (Phase 2)
+
+## Non-goals (KHÔNG làm)
+
+- ❌ Python AI service (user đã quyết gác vô thời hạn)
+- ❌ Mobile app
+- ❌ Multi-tenant (1 instance / 1 công ty)
+- ❌ Tích hợp e-signature (Phase 6+ nếu có)
+- ❌ Tích hợp SAP/Bravo ERP (Phase 6+ nếu có)
+- ❌ Public API / external webhooks
--- a/docs/STATUS.md
+++ b/docs/STATUS.md
@ -0,0 +1,55 @@
+# STATUS — Snapshot hiện tại
+
+> **Update rule:** trước khi bắt đầu 1 task → ghi row vào `🔥 In Progress`. Xong → chuyển sang `✅ Recently Done`.
+
+**Last updated:** 2026-04-21
+
+## 📍 Phase hiện tại: **Phase 0 — Draft Scaffold** (in progress)
+
+## 🔥 In Progress
+
+| Ai | Task | Bắt đầu |
+|---|---|---|
+| Claude | Hoàn tất Phase 0 — docs + git init | 2026-04-21 |
+
+## ✅ Recently Done (newest on top)
+
+| Ngày | Ai | Task | Commit |
+|---|---|---|---|
+| 2026-04-21 | Claude | Parse QUY_TRINH → `workflow-contract.md` (9 phase state machine + role matrix) | — |
+| 2026-04-21 | Claude | Parse 8 FORM → `forms-spec.md` (catalog + RG-001 code format) | — |
+| 2026-04-21 | Claude | Scaffold 2 React + Vite apps (fe-admin :8082, fe-user :8080) + proxy config + Node engines pin | — |
+| 2026-04-21 | Claude | Scaffold .NET 10 solution + 4 project (Domain/Application/Infrastructure/Api) + references + packages | — |
+| 2026-04-21 | Claude | Tạo cấu trúc thư mục `SOLUTION_ERP/` + MEMORY.md | — |
+
+## 🎯 Next up (Phase 0 còn lại)
+
+- [ ] Tạo file root: `.gitignore`, `README.md`, `global.json`, `docker-compose.yml`
+- [ ] Tạo 3 skill folder placeholders (`contract-workflow`, `form-engine`, `permission-matrix`)
+- [ ] `git init` + commit đầu tiên `[CLAUDE] Scaffold: khởi tạo SOLUTION_ERP Phase 0`
+- [ ] Set Gitea remote (khi user cấp URL)
+
+## 📋 Phase 1 — Alpha Core (sắp tới)
+
+Xem chi tiết ở [`changelog/migration-todos.md`](changelog/migration-todos.md) section **Phase 1**.
+
+Summary:
+1. Install Tailwind + shadcn/ui cho 2 FE + setup `BrandingProvider`
+2. Tạo `BaseEntity`, `AuditableEntity`, `ApplicationDbContext`, migration đầu tiên
+3. ASP.NET Identity + JWT endpoint (login, refresh, logout, seed admin)
+4. Permission Matrix (Role × MenuKey × CRUD) — copy pattern từ NamGroup skill
+5. CRUD Supplier + Project + Contract (draft only, chưa workflow)
+6. FE admin: login page + layout + permission guard + 3 CRUD page
+7. FE user: login + layout + list HĐ của tôi
+
+## 🚨 Blockers / risks
+
+- **Gitea remote** chưa có URL — chờ user cấp để push code
+- **3 file `.doc`** (FO-002.02, .03, .06) không parse được bằng python-docx — cần Word COM hoặc LibreOffice ở Phase 2
+- **Node 22 local vs 20 CI** — phải test CI sớm (Phase 5) để tránh surprise
+
+## 📊 Thông số
+
+- LOC: ~0 (scaffold chỉ)
+- Build time: ~10s (.NET)
+- Test coverage: 0% (chưa có test)
--- a/docs/changelog/migration-todos.md
+++ b/docs/changelog/migration-todos.md
@ -0,0 +1,164 @@
+# Migration To-dos — Atomic Roadmap
+
+> Mỗi item là 1 task atomic (~2-8h work). Tick `[x]` khi xong. Link session log nếu có.
+
+## Phase 0 — Draft Scaffold (T1)
+
+- [x] Tạo cấu trúc thư mục `SOLUTION_ERP/`
+- [x] Scaffold .NET 10 solution `SolutionErp.slnx`
+- [x] Scaffold 4 project: `SolutionErp.{Domain, Application, Infrastructure, Api}`
+- [x] Wire Clean Arch references (Api → App/Infra, Infra → App, App → Domain)
+- [x] Install NuGet base: MediatR, FluentValidation, AutoMapper, EF Core SqlServer, Identity, JWT, Swagger, Serilog
+- [x] Scaffold 2 React + Vite apps `fe-admin` + `fe-user` với TS template
+- [x] Config vite.config.ts: port, strictPort, proxy `/api`, alias `@`
+- [x] Pin Node `>=20` trong package.json + `.nvmrc` cho CI
+- [x] Parse 8 form → `docs/forms-spec.md`
+- [x] Parse quy trình → `docs/workflow-contract.md`
+- [x] Viết `docs/{CLAUDE,STATUS,PROJECT-MAP}.md`
+- [ ] Viết `.gitignore`, `README.md`, `global.json`, `docker-compose.yml`
+- [ ] Tạo placeholder skill folders: `contract-workflow`, `form-engine`, `permission-matrix`
+- [ ] `git init` + commit đầu
+- [ ] Push Gitea remote (chờ URL từ user)
+
+## Phase 1 — Alpha Core (T2-4)
+
+### Backend foundation
+
+- [ ] `Domain/BaseEntity.cs` (Id, CreatedAt, UpdatedAt, CreatedBy, UpdatedBy)
+- [ ] `Domain/AuditableEntity : BaseEntity` (IsDeleted, DeletedAt, DeletedBy)
+- [ ] `Domain/ValueObjects/ContractCode.cs` (wrap string theo format RG-001)
+- [ ] `Domain/Enums/ContractType.cs`, `ContractPhase.cs`, `ApprovalDecision.cs`
+- [ ] `Application/Common/IApplicationDbContext.cs` interface
+- [ ] `Application/Common/IDateTime.cs`, `ICurrentUser.cs`
+- [ ] `Application/DependencyInjection.cs` — register MediatR, FluentValidation, AutoMapper
+- [ ] `Infrastructure/Persistence/ApplicationDbContext.cs` : `IdentityDbContext<User, Role, Guid>`, `IApplicationDbContext`
+- [ ] Configurations per entity qua `IEntityTypeConfiguration<T>`
+- [ ] `Infrastructure/DependencyInjection.cs` — register DbContext, Identity, services
+- [ ] `Api/Program.cs` setup: services, Serilog, auth, Swagger, CORS, middleware
+- [ ] `Api/Middleware/GlobalExceptionMiddleware.cs`
+
+### Auth + Identity
+
+- [ ] `Domain/Entities/User : IdentityUser<Guid>`, `Role : IdentityRole<Guid>`
+- [ ] Migration 1: `Init` (Identity tables)
+- [ ] `Application/Auth/Commands/LoginCommand` + handler + validator
+- [ ] `Application/Auth/Commands/RefreshTokenCommand`
+- [ ] `Api/Controllers/AuthController` (login, refresh, logout, me)
+- [ ] JWT config: issuer, audience, key, expiry 1h + refresh 7d
+- [ ] Seed admin: `admin@solutionerp.local` / `Admin@123456`
+- [ ] Test login → get token → call `/me` OK
+
+### Permission Matrix
+
+- [ ] `Domain/Entities/MenuItem` (Key, Label, ParentKey, Order, Icon)
+- [ ] `Domain/Entities/Permission` (RoleId, MenuKey, CanRead, CanCreate, CanUpdate, CanDelete)
+- [ ] Seed default menu tree (based on FE screens list)
+- [ ] `Application/Permissions/Queries/GetMyMenuTree` — resolve per-user
+- [ ] `Api/Controllers/MenusController` + `RolesController` + `PermissionsController`
+- [ ] Admin UI: Permission Matrix grid (role × menu × CRUD checkbox)
+
+### CRUD master data
+
+- [ ] `Domain/Entities/Supplier` (Code, Name, TaxCode, Phone, Email, Address, Type: NCC/NTP/TĐ/ĐVDV)
+- [ ] `Domain/Entities/Project` (Code, Name, StartDate, EndDate, Manager)
+- [ ] `Domain/Entities/Department` (Code, Name, Manager)
+- [ ] CQRS + Controller + Migration cho 3 entity
+- [ ] FE admin 3 trang CRUD (list, create, edit, delete confirm)
+- [ ] Pagination, search, sort server-side
+
+### Contract draft (chưa workflow — chỉ CRUD)
+
+- [ ] `Domain/Entities/Contract` (skeleton: Id, Type, SupplierId, ProjectId, Phase=DangChon, DraftData)
+- [ ] API create/update/list/delete draft
+- [ ] FE admin: list contracts + filter
+- [ ] FE user: "HĐ của tôi" list
+
+### FE setup
+
+- [ ] Install Tailwind CSS cho 2 app + config content paths
+- [ ] Install shadcn/ui CLI, init 2 app
+- [ ] Install: `@tanstack/react-query`, `react-router-dom`, `axios`, `lucide-react`, `sonner`
+- [ ] `src/lib/api.ts` — axios instance + interceptor JWT
+- [ ] `src/contexts/AuthContext.tsx` — token từ localStorage
+- [ ] `src/components/PermissionGuard.tsx` + `usePermission()` hook
+- [ ] Layout shell: sidebar + header + content
+- [ ] Route với protected route + role guard
+- [ ] Toast notifications (sonner)
+
+### Exit criteria Phase 1
+
+- [ ] Admin login → tạo NCC/Project → tạo role "Nhân viên CCM" → gán permission menu "Contracts.Read"
+- [ ] User CCM login → thấy menu Contracts, không thấy menu Admin
+- [ ] Tạo Contract draft → list hiển thị, không bị 403 sai
+
+## Phase 2 — Form Engine (T5-6)
+
+- [ ] Khảo sát: OpenXml vs Aspose.Words — chọn 1 (Aspose có license phí; OpenXml free nhưng verbose)
+- [ ] Convert 3 file `.doc` → `.docx` (COM automation PowerShell hoặc LibreOffice headless)
+- [ ] Parse chi tiết field của 5 template HĐ — mỗi form thành JSON spec
+- [ ] `Domain/Entities/ContractTemplate` (Id, FormCode, Name, TemplateFile path, FieldSpec JSON)
+- [ ] `Application/Forms/Services/IFormRenderer` — input: template + data dict → output: byte[] (.docx)
+- [ ] Implement `DocxRenderer` (OpenXml-based replace placeholder)
+- [ ] Implement `XlsxRenderer` cho FO-002.07 (dùng EPPlus/ClosedXML)
+- [ ] `Api/Controllers/FormsController` — GET /templates, POST /render
+- [ ] FE user: form builder — chọn template → dynamic form → preview → export
+- [ ] FE admin: upload template mới, edit field mapping
+- [ ] Lưu `ContractClause` (FO-002.04) dạng rich text, admin edit qua TipTap/TinyMCE
+- [ ] Import/export template (để backup)
+- [ ] Test: 1 HĐ Giao khoán filled → export .docx mở bằng Word y hệt mẫu
+
+## Phase 3 — Workflow State Machine (T7-9)
+
+- [ ] `Domain/Entities/ContractApproval` + `ContractComment` + `ContractAttachment`
+- [ ] `Domain/Entities/Contract` update: thêm `Phase`, `SlaDeadline`, `BypassProcurementAndCCM`
+- [ ] `Domain/Services/IContractWorkflowService.TransitionAsync(...)` — state guard + role guard + side effects
+- [ ] `Infrastructure/Services/ContractCodeGenerator` (implement RG-001) với locking cho seq
+- [ ] `Infrastructure/HostedServices/SlaExpiryJob` — check mỗi 15min, auto-approve quá hạn
+- [ ] `Infrastructure/Services/NotificationService` — email (MailKit) + in-app (SignalR optional)
+- [ ] MediatR behavior: `AuditBehavior` — log mọi command
+- [ ] API: `POST /api/contracts/{id}/transitions` body: `{targetPhase, comment}`
+- [ ] FE user Inbox: list "HĐ chờ tôi xử lý" (query by current phase + user role)
+- [ ] FE Contract detail page: timeline 9 phase, approval panel, comment thread
+- [ ] Upload attachment (scan có chữ ký đối tác)
+- [ ] Notification UI: badge count, dropdown, click → detail
+- [ ] E2E test: happy path end-to-end 1 HĐ qua 9 phase
+- [ ] E2E test: reject → quay về DangSoanThao
+- [ ] E2E test: SLA expired → auto-approve + log
+
+## Phase 4 — Reporting + Polish (T10-11)
+
+- [ ] Dashboard admin: số HĐ theo phase, top NCC, top dự án, tổng giá trị theo tháng
+- [ ] Excel export theo bộ lọc (dùng EPPlus)
+- [ ] Report: HĐ quá hạn SLA bao nhiêu lần theo phase/role
+- [ ] UX polish: skeleton loader, empty state, error boundary có recovery button
+- [ ] Accessibility: keyboard nav, focus trap modal, aria labels
+- [ ] Dark mode (optional, nếu rảnh)
+- [ ] Performance: index DB cho query hot (SupplierId, ProjectId, Phase)
+- [ ] Tài liệu user guide: quy trình tạo HĐ + duyệt
+- [ ] UAT với 5-10 HĐ dữ liệu thật từ bộ phận Cung ứng
+
+## Phase 5 — Production (T12-13)
+
+- [ ] `docs/guides/cicd.md` — CI/CD runbook
+- [ ] Gitea Actions workflow `.gitea/workflows/deploy.yml` — build .NET + 2 FE, deploy IIS qua SSH/WinRM
+- [ ] Pin Node 20.x trong workflow, test CI sớm (không để surprise cuối dự án)
+- [ ] `scripts/deploy-iis.ps1` — stop app pool, xcopy, start app pool
+- [ ] Windows Server setup: IIS + URL Rewrite + ARR (reverse proxy FE → IIS)
+- [ ] SQL Server prod: backup plan daily + weekly full
+- [ ] HTTPS certificate (Let's Encrypt qua win-acme hoặc mua cert)
+- [ ] `appsettings.Production.json` + user secrets
+- [ ] Security audit: owasp top 10 check
+- [ ] Rate limiting middleware (AspNetCoreRateLimit hoặc built-in)
+- [ ] Health check endpoint `/health` cho IIS probe
+- [ ] Error tracking: Serilog → file rolling daily, retention 30 ngày
+- [ ] Runbook: restart app, rollback migration, restore backup
+- [ ] UAT production 1 tuần với 2-3 user thật
+- [ ] Go-live checklist: backup, rollback plan, on-call contact
+
+## Post-launch (Phase 6+ — future)
+
+- [ ] E-signature integration (VNPT CA hoặc FPT CA)
+- [ ] Tích hợp Bravo / SAP ERP import NCC
+- [ ] Mobile app (React Native?) cho BOD duyệt ngoài giờ
+- [ ] AI: gợi ý điền form dựa HĐ cũ, OCR scan HĐ đối tác
+- [ ] Multi-tenant nếu có công ty thứ 2
--- a/docs/forms-spec-raw.md
+++ b/docs/forms-spec-raw.md
--- a/docs/forms-spec.md
+++ b/docs/forms-spec.md
@ -0,0 +1,108 @@
+# Forms Specification — SOLUTION_ERP
+
+> **Nguồn:** `D:\Dropbox\CONG_VIEC\SOLUTION\FORM\` (8 file)
+> **Raw dump:** [`forms-spec-raw.md`](forms-spec-raw.md) — text gốc extract từ docx/xlsx
+> **Phase 2 deliverable:** parse từng form → template engine (điền field tự động → export .docx/.xlsx giống 100% mẫu)
+
+## Danh mục 8 form
+
+| Mã form | Tên | Loại file | Mục đích | Trạng thái parse |
+|---|---|---|---|---|
+| **SOL-CCM-FO-002.01** | Bảng kiểm tra hợp đồng | `.docx` | Checklist 4 bộ phận (Đề xuất / Cung ứng / CCM / Giám đốc) review HĐ trước ký | ✅ Parsed — table 40×13 |
+| **SOL-CCM-FO-002.02** | Hợp đồng trọn gói (nhân công + vật tư) | `.doc` | Template HĐ thầu phụ trọn gói cung cấp cả NC + VT | ⚠️ Cần convert `.doc` → `.docx` (COM/LibreOffice) ở Phase 2 |
+| **SOL-CCM-FO-002.03** | Hợp đồng trọn gói (nhân công + thiết bị) | `.doc` | Template HĐ thầu phụ trọn gói cung cấp NC + TB | ⚠️ Cần convert `.doc` → `.docx` ở Phase 2 |
+| **SOL-CCM-FO-002.04** | Điều kiện chung hợp đồng trọn gói | `.docx` | Phần điều khoản chung (5+ điều: am hiểu TL, nội dung CV, tiến độ, xử lý tranh chấp, sửa đổi HĐ) | ✅ Parsed — narrative text |
+| **SOL-CCM-FO-002.05** | Hợp đồng Giao khoán | `.docx` | Template HĐ giao khoán NC/Tổ đội — 10 table (thông tin, giá trị, hạng mục, nghiệm thu, thanh toán) | ✅ Parsed — 10 tables |
+| **SOL-CCM-FO-002.06** | Hợp đồng mua bán | `.doc` | Template HĐ mua bán (NCC cấp vật tư, thiết bị) | ⚠️ Cần convert `.doc` → `.docx` ở Phase 2 |
+| **SOL-CCM-FO-002.07** | Đơn đặt hàng (PO) | `.xlsx` | 3 sheet: `(F.01)_SS GIA` (so sánh giá NCC), `PO` (đơn đặt hàng chính), `Po01 NLT (sua)` (PO nguyên liệu) | ✅ Parsed — 3 sheets |
+| **SOL-CCM-RG-001** | Quy định mã số hợp đồng | `.docx` | Regex + convention đánh mã HĐ và PO (bảng ví dụ) | ✅ Parsed |
+
+---
+
+## Detail — các form đã parse được
+
+### SOL-CCM-FO-002.01 — Bảng kiểm tra hợp đồng
+
+**Nhóm field thông tin HĐ (phần trên bảng):**
+- `phong_ban_du_an` (Phòng ban / Dự án) — string
+- `loai_hop_dong` — enum: `ChuDauTu` | `NCC` | `ThauPhu` | `ToDoi` | `ThietBiThue` | `Khac`
+- `ten_doi_tac` — string
+- `noi_dung_hop_dong` — text
+
+**Nhóm field checklist theo bộ phận (mỗi row = 1 bộ phận × nội dung × ý kiến):**
+
+| Bộ phận | Nội dung kiểm tra (check) | Field dữ liệu |
+|---|---|---|
+| PHÒNG BAN/DỰ ÁN (Đề xuất) | Soạn thảo (✓), Nội dung HĐ | `de_xuat_soan_thao: bool`, `de_xuat_noi_dung_ok: bool`, `de_xuat_ho_ten`, `de_xuat_ngay`, `de_xuat_y_kien: text` |
+| PHÒNG CUNG ỨNG | Điều khoản HĐ, Điều khoản t/toán, Rủi ro pháp lý HĐ | `cung_ung_dieu_khoan: bool`, `cung_ung_thanh_toan: bool`, `cung_ung_rui_ro: bool`, `cung_ung_ho_ten`, `cung_ung_ngay`, `cung_ung_y_kien: text` |
+| PHÒNG CCM | G/trị HĐ so với NS, Rủi ro pháp lý HĐ | `ccm_gia_tri_so_ns: bool`, `ccm_rui_ro: bool`, `ccm_ho_ten`, `ccm_ngay`, `ccm_y_kien: text` |
+| GIÁM ĐỐC (hoặc ủy quyền) | Ký kết, phát hành | `gd_ky_ket: bool`, `gd_ho_ten`, `gd_ngay`, `gd_y_kien: text` |
+
+**Business rule (từ ghi chú cuối bảng):**
+- HĐ với Chủ đầu tư → Đơn vị đề xuất có thể **bypass** Cung ứng + CCM, chuyển thẳng Giám đốc.
+- Các loại khác → PHẢI qua Cung ứng + CCM trước.
+- Mỗi bộ phận **01 ngày** xử lý. Quá 1 ngày không phản hồi → **auto approve** ("xem như đã thông qua").
+- Nếu cần kéo dài → phải ghi chú vào "Ý kiến" + thông báo cho Đề xuất.
+
+→ **Mapping sang workflow state:** file này chính là thể hiện UI của workflow bên `workflow-contract.md`.
+
+### SOL-CCM-FO-002.04 — Điều kiện chung
+
+Pure narrative template — 5+ điều khoản cố định (AM HIỂU TÀI LIỆU, NỘI DUNG CV, TIẾN ĐỘ, XỬ LÝ TRANH CHẤP, SỬA ĐỔI HĐ). Không có field động — dùng làm **appendix cố định đính kèm** cho HĐ trọn gói.
+
+→ **Data model:** lưu dạng `ContractClauseTemplate` với `Content: text (markdown)`, version theo đợt cập nhật. Cho phép admin edit qua rich text editor.
+
+### SOL-CCM-FO-002.05 — Hợp đồng Giao khoán
+
+10 bảng. Các nhóm field chính (suy từ số row/col):
+- Thông tin 2 bên (Bên A + Bên B) — 4 row × 2 col
+- Giá trị HĐ + hạng mục công việc — 8 row × 8 col (chi tiết hạng mục, đơn giá, khối lượng, thành tiền)
+- Nghiệm thu + thanh toán — 6 row × 4 col
+- Bảng tiến độ — 9 row × 11 col
+- Ký tên 2 bên — 1 row × 2 col
+
+→ **Phase 2:** parse từng table chi tiết sau khi có cấu trúc DB ổn định.
+
+### SOL-CCM-FO-002.07 — Đơn đặt hàng (xlsx)
+
+| Sheet | Rows × Cols | Mục đích |
+|---|---|---|
+| `(F.01)_SS GIA` | 84 × 36 | So sánh giá nhiều NCC cho cùng mặt hàng (chọn NCC tốt nhất) |
+| `PO` | 80 × 17 | Đơn đặt hàng chính — template chuẩn |
+| `Po01 NLT (sua)` | 74 × 12 | Variant PO cho NLT (nguyên liệu?) |
+
+→ **Phase 2:** implement xuất file Excel đúng format — dùng **EPPlus** hoặc **ClosedXML** thay vì OpenXml thủ công (giữ được style, formula, merged cells).
+
+### SOL-CCM-RG-001 — Quy định mã số hợp đồng ⭐ (critical — dùng ở Phase 3)
+
+**Contract code format:**
+
+| Loại HĐ | Format | Ví dụ |
+|---|---|---|
+| HĐ Thầu phụ (TP) | `{ProjectCode}/HĐTP/SOL&{PartnerAbbr}/{Seq}` | `FLOCK 01/HĐTP/SOL&HD/01` |
+| HĐ Giao khoán / Tổ đội / Nhân công cơ hữu | `{ProjectCode}/HĐGK/SOL&{PartnerAbbr}/{Seq}` | `FLOCK 01/HĐGK/SOL&PVL/01` |
+| HĐ NCC (cấp riêng từng dự án) | `{ProjectCode}/NCC/SOL&{PartnerAbbr}/{Seq}` | `FLOCK 01/NCC/SOL&CC1/01` |
+| HĐ nguyên tắc NCC | `{Year}/NCC/SOL&{PartnerAbbr}/{Seq}` | `2026/NCC/SOL&AKATI/01` |
+| HĐ Dịch vụ (cấp riêng) | `{ProjectCode}/HĐDV/SOL&{PartnerAbbr}/{Seq}` | `FLOCK 01/HĐDV/SOL&KG/01` |
+| HĐ nguyên tắc Dịch vụ | `{Year}/HĐDV/SOL&{PartnerAbbr}/{Seq}` | `2026/HĐDV/SOL&TTL/01` |
+
+**PO code format:**
+
+| Loại PO | Format | Ví dụ |
+|---|---|---|
+| PO vật tư, thiết bị (theo HĐ Nguyên tắc) | `{ProjectCode}/{PartnerAbbr}/PO {Seq}` | `FLOCK 01/TRUNGDUNG/PO 01` |
+| PO với TP/NCC/ĐVDV (không theo HĐ Nguyên tắc) | `{ProjectCode}/PO/SOL&{PartnerAbbr}/{Seq}` | `FLOCK 01/PO/SOL&PVL/01` |
+
+**Seq** bắt đầu từ `01`, tăng dần theo dự án + loại HĐ + đối tác.
+
+→ **Domain service Phase 3:** `IContractCodeGenerator.Generate(project, type, partner) → string` — transactional để tránh race condition khi gen Seq.
+
+---
+
+## TODO Phase 2 (form engine)
+
+- [ ] Convert 3 file `.doc` (FO-002.02, 002.03, 002.06) sang `.docx` qua COM automation hoặc LibreOffice headless
+- [ ] Parse chi tiết field của 5 file template HĐ (002.02, .03, .04, .05, .06) — mỗi form thành 1 spec JSON
+- [ ] Xây template engine: `Template + data → output .docx/.xlsx` (dùng **DocumentFormat.OpenXml** hoặc **Aspose.Words** + **EPPlus**)
+- [ ] UI form builder cho admin: gán template ↔ loại HĐ ↔ field layout
+- [ ] Preview PDF trước khi export final
--- a/docs/workflow-contract.md
+++ b/docs/workflow-contract.md
@ -0,0 +1,156 @@
+# Workflow — Quy trình trình ký Hợp đồng TP/NCC/Tổ đội
+
+> **Nguồn:** `QUY_TRINH/QT TRINH KY HOP DONG TP-NCC.docx`
+> **Raw dump:** [`workflow-raw.md`](workflow-raw.md)
+> **Phase 3 deliverable:** Implement state machine + role guard + SLA timer + notification
+
+## 1. Phạm vi
+
+Áp dụng cho Hợp đồng/Phụ lục HĐ ký với: **Thầu phụ (NTP)** · **Nhà cung cấp (NCC)** · **Tổ đội (TĐ)**. Tham chiếu ISO 9001.
+
+## 2. Glossary (viết tắt)
+
+| Mã | Nghĩa | Role trong system |
+|---|---|---|
+| **BOD** | Ban Giám đốc | `Director` |
+| **NĐUQ** | Người được ủy quyền | `AuthorizedSigner` |
+| **CCM** | Phòng Kiểm soát Chi phí | `CostControl` |
+| **PRO** | Phòng Cung ứng | `Procurement` |
+| **FIN** | Phòng Tài chính | `Finance` |
+| **ACT** | Phòng Kế toán | `Accounting` |
+| **EQU** | Phòng Thiết bị | `Equipment` |
+| **HRA** | Nhân sự - Hành chính (đóng dấu) | `HR_Admin` |
+| **PB** | Phòng ban | `Department` |
+| **BCH CT** | Ban chỉ huy công trường | `SiteCommand` |
+| **PD** | Giám đốc Thi công | `ProjectDirector` |
+| **PM** | Giám đốc Dự án | `ProjectManager` |
+| **TPB** | Trưởng Phòng ban | `DeptManager` |
+| **TBP** | Trưởng Bộ phận | `SectionLeader` |
+| **QS/NV.PB** | QS công trường / Nhân viên PB | `Drafter` (người soạn) |
+| **NTP/NCC/TĐ** | Đối tác ký HĐ | Partner (external — không login) |
+
+## 3. State Machine (9 phase)
+
+```mermaid
+stateDiagram-v2
+    [*] --> DangChon: Tạo mới
+    DangChon --> DangSoanThao: Chọn NCC xong (chuyển Drafter)
+    DangSoanThao --> DangGopY: Gửi email góp ý (7d)
+    DangGopY --> DangDamPhan: Nhận xong comment (7d)
+    DangDamPhan --> DangInKy: Thỏa thuận xong (7d)
+    DangInKy --> DangKiemTraCCM: Đã ký nháy QS/PD/TPB, chuyển CCM (1d)
+    DangKiemTraCCM --> DangTrinhKy: CCM ký nháy xong (3d)
+    DangTrinhKy --> DangDongDau: BOD/NĐUQ ký duyệt (1d)
+    DangDongDau --> DaPhatHanh: HRA đóng dấu xong
+    DaPhatHanh --> [*]: PB scan + gửi bản gốc + lưu Filing
+
+    DangSoanThao --> TuChoi: Cancel
+    DangGopY --> DangSoanThao: Revise
+    DangKiemTraCCM --> DangSoanThao: CCM reject
+    DangTrinhKy --> DangSoanThao: BOD reject
+    TuChoi --> [*]
+```
+
+## 4. Chi tiết từng phase
+
+| # | Phase (state) | Role thực hiện | Input | Output | SLA | Form liên quan |
+|---|---|---|---|---|---|---|
+| 1 | `DangChon` — Lựa chọn NTP/NCC | `PB` / `BCH CT` | Yêu cầu công việc | Chốt đối tác | — | (theo Quy trình Cung ứng SOL-PRO-SP-001) |
+| 2 | `DangSoanThao` — Soạn thảo HĐ | `Drafter` (QS/NV.PB) + `TBP`/`TPB` check | Template HĐ | Dự thảo HĐ | **7 ngày** | FO-002.02/.03/.04/.05/.06 (chọn loại phù hợp) |
+| 3 | `DangGopY` — Góp ý nội dung | `PD`/`PM`/`PRO`/`CCM`/`FIN`/`ACT`/`EQU` | Dự thảo | Comment (email → hệ thống) | **7 ngày** | (đính kèm comment thread) |
+| 4 | `DangDamPhan` — Đàm phán | `Drafter` + `TBP`/`TPB`/`PD`/`PM` | Comment | Bản cuối thỏa thuận | **7 ngày** | — |
+| 5 | `DangInKy` — In + đối tác ký | `Drafter` + **NTP/NCC/TĐ** (external) + `PD`/`PM`/`TPB` ký nháy | Bản cuối | 2 mặt, có chữ ký đối tác + ký nháy nội bộ | **1 ngày** | FO-002.01 (cover approval) |
+| 6 | `DangKiemTraCCM` — CCM kiểm tra | `CCM` (`TP.CCM` ký nháy) | HĐ đã ký nháy | HĐ CCM approved | **3 ngày** | FO-002.01 |
+| 7 | `DangTrinhKy` — BOD ký duyệt | `BOD` hoặc `NĐUQ` | HĐ CCM approved | HĐ ký duyệt | **1 ngày** | FO-002.01 |
+| 8 | `DangDongDau` — Đóng dấu | `HRA`/`ISO` | HĐ đã ký | HĐ có dấu | — | — |
+| 9 | `DaPhatHanh` — Phát hành + lưu trữ | `PB`/`BCH CT` + `CCM` | HĐ có dấu | Scan + bản gốc gửi NCC + lưu Filing System | — | — |
+
+**Tổng SLA:** ~19 ngày (phase 2-7) cho 1 HĐ hoàn chỉnh.
+
+## 5. Role × Phase Matrix (quyền xem/thao tác)
+
+Ký hiệu: `R` = read, `W` = write/update draft, `A` = approve (chuyển phase tiếp), `-` = không có quyền.
+
+| Role \ Phase | 1.Chọn | 2.Soạn | 3.GópÝ | 4.ĐàmPhán | 5.InKý | 6.CCMCheck | 7.BODKý | 8.ĐóngDấu | 9.PhátHành |
+|---|---|---|---|---|---|---|---|---|---|
+| **Drafter** (QS/NV.PB) | R | W,A | R | W,A | W,A | R | R | R | W |
+| **TBP/TPB** | R | R,A | R,A | R,A | R,A | R | R | R | R |
+| **PD/PM** | R | R | W,A | R,A | R,A | R | R | R | R |
+| **PRO/EQU/FIN/ACT** | A | R | W,A | R | - | - | - | - | R |
+| **CCM** | - | R | W,A | R | R | W,A | R | R | W |
+| **BOD/NĐUQ** | - | - | - | - | - | - | A | - | R |
+| **HRA** | - | - | - | - | - | - | - | W,A | R |
+| **Admin** (system) | R | R | R | R | R | R | R | R | R (+ override) |
+
+**Guard rule:**
+- Đặc biệt: HĐ với **Chủ đầu tư** → có thể **bypass** phase 3 + 6 (không cần PRO/CCM góp ý + kiểm tra). Cờ `BypassProcurementAndCCM: bool` ở entity HĐ.
+- Quá SLA mỗi phase không action → **auto-approve** (chuyển phase tiếp). Gửi notification warning khi còn 2h.
+- Nếu cần kéo dài → bộ phận kiểm tra phải comment vào "Ý kiến" trước khi SLA hết.
+
+## 6. Notification triggers
+
+| Event | Người nhận | Kênh |
+|---|---|---|
+| Chuyển `DangSoanThao` → `DangGopY` | Tất cả role góp ý (PD/PM/PRO/CCM/FIN/ACT) | email + in-app |
+| Chuyển `DangKiemTraCCM` | `CCM` | email + in-app |
+| Chuyển `DangTrinhKy` | `BOD` + `NĐUQ` | email + in-app (high priority) |
+| Quá SLA 80% thời gian | Role đang giữ phase | in-app warning |
+| Quá SLA → auto-approve | Drafter + role giữ phase | email + in-app (log audit) |
+| Reject (quay về `DangSoanThao`) | Drafter | email + in-app |
+
+## 7. Data model implication (cho Phase 3)
+
+```csharp
+// Domain
+public enum ContractPhase {
+    DangChon = 1,
+    DangSoanThao,
+    DangGopY,
+    DangDamPhan,
+    DangInKy,
+    DangKiemTraCCM,
+    DangTrinhKy,
+    DangDongDau,
+    DaPhatHanh,
+    TuChoi
+}
+
+public class Contract : AuditableEntity {
+    public Guid Id { get; set; }
+    public string MaHopDong { get; set; }  // tự gen theo RG-001
+    public ContractType Type { get; set; }  // HDTP, HDGK, NCC, HDDV...
+    public ContractPhase Phase { get; set; }
+    public Guid SupplierId { get; set; }
+    public Guid ProjectId { get; set; }
+    public decimal GiaTri { get; set; }
+    public bool BypassProcurementAndCCM { get; set; }
+    public DateTime? SlaDeadline { get; set; }  // khi nào phase hiện tại hết hạn
+    // ...
+    public List<ContractComment> Comments { get; set; }  // thread góp ý phase 3
+    public List<ContractApproval> Approvals { get; set; }  // ai ký phase nào, lúc nào
+    public List<ContractAttachment> Attachments { get; set; }  // scan bản gốc, file export
+}
+
+public class ContractApproval {
+    public Guid ContractId { get; set; }
+    public ContractPhase Phase { get; set; }
+    public Guid ApproverUserId { get; set; }
+    public DateTime? ApprovedAt { get; set; }
+    public ApprovalDecision Decision { get; set; }  // Approve | Reject | AutoApprove
+    public string? Comment { get; set; }
+}
+```
+
+**Service chính:**
+- `IContractWorkflowService.TransitionAsync(contractId, targetPhase, userId, comment)` — check guard + update state + tạo approval + notify
+- `IContractCodeGenerator.GenerateAsync(projectId, type, supplierId)` — dùng SEMAPHORE/transaction tránh race condition
+- `ISlaExpiryJob` — hosted service chạy mỗi 15 phút, auto-approve các HĐ quá hạn
+
+## 8. Business rules summary
+
+1. **Một role chỉ có 1 phase active tại 1 thời điểm** cho 1 HĐ.
+2. **Auto-approve nếu quá SLA** — nhưng phải log `Decision=AutoApprove` rõ ràng trong `ContractApproval`.
+3. **Reject → quay về `DangSoanThao`** — Drafter nhận lại, toàn bộ approval trước đó bị invalidate (kept as history).
+4. **Không cho xóa HĐ** đã qua phase 5 (`DangInKy`) — chỉ soft delete.
+5. **Mã HĐ** gen theo `forms-spec.md § RG-001` — chỉ gen khi transition sang phase 5.
+6. **Audit log đầy đủ** — mọi transition đều ghi `AuditLog(entityId, action, oldPhase, newPhase, userId, timestamp, diff)`.
--- a/docs/workflow-raw.md
+++ b/docs/workflow-raw.md
@ -0,0 +1,63 @@
+MỤC ĐÍCH/PURPOSE:
+Nhằm thống nhất các bước thực hiện trình ký Hợp đồng Thầu phụ/Nhà cung cấp/Tổ đội.
+To unify the steps in the process of signing Subcontractor/Supplier/Team Contract.
+Đảm bảo sự tuân thủ và vận hành Hệ thống một cách đồng nhất trên tất cả các Phòng Ban/Dự án của Công ty TNHH Xây dựng Solutions.
+Ensure compliance and consistent of system operation through all Departments and Projects of Solutions Construction Co., Ltd.
+PHẠM VI VÀ ĐỐI TƯỢNG ÁP DỤNG/SCOPE AND OBJECTS OF APPLICATION:
+Áp dụng đối với các hợp đồng/phụ lục hợp đồng Thầu phụ/Nhà cung cấp/Tổ đội tại các Phòng ban/Dự án của Công ty TNHH Xây dựng Solutions như sau:
+This procedure shall apply to Subcontractor/Supplier/Team contracts and contract appendices at the Departments and Projects of Solutions Construction Co., Ltd., as follows:
+TÀI LIỆU THAM KHẢO/REFERENCES:
+Tiêu chuẩn ISO 9001/ISO 9001 standard.
+ĐỊNH NGHĨA, TỪ VIẾT TẮT/DEFINITIONS, ABBREVIATIONS:
+SOL		: Công ty TNHH Xây dựng Solutions/Solutions Construction Co., Ltd
+BOD	: Ban Giám đốc/Board of Directors
+NĐUQ	: Người được ủy quyền/Authorized person
+CCM	: Phòng Kiểm soát Chi phí/Cost Control Management Department
+PRO		: Phòng Cung ứng/Procurement Department
+FIN		: Phòng Tài chính/Financial Department
+ACT		: Phòng Kế toán/Accounting Department
+EQU		: Phòng Thiết bị/Equipment Department
+HRA	: Phòng Nhân sự - Hành chính/HRA Department
+PB		: Phòngban/Department
+TP		: Trưởng Phòng ban/Department Manager
+TBP		: Trưởng Bộ phận/Section Leader
+NV		: Nhân viên/Officer
+BCH CT	: Ban chỉ huy công trường/Site Management Team
+PD		: Giám đốc Thi công/Project Director
+PM		: Giám đốc Dự án/Project Manager
+QS		: QS công trường/QS
+HĐ		: Hợp đồng/Contract
+HĐTG	: Hợp đồng Trọn gói/Lump sum Contract
+HĐNC	: Hợp đồng Nhân công/Workmen Contract
+NTP	 	: Nhà thầu phụ/Subcontractor
+NCC	 	: Nhà cung cấp/Supplier
+TĐ		: Tổ đội/Team
+QUY TRÌNH/PROCEDURE:
+Lưu đồ/Flow chart
+Diễn giải/Description
+
+--- TABLE 1 (12r x 5c) ---
+Bước | Step || Quy trình | Procedure || Trách nhiệm | Responsibilities || Biểu mẫu | Forms || Thời gian | Time
+ ||  ||  ||  || 
+ ||  || PB/BCH CT || SOL-PRO-SP-001 Quy trình Cung ứng | SOL-PRO-SP-001 Procurement Procedure || 
+ ||  || QS/NV.PB/ | TBP/TPB || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 07 ngày | 07 days
+ ||  || PD/PM/PRO/ | CCM/FIN/ACT || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 07 ngày | 07 days
+ ||  || QS/NV.PB/ | TBP/TPB/ PD/PM || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 07 ngày | 07 days
+ ||  || NTP/NCC/TĐ || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 07 ngày | 07 days
+ ||  || CCM || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 03 ngày | 03 days
+ ||  || BOD/ | NĐUQ || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 01 ngày | 01 days
+ ||  || HRA || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 
+ ||  || PB/BCH CT/ CCM || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 
+ ||  ||  || SOL-CCM-FO-002.01.v01 | Chấp thuận Hợp đồng Contract approval cover | SOL-CCM-FO-002.02.v01 | Hợp đồng trọn gói - Nhân công, Vật tư | Lump sum contract - Labor and Material  | SOL-CCM-FO-002.03.v01 | Hợp đồng trọn gói - Nhân công, Thiết bị | Lump sum contract - Labor and Equipment  | SOL-CCM-FO-002.04.v01 | Hợp đồng trọn gói – Điều kiện chung | Lump sum contract – General conditions | SOL-CCM-FO-002.05.v01 | Hợp đồng giao khoán  | Workmen contract  | SOL-CCM-FO-002.06.v01 | Hợp đồng mua bán | Purchase contract  | SOL-CCM-FO-002.07.v01 | Đơn đặt hàng | Purchase order  | SOL-CCM-RG-001  | Quy định mã số hợp đồng và đơn hàng | Regulation on contract and purchasing order code || 
+
+--- TABLE 2 (10r x 3c) ---
+BƯỚC | STEP || TRÁCH NHIỆM | RESPONSIBILITIES || NỘI DUNG CHI TIẾT | DETAIL
+Lựa chọn NTP/NCC | Select NTP/NCC || PB/BCH CT || Thống nhất chọn NTP/NCC/ĐTC theo quy định. | Select NTP/NCC/ĐTC in accordance with regulations. | Tham khảo Quy trình Cung ứng để so sánh và lựa chọn NTP/NCC/TĐC đúng quy định.  | Refer to the Procurement Procedure to compare and select NTP/NCC/ĐTC in accordance with regulations.
+Soạn thảo hợp đồng | Draft the contract || QS/NV.PB/ | TBP/TPB || QS/NV.PB soạn dự thảo HĐ. | QS/NV.PB drafts Contract. | TBP/TPB kiểm tra các nội dung phù hợp với gói thầu và biểu mẫu HĐ. | TBP/TPB checks contents in compliance with the packages and Forms of Contract. | QS/NV.PB gởi dự thảo HĐ cho các Phòng ban để lấy ý kiến qua Email. | QS/NV.PB sends draft contract to relevant Departments for obtaining comments via email.
+Góp ý nội dung | Feedback content || PD/PM/PRO/ | CCM/FIN/ACT || PM/PD góp ý về phạm vi công việc, tiến độ, chất lượng, biện pháp thi công... (đối với HĐ của BCH CT). | PD/PM comments on scope of words, construction schedule, quality, construction methods,… (for BCH CT’s contract). | EQU góp ý (thuê/mua thiết bị). | EQU comments on hiring and purchasing equipment. | PRO góp ý (vật tư/thầu phụ trọn gói). | PRO comments on material and lumpsum Subcontractor. | CCM góp ý về các điều khoản liên quan đến chi phí. | CCM comments on provisions relating to cost. | ACT/FIN góp ý về điều kiện thanh toán, bảo lãnh, bảo hành. | ACT/FIN Comments on term of payments, guarantees, project warranty.
+Đàm phán, thương thảo hợp đồng | Negotiate the contract terms || QS/NV.PB/ | TBP/TPB/PD/PM || PB/BCH CT đàm phán các điều khoản về chất lượng, giao hàng, giá trị HĐ, điều kiện thanh toán, tạm ứng, ... | PB/BCH CT negotiates provisions on quality, product delivery, contract value, term of payment, advance payment, etc.  | Các Phòng chức năng tham gia thương thảo nếu có yêu cầu. | Departments participates in negotiation if required.
+In hợp đồng | Print the contract || QS/NV.PB || NTP/NCC/TĐ in hợp đồng 2 mặt, ký, đóng dấu Hợp đồng và gửi về cho PB/BCH CT. | NTP/NCC/TĐ prints double-sided contract, signs and seals on the contract and sends to PB/BCH CT. | Cập nhật số Hợp đồng theo quy định. | Update the contract number. | PD/PM/TPB kiểm tra các điều khoản hợp đồng và ký nháy trên từng HĐ đúng theo các vị trí quy định. | PD/PM/TPB checks provisions contract and initializes on each contract. | PD/PM/TPB/TBP ký duyệt và cho ý kiến (nếu có) lên tờ cover chấp thuận HĐ (SOL-CCM-FO-002.01). | PD/PM/TPB signs and gives comments (if any) on the cover of Contract approval cover (SOL-CCM-FO-002.01). | QS/NV.PB chuyển HĐ cho CCM. | QS/NV.PB handover the contract to CCM Dept.
+Kiểm tra  | Review and verify || CCM || CCM kiểm tra, TP.CCM ký nháy trên từng hợp đồng; ký duyệt và cho ý kiến (nếu có) lên Chấp thuận HĐ (SOL-CCM-FO-002.01.v01). | CCM checks and initializes on each contract; signs and gives comments (if any) on the Contract approval cover (SOL-CCM-FO-002.01.v01).
+Duyệt | Approve || BOD/ | NĐUQ || Xem xét và ký duyệt Hợp đồng. | Reviewing and signing the Contract.
+Đóng dấu hợp đồng | Seal the contract || HRA/ISO || PB/BCH CT chuyển hợp đồng đã được ký duyệt đến HRA/ISO để đóng dấu theo quy định. | PB/BCH CT transfrom the approved contract to HRA for seal the contract in accordance with regulations.
+Phát hành hợp đồng. Lưu trữ hồ sơ | Issue and archive the contract || PB/BCH CT/ | CCM || PB/BCH CT scan và gởi 01 bản gốc cho CCM.  | PB/BCH CT scan and send the original contract to CCM | PB/BCH CT thông báo và chuyển bản gốc hợp đồng đã ký (theo đúng số lượng) đến NTP/NCC. | Notifying and sending originals of the signed contract (in accordance with quantity) to NTP/NCC.  | Lưu trữ bản gốc hợp đồng. | Archive the original contract. | Lưu trữ trên Server theo Filing System (Hợp đồng bản cứng chính và bản scan). | Keep the contract on Filing System (hard copy and soft copy).