整理 PChome AI 自動化優先工作清單

2026-07-02 12:58:55 +08:00
parent 4ad94a0fe3
commit 72bd8e1e54
3 changed files with 216 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -142,6 +142,7 @@
 - Browse.sh 爬蟲診斷手冊: `docs/guides/browse_sh_crawler_playbook.md`
 - Webcrumbs 共用 UI Runtime: `docs/guides/webcrumbs_shared_runtime.md`
 - PChome 業績成長 UI/UX 守門: `docs/guides/pchome_growth_ui_ux_guardrails.md`
+- PChome AI 自動化優先工作清單: `docs/guides/pchome_ai_automation_priority_backlog.md`
 - 外部專業 Benchmark: `docs/guides/external_professional_benchmark.md`
 - AI 競價情報 SOT: `docs/AI_INTELLIGENCE_MODULE_SOT.md`
 - Agent 角色矩陣: `docs/guides/codex_agent_roles.md`
--- a/docs/AI_INTELLIGENCE_MODULE_SOT.md
+++ b/docs/AI_INTELLIGENCE_MODULE_SOT.md
@@ -83,6 +83,7 @@
 - V10.642 起 `/ai_intelligence` 的摘要卡與商品處理數字不可只跳到大區塊；點擊後必須開啟商品明細面板，列出商品名稱、分類、近 7 天業績、業績變化、MOMO 比價狀態與下一步按鈕。明細需至少支援全部、價格壓力、價格優勢、待確認、缺比價與有外部價切換；外部價格風險分佈也必須能一鍵篩選下方表格。
 - V10.643 起 `/ai_intelligence` 的商品明細上方必須提供「商品策略分流」視覺摘要，至少包含價格壓力、價格優勢、待確認、缺比價四類；每一類需顯示件數、近 7 天業績與比例條，且可點擊切換明細。舊 KPI 卡也不得是靜態數字，需可導向全部商品、可處理商品、高風險比價或處理紀錄。
 - V10.725 source-ready 起 PChome growth 必須提供 `/api/ai/pchome-growth/ai-automation-readiness` 與 Dashboard「AI 主流程」狀態列；同一摘要要聚合缺口偵測、同款搜尋包、候選決策包、證據收據與受控落地，並明確輸出 `primary_human_gate_count=0`、`automation_policy.primary_flow=ai_controlled`。PChome mapping 不得把 AI 例外決策當主流程；所有例外都要進 AI machine-verifiable auto-resolution，產生 failure reasons、下一個機器動作與 rollback/readback 路徑。
+- 2026-07-02 起 PChome AI 自動化主線工作順序以 `docs/guides/pchome_ai_automation_priority_backlog.md` 為可執行 backlog；使用者中途插入的 production truth、版本不得錯、GitHub freeze、推版到 Gitea/正式環境、AI 自動化取代人工主流程、外部專業 benchmark、主流專業產品網站、實作結果與完整優先順序要求，都必須列入 backlog 並依 P0/P1/P2/P3/P4 推進。未在 backlog 的支線不得蓋過 P0 runtime truth / controlled apply closure。
 - V10.644 起 `/ai_intelligence` 的商品明細列不得只用句子描述比價；每列必須顯示 PChome 價格、MOMO 參考價、差距、可信度四格價格證據，並保留下一步按鈕。單位價候選需顯示單位價與單位，候選待確認或缺資料則以「待補 / 候選待確認」呈現，不得捏造價格。
 - V10.645 起 `/ai_intelligence` 的商品明細分流切換後，必須顯示「這類商品怎麼處理」的行動摘要，包含件數、近 7 天業績、平均可信度、最大價差、代表商品與主按鈕；使用者不得只能看到商品列表而不知道下一步。
 - V10.646 起 `/ai_intelligence` 的商品明細必須提供搜尋與排序；搜尋至少涵蓋商品、分類、商品編號與 MOMO 候選資訊，排序至少支援優先級、近 7 天業績、價差、下滑幅度與可信度。搜尋/排序後的行動摘要與明細列表必須使用同一批結果。
--- a/docs/guides/pchome_ai_automation_priority_backlog.md
+++ b/docs/guides/pchome_ai_automation_priority_backlog.md
@@ -0,0 +1,214 @@
+# 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`
+- AI debt scanner 顯示產品面清空:
+  - `PRODUCT_SURFACE_CLEAR`
+  - `finding_count=0`
+  - `primary_human_gate_count=0`
+
+進行中 / 下一步，必須照順序:
+
+1. 建立 automated drift-verifier monitor / smoke path，讓 verifier 不是只可手動呼叫，而是能被例行檢查。
+2. 建立 drift rollback / re-apply recommendation package，未來出現 drift 時可自動給出修復方案與回滾證據。
+3. 建立正式環境 compact readback endpoint，回傳最新 apply / replay / drift receipts。
+4. 建立 PChome controlled-apply artifacts retention policy，讓 evidence 可追蹤但不無限制膨脹。
+
+完成標準:
+
+- 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。
+
+未開始 / 下一步，必須照順序:
+
+1. 把 PChome AI automation lanes 放進實際 product dashboard 第一視窗。
+2. 用繁體中文營運語言呈現 lane label、狀態與下一個機器動作。
+3. 正常產品畫面隱藏 raw endpoint、commit ID、DB table name、JSON payload。
+4. 增加專業的「今日 AI 自動化狀態」摘要:
+   - 已自動落地什麼
+   - 已驗證什麼
+   - drift 狀態
+   - 下一個機器動作
+5. 增加 UI tests 或 route 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。
+
+未開始 / 下一步，必須照順序:
+
+1. 對照目前 AI automation command center 與主流 observability / workflow dashboard pattern。
+2. 把 benchmark 結論轉成 UI guardrails 與 tests。
+3. 為 controlled apply、receipt replay、drift verifier 寫入正式產品文案。
+
+完成標準:
+
+- 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 必須分開回報。
+
+完成標準:
+
+- 每次 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 / smoke |
+| P0.6 | Drift verifier artifact | 已完成 | drift artifact hash match `1` | 增加 latest compact readback |
+| P0.7 | Automated drift monitor | 未開始 | none | 下一個實作 |
+| P0.8 | Drift rollback / re-apply package | 未開始 | none | P0.7 後實作 |
+| P1.1 | Dashboard AI automation first-viewport surface | 未開始 | API readiness exists | P0 monitor 後實作 |
+| P1.2 | UI wording guard for no raw engineering terms | 未開始 | existing guardrails only | 為新 automation surface 補 tests |
+| P2.1 | External benchmark encoded into requirements | 未開始 | benchmark guide exists | 更新 guardrails / tests |
+| P3.1 | Extend receipt / replay / drift pattern to more lanes | 未開始 | current retry lane complete | P1 後選下一條 safe lane |
+
+## 後續回報格式
+
+每次 continuation 必須回報:
+
+```text
+current_priority:
+- item: ...
+- reason: ...
+
+implemented:
+- ...
+
+verification:
+- tests: ...
+- gitea: ...
+- production: ...
+- artifacts: ...
+
+next_priority:
+- ...
+```