diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index b58be2a..3d39325 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -1,10 +1,22 @@ # HANDOFF — Brief 5 phút cho session tiếp theo -**Last updated:** 2026-04-22 03:00 (post-Tier-3-feature-complete + versioned workflow) +**Last updated:** 2026-04-23 09:30 (post-skill-governance + cron audit định kỳ) ## TL;DR -Tier 3 ERP features xong hết (Attachment, SignalR, Form builder, PDF, Versioned workflow, Nested menu, Permission layout). Prod live 3 domain. **Còn lại chủ yếu là UAT + SMTP + rotate creds**, không còn module kỹ thuật lớn nào chưa làm. +Tier 3 ERP feature-complete (prod 3 domain live). **Skill governance setup xong** — 6 skill project-level (3 domain + 3 ops) + cron audit 1/tháng (next 2026-05-01). **Còn lại chủ yếu là UAT + SMTP + rotate creds**, không còn module kỹ thuật lớn nào chưa làm. + +## ⭐ Skills (.claude/skills/) — PHẢI dùng khi task khớp + +| Domain (3) | Ops (3) | +|---|---| +| `contract-workflow` — state machine + versioned WF | `dependency-audit-erp` — npm/dotnet CVE scan | +| `form-engine` — render docx/xlsx + PDF | `ef-core-migration` — EF migration + 3-file rule | +| `permission-matrix` — role × menu × CRUD | `iis-deploy-runbook` — 3 site IIS + win-acme + runner | + +**Audit cron:** `0 9 1 * *` (9:00 AM ngày 1 mỗi tháng). Workflow: `docs/rules.md §9.4`. Lần kế: **2026-05-01**. + +**Quy tắc:** KHÔNG bulk-clone repo skill 3rd party. Chỉ skill PROJECT-SPECIFIC. Đầy đủ: `docs/rules.md §9`. ## Ở đâu rồi? @@ -18,6 +30,7 @@ Tier 3 ERP features xong hết (Attachment, SignalR, Form builder, PDF, Versione | 5 Prep + 5.1 Security + Users Mgmt | ✅ Done | | **5 Deploy prod** (3 domain HTTPS live) | ✅ Done | | **Tier 3 (Attach + Realtime + Form builder + PDF + Versioned WF + Nested menu + Permission 3-panel)** | ✅ Done | +| **Skill governance** (6 skill project-level + audit cron 1/tháng) | ✅ Done | | 6+ Post-launch (E-signature, Bravo/SAP, Mobile, AI) | 📝 Future | ## Run nhanh @@ -251,11 +264,13 @@ SOLUTION_ERP/ ``` HEAD → main -91b2da1 — PermissionsPage 3-panel layout (LATEST) -f216169 — Admin Workflows tabs → sidebar menu items +b904a25 — Skill: governance + audit định kỳ hàng tháng (LATEST) +661f859 — Skill: thêm 3 skill ops project-specific +fbca832 — Docs: chốt session Tier 3 feature-complete + versioned workflow +91b2da1 — FE-Admin: PermissionsPage 3-panel layout +f216169 — FE-Admin+Domain+Infra+App: Workflows tab → sidebar menu items 355bbe3 — Fix Dialog size TS (xl → lg) e7e5f2d — Versioned workflow entities + migration + designer -4 session trước đó nằm trong STATUS table Branch: main (tracking origin/main) Remote: https://git.baocaogiaoduc.vn/vietreport-admin/solution-erp.git diff --git a/docs/STATUS.md b/docs/STATUS.md index 9d043bd..23dc0ae 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -2,9 +2,9 @@ > **Update rule:** trước khi bắt đầu 1 task → ghi row vào `🔥 In Progress`. Xong → chuyển sang `✅ Recently Done`. -**Last updated:** 2026-04-22 03:00 (post-Tier-3-feature-complete + versioned workflow) +**Last updated:** 2026-04-23 09:30 (post-skill-governance + cron audit định kỳ) -## 📍 Phase hiện tại: **Tier 3 feature-complete** — Prod live, tất cả module lớn xong. Còn: UAT thật + Email outbox (chờ SMTP) + rotate creds. +## 📍 Phase hiện tại: **Tier 3 feature-complete + skill governance** — Prod live, 6 skill project-level + audit cron 1/tháng. Còn: UAT thật + Email outbox (chờ SMTP) + rotate creds. ### 🌐 Production URLs @@ -16,12 +16,14 @@ ## 🔥 In Progress -_(không có — Tier 3 đóng gói xong, chờ UAT để quyết Tier 4)_ +_(không có — Tier 3 + skill governance đóng gói xong, chờ UAT + chờ cron audit fire 2026-05-01)_ ## ✅ Recently Done (newest on top) | Ngày | Ai | Task | Commit | |---|---|---|---| +| 2026-04-23 | Claude | **Skill governance + audit định kỳ** — `docs/rules.md §9` mới (6 skill bảng, nguyên tắc tạo project-specific, format SKILL.md bắt buộc, workflow audit 7 bước, 4 anti-patterns). Cron task `solution-erp-skill-audit-monthly` fire 9:00 AM ngày 1 mỗi tháng (next 2026-05-01) — self-contained prompt cold-start, auto-refresh stale nhỏ + đề xuất add/archive cho human approve, log vào `docs/changelog/skill-audit-{YYYY-MM}.md`, ABORT nếu repo dirty. Touch-points: CLAUDE.md callout + HANDOFF A1 + migration-todos checkbox + skill scope commit | `b904a25` | +| 2026-04-23 | Claude | **3 skill ops project-specific** — Khảo sát alirezarezvani/claude-skills, quyết định KHÔNG bulk-clone (skill global đã cover phần generic, repo còn lại doc-dump không có when-to-use). Viết 3 skill mới encode SOLUTION_ERP-only: `dependency-audit-erp` (npm/dotnet CVE scan respect MediatR 12.4.1 + Swashbuckle 6.9.0 pin), `ef-core-migration` (8 migration history + 3-file rule + DesignTimeDbContextFactory + 6 pitfalls cụ thể), `iis-deploy-runbook` (3 IIS site + win-acme + NSSM gitea-runner + LibreOffice + debug playbook 500/502/SignalR). Total skill project-level = 6 (3 domain + 3 ops) | `661f859` | | 2026-04-22 | Claude | **PermissionsPage 3-panel layout** — Grid `lg:grid-cols-[280px_1fr_300px]`: Panel 1 Role list click-to-select (active ring-brand), Panel 2 Menu×CRUD matrix sticky thead + search + column bulk-toggle + brand-tinted hover, Panel 3 Granted progress bar + CRUD breakdown color badges (slate/emerald/amber/red) + Tip | `91b2da1` | | 2026-04-22 | Claude | **Admin Workflows tabs → sidebar menu items** — Seed 7 `Wf_` leaf dưới group `Workflows`. Layout resolvePath `Wf_` → `/system/workflows/`. WorkflowsPage bỏ tab bar, URL param drives type selection. Landing 7-card grid khi click top-level `Quy trình HĐ`. Inheritance: `Workflows.Read` perm → tất cả 7 leaves auto-visible. | `f216169` | | 2026-04-22 | Claude | **Versioned workflow per ContractType** — 3 entity mới: WorkflowDefinition (Code+Version+IsActive+ContractType), WorkflowStep (Order+Phase+Name+SlaDays), WorkflowStepApprover (Role/User + AssignmentValue). Contract.WorkflowDefinitionId nullable FK pin tại create. Migration `AddVersionedWorkflows`. Seed v01 per 7 ContractType. `WorkflowPolicyRegistry.FromDefinition()` build runtime policy từ DB. ContractWorkflowService load pinned definition. Admin `/system/workflows/:typeCode` Designer modal (create new version, clone, add/remove step, +Role/+User approvers). POST /api/workflows auto-increment Version + deactivate old. Invariant: HĐ cũ pin v01 giữ nguyên khi v02 active. E2E verified: QT-MB-v02 active, HĐ cũ vẫn chạy v01. | `e7e5f2d` + `355bbe3` | @@ -52,7 +54,7 @@ _(không có — Tier 3 đóng gói xong, chờ UAT để quyết Tier 4)_ | 2026-04-21 | Claude | **Phase 1 foundation** + Docs addition | `702411f` + `49a5f57` | | 2026-04-21 | Claude | **Phase 0** | `25dad7f` | -Session logs: [P0](changelog/sessions/2026-04-21-1045-phase0-scaffold.md) · [P1f](changelog/sessions/2026-04-21-1100-phase1-foundation.md) · [P1.2](changelog/sessions/2026-04-21-1130-phase1-cruds-permission.md) · [P2](changelog/sessions/2026-04-21-1200-phase2-form-engine.md) · [P3](changelog/sessions/2026-04-21-1330-phase3-workflow.md) · [P4](changelog/sessions/2026-04-21-1430-phase4-report.md) · [P5prep](changelog/sessions/2026-04-21-1530-phase5-prep.md) · [**Tier 3**](changelog/sessions/2026-04-22-0300-tier3-feature-complete.md) +Session logs: [P0](changelog/sessions/2026-04-21-1045-phase0-scaffold.md) · [P1f](changelog/sessions/2026-04-21-1100-phase1-foundation.md) · [P1.2](changelog/sessions/2026-04-21-1130-phase1-cruds-permission.md) · [P2](changelog/sessions/2026-04-21-1200-phase2-form-engine.md) · [P3](changelog/sessions/2026-04-21-1330-phase3-workflow.md) · [P4](changelog/sessions/2026-04-21-1430-phase4-report.md) · [P5prep](changelog/sessions/2026-04-21-1530-phase5-prep.md) · [Tier 3](changelog/sessions/2026-04-22-0300-tier3-feature-complete.md) · [**Skill gov**](changelog/sessions/2026-04-23-0900-skill-governance.md) **Docs entry points:** @@ -60,7 +62,8 @@ Session logs: [P0](changelog/sessions/2026-04-21-1045-phase0-scaffold.md) · [P1 - [`workflow-contract.md`](workflow-contract.md) · [`forms-spec.md`](forms-spec.md) - [`database/database-guide.md`](database/database-guide.md) · [`database/schema-diagram.md`](database/schema-diagram.md) - [`flows/`](flows/) (7 file) · [`guides/`](guides/) (4 file) · [`gotchas.md`](gotchas.md) -- [`changelog/migration-todos.md`](changelog/migration-todos.md) · [`changelog/sessions/`](changelog/sessions/) (8 file) +- [`changelog/migration-todos.md`](changelog/migration-todos.md) · [`changelog/sessions/`](changelog/sessions/) (12 file) +- [`.claude/skills/README.md`](../.claude/skills/README.md) — 6 skill (3 domain + 3 ops) · audit định kỳ 1/tháng (cron `solution-erp-skill-audit-monthly`) ## 🎯 Next up diff --git a/docs/changelog/sessions/2026-04-23-0900-skill-governance.md b/docs/changelog/sessions/2026-04-23-0900-skill-governance.md new file mode 100644 index 0000000..709e2e6 --- /dev/null +++ b/docs/changelog/sessions/2026-04-23-0900-skill-governance.md @@ -0,0 +1,136 @@ +# Session 2026-04-23 ~09:00 — Skill governance + 3 ops skill mới + +**Focus:** Khảo sát repo skill 3rd party (alirezarezvani/claude-skills), +quyết định KHÔNG bulk-clone, viết 3 skill PROJECT-SPECIFIC bổ sung, +setup quy trình audit định kỳ hàng tháng (rules + cron tự động). + +## Outcomes + +### A. Khảo sát + quyết định ✓ + +- Fetch repo `alirezarezvani/claude-skills` qua WebFetch +- 10 nhóm skill (engineering / marketing / product / agents / ...) +- Phát hiện: **phần lớn skill đã có ở user-level rồi** (`code-reviewer`, + `sql-database-assistant`, `focused-fix`, `senior-frontend`, + `mcp-builder`, `webapp-testing`, `review`, `security-review`, ...) +- Phần còn lại: doc-dump generic, **không có YAML `when-to-use`**, + reference Python script aspirational +- **Quyết định: KHÔNG bulk-import**. Lý do: + - Trùng skill global đã có → bloat trigger + - Generic không match SOLUTION_ERP-specific (path, version pin, gotcha #) + - Vô YAML triggers → trigger sai trong session khác +- **Hành động thay thế:** viết 3 skill PROJECT-SPECIFIC encode + kiến thức SOLUTION_ERP-only + +### B. 3 skill ops mới ✓ + +| Skill | Path | Encode kiến thức gì | +|---|---|---| +| `dependency-audit-erp` | `.claude/skills/dependency-audit-erp/SKILL.md` | dotnet/npm scan + pin constraint MediatR 12.4.1 / Swashbuckle 6.9.0 / Node 20 / TypeScript 6 erasable, dẫn chiếu gotchas, output template, CI integration TODO | +| `ef-core-migration` | `.claude/skills/ef-core-migration/SKILL.md` | 8 migration history (Init → AddVersionedWorkflows), DesignTimeDbContextFactory pattern, 3-file rule, 6 pitfalls cụ thể (cascade vs restrict cho `Contracts.WorkflowDefinitionId` quan trọng), workflow add entity end-to-end, prod apply via idempotent script | +| `iis-deploy-runbook` | `.claude/skills/iis-deploy-runbook/SKILL.md` | 3 IIS site topology, win-acme + NSSM gitea-runner shared VIETREPORT, LibreOffice 25.8.6 headless, debug playbook 500/502/SignalR/login, deploy steps + manual emergency, rotate creds + backup commands, dẫn chiếu gotcha #25/26/28/29 | + +Tất cả đều có YAML `when-to-use` triggers (mix tiếng Việt + Anh) để +auto-trigger semantic match. + +Sau update: **6 skill project-level** (3 domain + 3 ops). + +### C. Skill governance — `docs/rules.md §9` mới ✓ + +Section đầy đủ về Skills (push "Liên quan" từ §9 → §10): + +- **§9.1** — Bảng 6 skill chia 2 nhóm với trigger phrase +- **§9.2** — Nguyên tắc tạo skill mới: project-specific (KHÔNG clone + generic), encode SOLUTION_ERP-only, YAML `when-to-use` bắt buộc, + Vietnamese-first +- **§9.3** — Format `SKILL.md` template chuẩn +- **§9.4** — **Workflow audit định kỳ 7 bước:** + 1. Đọc `.claude/skills/README.md` + 2. Cross-check `STATUS.md` Recently Done — feature mới chưa cover + 3. Cross-check `gotchas.md` — gotcha mới có nên gom thành skill + 4. Cross-check `migration-todos.md` Next up — task lớn cần skill + 5. Check repo nguồn 3rd party có skill mới + 6. Đánh giá staleness (path, version, trigger còn đúng) + 7. Action: refresh / add / archive + commit + log +- **§9.5** — 4 anti-patterns (KHÔNG bulk-clone / không tạo skill chỉ + để có / không copy docs / không bỏ qua skill khi task khớp) + +### D. Cadence — Cron tự động hàng tháng ✓ + +``` +Task ID: solution-erp-skill-audit-monthly +Schedule: 0 9 1 * * (9:00 AM ngày 1 mỗi tháng, local time) +Next run: Fri, May 1 2026 +Notify: có +``` + +Self-contained prompt cold-start (không cần context session hiện tại). +Bao gồm: +- Cross-check 7 bước theo §9.4 +- Auto-refresh stale skill nhỏ (path, version, trigger) +- CHỈ ĐỀ XUẤT add/archive (cần human approve) +- Log vào `docs/changelog/skill-audit-{YYYY-MM}.md` +- Commit `[CLAUDE] Skill: audit định kỳ YYYY-MM` +- ABORT nếu repo dirty + +### E. Touch-points cho session sau ✓ + +| File | Update | +|---|---| +| `CLAUDE.md` (root) | Block "🛠️ Skills" callout 6 skill + audit cadence + commit scope thêm `Skill` | +| `docs/CLAUDE.md` | Project layout — skill count 6 | +| `docs/HANDOFF.md` | Section A1 — định kỳ audit, lần kế tiếp 2026-05-01 | +| `docs/changelog/migration-todos.md` | Section "Skill governance (recurring)" với checkbox audit hàng tháng | +| `docs/rules.md` | §9 đầy đủ workflow + cadence + anti-patterns; §10 Liên quan thêm link skill index | +| `.claude/skills/README.md` | Bảng 6 skill chia 2 nhóm + nguyên tắc design | + +Session mới đọc 4 file đầu (`STATUS.md` / `PROJECT-MAP.md` / +`migration-todos.md` / `workflow-contract.md`) sẽ thấy ngay quy tắc +skills + audit cadence — không cần ai nhắc. + +## Commits (chronological) + +``` +661f859 — Skill: thêm 3 skill ops project-specific (dependency-audit-erp, + ef-core-migration, iis-deploy-runbook) +b904a25 — Skill: governance + audit định kỳ hàng tháng + (rules §9 + CLAUDE.md callout + HANDOFF + migration-todos) +``` + +## Key architectural decisions + +1. **NO bulk-clone repo skill 3rd party** — phần lớn doc-dump generic, + không có `when-to-use`, dễ trigger nhầm. Chỉ extract concept rồi viết + project-specific. +2. **Skill = project-encoded knowledge** — encode commit convention, + path, version pin, gotcha #. Generic skill global cover phần phổ + thông; project skill cover phần chỉ-có-ở-project. +3. **Audit = data-driven** — cross-check STATUS / gotchas / migration- + todos để biết feature nào CHƯA có skill cover, không phán đoán cảm + tính. +4. **Cron self-contained prompt** — cold-start không cần session + context, log vào file để user xem sau, ABORT nếu repo dirty (an toàn). +5. **Auto-refresh nhỏ, đề xuất add/archive** — refresh path/version + safe vì không thay đổi semantic; add/archive cần human approve vì + ảnh hưởng trigger map. + +## Skill list (sau audit setup này — 6 skill) + +**Domain (3 — logic nghiệp vụ):** +- `contract-workflow` — state machine 9 phase + versioned WF + role guard +- `form-engine` — render template docx/xlsx + FieldSpec + DynamicForm + PDF +- `permission-matrix` — role × menu × CRUD + inherit Contracts/Workflows + +**Ops (3 — devops + security + schema):** +- `dependency-audit-erp` — npm/dotnet CVE scan respect pin constraint +- `ef-core-migration` — EF Core 10 + 8 migration history + 3-file rule +- `iis-deploy-runbook` — 3 IIS site + win-acme + gitea-runner + debug playbook + +## Next session priority + +1. **Wait audit fire 2026-05-01** — xem cron có chạy đúng không, log có sạch không +2. UAT 2-3 user thật (vẫn pending từ session trước) +3. Email outbox (chờ SMTP) +4. Roles CRUD (optional) +5. User-kind approver runtime guard +6. Rotate creds + SQL backup schedule