From 2675a3a67462180cd7b6fd8abf82723ea13d7662 Mon Sep 17 00:00:00 2001 From: pqhuy1987 Date: Thu, 30 Apr 2026 01:56:29 +0700 Subject: [PATCH] =?UTF-8?q?[CLAUDE]=20Docs:=20rule=20=C2=A76.5=20consolida?= =?UTF-8?q?te=20KEEP=20vs=20CUT=20+=20restore=20narrative=20migration-todo?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bài học session 6: compact -288 dòng nhanh nhưng paraphrase + collapse mất narrative tích lũy qua sessions. User feedback: "viết MD gọn lại tý là mất mẹ luôn tính cách cũ". Docs đọc 6 tháng sau như machine output. Changes: 1. docs/rules.md §6.5 mới — Consolidate MD đúng cách (KEEP vs CUT): - KEEP cấm cắt: narrative, rationale, gotcha context, anecdote, "decision why" - CUT được: duplicate cross-ref, list>30 row archive, phase>1 tháng collapse - CẤM: paraphrase, summary đoạn có narrative, "đẹp hóa" bằng cắt - Decision tree + Validation 3 câu sau consolidate 2. docs/changelog/migration-todos.md restore Phase 6-7 nguyên văn từ b874743: - Phase 6 iter 1 (10 task chi tiết: Migration 12, Domain 2 enum, Application CQRS ~900 LOC, PurchaseEvaluationWorkflowService, Controller 17 endpoint, FE 2 app, Kế thừa HĐ guard, Migration 13 atomic seq, Demo PE seed) - Phase 6 iter 2 (8 task UX polish: rename Phương Án→Giải pháp, menu inheritance #35, accordion mutex, queryMatches #34, flat layout, per-NCC attachment, readOnly mode, email rebrand #38) - Domain rebrand 4 task chi tiết (gotcha #30 ASCII-only, 18 file repo, CI/CD auto rebuild, "Old fallback chưa remove" rationale) - Phase 7 PE feature gap A/B/C/D/E section đầy đủ: A. 3 task PE feature gap với file path + Option A/B reasoning B. 4 optional polish carry over Phase 9 C. 6 ops task carry over Phase 9 hard blockers D. Budget BE 7 task chi tiết (Migration 14, ~340 LOC, 11 endpoint, 14 demo) E. 4 pending migration với rationale "khi nào cần" - Tick [x] task đã DONE S5 (PE WF Designer + Ý kiến 4 PB) + giữ [ ] chưa làm Net change migration-todos: 136 → 217 (+81 dòng narrative) Files: docs/rules.md + docs/changelog/migration-todos.md (docs-only → CI skip) Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/changelog/migration-todos.md | 95 +++++++++++++++++++++++++++---- docs/rules.md | 60 +++++++++++++++++++ 2 files changed, 144 insertions(+), 11 deletions(-) diff --git a/docs/changelog/migration-todos.md b/docs/changelog/migration-todos.md index b66438c..e882c79 100644 --- a/docs/changelog/migration-todos.md +++ b/docs/changelog/migration-todos.md @@ -17,22 +17,95 @@ Detail chi tiết: `docs/changelog/sessions/2026-04-21-*.md` + `2026-04-22-0300-tier3-feature-complete.md` + `2026-04-23-*.md`. -## ✅ Phase 6-7 — PE Module + Budget BE — Done (2026-04-23..28) +## ✅ Phase 6 — Module Duyệt NCC (tiền-HĐ) — Done -- **Phase 6 iter 1+2**: Module Duyệt NCC tiền-HĐ — Migration 12+13, 10 bảng PE + WorkflowDefinitions, 2 type A/B, 17 endpoint, FE 3-panel cả 2 app, kế thừa HĐ qua `CreateContractFromEvaluationCommand`. UX polish iter 2 (flat layout, per-NCC attachments, readOnly mode Duyệt). Demo seed 4 phiếu varied + 7 role × 9 Pe_* permission defaults. -- **Domain rebrand**: 3 sub `.huypham.vn` → `.solutions.com.vn` E2E live HTTPS (cert + CORS + FE bundle). -- **Phase 7 — Budget BE**: Migration 14, 4 bảng Budgets + workflow simple 3-step hardcoded `BudgetPolicy.Default`, 11 endpoint, link nullable Contract.BudgetId/PE.BudgetId. **FE chưa làm** (Phase 8 done). -- **Phase 7 — 14 demo Solutions users**: PRO 5 + CCM 7 + ISO 1 + CEO 1, total 30 user (16 sample + 14 thật). +### Iter 1 (2026-04-23) -Session logs: `2026-04-23-2300-purchase-evaluations.md` · `2026-04-24-chot-session-3-pe-polish.md` · `2026-04-28-chot-session-4-budget.md`. +- [x] Migration 12 `AddPurchaseEvaluations` — 10 bảng (Header/Suppliers/Details/Quotes/Approvals/Changelogs/Attachments/WorkflowDefinitions/Steps/StepApprovers) +- [x] Domain — 2 enum (Type A/B, Phase 7-state) + Policy record + Registry + FromDefinition builder +- [x] Seed — 13 menu Pe_*/PeWf_* + 2 WorkflowDefinition v01 (QT-DN-A 3-step, QT-DN-B 5-step) +- [x] Application CQRS ~900 LOC — Create/Update/Transition/List/Inbox/Get/Delete + Supplier CRUD + Detail CRUD + Quote Upsert + SelectWinner + Changelog +- [x] PurchaseEvaluationWorkflowService — policy guard + approval + notification + changelog +- [x] PurchaseEvaluationsController — 17 endpoint REST +- [x] FE 2 app — Types + PurchaseEvaluationsListPage 3-panel + Create page + PeDetailTabs + PeWorkflowPanel + Menu resolver Pe_* +- [x] Kế thừa HĐ — `CreateContractFromEvaluationCommand` (guard DaDuyet + SelectedSupplier + !ContractId) → Contract draft. FE CreateContractDialog pick ContractType. +- [x] **Migration 13** `AddPurchaseEvaluationCodeSequences` — atomic MaPhieu sequence `PE/{YYYY}/{A|B}/{Seq:D3}` +- [x] Demo PE seed — 4 phiếu varied phase (A-001/A-002/A-003/B-001) + Pe_* permission defaults 7 role × 9 menu key -3 task PE feature gap (Workflow Designer / Ý kiến 4 PB / Export PDF) → đã đóng 2/3 ở Phase 8 §C+D. Export PDF carry over Phase 9. +Session log: `2026-04-23-2300-purchase-evaluations.md` + `2026-04-24-1030-pe-polish-demo-maphieu-perms.md`. -### Pending migrations (chưa cần đến) +### Iter 2 — UX polish (2026-04-24) -- [ ] `AddPePaymentTermFields` — nếu chốt UX tách field (JSON → 6 column riêng) -- [ ] `AddBudgetCodeSequences` — atomic SERIALIZABLE khi chốt format MaNganSach (hiện Random.Shared) -- [ ] `AddBudgetVersionedWorkflow` — nếu user cần admin config UI thay hardcoded `BudgetPolicy.Default` +- [x] Rename menu "Phương Án" → "Giải pháp" + backfill DB (zero breaking change) +- [x] Menu tree inheritance extend Pe_*/PeWf_* (`GetMyMenuTreeQuery` + 4 root) +- [x] Accordion mutex Pe_* groups + sidebar w-72 + label nowrap +- [x] NavLink active check query string (queryMatches helper) — fix 2 leaf cùng highlight +- [x] PE detail flat layout: Panel 2 = 4 section (Thông tin/NCC/Hạng mục/**Bảng so sánh**), Panel 3 += Approvals + Changelog +- [x] Upload file đính kèm per-NCC (SupplierAttachmentsCell) + Bảng so sánh tổng (GeneralAttachmentsSection, supplierRowId=null) + enum `ComparisonTable=4` +- [x] readOnly mode menu "Duyệt" (pendingMe=1) — hide Sửa/Xóa/Thêm/Edit/Upload/Delete, giữ download + transition + comment +- [x] Contract: move Lịch sử điều chỉnh Panel 2 → Panel 3 (Chi tiết HĐ full-width) +- [x] Demo email rebrand `@solutionerp.local` → `@solutions.com.vn` + `BackfillUserEmailDomainAsync` (idempotent rename 4 field Email/NormalizedEmail/UserName/NormalizedUserName) + +Session log: `2026-04-24-chot-session-3-pe-polish.md`. + +### ✅ Domain rebrand `.huypham.vn` → `.solutions.com.vn` (2026-04-24) + +- [x] 18 file repo (FE env + scripts + CI/CD + docs + skill + code comments) +- [x] `scripts/migrate-domains.ps1` (ASCII-only #30) — 3 IIS binding + 3 cert Let's Encrypt + auto HTTPS + redirect +- [x] CI/CD auto rebuild BE CORS + FE bundle VITE_API_BASE_URL +- [x] E2E verified 3 domain live + preflight OK + +Sub: `api.solutions.com.vn` · `admin.solutions.com.vn` · `eoffice.solutions.com.vn`. Old `.huypham.vn` vẫn fallback (chưa remove — Phase 9 Ops). + +## 📝 Phase 7 — PE feature gap + Budget BE (Session 4 partial done) + +### A. PE feature gap (3 task — phần lớn đóng ở Phase 8 S5) + +- [x] **PE Workflow admin designer UI** `/system/pe-workflows/:typeCode` — done S5 (`5d94bb4`) + - BE `Application/PurchaseEvaluations/PeWorkflowAdminFeatures.cs` (mirror `WorkflowAdminFeatures.cs`) + - `Api/Controllers/PeWorkflowsController.cs` + - FE `fe-admin/src/pages/system/PeWorkflowsPage.tsx` + `PeWorkflowDesigner.tsx` + - Route `/system/pe-workflows/:typeCode` (menu PeWf_* + resolver đã sẵn) +- [x] **Ý kiến 4 phòng ban** (Phê duyệt / P.CCM / P.MuaHàng / SM-PM) ở tab Thông tin — done S5 (`5d94bb4`, Migration 15) + - Option A: 4 text field + signoff date + UserId vào header + - Option B: dùng `PurchaseEvaluationApprovals` với roleKind extra field + - **Chốt:** dùng Migration 15 `AddPurchaseEvaluationDepartmentOpinions` (separate table UNIQUE PEId+Kind, 4 box sign-off 2x2 grid OpinionBox như Excel mẫu) — tốt hơn Option A/B vì audit qua Changelog + Upsert preserve chữ ký cũ khi text-only edit. +- [ ] **Export phiếu PDF/Excel** — tái dùng `IDocumentConverter` + template `PE-TrinhDuyet.docx` → carry over Phase 9 (user pending — không quan trọng lắm) + +### B. Optional polish (carry over Phase 9 — làm khi UAT phát sinh) + +- [ ] Auto-map PE Details → Contract per-type Details khi gen HĐ (phức tạp vì 7 schema khác nhau) +- [ ] Payment terms tách field từ JSON → 6 column (Tạm ứng/TT tạm/Quyết toán/Bảo hành/Hạn mức/Đánh giá) +- [ ] Matrix Quotes bulk paste từ Excel +- [ ] fe-user Inbox thêm section "Phiếu Duyệt NCC chờ tôi" + +### C. Ops (carry over Phase 9 — Hard blockers) + +- [ ] Remove binding cũ `.huypham.vn` sau verify stable: `ssh vietreport-vps ; cd C:\solution-erp\scripts ; .\migrate-domains.ps1 -RemoveOld -SkipCert` +- [ ] win-acme scheduled task fix unhealthy (cert expire 2026-06-18) +- [ ] UAT thật 1 tuần với 2-3 user (30 demo user — 16 sample + 14 Solutions thật) +- [ ] SMTP config → Email outbox +- [ ] Rotate credentials (admin + 30 demo + SA + vrapp + JWT) +- [ ] Schedule SQL backup Task Scheduler + +### D. Module Ngân sách (Budget) — Session 4 ✅ partial done + +- [x] **Migration 14** `AddBudgets` — 4 bảng (Budgets/BudgetDetails/BudgetApprovals/BudgetChangelogs) + index BudgetId nullable trên Contract & PurchaseEvaluation +- [x] Domain — `Budget` (Header) + `BudgetDetail` (flat row) + `BudgetApproval` + `BudgetChangelog` + enum `BudgetPhase` 5-state + `BudgetEntityType` Header/Detail/Workflow +- [x] `BudgetPolicy.Default` hardcoded simple 3-step (Drafter→CCM→CEO + Reject từ ChoCCM/ChoCEO về DangSoanThao) +- [x] Application CQRS ~340 LOC — Create + UpdateDraft + Transition + List + GetDetail + Delete (only DangSoanThao/TuChoi) + Detail CRUD (auto-recompute TongNganSach) + ListChangelogs +- [x] `BudgetsController` 11 endpoint REST +- [x] Menu seed `Budgets` root + 3 leaf (Bg_List/Bg_Create/Bg_Pending) order=27 icon Wallet +- [x] **14 demo user Solutions thật** — PRO 5 + CCM 7 + ISO 1 + CEO 1 (pwd `User@123456`). Reconcile pattern (gotcha #38 4-field rename). Tổng 30 user (16 sample cũ + 14 Solutions thật mới). + +Session log: `2026-04-28-chot-session-4-budget.md`. + +### E. Pending migrations + +- [ ] `AddPePaymentTermFields` (nếu chốt UX tách field — JSON blob → 6 column) +- [x] **`AddPurchaseEvaluationDepartmentOpinions`** ✅ migration 15 (S5) +- [ ] `AddBudgetCodeSequences` (nếu chốt format MaNganSach atomic — hiện Random.Shared) +- [ ] `AddBudgetVersionedWorkflow` (nếu user cần admin config UI thay vì hardcoded `BudgetPolicy.Default`) ## ✅ Phase 8 — Budget FE + PE/HD integration (Session 5 done) diff --git a/docs/rules.md b/docs/rules.md index 4539452..b3c7200 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -305,6 +305,66 @@ Co-Authored-By: Claude Opus 4.7 (1M context) **Trigger override:** User nói "audit MD", "kiểm tra docs", "định kỳ kiểm tra", "compact docs" → chạy doc audit ngay không đợi cron. +### 6.5 Consolidate MD đúng cách — KEEP vs CUT + +> **Bài học session 6 (2026-04-30):** Compact -288 dòng nhanh, paraphrase + cắt narrative để "rõ đẹp" → user phản hồi "viết MD gọn lại tý là mất mẹ luôn tính cách cũ". Docs đọc 6 tháng sau như machine output, không hiểu tại sao chọn approach. Rule §6.5 này chốt để KHÔNG TÁI PHẠM. + +**Mục tiêu consolidate:** Giảm độ dài để session sau đọc context không mệt. **KHÔNG = cắt thông tin / paraphrase / "đẹp hóa".** + +#### KEEP — CẤM CẮT (asset không tái tạo được) + +| Loại | Vì sao bắt buộc giữ NGUYÊN VĂN | Ví dụ | +|---|---|---| +| **Narrative tích lũy qua sessions** | Không tái tạo. Là tài sản chỉ ra "đã đi qua đâu, đã đổi hướng ra sao" | "Ban đầu chọn MediatR 14, fail DI runtime, downgrade 12.4.1" | +| **Rationale (lý do quyết định)** | Quan trọng hơn quyết định. Mất rationale → agent mới revert vì không biết tại sao | "Pin Swashbuckle 6.9.0 vì 10.x conflict OpenApi 2", "Skip E2E Playwright vì brittle cho solo dev" | +| **Gotcha context (incident bối cảnh)** | Gotcha = fix + bối cảnh đau. Mất context → instructions khô không apply được | G-084 "Next.js bind 0.0.0.0 → Gitea fallback IPv6 → IIS ARR resolve IPv4 first → leak homepage" | +| **Anecdote / bài học** | Nuance không có trong code/git, chỉ có trong docs | "Bài học NamGroup: Node latest fail CI Windows" | +| **Decision why over decision what** | Code chỉ có "what", docs phải bù "why" | "PE workflow tách enum riêng vì Phase ≠ ContractPhase" | + +#### CUT — XÓA hoặc CHUYỂN CHỖ được + +| Loại | Cách xử lý | Ví dụ | +|---|---|---| +| Số liệu lặp giữa nhiều file | Giữ 1 chỗ canonical, các file khác cross-ref | "52 bảng" canonical ở PROJECT-MAP, STATUS/HANDOFF cross-ref | +| Section duplicate copy-paste | Cross-ref thay vì copy nguyên văn | "Versioned WF quick ref" → cross-ref `workflow-contract.md §7bis` | +| List Recently Done > 30 row | Archive sang file riêng `recently-done-archive-{YYYY-MM}.md` (CHUYỂN CHỖ, KHÔNG xóa) | Phase 0-7 cũ | +| Phase đã đóng > 1 tháng | Collapse thành 1 paragraph + link session log đầy đủ | Phase 0-5 → "Phase 0-5 done, [session logs](changelog/sessions/)" | +| Stats lặp | Cumulative table giữ ở STATUS, file khác chỉ con số mới nhất | LOC / endpoint / migration count | + +#### CẤM TUYỆT ĐỐI + +- ❌ **Paraphrase câu chữ original** — dù "rõ ràng hơn", KHÔNG paraphrase. Giữ y nguyên văn cũ. +- ❌ **Summary đoạn đã có narrative** — không tóm tắt 5 dòng kể chuyện thành 1 dòng "X done". Mất context. +- ❌ **"Đẹp hóa" bằng cách cắt** — đẹp đạt qua format (bảng, anchor link, heading), KHÔNG qua cắt nội dung. +- ❌ **Compact với mindset machine-first** — viết cho agent mới đọc 6 tháng sau hiểu, KHÔNG phải tổng hợp ngắn nhất. + +#### Decision tree khi gặp đoạn dài + +``` +Đoạn này có narrative / rationale / gotcha context / anecdote / "tại sao"? +├─ Có → GIỮ NGUYÊN VĂN, kể cả dài (lossless) +└─ Không → kiểm tra: + ├─ Duplicate file khác? → cross-ref + ├─ Số liệu cũ stale? → archive sang file riêng + ├─ Phase đã đóng > 1 tháng? → collapse + link session log + └─ KHÔNG match gì → GIỮ NGUYÊN (default lossless) +``` + +#### Validation sau consolidate (BẮT BUỘC chạy) + +Đọc lại file đã compact, tự hỏi 3 câu: +1. **Agent mới đọc 6 tháng sau có biết "tại sao chọn approach này" không?** +2. **Có còn cảm giác "kể chuyện" tích lũy không, hay chỉ là instructions khô?** +3. **Gotcha context vẫn còn ý nghĩa khi đọc rời rạc không?** + +→ Nếu "không" cho **bất kỳ** câu nào → revert đoạn đó về nguyên văn cũ. + +#### Trigger áp §6.5 + +- Audit định kỳ §6.4 (cron đầu tháng) +- 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) ### Stack đã apply