52999f33fa
Some checks failed
Deploy SOLUTION_ERP / build-deploy (push) Failing after 22s
Session 5 (29/04) — 6 commit feature + 1 chốt MD này. ==== Stats sau session 5 ==== - 52 DB tables (+1 PEDeptOpinions) - 15 migrations (+`AddPurchaseEvaluationDepartmentOpinions`) - ~128 API endpoints (+4) - ~31 FE pages (+5 Budget + 1 PeWorkflowsPage) - 71 unit test pass (54 Domain + 17 Infra) — CI gate live, fail → no deploy - ~13050 BE LOC (+1300) - 30 demo user, 38 gotchas, 6 skill (no change) ==== MD touched ==== - STATUS.md: header Phase 8 + 6 row Recently Done session 5 + cumulative cột S5 + In Progress S6 (Hard blockers + Optional polish + Tests Phase 3-5 + Ops) - HANDOFF.md: TL;DR 6 milestone S5 + Cảnh báo S6 (CI test gate workflow mới) + Priority 0 S6 (UAT + Ops focus) + Phase status table cập nhật - migration-todos.md: Phase 8 done với A/B/C/D/E (FE Budget / PE-HD integration / PE WF Designer / Ý kiến 4 PB / Tests Phase 1-2) + Phase 9 active (UAT + Ops + carry over) - architecture.md: §11 Testing strategy mới (test pyramid bottom-heavy + stack + CI gate + phased priority + quy tắc bổ sung mỗi feature) - database/schema-diagram.md: Migration 15 row + total 52 tables + §13 PE Department Opinion (1 bảng UNIQUE PEId+Kind + Upsert behavior + SQL DDL) - ef-core-migration SKILL: migration 15 entry + 52 tables total + Phase 8 update note - CLAUDE.md (root): modules table + Tests row + scope `Tests` + Tests section mới + count update 15/52 - docs/CLAUDE.md: 7 module bullet + ERD 52 bảng + Roadmap Phase 8 done + Phase 9 active S6 - memory project_solution_erp.md: Phase 8 summary + Session 6 priority + workflow user mới (dotnet test → commit → push) - session log 2026-04-29-chot-session-5-budget-fe-pe-tests.md (NEW — 10+ section detail) ==== Verify ==== - dotnet test SolutionErp.slnx → 71 pass / 2s - git status clean sau commit này Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
371 lines
20 KiB
Markdown
371 lines
20 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. Testing strategy (Phase 8 — Session 5)
|
||
|
||
Test pyramid bottom-heavy, **không E2E** (brittle, maintenance cao cho solo dev).
|
||
|
||
```
|
||
┌──────────────────────────────────┐ ❌ Skip
|
||
│ E2E / UI (Playwright) │ Brittle, slow, tốn time maintain
|
||
├──────────────────────────────────┤ ⚠️ TODO Phase 4
|
||
│ API smoke (WebApplicationFactory)│ 1-2 happy path roundtrip per critical endpoint
|
||
├──────────────────────────────────┤ ⚠️ TODO Phase 3
|
||
│ Application Handler (CQRS) │ EF InMemory cho business rules
|
||
├──────────────────────────────────┤ ✅ Done Phase 2 — 17 test
|
||
│ Infrastructure (SQLite in-mem) │ Code generator format + sequence + year boundary
|
||
├──────────────────────────────────┤ ✅ Done Phase 1 — 54 test
|
||
│ Domain Policy (pure functions) │ State machine + role transition + Registry mapping
|
||
└──────────────────────────────────┘
|
||
```
|
||
|
||
**Stack:**
|
||
|
||
| Layer | Framework | Note |
|
||
|---|---|---|
|
||
| .NET test | xUnit 2.9.3 | Industry standard |
|
||
| Assertion | FluentAssertions 7.2 | Pin trước v8 commercial license |
|
||
| EF testing | Microsoft.EntityFrameworkCore.Sqlite 10 | Phase 2+ — supports transactions |
|
||
| Test fixture | Custom `SqliteDbFixture` + `TestApplicationDbContext` | Override `nvarchar(max) → TEXT` cho SQLite compat |
|
||
|
||
**CI gate:** `.gitea/workflows/deploy.yml` chạy `dotnet test` cho từng test project TRƯỚC build/publish/deploy. Test fail → `exit $LASTEXITCODE` → no deploy.
|
||
|
||
```yaml
|
||
- name: Run unit tests (Domain)
|
||
run: dotnet test tests/SolutionErp.Domain.Tests/...
|
||
|
||
- name: Run integration tests (Infrastructure)
|
||
run: dotnet test tests/SolutionErp.Infrastructure.Tests/...
|
||
```
|
||
|
||
**Phase priority — anti-overkill:**
|
||
|
||
1. **Phase 1 (Done)** — Domain policy: 3 test file (Contract WF / PE WF / Budget) cover transition rules + Registry + FromDefinition. ~54 test, < 7s.
|
||
2. **Phase 2 (Done)** — Infra code generator: format RG-001/PE + sequence increment + year boundary (framework HĐ). ~17 test, ~2s.
|
||
3. **Phase 3 (Pending)** — Application CQRS handler: critical state-change handlers (Transition + Create) với EF InMemory.
|
||
4. **Phase 4 (Pending)** — API smoke: WebApplicationFactory + SQLite, 5-7 endpoint critical roundtrip.
|
||
5. **Phase 5 (Pending)** — FE Vitest cho lib utility (queryMatches, fmtMoney) — chỉ pure functions, KHÔNG component snapshot.
|
||
|
||
**Quy tắc bổ sung mỗi feature mới:**
|
||
- Domain policy method → 2-3 test (positive + negative + edge)
|
||
- CQRS handler có guard → 1 test mỗi guard branch
|
||
- Bug found in production → 1 regression test added before merge
|
||
|
||
Detail run: `dotnet test SolutionErp.slnx` chạy cả 71 test ~2s.
|
||
|
||
## 12. 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
|