# PChome AI 自動化優先工作清單

> 最後更新: 2026-07-02 Asia/Taipei
> 範圍: PChome growth / MOMO mapping AI 自動化主線
> 真相來源: Gitea `dev` / `main`、正式環境 `/health`、正式 DB readback、machine-verifiable artifacts

## 不可遺漏的插入需求

以下是使用者在主線推進期間插入、且必須保留在完整工作項目裡的要求。後續不得再把這些需求漏掉或變成口頭提醒。

1. 正式環境才是最新版本真相；不得用本機檔案、舊筆記、舊分支蓋過 production truth。
2. 版本不得搞錯；目前正式環境 `/health` 版本維持 `V10.725`，除非有明確版本 bump、部署與 readback。
3. GitHub 全面 freeze；不得使用 GitHub、`gh`、GitHub API、GitHub Actions、PR、issue、mirror 或 read-only GitHub 流程。
4. 實作結果必須推到 Gitea `dev` 與 `main`；若改到 runtime 行為，還必須部署到正式環境並回讀。
5. 主方向是 AI 自動化，不是人工審核；人工欄位只能當 evidence / ledger / UI truth，不得阻擋低爆炸半徑、可驗證、可回滾的 controlled apply。
6. 每條主線都要產生實作結果；不能只交計畫、UI 卡片、文件或口頭盤點。
7. 中途插入的所有需求都必須進入本 backlog，且標明優先順序與狀態。
8. 所有工作必須照優先順序推進；除非高優先 blocker 要求，否則不得開支線偏離。
9. 產品體驗要往主流、專業產品網站前進：AI 狀態可見、下一步清楚、繁中介面、營運儀表板密度足夠、一般產品頁不暴露 raw engineering terms。
10. 必須參考外部主流專業網站 / SaaS / observability dashboard 做法：狀態分層、下一步優先、收據可追蹤、drift 監控、automation health visibility。
11. AI 技術自動化要升級為可見能力：agent status、controlled apply、artifact receipts、drift verifier、rollback / re-apply evidence，不能把隱藏人工 gate 當主流程。
12. 每次宣稱完成都必須列出 source truth、runtime truth、測試、production readback、artifact / blocker 狀態。
13. 不把工作丟回給使用者；Codex 收到「批准 / 繼續」後，必須主動補齊 target selector、dry-run / check-mode、rollback、post-apply verifier 與回讀證據。
14. 需要同時看清楚所有工作狀態：已完成、進行中、未開始；不能只報正在做的一小段。

## 優先順序總表

| Priority | 主線 | 狀態 | 為什麼排這裡 |
|---|---|---|---|
| P0 | Runtime truth + AI controlled apply closure | 進行中，核心閉環已完成多段 | 先證明 AI 真的在正式環境可執行、可回讀、可驗證、可回滾 |
| P1 | 產品可視化 + 專業網站體驗 | 進行中 | 使用者要看得到實作結果，AI 自動化不能只藏在 artifact / log |
| P2 | 外部主流 benchmark 落成 guardrails | 未開始 | 把主流專業做法變成可測規則，不只是參考口號 |
| P3 | 擴大 AI 自動化覆蓋面 | 未開始 | 把目前 PChome retry lane 的閉環模式複製到更多安全場景 |
| P4 | Source / deployment governance | 持續進行 | 保證版本、Gitea、正式環境、DB 安全紅線不再混亂 |

## P0 - Runtime Truth And AI Controlled Apply Closure

狀態: 進行中，核心閉環已完成多段。

目的: 先讓 PChome mapping automation 在正式環境真的 execute、verify、stay correct。

已完成:

- 正式環境版本真相 guard：`/health` 是最高真相，目前維持 `V10.725`。
- Gitea `dev` / `main` source truth 對齊。
- Retry exception controlled apply executor 已落地，目標表為 `pchome_product_matches`。
- 正式 DB 已 controlled apply 4 個 selectors:
  - `14560744 -> DDBH21-A900I79YR-002`
  - `8932783 -> DDBH21-A900I79YR-002`
  - `15132753 -> DDBH21-A900I79YR-002`
  - `14941743 -> DDBH21-A900I79YR-002`
