From 7710d4345c60d24de37783ed527a559d27c9de0d Mon Sep 17 00:00:00 2001 From: pqhuy1987 Date: Sat, 9 May 2026 21:40:34 +0700 Subject: [PATCH] =?UTF-8?q?[CLAUDE]=20Docs+Skill:=20Session=2019=20consoli?= =?UTF-8?q?date=20=E2=80=94=20schema-diagram=20=C2=A715=20+=20skill=20refr?= =?UTF-8?q?esh?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit User chốt Session 19 toàn bộ: update các MD chưa làm ở Chunk D Docs trước (theo §6.5 không cố sửa khi không cần — nhưng schema mới fundamental + skill drift quá lệch → đáng update ngay). - docs/database/schema-diagram.md — thêm §15 PE Level Opinions V2 (Mig 26): bối cảnh decision (5 câu Q&A user chốt), schema bảng + constraint design rationale (UNIQUE composite, FK Cascade Pe + Restrict Level, denorm SignedByFullName), Service hook pattern (ApproveV2Async UPSERT), so sánh anti-pattern Mig 15 cũ (endpoint POST/opinions rời) vs Mig 26 (Service hook auto sync khi Duyệt). Pattern reusable cho derived state khác. §16 cũ "Liên quan" đổi thành §16 (renumber). - .claude/skills/ef-core-migration/SKILL.md — frontmatter "21 migration" → "26 migration" + table history thêm Mig 22 ApprovalWorkflowsV2 / Mig 23 PE.ApprovalWorkflowId / Mig 24 CurrentApprovalLevelOrder / Mig 25 IsUserSelectable / Mig 26 PeLevelOpinionsForV2. Total bảng 55→59. Code pointers + Related cross-ref §15 mới. - .claude/skills/README.md — count "16 migration" → "26 migration" + "41 bẫy" → "44 bẫy" (drift cumulative S16-S19 patch). Path filter `.claude/skills/**` + `docs/**` → CI skip deploy (gotcha #41). Verify: dotnet test 81 pass (no regression). Memory home dir KHÔNG commit (ở C:\Users\pqhuy\.claude\): add entry mới `feedback_service_hook_vs_endpoint.md` + MEMORY.md index +1 row (15 entries total). --- .claude/skills/README.md | 4 +- .claude/skills/ef-core-migration/SKILL.md | 15 +++-- docs/database/schema-diagram.md | 80 +++++++++++++++++++++-- 3 files changed, 88 insertions(+), 11 deletions(-) diff --git a/.claude/skills/README.md b/.claude/skills/README.md index ffa74e1..3d3a8ef 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -17,7 +17,7 @@ Skill này là tài liệu chuyên biệt để Claude (và developer khác) dù | Skill | Mục đích | Trigger ví dụ | Trạng thái | |---|---|---|---| | `dependency-audit-erp` | Scan CVE NuGet + npm 2 FE, respect pin constraint (MediatR 12.4.1, Swashbuckle 6.9.0) | "npm audit", "dotnet vulnerable", "deps scan", "nâng cấp package" | ✅ New Tier 3 | -| `ef-core-migration` | Tạo/revert EF Core 10 migration, 3-file rule, DesignTimeDbContextFactory, **16 migration history** (Init → AddTwoStageDeptApprovalAndSmartReject) | "thêm migration", "EF migration", "schema update", "snapshot lỗi" | ✅ Updated Phase 9 (Mig 16) | +| `ef-core-migration` | Tạo/revert EF Core 10 migration, 3-file rule, DesignTimeDbContextFactory, **26 migration history** (Init → AddPeLevelOpinionsForV2) | "thêm migration", "EF migration", "schema update", "snapshot lỗi" | ✅ Updated Session 19 (Mig 26 PE Level Opinions V2) | | `iis-deploy-runbook` | 3 IIS site + win-acme cert + gitea-runner + LibreOffice + debug 500/502/SignalR prod + **G-084 IPv4/IPv6 hardening** | "prod 500", "IIS fail", "cert hết hạn", "restart app pool", "deploy IIS", "port hijack" | ✅ Updated (G-084) | ## Format chuẩn 1 skill @@ -87,5 +87,5 @@ when-to-use: ## Related - `docs/CLAUDE.md` — quick rules + full stack context -- `docs/gotchas.md` — 41 bẫy đã gặp +- `docs/gotchas.md` — 44 bẫy đã gặp - `docs/changelog/migration-todos.md` — roadmap 5 phase + Tier 3 diff --git a/.claude/skills/ef-core-migration/SKILL.md b/.claude/skills/ef-core-migration/SKILL.md index 45043cc..f02e2b5 100644 --- a/.claude/skills/ef-core-migration/SKILL.md +++ b/.claude/skills/ef-core-migration/SKILL.md @@ -1,6 +1,6 @@ --- name: ef-core-migration -description: Tạo/sửa/revert EF Core 10 migration cho SOLUTION_ERP. Dùng khi thêm entity mới, thay đổi schema, rollback migration, debug DesignTimeDbContextFactory fail. Đã có 21 migration sẵn (Init → RefactorWorkflowToFlatModel). Snapshot + Designer + Migration 3-file rule bắt buộc commit đủ. +description: Tạo/sửa/revert EF Core 10 migration cho SOLUTION_ERP. Dùng khi thêm entity mới, thay đổi schema, rollback migration, debug DesignTimeDbContextFactory fail. Đã có 26 migration sẵn (Init → AddPeLevelOpinionsForV2). Snapshot + Designer + Migration 3-file rule bắt buộc commit đủ. when-to-use: - "thêm migration" - "EF Core migration" @@ -16,7 +16,7 @@ when-to-use: > **Context:** .NET 10 + EF Core 10 + SQL Server. DbContext: `ApplicationDbContext` ở `Infrastructure/Persistence/`. Startup: `SolutionErp.Api`. -## Migration history (21 migration hiện có) +## Migration history (26 migration hiện có) | # | Name | Tables added / changed | |---|---|---| @@ -41,8 +41,13 @@ when-to-use: | **19** | **`AlterPeDeptApprovalsUniqueFilteredForInnerSteps`** | **Filtered unique split: drop UNIQUE cũ Mig 16 → 2 filtered: legacy `WHERE InnerStepId IS NULL` (Stage Review/Confirm) + N-stage `WHERE InnerStepId IS NOT NULL` (per inner step). Tránh conflict 2 inner step cùng dept Stage=Confirm. Session 12.** | | **20** | **`AddContractWorkflowInnerStepsAndAlterDeptApprovalUnique`** | **N-stage workflow Contract mirror PE Mig 18+19 — GỘP 1 migration: CREATE TABLE `WorkflowStepInnerSteps` + ALTER `ContractDeptApproval.InnerStepId` + DropIndex old + Recreate filtered legacy/N-stage + 3 IX + FK. Session 13 (2026-05-07).** | | **21** | **`RefactorWorkflowToFlatModel`** | **🎯 DRASTIC REFACTOR (Session 16, 2026-05-08): bỏ phase enum legacy, dùng ChoDuyet=10 đơn nhất + currentStepIndex tracking. Workflow flat (Phòng × Cấp + Approvers). 4 ALTER (PE/Contract +CurrentWorkflowStepIndex/RejectedAtStepIndex) + 2 ALTER (WorkflowStep +DepartmentId/PositionLevel PE+Contract) + DROP TABLE × 2 (PE+Contract WorkflowStepInnerSteps Mig 18+20) + DROP COLUMN InnerStepId × 2 + DROP filtered indexes Mig 19/20 + RESTORE simple unique non-filtered × 2.** | +| **22** | **`AddApprovalWorkflowsV2`** | **🎯 V2 schema mới (Session 17, 2026-05-08) — riêng cho UAT trước khi drop legacy V1. 3 entity ApprovalWorkflow + Step + Level + enum ApplicableType (DuyetNcc=1 / DuyetNccPhuongAn=2 / Contract=3). 3 CREATE TABLE + UNIQUE (Code, Version) + FK Cascade Step→Workflow + Level→Step + FK Restrict Department + ApproverUserId. Cấu trúc: Quy trình > Bước (Phòng) > Cấp (1 NV cụ thể qua ApproverUserId, OR-of-N rows cùng Order = same Cấp). DbInitializer +menu V2 + leaf `AwV2_DuyetNcc/DuyetNccPhuongAn`.** | +| **23** | **`AddApprovalWorkflowIdToPurchaseEvaluation`** | **Pin V2 vào PE — `PE.ApprovalWorkflowId Guid?` + EF FK Restrict. Workspace Select bắt buộc workflow lúc create + Validate `ApplicableType` match `PE.Type`. Session 17.** | +| **24** | **`AddCurrentApprovalLevelOrderToPe`** | **Service V2 wire — `PE.CurrentApprovalLevelOrder int?` track Cấp đang chờ trong Step hiện tại khi pin ApprovalWorkflowId. Null khi V1 legacy hoặc terminal. Service `ApproveV2Async` group Levels by Order = Cấp (OR-of-N), match `actor.Id ∈ ApproverUserId`, advance levelOrder++ trong Step → idx++ + reset levelOrder=1 → DaDuyet. Synthetic Policy `ForV2Schema()` cho FE nextPhases. Session 17.** | +| **25** | **`AddIsUserSelectableToApprovalWorkflows`** | **ALTER `ApprovalWorkflows` +`IsUserSelectable bit NOT NULL DEFAULT 0` — admin pin/unpin workflow cho user pick lúc create phiếu (multi-select, độc lập IsActive — multiple version cùng selectable). Backfill `WHERE IsActive=1 SET 1` giữ behavior cũ (active workflows vẫn pickable). Designer +badge "Cho user chọn" + button Ghim/Bỏ ghim + mutation toggle. Workspace dropdown filter `isUserSelectable=true` only. API `PATCH /api/approval-workflows-v2/{id}/user-selectable` admin-only. Session 18 (2026-05-08).** | +| **26** | **`AddPeLevelOpinionsForV2`** | **🎯 Section 5 dynamic theo Workflow V2 (Session 19, 2026-05-09) — bảng mới `PurchaseEvaluationLevelOpinions` UNIQUE composite (PEId, ApprovalWorkflowLevelId), FK Cascade Pe + Restrict Level. Comment nvarchar(2000) + SignedAt + SignedByUserId + SignedByFullName denorm. Service `ApproveV2Async` UPSERT auto khi NV duyệt (Q1=1B sync gắn với Duyệt, KHÔNG endpoint CRUD rời). Match level theo ApproverUserId; Admin override fallback first level (FE banner "Admin duyệt thay" khi SignedByUserId !== ApproverUserId). Comment empty → "(duyệt — không ý kiến)" placeholder Q4 bonus. Phiếu V1 legacy fallback Mig 15 4 box readOnly. Mig 15 deprecated cho V2 phiếu (drop sau UAT confirm Mig 27+).** | -Total: **55 bảng** dbo + `__EFMigrationsHistory` (Mig 21 drop 2 InnerStep tables, restore Mig 16 simple unique). Xem `docs/database/schema-diagram.md` ERD đầy đủ. +Total: **59 bảng** dbo + `__EFMigrationsHistory` (Mig 22 add 3 V2 + Mig 26 add 1 PE Level Opinions). Xem `docs/database/schema-diagram.md` ERD đầy đủ + §14 ApprovalWorkflow V2 + §15 PE Level Opinions V2. ## N-stage workflow pattern (Mig 18-20 — Session 12-13) @@ -250,7 +255,7 @@ sqlcmd -S .\SQLEXPRESS -d SolutionErp -U vrapp -P -i migrate.sql ## Code pointers -- `src/Backend/SolutionErp.Infrastructure/Persistence/ApplicationDbContext.cs` — DbSet cho 55 bảng (16 migration) +- `src/Backend/SolutionErp.Infrastructure/Persistence/ApplicationDbContext.cs` — DbSet cho 59 bảng (26 migration) - `src/Backend/SolutionErp.Infrastructure/Persistence/DesignTimeDbContextFactory.cs` — EF tooling factory - `src/Backend/SolutionErp.Infrastructure/Persistence/DbInitializer.cs` — seed + warn + migrate runtime + backfill (idempotent reconcile pattern) - `src/Backend/SolutionErp.Infrastructure/Persistence/Configurations/` — IEntityTypeConfiguration per entity @@ -259,5 +264,5 @@ sqlcmd -S .\SQLEXPRESS -d SolutionErp -U vrapp -P -i migrate.sql ## Related - `docs/database/database-guide.md` — conventions + migration workflow chi tiết -- `docs/database/schema-diagram.md` — **ERD 55 bảng** + §11 PE module + §12 Budget module + §13 PEDeptOpinions + §14 DepartmentApprovals (Mig 16) +- `docs/database/schema-diagram.md` — **ERD 59 bảng** + §11 PE module + §12 Budget module + §13 PEDeptOpinions (Mig 15) + §14 ApprovalWorkflow V2 (Mig 22-25) + §15 PE Level Opinions V2 (Mig 26) - `docs/gotchas.md` #7, #17, #38 — migration pitfalls + Identity 4-field rename diff --git a/docs/database/schema-diagram.md b/docs/database/schema-diagram.md index 137c5ec..78b7ddd 100644 --- a/docs/database/schema-diagram.md +++ b/docs/database/schema-diagram.md @@ -805,12 +805,84 @@ Default behavior (sau Mig 25 backfill): active workflows tự động `IsUserSel Workspace `PeWorkspaceCreateView` query `.filter(w => w.isUserSelectable)` — chỉ hiện workflows admin đã ghim. -### Pending Session 19+: +### Pending Session 20+: -- Contract V2 wire (Mig 26): mirror PE pattern — thêm `Contract.ApprovalWorkflowId` + `CurrentApprovalLevelOrder` + `ContractWorkflowService.ApproveV2Async` -- Drop legacy V1: sau khi không còn phiếu pin `WorkflowDefinitionId` → drop `WorkflowDefinitions` + `WorkflowSteps` + `WorkflowStepApprovers` + drop deprecated columns `RejectedAtStepIndex` / `RejectedFromPhase` (Mig 27 cleanup) +- Contract V2 wire (Mig 27/28): mirror PE pattern — thêm `Contract.ApprovalWorkflowId` + `CurrentApprovalLevelOrder` + `ContractWorkflowService.ApproveV2Async` + `ContractLevelOpinions` (mirror Mig 26) +- Drop legacy V1: sau khi không còn phiếu pin `WorkflowDefinitionId` → drop `WorkflowDefinitions` + `WorkflowSteps` + `WorkflowStepApprovers` + drop deprecated columns `RejectedAtStepIndex` / `RejectedFromPhase` (Mig cleanup) +- Drop Mig 15 `PurchaseEvaluationDepartmentOpinions` cho V2 phiếu (sau khi tất cả phiếu V2 chỉ dùng Mig 26 LevelOpinions). Phiếu V1 legacy giữ Mig 15 backward compat. -## 15. Liên quan +## 15. PE Level Opinions V2 (Migration 26 — 1 bảng mới, Session 19) + +**Mục đích:** Thay thế Section 5 "Ý kiến 4 phòng ban" CỨNG (Mig 15 — PheDuyet/CCM/MuaHàng/SmPm) → động theo `ApprovalWorkflowsV2` (Mig 22-25). Mỗi (PE × Level) = 1 row sign-off với ý kiến + chữ ký NV. + +**Bối cảnh decision (đáng giữ nguyên văn cho session sau):** User UAT Section 5 cũ "có 4 box CỨNG" — không scale theo workflow V2 cấu hình động (N Bước × N Cấp × N NV). Q&A 5 câu chốt spec trước code (memory `feedback_drastic_refactor_scope` áp dụng): + +- **Q1=1B (gắn — KHÔNG rời):** Comment khi NV nhấn Duyệt qua Workflow Panel → auto sync sang OpinionBox của NV đó. Section 5 read-only summary, KHÔNG có form input rời (anti-pattern Mig 15 cũ — user phải double action: duyệt + ký). +- **Q2=2A+Admin override:** NV chính chủ duyệt (match `ApproverUserId == actor.Id`). Admin override → fallback first level group, lưu `SignedByUserId = admin.Id`. FE banner amber "⚠ Admin duyệt thay" khi `SignedByUserId !== ApproverUserId` → minh bạch ai thực sự duyệt. +- **Q3=V2 hết:** Phiếu V2 (pin `ApprovalWorkflowId`) → render dynamic. Phiếu V1 legacy (chỉ `WorkflowDefinitionId`) → fallback Mig 15 readOnly (giữ data history, KHÔNG drop). Mig 15 deprecated cho V2 phiếu, drop sau UAT confirm. +- **Q4=4C+placeholder:** Phase=DaDuyet/TuChoi → khoá hoàn toàn. Comment empty/whitespace → ghi `"(duyệt — không ý kiến)"` placeholder (vẫn tính là sign-off). +- **Q5=5A grid layout:** Group theo Step (header "Bước N — Phòng X" badge emerald + hint "(N người duyệt)") → grid-cols-2 cho N approvers. "Bước 1 phòng A có 2 NV → 2 box ngang hàng" — wrap row khi N>2. + +**Bảng `PurchaseEvaluationLevelOpinions`:** + +``` +Id uniqueidentifier PK +PurchaseEvaluationId FK Cascade → PurchaseEvaluations +ApprovalWorkflowLevelId FK Restrict → ApprovalWorkflowLevels (Mig 22) +Comment nvarchar(2000) -- ý kiến hoặc placeholder +SignedAt datetime2 NOT NULL -- luôn có khi UPSERT +SignedByUserId uniqueidentifier NOT NULL -- NV chính chủ HOẶC Admin override +SignedByFullName nvarchar(200) NOT NULL -- denorm: tránh user xóa/đổi tên ++ AuditableEntity audit fields (CreatedAt/UpdatedAt/IsDeleted/...) + +UNIQUE (PurchaseEvaluationId, ApprovalWorkflowLevelId) +INDEX (ApprovalWorkflowLevelId) +``` + +**Constraint design rationale (KHÔNG paraphrase):** + +- **UNIQUE composite (PEId, LevelId):** 1 row per (phiếu × Cấp). Latest write wins khi Service ApproveV2Async UPSERT — phiếu loop qua TraLai → resubmit → cùng NV duyệt lại = OVERWRITE row cũ (không tạo duplicate). Multi-NV cùng Cấp (OR-of-N) = nhiều LevelId distinct → mỗi NV có row riêng nếu duyệt. +- **FK Cascade Pe:** Xoá phiếu (soft-delete actually) → opinions cascade. +- **FK Restrict Level:** Admin xoá Level (qua Designer V2) bị chặn nếu opinion tồn tại — protect history sign-off. +- **`SignedByUserId` KHÔNG nav (denorm `SignedByFullName`):** User có thể bị soft-delete / đổi tên → opinion vẫn render lịch sử đúng tên tại thời điểm ký. Tránh cascade phức tạp khi xoá user. + +**Service hook pattern (ApproveV2Async):** + +```csharp +// Sau khi log approval row → UPSERT opinion cho Cấp hiện tại +var matchingLevel = pendingLevelGroup + .FirstOrDefault(l => l.ApproverUserId == actorUserId) // NV chính chủ + ?? pendingLevelGroup.First(); // Admin fallback first + +var existing = await db.PurchaseEvaluationLevelOpinions + .FirstOrDefaultAsync(o => o.PEId == pe.Id && o.LevelId == matchingLevel.Id, ct); + +var normalizedComment = string.IsNullOrWhiteSpace(comment) + ? "(duyệt — không ý kiến)" // Q4 bonus placeholder + : comment.Trim(); + +// Upsert: existing → update; null → Add new +``` + +**Reject KHÔNG sync** (Trả lại / Từ chối) — giữ snapshot opinion cũ nếu có. + +**Lưu ý anti-pattern (so với Mig 15 cũ):** + +- ❌ Mig 15 dùng endpoint POST `/pe/{id}/opinions` cho user nhập rời + 4 box CỨNG → user phải nhấn 2 action (Duyệt workflow + Ký opinion box) → UX kém + risk inconsistency +- ✅ Mig 26 dùng Service hook UPSERT khi nhấn Duyệt → 1 action user, sync auto + +→ Pattern **"derived state qua Service hook, KHÔNG endpoint CRUD riêng"** áp dụng được cho: +- Audit trail tự động khi save entity +- Notification interceptor SaveChangesInterceptor +- Code generation (gen mã HĐ khi DangDongDau) — đã có + +### Pending Session 20+: + +- Contract Section 5 V2 dynamic — mirror PE Mig 26 pattern. Tạo `ContractLevelOpinions` (Mig sau Contract V2 wire). Audit-reuse pattern memory `feedback_audit_reuse_before_clone` áp dụng. +- Drop Mig 15 cho V2 phiếu — cleanup sau UAT confirm. +- Test V2 Service hook — Domain test ApproveV2 + UPSERT opinion match logic + Admin override match firstLevel + comment empty placeholder. + +## 16. Liên quan - [`database-guide.md`](database-guide.md) — conventions + migration workflow + cheatsheet đầy đủ - [`../architecture.md`](../architecture.md) — layered architecture + data flow