[CLAUDE] Phase3: Workflow MVP — 9-phase state machine + code gen + FE Inbox/Detail

Backend Contracts domain (5 entities):
- Contract aggregate: Phase (9 enum), SlaDeadline, MaHopDong, BypassProcurementAndCCM, DraftData, SlaWarningSent
- ContractApproval: FromPhase → ToPhase, ApproverUserId (null = system auto-approve), Decision, Comment
- ContractComment: thread theo Phase current
- ContractAttachment: FileName + StoragePath + Purpose (DraftExport/ScannedSigned/SealedCopy)
- ContractCodeSequence: Prefix PK + LastSeq — atomic gen

EF configs:
- Unique MaHopDong filtered [MaHopDong] IS NOT NULL
- Indexes: Phase+IsDeleted, SupplierId, ProjectId, SlaDeadline, ContractId+ApprovedAt, ContractId+CreatedAt
- Cascade delete Approvals/Comments/Attachments khi Contract xoa
- Query filter IsDeleted
- Migration AddContractsWorkflow (DB 19 tables)

Workflow service:
- IContractWorkflowService.TransitionAsync:
  - Adjacency check qua Transitions Dict<(from,to), roles[]> (12 transitions)
  - Role guard: user phai co role ∈ allowed
  - Admin bypass (role Admin pass moi check)
  - System bypass (userId=null + Decision=AutoApprove → cho SLA job sau nay)
  - Bypass CCM: BypassProcurementAndCCM=true cho phep DangInKy → DangTrinhKy skip phase 6
  - Gen ma HD khi chuyen DangDongDau (idempotent — khong gen lai neu da co)
  - Reset SlaDeadline = UtcNow + PhaseSla
  - Insert ContractApproval row

Code generator (RG-001):
- 7 format theo ContractType: HDTP / HDGK / NCC / HDDV / MB + 2 framework (year prefix)
- BeginTransactionAsync(Serializable) + ContractCodeSequences UPSERT → atomic
- Idempotent: neu MaHopDong da co thi skip

CQRS (8 feature, ContractFeatures.cs):
- CreateContractCommand + Validator + Handler (set SlaDeadline = +7d)
- UpdateContractDraftCommand (chi khi Phase=DangSoanThao)
- TransitionContractCommand (delegate → WorkflowService)
- AddCommentCommand (phase = hien tai)
- ListContractsQuery (PagedResult + filter phase/supplier/project/search)
- GetMyInboxQuery (map Phase → actor roles, filter theo role user)
- GetContractQuery (detail + approvals + comments + attachments + resolve user names)
- DeleteContractCommand (soft, block > DangInKy)

Controller:
- ContractsController 8 endpoint: GET list/inbox/detail, POST create/transition/comment, PUT update, DELETE

Frontend fe-admin (2 page moi):
- types/contracts.ts: ContractPhase const + Label + Color maps + types
- components/PhaseBadge.tsx
- pages/contracts/ContractsListPage.tsx: filter phase + search + click → detail
- pages/contracts/ContractDetailPage.tsx: 2-col layout (info+comments | timeline), action dialog select target phase + comment

