# Module Development Playbook

## 目的

這份是新模組開發手冊。每次新增模組都照這份走，避免架構偏移與重複返工。

## 開發前 Gate（必過）

### Gate 1：需求與範圍

- 模組名稱、目標使用者、成功指標
- in-scope / out-of-scope
- 是否影響既有主線流程

### Gate 2：資料邊界

- 先套 [DATA_OWNERSHIP_MATRIX.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/DATA_OWNERSHIP_MATRIX.md)
- 明確列出哪些 entity 放 Directus、哪些放 native

### Gate 3：API 邊界

- Admin / Editor / Runtime 入口放哪裡
- DTO 與錯誤碼策略是否已定義
- 是否需升 API version

### Gate 4：UI/UX 與流程

- 是否符合「流程化、簡單化、中文化」
- 是否對行銷人員友善（非工程術語）

## 開發中 Gate（必做）

- 每個里程碑更新：
  - `docs/EXECUTION_PLAN.md`
  - `docs/CURRENT_WORK_ITEMS.md`
- 不在 `ROADMAP.md` 寫細節流水帳
- PR 要附上：
  - 規格對應章節
  - 驗收案例
  - 風險與回滾方式

## 開發後 Gate（上線前）

- 契約檢查：對齊 [API_CONTRACT_MASTER.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/backend/API_CONTRACT_MASTER.md)
- 驗收檢查：對齊 [TEST_ACCEPTANCE_MASTER.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/validation/TEST_ACCEPTANCE_MASTER.md)
- 營運檢查：對齊 [RELEASE_OPERATIONS_MASTER.md](/Users/chirs/Documents/workspace/marketing/mkt.ose.tw/docs/operations/RELEASE_OPERATIONS_MASTER.md)

## 新模組文件清單（最小）

1. 模組規格（用模板）
2. API 契約差異（若有）
3. 測試案例與 DoD
4. 上線與回滾計畫

## 不可踩紅線

- 不新增 frontend 直連 Directus 的新業務邏輯。
- 不把 high-frequency runtime path 設計在 Directus revision 流。
- 不先做視覺 polish 而跳過主流程可用性驗收。