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

---
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, 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"
  - "HĐ quá hạn auto-approve"
  - "role không duyệt được"
  - "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:** Tier 3 FEATURE-COMPLETE — State transitions + code gen + SLA job + attachment + realtime notify + versioned workflow admin-configurable. Còn thiếu: email outbox (SMTP), warning 20% SLA.
>
> **Phase 6 cross-ref (2026-04-23):** Module `PurchaseEvaluation` (tiền-HĐ) có
> **workflow SEPARATE** — `PurchaseEvaluationPolicy` + registry +
> `FromDefinition` mirror pattern này nhưng tách table riêng (3 bảng
> `PurchaseEvaluationWorkflow*`) vì Phase enum khác. Xem:
> - `Domain/PurchaseEvaluations/PurchaseEvaluationPolicy.cs`
> - `Infrastructure/Services/PurchaseEvaluationWorkflowService.cs`
> - Kế thừa HĐ từ phiếu `DaDuyet` qua `CreateContractFromEvaluationCommand` — pin `Contract.WorkflowDefinitionId` theo ContractType user chọn.
>
> **Phase 9 cross-ref (Migration 16 — Session 8/9):** 3 mở rộng cross-cut 3 module
> (Contract + PurchaseEvaluation + Budget):
> - **2-stage dept approval** (đóng bug anh Kiệt FDC): NV Review → TPB Confirm.
>   `*DepartmentApprovals` table UNIQUE (TargetId, Phase, Dept, Stage). Service
>   inject UserManager → check role DeptManager / CanBypassReview → upsert row +
>   block transition cho đến khi Stage=Confirm. **6 test PE 2-stage** ở
>   `tests/.../Services/PeTwoStageApprovalTests.cs` (`IdentityFixture` reusable).
> - **Smart reject + Resume jump-back**: `Reject` → set `RejectedFromPhase` snapshot
>   + force `targetPhase=DangSoanThao`. `Resume` (Drafter trình lại từ DangSoanThao
>   với RejectedFromPhase != null) → jump straight tới phase đã reject, bypass
>   policy guard. Áp dụng 3 module.
> - **Lock edit guards** 17 handler: Phase != DangSoanThao → throw 409 ConflictException.
>   KHÔNG lock Comment + Attachment + Opinion (workflow design intent).

## Domain entities (implemented)

```
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

```
DangChon(1) → DangSoanThao(2) → DangGopY(3) → DangDamPhan(4) → DangInKy(5) →
  DangKiemTraCCM(6) → DangTrinhKy(7) → DangDongDau(8) → DaPhatHanh(9)

Alternates:
  DangSoanThao → TuChoi(99)
  DangGopY → DangSoanThao (revise)
  DangKiemTraCCM → DangSoanThao (CCM reject)
  DangTrinhKy → DangSoanThao (BOD reject)

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
```

## Versioned workflow (Tier 3) — policy resolution runtime

```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 |
| DangDamPhan | 7d |
| DangInKy | 1d |
| DangKiemTraCCM | 3d |
| DangTrinhKy | 1d |
| DangDongDau | none |
| DaPhatHanh | none |

Nếu pinned WorkflowStep có `SlaDays > 0` → ưu tiên value của step đó.

## Role × Phase guard matrix (hardcoded Standard)

Xem `WorkflowPolicies.Standard.Transitions`. Tóm tắt:

| Phase hiện tại → target | Roles được phép |
|---|---|
| DangSoanThao → DangGopY | Drafter, DeptManager |
| DangSoanThao → TuChoi | Drafter, DeptManager |
| DangGopY → DangDamPhan | Drafter, DeptManager |
| DangGopY → DangSoanThao | ProjectManager, Procurement, CostControl, Finance, Accounting, Equipment |
| DangDamPhan → DangInKy | Drafter, DeptManager, ProjectManager |
| DangInKy → DangKiemTraCCM | Drafter, DeptManager, ProjectManager |
| DangInKy → DangTrinhKy (bypass) | Drafter, DeptManager, ProjectManager (chỉ khi `BypassProcurementAndCCM=true`) |
| DangKiemTraCCM → DangTrinhKy | CostControl |
| DangKiemTraCCM → DangSoanThao | CostControl |
| DangTrinhKy → DangDongDau | Director, AuthorizedSigner |
| DangTrinhKy → DangSoanThao | Director, AuthorizedSigner |
| DangDongDau → DaPhatHanh | HrAdmin |

**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Đ:

| Type | Format |
|---|---|
| HopDongThauPhu | `{ProjectCode}/HĐTP/SOL&{SupplierCode}/{Seq:D2}` |
| HopDongGiaoKhoan | `{ProjectCode}/HĐGK/SOL&{SupplierCode}/{Seq:D2}` |
| HopDongNhaCungCap | `{ProjectCode}/NCC/SOL&{SupplierCode}/{Seq:D2}` |
| HopDongDichVu | `{ProjectCode}/HĐDV/SOL&{SupplierCode}/{Seq:D2}` |
| HopDongMuaBan | `{ProjectCode}/MB/SOL&{SupplierCode}/{Seq:D2}` |
| HopDongNguyenTacNCC | `{Year}/NCC/SOL&{SupplierCode}/{Seq:D2}` ← framework |
| HopDongNguyenTacDichVu | `{Year}/HĐDV/SOL&{SupplierCode}/{Seq:D2}` ← framework |

