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. Dùng khi debug chuyển phase, 403 forbidden, code sai format, bypass Chủ đầu tư.
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ư"
---

# Contract Workflow Skill

> **Status:** Phase 3 IMPLEMENTED (MVP — state transitions + code gen). Còn thiếu: SLA hosted service, email notify, in-app realtime.

## Domain entities (implemented)

```
Contract ─────< ContractApproval (lịch sử mỗi transition)
         ─────< ContractComment (thread góp ý)
         ─────< ContractAttachment (scan signed/sealed)

ContractCodeSequence (Prefix PK, LastSeq) — gen mã HĐ atomic
```

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

## SLA mặc định (sau transition, set `Contract.SlaDeadline = UtcNow + sla`)

| Phase | SLA |
|---|---|
| DangSoanThao | 7d |
| DangGopY | 7d |
| DangDamPhan | 7d |
| DangInKy | 1d |
| DangKiemTraCCM | 3d |
| DangTrinhKy | 1d |
| DangDongDau | none |
| DaPhatHanh | none |

## Role × Phase guard matrix

Xem `ContractWorkflowService.Transitions` dictionary. 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.

## 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 UPDATE. 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

**Backend:**
- `Domain/Contracts/Contract.cs` — aggregate root
- `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

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

## API endpoints

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/contracts` | List với filter phase/supplier/project + paging |
| 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) |
| 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 |
| DELETE | `/api/contracts/{id}` | Soft delete (chỉ < DangInKy) |

## 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 đó
- **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
- **Self-delete:** không cho xóa HĐ đã qua `DangInKy`

## Workflow tạo HĐ end-to-end (testable)

```bash
# 1. Setup master data
POST /api/suppliers  { code: "PVL", name: "...", type: 1 }
POST /api/projects   { code: "FLOCK 01", name: "..." }

# 2. Tạo HĐ
POST /api/contracts  { type: 2, supplierId, projectId, giaTri: 150000000, tenHopDong: "..." }
# → Phase = DangSoanThao, SlaDeadline = +7d

# 3. Submit góp ý
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. BOD ký → gen mã HĐ
→ 8 DangDongDau
  # contract.MaHopDong = "FLOCK 01/HĐGK/SOL&PVL/01"

# 6. 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** → map `NEXT_PHASES` ở FE phải match BE `Transitions`. Nếu BE đổi, FE quên update → user click → 403.

## Phase 3 iteration 2 (còn thiếu)

- [ ] `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)
- [ ] ContractClause appendix attach khi export HĐ trọn gói
- [ ] Audit log riêng (`AuditLogs` table) ngoài `ContractApprovals`