awoooi/docs/adr/ADR-013-code-annotation-standards.md

# ADR-013: Code Annotation Standards

> **狀態**: 🟡 草稿 (待 CTO 批准)
> **日期**: 2026-03-24
> **決策者**: CTO

## 背景

AWOOOI 專案缺乏統一的代碼註解規範，導致：
- Code Review 時對「是否需要註解」有爭論
- 新人入職時難以理解複雜邏輯
- 危險操作缺乏警示說明

## 決策

採用分層註解策略，區分「強制」與「建議」場景。

---

## 1. 強制註解場景 (Must Have)

以下場景**必須**有註解，否則 PR 不予合併：

### 1.1 安全相關
```python
# 🔐 Token 驗證: 檢查 JWT 是否過期且具有對應 Tier 權限
def verify_token(token: str, required_tier: int) -> bool:
```

### 1.2 複雜邏輯
```typescript
// 正則說明: 匹配 K8s Pod 名稱格式 <deployment>-<hash>-<random>
const POD_NAME_REGEX = /^(.+)-([a-f0-9]{8,10})-([a-z0-9]{5})$/
```

### 1.3 外部依賴
```python
# 🌐 外部 API: Alertmanager webhook，預期回應 200 OK
async def send_to_alertmanager(payload: dict) -> bool:
```

### 1.4 危險操作
```yaml
# 🔴 危險: 此 NetworkPolicy 控制 Worker 出站流量
# 修改前請確認 Redis/PostgreSQL 連線不受影響
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
```

---

## 2. 格式規範

### 2.1 Python (Google Style Docstring)

```python
def restart_pod(namespace: str, pod_name: str) -> bool:
    """重啟指定 Pod。

    Args:
        namespace: K8s 命名空間
        pod_name: Pod 名稱 (不含 hash 後綴)

    Returns:
        True 表示重啟成功

    Raises:
        K8sPermissionError: 缺少 delete pods 權限

    Warning:
        此操作會導致短暫服務中斷
    """
```

### 2.2 TypeScript (JSDoc)

```typescript
/**
 * 簽核待審批請求
 * @param id - Approval UUID
 * @param signerId - 簽核者 ID (需有對應 Tier 權限)
 * @returns 簽核結果，包含是否觸發執行
 * @throws {UnauthorizedError} 簽核者權限不足
 * @example
 * const result = await signApproval('abc-123', 'admin-001')
 * if (result.execution_triggered) { ... }
 */
async function signApproval(id: string, signerId: string): Promise<ApprovalResult>
```

### 2.3 YAML/Kubernetes

```yaml
# 🔴 危險操作標記
# 📝 用途說明
# ⚠️ 注意事項
```

---

## 3. 測試標記 (data-testid)

### 命名規則
```
<component>-<element>[-<action>]
```

### 範例
```tsx
<button data-testid="approval-card-approve-btn">
<input data-testid="search-input-filter">
<div data-testid="incident-list-container">
```

### 強制場景
- 所有可交互元素 (button, input, select)
- E2E 測試會定位的容器
- 動態渲染的列表項

---

## 4. 不需要註解的場景

- 自明的 CRUD 操作
- 標準庫/框架常見用法
- 已有 TypeScript 型別說明的參數

---

## 5. 執行方式

### Phase 1 (本週)
- [x] ADR-013 文件建立
- [ ] ESLint `require-jsdoc` 配置 (危險函數)
- [ ] Ruff D100 規則 (公開函數)

### Phase 2 (下週)
- [ ] 補齊 P0/P1 關鍵模組註解
- [ ] 補齊 data-testid (Approval/Incident)
- [ ] CI 加入 lint 檢查

### Phase 3 (持續)
- [ ] Code Review 強制執行
- [ ] 新代碼必須符合標準

---

## 6. 參考

- [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
- [JSDoc Reference](https://jsdoc.app/)
- [Testing Library - data-testid](https://testing-library.com/docs/queries/bytestid/)