Frontend fe-user (4 page moi + 14 file shared):
- cp 14 file shared tu fe-admin (menuKeys, types/*, DataTable, PhaseBadge, Dialog, Textarea, Select, apiError, usePermission, PermissionGuard)
- AuthContext update: load menu tu /menus/me + cache
- Layout: menu fixed 3 muc + user info + roles display
- InboxPage: list HD cho role user xu ly (sort theo SLA)
- ContractCreatePage: form chon loai + template + NCC + du an + gia tri + bypass CDT
- ContractDetailPage: duplicate fe-admin pattern (convention)
- MyContractsPage: list HD cua toi
- App.tsx: 4 route moi

E2E verified:
- Setup Supplier + Project
- POST /contracts → 201 + phase=2
- POST /contracts/{id}/transitions x7 → di het 9 phase
- Final: MaHopDong = "FLOCK 01/HĐGK/SOL&PVL2026/01" dung format RG-001
- Approvals: 7 rows audit day du

Docs:
- .claude/skills/contract-workflow/SKILL.md: placeholder → full spec voi state machine, SLA table, role matrix, 7 code format, code pointers, API, E2E workflow, pitfalls
- docs/changelog/sessions/2026-04-21-1330-phase3-workflow.md: session log
- docs/STATUS.md: Phase 3 MVP done, next Phase 4
- docs/HANDOFF.md: update phase status + file tree + commit log + testing points
- docs/changelog/migration-todos.md: tick Phase 3 MVP items + add iteration 2 list

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

src/Backend/SolutionErp.Domain/Contracts/Contract.cs

@@ -0,0 +1,28 @@
+using SolutionErp.Domain.Common;
+
+namespace SolutionErp.Domain.Contracts;
+
+// Aggregate root cho quy trình trình ký HĐ.
+// State machine xem docs/workflow-contract.md — 9 phase + 1 TuChoi.
+public class Contract : AuditableEntity
+{
+    public string? MaHopDong { get; set; }                         // Gen khi chuyển phase DangDongDau (RG-001)
+    public ContractType Type { get; set; }
+    public ContractPhase Phase { get; set; } = ContractPhase.DangSoanThao;
+    public Guid SupplierId { get; set; }
+    public Guid ProjectId { get; set; }
+    public Guid? DepartmentId { get; set; }
+    public Guid? DrafterUserId { get; set; }                       // Người soạn thảo
+    public Guid? TemplateId { get; set; }                          // Template dùng để render
+    public decimal GiaTri { get; set; }
+    public string? TenHopDong { get; set; }
+    public string? NoiDung { get; set; }
+    public bool BypassProcurementAndCCM { get; set; }              // HĐ Chủ đầu tư → skip CCM
+    public DateTime? SlaDeadline { get; set; }                     // Hết hạn phase hiện tại
+    public string? DraftData { get; set; }                         // JSON field values (render template)
+    public bool SlaWarningSent { get; set; }                       // Flag để không gửi warning 2 lần
+
+    public List<ContractApproval> Approvals { get; set; } = new();
+    public List<ContractComment> Comments { get; set; } = new();
+    public List<ContractAttachment> Attachments { get; set; } = new();
+}

src/Backend/SolutionErp.Domain/Contracts/ContractApproval.cs

@@ -0,0 +1,18 @@
+using SolutionErp.Domain.Common;
+
+namespace SolutionErp.Domain.Contracts;
+
+// Lịch sử phê duyệt: mỗi lần chuyển phase tạo 1 row.
+// ApproverUserId = null nếu là auto-approve do SLA expired.
+public class ContractApproval : BaseEntity
+{
+    public Guid ContractId { get; set; }
+    public ContractPhase FromPhase { get; set; }
+    public ContractPhase ToPhase { get; set; }
+    public Guid? ApproverUserId { get; set; }
+    public ApprovalDecision Decision { get; set; }
+    public string? Comment { get; set; }
+    public DateTime ApprovedAt { get; set; }
+
+    public Contract? Contract { get; set; }
+}

src/Backend/SolutionErp.Domain/Contracts/ContractAttachment.cs

@@ -0,0 +1,24 @@
+using SolutionErp.Domain.Common;
+
+namespace SolutionErp.Domain.Contracts;
+
+public enum AttachmentPurpose
+{
+    DraftExport = 1,     // File render từ template (.docx/.xlsx) ở phase DangSoanThao
+    ScannedSigned = 2,   // Scan HĐ có chữ ký NCC ở phase DangInKy
+    SealedCopy = 3,      // Scan HĐ đã đóng dấu ở phase DangDongDau
+    Other = 99,
+}
+
+public class ContractAttachment : BaseEntity
+{
+    public Guid ContractId { get; set; }
+    public string FileName { get; set; } = string.Empty;
+    public string StoragePath { get; set; } = string.Empty;  // relative path under wwwroot/uploads/
+    public long FileSize { get; set; }
+    public string ContentType { get; set; } = string.Empty;
+    public AttachmentPurpose Purpose { get; set; }
+    public string? Note { get; set; }
+
+    public Contract? Contract { get; set; }
+}

src/Backend/SolutionErp.Domain/Contracts/ContractCodeSequence.cs

@@ -0,0 +1,11 @@
+namespace SolutionErp.Domain.Contracts;
+
+// Sequence generator cho mã HĐ theo RG-001.
+// Prefix = phần đầu mã (vd "FLOCK 01/HĐGK/SOL&PVL"). LastSeq tăng dần.
+// Update atomic qua transaction SERIALIZABLE.
+public class ContractCodeSequence
+{
+    public string Prefix { get; set; } = string.Empty;
+    public int LastSeq { get; set; }
+    public DateTime UpdatedAt { get; set; }
+}

src/Backend/SolutionErp.Domain/Contracts/ContractComment.cs

@@ -0,0 +1,14 @@
+using SolutionErp.Domain.Common;
+
+namespace SolutionErp.Domain.Contracts;
+
+// Thread góp ý — dùng chủ yếu ở phase DangGopY nhưng có thể ở bất kỳ phase nào.
+public class ContractComment : BaseEntity
+{
+    public Guid ContractId { get; set; }
+    public Guid UserId { get; set; }
+    public ContractPhase Phase { get; set; }
+    public string Content { get; set; } = string.Empty;
+
+    public Contract? Contract { get; set; }
+}