diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md index 3229f7fb..8dd793d5 100644 --- a/docs/LOGBOOK.md +++ b/docs/LOGBOOK.md @@ -1,3 +1,105 @@ +## 2026-05-24|T159 KM stale owner-review burn-down dashboard + +**觸發**: + +- T158 已把 pending owner-review dispatch 顯示成工作台,但 operator 還需要直接看 stale ratio 是否因 owner-approved completion 而下降。 +- 使用者要求前端要能呈現「已完成 / 正在推進 / 卡在哪個階段」,不能只靠 Telegram 或單筆按鈕回覆。 +- 本階段目標是把 owner-review、completion audit、stale ratio recheck 與剩餘門檻差距集中成 read-only burn-down 面板。 + +**修正**: + +- 新增 `GET /api/v1/ai/governance/km-stale-owner-review-burndown`: + - schema `km_stale_owner_review_burndown_v1`。 + - 回傳 current stale ratio snapshot、距離 20% 門檻仍需處理幾筆、pending/completed owner review、completion audit/recheck 總數。 + - 回傳最近 owner-approved completion trail,包含 source dispatch、recheck dispatch、workflow stage、review outcome、stale count/ratio delta。 + - read-only:`writes_on_read=false`、`manual_review_required=true`。 +- AwoooP Work Items / AI 治理新增 `Stale ratio burn-down` 面板: + - 顯示目前陳舊比例、陳舊/總數、待審/完成、最新 delta。 + - 顯示 completion audit / recheck count 與 guardrail。 + - 顯示最近 completion trail,和 T158 Owner review 工作台放在同一個治理區塊。 +- `km_stale_ratio_recheck` context 補上 `project_id`,讓後續 burn-down 與多租戶查詢能穩定對齊。 + +**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/tests/test_ai_governance_endpoints.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/tests/test_ai_governance_endpoints.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 + -> 105 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 +``` + +**production deploy / smoke**: + +```text +code commit: +ded2223d feat(governance): surface stale km burndown + +deploy marker: +a68bc7f0 chore(cd): deploy ded2223 [skip ci] + +Gitea Actions: +2993 CD -> success + tests 3939 -> success + build-and-deploy 3940 -> success + post-deploy-checks 3941 -> success +2994 AI Code Review -> success +2995 Type Sync Check -> success + +K8s: +awoooi-api image=.../api:ded2223d14c184f7fc6b9edd078cb1adce23aed9 ready=2/2 +awoooi-web image=.../web:ded2223d14c184f7fc6b9edd078cb1adce23aed9 ready=2/2 +awoooi-worker image=.../api:ded2223d14c184f7fc6b9edd078cb1adce23aed9 ready=1/1 + +burn-down API: +schema_version=km_stale_owner_review_burndown_v1 +project_id=awoooi +burn_down_status=above_threshold +current_snapshot=1491/3027 ratio=0.493 threshold=0.2 stale_days=7 +entries_to_threshold=886 +pending_owner_reviews=10 +completed_owner_reviews=1 +completion_audit_total=1 +stale_ratio_recheck_total=1 +writes_on_read=false +manual_review_required=true +latest completion: + audit=c0a62d49-448b-4223-ae80-1abb6e361260 + entry=01951ae2-87e3-46ce-afb6-e7e7e1fb16ba + stage=km_writeback_after_approval + outcome=refresh_with_evidence + recheck=a2a7f76f-e257-41ee-bd94-186c42975a40 + +frontend: +GET /zh-TW/awooop/work-items?project_id=awoooi -> 200 +Browser smoke: + hasCriticalError=false + hasAwoooP=true + hasNav=true + hasBurnDown=true + hasRemaining=true + hasOwnerReviewInbox=true + screenshot=/tmp/t159-work-items-burndown-visible.png +``` + +**處置判讀**: + +- T159 讓 KM governance 的「數據是否真的下降」從隱藏在 completion 回覆,升級成 operator console 的常駐 burn-down read model。 +- 目前 production 仍高於 20% 門檻:1491/3027 = 49.3%,距離門檻約 886 筆;所以 knowledge_degradation 告警不應關閉。 +- 下一段應做 T160:owner review completion 的批次輔助與 stale ratio burn-down 篩選,讓已審核項目能更快完成並把 pending/completed/failed 分流清楚。 + +**目前整體進度**: + +- AwoooP 告警可觀測鏈:約 98.5%。 +- 治理告警可讀性 / 可處置性:約 97.5%。 +- KM stale governance 自動化:約 95.5%。 +- Frontend AI 自動化管理介面同步:約 98.5%。 +- Runtime rollout 穩定性:約 97.5%。 +- 完整 AI 自動化管理產品化:約 96.5%。 + ## 2026-05-24|T158 KM stale owner-review inbox / per-item completion surface **觸發**: