solution-erp/docs/CLAUDE.md

CLAUDE.md — Full Context (SOLUTION_ERP)

1. Giới thiệu

SOLUTION_ERP là hệ thống quản lý Hợp đồng Nhà cung cấp / Thầu phụ / Tổ đội / Dịch vụ cho Công ty TNHH Xây dựng Solutions, thay thế quy trình giấy / Word+Excel hiện tại.

Scope chính:

1. Số hóa 8 form hợp đồng (template engine điền field → export .docx/.xlsx)
2. Workflow 9 phase trình ký (state machine + role guard + SLA auto-approve)
3. Tự gen mã HĐ theo Quy định SOL-CCM-RG-001
4. Dashboard báo cáo HĐ theo NCC, dự án, trạng thái, giá trị

2. Kiến trúc tổng thể

┌────────────────┐  ┌────────────────┐
│  fe-admin      │  │  fe-user       │    React 18 + Vite + TS + shadcn/ui
│  :8082         │  │  :8080         │    TanStack Query, Tailwind
└────────┬───────┘  └────────┬───────┘
         │                   │
         │   Vite proxy /api → :5443
         ▼                   ▼
┌──────────────────────────────────────┐
│  SolutionErp.Api :5443               │    ASP.NET Core 10 + JWT
│  Controllers / Middleware / Swagger  │
└──────────────┬───────────────────────┘
               │
      ┌────────▼─────────┐
      │ SolutionErp.     │    CQRS + MediatR
      │ Application      │    FluentValidation + AutoMapper
      └────────┬─────────┘
               │
      ┌────────▼─────────┐    ← SolutionErp.Infrastructure
      │ SolutionErp.     │         (EF Core, Identity, Repos, External services)
      │ Domain           │
      └──────────────────┘
               │
               ▼
       ┌────────────────┐
       │  SQL Server    │    dbo schema, GUID PK
       └────────────────┘

3. Project layout

SOLUTION_ERP/
├── src/Backend/
│   ├── SolutionErp.Domain/         Entities, ValueObjects, Enums, DomainEvents
│   ├── SolutionErp.Application/    CQRS handlers, DTOs, Validators, Mappings, Interfaces
│   ├── SolutionErp.Infrastructure/ EF DbContext, Identity, Repositories, External
│   └── SolutionErp.Api/            Controllers, Middleware, Program.cs, appsettings
├── fe-admin/                       (admin UI — CRUD master data, approve, dashboards)
│   └── src/
├── fe-user/                        (user UI — soạn thảo HĐ, comment, upload)
│   └── src/
├── docs/
│   ├── CLAUDE.md                   (file này)
│   ├── STATUS.md
│   ├── PROJECT-MAP.md
│   ├── forms-spec.md               ⭐ 8 form catalog + RG-001 code format
│   ├── workflow-contract.md        ⭐ 9 phase state machine + role matrix
│   ├── database/
│   │   └── database-guide.md       ⭐ Conventions, schema hiện tại + planned, ERD, migration workflow
│   ├── flows/                      ⭐ Sequence/state diagram mỗi feature
│   │   ├── README.md               (index)
│   │   ├── auth-flow.md            ✅ implemented
│   │   ├── permission-flow.md      📝 Phase 1 đợt 2
│   │   ├── contract-creation-flow.md  📝 Phase 2
│   │   ├── contract-approval-flow.md  📝 Phase 3
│   │   ├── form-render-flow.md     📝 Phase 2
│   │   └── sla-expiry-flow.md      📝 Phase 3
│   ├── guides/                     setup, cicd, code-rules...
│   └── changelog/
│       ├── migration-todos.md      Roadmap 5 phase
│       └── sessions/               YYYY-MM-DD session logs
├── .claude/skills/                 6 skill: 3 domain (contract-workflow, form-engine, permission-matrix) + 3 ops (dependency-audit-erp, ef-core-migration, iis-deploy-runbook)
├── scripts/                        parse_forms.py, parse_workflow.py, seed, deploy
├── SolutionErp.slnx                Solution file
├── global.json                     .NET 10 SDK pin
├── docker-compose.yml              SQL Server cho dev
└── CLAUDE.md                       Pointer → docs/CLAUDE.md

4. Tech stack chi tiết

Layer	Tech	Version
.NET SDK	.NET	10.0.104
ORM	EF Core	10
DB	SQL Server	2019+ (LocalDB dev)
API	ASP.NET Core Web API	10
Mediator	MediatR	latest
Validation	FluentValidation	latest
Mapping	AutoMapper	latest
Auth	JWT Bearer + ASP.NET Identity	10
Logging	Serilog	latest
OpenAPI	Swashbuckle	latest
FE Build	Vite	8
FE Lib	React	19 (auto-scaffolded)
FE Lang	TypeScript	6
FE Styling	Tailwind CSS + shadcn/ui	Phase 1 install
FE Data	TanStack Query	Phase 1 install
Node (local)	>= 20	local có thể Node 22
Node (CI)	pin 20.x	bài học từ NamGroup

5. Reference projects

• NamGroup (D:\Dropbox\CONG_VIEC\NAMGROUP\SOURCECODE_CÔNG_TY\NAMGROUP\) — template 2 FE + IIS deploy + permission matrix
• DH_Y_DUOC (D:\Dropbox\CONG_VIEC\DAI_Y_DUOC\DH_Y_DUOC_SOURCECODE\DH_Y_DUOC\) — template backend hiện đại (Clean Arch + CQRS + EF migrations)

6. Roadmap 5 phase (summary)

Phase	Tuần	Focus	Exit criteria
0 Draft	T1	Scaffold, parse FORM + QUY_TRINH	Build pass, docs đủ
1 Alpha Core	T2-4	Auth + Permission + CRUD Supplier/Project/Contract	Admin tạo HĐ draft + gán role
2 Form Engine	T5-6	Template engine 8 form, export .docx/.xlsx	Export 1 HĐ giống mẫu 100%
3 Workflow	T7-9	State machine 9 phase + SLA + notify	HĐ đi hết quy trình → có mã số
4 Report + Polish	T10-11	Dashboard, Excel export, UX pass	UAT 5-10 HĐ thật
5 Production	T12-13	CI/CD IIS, security, runbook, UAT	Go-live

Chi tiết atomic tasks ở changelog/migration-todos.md.

7. Quy ước code

• Ngôn ngữ UI: 100% tiếng Việt. Code + comment + tên DB table: English.
• Tên file: PascalCase cho .cs, kebab-case cho TS/TSX (trừ React component = PascalCase).
• Null safety: .NET bật nullable reference types. TS strict: true.
• Async/await cho mọi I/O.
• Error handling BE: GlobalExceptionMiddleware → map exception → ProblemDetails. KHÔNG try-catch ở controller.
• Error handling FE: error boundary + toast. Dùng useErrorHandler hook.
• Logging: Serilog structured. Không Console.WriteLine.

8. Security baseline

• HTTPS everywhere (IIS redirect HTTP → HTTPS)
• JWT expiry 1h, refresh token 7d
• Password hash: Identity default (PBKDF2)
• CORS: whitelist chỉ 2 FE origin
• Rate limit: 100 req/min/IP cho endpoint auth
• SQL injection: EF Core parameterized (không raw SQL trừ khi cần)
• Audit log: mọi write → AuditLog table

9. Liên hệ

• Dev: pqhuy1987@gmail.com (solo)
• Domain expert: TBD (sẽ update sau UAT đầu tiên)