[CLAUDE] Phase4: Report MVP + Docs Consolidation (rules, architecture, schema-diagram)

Backend Report: - Application/Reports/Dtos/DashboardStatsDto: 5 KPI + PhaseCount + SupplierCount + ProjectCount + MonthlyValue - Application/Reports/Queries/GetDashboardStats handler: total/active/overdue/published this month/totalValueActive + byPhase + top 5 NCC/du an + 12 thang monthly (fill zero khi thang empty) - Application/Reports/Services/IContractExcelExporter interface - Infrastructure/Reports/ContractExcelExporter: ClosedXML workbook 10 cot, header style bold+blue, number format #,##0, formula SUM, auto-fit, freeze header - Application/Reports/Commands/ExportContractsToExcelCommand: filter phase/supplier/project/date range - Api/Controllers/ReportsController: GET /reports/dashboard, GET /reports/contracts/export - DI register IContractExcelExporter (Scoped) Frontend fe-admin: - types/reports.ts: DashboardStats type - components/BarChart.tsx: generic horizontal bar chart — chi Tailwind, khong thu vien ngoai - pages/DashboardPage.tsx REWRITE: 5 KPI card (FileText/TrendingUp/AlertTriangle/CheckCircle2/Coins) + by-phase bar + monthly 12-month chart + top 5 NCC + top 5 du an + skeleton loader - pages/ReportsPage.tsx MOI: filter phase/fromDate/toDate → export Excel button - Route /reports vao App.tsx E2E verified: - GET /api/reports/dashboard → 200 voi day du KPI + monthly fill 12 thang - GET /api/reports/contracts/export → 200 xlsx 7229 bytes (Microsoft Excel 2007+) Docs consolidation (theo yeu cau user): - docs/rules.md MOI: 9 section coding conventions (ngon ngu UI/code/DB/docs, BE Clean Arch, CQRS+MediatR, Validation FluentValidation, Error handling, Async, Entity rules, DI, Package pinning, FE React/TS erasableSyntaxOnly, path alias, TanStack Query, Permission guard, Toast+error, DB convention, Git commit format, Docs structure, Testing, Security) - docs/architecture.md MOI: layered overview ASCII art, request lifecycle (1 POST/api/contracts qua 10 step), workflow state machine 9 phase, permission model, data flow sequence diagram 4 actor (Drafter/Manager/CCM/BOD/HRA), deployment architecture Phase 5, skill library, non-functional table - docs/database/schema-diagram.md MOI: full ERD 19 table mermaid + data flow diagram + vong doi 1 HD (create → 7 transition → gen ma → publish) + index strategy table + relationship cardinality + soft delete behavior + SQL queries (inbox/dashboard/gen ma) + migration history - docs/gotchas.md UPDATE: 17 → 26 pitfalls, them section "Claude Code harness quirks" (Edit File not read, DI build pass nhung runtime fail) + "Contract workflow" (ma HD gen 2 lan, BE-FE NEXT_PHASES sync, race condition) + "Permission matrix" (cache real-time, MenuKey typo) - docs/STATUS.md: Phase 4 MVP done, docs entry points section liet ke het, next Phase 5 Production - docs/HANDOFF.md: phase table them Phase 4 row, file tree update voi Reports, test points day du, git state commit 7 - docs/changelog/migration-todos.md: tick Phase 4 MVP items + them iteration 2 list - docs/changelog/sessions/2026-04-21-1430-phase4-report.md: session log voi thong so cumulative (BE 3100 LOC, 30 docs) - CLAUDE.md root: update Tai lieu quan trong section them rules.md, architecture.md, schema-diagram.md, .claude/skills (13 links now) Bug fix: - TS unused import ContractPhaseLabel trong DashboardPage - DI thieu register IContractExcelExporter — build pass but runtime would fail (added) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 12:42:46 +07:00
parent 7e957a7654
commit fe7ad8e4a3
21 changed files with 1817 additions and 212 deletions
--- a/docs/HANDOFF.md
+++ b/docs/HANDOFF.md
@ -1,6 +1,6 @@
 # HANDOFF — Brief 5 phút cho session tiếp theo

-**Last updated:** 2026-04-21 13:30 (cuối Phase 3 MVP)
+**Last updated:** 2026-04-21 14:30 (cuối Phase 4 MVP + docs consolidation)

 ## Ở đâu rồi?

@ -11,10 +11,11 @@
 | 1 Alpha Core đợt 2 (CRUD + Permission) | ✅ Done |
 | 2 Form Engine MVP | ✅ Done |
 | 2 Form Engine iteration 2 | 📝 Optional |
-| **3 Workflow MVP (9 phase + code gen)** | ✅ Done |
+| 3 Workflow MVP (9 phase + code gen) | ✅ Done |
 | 3 Workflow iteration 2 (SLA job + notify + attachment) | 📝 Optional |
