digimon
/
template-monorepo
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
template-monorepo/AGENTS.md

40 lines
1.9 KiB
Markdown
Raw Permalink Normal View History

docs(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
# AGENTS.md
add fix eage case
2026-05-26 06:05:33 +00:00
`template-monorepo` 是基於 [go-zero](https://github.com/zeromicro/go-zero) 的 API Gateway，採用「模組化 Clean Architecture」。
docs(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
add fix eage case
2026-05-26 06:05:33 +00:00
完整的 AI agent 工作準則請見 **[docs/AGENTS.md](docs/AGENTS.md)**（Cursor / Claude / Codex / 其他 agent 皆適用）。
docs(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
add fix eage case
2026-05-26 06:05:33 +00:00
## 一分鐘快速理解
docs(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
add fix eage case
2026-05-26 06:05:33 +00:00
- **業務模組** 一律放 `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(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
add fix eage case
2026-05-26 06:05:33 +00:00
## 常用入口
docs(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
add fix eage case
2026-05-26 06:05:33 +00:00
| 文件 | 用途 |
docs(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
|---|---|
add fix eage case
2026-05-26 06:05:33 +00:00
| [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 測試流程 |
docs(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
## 指令速查
add fix eage case
2026-05-26 06:05:33 +00:00
```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
```
docs(api): group OpenAPI by tags + add Chinese field descriptions and enums Make the generated docs/openapi/gateway.yaml usable by adding three things go-doc parses out of the .api source: - @server tags + summary on every block → Swagger UI groups endpoints (Auth / Member / Permission / Normal) instead of dumping everything under "default". - backtick end-of-line // 中文 on every Request field → property descriptions in the schema. go-doc only reads the trailing comment, not the line above, so all comments are placed on the same line as the tag. - options=A|B|C in json/form tags wherever validate:"oneof=..." exists → enum dropdowns. The validate tag is kept for runtime validation; go-zero also enforces options= at bind time. Codify the rules in generate/api/README.md (tags / 行末註解 / options=) and add AGENTS.md at repo root so any AI agent (Claude / Cursor / Codex) picks them up automatically when working on the project. types.go regenerated via make gen-api to keep json tags in sync. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 09:15:25 +00:00
add fix eage case
2026-05-26 06:05:33 +00:00
完整列表：`make help`。