e0b4e7f096
All checks were successful
Deploy SOLUTION_ERP / build-deploy (push) Successful in 2m53s
- STATUS.md: header Phase 7 + 3 row Recently Done (Budget BE / 14 users / Docs cleanup) + cumulative cột mới (51 tables / 14 mig / ~124 endpoints) - 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 - migration-todos.md: Phase 7 thêm section D Budget done + Phase 8 mới (FE Budget pages + integration) + pending migrations Budget - architecture.md: §10 Budget module mới (ERD + state machine + auto-recompute + integration roadmap) - database/schema-diagram.md: migration history rows 13+14 + §12 Budget ERD chi tiết - ef-core-migration SKILL: migration 14 entry + Phase 8 pending Budget refinement - CLAUDE.md root + docs: modules table thêm Budget row + scope Budget + count 51 bảng / 14 mig - Session log 2026-04-28-chot-session-4-budget.md (10+ section detailed) Stats: 51 tables (+4 Budget), 14 migrations (+AddBudgets), ~124 endpoints (+11 Budget), 30 demo user (16 sample + 14 Solutions thật), 38 gotchas, ~340 LOC Budget CQRS. FE Budget pages chưa làm — Priority 0 session 5. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
319 lines
17 KiB
Markdown
319 lines
17 KiB
Markdown
# Architecture — SOLUTION_ERP
|
||
|
||
> Kiến trúc tổng thể + trách nhiệm từng layer + diagram luồng dữ liệu.
|
||
|
||
## 1. Layered overview
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ CLIENT TIER │
|
||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||
│ │ fe-admin :8082 │ │ fe-user :8080 │ │
|
||
│ │ React 19 + Vite │ │ React 19 + Vite │ │
|
||
│ │ Tailwind 4 │ │ Tailwind 4 │ │
|
||
│ │ TanStack Query │ │ TanStack Query │ │
|
||
│ └────────┬─────────┘ └────────┬─────────┘ │
|
||
└───────────┼──────────────────────────┼───────────────────────┘
|
||
│ Vite dev proxy /api │
|
||
│ IIS URL Rewrite prod │
|
||
▼ ▼
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ API LAYER (:5443) │
|
||
│ SolutionErp.Api — ASP.NET Core 10 Web API │
|
||
│ ┌────────────────────────────────────────────────────────┐ │
|
||
│ │ Controllers: Auth, Menus, Roles, Permissions, │ │
|
||
│ │ Suppliers, Projects, Departments, │ │
|
||
│ │ Forms, Contracts, Reports │ │
|
||
│ │ Middleware: GlobalException, Serilog, CORS, JWT │ │
|
||
│ │ Authorization: MenuPermissionHandler (policy-based) │ │
|
||
│ │ Services: CurrentUserService, WebHostEnvLocator │ │
|
||
│ │ wwwroot/templates/ (5 .docx/.xlsx) │ │
|
||
│ └────────────────────┬───────────────────────────────────┘ │
|
||
└───────────────────────┼──────────────────────────────────────┘
|
||
│ MediatR ISender.Send(cmd)
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ APPLICATION LAYER │
|
||
│ SolutionErp.Application │
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ Auth │ │ Master │ │ Permissions │ │
|
||
│ │ (Login/Me) │ │ (CRUD 3 │ │ (Menu tree + │ │
|
||
│ │ │ │ entity) │ │ matrix) │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
|
||
│ ┌──────────────┐ ┌──────────────────┐ │
|
||
│ │ Forms │ │ Contracts │ ┌──────────────┐ │
|
||
│ │ (Render │ │ (Workflow 9 │ │ Reports │ │
|
||
│ │ engine) │ │ phase, Inbox) │ │ (Dashboard + │ │
|
||
│ └──────────────┘ └──────────────────┘ │ Excel exp) │ │
|
||
│ └──────────────┘ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ Common: Exceptions, Behaviors (ValidationPipeline), │ │
|
||
│ │ Interfaces (IDbContext, ICurrentUser, ...), │ │
|
||
│ │ Models (PagedResult) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└───────┬──────────────────────────────────────────┬───────────┘
|
||
│ depends on interface │ runs on
|
||
▼ ▼
|
||
┌──────────────────────┐ ┌───────────────────────────┐
|
||
│ DOMAIN LAYER │ │ INFRASTRUCTURE LAYER │
|
||
│ SolutionErp.Domain │ │ SolutionErp.Infrastructure│
|
||
│ │ │ │
|
||
│ Common/BaseEntity │ │ Persistence/ApplicationD │
|
||
│ Contracts/ │ │ bContext + Migrations │
|
||
│ Forms/ │ │ Identity/JwtTokenService │
|
||
│ Identity/ │ │ Forms/Docx+XlsxRenderer │
|
||
│ Master/ │ │ Services/ContractWorkflow│
|
||
│ │ │ + ContractCodeGenerator│
|
||
│ Enum + value object │ │ Reports/ExcelExporter │
|
||
└──────────────────────┘ │ Services/DateTimeService │
|
||
↑ └────────────┬──────────────┘
|
||
│ references │
|
||
└───────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌───────────────────────┐
|
||
│ DATA TIER │
|
||
│ SQL Server 2022 │
|
||
│ (dbo schema, 19 bảng)│
|
||
└───────────────────────┘
|
||
```
|
||
|
||
## 2. Request lifecycle (1 POST/api/contracts)
|
||
|
||
```
|
||
1. Browser → POST /api/contracts { type, supplierId, ... }
|
||
2. Vite → proxy tới :5443
|
||
3. JwtBearerMiddleware → validate token, set ClaimsPrincipal
|
||
4. Routing → ContractsController.Create(cmd)
|
||
5. MediatR.Send(CreateContractCommand)
|
||
6. ValidationBehavior (pipeline) → FluentValidation run
|
||
7. CreateContractCommandHandler
|
||
├─ check Supplier/Project exists (IApplicationDbContext)
|
||
├─ new Contract entity + set DrafterUserId (ICurrentUser)
|
||
├─ set SlaDeadline (IDateTime + IContractWorkflowService.GetPhaseSla)
|
||
├─ db.Contracts.Add(...)
|
||
└─ SaveChangesAsync
|
||
├─ AuditingInterceptor sets CreatedAt/CreatedBy
|
||
└─ EF Core INSERT → SQL Server
|
||
8. Return Guid id
|
||
9. Controller → 201 Created + Location header
|
||
10. Axios interceptor (FE) → TanStack Query invalidate + UI update
|
||
```
|
||
|
||
## 3. Workflow state machine (Phase 3)
|
||
|
||
Xem full ở [`workflow-contract.md`](workflow-contract.md).
|
||
|
||
```
|
||
DangChon → DangSoanThao → DangGopY → DangDamPhan → DangInKy →
|
||
→ DangKiemTraCCM → DangTrinhKy → DangDongDau → DaPhatHanh
|
||
|
||
Alternates: → TuChoi (từ DangSoanThao)
|
||
→ DangSoanThao (revise từ bất kỳ phase duyệt)
|
||
|
||
Bypass CĐT (BypassProcurementAndCCM=true):
|
||
DangInKy → DangTrinhKy (skip CCM)
|
||
```
|
||
|
||
**Code generator trigger:** khi `targetPhase = DangDongDau` + `MaHopDong IS NULL` → gen format RG-001 với transaction SERIALIZABLE.
|
||
|
||
## 4. Permission model
|
||
|
||
```
|
||
User ──(AspNetUserRoles)── Role ──(Permissions)── MenuItem
|
||
│
|
||
├── CanRead
|
||
├── CanCreate
|
||
├── CanUpdate
|
||
└── CanDelete
|
||
```
|
||
|
||
**Resolution:**
|
||
- Login → JWT chứa claims (sub, email, roles)
|
||
- `/api/menus/me` → query Permissions theo roleIds, **union OR** CRUD flags, filter tree theo CanRead
|
||
- FE cache menu trong `AuthContext` + localStorage
|
||
- Mỗi API action: `[Authorize(Policy = "{MenuKey}.{Action}")]` → `MenuPermissionHandler` check
|
||
|
||
**Admin bypass:** role `Admin` luôn pass mọi policy (seed default full CRUD).
|
||
|
||
## 5. Data flow — "tạo HĐ và chạy hết workflow"
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor D as Drafter
|
||
actor M as Manager (PD/PM)
|
||
actor C as CCM
|
||
actor B as BOD
|
||
actor H as HRA
|
||
|
||
participant FE as fe-user
|
||
participant API
|
||
participant WF as WorkflowService
|
||
participant CG as CodeGenerator
|
||
participant DB
|
||
|
||
D->>FE: POST /contracts/new
|
||
FE->>API: POST /api/contracts
|
||
API->>DB: INSERT Contracts (Phase=DangSoanThao, SLA=+7d)
|
||
API-->>FE: 201 {id}
|
||
|
||
D->>FE: Click "Submit → góp ý"
|
||
FE->>API: POST /contracts/{id}/transitions {target:3}
|
||
API->>WF: Transition(contract, 3, roles=[Drafter])
|
||
WF->>WF: Check adjacency + role
|
||
WF->>DB: INSERT ContractApproval + UPDATE Contract Phase=3
|
||
API-->>FE: 204
|
||
|
||
M->>FE: Inbox → click HĐ → góp ý + "Chuyển tiếp"
|
||
FE->>API: POST /transitions {target:4}
|
||
API->>WF: Transition → Phase 4
|
||
Note over WF: Chạy tương tự qua 5,6,7
|
||
|
||
B->>FE: Duyệt → target:8 DangDongDau
|
||
FE->>API: POST /transitions {target:8}
|
||
API->>WF: Transition
|
||
WF->>CG: GenerateAsync(contract, project, supplier)
|
||
CG->>DB: BEGIN TRAN SERIALIZABLE
|
||
CG->>DB: SELECT/UPDATE ContractCodeSequences
|
||
CG->>DB: COMMIT
|
||
CG-->>WF: "FLOCK 01/HĐGK/SOL&PVL/03"
|
||
WF->>DB: UPDATE Contract SET MaHopDong, Phase=8
|
||
API-->>FE: 204
|
||
|
||
H->>FE: Click đóng dấu → target:9
|
||
FE->>API: POST /transitions {target:9}
|
||
API->>WF: Transition (role HrAdmin)
|
||
WF->>DB: UPDATE Phase=9 (DaPhatHanh)
|
||
API-->>FE: 204
|
||
```
|
||
|
||
## 6. Deployment architecture (Phase 5 — planned)
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ Internet / Corp LAN │
|
||
└──────────────┬──────────────┘
|
||
│
|
||
┌──────────▼──────────┐
|
||
│ IIS (Win Server) │
|
||
│ URL Rewrite / ARR │
|
||
└──────────┬──────────┘
|
||
┌─────────────┼─────────────┐
|
||
│ │ │
|
||
┌──────▼──────┐ ┌───▼────┐ ┌──────▼──────┐
|
||
│ fe-admin │ │ Api │ │ fe-user │
|
||
│ static files│ │ Kestrel│ │ static files│
|
||
│ (dist/) │ │ :5443 │ │ (dist/) │
|
||
└─────────────┘ └───┬────┘ └─────────────┘
|
||
│
|
||
┌────────▼────────┐
|
||
│ SQL Server │
|
||
│ (same host OR │
|
||
│ separate VM) │
|
||
└─────────────────┘
|
||
```
|
||
|
||
- IIS app pool riêng cho Api, Integrated Managed Pipeline, .NET CLR disabled (hosting .NET 10 OOP)
|
||
- Static files 2 FE deploy vào `C:\inetpub\wwwroot\solution-erp-admin\` + `...user\`
|
||
- HTTPS: Let's Encrypt qua win-acme (hoặc cert mua)
|
||
- Backup SQL: daily full + 15min log → D:\Backups
|
||
|
||
## 7. Skill library (AI agent support)
|
||
|
||
`.claude/skills/` có 3 skill chuyên biệt:
|
||
|
||
| Skill | Dùng khi |
|
||
|---|---|
|
||
| [`contract-workflow`](../.claude/skills/contract-workflow/SKILL.md) | Debug chuyển phase, 403, mã HĐ, bypass CĐT |
|
||
| [`form-engine`](../.claude/skills/form-engine/SKILL.md) | Render template, upload, placeholder không replace |
|
||
| [`permission-matrix`](../.claude/skills/permission-matrix/SKILL.md) | Access denied, menu không hiện, gán role |
|
||
|
||
Claude auto-invoke theo description matching.
|
||
|
||
## 8. Non-functional
|
||
|
||
| Aspect | Current | Phase 5 target |
|
||
|---|---|---|
|
||
| Availability | dev-only | 99.5% (IIS restart, SQL HA optional) |
|
||
| Latency | <200ms P95 local | <500ms P95 prod |
|
||
| Concurrency | unrestricted | rate limit 100 req/min/IP |
|
||
| Observability | Serilog console | + file rolling daily + Seq/ELK |
|
||
| Security | JWT + HTTPS dev | + rate limit + audit log + CSP |
|
||
|
||
## 9. PurchaseEvaluation (Phase 6 — tiền-HĐ)
|
||
|
||
Module mới song song Contract — phiếu trình duyệt so sánh giá N NCC × M hạng mục, duyệt xong kế thừa làm HĐ.
|
||
|
||
```
|
||
PurchaseEvaluation (Header) ─< PurchaseEvaluationSupplier (N:M × Supplier)
|
||
─< PurchaseEvaluationDetail (hạng mục) ─< PurchaseEvaluationQuote (báo giá N×M)
|
||
─< PurchaseEvaluationApproval (workflow history)
|
||
─< PurchaseEvaluationChangelog (audit)
|
||
─< PurchaseEvaluationAttachment (file)
|
||
─> PurchaseEvaluationWorkflowDefinition (PINNED at create)
|
||
─> Contract? (nullable FK — set khi gen HĐ từ phiếu DaDuyet)
|
||
```
|
||
|
||
**Workflow** (tách riêng vì Phase enum khác ContractPhase):
|
||
- A `DuyetNcc` — 3 step: Drafter → Procurement → CostControl → Director → DaDuyet
|
||
- B `DuyetNccPhuongAn` — 5 step: + ProjectManager sau Procurement, + Director duyệt PA trước duyệt NCC
|
||
|
||
**Kế thừa HĐ** (`CreateContractFromEvaluationCommand`):
|
||
- Guard: phase = DaDuyet, SelectedSupplierId != null, ContractId = null
|
||
- User pick ContractType (1-7) → gen Contract draft với SupplierId/ProjectId/GiaTri kế thừa
|
||
- Pin `Contract.WorkflowDefinitionId` theo ContractType chọn
|
||
- Link 2 chiều: `PurchaseEvaluation.ContractId = contract.Id`
|
||
|
||
Chi tiết: [`database/schema-diagram.md §11`](database/schema-diagram.md).
|
||
|
||
## 10. Budget (Phase 7 — Module Ngân sách)
|
||
|
||
Module quản lý ngân sách dự án: header + chi tiết hạng mục + workflow simple 3-step + audit log. Liên kết nullable cả Contract và PurchaseEvaluation để đối chiếu chi phí.
|
||
|
||
```
|
||
Budget (Header) ─< BudgetDetail (flat row hạng mục)
|
||
─< BudgetApproval (workflow history)
|
||
─< BudgetChangelog (audit log)
|
||
─> Project (FK Restrict)
|
||
─> Department? (FK Restrict)
|
||
─> User Drafter (FK Restrict)
|
||
|
||
Contract.BudgetId? ──────────► Budget (link đối chiếu chi phí HĐ)
|
||
PurchaseEvaluation.BudgetId? ─► Budget (link đối chiếu chi phí tiền-HĐ)
|
||
```
|
||
|
||
**Phase enum** (`BudgetPhase` 5-state):
|
||
|
||
```
|
||
DangSoanThao(1) ──Trình──► ChoCCM(2) ──Duyệt──► ChoCEO(3) ──Duyệt──► DaDuyet(4)
|
||
▲ │ │
|
||
└──Reject(99)───────────┴─────────────────────┘
|
||
```
|
||
|
||
**Workflow simple hardcoded** (`BudgetPolicy.Default`):
|
||
- Drafter / DeptManager: DangSoanThao → ChoCCM (Trình) hoặc → TuChoi (Hủy)
|
||
- CostControl (CCM): ChoCCM → ChoCEO (Duyệt) hoặc → DangSoanThao (Trả về)
|
||
- Director / AuthorizedSigner: ChoCEO → DaDuyet (Duyệt) hoặc → DangSoanThao (Trả về)
|
||
|
||
**Mã ngân sách** `NS-{YYYYMM}-{Random:4d}` — hiện Random.Shared, sẽ chuyển atomic SERIALIZABLE khi format chốt chính thức (mirror Contract/PE pattern).
|
||
|
||
**Auto-recompute** `TongNganSach`:
|
||
- Sau Add/Update/Delete BudgetDetail → handler tự sum `Sum(d.ThanhTien)` lại Header.
|
||
- Tránh state drift, đơn giản hơn trigger DB.
|
||
|
||
**Integration roadmap**:
|
||
- PE form select Budget (filter `Phase=DaDuyet && NamNganSach=current && ProjectId match`)
|
||
- Contract form tương tự
|
||
- Tab Hạng mục PE/HD compute "So với ngân sách" (match GroupCode + ItemCode)
|
||
|
||
Chi tiết: [`database/schema-diagram.md §12`](database/schema-diagram.md).
|
||
|
||
## 11. Liên quan
|
||
|
||
- [`rules.md`](rules.md) — coding conventions
|
||
- [`database/database-guide.md`](database/database-guide.md) — DB schema chi tiết
|
||
- [`flows/`](flows/) — per-feature sequence diagrams
|
||
- [`workflow-contract.md`](workflow-contract.md) — state machine spec
|
||
- [`forms-spec.md`](forms-spec.md) — 8 form catalog
|