- Executor receipt 已 materialize。
- Receipt replay closeout 已用 artifacts 與 DB readback 補齊。
- AI automation readiness 已可回報:
  - `AI_AUTOMATION_CONTROLLED_APPLY_CLOSEOUT_VERIFIED`
  - controlled apply lane completed
  - receipt replay lane completed
- Drift verifier 已完成:
  - production readback `4/4`
  - `drift_count=0`
  - drift lane completed
- Drift verifier artifact receipt 已完成:
  - materialized artifact count `1`
  - hash match count `1`
- Automated drift monitor / smoke path 已完成:
  - `PChome 受控落地 drift monitor` 已納入 AI automation smoke checks
  - 每次 `/api/ai-automation/smoke` 與每日 smoke 摘要都會例行執行 read-only drift verifier
  - drift detected 或 verifier write-risk 會升為 `critical`
- Drift rollback / re-apply recommendation package 已完成:
  - `direct-mapping-retry-candidate-exception-controlled-apply-drift-recovery-package` 可輸出 read-only recovery package
  - drift detected 時會產生 controlled re-apply SQL shape、rollback SQL shape、selector bindings 與 acceptance gates
  - 0 drift 時會產生 no-op evidence，避免把正常狀態誤報成人工審核
- Compact latest apply / replay / drift / recovery readback endpoint 已完成:
  - `direct-mapping-retry-candidate-exception-controlled-apply-compact-readback-package` 會回傳 apply、replay、drift、recovery 四段 compact receipt
  - 產品面可直接讀取 `product_status`、`next_machine_action`、selector readback、drift count 與 artifact hash 狀態
  - compact readback 自身也可 materialize artifact 並驗證 hash
- Controlled-apply artifact retention policy 已完成:
  - `direct-mapping-retry-candidate-exception-controlled-apply-artifact-retention-package` 會掃描 controlled apply 相關 artifact families
  - 每個 family 依 `keep_latest_per_family` 保留最新 evidence，並額外保護 active compact readback chain
  - 只產生 prune candidates 與 retention receipt，不直接刪檔、不寫 DB、不執行 destructive prune
- Product dashboard first-viewport surface 已完成:
  - PChome 業績成長作戰台第一視窗已接入 AI automation readiness、receipt replay、drift verifier、drift recovery、compact readback 與 artifact retention policy
  - 第一視窗直接顯示「AI 全自動閉環已回讀」、selector readback、drift count、retention 保留數與 automation lane 狀態
  - 頁面讀取採 read-only package，不寫 DB、不刪 artifacts、不執行 prune
- AI debt scanner 顯示產品面清空:
  - `PRODUCT_SURFACE_CLEAR`
  - `finding_count=0`
  - `primary_human_gate_count=0`

進行中 / 下一步，必須照順序:

1. 將 PChome retry lane 的 receipt / replay / drift / product dashboard pattern 複製到下一條 safe automation lane。

完成標準:

- Gitea `dev` / `main` 已 push。
- runtime code change 已部署正式環境。
- `/health` healthy 且 production version truth PASS。
- 正式 DB readback 與 artifact hash readback 都有證據。
- focused PChome automation 與 AI debt tests 通過。

## P1 - Product Visibility And Professional Website Experience

狀態: 已完成。

目的: 讓 AI 自動化在產品裡可見，成為專業營運工作流，而不是只藏在後端。

已完成:

- AI readiness 已聚合主要 automation lanes。
- Controlled apply、receipt replay、drift verifier 已進 readiness。
- 產品層 automation result 已輸出 zero primary human gates。
- PChome dashboard 第一視窗已接入 compact readback 與 artifact retention policy。
- 第一視窗 automation pipeline 已從「等待 verifier」改成顯示受控落地、最新回讀、證據留存的 read-only production 狀態。
- Dashboard AI automation wording guard 已完成:
  - 第一視窗可見文案改為繁中營運語言：異動、最新回讀、證據留存、資料寫入、清理建議
  - 不再把 `retention`、`Compact`、`Artifact`、`DB writes`、`prune` 壓在產品第一視窗
  - `tests/test_pchome_dashboard_ai_wording_guard.py` 已鎖住第一視窗不可退回 raw engineering terms

