awoooi/docs/awooop/inventory/INV-5-migration-compatibility-matrix.md

INV-5: Migration Compatibility Matrix

版本：v1.0 初稿 日期：2026-05-03（台北） 範圍：apps/api/pyproject.toml 實際版本 + AwoooP Phase 1 migration 需求 用途：Phase 1 schema migration 前確認版本相容性，避免 breaking change 踩雷

---

1. 當前依賴版本（從 pyproject.toml 實際讀取）

套件	當前約束	對 AwoooP Phase 1 的影響
Python	>=3.11	✅ 足夠；asyncio.TaskGroup（3.11）可用
FastAPI	>=0.115.0	✅ 0.115 已支援 lifespan context manager
SQLAlchemy	>=2.0.0 ✅ 已是 2.x	✅ mapped_column、DeclarativeBase、async session 均可用
Pydantic	>=2.5.0 ✅ 已是 v2	✅ model_validator、field_validator v2 語法可直接用
pydantic-settings	>=2.1.0	✅
asyncpg	>=0.29.0	✅ 支援 PostgreSQL 15/16
redis	>=5.0.0	✅ redis-py 5.x 支援 cluster mode + NX
Alembic	未列出（透過 SQLAlchemy 間接）	⚠️ 需確認版本；建議鎖定 >=1.13.0
Langfuse	>=2.0.0,<3.0.0（鎖定）	✅ 無 AwoooP 影響，保持不變
opentelemetry	>=1.20.0	✅ GenAI semantic conventions 需要 >=1.25.0（ADR-121）
claude-agent-sdk	>=0.1.50	✅ 已使用

---

2. 重要發現

✅ SQLAlchemy 已是 2.x：MASTER-WORKPLAN 中「ORM 1.x vs 2.x」問題已不存在。

• mapped_column、relationship、async session 均可正常用
• 但仍需確認：AwoooP 新 model 使用正確的 2.x 寫法（DeclarativeBase 而非舊 declarative_base()）

✅ Pydantic 已是 v2：六合約 Pydantic models 可直接用 v2 語法。

⚠️ Alembic 版本未鎖定：

• apps/api/migrations/ 有大量 .sql 手寫 migration（非 Alembic auto-generate）
• AwoooP Phase 1 要決定：繼續手寫 SQL migration，還是引入 Alembic autogenerate？
• 建議：保持手寫 SQL（現有慣例），每個 migration 強制有 down migration

⚠️ OTel 版本需升級（ADR-121）：

• GenAI Semantic Conventions 需要 opentelemetry-semantic-conventions>=0.46b0（含 gen_ai.* namespace）
• 當前 >=1.20.0 可能不夠，需要 >=1.25.0
• 升級風險：低（向後相容）；需要加入 opentelemetry-semantic-conventions 依賴

---

3. AwoooP Phase 1 新依賴需求

套件	版本	用途	是否需要新增
pg_partman（PostgreSQL extension）	>=4.7.0	高流量表 partition 自動管理	⚠️ 需在 DB 層安裝，非 Python 套件
opentelemetry-semantic-conventions	>=0.46b0	OTel GenAI attribute（ADR-121）	✅ 需新增到 pyproject.toml
PgBouncer	>=1.21.0	Connection pool（tool-expert 需求）	⚠️ Infrastructure，非 Python 套件

---

4. Migration SQL 版本相容性

Migration 問題	當前狀態	修補方式
adr105_mcp_audit_snapshots.sql 建表 mcp_audit_snapshots，但 models.py 用 mcp_audit_log	⚠️ 衝突	確認是否已 rollback；若 mcp_audit_log 是現行表，則 mcp_audit_snapshots 已廢棄
部分 migration 無 rollback SQL	⚠️ MASTER-WORKPLAN P0-02	Phase 1 新 migration 強制加 down migration
ARRAY 型別在部分 migration 用 TEXT[]，在其他用 JSONB	🟠 不一致	AwoooP 新表一律用 JSONB（fix_playbooks_array_to_jsonb.sql 已示範）

---

5. SQLAlchemy 2.x 正確寫法確認清單（Phase 1 新 model 必須遵守）

# ✅ 正確（SQLAlchemy 2.x）
from sqlalchemy.orm import DeclarativeBase, mapped_column, Mapped
from sqlalchemy import String, DateTime, func
from typing import Optional

class Base(DeclarativeBase):
    pass

class AwooopProject(Base):
    __tablename__ = "awooop_projects"
    project_id: Mapped[str] = mapped_column(String(64), primary_key=True)
    display_name: Mapped[str] = mapped_column(String(128), nullable=False)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now()
    )
    migration_mode: Mapped[str] = mapped_column(
        String(32), nullable=False, default="legacy_awoooi_default"
    )

# ❌ 舊寫法（SQLAlchemy 1.x，不要用）
# from sqlalchemy.ext.declarative import declarative_base
# Base = declarative_base()
# project_id = Column(String(64), primary_key=True)

---

6. 版本兼容風險清單

風險	嚴重度	緩解方式
pg_partman 未安裝，partition 手動建立出錯	中	Phase 1 先不建 partition，只規劃；Phase 4 前安裝 pg_partman
OTel semantic conventions 版本不足	低	Phase 4 前升級（非 Phase 1 阻擋項）
PgBouncer 未安裝，AwoooP worker 壓力測試可能爆連接	中	Phase 4（platform shell）前安裝
Alembic 未鎖定，CI 環境版本飄移	低	鎖定 alembic>=1.13.0 加入 pyproject.toml

---

7. 驗收標準

• Phase 1 所有新 migration 使用 SQLAlchemy 2.x mapped_column 語法
• 所有新 migration 有 down migration SQL
• mcp_audit_snapshots vs mcp_audit_log 衝突已解決（確認哪個是現行表）
• pg_partman 安裝計畫已寫入 runbook

最後更新：2026-05-03（台北）