From 7dc0233f08ae9338731bd21d7370a7f2ea377289 Mon Sep 17 00:00:00 2001 From: pqhuy1987 Date: Wed, 6 May 2026 15:53:51 +0700 Subject: [PATCH] =?UTF-8?q?[CLAUDE]=20Docs+Skill:=20audit=20=C4=91?= =?UTF-8?q?=E1=BB=8Bnh=20k=E1=BB=B3=202026-05=20=E2=80=94=206=20file=20pat?= =?UTF-8?q?ch=20+=201=20log=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Combined audit (skill staleness + doc drift) theo §6.4 + §9.4. Cron 2026-05-01 trễ 4 ngày (cron empty), chạy manual 2026-05-04 sau Session 9 close Chunk E-bis. Drift patched (Phase 1 — count cross-check): - docs/CLAUDE.md:70 52 bảng → 55 bảng (+§14 DepartmentApprovals Mig 16) - docs/rules.md:368 Phase 8 active — 77 test → Phase 9 — 83 test - docs/architecture.md:329, 365 77 test → 83 test (2 chỗ) - .claude/skills/ef-core-migration/SKILL.md:52 77 test → 83 test + ghi 6 PE 2-stage S9 - .claude/skills/dependency-audit-erp/SKILL.md:153 26+ bẫy → 41 bẫy Skill content patch (Phase 2 — staleness): - contract-workflow: thêm "Phase 9 cross-ref (Mig 16)" block + section "Phase 9 done" (2-stage dept approval + smart reject + lock edit + CanBypassReview) → KHÔNG tạo skill 2-stage riêng (§9.5 anti-pattern "viết skill chỉ để có thêm") KEEP per §6.5 (không cắt narrative): - docs/rules.md:328 "52 bảng" example minh họa rule §6.5 - docs/changelog/migration-todos.md:152, 196 historical session record - 9 session log mention 77/52 — snapshot lịch sử Total patches: 6 file ~+30 / ~12 lines, KHÔNG rewrite, đáp ứng 3 câu validation §6.5. Audit log: docs/changelog/skill-audit-2026-05.md (1 page max per cadence). Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/skills/contract-workflow/SKILL.md | 21 ++++ .claude/skills/dependency-audit-erp/SKILL.md | 2 +- .claude/skills/ef-core-migration/SKILL.md | 2 +- docs/CLAUDE.md | 2 +- docs/architecture.md | 4 +- docs/changelog/skill-audit-2026-05.md | 102 +++++++++++++++++++ docs/rules.md | 2 +- 7 files changed, 129 insertions(+), 6 deletions(-) create mode 100644 docs/changelog/skill-audit-2026-05.md diff --git a/.claude/skills/contract-workflow/SKILL.md b/.claude/skills/contract-workflow/SKILL.md index 3e0fb5a..0e2661a 100644 --- a/.claude/skills/contract-workflow/SKILL.md +++ b/.claude/skills/contract-workflow/SKILL.md @@ -26,6 +26,20 @@ when-to-use: > - `Domain/PurchaseEvaluations/PurchaseEvaluationPolicy.cs` > - `Infrastructure/Services/PurchaseEvaluationWorkflowService.cs` > - Kế thừa HĐ từ phiếu `DaDuyet` qua `CreateContractFromEvaluationCommand` — pin `Contract.WorkflowDefinitionId` theo ContractType user chọn. +> +> **Phase 9 cross-ref (Migration 16 — Session 8/9):** 3 mở rộng cross-cut 3 module +> (Contract + PurchaseEvaluation + Budget): +> - **2-stage dept approval** (đóng bug anh Kiệt FDC): NV Review → TPB Confirm. +> `*DepartmentApprovals` table UNIQUE (TargetId, Phase, Dept, Stage). Service +> inject UserManager → check role DeptManager / CanBypassReview → upsert row + +> block transition cho đến khi Stage=Confirm. **6 test PE 2-stage** ở +> `tests/.../Services/PeTwoStageApprovalTests.cs` (`IdentityFixture` reusable). +> - **Smart reject + Resume jump-back**: `Reject` → set `RejectedFromPhase` snapshot +> + force `targetPhase=DangSoanThao`. `Resume` (Drafter trình lại từ DangSoanThao +> với RejectedFromPhase != null) → jump straight tới phase đã reject, bypass +> policy guard. Áp dụng 3 module. +> - **Lock edit guards** 17 handler: Phase != DangSoanThao → throw 409 ConflictException. +> KHÔNG lock Comment + Attachment + Opinion (workflow design intent). ## Domain entities (implemented) @@ -293,6 +307,13 @@ POST /api/contracts/{id}/transitions { targetPhase: 3, decision: 1, comment: ".. - **WorkflowDefinition cascade delete** → NÊN restrict FK. Nếu cascade sẽ xóa Contract cũ → data loss. Đã fix trong migration. - **User-kind approver không enforce runtime** — designer cho chọn nhưng guard v1 chỉ check Role. Iter 2 cần wire `step.Approvers.Where(a => a.Kind == User)` vào check. +## Phase 9 done (Mig 16 — Session 8/9) + +- [x] **2-stage dept approval** xuyên 3 module — NV Review BLOCK / TPB Confirm ALLOW +- [x] **Smart reject + Resume jump-back** — RejectedFromPhase snapshot + bypass policy +- [x] **Lock edit guards** 17 handler khi Phase != DangSoanThao +- [x] **CanBypassReview toggle** per User — admin UI + audit IsBypassed=true + ## Tier 4+ (còn thiếu / future) - [ ] Warning notification 20% SLA (`SlaWarningSent` flag đã có) diff --git a/.claude/skills/dependency-audit-erp/SKILL.md b/.claude/skills/dependency-audit-erp/SKILL.md index 858c826..7e31ae0 100644 --- a/.claude/skills/dependency-audit-erp/SKILL.md +++ b/.claude/skills/dependency-audit-erp/SKILL.md @@ -150,6 +150,6 @@ Lưu vào `docs/changelog/deps-audit-{YYYY-MM-DD}.md` nếu có action. ## Related -- `docs/gotchas.md` — 26+ bẫy package compat đã gặp +- `docs/gotchas.md` — 41 bẫy package compat / CI / IIS / Identity đã gặp - `docs/changelog/migration-todos.md` Phase 5.1 — checklist deps scan CI - `SolutionErp.slnx` + `global.json` — .NET version pin diff --git a/.claude/skills/ef-core-migration/SKILL.md b/.claude/skills/ef-core-migration/SKILL.md index 9b98765..c5c5496 100644 --- a/.claude/skills/ef-core-migration/SKILL.md +++ b/.claude/skills/ef-core-migration/SKILL.md @@ -49,7 +49,7 @@ Total: **55 bảng** dbo + `__EFMigrationsHistory`. Xem `docs/database/schema-di **Phase 8 update (2026-04-29 Session 5):** - Migration 15 `AddPurchaseEvaluationDepartmentOpinions` — 1 bảng riêng (UNIQUE PEId+Kind), max 4 row mỗi phiếu cho 4 phòng ban (Phê duyệt/Ccm/MuaHang/SmPm). UPDATE in-place khi user đổi ý, audit qua Changelog. -- Tests Phase 1-2-3mini live: `tests/SolutionErp.Domain.Tests/` (54 test policy state machine) + `tests/SolutionErp.Infrastructure.Tests/` (17 test code generator + 6 test PE WF versioning). **Total 77 test pass / ~3s**. CI fail → no deploy. +- Tests Phase 1-2-3mini-2stage live: `tests/SolutionErp.Domain.Tests/` (54 test policy state machine) + `tests/SolutionErp.Infrastructure.Tests/` (17 test code generator + 6 test PE WF versioning + 6 test PE 2-stage approval Session 9). **Total 83 test pass / ~3s**. CI fail → no deploy. - CI optimize 3 fix (29/04): - Manual checkout bypass github.com (gotcha #39) — fix TCP timeout 21s - Path filter docs-only skip (gotcha #41) — commit MD-only KHÔNG trigger CI diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index 326b30d..3889ca1 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -67,7 +67,7 @@ SOLUTION_ERP/ │ ├── workflow-contract.md 9 phase HĐ + role matrix │ ├── database/ │ │ ├── database-guide.md conventions + migration workflow -│ │ └── schema-diagram.md ERD 52 bảng (+§11 PE +§12 Budget +§13 PEDeptOpinions) +│ │ └── schema-diagram.md ERD 55 bảng (+§11 PE +§12 Budget +§13 PEDeptOpinions +§14 DepartmentApprovals Mig 16) │ ├── flows/ 6 sequence diagram (auth/permission/contract/form/sla + PE ref architecture) │ ├── guides/ setup, cicd, deploy, runbook, security │ ├── changelog/ diff --git a/docs/architecture.md b/docs/architecture.md index eafa903..b9eb5c4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -326,7 +326,7 @@ Test pyramid bottom-heavy, **không E2E** (brittle, maintenance cao cho solo dev ├──────────────────────────────────┤ ✅ Done Phase 1 — 54 test │ Domain Policy (pure functions) │ State machine + role transition + Registry mapping └──────────────────────────────────┘ - Total: 77 test pass / ~3s + Total: 83 test pass / ~3s ``` **Stack:** @@ -362,7 +362,7 @@ Test pyramid bottom-heavy, **không E2E** (brittle, maintenance cao cho solo dev - CQRS handler có guard → 1 test mỗi guard branch - Bug found in production → 1 regression test added before merge -Detail run: `dotnet test SolutionErp.slnx` chạy cả **77 test ~3s**. +Detail run: `dotnet test SolutionErp.slnx` chạy cả **83 test ~3s**. ### CI/CD optimization (29/04) diff --git a/docs/changelog/skill-audit-2026-05.md b/docs/changelog/skill-audit-2026-05.md new file mode 100644 index 0000000..235fe34 --- /dev/null +++ b/docs/changelog/skill-audit-2026-05.md @@ -0,0 +1,102 @@ +# Skill + Doc Audit — 2026-05 + +> **Cadence:** Cron `solution-erp-skill-audit-monthly` 9:00 ngày 1 mỗi tháng. +> **Lần này:** chạy manual 2026-05-04 (trễ 4 ngày so với schedule 2026-05-01 vì cron empty `No scheduled jobs` — recreate khi user trigger). +> **Workflow:** combined audit theo `docs/rules.md §6.4` (doc drift) + `§9.4` (skill staleness). + +## Phase 1 — Count cross-check + +| Item | Claim trong MD | Actual | Drift? | +|---|---:|---:|:---:| +| Tests (`dotnet test SolutionErp.slnx`) | 83 | 83 (54 Domain + 29 Infra) | ✅ | +| Migrations (Glob `*.cs` ÷ 2) | 16 | 16 (32 file ÷ 2 + Snapshot) | ✅ | +| Gotchas (`### \d+\.` count) | 41 | 41 | ✅ | +| Skills (Ls `.claude/skills/`) | 6 | 6 | ✅ | +| STATUS Recently Done rows | < 30 | 12 | ✅ chưa cần archive | + +### Drift patches applied + +| File:line | Stale | Patch | +|---|---|---| +| `docs/CLAUDE.md:70` | `ERD 52 bảng` | → `55 bảng (+§14 DepartmentApprovals Mig 16)` | +| `docs/rules.md:368` | `Phase 8 active — 77 test` | → `Phase 9 active — 83 test` | +| `docs/architecture.md:329` | `Total: 77 test pass` | → `83 test pass` | +| `docs/architecture.md:365` | `cả 77 test ~3s` | → `cả 83 test ~3s` | +| `.claude/skills/ef-core-migration/SKILL.md:52` | `Total 77 test pass` | → `Total 83 test pass` (ghi rõ +6 PE 2-stage S9) | + +### KEEP (rule §6.5 không cắt narrative) + +- `docs/rules.md:328` "52 bảng canonical" — example minh họa rule §6.5, KHÔNG drift +- `docs/changelog/migration-todos.md:152, 196` "77 test" — historical session record (Phase 8 Tests / Session 8 verify), session log historical = giữ nguyên văn +- `docs/changelog/sessions/*.md` — 9 file mention "77 test" hoặc "52 bảng" — TẤT CẢ snapshot lịch sử, KEEP + +## Phase 2 — Skill staleness (per §9.4) + +| Skill | Status hiện tại | Drift findings | Action | +|---|---|---|---| +| `contract-workflow` | Tier 3 + Phase 6 cross-ref PE | KHÔNG mention 2-stage dept approval (Mig 16 đóng bug anh Kiệt) ở Tier 4+ pending. Lock edit + smart reject cũng chưa nhắc. | ✅ Patch — thêm "Phase 9 cross-ref" block + section "Phase 9 done" trước Tier 4+ | +| `permission-matrix` | post Session 6 — 60 menu | Vẫn đúng (chưa thêm menu mới S8/S9). Header "post Session 6" có thể fresh nhưng không critical. | ⏸ optional, skip | +| `form-engine` | post Session 6 — Tier 3 FEATURE-COMPLETE | Vẫn đúng. PE PDF export pending nhắc đúng (Phase 9 carry over). | — no patch | +| `dependency-audit-erp` | Phase 5.1 backlog | Line 153 "26+ bẫy" stale | ✅ Patch → "41 bẫy" | +| `ef-core-migration` | 16 migration → 55 bảng | "Total 77 test pass" line 52 (đã session 8 ending refresh count migration nhưng quên test) | ✅ Patch (cùng Phase 1) | +| `iis-deploy-runbook` | Updated G-084 IPv4/IPv6 | Topology + 3 site + win-acme + NSSM runner vẫn đúng | — no patch | + +## Phase 3 — Feature gap audit + +**Feature mới Session 8/9 nào chưa có skill cover?** + +| Feature S8/S9 | Skill cover? | Decision | +|---|---|---| +| 2-stage dept approval Migration 16 (cross 3 module) | ❌ chưa | Cross-ref vào `contract-workflow` (rule §9.5 anti-pattern "viết skill chỉ để có thêm" — pattern đủ generic, ghi đủ Domain entity + service + 6 test reusable) | +| Smart reject + Resume jump-back | ❌ chưa | Cross-ref `contract-workflow` Phase 9 done section | +| Lock edit guards 17 handler | ❌ chưa | Cross-ref `contract-workflow` Phase 9 done | +| `IdentityFixture` test pattern (Session 9 E6) | — | Không cần skill — test rule đã ở `rules.md §7`. Pattern reusable trực tiếp từ `tests/Common/IdentityFixture.cs`. | +| User.CanBypassReview toggle UI | — | Minor admin UX, không xứng skill | + +**KHÔNG tạo skill mới.** Tổng số skill giữ **6** (3 domain + 3 ops). + +**Threshold check:** +- gotchas.md +0 gotcha mới session 9 → KHÔNG đạt threshold §9.4 "+5 gotcha mới → audit cluster" +- Phase mới (9) đóng → đã audit +- Skill drift > 30%? KHÔNG (chỉ 1 line stale ở dependency-audit-erp + 1 block cross-ref ở contract-workflow) + +## Phase 4 — Patches applied (Edit, KHÔNG rewrite) + +5 file patched (xem Phase 1 + Phase 2 tables above): +- `docs/CLAUDE.md` — count 52→55 bảng + section §14 DepartmentApprovals +- `docs/rules.md` — Phase header 8→9 + count 77→83 +- `docs/architecture.md` — count 77→83 (2 chỗ) +- `.claude/skills/ef-core-migration/SKILL.md` — count 77→83 + ghi 6 PE 2-stage +- `.claude/skills/contract-workflow/SKILL.md` — Phase 9 cross-ref block + Phase 9 done section +- `.claude/skills/dependency-audit-erp/SKILL.md` — 26+→41 bẫy + +**Tổng diff:** ~30 dòng thêm + ~12 dòng patch. KHÔNG rewrite toàn bộ. KHÔNG cắt narrative. + +## Phase 5 — Validation per §6.5 + +3 câu sau consolidate (per rule §6.5): + +1. **Agent mới đọc 6 tháng sau có biết "tại sao chọn approach này" không?** + ✅ Có — narrative Phase 6 cross-ref + Phase 9 cross-ref + Tier 3/4 status preserved. + +2. **Có còn cảm giác "kể chuyện" tích lũy không, hay chỉ là instructions khô?** + ✅ Có — Phase 9 cross-ref block trong contract-workflow kể đủ context "đóng bug anh Kiệt" + 3 mở rộng + reusable test pattern. + +3. **Gotcha context vẫn còn ý nghĩa khi đọc rời rạc không?** + ✅ Có — gotcha #1-#41 narrative giữ nguyên. dependency-audit-erp chỉ patch số 26→41, narrative pin constraints + workflow vẫn đầy đủ. + +## Đề xuất next audit + +- **Cron 2026-06-01** — recreate `solution-erp-skill-audit-monthly` khi user trigger / cuối session 9. +- **Threshold trigger sớm** nếu: + - +5 gotcha mới (cluster có thể gom thành skill mới) + - Phase 10 đóng (Post-launch — E-signature / Bravo / Mobile / AI OCR — cần skill mới) + - Skill drift > 30% (count broken / path broken / mention phase cũ) + +## Stats + +- Total skill: 6 (no add/archive) +- Files patched: 6 (5 docs + 1 SKILL.md cross-skill) +- Lines diff: ~+30 / ~12 patch +- Effort: ~30 phút (thực thi qua Edit, không rewrite) +- Audit log: 1 page (file này, theo cadence rule) diff --git a/docs/rules.md b/docs/rules.md index b3c7200..21c2ca7 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -365,7 +365,7 @@ Co-Authored-By: Claude Opus 4.7 (1M context) - User nói "consolidate", "compact", "gọn lại MD", "rõ ràng MD" - Cuối phase đóng (>1 tháng) khi compact STATUS/HANDOFF/migration-todos -## 7. Testing (Phase 8 active — 77 test pass + CI gate live) +## 7. Testing (Phase 9 active — 83 test pass + CI gate live) ### Stack đã apply