# 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ụ + **Phiếu Duyệt NCC tiền-HĐ** 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ý HĐ (state machine + role guard + SLA auto-approve + versioned WF per ContractType)
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ị
5. **Module Duyệt NCC (Phase 6-8)** — phiếu trình duyệt so sánh giá tiền-HĐ, 2 quy trình A/B versioned admin-config, kế thừa HĐ 1-click khi DaDuyet, Ý kiến 4 phòng ban sign-off
6. **Module Ngân sách (Phase 7-8)** — 4 bảng quản lý ngân sách dự án, workflow simple 3-step, integration link với Contract & PE + cột "So với ngân sách" PE matrix
7. **Test gate (Phase 8)** — xUnit Domain policy + Infra code generator, CI fail-fast no deploy

## 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 + Enums (Contracts/, PurchaseEvaluations/, Forms/, Identity/, Master/, Notifications/)
│   ├── SolutionErp.Application/    CQRS handlers, DTOs, Validators, Mappings, Interfaces
│   ├── SolutionErp.Infrastructure/ EF DbContext, Identity, Repositories, External services
│   └── SolutionErp.Api/            Controllers, Middleware, Program.cs, appsettings
├── fe-admin/                       (admin UI — CRUD master, approve, dashboards, workflow designer, permission matrix)
├── fe-user/                        (user UI — soạn HĐ + duyệt phiếu PE + inbox)
├── docs/
│   ├── CLAUDE.md                   (file này)
│   ├── STATUS.md                   ⭐ snapshot hiện tại + Recently Done
│   ├── HANDOFF.md                  ⭐ brief 5 phút cho session tiếp
│   ├── PROJECT-MAP.md              bản đồ tổng quan
│   ├── rules.md                    coding conventions
│   ├── architecture.md             layered + PE §9 + Budget §10 + Testing §11
│   ├── gotchas.md                  58 pitfall đã gặp
│   ├── forms-spec.md               8 form catalog + RG-001
│   ├── workflow-contract.md        9 phase HĐ + role matrix
│   ├── database/
│   │   ├── database-guide.md       conventions + migration workflow
│   │   └── schema-diagram.md       ERD 93 bảng (+§11 PE +§12 Budget +§13 PEDeptOpinions +§14 Contract V2 LevelOpinions; §16+ Mig 27-48 pending)
│   ├── flows/                      6 sequence diagram (auth/permission/contract/form/sla + PE ref architecture)
│   ├── guides/                     setup, cicd, deploy, runbook, security
│   ├── changelog/
│   │   ├── migration-todos.md      roadmap compact (Phase 0-5+Tier3 collapsed)
│   │   └── sessions/               session logs YYYY-MM-DD
│   └── _archive/                   raw dump Phase 0 (forms-spec-raw, workflow-raw)
├── .claude/skills/                 6 skill: 3 domain (contract-workflow, form-engine, permission-matrix) + 3 ops (dependency-audit-erp, ef-core-migration, iis-deploy-runbook)
├── scripts/                        deploy, migrate-domains, backup, deps-audit
├── SolutionErp.slnx                Solution file
├── global.json                     .NET 10 SDK pin
└── 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 (status 2026-04-29)

| Phase | Focus | Trạng thái |
|---|---|---|
| **0 Draft** | Scaffold, parse FORM + QUY_TRINH | ✅ Done |
| **1 Alpha Core** | Auth + Permission + CRUD master + Contract draft | ✅ Done |
| **2 Form Engine** | OpenXml + ClosedXML + LibreOffice PDF + DynamicForm | ✅ Done |
| **3 Workflow** | 9 phase state machine + RG-001 code gen + SLA job + attachments + SignalR | ✅ Done |
| **4 Reporting** | Dashboard KPI + Excel export + MyDashboard role-aware | ✅ Done |
| **5 Production** | CI/CD Gitea Actions + 3 IIS site + Let's Encrypt + Security headers + Users CRUD | ✅ Done |
| **Tier 3** | Versioned WF + 3-panel layout + 4-bảng + 4 catalogs + 16 demo users + Brand identity | ✅ Done |
| **6 Module Duyệt NCC** | PE iter 1 (skeleton) + iter 2 (UX polish) + Domain rebrand `.solutions.com.vn` | ✅ Done |
| **7 Budget BE + 14 Solutions users** | Migration 14 — 4 bảng Budget + workflow simple + 11 endpoint + 14 user thật | ✅ Done (Session 4) |
| **8 Budget FE + PE feature complete + Tests** | FE Budget 3-panel + PE/HD-Budget integration + PE Workflow Designer + Ý kiến 4 PB (mig 15) + Tests Phase 1-2 (71 test) + CI gate | ✅ Done (Session 5) |
| **9 UAT + Ops + carry over** | UAT thật + SMTP + Rotate creds + SQL backup + Export PDF (pending) + Tests Phase 3-5 | 📝 Active (Session 6) |
| **10+ Post-launch** | E-signature, Bravo/SAP, Mobile, AI OCR | 📝 Future |

Chi tiết atomic tasks: [`changelog/migration-todos.md`](changelog/migration-todos.md).
Session logs: [`changelog/sessions/`](changelog/sessions/).

## 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ệ + Production

- **Dev:** pqhuy1987@gmail.com (solo + Claude)
- **Prod login:** `admin@solutions.com.vn` / `Admin@123456` ⚠️ rotate sau login đầu
- **3 domain prod:**
  - https://api.solutions.com.vn — API
  - https://admin.solutions.com.vn — Admin FE
  - https://eoffice.solutions.com.vn — User FE
- **Gitea remote:** https://git.baocaogiaoduc.vn/vietreport-admin/solution-erp
- **SSH VPS:** `ssh vietreport-vps` (config sẵn `~/.ssh/config` user=Administrator key=id_ed25519)
- **Domain expert:** TBD (sẽ update sau UAT đầu tiên)