# 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
│   ├── guides/                     setup, cicd, code-rules...
│   ├── database/                   schema docs
│   └── changelog/
│       ├── migration-todos.md      Roadmap 5 phase
│       └── sessions/               YYYY-MM-DD session logs
├── .claude/skills/                 Skill library (contract-workflow, form-engine, ...)
├── 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`](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)