# AGENTS.md

`template-monorepo` 是基於 [go-zero](https://github.com/zeromicro/go-zero) 的 API Gateway，採用「模組化 Clean Architecture」。

完整的 AI agent 工作準則請見 **[docs/AGENTS.md](docs/AGENTS.md)**（Cursor / Claude / Codex / 其他 agent 皆適用）。

## 一分鐘快速理解

- **業務模組** 一律放 `internal/model/<module>/`，內部分 `domain` / `repository` / `usecase` / `config`。
- **跨模組編排**（多 usecase 串接）放 `internal/logic/<module>/`；**usecase 不可呼叫其他 usecase**。
- **API** 由 `generate/api/*.api` 定義，`make gen-api` 產生 handler / types，`make gen-doc` 產生 OpenAPI。
- **錯誤碼** 8 碼 `SSCCCDDD`，全專案唯一在 `internal/library/errors`。
- **回應永遠用繁體中文。**

## 常用入口

| 文件 | 用途 |
|---|---|
| [docs/AGENTS.md](docs/AGENTS.md) | Agent 工作準則總覽（必讀） |
| [README.md](README.md) | 專案總覽、開發約定、HTTP / 錯誤格式 |
| [docs/model.md](docs/model.md) | `internal/model/{module}` 分層規範 |
| [generate/api/README.md](generate/api/README.md) | `.api` 寫法、`@respdoc`、middleware 宣告 |
| [internal/library/errors/README.md](internal/library/errors/README.md) | 8 碼錯誤碼設計與 HTTP 對照 |
| [docs/identity-member-design.md](docs/identity-member-design.md) | Identity / Member / Permission 跨模組架構 |
| [docs/auth-unified-registration.md](docs/auth-unified-registration.md) | 統一註冊／登入完整時序 |
| [docs/e2e-testing.md](docs/e2e-testing.md) | E2E 測試流程 |

## 指令速查

```bash
make gen-api        # .api → handler / logic(skip exists) / types
make gen-doc        # .api → docs/openapi/gateway.yaml
make fix            # gofmt + goimports + lint --fix + lint
make check          # fix + test（提交前必跑）
make run-dev        # 本機啟動（需 make deps-up）
make deps-up        # docker compose Mongo + Redis
```

完整列表：`make help`。