docs(logbook): record stale km completion queue rollout [skip ci]

2026-05-24 23:04:25 +08:00
parent c16b2931e8
commit 1a4ac330b1
1 changed files with 101 additions and 0 deletions
--- a/docs/LOGBOOK.md
+++ b/docs/LOGBOOK.md
@@ -1,3 +1,104 @@
+## 2026-05-24｜T160 KM stale owner-review completion queue
+
+**觸發**：
+
+- T159 已能看到 stale ratio burn-down，但 operator 還缺「哪些 owner-review 可完成、哪些卡住、哪些已完成/失敗」的下一步分流。
+- 使用者要求前端要呈現已完成與推進中工作，並清楚知道 AI 治理告警後續由誰處理、卡在哪個階段。
+- 本階段目標是把 KM owner review completion 做成 read-only completion queue，不因開頁或查詢自動寫 KM。
+
+**修正**：
+
+- 新增 `GET /api/v1/ai/governance/km-stale-owner-review-completion-queue`：
+  - schema `km_stale_owner_review_completion_queue_v1`。
+  - 以 owner-review dispatch + KM priority context 建立 completion 分流。
+  - 回傳 `pending_count`、`ready_count`、`blocked_count`、`completed_count`、`failed_count`。
+  - 每筆回傳 readiness、blockers、required owner fields、recommended completion outcome、next action、batch source、dry-run fingerprint。
+  - read-only guardrail：`writes_on_read=false`、`manual_review_required=true`、`batch_writes_allowed=false`。
+- AwoooP Work Items / AI 治理新增 `Completion 分流佇列`：
+  - 顯示可處理 / 卡住 / 完成 / 失敗 / 待處理 dispatch。
+  - ready 項目可沿用既有逐筆 dry-run + confirm complete 流程。
+  - completed / failed / blocked 項目只呈現狀態與下一步，不提供寫入按鈕。
+- CI 技術債清理：
+  - `test_gitea_webhook.py::test_webhook_push_event` 在 ASGITransport 會等待 FastAPI background task，進而真的觸發 push review 重活並卡住 CI。
+  - 在 `MOCK_MODE=true` 時，Gitea PR / Push webhook 僅驗證 HTTP 接受與 review id，不排入背景 code review task；production `MOCK_MODE=false` 行為不變。
+
+**local verification**：
+
+```text
+python3 -m py_compile apps/api/src/models/governance.py apps/api/src/services/governance_km_stale_review_service.py apps/api/src/api/v1/ai_governance.py apps/api/src/api/v1/gitea_webhook.py apps/api/tests/test_ai_governance_endpoints.py apps/api/tests/test_gitea_webhook.py -> OK
+/Users/ogt/.pyenv/shims/ruff check apps/api/src/models/governance.py apps/api/src/services/governance_km_stale_review_service.py apps/api/src/api/v1/ai_governance.py apps/api/src/api/v1/gitea_webhook.py apps/api/tests/test_ai_governance_endpoints.py apps/api/tests/test_gitea_webhook.py -> OK
+DATABASE_URL='postgresql+asyncpg://test:test@localhost/test' /Users/ogt/.pyenv/shims/pytest apps/api/tests/test_ai_governance_endpoints.py apps/api/tests/test_governance_agent.py apps/api/tests/test_hermes_kb_growth_worker.py apps/api/tests/test_governance_dispatcher.py -q
+  -> 108 passed
+cd apps/api && DATABASE_URL='postgresql+asyncpg://ci:ci@localhost/ci' PYTHONFAULTHANDLER=1 /Users/ogt/.pyenv/shims/pytest tests/test_gitea_webhook.py tests/test_ai_governance_endpoints.py -q -p no:cacheprovider
+  -> 73 passed
+pnpm --filter @awoooi/web exec tsc --noEmit --incremental false -> OK
+pnpm --dir apps/web exec next lint --file 'src/app/[locale]/awooop/work-items/page.tsx' -> OK
+json parse apps/web/messages/zh-TW.json apps/web/messages/en.json -> OK
+git diff --check -> OK
+local Browser smoke:
+  /zh-TW/awooop/work-items?project_id=awoooi
+  hasAwoooP=true, hasBurnDown=true, hasCompletionQueue=true, hasCriticalError=false
+```
+
+**production deploy / smoke**：
+
+```text
+code commits:
+0a8a1507 feat(governance): surface stale km completion queue
+0e447bbe test(gitea): skip review background tasks in mock mode
+
+deploy marker:
+c16b2931 chore(cd): deploy 0e447bb [skip ci]
+
+Gitea Actions:
+3006 CD -> success
+  tests 3963 -> success
+  build-and-deploy 3964 -> success
+  post-deploy-checks 3965 -> success
+3007 AI Code Review -> success
+
+K8s:
+awoooi-api    image=.../api:0e447bbe47d3882b2ac1c33678b23b88c4c35031 ready=2/2
+awoooi-web    image=.../web:0e447bbe47d3882b2ac1c33678b23b88c4c35031 ready=2/2
+awoooi-worker image=.../api:0e447bbe47d3882b2ac1c33678b23b88c4c35031 ready=1/1
+
+completion queue API:
+schema_version=km_stale_owner_review_completion_queue_v1
+project_id=awoooi
+status_bucket=all
+total=11
+returned=11
+pending_count=10
+ready_count=10
+blocked_count=0
+completed_count=1
+failed_count=0
+writes_on_read=false
+manual_review_required=true
+batch_writes_allowed=false
+first=bf81a30d-6abe-4c0c-b4ba-9c0ba0d761bf|ready|pending|preview_stale_km_review_completion
+
+burn-down API:
+schema_version=km_stale_owner_review_burndown_v1
+burn_down_status=above_threshold
+entries_to_threshold=886
+pending_owner_reviews=10
+completed_owner_reviews=1
+
+frontend:
+GET /zh-TW/awooop/work-items?project_id=awoooi -> 200
+Browser production smoke:
+  hasAwoooP=true
+  hasCompletionQueue=true
+  hasReadyCount=true
+  hasCriticalError=false
+```
+
+**下一步**：
+
+- T161：completion queue 加上 owner-review 篩選 / 批次 dry-run preview，不做批次寫入；只把 ready/blocked/completed/failed 的操作路徑再收斂。
+- T162：把 KM stale completion 的 owner review 結果回寫到 Work Items summary 與 Telegram 詳情/歷史，讓告警卡也能看到 completion queue 狀態。
+
 ## 2026-05-24｜T159 KM stale owner-review burn-down dashboard

 **觸發**：