solution-erp/docs/changelog/sessions/2026-04-29-2300-chot-final-ci-tests-gotchas.md

Session log — 2026-04-29 chiều/tối (Chốt final session 5 — CI optimize + Tests Phase 3 mini + 3 gotcha CI)

Topic: CI/CD incident #108/#109 → fix manual checkout + path filter + thử npm cache (fail rollback) + Tests Phase 3 mini PE Workflow Designer + 3 gotcha CI mới + chốt MD lần 2.

Commits session 5 chiều/tối:

• 52999f3 — Docs chốt session 5 đầu (Budget FE + PE feature gap)
• 26075c4 — Empty re-trigger sau #108 fail
• 14b7d18 — CI: Manual checkout bypass github.com (fix #108/#109 TCP timeout)
• 29eb5d9 — CI: Path filter docs-only + npm junction cache (Option C)
• a21790d — CI: Rollback npm cache (fail #111 tsc not found), giữ path filter
• 512880c — Docs test: STATUS update — verify path filter docs-only skip → ✅ no run #113
• (commit chốt MD này)

A. CI/CD incident & fix

Run #108/#109 fail TCP timeout 21s

Get "https://github.com/actions/checkout/info/refs?service=git-upload-pack":
  dial tcp 20.205.243.166:443: connectex: A connection attempt failed
  because the connected party did not properly respond

Test gate (Domain + Infra) chưa kịp chạy. act_runner mỗi run đều cố git fetch actions/checkout@v4 từ github.com để kiểm tra update.

Fix (commit 14b7d18): Replace uses: actions/checkout@v4 + actions/upload-artifact@v4 bằng manual git checkout từ Gitea internal — bypass github.com hoàn toàn.

- name: Checkout (manual git, bypass github.com)
  shell: powershell
  run: |
    git config --global --add safe.directory '*'
    git init -q
    git remote add origin "https://gitea-actions:${{ github.token }}@git.baocaogiaoduc.vn/${{ github.repository }}.git"
    $ref = "${{ github.ref }}"
    if ($ref -like "refs/heads/*") { $ref = $ref.Substring(11) }
    git fetch --depth=30 origin $ref
    git checkout --quiet "${{ github.sha }}"
    git log -1 --oneline

Verify: Run #110 commit 14b7d18 PASS 3m16s, smoke /health/live → 200.

Path filter docs-only skip (commit 29eb5d9 + verify 512880c)

User propose Option C (path filter + npm cache). Implement:

on:
  push:
    branches: [main]
    paths-ignore:
      - 'docs/**'
      - '**/*.md'
      - '.claude/skills/**'
      - '.gitignore'
      - 'scripts/**.md'

Verify: Push commit 512880c chỉ touch docs/STATUS.md → curl https://git.baocaogiaoduc.vn/.../actions/runs/113/jobs/0/logs trả Not found → Gitea KHÔNG trigger run mới. ✅

Saving: ~196s/commit cho ~30% commit thuộc loại docs-only (chốt MD, session log, etc).

npm junction cache fail (commit 29eb5d9 rollback ở a21790d)

Implement junction-based cache:

• Cache key = SHA256(package.json) 16-char prefix
• Cache stored: C:\npm-cache-erp\<app>\<hash>\node_modules
• Junction fe-admin\node_modules → cache (instant, không file copy)

Run #111 FAIL 'tsc' is not recognized ở step Build fe-admin. Symptoms:

• VPS check: cache dir C:\npm-cache-erp\ chưa có (cold)
• Log: KHÔNG có Write-Host "cache MISS" hay "added 239 packages"
• Timing: 1.6s từ end-of-BE-build → start-of-fe-admin npm run build (impossible cho npm install 49s)
• Test gate (Domain 54 + Infra 17) PASS nên không phải code regression

Hypothesis:

• (A) Move-Item của node_modules chứa nested junctions/symlinks → .bin/ relative paths broken
• (B) act_runner PowerShell stream capture có quirk với cache MISS branch
• (C) Test-Path stale TRUE từ state khác

Decision: Rollback về fresh npm install mỗi run (49s + 33s = 82s). Path filter docs-only skip là alternative win lớn hơn (saving 100% time cho 30% commit).

Verify rollback: Run #112 commit a21790d PASS 3m9s, smoke 200.

TODO debug session sau: Thử robocopy /MIR thay Move-Item (handle symlinks tốt hơn), hoặc dùng act_runner built-in cache.host server.

B. Tests Phase 3 mini — PE Workflow Designer

tests/SolutionErp.Infrastructure.Tests/Application/PeWorkflowAdminTests.cs
└── CreatePeWorkflowDefinitionCommandHandlerTests (6 test)
    ├── Create_FirstVersion_PersistsWith_Version1_And_IsActiveTrue
    ├── Create_SecondVersionSameCode_AutoIncrements_AndDeactivatesPrevious
    ├── Create_DifferentEvaluationType_DoesNotAffect_Other
    ├── Create_PersistsAllSteps_OrderedByOrderField
    ├── Create_PersistsApprovers_PerStep
    └── Create_ThirdVersion_DeactivatesV2_Increments_To_V3

Coverage:

• Auto-increment Version per Code (1 → 2 → 3)
• Invariant "AT MOST ONE IsActive=true per EvaluationType" — deactivate cũ atomic
• Type independence — Type A active không ảnh hưởng Type B active
• Persistence: steps ordered + approvers per step

Skip Phase 3 full (Opinion Upsert + Budget link validation) — cần UserManager DI helper, time-cost cao. Document làm session sau khi cần.

Total tests sau session 5: 77 pass / ~3s (54 Domain + 17 Infra + 6 PE WF Application).

C. 3 gotcha CI mới

#39 act_runner github.com TCP timeout 21s (manual checkout fix)

Documented cause + workaround. Reference run #108 commit 52999f3 fail, run #110 commit 14b7d18 fix pass.

#40 npm junction cache tsc not found sau Move-Item — chưa xác định root cause

Documented hypothesis + workaround tạm + TODO debug. Reference run #111 commit 29eb5d9 fail, rollback ở a21790d.

#41 Gitea Actions paths-ignore — workflow file change vẫn trigger

Documented behavior + verify pattern. Reference commit 29eb5d9 add filter, 512880c (docs-only) verify no run #113.

Total gotchas: 38 → 41. Checklist debug bug mới cũng update items 18-20.

D. Doc updates (chốt lần 2)

File	Change
docs/STATUS.md	Header Phase 8 update + 3 row Recently Done CI fixes + cumulative test count 71 → 77
docs/HANDOFF.md	TL;DR thêm CI optimize section + Phase status table thêm 3 task done + gotcha count 38 → 41
docs/changelog/migration-todos.md	Phase 8 §E thêm Phase 3 mini done + CI fixes
docs/rules.md §7 Testing	Rewrite full section: stack + test pyramid + quy tắc bổ sung mỗi feature + workflow user end-of-task + CI gate behavior
docs/architecture.md §11 Testing strategy	Update test pyramid + phased priority + CI optimization sub-section (3 fix) + tốc độ deploy table
docs/gotchas.md	+ #39 #40 #41 + checklist debug items 18-20
.claude/skills/ef-core-migration/SKILL.md	Phase 8 update note thêm CI fixes + 77 test
CLAUDE.md (root)	Test count 71 → 77 + folder structure update + CI/CD pipeline 3 fix
~/.claude/.../memory/project_solution_erp.md	Session 5 summary + workflow user mới

E. Skill audit cron (định kỳ)

solution-erp-skill-audit-monthly cron next fire 2026-05-01 (2 ngày sau session này). Workflow đã setup từ session trước (commit b904a25). Cron survives across sessions.

Setup ban đầu document tại docs/rules.md §9.4. Khi fire sẽ:

• Cross-check 6 skill hiện có với STATUS / gotchas / migration-todos
• Auto-refresh stale entries
• Đề xuất add/archive cho human approve
• Log vào docs/changelog/skill-audit-2026-05.md
• ABORT nếu repo dirty

F. Stats sau session 5 final

	Trước S5	Sau S5 final
BE LOC	~11750	~13050 (+1300)
DB tables	51	52 (+1)
Migrations	14	15
API endpoints	~124	~128
FE pages	~26	~31 (+5)
Tests	0	77 (Phase 1+2+3mini)
Gotchas	38	41 (+3 CI)
CI/CD pipeline	1 step build	Test gate (3 step) + path filter + manual checkout
Demo user	30	30
Commits S5	~75	~91 (+16 session 5 incl chốt + CI iterations)

G. Cảnh báo session 6

1. CI test gate active — workflow user: code → dotnet test local → commit → push. Test fail = NO deploy.
2. Path filter live — commit chỉ touch docs/**/**/*.md/.claude/skills/**/.gitignore → CI SKIP hoàn toàn (saving ~196s).
3. Manual checkout từ Gitea — không phụ thuộc github.com. Nếu nâng cấp act_runner version → check xem hỗ trợ uses: actions/* tốt hơn không (lúc đó có thể switch back).
4. npm cache CHƯA work (gotcha #40) — debug session sau với robocopy hoặc act_runner built-in cache server.
5. Skill audit cron next 2026-05-01 — kiểm tra log audit khi fire.
6. Tests Phase 3 full + 4 + 5 pending — chỉ làm khi gặp bug recurring để justify ROI.
7. Login email vẫn admin@solutionerp.local — chưa rebrand @solutions.com.vn.
8. win-acme scheduled task unhealthy — fix trước cert expire 2026-06-18.
9. Hard blockers ops — UAT thật, SMTP, rotate creds, SQL backup schedule.

H. Lessons learned final S5

1. CI debug strategy "log first, ROI second" — incident #108/#109 spent 50min debugging. Cuối cùng fix là 30 dòng workflow YAML thay 1 line uses: actions/checkout@v4. Đáng vì workflow ổn định lâu dài.

2. Path filter ROI cực cao cho solo dev — 30% commit là docs-only (chốt MD, session log, planning). Skip CI hoàn toàn = 100% saving cho commit đó. Implementation 2 dòng YAML.

3. npm cache với junction tricky on Windows — Move-Item của node_modules chứa nested junctions có thể disrupt .bin/ structure. PowerShell stream capture ở act_runner cũng có quirk khó debug. Better path: robocopy hoặc act_runner built-in cache.

4. Tests Phase 3 incremental approach — full handler tests cần Identity DI heavy. Mini scope (handler không phụ thuộc UserManager) như CreatePeWorkflowDefinition là sweet spot cho ROI nhanh. 6 test thêm trong 30 phút.

5. Workflow user mới dotnet test local trước commit — catch bug local nhanh hơn đợi CI fail. Thói quen tốt cho solo dev.

6. Gotcha doc khi gặp 1 lần là đủ — 3 gotcha CI mới documented chi tiết để session sau hiểu ngay context, không phải tái-debug.

I. Files touched session 5 final

.gitea/workflows/deploy.yml            (mod multi: manual checkout + path filter + npm cache thử rồi rollback)

tests/SolutionErp.Infrastructure.Tests/Application/PeWorkflowAdminTests.cs (NEW — 6 test)

docs/STATUS.md                         (mod: Phase 8 header + 3 row Recently Done CI fixes + cumulative)
docs/HANDOFF.md                        (mod: TL;DR + CI optimize section + Phase status + gotcha count)
docs/changelog/migration-todos.md      (mod: Phase 8 §E updated)
docs/rules.md                          (mod: §7 Testing rewrite full)
docs/architecture.md                   (mod: §11 update + CI optimization sub-section)
docs/gotchas.md                        (mod: + #39 #40 #41 + checklist 18-20)
.claude/skills/ef-core-migration/SKILL.md (mod: Phase 8 update note)
CLAUDE.md (root)                       (mod: 77 test + CI/CD pipeline 3 fix)
docs/changelog/sessions/2026-04-29-2300-chot-final-ci-tests-gotchas.md (NEW — file này)
~/.claude/.../memory/project_solution_erp.md (mod: session 5 summary + workflow user mới)