-| 4 Report + Polish | 📋 Next |
-| 5 Production (CI/CD IIS) | 📋 Queue |
+| **4 Report + Polish MVP (Dashboard + Excel)** | ✅ Done |
+| 4 Report iteration 2 (SLA report, PDF export) | 📝 Optional |
+| 5 Production (CI/CD IIS) | 📋 Next |

 ## Run nhanh

@ -31,34 +32,43 @@ cd fe-user && npm run dev   # → http://localhost:8080

 Login: `admin@solutionerp.local` / `Admin@123456`

-Điểm cần test ngay (Phase 3 MVP):
+Điểm cần test ngay (Phase 4 MVP):
+- **Admin `/dashboard`** → 5 KPI card + By Phase bar + Monthly chart + Top NCC/dự án
+- **Admin `/reports`** → filter phase/date → Export Excel .xlsx 10 cột có formula SUM
 - **fe-user `/contracts/new`** → tạo HĐ draft (Phase 2 DangSoanThao, SLA +7d)
 - **fe-user `/inbox`** → xem HĐ chờ role mình xử lý
- **`/contracts/{id}`** (cả 2 FE) → click "Duyệt → tiếp" chạy state machine. Đến phase 8 DangDongDau → xem `MaHopDong` tự gen theo RG-001
- **`/forms`** (admin) → render template .docx với JSON data
+- **`/contracts/{id}`** → click "Duyệt → tiếp" chạy state machine. Phase 8 gen `MaHopDong` RG-001
+- **`/forms`** → render template .docx
 - **`/system/permissions`** → ma trận Role × MenuKey
 - **`/master/suppliers|projects|departments`** → CRUD

 ## Cần làm kế tiếp (ưu tiên)

-### A. Phase 4 — Report + Polish (tuần 10-11)
+### A. Phase 5 — Production (tuần 12-13, item lớn nhất còn lại)

- Dashboard admin: HĐ theo phase, top NCC, top dự án, tổng giá trị tháng
- Excel export list HĐ (dùng ClosedXML đã có)
- Report quá hạn SLA theo phase/role
- UX polish: skeleton loader, empty state có action, error boundary recovery
- Accessibility: keyboard nav, aria labels
- Index DB hot query (SupplierId, ProjectId, Phase combo)
- User guide docs
+**Đọc trước:** `docs/changelog/migration-todos.md` section Phase 5.

-### B. Phase 3 iteration 2 (polish workflow)
+- [ ] `.gitea/workflows/deploy.yml` CI/CD build + deploy IIS
+- [ ] `scripts/deploy-iis.ps1` stop app pool → xcopy → start
+- [ ] Windows Server IIS + URL Rewrite + ARR (reverse proxy FE → .NET)
+- [ ] HTTPS cert via win-acme hoặc mua
+- [ ] `appsettings.Production.json` + user secrets + JWT secret rotation
+- [ ] Rate limiting middleware (auth endpoint 5 req/min/IP)
+- [ ] Security audit OWASP top 10
+- [ ] Health check endpoint `/health`
+- [ ] Serilog → file rolling daily retention 30d
+- [ ] SQL backup: daily full + 15min log
+- [ ] Runbook: restart, rollback migration, restore backup
+- [ ] UAT production 1 tuần với 2-3 user thật
+- [ ] Go-live checklist

- [ ] `SlaExpiryJob` BackgroundService auto-approve (xem `flows/sla-expiry-flow.md`)
- [ ] Email notification (MailKit) — pick up phase + SMTP config
- [ ] In-app notification (SignalR + badge counter)
- [ ] Upload attachment endpoint + FE multipart (store vào `wwwroot/uploads/contracts/{id}/`)
- [ ] RowVersion optimistic concurrency (2 user race → 409)
- [ ] Render HĐ docx lúc tạo (merge TemplateId + DraftData + ContractClause appendix)
+### B. Polish iterations (optional — khi rảnh)
+
+**Phase 2 iter 2:** convert 3 .doc qua Word COM `DisplayAlerts=0` hoặc LibreOffice, field spec JSON + form builder FE dynamic, `{{#loop}}` block support, PDF convert, FE upload template multipart.
+
+**Phase 3 iter 2:** `SlaExpiryJob` BackgroundService auto-approve, email (MailKit) + in-app (SignalR) notify, upload attachment endpoint + FE multipart (`wwwroot/uploads/contracts/{id}/`), RowVersion concurrency, render HĐ docx khi tạo (merge TemplateId + DraftData + ContractClause).
+
+**Phase 4 iter 2:** SLA overdue report by role/phase, PDF HĐ export (LibreOffice), dashboard user-specific (role tôi).

 ### C. Phase 2 iteration 2 (form engine polish)

