# 專案狀態機修復（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_status`（`audit_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_project` 設 `deleted_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.PENDING` → `IN_PROGRESS` | 新專案 DB status 即 `in_progress`（原停 pending） |
| `app/grc/service/audit_round_app_service.py` | `create_round` 成功後補呼 `_sync_project_status`；`launch_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_project` 的 `status` 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 migration**：`2026-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。