solution-erp/docs/HANDOFF.md

HANDOFF — Brief 5 phút cho session tiếp theo

Last updated: 2026-04-21 12:00 (cuối Phase 2 MVP)

Ở đâu rồi?

Phase	Trạng thái
0 Draft	✅ Done
1 Alpha Core foundation	✅ Done
1 Alpha Core đợt 2 (CRUD + Permission)	✅ Done
2 Form Engine MVP	✅ Done
2 Form Engine iteration 2	📝 Optional
3 Workflow (9 phase state machine)	📋 Next
4 Report + Polish	📋 Queue
5 Production (CI/CD IIS)	📋 Queue

Run nhanh

# Terminal 1 — API (auto seed 8 template lần đầu)
dotnet run --project src\Backend\SolutionErp.Api

# Terminal 2 — Admin FE
cd fe-admin && npm run dev  # → http://localhost:8082

# Terminal 3 — User FE
cd fe-user && npm run dev   # → http://localhost:8080

Login: admin@solutionerp.local / Admin@123456

Điểm cần test ngay:

• /forms → render FO-002.05 → download .docx (Phase 2 MVP)
• /system/permissions → chọn role → tick matrix
• /master/suppliers|projects|departments → CRUD

Cần làm kế tiếp (ưu tiên)

A. Phase 3 — Workflow (item lớn, ~3 tuần work)

Đọc trước:

1. workflow-contract.md — spec 9 phase + role matrix
2. flows/contract-approval-flow.md — sequence diagram
3. flows/sla-expiry-flow.md — BackgroundService auto-approve
4. forms-spec.md#RG-001 — format mã HĐ

Deliverable chính:

• Entity: Contract (Phase, SlaDeadline, BypassProcurementAndCCM, DraftData) + ContractApproval + ContractComment + ContractAttachment
• IContractWorkflowService.TransitionAsync() — state guard (9 phase adjacency) + role guard
• IContractCodeGenerator (implement RG-001) với transaction SERIALIZABLE + ContractCodeSequences table
• SlaExpiryJob BackgroundService — auto-approve HĐ quá hạn mỗi 15 phút
• INotificationService — email (MailKit) + in-app
• API POST /api/contracts/{id}/transitions
• FE /inbox (list HĐ chờ tôi xử lý theo role × phase)
• FE /contracts/{id} detail — timeline 9 phase, approval panel, comment thread, attachment upload

B. Phase 2 iteration 2 (nếu user muốn polish Form Engine)

• Convert 3 file .doc (retry Word COM với timeout OR LibreOffice)
• Field spec JSON → dynamic form builder
• {{#loop}}...{{/loop}} support
• PDF convert
• FE upload template UI

C. Quick wins (không block phase)

• FE Users management + Roles CRUD (test permission với non-admin role)
• fe-user sync menu động (đang hardcode)

Lưu ý kỹ thuật quan trọng

Đọc gotchas.md trước khi:

• Thêm package mới → check compat với .NET 10 (MediatR 14 fail → dùng 12)
• Debug 404 API → kiểm Program.cs có persist không (Dropbox issue)
• Expression tree error → tách switch ra ngoài LINQ
• TS enum error → dùng const-object pattern (erasableSyntaxOnly)
• Word COM stuck → kill + fallback LibreOffice
• Migration lỗi → check 3 file đầy đủ (Designer + Migration + Snapshot)

File đang active

SOLUTION_ERP/
├── src/Backend/              (Clean Arch, 4 project, .NET 10)
│   ├── SolutionErp.Domain/
│   │   ├── Common/           BaseEntity, AuditableEntity
│   │   ├── Contracts/        ContractType, ContractPhase, ApprovalDecision
│   │   ├── Forms/            ContractTemplate, ContractClause  ← Phase 2
│   │   ├── Identity/         User, Role, MenuItem, Permission, AppRoles, MenuKeys
│   │   └── Master/           Supplier, Project, Department, SupplierType
│   ├── SolutionErp.Application/
│   │   ├── Auth/             Login, Refresh, Me
│   │   ├── Common/           Exceptions, Behaviors, Interfaces, Models
│   │   ├── Forms/            FormFeatures (List/Get/Render)  ← Phase 2
│   │   ├── Master/           Suppliers, Projects, Departments CQRS
│   │   └── Permissions/      GetMyMenuTree, matrix upsert
│   ├── SolutionErp.Infrastructure/
│   │   ├── Forms/            DocxRenderer, XlsxRenderer, FormRenderer  ← Phase 2
│   │   ├── Identity/         JwtSettings, JwtTokenService
│   │   ├── Persistence/      DbContext, DbInitializer, Interceptors, Migrations (4)
│   │   └── Services/         DateTimeService
│   └── SolutionErp.Api/
│       ├── Authorization/    MenuPermissionHandler + Requirement
│       ├── Controllers/      Auth, Suppliers, Projects, Departments, Menus, Roles, Permissions, Forms
│       ├── Middleware/       GlobalExceptionMiddleware
│       ├── Services/         CurrentUserService, WebHostEnvironmentLocator
│       └── wwwroot/templates/ 5 file .docx/.xlsx  ← Phase 2
├── fe-admin/                  (7 page)
│   └── src/pages/
│       ├── LoginPage
│       ├── DashboardPage
│       ├── master/SuppliersPage, ProjectsPage, DepartmentsPage
│       ├── system/PermissionsPage
│       └── forms/FormsPage  ← Phase 2
├── fe-user/                   (2 page — Login + Inbox placeholder)
├── docs/                      (24 file — STATUS, PROJECT-MAP, workflow, forms-spec, database-guide, 6 flow, gotchas, 4 session log, 1 handoff)
└── .claude/skills/            (3 skill — contract-workflow placeholder, form-engine + permission-matrix full spec)

Git state

49a5f57..(sẽ là commit 5) — Phase 2 MVP
54d6c9b — Phase 1.2 CRUD + Permission
49a5f57 — Docs database-guide + flows
702411f — Phase 1 foundation
25dad7f — Phase 0 scaffold

Branch: main
Remote: chưa (Gitea URL chờ user)

Credentials + URLs

admin@solutionerp.local / Admin@123456

• API: http://localhost:5443 (swagger /swagger)
• Admin FE: http://localhost:8082
• User FE: http://localhost:8080
• SQL LocalDB: (localdb)\MSSQLLocalDB / Database=SolutionErp_Dev

Đánh giá nhanh

Tốt:

• Build pass 100% cả BE + FE
• E2E test: login + CRUD + render template đều pass
• Docs đầy đủ: 24 file, có session log mỗi chunk, gotchas library tích lũy

Rủi ro:

• fe-user còn thô — Phase 3 phải build inbox
• Form render chỉ MVP — loop table + PDF chưa có
• Permission matrix chưa test thực với non-admin user