balantrapu87/amds

Motion Studio SDLC 執行手冊

當需要在此儲存庫中實作功能或修復錯誤時，請依序執行以下精確步驟：

步驟 1：合約同步（規格閘門）

1. 檢查 engine/schemas.py 和 remotion/src/types.ts。
2. 新增或修改欄位以滿足功能需求。
3. 驗證 Pydantic 模型可編譯：

   python3 -c "import engine.schemas as s; print('Schemas OK')"
   

   （注意：如果存在專案虛擬環境，請透過 .venv/bin/python3 執行）。
4. 在兩種語言的合約對齊之前，絕對不要進行實作程式碼。

步驟 2：紅燈階段（撰寫失敗測試）

1. 在 tests/（Pytest）或 remotion/src/__tests__/（Vitest/Jest）下撰寫新的測試檔案或測試案例。
2. 斷言 schema 驗證、邊界情況以及預期的序列化輸出。
3. 執行測試並確認失敗：

   pytest tests/
   # 如果 `remotion/package.json` 中已設定前端測試執行器：
   npm --prefix remotion test -- --run
   

4. 記錄失敗追蹤。如果測試立即通過，請重寫它以測試實際的新功能。僅當測試因預期斷言而失敗時，才滿足紅燈階段。

步驟 3：綠燈階段（最小實作）

1. 在 engine/ 或 remotion/src/ 中撰寫最少量的程式碼，以使失敗的測試通過。
2. 在 Remotion 中，嚴格遵守確定性幀法則：
   • 推導必須嚴格來自 useCurrentFrame() 和 useVideoConfig()。
   • 絕不使用 Date.now()、Math.random() 或無界 requestAnimationFrame()。
3. 保留現有的架構模式（<Series>、<Sequence>、<ThreeScene>、<KineticScene>）。
4. 確保向量素材根據 remotion/svgo.config.mjs 保留 ID 和類別，以便 GSAP 定位。

步驟 4：品質閘門與自動自我修復循環

追蹤循環迭代計數器（ATTEMPT ∈ {1, 2, 3}）。依序執行每個閘門，不要遮蓋退出碼（不要附加 || true）：

# 第 1 層：靜態型別分析
python3 -m mypy engine/schemas.py engine/api.py
npm --prefix remotion run build -- --bundle-cache=false

# 第 2 層：自動化測試套件
pytest tests/
# 如果 `remotion/package.json` 中已設定前端測試執行器：
npm --prefix remotion test -- --run

# 第 3 層：無頭 Chromium 幀柵格化
(cd remotion && npx remotion still src/index.ts MainComposition /tmp/smoke.png \
  --props='{"scenes":[],"theme":{}}' \
  --gl=angle \
  --overwrite)

自我修復與回滾策略

• 失敗時（嘗試 1 或 2）：

  1. 擷取確切的檔案路徑、失敗行號和 stderr/traceback。
  2. 實作一個完全針對報告錯誤的最小目標修補程式。
  3. 增加 ATTEMPT 並重新開始第 1 層。

• 失敗時（嘗試 3 - 預算耗盡）： 立即停止推測性修改，並僅還原已更改和建立的功能檔案（絕不進行全面全域清理）：

  # 第 4 層耗盡回退：僅針對功能程式碼範圍
  git restore --staged --worktree engine/ remotion/ tests/
  git clean -fd engine/ remotion/ tests/
  rm -f /tmp/smoke.png
  echo "品質閘門在 3 次嘗試後失敗。目標程式碼路徑已還原為乾淨基準。"
  exit 1
  

  （替代方案：若要保留工作供事後分析：git stash push -u -m "sdlc-failed-attempt-$(date +%s)" -- engine/ remotion/ tests/）

• 成功時（所有層級退出碼為 0）： 移除暫存產物並建立已驗證的提交：

  rm -f /tmp/smoke.png
  git add engine/ remotion/ tests/
  git commit -m "feat(motion-sdlc): implement verified feature with green test gate"