solution-erp/docs/changelog/sessions/2026-04-28-chot-session-4-budget.md

Session log — 2026-04-28 (Phase 7 — Module Ngân sách BE + 14 Solutions users)

Topic: Module Ngân sách (Budget) BE chốt + 14 demo user Solutions thật + chốt MD session 4 → 5

Commits:

• 309dcd9 · e71e0eb · e65578a — Docs cleanup từ session 3 (audit MD + tái cấu trúc + archive raw)
• 8097892 — Infra: 14 demo user Solutions company (PRO 5 + CCM 7 + ISO 1 + CEO 1)
• a05c57b — Domain+App+Api: Module Ngân sách (Budget) — 4 bảng + workflow simple 3-step
• (Session log + chốt MD này — commit cuối session 4)

Migration: 14 AddBudgets — 4 bảng Budgets / BudgetDetails / BudgetApprovals / BudgetChangelogs + 2 cột nullable FK Contracts.BudgetId & PurchaseEvaluations.BudgetId.

A. Module Ngân sách BE

Domain (SolutionErp.Domain/Budgets/)

• BudgetPhase enum 5-state — DangSoanThao(1) → ChoCCM(2) → ChoCEO(3) → DaDuyet(4) + TuChoi(99)
• Budget aggregate root (AuditableEntity):
  • MaNganSach NS-{YYYYMM}-{Random:4d} (chưa atomic), TenNganSach required, Description
  • NamNganSach int (year), ProjectId FK Restrict, DepartmentId? FK Restrict, DrafterUserId FK Restrict
  • Phase enum, TongNganSach decimal(18,2) auto-recompute, SlaDeadline?, SlaWarningSent
  • Navigation: Details / Approvals / Changelogs collections
• BudgetDetail flat row pattern — KHÔNG nested per-type:
  • GroupCode/GroupName (phân nhóm hạng mục), ItemCode, NoiDung, DonViTinh
  • KhoiLuong dec(18,4), DonGia dec(18,2), ThanhTien dec(18,2), Order, GhiChu
• BudgetApproval workflow history (FromPhase/ToPhase/Decision reuse ApprovalDecision)
• BudgetChangelog audit log với enum BudgetEntityType (Header/Detail/Workflow)
• BudgetPolicy record + BudgetPolicy.Default hardcoded simple 3-step:
  • Drafter/DeptManager: DangSoanThao → ChoCCM (Trình) hoặc TuChoi
  • CostControl: ChoCCM → ChoCEO hoặc DangSoanThao (trả về)
  • Director/AuthorizedSigner: ChoCEO → DaDuyet hoặc DangSoanThao

Modify Contract & PE

• Contract.BudgetId? Guid + index
• PurchaseEvaluation.BudgetId? Guid + index
• Không có FK constraint cứng — app layer guard validate khi pick Budget

Application (SolutionErp.Application/Budgets/)

BudgetFeatures.cs ~340 LOC, 11 CQRS handler:

1. CreateBudgetCommand + Validator + Handler — gen MaNganSach, set Phase=DangSoanThao, log Changelog
2. UpdateBudgetDraftCommand — chỉ DangSoanThao, log field changes JSON
3. TransitionBudgetCommand — guard BudgetPolicy.Default.IsTransitionAllowed, append BudgetApproval, log Changelog Transition
4. ListBudgetsQuery — Page/Search/Filter Phase/ProjectId/NamNganSach
5. GetBudgetQuery — return BudgetDetailBundleDto (Header + Details + Approvals + Workflow summary)
6. DeleteBudgetCommand — chỉ DangSoanThao/TuChoi (soft delete)
7. AddBudgetDetailCommand — auto recompute Sum(ThanhTien) lại Header
8. UpdateBudgetDetailCommand — auto recompute
9. DeleteBudgetDetailCommand — auto recompute
10. ListBudgetChangelogsQuery — order CreatedAt DESC

