[CLAUDE] Docs: chốt session Tier 3 feature-complete + versioned workflow

- Session log 2026-04-22-0300 (A→K): attachment, SignalR, form builder,
  PDF, dynamic + versioned workflow, nested menu, 3-panel permissions,
  seed master, brand identity, content polish, Gitea fix
- STATUS: Tier 3 feature-complete snapshot + cumulative stats (24 tables,
  ~50 endpoints, 8 migrations); next-up = UAT + Email SMTP (blocked) +
  rotate creds + SQL backup schedule
- HANDOFF: rewrite brief cho session mới — phase 5 prod done, Tier 3
  đóng gói, quick sanity-check 2 app, versioned workflow quick ref,
  file active hiện trạng, git state
- migration-todos: tick Tier 3 items (attachment/realtime/form builder/
  PDF/dynamic+versioned workflow/nested menu) + thêm iter-3 versioned
  workflow section + post-launch list
- schema-diagram: +5 table (Notifications, WorkflowTypeAssignments,
  WorkflowDefinitions, WorkflowSteps, WorkflowStepApprovers); indexes
  mới, cardinality FK restrict cho pinned policy, truy vấn tiêu biểu
- workflow-contract: +section 7bis resolution order, 7ter admin
  designer flow, updated data model + code pointers Tier 3
- PROJECT-MAP: module map post-Tier-3 (3 box mới Notification/
  Attachment/Branding + Infra/DevOps box), API namespace đầy đủ,
  architectural wins 5 điểm
- contract-workflow skill: versioned workflow section, policy
  resolution code snippet, admin designer flow, code pointers Tier 3,
  tier 4+ backlog
