ewoooc/docs/memory/feedback_db_metadata_import.md

DB Metadata Import 鐵律

問題

Base.metadata.create_all() 只會建立已載入 metadata 的 model。若 model 檔沒有被 database/manager.py 或其他啟動必經路徑 import，新環境就會漏表，但既有環境可能因舊資料庫已存在而掩蓋問題。

鐵律

1. 新增 SQLAlchemy model 時，必須在 database/manager.py 顯式 import。
2. 禁止依賴 re-export shim 或副作用 import 讓 table 偷偷進 metadata。
3. 若 init SQL 已有表，仍要補 ORM 或在 ADR 中明確說明為外部管理表。
4. app.py 啟動 self-check 的 expected table 清單要同步更新。
5. 新環境驗收要跑：

python3 - <<'PY'
from database.manager import Base
print(len(Base.metadata.tables))
print(sorted(Base.metadata.tables))
PY

Phase 3f-0 決策

• database/manager.py 顯式載入 permission、AI history、autoheal、import、notification、PPT、vendor、realtime sales models。
• database/ai_models.py 移除 autoheal re-export shim；需要 autoheal model 的程式必須直接 import database.autoheal_models。
• database/realtime_sales_models.py 補 realtime_sales_monthly ORM，讓 metrics、匯入與啟動自檢有同一份 metadata 來源。
• PostgreSQL create_all() 必須經 process-local guard 與 advisory lock，避免多 worker 或多次 DatabaseManager() 在一般流程重複做 DDL 檢查。
• ORM 若對齊 init SQL 管理的表，必須同步 docker/postgres/init/01-init.sql，因 create_all() 不會 alter 已存在的窄表。