ewoooc/docs/guides/pchome_ai_automation_priority_backlog.md

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_intelligence、/observability/overview、/ai_automation_smoke 與 /observability/agent_orchestration 密集 AI 工作台文字密度守門。

目的: 讓 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
• /ai_intelligence 商品明細價格證據 guard 已完成:
  • 商品列與單品詳情都以 aria-label="價格證據" 與 data-evidence 固定 PChome 價格、MOMO 參考價、差距、可信度四格。
  • 搜尋欄明確涵蓋商品、分類、編號與 MOMO 候選，排序支援優先級、近 7 天業績、價差、下滑幅度、可信度。
  • tests/test_ai_intelligence_product_evidence_guardrails.py 已鎖住四格價格證據、候選待確認 / 待補狀態與搜尋排序契約。
• /ai_intelligence 密集 AI 工作台文字密度 guard 已完成:
  • 首屏改成 data-density-guardrail="compact-ai-workbench"，以「AI 作戰 / 證據優先 / 下一步」短標籤取代長說明。
  • KPI note、benchmark detail、alert 副句、mini-card 說明、策略 note、decision copy、來源長句與單品 reason list 從可見 UI 退場。
  • tests/test_ai_intelligence_text_density_guardrails.py 已鎖住短任務文案、detail meta 與 explanatory copy hidden contract。
• /observability/overview 密集 AI 觀測工作台文字密度 guard 已完成:
  • 首屏改成 data-density-guardrail="compact-observability-workbench"，以「AI 觀測 / 風險優先 / 下一步」短標籤承接 golden signals。
  • hero lede、signal note、route desc、host meta 與資料來源長句從可見 UI 退場，保留狀態、數字與子頁入口。
  • tests/test_observability_text_density_guardrails.py 已鎖住 compact marker、第一層狀態數字與 explanatory copy hidden contract。
• /ai_automation_smoke 密集 AI 巡檢工作台文字密度 guard 已完成:
  • 首屏改成 data-density-guardrail="compact-smoke-workbench"，以「AI 巡檢 / 風險優先 / 推播摘要」短標籤承接 AI 健康檢查。
  • hero lede、趨勢說明、每日摘要說明與診斷細節提示從可見 UI 退場，保留狀態、數字、趨勢、每日摘要與檢查項目 summary。
  • tests/test_ai_automation_smoke_text_density_guardrails.py 已鎖住 compact marker、第一層狀態數字與 explanatory copy hidden contract。
• /observability/agent_orchestration 密集 AI Agent 工作台文字密度 guard 已完成:
  • 首屏改成 data-density-guardrail="compact-agent-workbench"，以「AI 分工 / 成本守門 / 知識命中」短標籤承接 Agent 編排狀態。
  • hero 說明、KPI 小註、列內描述、卡片描述與頁尾重複標題從可見 UI 退場，保留呼叫總量、主力路徑、付費成本、知識命中、分工矩陣與工具協作表。
  • tests/test_agent_orchestration_text_density_guardrails.py 已鎖住 compact marker、第一層狀態數字與 explanatory copy hidden contract。

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

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。
   • 已完成: /ai_intelligence 與 /observability/overview 首屏都有 AI 自動化狀態 golden-signal strip。
   • 已完成: 兩頁都明確呈現「已自動落地、已驗證、異動狀態、下一步」。
   • 已完成: tests/test_ai_surface_benchmark_guardrails.py 鎖住 DOM、下一步優先與 evidence-on-demand wording。
2. 為後續 safe automation lanes 建立同樣的 first-viewport summary。
   • 已完成: /api/ai/pchome-growth/ai-automation-surface-summary 會把 readiness safe lanes 收斂成 golden_signals、safe_automation_lanes、surface_contract、next_machine_action 與 no-write 安全欄位。
   • 已完成: /ai_intelligence 首屏改吃 surface summary，不再自行拼接 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 必須分開回報。
• 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
P1.3	AI intelligence product evidence guardrails	已完成	detail rows + single product detail expose four evidence cells + focused guard tests	P2 / P3 automation surfaces
P1.4	AI intelligence compact workbench text-density guardrails	已完成	/ai_intelligence first viewport and drilldown hide explanatory copy; focused density guard test	P2.2 benchmark guardrails and future AI surfaces
P1.5	Observability compact workbench text-density guardrails	已完成	/observability/overview first viewport hides explanatory copy; focused density guard test	Apply density guard to remaining high-visibility AI surfaces
P1.6	AI automation smoke compact workbench text-density guardrails	已完成	/ai_automation_smoke first viewport hides explanatory copy; focused density guard test	Apply density guard to remaining high-visibility AI surfaces
P1.7	Agent orchestration compact workbench text-density guardrails	已完成	/observability/agent_orchestration first viewport hides explanatory copy; focused density guard test	Apply density guard to remaining high-visibility AI surfaces
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
P2.2	Benchmark guardrails applied to core AI surfaces	已完成	/ai_intelligence + /observability/overview golden-signal strips + focused tests	後續 safe automation lanes 套同樣 first-viewport summary

後續回報格式

每次 continuation 必須回報:

current_priority:
- item: ...
- reason: ...

implemented:
- ...

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

next_priority:
- ...