# API 定義（goctl + go-doc 共用）

## 檔案

| 檔案 | 用途 |
|------|------|
| `gateway.api` | 入口：`info()` + `import` |
| `common.api` | 共用文件型別（`APIErrorStatus`、`ErrorDetail`） |
| `auth.api` | Auth 路由（scope 28） |
| `member.api` | Member 路由（scope 29） |
| `normal.api` | 路由與業務 `data` 型別 |

## 指令

```bash
make gen-api   # 生成 handler / logic / types
make gen-doc   # 生成 docs/openapi/gateway.yaml（OpenAPI 3.0）
```

## 註解約定

- **Logic `returns`**：只寫業務 data（如 `PingData`）
- **文件 `@respdoc`**：寫實際 HTTP JSON（如 `PingOKStatus`、`APIErrorStatus`）
- **`@doc`**：單一 API 的 summary / description
- 多狀態碼用 `/* @respdoc-200 ... */` 區塊，放在 `@handler` 前
- **Request 驗證**：欄位可加 `validate:"required,email"` 等 tag；`make gen-api` 後 handler 會自動 `ValidateAll`（見 `generate/goctl/api/handler.tpl`）

## 與 runtime 對齊

Handler 使用 `response.Write` 輸出：

```json
{ "code": 102000, "message": "SUCCESS", "data": { ... } }
```

失敗時含 `error.biz_code` / `error.scope` 等欄位。Handler parse 錯誤為 Facade scope（`10101000`）；各模組 logic/usecase 使用對應 scope（Auth=28、Member=29）。