75 lines
3.9 KiB
Markdown
75 lines
3.9 KiB
Markdown
# AGENTS.md
|
||
|
||
給 AI coding agent（Claude / Cursor / Codex / 其他）的專案工作準則。請在開始任務前讀過一遍，並在需要時翻閱對應子文件。
|
||
|
||
## 專案簡介
|
||
|
||
`template-monorepo` 是基於 [go-zero](https://github.com/zeromicro/go-zero) 的 API Gateway,採用「**模組化 Clean Architecture**」:每個業務模組（auth / member / notification / permission ...）放在 `internal/model/<module>/`,內部分 `domain`(介面 + enum + errors) / `repository`(Mongo / Redis 實作) / `usecase`(原子業務邏輯) / `config`。
|
||
|
||
跨模組編排（例如「發 OTP → 寄信 → 驗碼 → 更新 profile」）一律放在 `internal/logic/<module>/`,**usecase 不可呼叫其他 usecase**。
|
||
|
||
## 必讀文件
|
||
|
||
| 文件 | 何時讀 |
|
||
|---|---|
|
||
| [`generate/api/README.md`](generate/api/README.md) | 新增 / 修改 API 端點、type、文件分組、欄位描述、enum 列舉前 |
|
||
| [`generate/doc-generate/README.md`](generate/doc-generate/README.md) | 需要查 go-doc 支援的 tag / `@respdoc` 寫法時 |
|
||
| `internal/model/<module>/README.md` | 動到該模組的領域邏輯時 |
|
||
| `docs/model.md`(若存在) | 全局架構規範 |
|
||
|
||
## 標準工作流程
|
||
|
||
### 1. 修改 API（`.api` → handler / types / docs）
|
||
|
||
1. 編輯 `generate/api/*.api`(遵守 `generate/api/README.md` 的三條規則：tags 分組 / backtick 行末 `//` 中文 description / `options=A|B|C` enum)
|
||
2. `make gen-api` — 重新產生 `internal/handler/`、`internal/logic/`(已存在則不覆蓋)、`internal/types/types.go`
|
||
3. `make gen-doc` — 重新產生 `docs/openapi/gateway.yaml`(gitignore,本地驗證用)
|
||
4. 實作 / 修改 `internal/logic/<module>/<handler>_logic.go` 的業務邏輯
|
||
5. `go build ./...` 確保編譯通過
|
||
6. `make lint` / `make test` 視改動範圍跑
|
||
|
||
### 2. 新增 / 修改業務模組
|
||
|
||
- 領域介面與型別放 `internal/model/<module>/domain/`
|
||
- Mongo / Redis 實作放 `internal/model/<module>/repository/`
|
||
- 原子 usecase 放 `internal/model/<module>/usecase/`(**不可**互相呼叫)
|
||
- 多步驟流程編排放 `internal/logic/<module>/`
|
||
- 模組的對外裝配入口統一在 `internal/model/<module>/usecase/module.go`,並從 `internal/svc/service_context.go` 注入
|
||
|
||
### 3. 錯誤碼
|
||
|
||
- 業務碼格式 `SSCCCDDD`(scope * 1_000_000 + category * 1_000 + detail)
|
||
- Scope 註冊在 `internal/library/errors/code/types.go`(Facade=10, Auth=28, Member=29, Notification=30, Permission=31)
|
||
- 新增 scope 時:同步更新 `gateway.api` 的 `bizCodeEnumDescription`
|
||
|
||
### 4. Redis / Mongo / 設定
|
||
|
||
- 每個模組的設定型別放 `internal/model/<module>/config/config.go`,再合入 `internal/config/config.go` 的 `Config` struct
|
||
- Redis client 共用 `internal/library/redis/`,需 Pub/Sub 用 `client.PubSubClient()`
|
||
- Mongo index 註冊到 `cmd/mongo-index/main.go`(在 `run()` 裡呼叫 `<module>repo.EnsureMongoIndexes`)
|
||
|
||
## 通用準則
|
||
|
||
- **回應 traditional Chinese**(繁體中文)
|
||
- 程式碼註解只寫「為什麼」、邊界條件、trade-off,**不寫**「import the module / increment counter」這類顯而易見的描述
|
||
- 不主動建立 `*.md` 文件,除非使用者明確要求
|
||
- 改 git config / 強制 push / `rm -rf` 等破壞性操作 **必須**先取得使用者同意
|
||
- 不要在沒被要求時直接 commit;commit 前先 `git status` / `git diff` 確認
|
||
- commit message 用繁中描述「為什麼」改,不是「改了什麼」
|
||
|
||
## 指令速查
|
||
|
||
| 指令 | 用途 |
|
||
|---|---|
|
||
| `make gen-api` | `.api` → handler / logic(skip exists)/ types |
|
||
| `make gen-doc` | `.api` → `docs/openapi/gateway.yaml` |
|
||
| `make gen-mock` | 模組 mock(gomock) |
|
||
| `make tools` | 安裝 goctl / goimports / golangci-lint |
|
||
| `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 mongo-index` | 建立 / 更新 Mongo 索引 |
|
||
|
||
完整列表跑 `make help`。
|