@ -98,42 +108,53 @@ SOLUTION_ERP/
 │   ├── SolutionErp.Application/
 │   │   ├── Auth/             Login, Refresh, Me
 │   │   ├── Common/           Exceptions, Behaviors, Interfaces, Models
-│   │   ├── Contracts/        **ContractFeatures (8 CQRS), IContractWorkflowService, IContractCodeGenerator, DTOs** ← Phase 3
+│   │   ├── Contracts/        ContractFeatures (8 CQRS), IContractWorkflowService, IContractCodeGenerator, DTOs  ← Phase 3
 │   │   ├── Forms/            FormFeatures (List/Get/Render)  ← Phase 2
 │   │   ├── Master/           Suppliers, Projects, Departments CQRS
-│   │   └── Permissions/      GetMyMenuTree, matrix upsert
+│   │   ├── Permissions/      GetMyMenuTree, matrix upsert
+│   │   └── Reports/          **DashboardStats, ExportContractsToExcel, IContractExcelExporter** ← Phase 4
 │   ├── SolutionErp.Infrastructure/
 │   │   ├── Forms/            DocxRenderer, XlsxRenderer, FormRenderer  ← Phase 2
 │   │   ├── Identity/         JwtSettings, JwtTokenService
-│   │   ├── Persistence/      DbContext, DbInitializer, Interceptors, Migrations (**5** now)
-│   │   └── Services/         DateTimeService, **ContractWorkflowService, ContractCodeGenerator** ← Phase 3
+│   │   ├── Persistence/      DbContext, DbInitializer, Interceptors, Migrations (**5**)
+│   │   ├── Reports/          **ContractExcelExporter** ← Phase 4
+│   │   └── Services/         DateTimeService, ContractWorkflowService, ContractCodeGenerator  ← Phase 3
 │   └── SolutionErp.Api/
 │       ├── Authorization/    MenuPermissionHandler + Requirement
-│       ├── Controllers/      Auth, Suppliers, Projects, Departments, Menus, Roles, Permissions, Forms, **Contracts** ← Phase 3
+│       ├── Controllers/      Auth, Suppliers, Projects, Departments, Menus, Roles, Permissions, Forms, Contracts, **Reports** (10 controller)
 │       ├── Middleware/       GlobalExceptionMiddleware
 │       ├── Services/         CurrentUserService, WebHostEnvironmentLocator
 │       └── wwwroot/templates/ 5 file .docx/.xlsx  ← Phase 2
-├── fe-admin/                  (9 page)
+├── fe-admin/                  (11 page)
 │   └── src/pages/
 │       ├── LoginPage
-│       ├── DashboardPage
+│       ├── DashboardPage  ← Phase 4 rewrite (KPI cards + BarChart)
 │       ├── master/SuppliersPage, ProjectsPage, DepartmentsPage
 │       ├── system/PermissionsPage
 │       ├── forms/FormsPage  ← Phase 2
-│       └── contracts/ContractsListPage, ContractDetailPage  ← Phase 3
+│       ├── contracts/ContractsListPage, ContractDetailPage  ← Phase 3
+│       └── ReportsPage  ← Phase 4
 ├── fe-user/                   (5 page)
 │   └── src/pages/
 │       ├── LoginPage
 │       ├── InboxPage  ← Phase 3
 │       └── contracts/ContractCreatePage, ContractDetailPage, MyContractsPage  ← Phase 3
-├── docs/                      (26 file — STATUS, PROJECT-MAP, workflow, forms-spec, database-guide, 6 flow, gotchas, HANDOFF, 5 session log)
-└── .claude/skills/            (3 skill — all full spec: contract-workflow, form-engine, permission-matrix)
+├── docs/                      (30 file)
+│   ├── STATUS.md, HANDOFF.md, rules.md, architecture.md
+│   ├── CLAUDE.md, PROJECT-MAP.md
+│   ├── workflow-contract.md, forms-spec.md
+│   ├── database/{database-guide, schema-diagram}.md
+│   ├── flows/ (7 file — README + 6 flow)
+│   ├── changelog/migration-todos.md + sessions/ (6 session log)
+│   └── gotchas.md
+└── .claude/skills/            (3 skill — all full spec)
 ```

 ## Git state

 ```
-(sẽ là commit 6) — Phase 3 Workflow MVP
+(sẽ là commit 7) — Phase 4 Report MVP + docs consolidation
+7e957a7 — Phase 3 Workflow MVP
 5113e4c — Phase 2 Form Engine MVP
 54d6c9b — Phase 1.2 CRUD + Permission
 49a5f57 — Docs database-guide + flows
@ -141,7 +162,7 @@ SOLUTION_ERP/
 25dad7f — Phase 0 scaffold

 Branch: main
-Remote: chưa (Gitea URL chờ user)
+Remote: chưa (Gitea URL chờ user — cần cho Phase 5)
 ```

 ## Credentials + URLs