awoooi/docs/awooop/inventory/INV-7-pr-cutting-plan.md

INV-7: PR Cutting Plan

版本：v1.0 初稿 日期：2026-05-03（台北） 範圍：Phase 2 全部重構 PR 的切割方案（refactor-specialist 設計） 用途：避免大 PR 難以 review；每個 PR 獨立可合併、有 rollback 能力

---

原則

1. 每個 PR 必須可獨立合併（不依賴後 PR 才能運行）
2. 每個 PR 有 rollback 方式（revert commit 或 feature flag）
3. PR-01~05 無依賴，可並行；PR-06+ 有順序依賴

---

PR 清單

PR-01: telemetry.py hardcoded IP assert 移除

範圍：apps/api/src/core/telemetry.py:71（約 1-3 行） 前置：無 解決：P0-08 EwoooC 啟動失敗

# 修改前
if "192.168.0.188" not in endpoint:
    raise ValueError(f"Forbidden OTEL endpoint: {endpoint}")

# 修改後
allowed = [e.strip() for e in settings.ALLOWED_TELEMETRY_ENDPOINTS.split(",")]
if not any(a in endpoint for a in allowed):
    raise ValueError(f"Forbidden OTEL endpoint: {endpoint}")
# 同步在 config.py 加入 ALLOWED_TELEMETRY_ENDPOINTS = "192.168.0.188"（default）

review：vuln-verifier 風險：低（僅移除一個 IP assert）

---

PR-02: decision_manager.py silence key 常數化

範圍：apps/api/src/services/decision_manager.py:240（約 2 行） 前置：無 解決：P1-24 兩處定義不一致

# 修改前（decision_manager.py:240）
silence_key = f"telegram_silence:{target}"

# 修改後
from apps.api.src.services.telegram_gateway import SILENCE_KEY_PREFIX
silence_key = f"{SILENCE_KEY_PREFIX}{target}"

review：debugger（確認 SILENCE_KEY_PREFIX = "telegram_silence:"，功能等效） 風險：低

---

PR-03: ollama_auto_recovery.py 第二定義移除

範圍：apps/api/src/services/ollama_auto_recovery.py:230（約 5 行） 前置：需確認 INV-1 中 ollama:current_primary 的所有寫入點 解決：P0-11 GCP 三層拓撲遷移必裂

# 移除 ollama_auto_recovery.py 中第二個 ollama:current_primary 寫入點
# 統一從 config.py 或 ollama_failover_manager.py 讀取，不在 auto_recovery 自行決定 primary

review：tool-expert（確認 GCP 拓撲三層 failover 邏輯） 風險：中（影響 Ollama failover 路徑）

---

PR-04: registry.py _provider → __provider

範圍：apps/api/src/plugins/mcp/registry.py:24-71（約 20 行） 前置：無 解決：P1-05 _provider public 可繞過 audit

# 修改所有 self._provider → self.__provider
# 加 @property provider 讀取（需要時）
# 加 unit test:
#   with pytest.raises(AttributeError):
#       registry.__provider  # double underscore = name mangling

review：vuln-verifier 風險：低（Python name mangling，只影響直接反射存取）

---

PR-05: mcp_bridge.py namespace 動態化

範圍：apps/api/src/plugins/mcp/mcp_bridge.py:592,602,631,647,681（約 30 行） 前置：無（Phase 1 schema 未完成前，先改為 from settings fallback） 解決：P0-13 EwoooC K8s tool 無法使用

# Phase 1 前的過渡做法（PR-05a）：
DEFAULT_NAMESPACE = os.getenv("K8S_DEFAULT_NAMESPACE", "awoooi-prod")
namespace = parameters.get("namespace", DEFAULT_NAMESPACE)

# Phase 2 後的完整做法（PR-05b，需 Phase 1 schema 先完成）：
namespace = parameters.get("namespace",
    get_project_contract(project_id).allowed_k8s_namespaces[0])

review：tool-expert 風險：低（有 env fallback，功能等效）

---

PR-06: consensus_engine.py CONSENSUS_PREFIX 加 project 前綴

範圍：apps/api/src/services/consensus_engine.py（約 15 行） 前置：Redis 雙寫 Phase A 已完成（舊 consensus: key 已雙寫新 key） 解決：P0-12 consensus engine 多租戶跨 tenant 共用

# 修改前
CONSENSUS_PREFIX = "consensus:"

