強化 CD Gunicorn 掛載與 metrics 降噪

docs/AI_INTELLIGENCE_MODULE_SOT.md

@@ -1,8 +1,8 @@
 # MOMO PRO — AI 競價情報模組 Single Source of Truth
 
-> **最後更新**: 2026-04-29 (台北時間)
-> **狀態**: 🟢 四 AI Agent 自動化閉環已落地 — EventRouter / AutoHeal / OpenClaw Memory / ElephantAlpha bridge / Prometheus metrics / Smoke Dashboard / Smoke Trend Management / Telegram Summary / Grafana provisioning / Prometheus scrape 具測試覆蓋
-> **適用版本**: V10.11 AI Automation Metrics Scrape 架構
+> **最後更新**: 2026-04-30 (台北時間)
+> **狀態**: 🟢 四 AI Agent 自動化閉環已落地 — EventRouter / AutoHeal / OpenClaw Memory / ElephantAlpha bridge / Prometheus metrics / Smoke Dashboard / Smoke Trend Management / Telegram Summary / Grafana provisioning / Prometheus scrape / CD Gunicorn 掛載具測試覆蓋
+> **適用版本**: V10.13 CD Gunicorn 掛載強化版
 
 ---
 
@@ -69,6 +69,8 @@ SQL漏斗(~300筆)
 - Smoke 每日摘要支援手動 Telegram 推播，並由 `momo-scheduler` 每日 09:10 呼叫 `run_ai_smoke_daily_summary_task()`。
 - Grafana provisioning 新增 `docker/grafana/provisioning/dashboards/json/ai-automation-overview.json`，觀測 EventRouter dispatch/latency、safe action、Telegram replay 與 AutoHeal action/duration。
 - Active monitoring stack 使用 `monitoring/prometheus.yml` 的 `momo-app` job scrape `momo-pro-system:80/metrics`；Prometheus container 需加入 `momo-network`。
+- `/metrics` 對 `realtime_sales_monthly` 只用 raw `SELECT COUNT(*)` 取得總筆數，避免 ORM schema drift 讓 Prometheus scrape 產生 warning。
+- `momo-app` 必須 bind mount `./gunicorn.conf.py:/app/gunicorn.conf.py:ro`，讓 CD sync/rebuild 後的 Gunicorn runtime 設定與 repo 保持一致。
 
 ---
 

docs/guides/devops_handbook.md

@@ -77,3 +77,12 @@
 - **原因**: `docker-compose.yml` 遺漏了 `/app/routes` 的 Volume 掛載。
 - **檢查**: `docker inspect momo-telegram-bot | jq '.[0].Mounts'`。
 - **修復**: 確保 `volumes` 段落包含 `- ./routes:/app/routes:ro`。
+
+### 5. Gunicorn 設定更新後仍吃舊版 image 內容
+- **原因**: `gunicorn.conf.py` 若沒有 bind mount，容器 restart 會使用 image 內建檔案；host 上新版設定不會自動進入 `/app/gunicorn.conf.py`。
+- **檢查**: `docker inspect momo-pro-system | jq '.[0].Mounts'`，確認有 `/app/gunicorn.conf.py`。
+- **修復**: `docker-compose.yml` 的 `momo-app.volumes` 必須包含 `- ./gunicorn.conf.py:/app/gunicorn.conf.py:ro`，再走 CD rebuild 或精準 recreate app/scheduler/bot。
+
+### 6. `/metrics` 持續出現 realtime_sales_monthly 欄位不存在 warning
+- **原因**: 線上表 schema 可能比 ORM 窄，ORM count 會包子查詢並引用不存在欄位。
+- **修復**: metrics 只需要總筆數時使用 `SELECT COUNT(*) FROM realtime_sales_monthly`，不要透過 `session.query(RealtimeSalesMonthly).count()`。

docs/memory/README.md

@@ -16,6 +16,7 @@
 | `ai_automation_closure_20260429.md` | 四 AI Agent 自動化閉環、Smoke、metrics 與 Grafana 觀測實況 | 接續 AI 自動化、EventRouter、AutoHeal、OpenClaw memory、ElephantAlpha 編排、可觀測性時 |
 | `credentials_passbook.md` | 伺服器、帳密、埠位對照 | 需要維運、部署、憑證核對時 |
 | `feedback_db_metadata_import.md` | SQLAlchemy metadata / `create_all()` 漏表鐵律 | 新增 model、修 schema、排查 fresh env 漏表時 |
+| `db_connection_pool_singleton_20260430.md` | PostgreSQL `too many clients` 連線池放大事故與 DatabaseManager singleton 修正 | 排查 DB 連線數暴增、route 內反覆初始化 DatabaseManager、SQLAlchemy engine/pool 行為時 |
 | `project_phase3f_cleanup_roadmap.md` | ADR-017 執行矩陣與階段紅線 | 正在做 3f 模組化收尾時 |
 | `schema_inventory_baseline.md` | DB 表分類與 drift 基線 | 要收斂 migration / ORM / raw SQL 真相時 |
 

docs/memory/ai_automation_closure_20260429.md

