49a5f57a50
docs/database/database-guide.md: - Conventions (naming, data types, audit fields, soft delete) - Schema hien tai (Identity tables sau migration Init) + seed 12 role + admin - Schema planned: Phase 1 dot 2 (Supplier/Project/Department + Permission Matrix) - Schema planned: Phase 3 (Contract + Approval + Comment + Attachment + Template + Clause + CodeSequence) - Mermaid ERD cho tung phase - Migration workflow (create/apply/revert) - Index strategy + unique indexes - Backup/restore SQL - Common pitfalls + SQL cheatsheet docs/flows/ — 6 flow documentation: - README.md: index - auth-flow.md: login/refresh/me/logout (IMPLEMENTED, sequence + edge cases + security checklist) - permission-flow.md: Phase 1 dot 2 - Role x MenuKey x CRUD resolution + FE guard + BE policy - contract-creation-flow.md: Phase 2 - Drafter flow chon template -> fill -> preview -> save draft - contract-approval-flow.md: Phase 3 - state machine 9 phase chi tiet + reject flow + timeline UI - form-render-flow.md: Phase 2 - OpenXml + ClosedXML + LibreOffice PDF convert - sla-expiry-flow.md: Phase 3 - BackgroundService auto-approve qua SLA + warning notify Update references: - CLAUDE.md (root): them 2 row Tai lieu quan trong - docs/CLAUDE.md: update project layout voi flows/ + database/ - docs/STATUS.md: log docs addition - docs/changelog/migration-todos.md: tick Phase 0 docs items Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
149 lines
7.2 KiB
Markdown
149 lines
7.2 KiB
Markdown
# 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/ 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)
|