已完成 / 下一步，必須照順序:

1. 對照外部主流 observability / workflow dashboard pattern，將 benchmark 結論固化為 UI guardrails。
2. 增加專業的「今日 AI 自動化狀態」摘要:
   - 已自動落地什麼
   - 已驗證什麼
   - 異動狀態
   - 下一個機器動作
3. 增加 route / HTML readback，避免產品頁退回 raw engineering wording。

完成標準:

- 使用者不用讀 log / artifact，就能在第一畫面看到 AI 自動化狀態。
- 頁面能回答「發生什麼、是否安全、下一步機器會做什麼」。
- UI 是專業 dashboard pattern，不是裝飾卡片或空泛 marketing copy。

## P2 - External Benchmark And Mainstream Product Practice

狀態: 已完成第一版，後續持續擴充。

目的: 把外部主流專業產品網站 / SaaS / observability dashboard 的做法落到規則與測試。

必須採用的 benchmark 原則:

- 狀態分層清楚: healthy、warning、blocked、completed。
- 下一步優先: next machine action 必須比細節更早被看見。
- Evidence-on-demand: receipts、hashes、raw payload 放詳細層，不壓在主畫面。
- Manual review 是例外處理，不是 primary flow。
- 產品面不顯示 raw stack traces、provider internals、database naming。
- Golden signals: 第一視窗必須能回答已自動落地、已驗證、異動狀態、下一步。
- Dashboard-as-code: benchmark 結論必須進 focused tests，不靠口頭記憶。

已完成:

- 已參考 Grafana、Datadog、New Relic、Atlassian Statuspage 官方資料。
- 已更新 `docs/guides/external_professional_benchmark.md` 的 AI automation dashboard benchmark。
- 已新增 `tests/test_pchome_dashboard_benchmark_guardrails.py`，鎖住狀態分層、下一步優先、證據按需與 golden signals。
- PChome dashboard 第一視窗已新增「今日 AI 自動化狀態」：已自動落地、已驗證、異動狀態、下一步。

下一步:

1. 將同一套 benchmark guardrails 套到 `/ai_intelligence` 與 `/observability/overview`。
2. 為後續 safe automation lanes 建立同樣的 first-viewport summary。

完成標準:

- benchmark-derived requirements 已被 tests 或 guardrails 固化。
- desktop / mobile 都維持可操作、專業、可掃描。

## P3 - Broader AI Automation Expansion

狀態: 進行中。

目的: 把目前 PChome retry mapping lane 的 controlled apply 閉環模式擴展到更多安全場景。

未開始 / 下一步，必須照順序:

1. 對其他 safe mapping backlog lanes 套用 receipt / replay / drift verifier 模式。
2. 增加 scheduled automation health summaries。
3. 為每一類 controlled apply 自動產生 rollback evidence package。
4. 把 AI automation metrics 整合進既有 observability surfaces。

完成標準:

- 每個 automation family 都有 preflight、executor、receipt、replay、drift verifier、product readiness。
- 每條 lane 都有 machine-verifiable evidence，且沒有隱藏人工-primary blocker。

## P4 - Source / Deployment Governance

狀態: 持續進行。

目的: 保持 source control、部署、正式環境真相一致，避免版本與環境再次混亂。

持續規則:

- Gitea 是 source-control truth。
- GitHub 維持 freeze。
- 不從未驗證分支部署。
- 不意外 bump version。
- 不 recreate / destroy / prune `momo-db`。
- source-control success、deployment success、production runtime readback 必須分開回報。
- `scripts/ops/report_source_deploy_runtime_truth.py` 必須可輸出 machine-readable P4 report，明確拆開 local / origin / Gitea refs、部署檔案 hash、正式 `/health`、容器狀態與安全紅線。

