專案狀態機修復(B 案)SUMMARY

收尾日期:2026-07-09|作業:Claude(外部 session 執行主導交付的 handoff prompt) 追蹤來源:docs/analysis/2026-07-07-known-pits-remediation-tracker.md §UX「Review 後新開調整項」③ 狀態:✅ 已實作 + commit + 手測通過(DEV/STG 已回填,POC 按住、push 待 user 明示)


1. 問題與定調

起因:user 回報「專案列表狀態篩選跟實際狀態對不上」。

Root cause:FR-038 v2 把「顯示」改用輪次狀態(latest_round_status),但 project.status 的維護只做了一半——_sync_project_statusaudit_round_app_service.py)只掛 close_round,專案啟動稽核後 status 停在 pending。v1 的完整維護點(oscal_audit_service.py PENDING→IN_PROGRESS)整支已 dark(DI 註解、v2 恆 None 的 project_mapping gate 死路)。

DEV DB 佐證compliance.projects.status 只有 pending(12) / archived(193),零 in_progress/completed → 列表「進行中/已完成」篩選永遠空、專案調查結果報表 picker(filters in_progress/completed)也空。

定調(user 拍板 B 案):專案一建立即算「進行中」(不再有「未開始」語意)。輪次驅動,project.status 為被維護的粗粒度真相。archived=軟刪除終態(soft_delete_projectdeleted_at+archived,列表已排除),不動。


2. Commits

Repo Commit 內容
BE c574f7ca 建立即 IN_PROGRESS、create_round 補 sync、啟動通知遷 launch_audit、回填 migration
FE 6cd28aa 移除「未開始」篩選、規劃提示改輪次驅動、Dashboard 只判 in_progress
BE(docs) 本次收尾 project-list spec 更新 + html rebuild + tracker ③ 銷帳 + 本 SUMMARY

兩 code commit 均在 fix/v1.8.0-bugs未 push(等 user 明示)。工作區另有別批已 commit 的 OTP/device/notification 改動,與本案獨立。


3. 改動範圍與行為差異

BE

檔案 改動 行為差異
app/project/service/project_start_app_service.py 建 project 主檔 ProjectStatus.PENDINGIN_PROGRESS 新專案 DB status 即 in_progress(原停 pending)
app/grc/service/audit_round_app_service.py create_round 成功後補呼 _sync_project_statuslaunch_audit 補呼 notify_project_started(新 helper _notify_project_started_safe);__init__ 注入 project_service 開輪同步專案狀態(涵蓋 COMPLETED 再開輪回退);啟動稽核通知所有角色
app/grc/service/project_service.py 新增 public notify_project_started wrapper(委派既有 _notify_project_started 供跨 app service 復用,不重造通知邏輯
di_containers/grc/grc_containers.py audit_round_app_service provider 移到 project_service 之後 + 注入 project_service 解決 provider 定義順序(audit_round 依賴 project_service)
scripts/sql/2026-07-09-backfill-project-status-b-model.sql 回填既有 pending 專案 pending→completed(全輪 closed)/in_progress(其餘)

⚠️ 修正 plan 假設:plan 稱 launch_audit/create_round/覆核輪建立三處都漏呼 sync,實測只有 create_round——launch_audit(:386)、close_round(:506)、launch_reverify(:572) 早已呼叫(plan 行號取自舊版狀態)。故只補 create_round 一處,未重複加。

啟動通知遷移細節:原觸發=update_projectstatus pending→in_progress 轉換(project_service.py:409);建立即 in_progress 後此轉換不再發生(FE 專案設定頁本就不送 status、v2 workflow dark path 的 project_mapping 恆 None)。改掛 launch_audit(語意=啟動稽核即通知所有角色)。update_project 的原觸發保留(dead but harmless,不破壞既有 caller)。

FE

檔案 改動
src/views/project/ProjectListView.vue statusOptions 移除「未開始」(四鈕→三鈕)
src/config/locales/i18n/{en,zh-tw}/project-list.json 清孤兒 key filter_pending
src/views/project/ProjectAuditorOverview.vue 新增 isPlanningPhase(round 模式看該輪 status==='planning',legacy 沿用 project pending),取代 3 處裸 isPending gate(SSP 完成度卡 / control SSP 描述提示 / group SSP 完成度);showPlanningBanner 併用
src/views/project/DashboardView.vue SSP 完成度 eligible + 進行中專案查詢改只判 in_progress

摘要報表 picker(ProjectSummaryReportManage.vue ['in_progress','completed'])是別批(②#5)改動,本案落地+回填後自然見效——強互鎖已解


4. 回填 migration 執行紀錄

環境 Host/DB 結果
DEV 188:25432 / guidant_ai_dev 12 pending → 12 in_progress(0 符合 completed,無全輪 closed 者);archived 193 不動
STG 188:25432 / guidant_ai_stg 1 pending → in_progress(原已有 2 in_progress → 3);archived 44 不動
POC 189:25432 / guidant_ai_poc 未套(按住待 user 明示)

冪等:兩段 UPDATE 皆 WHERE status='pending',重跑無副作用;schema_migrations 已登記。


5. 驗證

  • BE 測試:test_create_round_flow_binding 2 passed;test_project_start_creates_first_round 2 failed 為既有 stale mock(_project_extension_domain_service 未注入,已 stash 比對確認與本次無關)→ 零新增失敗
  • FE build:DEV 綠。
  • DI provider 解析:isolated resolution 確認 project_service 已正確注入(僅 sibling container 未 wire,屬 isolation 預期)。
  • 手測(user):建專案→in_progress、啟動稽核→通知+仍 in_progress、全輪 closed→completed、開覆核輪→回 in_progress、刪除→archived+列表消失、三態篩選正確、摘要報表 picker 有選項 → 通過

6. 規範文件清單(本次收尾已更新)

  • docs/specs/v1.8.0/project-management/project-list.md — §1.1 狀態篩選四鈕→三鈕、§4 狀態語意表補 project.status 生命週期 + 檔頭變更紀錄;html 已 rebuild
  • docs/analysis/2026-07-07-known-pits-remediation-tracker.md §UX ③ — 銷帳(含 plan 假設修正 + #5 互鎖解除)
  • ✅ 本 SUMMARY

7. 已知 follow-up / 部署 handover

  • push:BE c574f7ca + FE 6cd28aa 未 push,等 user 明示。
  • POC migration2026-07-09-backfill-project-status-b-model.sql 未套 POC,等 user 明示。
  • BE 需重啟(無 hot reload)才生效。
  • 既有 stale 測試test_project_start_creates_first_round mock 缺 _project_extension_domain_service)非本案 scope,未修——如要修屬另一 test scaffolding 工作。
  • 硬刪除/回收站:user 已定調另開 FR,不在本案 scope。