@@ -20,6 +20,8 @@
 - 2026-04-30 發現並修復 `gunicorn.conf.py` `post_fork` 掃到 Flask/Werkzeug LocalProxy 導致 worker boot fail 的問題。
 - 2026-04-30 CD 健康檢查曾因 rebuild 後短暫 502 太早失敗；已改為 internal `docker exec momo-pro-system /health` + external `https://mo.wooo.work/health` 雙檢查，重試約 3 分鐘。
 - 2026-04-30 CD Sync 模式曾只 rsync + `docker compose up -d`，導致 host 檔案已是新版但 gunicorn process 仍跑舊版；已補 `docker compose restart momo-app scheduler telegram-bot`。
+- 2026-04-30 `gunicorn.conf.py` 不是 app container bind mount，曾導致手動 restart 後回吃 image 內舊設定；`momo-app` 已補 `./gunicorn.conf.py:/app/gunicorn.conf.py:ro`。
+- 2026-04-30 `/metrics` 對 `realtime_sales_monthly` 改用 raw `SELECT COUNT(*)`，避免 ORM 欄位與線上表 schema drift 時每次 Prometheus scrape 都產生 warning。
 
 ## 已落地範圍
 
@@ -38,6 +40,7 @@
 - Daily summary API：`POST /api/ai-automation/smoke/daily-summary/send`。
 - Grafana dashboard 檔案：`docker/grafana/provisioning/dashboards/json/ai-automation-overview.json`；provider 會載入 JSON 目錄，不需要修改 dashboard provider。
 - Active monitoring 使用 `monitoring/prometheus.yml`，不是 `docker/prometheus/prometheus.yml`；若線上 panel 無資料，先查 Prometheus 是否有 `momo-app` target。
+- App container 的 runtime `gunicorn.conf.py` 由 `docker-compose.yml` bind mount；若未來改 gunicorn 設定，不應再手動 `docker cp` 作為常態流程。
 
 ## 驗證紀錄
 
@@ -51,6 +54,8 @@
 - 2026-04-30 Gunicorn LocalProxy 修復：新增 `tests/test_gunicorn_config.py`。
 - 2026-04-30 Prometheus scrape 修復：新增 `tests/test_prometheus_ai_automation_scrape.py`。
 - 2026-04-30 CD health check hardening：新增 `tests/test_cd_health_check.py`。
+- 2026-04-30 CD Gunicorn mount hardening：新增 `tests/test_docker_compose_runtime_mounts.py`。
+- 2026-04-30 Metrics schema drift 降噪：`tests/test_ai_automation_metrics.py` 覆蓋 raw sales count query。
 - 2026-04-29 L2 安全記憶批次：`24 passed`。
 - collect-only：`48 tests collected`。
 - `git diff --check` 已通過。

docs/memory/db_connection_pool_singleton_20260430.md

@@ -0,0 +1,15 @@
+# DB Connection Pool Singleton Hotfix (2026-04-30)
+
+## 背景
+
+`/daily_sales` 出現 PostgreSQL `FATAL: sorry, too many clients already`。根因不是單一查詢過重，而是多個 route 會在 request 內直接呼叫 `DatabaseManager()`，舊實作每次初始化都 `create_engine()`，導致同一個 worker process 內反覆建立新的 SQLAlchemy connection pool。
+
+## 修正
+
+`database/manager.py` 的 `DatabaseManager` 以 `(DATABASE_TYPE, effective_db_path)` 作為 key 快取 `engine` 與 `Session` factory。後續直接 `DatabaseManager()` 會共用同一組連線池，不再持續放大 PostgreSQL client 數。
+
+## 維運提醒
+
+- 若再次遇到 `too many clients already`，先檢查是否有新模組繞過 `database.manager.get_db_manager()` 或直接 `create_engine()`。
+- 熱修後需重啟 `momo-pro-system`，讓舊 process 釋放既有連線池。
+- 不需要重啟或重建 `momo-db`。

docs/memory/history_logs.md

@@ -33,6 +33,8 @@
 - **Grafana 線上載入與 scrape 修復**: 188 active Grafana 載入 4 dashboards；active Prometheus 補 `momo-app` scrape job，並修復 gunicorn preload LocalProxy boot crash。
 - **CD 健康檢查強化**: Gitea Actions health check 改為 internal container health + external URL 雙檢查，降低 rebuild 後短暫 502 誤判。
 - **CD Sync reload 修復**: rsync 後明確 restart 三容器，避免 bind-mounted Python 檔案更新但 gunicorn/scheduler/bot process 未 reload。
+- **CD Gunicorn 掛載強化**: `momo-app` 補 `./gunicorn.conf.py:/app/gunicorn.conf.py:ro`，避免容器 restart 後回吃 image 內舊 gunicorn 設定。
+- **Metrics schema drift 降噪**: `/metrics` 的 `realtime_sales_monthly` 總筆數改用 raw `COUNT(*)`，避免 ORM 欄位 drift 造成 Prometheus scrape warning。
 
 ### 2026-04-28~29：Phase 3e 重構大戰 + daily_sales cache 隱形 bug 根除
 - **app.py 縮減 -10.8%**: 7,386 → 6,590 行，11 commits 全綠零 502。