Api (SolutionErp.Api/Controllers/)

BudgetsController.cs 11 endpoint REST:

GET    /api/budgets                             list paged
GET    /api/budgets/{id}                        bundle
POST   /api/budgets                             create
PUT    /api/budgets/{id}                        update draft
POST   /api/budgets/{id}/transitions            phase transition
DELETE /api/budgets/{id}                        soft delete
POST   /api/budgets/{id}/details                add detail
PUT    /api/budgets/{id}/details/{detailId}     update detail
DELETE /api/budgets/{id}/details/{detailId}     delete detail
GET    /api/budgets/{id}/changelogs             audit log

Menu seed (DbInitializer)

• Root Budgets (MenuKeys.Budgets) order=27 icon Wallet
• 3 leaf:
  • Bg_List "Danh sách ngân sách" → /budgets
  • Bg_Create "Tạo ngân sách" → /budgets/new
  • Bg_Pending "Ngân sách chờ duyệt" → /budgets?phase=Pending
• FE chưa wire route + menu resolver — Priority 0 session 5

B. 14 demo user Solutions company thật

SeedDemoUsersAsync thêm 14 user với reconcile pattern (per-user try-catch, gotcha #38 4-field Email/NormalizedEmail/UserName/NormalizedUserName).

PRO (Phòng Cung ứng) 5 user

Email	Họ tên	Vai trò
tra.bui@solutions.com.vn	Bùi Lê Thủy Trà	TPB.PRO
phuong.nguyen@solutions.com.vn	Nguyễn Thị Bích Phượng	NV.PRO
binh.lethanh@solutions.com.vn	Lê Thanh Bình	NV.PRO
danh.huynh@solutions.com.vn	Huỳnh Tài Danh	NV.PRO
dat.tran@solutions.com.vn	Trần Văn Đạt	NV.PRO

CCM (Phòng Kiểm soát chi phí) 7 user

Email	Họ tên	Vai trò
ngocanh.huynh@solutions.com.vn	Huỳnh Thị Ngọc Ánh	TPB.CCM
ha.dao@solutions.com.vn	Đào Đức Hà	NV.CCM
cuong.do@solutions.com.vn	Đỗ Mạnh Cường	NV.CCM
long.le@solutions.com.vn	Lê Phụng Long	NV.CCM
ha.nguyen@solutions.com.vn	Nguyễn Thị Thu Hà	NV.CCM
dung.nguyen@solutions.com.vn	Nguyễn Phúc Dũng	NV.CCM
anh.nguyen@solutions.com.vn	Nguyễn Phước Tuấn Anh	NV.CCM

ISO 1 user

Email	Họ tên	Vai trò
chau.le@solutions.com.vn	Lê Bảo Châu	NV.ISO

CEO 1 user

Email	Họ tên	Vai trò
huy.duong@solutions.com.vn	Dương Quang Huy	BOD

Pwd toàn bộ: User@123456. Tổng demo user = 30 (16 sample @solutionerp.local cũ + 14 Solutions thật @solutions.com.vn).

C. Docs cleanup từ session 3

3 commit dọn MD trước:

• e65578a — chốt session 3 PE polish iter 2 + domain rebrand + 5 gotcha mới (#34-38)
• e71e0eb — tái cấu trúc cleanup: archive raw dump, compact migration-todos, update CLAUDE+flows
• 309dcd9 — chốt final session 3 audit MD + session log + minor fixes

D. Chốt MD session 4 → 5

Updated:

• docs/STATUS.md — header + Recently Done 3 row mới (Budget BE / 14 users / Docs cleanup), cumulative table thêm cột "+Budget+30 users"
• docs/HANDOFF.md — TL;DR session 4 (2 milestone Budget BE + 14 users) + Cảnh báo session 5 + Priority 0 (FE Budget + PE/HD integration + PE feature gap) + Credentials 30 user
• docs/changelog/migration-todos.md — Phase 7 thêm section D Budget done, Phase 8 mới (FE Budget pages + integration), pending migrations Budget
• docs/architecture.md — §10 Budget module mới (sơ đồ ERD + state machine + auto-recompute + integration roadmap), renumber §11 Liên quan
• docs/database/schema-diagram.md — Migration history rows 13+14, §12 Budget ERD chi tiết (4 bảng + state machine + auto-recompute + pending refinement), §13 Liên quan
• .claude/skills/ef-core-migration/SKILL.md — Migration 14 entry, total 51 bảng, Phase 8 pending Budget refinement
• CLAUDE.md (root + docs/) — modules table thêm Budget row, scope Budget, count 51 bảng / 14 migration
• ~/.claude/projects/.../memory/project_solution_erp.md — Phase 7 Budget BE + 14 user + tổng số mới + Session 5 priority

E. Session 5 carry-over

Priority 0 — FE Budget pages

Copy pattern PE:

• fe-admin/src/types/budget.ts
• fe-admin/src/pages/budgets/BudgetsListPage.tsx (3-panel)
• fe-admin/src/pages/budgets/BudgetCreatePage.tsx
• fe-admin/src/components/budgets/BudgetDetailTabs.tsx
• fe-admin/src/components/budgets/BudgetWorkflowPanel.tsx
• Mirror sang fe-user
• Routes /budgets, /budgets/new, /budgets/:id
• Menu resolver Bg_*

Priority 1 — PE/Contract → Budget integration

• PE form thêm field Ngân sách select Budget (filter Phase=DaDuyet && NamNganSach=current && ProjectId match)
• Contract form tương tự
• PE Detail tab thêm cột "So với ngân sách" (compute từ BudgetDetail tương ứng)

Priority 2 — PE feature gap

• PE Workflow admin designer UI /system/pe-workflows/:typeCode
• Ý kiến 4 phòng ban (Phê duyệt/CCM/MuaHàng/SM-PM)
• Export phiếu PDF/Excel

Optional

• Budget MaNganSach atomic sequence (chốt format chính thức)
• Budget versioned workflow (admin config UI)
• Payment terms PE tách field
• Auto-map PE Details → Contract Details
• Matrix Quotes bulk paste

Ops

• Remove binding cũ .huypham.vn
• win-acme fix unhealthy
• UAT thật 1 tuần với 2-3 user (30 user demo)
• SMTP config Email outbox
• Rotate credentials
• Schedule SQL backup

F. Stats sau session 4

	Trước session 4	Sau session 4
BE LOC	~11400	~11750 (+340 Budget)
DB tables	47	51 (+4 Budget)
API endpoints	~113	~124 (+11 Budget)
Migrations	13	14 (AddBudgets)
FE pages	~26	~26 (Budget FE TODO)
Demo user	16	30 (+14 Solutions thật)
Docs	~48	~50 (+ session log + chốt MD)
Gotchas	38	38 (no new)
Commits	~70	~75

G. Lessons learned session 4

1. Workflow simple hardcoded chấp nhận được khi user yêu cầu "tạm thời chưa có" — không over-engineer versioned WF + atomic sequence ngay từ đầu. User confirm BudgetPolicy.Default static + Random.Shared MaNganSach OK cho UAT, refine sau khi format chính thức chốt.

2. Auto-recompute ở app layer thay vì DB trigger — đơn giản hơn, debug dễ. Mỗi handler Detail mutation gọi budget.TongNganSach = budget.Details.Sum(d => d.ThanhTien). Trade-off: nếu N người sửa Detail concurrent thì cuối cùng còn đúng do tx wrap.

3. Reconcile pattern per-user try-catch chính xác cho seed user — 1 user fail (gotcha #38 4-field rename) không kill toàn bộ seed. Drift dept/position/role tự fix nếu user đã tồn tại.

4. Link nullable thay vì required FK giữa Budget và Contract/PE — không bắt buộc tất cả HĐ phải có ngân sách → FE form optional + filter Phase=DaDuyet khi pick. Tránh chicken-and-egg khi roll-out module mới.

H. Cảnh báo session 5

1. FE Budget chưa có gì — BE tested OK qua Swagger nhưng người dùng cuối chưa truy cập được. Đây là Priority 0.
2. PE/Contract chưa thấy field Ngân sách — BE đã có FK nhưng FE chưa wire. Priority 1.
3. Login email — admin@solutionerp.local vẫn dùng (chỉ rebrand demo + sample user). Update khi UAT thật.
4. Atomic sequence Budget chưa chốt — Random.Shared race condition risk thấp nhưng không zero. Nếu Solutions cần serial number nghiêm túc → migration AddBudgetCodeSequences + IBudgetCodeGenerator.
5. Versioned workflow Budget chưa có — nếu Solutions muốn admin config 5-step thay vì 3-step → migration AddBudgetVersionedWorkflow (3 bảng + pin per Budget).

Files touched session 4

src/Backend/SolutionErp.Domain/Budgets/                    (NEW — 5 file)
  ├── BudgetPhase.cs
  ├── Budget.cs
  ├── BudgetDetail.cs
  ├── BudgetApproval.cs
  ├── BudgetChangelog.cs
  └── BudgetPolicy.cs

src/Backend/SolutionErp.Domain/Contracts/Contract.cs       (mod: +BudgetId?)
src/Backend/SolutionErp.Domain/PurchaseEvaluations/PurchaseEvaluation.cs (mod: +BudgetId?)
src/Backend/SolutionErp.Domain/Identity/MenuKeys.cs        (mod: +Budgets keys)

src/Backend/SolutionErp.Infrastructure/Persistence/Configurations/
  ├── BudgetConfiguration.cs                               (NEW — 4 entity config)
  ├── ContractConfiguration.cs                             (mod: +BudgetId index)
  └── PurchaseEvaluationConfiguration.cs                   (mod: +BudgetId index)

src/Backend/SolutionErp.Infrastructure/Persistence/
  ├── ApplicationDbContext.cs                              (mod: +4 DbSet Budget*)
  └── DbInitializer.cs                                     (mod: +14 Solutions user + Budget menu seed)

src/Backend/SolutionErp.Infrastructure/Persistence/Migrations/
  └── 20260428043508_AddBudgets.cs                         (NEW — migration 14)
  └── 20260428043508_AddBudgets.Designer.cs                (NEW)
  └── ApplicationDbContextModelSnapshot.cs                 (mod)

src/Backend/SolutionErp.Application/Common/Interfaces/IApplicationDbContext.cs (mod: +4 DbSet)
src/Backend/SolutionErp.Application/Budgets/                (NEW — 2 file)
  ├── BudgetFeatures.cs                                     (~340 LOC, 11 CQRS handler)
  └── Dtos/BudgetDtos.cs                                    (6 DTO)

src/Backend/SolutionErp.Api/Controllers/BudgetsController.cs (NEW — 11 endpoint)

docs/STATUS.md                                              (mod: header + Recently Done + cumulative)
docs/HANDOFF.md                                             (mod: TL;DR + Priority 0 + creds)
docs/changelog/migration-todos.md                           (mod: Phase 7 partial + Phase 8 mới)
docs/architecture.md                                        (mod: +§10 Budget)
docs/database/schema-diagram.md                             (mod: +migration 13+14, +§12 Budget)
docs/CLAUDE.md                                              (mod: Phase 7 row + scope Budget)
CLAUDE.md                                                   (mod: modules table + scope)
.claude/skills/ef-core-migration/SKILL.md                   (mod: migration 14)
docs/changelog/sessions/2026-04-28-chot-session-4-budget.md (NEW — file này)
~/.claude/projects/.../memory/project_solution_erp.md       (mod: Phase 7 + 14 user)