7ca6c914fa
All checks were successful
Deploy SOLUTION_ERP / build-deploy (push) Successful in 2m55s
User feedback: "phần Duyệt NCC chưa xong đâu đấy nhé, còn chỉnh nhiều" → mark PE module skeleton (not feature-complete), liệt kê chi tiết chức năng/UX/edge-case còn missing cho session tiếp. Update 7 file: - STATUS.md — phase = "PE skeleton + refinement WIP", In Progress liệt kê 4 nhóm: A Chức năng MISSING (9 item), B UX/Polish (6 item), C Edge case (4 item), D Deploy/Ops (1 item). +G-084 row Recently Done. - HANDOFF.md — TL;DR "PE skeleton, còn chỉnh nhiều" + Priority 0 section cho session tiếp (9 task PE refinement) + cảnh báo runner + G-084. - migration-todos.md — Phase 7 checklist (A/B/C/D nhóm) trước Phase 8 post-launch. Pending migrations: PaymentTermFields + DepartmentOpinions + CodeSequences. - architecture.md — Section 9 PurchaseEvaluation module (ERD + workflow A/B + kế thừa HĐ flow). - CLAUDE.md (root) — 5 file đọc đầu (thêm HANDOFF), Modules table, 12 migration 46 bảng, +PurchaseEvaluation commit scope. - .claude/skills/ — 4 skill cross-ref Phase 6: * README: trạng thái updated với Phase 6 note * contract-workflow: note PE workflow tách table riêng * permission-matrix: +Pe_*/PeWf_* menu keys + TODO grant non-admin * ef-core-migration: 12 migration history + Phase 7 pending - docs/changelog/sessions/2026-04-23-2359-chot-session-pe-skeleton.md — session log full commits + MD files updated + session tiếp priorities + notes (PE là skeleton, runner check, G-084 rule, MaPhieu format).
277 lines
15 KiB
Markdown
277 lines
15 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. 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
|