# 修改後（consensus engine 接受 project_id 參數）
def get_consensus_prefix(project_id: str) -> str:
    return f"{project_id}:consensus:"

review：db-expert（確認 consensus 語義正確）、debugger（regression） 風險：中（需 Redis 雙寫先完成）

---

PR-07: security hardening（nonce + webhook replay + approval policy）

範圍：

• apps/api/src/services/security_interceptor.py:451-490（nonce 重設計）
• apps/api/src/api/v1/webhooks.py:679-728（webhook timestamp/nonce）
• apps/api/src/services/decision_manager.py（requires_approval policy-derived） 前置：ADR-116 已 Accepted（規格凍結） 解決：P0-04、P0-05、P0-06（3 個 PoC 確認漏洞）

# security_interceptor.py: nonce 必須 HMAC(server_secret + nonce)
# webhooks.py: 加 X-Timestamp header 驗證 ±5min window + Redis NX nonce
# decision_manager.py: requires_approval 從 policy contract 讀，禁止 LLM output 決定

review：vuln-verifier（PoC 重跑驗證修補有效） 風險：高（安全修補，必須 PoC 驗證）

---

PR-08: Repository project_id filter 批次 1

範圍：

• IncidentRepository（incidents 表）
• PlaybookRepository（playbooks 表）
• KnowledgeRepository（knowledge_entries 表） 前置：Phase 1 schema migration 完成（project_id 欄位已存在） 解決：P0-03 30+ 業務表無 project_id filter

# 每個 repository 方法加 project_id 參數
# 例：
async def get_incident(self, incident_id: str, project_id: str) -> Incident:
    return await self.session.execute(
        select(Incident)
        .where(Incident.incident_id == incident_id)
        .where(Incident.project_id == project_id)  # 新增
    )

review：db-expert（query plan 確認） 風險：中（約 200 行；需 regression test）

---

PR-09: Repository project_id filter 批次 2

範圍：

• McpAuditRepository（加 trace_id + project_id）
• AiDecisionRepository（加 run_id + project_id）
• ApprovalRepository（加 trace_id + project_id） 前置：PR-08 合併後 解決：P0-03 繼續

review：db-expert + debugger（trace_id 貫穿驗證） 風險：中

---

PR-10: Background loop 標記（ADR-123）

範圍：apps/api/src/main.py（31 個 loop，約 150 行） 前置：ADR-123 已 Accepted 解決：P0-07 31 個 loop 無 project_id

# 每個 loop 的 context 加上標記
# platform_internal: asyncio.create_task 前設定 contextvars
# legacy_awoooi_default: fallback project_id = 'awoooi'

async def _run_with_project_context(coro, project_id: str):
    token = project_id_var.set(project_id)
    try:
        await coro
    finally:
        project_id_var.reset(token)

review：critic（確認標記正確） 風險：中（影響所有 background loop 的 logging context）

---

PR-11: AnomalyCounter per-project 改造

範圍：apps/api/src/services/anomaly_counter.py:790（約 80 行） 前置：PR-10 完成（loop 有 project_id context 後才能傳入） 解決：P1-17 AnomalyCounter 全域單例

# 修改前：全域單例，6 個 prefix 無 tenant
_anomaly_counter = AnomalyCounter(get_redis())

# 修改後：per-project 工廠
def get_anomaly_counter(project_id: str) -> AnomalyCounter:
    return AnomalyCounter(get_redis(), project_prefix=f"{project_id}:anomaly")

review：debugger（確認 6 個 prefix 全數改造） 風險：中

---

執行順序圖

並行群組 G-D（無依賴，可同時開）：
  PR-01, PR-02, PR-03, PR-04, PR-05

↓ Phase 1 Schema 完成後

並行群組 G-E（部分並行）：
  PR-07（安全修補，優先）
  PR-06（需 Redis 雙寫 Phase A）
  PR-08（需 Phase 1 schema）

↓ PR-08 合併後

  PR-09（依賴 PR-08）

↓ ADR-123 Accepted 後

  PR-10（background loop 標記）

↓ PR-10 合併後

  PR-11（AnomalyCounter）

---

驗收標準

• PR-01~05 全部合併（無依賴，Phase 0 完成後即可）
• PR-07 通過 vuln-verifier PoC 重跑驗證
• PR-08~09 通過 db-expert review（query plan 確認）
• PR-10~11 通過 regression test（31 個 loop logging context 正確）

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