已完成:

- Source / deploy / runtime truth report 已建立:
  - policy: `p4_source_deployment_runtime_truth_v1`
  - source truth: local HEAD、origin `main` / `dev`、Gitea SSH `main` / `dev`
  - deployment truth: tracked file SHA256 readback
  - runtime truth: production `/health` version/status 與 optional container readback
  - safety truth: GitHub freeze、`momo-db` protected、no `--remove-orphans`、no secret read、no DB write

完成標準:

- 每次 push / deploy 都回報 Gitea head、production health、version truth、相關 readback。

## Current Work Queue

| Priority | Work item | Status | Latest evidence | Next action |
|---|---|---|---|---|
| P0.1 | Controlled apply executor | 已完成 | `DIRECT_MAPPING_RETRY_EXCEPTION_CONTROLLED_APPLY_EXECUTED`, 4 DB rows | 納入 drift verifier 監控 |
| P0.2 | Executor receipt | 已完成 | executor receipt artifact generated | 進 compact summary |
| P0.3 | Receipt replay closeout | 已完成 | `DIRECT_MAPPING_RETRY_EXCEPTION_CONTROLLED_APPLY_RECEIPT_REPLAYED`, readback `4/4` | 作為 baseline |
| P0.4 | Product readiness visibility | 已完成 | `AI_AUTOMATION_CONTROLLED_APPLY_CLOSEOUT_VERIFIED` | 接到 UI first viewport |
| P0.5 | Drift verifier | 已完成 | `DRIFT_VERIFIED`, `drift_count=0`, readback `4/4` | 由 monitor 持續檢查 |
| P0.6 | Drift verifier artifact | 已完成 | drift artifact hash match `1` | 增加 latest compact readback |
| P0.7 | Automated drift monitor | 已完成 | smoke check `PChome 受控落地 drift monitor` | 納入每日 smoke 與 runtime readback |
| P0.8 | Drift rollback / re-apply package | 已完成 | drift recovery package route + focused tests | 接入 compact readback |
| P0.9 | Compact latest apply / replay / drift / recovery readback endpoint | 已完成 | compact readback route + focused tests | 接入 product dashboard first viewport |
| P0.10 | Controlled-apply artifact retention policy | 已完成 | retention policy route + focused tests | 接入 product dashboard first viewport |
| P1.1 | Dashboard AI automation first-viewport surface | 已完成 | dashboard command center reads compact + retention packages | P1.2 wording guard |
| P1.2 | UI wording guard for no raw engineering terms | 已完成 | focused wording guard test | P2.1 benchmark guardrails |
| P2.1 | External benchmark encoded into requirements | 已完成 | benchmark guide + focused guard test + first-viewport status | P3.1 safe lane expansion |
| P3.1 | Extend receipt / replay / drift pattern to more lanes | 已完成 | direct mapping candidate decision lane closeout route + focused tests | P3.2 scheduled automation health summaries |
| P3.2 | Scheduled automation health summaries | 已完成 | `/api/ai-automation/scheduled-health-summary` + smoke service focused tests | P3.3 rollback evidence packages |
| P3.3 | Rollback evidence packages | 已完成 | controlled apply rollback evidence route + focused tests | P3.4 observability metrics integration |
| P3.4 | Observability metrics integration | 已完成 | `/metrics` exports scheduled health summary gauges + focused tests | P4 source / deployment governance ongoing |
| P4.1 | Source / deployment / runtime truth package | 已完成 | `scripts/ops/report_source_deploy_runtime_truth.py` + focused tests | 每次 Gitea push / production deploy 後執行 P4 report |

## 後續回報格式

每次 continuation 必須回報:

```text
current_priority:
- item: ...
- reason: ...

implemented:
- ...

verification:
- tests: ...
- gitea: ...
- production: ...
- artifacts: ...

next_priority:
- ...
```