solution-erp/docs/changelog/sessions/2026-04-21-1330-phase3-workflow.md

Session 2026-04-21 13:30 — Phase 3 Workflow MVP

Dev: Claude (Opus 4.7) Duration: ~1h15m Base commit: 5113e4c

Làm được

Chunk G — Domain + EF + Migration

• Domain/Contracts: Contract (aggregate, 15 fields) + ContractApproval (history) + ContractComment (thread) + ContractAttachment (files với AttachmentPurpose enum) + ContractCodeSequence (Prefix PK + LastSeq)
• EF configs với:
  • Unique MaHopDong filtered WHERE [MaHopDong] IS NOT NULL
  • Indexes: (Phase, IsDeleted), SupplierId, ProjectId, SlaDeadline
  • Cascade delete cho Approvals/Comments/Attachments khi Contract xóa
  • Query filter IsDeleted
• DbSets + IApplicationDbContext update (5 DbSet mới)
• Migration AddContractsWorkflow

Chunk H — Workflow service + CodeGenerator + CQRS + Controller

Services:

• IContractWorkflowService.TransitionAsync(contract, targetPhase, userId, roles, decision, comment):
  • Adjacency check qua Transitions Dictionary<(from,to), roles[]>
  • Role check (Admin bypass)
  • System actor bypass (cho SLA job Phase 3.2)
  • Bypass rule Chủ đầu tư (DangInKy → DangTrinhKy skip CCM)
  • Gen mã HĐ khi DangDongDau (nếu chưa có)
  • Reset SlaDeadline theo target phase SLA
  • Insert ContractApproval row
• IContractCodeGenerator.GenerateAsync():
  • 7 format theo ContractType (HĐTP/HĐGK/NCC/HĐDV/MB + 2 framework)
  • BeginTransactionAsync(IsolationLevel.Serializable) + ContractCodeSequences UPSERT → atomic
• Register scoped trong Infrastructure DI

CQRS (ContractFeatures.cs):

• CreateContractCommand + Validator + Handler (tạo draft, SlaDeadline = UtcNow + 7d)
• UpdateContractDraftCommand (chỉ khi Phase = DangSoanThao)
• TransitionContractCommand (delegate → WorkflowService)
• AddCommentCommand (phase = hiện tại)
• ListContractsQuery (PagedResult với filter phase/supplier/project + search)
• GetMyInboxQuery (map Phase → roles, return HĐ phù hợp role user)
• GetContractQuery (detail + approvals + comments + attachments, resolve user names)
• DeleteContractCommand (soft, block > DangInKy)

Controller:

• ContractsController với 8 endpoint: GET list/inbox/detail, POST create/transition/comment, PUT update, DELETE
• Body DTOs inline: TransitionContractBody, AddCommentBody

Chunk I — Frontend 2 app

fe-admin (2 page mới):

• types/contracts.ts — ContractPhase/Decision const-object + Label + Color maps + types
• components/PhaseBadge.tsx — badge màu theo phase
• pages/contracts/ContractsListPage.tsx — DataTable full filter + click row → detail
• pages/contracts/ContractDetailPage.tsx — 2-col layout: info + comments + timeline + action dialog (approve/reject với select target phase + comment)

fe-user (4 page mới + port shared):

• Copy 14 file shared từ fe-admin (menuKeys, types/*, DataTable, PhaseBadge, Dialog, Textarea, Select, apiError, usePermission, PermissionGuard)
• contexts/AuthContext.tsx update — load menu from /menus/me + localStorage cache
• components/Layout.tsx — menu fixed 3 mục (Inbox / Tạo mới / HĐ của tôi) + user info + role display
• pages/InboxPage.tsx — list /api/contracts/inbox (HĐ chờ role của tôi xử lý, sort theo SLA)
• pages/contracts/ContractCreatePage.tsx — form chọn loại HĐ + template + NCC + dự án + giá trị + bypass CĐT
• pages/contracts/ContractDetailPage.tsx — duplicate fe-admin pattern (convention)
• pages/contracts/MyContractsPage.tsx — HĐ của tôi
• App.tsx — 4 route mới

E2E verified

# Setup
POST /api/suppliers { code: "PVL2026", type: 1 }   → 201
POST /api/projects { code: "FLOCK 01" }             → 201

# Tạo HĐ
POST /api/contracts { type: 2, supplierId, projectId, giaTri: 150000000 }
  → 201 contractId e20083d5
  → phase=2 (DangSoanThao), slaDeadline=+7d

# Inbox
GET /api/contracts/inbox  → 1 contract

# Full workflow 9 phase (admin bypass)
POST /transitions {targetPhase: 3}  → 204
POST /transitions {targetPhase: 4}  → 204
POST /transitions {targetPhase: 5}  → 204
POST /transitions {targetPhase: 6}  → 204
POST /transitions {targetPhase: 7}  → 204
POST /transitions {targetPhase: 8}  → 204  ← GEN MÃ HĐ
POST /transitions {targetPhase: 9}  → 204

# Final
GET /api/contracts/{id}
  → phase: 9 (DaPhatHanh)
  → maHopDong: "FLOCK 01/HĐGK/SOL&PVL2026/01"  ✅ ĐÚNG FORMAT RG-001
  → 7 approvals với đủ from/to/decision/comment

TS check fe-admin + fe-user pass.

Bug gặp + fix

Bug	Fix
Edit tool "File not read" sau system-reminder	Re-read file rồi Write full
Python f-string backslash trong curl test script	Bỏ escape trong f-string

Docs updates

• .claude/skills/contract-workflow/SKILL.md — full spec từ placeholder: state machine, role matrix, SLA, RG-001 format 7 loại, code pointers, API, workflow E2E, pitfalls
• Session log này (session #4 trong changelog/sessions)

Handoff cho session tiếp theo

Phase 3 iteration 2 (optional — polish)

• SlaExpiryJob BackgroundService (hosted service, 15min interval, auto-approve quá hạn với Decision=AutoApprove) — spec ở docs/flows/sla-expiry-flow.md
• Email notification (MailKit) khi chuyển phase
• In-app notification (SignalR + badge counter)
• Upload attachment endpoint + FE (multipart, store vào wwwroot/uploads/contracts/{id}/)
• RowVersion optimistic concurrency (2 user cùng duyệt → 409)
• Render HĐ ra .docx lúc tạo (link với TemplateId + DraftData + merge ContractClause appendix)
• E2E test permission matrix: tạo user role Drafter thật → verify chỉ thấy nút approve khi ở đúng phase

Phase 4 — Report + Polish

Xem docs/changelog/migration-todos.md section Phase 4.

Quick wins

• FE Users management (tạo user, gán role) — để test workflow với multi-user
• Filter Inbox theo phase (dropdown FE)
• Export HĐ list ra Excel

Blocker

• ⏳ Gitea remote URL (vẫn chờ)

Thông số cumulative

	Sau Phase 2	Sau Phase 3 MVP
BE LOC	~1900	~2700
DB tables	14	19 (+Contracts, ContractApprovals, Comments, Attachments, CodeSequences)
API endpoints	~23	~31 (+8 contract)
Migrations	4	5
FE pages	7 (fe-admin) + 2 (fe-user)	9 + 5
Commits	5	6 (sắp)