- gotchas +7 bẫy mới (#26-32): SignalR WebSocket headers, interceptor
  2-phase pattern, LibreOffice mirror 404, PS 5.1 UTF-16 GITHUB_PATH,
  PS 5.1 diacritics parse, Dialog size TS, NavLink end query-params

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.claude/skills/contract-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: contract-workflow
-description: State machine 9 phase cho hợp đồng TP/NCC/Tổ đội — transition guard, role check, SLA deadline, auto-gen mã HĐ RG-001. Dùng khi debug chuyển phase, 403 forbidden, code sai format, bypass Chủ đầu tư.
+description: State machine 9 phase cho hợp đồng TP/NCC/Tổ đội — transition guard, role check, SLA deadline, auto-gen mã HĐ RG-001, versioned workflow admin-configurable per ContractType. Dùng khi debug chuyển phase, 403 forbidden, code sai format, bypass Chủ đầu tư, workflow policy resolution.
 when-to-use:
   - "transition contract"
   - "chuyển phase hợp đồng"
@@ -9,11 +9,15 @@ when-to-use:
   - "reject contract về draft"
   - "mã HĐ sai format"
   - "bypass CCM chủ đầu tư"
+  - "versioned workflow"
+  - "quy trình mới HĐ cũ giữ cũ"
+  - "WorkflowDefinition pin"
+  - "admin workflow designer"
 ---
 
 # Contract Workflow Skill
 
-> **Status:** Phase 3 IMPLEMENTED (MVP — state transitions + code gen). Còn thiếu: SLA hosted service, email notify, in-app realtime.
+> **Status:** Tier 3 FEATURE-COMPLETE — State transitions + code gen + SLA job + attachment + realtime notify + versioned workflow admin-configurable. Còn thiếu: email outbox (SMTP), User-kind approver runtime, warning 20% SLA.
 
 ## Domain entities (implemented)
 
@@ -21,8 +25,14 @@ when-to-use:
 Contract ─────< ContractApproval (lịch sử mỗi transition)
          ─────< ContractComment (thread góp ý)
          ─────< ContractAttachment (scan signed/sealed)
+         ─────> WorkflowDefinition (PINNED at create-time, nullable FK)
 
 ContractCodeSequence (Prefix PK, LastSeq) — gen mã HĐ atomic
+
+WorkflowDefinition ─────< WorkflowStep ─────< WorkflowStepApprover
+  (Code + Version + IsActive + ContractType)    (Kind=Role|User + AssignmentValue)
+
+WorkflowTypeAssignment (admin override legacy, fall back khi Contract.WorkflowDefinitionId == null)
 ```
 
 ## 9 phase state machine
@@ -39,11 +49,69 @@ Alternates:
 
 Bypass (HĐ Chủ đầu tư, BypassProcurementAndCCM=true):
   DangInKy → DangTrinhKy (skip CCM)
+
+Policy variants (hardcoded fallback, dùng khi không có WorkflowDefinition pin):
+  - Standard (8 phase full CCM) — Thầu phụ, Giao khoán, NCC
+  - SkipCcm (7 phase bỏ CCM) — Dịch vụ, Mua bán, Nguyên tắc NCC, Nguyên tắc DV
 ```
 
-## SLA mặc định (sau transition, set `Contract.SlaDeadline = UtcNow + sla`)
+## Versioned workflow (Tier 3) — policy resolution runtime
 
-| Phase | SLA |
+```csharp
+// ContractWorkflowService.LoadPolicyAsync(contractId):
+//   1. Load contract
+var c = await db.Contracts.FindAsync(contractId);
+
+//   2. If pinned — nạp từ DB
+if (c.WorkflowDefinitionId != null) {
+    var def = await db.WorkflowDefinitions
+        .Include(d => d.Steps).ThenInclude(s => s.Approvers)
+        .FirstAsync(d => d.Id == c.WorkflowDefinitionId);
+    return WorkflowPolicyRegistry.FromDefinition(def);
+    // → xây policy runtime từ Steps.Approvers
+    // → Role-kind → allowedRoles
+    // → User-kind (data model ready, iter sau enable guard)
+}
+
+//   3. Nếu không pin — check admin override WorkflowTypeAssignments
+var assignment = await db.WorkflowTypeAssignments.FirstOrDefaultAsync(a => a.ContractType == c.Type);
+if (assignment != null) return WorkflowPolicyRegistry.ByName(assignment.PolicyName);
+
+//   4. Fallback hardcoded
+return WorkflowPolicyRegistry.For(c.Type); // Standard or SkipCcm
+```
+
+## Admin designer flow (Tạo version mới)
+
+```
+Admin → /system/workflows → grid 7 type card
+      → click "HĐ Mua bán" → /system/workflows/MuaBan
+      → thấy QT-MB-v01 active + history
+      → click "Tạo phiên bản mới" (có thể Clone từ v01)
+      → Designer modal:
+          Code:  QT-MB (auto-fill)
+          Version: v02 (auto-compute max+1)
+          Name + Description
+          Steps (repeatable, reorderable):
+            Step 1: Phase=2 (DangSoanThao) SLA=7d
+                    Approvers: +Role Drafter, +Role DeptManager
+            Step 2: Phase=3 (DangGopY) SLA=7d
+                    Approvers: +Role ProjectManager, +User {userId alice}
+            ...
+      → Save → POST /api/workflows
+        BE atomically:
+          UPDATE WorkflowDefinitions SET IsActive=0 WHERE ContractType=5 AND IsActive=1;
+          INSERT WorkflowDefinitions (Id, Code='QT-MB', Version=2, IsActive=1, ...);
+          INSERT WorkflowSteps / WorkflowStepApprovers batch;
+      → trở về /system/workflows/MuaBan → v02 active badge, v01 archived "N HĐ còn chạy"
+
+      → HĐ cũ pin v01 KHÔNG BỊ ẢNH HƯỞNG (Contract.WorkflowDefinitionId = v01.Id)
+      → HĐ mới tạo sau đó pick active → pin v02
+```
+
+## SLA mặc định (khi pinned def không có SlaDays → fallback)
+
+| Phase | SLA fallback |
 |---|---|
 | DangSoanThao | 7d |
 | DangGopY | 7d |
@@ -54,9 +122,11 @@ Bypass (HĐ Chủ đầu tư, BypassProcurementAndCCM=true):
 | DangDongDau | none |
 | DaPhatHanh | none |
 
-## Role × Phase guard matrix
+Nếu pinned WorkflowStep có `SlaDays > 0` → ưu tiên value của step đó.
 
-Xem `ContractWorkflowService.Transitions` dictionary. Tóm tắt:
+## Role × Phase guard matrix (hardcoded Standard)
+
+Xem `WorkflowPolicies.Standard.Transitions`. Tóm tắt:
 
 | Phase hiện tại → target | Roles được phép |
 |---|---|
@@ -75,6 +145,8 @@ Xem `ContractWorkflowService.Transitions` dictionary. Tóm tắt:
 
 **Admin bypass:** user có role `Admin` → pass mọi guard. Dùng để test flow nhanh.
 
+**Versioned override:** Nếu HĐ có `WorkflowDefinitionId` pin → allowed roles sẽ lấy từ `WorkflowStep.Approvers` (Role-kind) thay vì hardcoded. Admin có thể config 2 role bất kỳ cho step 3, guard theo đó.
+
 ## Mã HĐ gen (RG-001)
 
 Xem `ContractCodeGenerator.GenerateAsync()`. Format theo loại HĐ:
@@ -89,78 +161,116 @@ Xem `ContractCodeGenerator.GenerateAsync()`. Format theo loại HĐ:
 | HopDongNguyenTacNCC | `{Year}/NCC/SOL&{SupplierCode}/{Seq:D2}` ← framework |
 | HopDongNguyenTacDichVu | `{Year}/HĐDV/SOL&{SupplierCode}/{Seq:D2}` ← framework |
 
-**Transactional:** `BeginTransactionAsync(IsolationLevel.Serializable)` + `ContractCodeSequences` row UPDATE. Tránh race condition khi 2 HĐ cùng prefix gen song song.
+**Transactional:** `BeginTransactionAsync(IsolationLevel.Serializable)` + `ContractCodeSequences` row UPSERT. Tránh race condition khi 2 HĐ cùng prefix gen song song.
 
 **Gen khi nào:** transition sang `DangDongDau`. Nếu `MaHopDong` đã có (reject rồi approve lại) → giữ nguyên, không gen lại.
 
-## Code pointers
+## Code pointers (Tier 3 updated)
 
-**Backend:**
-- `Domain/Contracts/Contract.cs` — aggregate root
+**Backend Domain:**
+- `Domain/Contracts/Contract.cs` — aggregate root (+ `WorkflowDefinitionId?`)
 - `Domain/Contracts/ContractApproval.cs` — history
 - `Domain/Contracts/ContractComment.cs` — thread
 - `Domain/Contracts/ContractAttachment.cs` — files
 - `Domain/Contracts/ContractCodeSequence.cs` — seq table
-- `Application/Contracts/Services/IContractWorkflowService.cs` + `IContractCodeGenerator.cs`
-- `Infrastructure/Services/ContractWorkflowService.cs` — state + role guard
-- `Infrastructure/Services/ContractCodeGenerator.cs` — transactional gen
-- `Application/Contracts/ContractFeatures.cs` — CQRS (Create, Update draft, Transition, AddComment, List, Inbox, GetDetail, Delete)
-- `Api/Controllers/ContractsController.cs` — REST endpoints
+- `Domain/Contracts/WorkflowPolicy.cs` — record + `WorkflowPolicies.Standard/SkipCcm` + `WorkflowPolicyRegistry.{For, FromDefinition, ByName}`
+- **`Domain/Contracts/WorkflowDefinition.cs`** — versioned policy header
+- **`Domain/Contracts/WorkflowStep.cs`** — step trong definition
+- **`Domain/Contracts/WorkflowStepApprover.cs`** — Role/User approver (+ `ApproverKind` enum)
+- `Domain/Contracts/WorkflowTypeAssignment.cs` — legacy admin override
 
-**Frontend:**
-- `fe-admin/src/pages/contracts/ContractsListPage.tsx` — full list admin view
-- `fe-admin/src/pages/contracts/ContractDetailPage.tsx` — detail + timeline + action
-- `fe-user/src/pages/InboxPage.tsx` — HĐ chờ role tôi xử lý
-- `fe-user/src/pages/contracts/ContractCreatePage.tsx` — tạo HĐ draft
-- `fe-user/src/pages/contracts/ContractDetailPage.tsx` — duplicate có chủ đích
-- `fe-user/src/pages/contracts/MyContractsPage.tsx` — HĐ của tôi
-- `fe-admin/src/types/contracts.ts` + `fe-user/src/types/contracts.ts` — type mirror
-- `fe-admin/src/components/PhaseBadge.tsx` — badge màu theo phase
+**Backend Application:**
+- `Application/Contracts/Services/IContractWorkflowService.cs` + `IContractCodeGenerator.cs`
+- `Application/Contracts/ContractFeatures.cs` — CQRS (Create pin WorkflowDefId, Update draft, Transition, AddComment, List, Inbox, GetDetail, Delete)
+- `Application/Contracts/ContractAttachmentFeatures.cs` — Upload/Download/Delete CQRS
+- **`Application/Contracts/WorkflowAdminFeatures.cs`** — `GetWorkflowAdminOverviewQuery` + `CreateWorkflowDefinitionCommand`
+
+**Backend Infrastructure:**
+- `Infrastructure/Services/ContractWorkflowService.cs` — resolve policy (pinned → override → fallback), state + role guard
+- `Infrastructure/Services/ContractCodeGenerator.cs` — transactional gen
+- `Infrastructure/Services/NotificationService.cs` — write to DbContext (caller atomicity)
+- `Infrastructure/Persistence/Interceptors/NotificationPushInterceptor.cs` — auto-push via SignalR
+
+**Backend Api:**
+- `Api/Controllers/ContractsController.cs` — REST endpoints
+- **`Api/Controllers/WorkflowsController.cs`** — admin overview + create new version
+- `Api/Hubs/NotificationHub.cs` + `Api/Realtime/SignalRNotifier.cs`
+
+**Frontend Admin:**
+- `fe-admin/src/pages/contracts/{ContractsListPage, ContractCreatePage, ContractDetailPage}.tsx`
+- `fe-admin/src/pages/system/WorkflowsPage.tsx` — URL-driven landing + per-type
+- `fe-admin/src/components/workflow/{WorkflowDesigner, DefinitionCard}.tsx`
+- `fe-admin/src/components/{PhaseBadge, WorkflowSummaryCard, ContractAttachmentsSection, DynamicForm, SlaTimer}.tsx`
+
+**Frontend User:**
+- `fe-user/src/pages/InboxPage.tsx` — filter `?type=X`
+- `fe-user/src/pages/contracts/{ContractCreatePage, ContractDetailPage, MyContractsPage}.tsx`
+- `fe-user/src/components/{Layout, ContractAttachmentsSection, SlaTimer, NotificationBell}.tsx`
 
 ## API endpoints
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/contracts` | List với filter phase/supplier/project + paging |
+| GET | `/api/contracts` | List với filter phase/supplier/project/type + paging + pendingMe |
 | GET | `/api/contracts/inbox` | HĐ chờ role của user xử lý |
-| GET | `/api/contracts/{id}` | Detail + approvals + comments + attachments |
-| POST | `/api/contracts` | Tạo draft (Phase = DangSoanThao) |
+| GET | `/api/contracts/{id}` | Detail + approvals + comments + attachments + pinned workflow |
+| POST | `/api/contracts` | Tạo draft — pin `WorkflowDefinitionId = active version for type` |
 | PUT | `/api/contracts/{id}` | Update draft (chỉ khi Phase = DangSoanThao) |
 | POST | `/api/contracts/{id}/transitions` | Chuyển phase (body: `{targetPhase, decision, comment}`) |
 | POST | `/api/contracts/{id}/comments` | Thêm comment vào thread |
+| POST | `/api/contracts/{id}/attachments` | Upload file (multipart, 20MB, MIME whitelist) |
+| GET | `/api/contracts/{id}/attachments/{aid}` | Download stream |
+| DELETE | `/api/contracts/{id}/attachments/{aid}` | Delete (+ cleanup file) |
 | DELETE | `/api/contracts/{id}` | Soft delete (chỉ < DangInKy) |
+| **GET** | **`/api/workflows`** | Admin: overview per ContractType (active + history + "N HĐ còn chạy") |
+| **GET** | **`/api/workflows/{type}`** | Per-type definitions + steps + approvers |
+| **POST** | **`/api/workflows`** | Create new version (auto-increment + deactivate old) |
 
 ## Guard Rules đã implement
 
-- **State adjacency:** chỉ cho chuyển giữa các (from, to) đã khai báo trong `Transitions` dict
-- **Role check:** role của actor phải ∈ allowed roles của transition đó
+- **State adjacency:** chỉ cho chuyển giữa các (from, to) đã khai báo trong `policy.Transitions` (pinned def hoặc hardcoded)
+- **Role check:** role của actor phải ∈ allowed roles của transition đó (từ Role-kind approvers hoặc hardcoded)
 - **Admin bypass:** role `Admin` pass mọi check
-- **System bypass:** `actorUserId == null` + `Decision = AutoApprove` → cho phép (dành cho SLA job Phase 3.2)
-- **Bypass CCM:** `Contract.BypassProcurementAndCCM=true` cho phép `DangInKy → DangTrinhKy` (skip CCM). Default false → phải qua CCM
+- **System bypass:** `actorUserId == null` + `Decision = AutoApprove` → cho phép (dành cho SLA job)
+- **Bypass CCM:** `Contract.BypassProcurementAndCCM=true` cho phép `DangInKy → DangTrinhKy` (skip CCM)
 - **Self-delete:** không cho xóa HĐ đã qua `DangInKy`
+- **Versioned pin:** `Contract.WorkflowDefinitionId` pinned at create → không update sau đó. FK restrict → admin không xóa được def nếu HĐ còn tham chiếu
 
-## Workflow tạo HĐ end-to-end (testable)
+## Workflow tạo HĐ end-to-end (testable, Tier 3)
 
 ```bash
-# 1. Setup master data
-POST /api/suppliers  { code: "PVL", name: "...", type: 1 }
-POST /api/projects   { code: "FLOCK 01", name: "..." }
+# 1. Setup master data (auto-seeded: 5 supplier + 3 project + 9 dept)
+# 2. Admin tạo version mới cho HĐ Mua bán
+POST /api/workflows
+{
+  "code": "QT-MB",
+  "name": "Quy trình Mua bán v02",
+  "contractType": 5,
+  "steps": [
+    { "order": 1, "phase": 2, "name": "Soạn thảo", "slaDays": 7,
+      "approvers": [{ "kind": 1, "assignmentValue": "Drafter" }, { "kind": 1, "assignmentValue": "DeptManager" }] },
+    { "order": 2, "phase": 3, "name": "Góp ý", "slaDays": 7,
+      "approvers": [{ "kind": 1, "assignmentValue": "ProjectManager" }, { "kind": 2, "assignmentValue": "{userId}" }] },
+    ...
+  ]
+}
+# → Version=02, IsActive=1, v01 deactivated
 
-# 2. Tạo HĐ
-POST /api/contracts  { type: 2, supplierId, projectId, giaTri: 150000000, tenHopDong: "..." }
-# → Phase = DangSoanThao, SlaDeadline = +7d
+# 3. User tạo HĐ Mua bán → pin WorkflowDefinitionId = v02.Id
+POST /api/contracts { type: 5, supplierId, projectId, giaTri: ..., tenHopDong: "..." }
+# → Phase=DangSoanThao, SlaDeadline=+7d, WorkflowDefinitionId=v02
 
-# 3. Submit góp ý
-POST /api/contracts/{id}/transitions  { targetPhase: 3, decision: 1, comment: "..." }
+# 4. Transition — guard load từ v02.Steps.Approvers
+POST /api/contracts/{id}/transitions { targetPhase: 3, decision: 1, comment: "..." }
 
-# 4. Chuyển qua các phase (với admin)
-→ 4 DangDamPhan → 5 DangInKy → 6 DangKiemTraCCM → 7 DangTrinhKy
+# 5. Chuyển qua các phase
+→ 4 DangDamPhan → 5 DangInKy → (skip CCM nếu SkipCcm policy) → 7 DangTrinhKy
 
-# 5. BOD ký → gen mã HĐ
+# 6. BOD ký → gen mã HĐ
 → 8 DangDongDau
-  # contract.MaHopDong = "FLOCK 01/HĐGK/SOL&PVL/01"
+  # contract.MaHopDong = "FLOCK 01/MB/SOL&PVL/01"
 
-# 6. HRA đóng dấu + phát hành
+# 7. HRA đóng dấu + phát hành
 → 9 DaPhatHanh
 ```
 
@@ -171,15 +281,17 @@ POST /api/contracts/{id}/transitions  { targetPhase: 3, decision: 1, comment: ".
 - **Race condition gen mã song song** → dùng `IsolationLevel.Serializable`, không skip.
 - **SLA Deadline không reset khi reject** → `TransitionAsync` luôn reset theo target phase, kể cả reject.
 - **Comment ở phase sai** → `AddCommentCommand` luôn lấy phase hiện tại tại thời điểm comment.
-- **FE hiển thị next phase button** → map `NEXT_PHASES` ở FE phải match BE `Transitions`. Nếu BE đổi, FE quên update → user click → 403.
+- **FE hiển thị next phase button** → RESOLVED Tier 3. FE dùng `contract.workflow.nextPhases` từ BE (pinned policy → single source of truth).
+- **WorkflowDefinition cascade delete** → NÊN restrict FK. Nếu cascade sẽ xóa Contract cũ → data loss. Đã fix trong migration.
+- **User-kind approver không enforce runtime** — designer cho chọn nhưng guard v1 chỉ check Role. Iter 2 cần wire `step.Approvers.Where(a => a.Kind == User)` vào check.
 
-## Phase 3 iteration 2 (còn thiếu)
+## Tier 4+ (còn thiếu / future)
 
-- [ ] `SlaExpiryJob` BackgroundService — auto-approve khi quá hạn (xem `docs/flows/sla-expiry-flow.md`)
-- [ ] Warning notification khi còn 20% SLA
-- [ ] Email notification (MailKit) khi chuyển phase
-- [ ] In-app notification badge — SignalR push
-- [ ] Upload attachment endpoint + FE (multipart)
-- [ ] RowVersion optimistic concurrency (2 user cùng duyệt)
+- [ ] Warning notification 20% SLA (`SlaWarningSent` flag đã có)
+- [ ] User-kind approver runtime guard (data model ready)
+- [ ] Email notification (MailKit) khi chuyển phase — BLOCKED SMTP
+- [ ] RowVersion optimistic concurrency (2 user cùng duyệt → 409)
 - [ ] ContractClause appendix attach khi export HĐ trọn gói
 - [ ] Audit log riêng (`AuditLogs` table) ngoài `ContractApprovals`
+- [ ] MediatR `AuditBehavior` — log mọi command
+- [ ] E-signature integration (VNPT/FPT CA)