**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 (Tier 3 updated)

**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
- `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

**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/type + paging + pendingMe |
| GET | `/api/contracts/inbox` | HĐ chờ role của user xử lý |
| 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 `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)
- **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, Tier 3)

```bash
# 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

# 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

# 4. Transition — guard load từ v02.Steps.Approvers
POST /api/contracts/{id}/transitions { targetPhase: 3, decision: 1, comment: "..." }

# 5. Chuyển qua các phase
→ 4 DangDamPhan → 5 DangInKy → (skip CCM nếu SkipCcm policy) → 7 DangTrinhKy

# 6. BOD ký → gen mã HĐ
→ 8 DangDongDau
  # contract.MaHopDong = "FLOCK 01/MB/SOL&PVL/01"

# 7. HRA đóng dấu + phát hành
→ 9 DaPhatHanh
```

## Common pitfalls (xem gotchas.md)

- **Admin check mọi phase** → đôi khi không catch role-scope bug. Test với user không phải Admin.
- **Mã HĐ gen 2 lần** (sau reject rồi approve) → generator check `if (MaHopDong is null)` trước khi gen.
- **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** → 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 9 done (Mig 16 — Session 8/9)

- [x] **2-stage dept approval** xuyên 3 module — NV Review BLOCK / TPB Confirm ALLOW
- [x] **Smart reject + Resume jump-back** — RejectedFromPhase snapshot + bypass policy
- [x] **Lock edit guards** 17 handler khi Phase != DangSoanThao
- [x] **CanBypassReview toggle** per User — admin UI + audit IsBypassed=true

## Phase 9+ done (Mig 18-20 — Session 12/13/14)

### N-stage workflow (PE Mig 18-19 + Contract Mig 20)

- [x] **N-stage approval** Phòng × PositionLevel (NV/PP/TP) cấu hình động per
      WorkflowStep cha. Mỗi inner step = 1 cấp duyệt (Order asc, sequential).
- [x] **PositionLevel enum** Domain/Identity (NV=1, PP=2, TP=3) + `User.PositionLevel int?`
- [x] **InnerStep entity** + ALTER `*DepartmentApproval.InnerStepId Guid?` per module
- [x] **Filtered unique split** (Mig 19 cho PE / gộp Mig 20 cho Contract):
      legacy `WHERE InnerStepId IS NULL` (Stage Review/Confirm) + N-stage
      `WHERE InnerStepId IS NOT NULL` (per inner step)
- [x] **Service refactor** TransitionAsync — load InnerSteps eager + reject
      branch clear N-stage rows + dept approval block split: hasInnerSteps→N-stage
      logic / else→legacy 2-stage. Match firstPending Order asc + (exact level
      OR canBypass + level≥). Bypass batch upsert NV+PP+TP cùng dept ≤ actor.
- [x] **6 test PE N-stage** + **6 test Contract N-stage** (`PeNStageApprovalTests`,
      `ContractNStageApprovalTests`). Pattern reusable.
- [x] **FE Designer** (PeWorkflowsPage + WorkflowsPage) sub-section "Cấp duyệt nhỏ
      trong phòng" drag-list { Phòng × Cấp + required }
- [x] **UsersPage cột Cấp** + cycle button null→1→2→3→null
- [x] **API** `PATCH /users/{id}/position-level`

**Backward compat 100%:** workflow no InnerSteps → service fallback legacy 2-stage
Mig 16. Data legacy InnerStepId=null vẫn enforce unique cũ qua filtered index.

### PE 3-button approval (Session 14 — `0d77698`)

UI distinguishment 3 hành động cho approver:
- **Duyệt** = forward (decision=Approve)
- **Trả lại** = về DangSoanThao + Drafter sửa (decision=Reject + target=DangSoanThao
  → smart reject pattern Mig 16 + clear N-stage rows + jump-back)
- **Từ chối** = Phase=TuChoi (decision=Reject + target=TuChoi → phiếu khoá
  vĩnh viễn 17 handler Mig 16 lock edit, Drafter phải tạo phiếu mới)

**Domain policy expand:** NccOnly + NccWithPlan + FromDefinition thêm `(X → TuChoi)`
transition cho mọi phase trung gian (trước chỉ DangSoanThao→TuChoi).

**Service Reject branch tách 2 case:**
- target=TuChoi → giữ nguyên (KHÔNG override + KHÔNG set RejectedFromPhase + KHÔNG clear N-stage)
- target khác (DangSoanThao) → smart reject (force DangSoanThao + RejectedFromPhase + clear N-stage)

### Defer

- Budget N-stage — cần migration `AddBudgetVersionedWorkflow` trước (Budget
  hardcoded `BudgetPolicy.Default`, chưa có versioned WorkflowDefinition).
- Phase TraLai = 98 (Domain enum từ S11+++++++) — orphan, KHÔNG wire (user
  Session 14 chốt không cần phase trung gian).

## Tier 4+ (còn thiếu / future)

- [ ] 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)