template-monorepo/README.md

# Portal API Gateway (PGW)

基於 [go-zero](https://github.com/zeromicro/go-zero) 的 API Gateway，提供統一 HTTP JSON 回應、8 碼業務錯誤碼，以及由 `.api` 定義驅動的程式碼與 OpenAPI 3.0 文件生成。

## 功能概覽

- **REST API**：go-zero `rest` 服務，預設 `http://0.0.0.0:8888`
- **統一回應格式**：成功 / 失敗皆為 `Status` envelope（`code`、`message`、`data`、`error`）
- **結構化錯誤**：8 碼 `SSCCCDDD`（Scope + Category + Detail），可映射 HTTP / gRPC
- **程式碼生成**：`goctl` + 自訂 handler 模板（自動 `response.Write`）
- **API 文件**：`go-doc` 由同一套 `.api` 產出 OpenAPI 3.0 YAML

## 環境需求

| 工具 | 必要 | 說明 |
|------|:----:|------|
| Go | ✓ | ≥ 1.26.1（見 `go.mod`） |
| Make | ✓ | 執行 `gen-api` / `gen-doc` 等 |
| [goctl](https://go-zero.dev/docs/tasks/installation/goctl) | ✓ | `make gen-api` 用；可 `make tools` 安裝 |
| goimports | 建議 | `make fmt` 用；`make tools` 安裝 |
| golangci-lint | 建議 | `make lint` 用；`make tools` 安裝（v2，見 `.golangci.yml`） |
| jq | 選用 | README 範例 `curl \| jq` |

請確認 **`$(go env GOPATH)/bin` 在 PATH**，否則 `go install` 的 `goctl` 找不到。

## 快速開始（首次）

```bash
cd gateway

# 1. 工具（goctl、goimports）
make tools

# 2. 依賴
go mod download

# 3. 依 .api 生成程式碼（可選，repo 內通常已有）
make gen-api

# 4. 啟動
make run
# 或：go run gateway.go -f etc/gateway.yaml
```

### 本機 Mongo + Redis（Notification / Member OTP）

需要持久化通知、異步重試或 member 驗證時：

```bash
make deps-up          # Mongo :27017、Redis :6379
make mongo-index      # 建立 notifications / notification_dlq 索引
make run-dev          # 使用 etc/gateway.dev.yaml
```

詳見 [deploy/README.md](deploy/README.md)、[etc/README.md](etc/README.md)。選用 MailHog：`make deps-up-smtp`。

產生 OpenAPI（會先編譯 `generate/doc-generate` 內的 go-doc）：

```bash
make gen-doc   # 輸出 docs/openapi/gateway.yaml
```

健康檢查：

```bash
curl -s http://127.0.0.1:8888/api/v1/health | jq
```

預期回應：

```json
{
  "code": 0,
  "message": "SUCCESS",
  "data": { "pong": "ok" }
}
```

## 常用指令

執行 `make` 或 `make help` 可看完整列表。

| 指令 | 說明 |
|------|------|
| `make tools` | 首次安裝 goctl、goimports |
| `make gen-api` | 由 `gateway.api` 生成 Go（自訂 `generate/goctl` 模板） |
| `make gen-doc` | 編譯 go-doc 並生成 `docs/openapi/gateway.yaml` |
| `make test` | 執行測試 |
| `make fmt` | gofmt + goimports |
| `make lint` | golangci-lint 靜態檢查（必須 0 issues） |
| `make lint-fix` | 自動修正可修的 lint / import 問題 |
| `make fix` | `fmt` + `lint-fix` + `lint`（提交前建議） |
| `make check` | `fix` + `test`（PR / AI 完成前必跑） |
| `make run` | 啟動 Gateway（無 DB） |
| `make deps-up` | Docker 啟動 Mongo + Redis |
| `make run-dev` | 啟動 Gateway（`etc/gateway.dev.yaml`，需 Docker） |
| `make config-check` | 驗證 yaml 可載入 |
| `make mongo-index` | 建立 notification Mongo 索引 |

## 專案結構

```
gateway/
├── gateway.go                 # 程式入口
├── etc/gateway.yaml           # 服務設定（埠號等）
├── generate/
│   ├── api/                   # API 定義（goctl + go-doc 共用）
│   ├── goctl/api/handler.tpl  # 自訂 handler 模板 → response.Write
│   └── doc-generate/          # go-doc（.api → OpenAPI）
├── internal/
│   ├── handler/               # HTTP handler（goctl 生成，response.Write）
│   ├── logic/                 # HTTP 編排：types ↔ usecase DTO，只回 data + error
│   ├── types/                 # goctl 生成的請求/回應型別
│   ├── response/              # 統一 JSON 回應封裝
│   ├── svc/                   # ServiceContext：組裝各模組 UseCase
│   ├── config/                # go-zero RestConf 等服務設定
│   ├── library/errors/        # 全專案唯一結構化錯誤（8 碼 SSCCCDDD）
│   ├── library/validate/      # struct 驗證（go-playground/validator + 翻譯）
│   ├── library/mongo/         # DocumentDB + Redis cache（mongo-driver v2）
│   ├── library/errlog/        # 可選 slog 日誌輔助
│   └── model/                 # 業務模型根目錄（見下方）
│       └── {module}/          # 例如 member/、order/
└── docs/
    ├── model.md               # model/{module} 內 entity / repository / usecase 細節
    └── openapi/               # gen-doc 輸出（預設 .gitignore）
```

### 業務模型（`internal/model/{module}/`）

業務領域程式碼一律放在 **`internal/model/`** 底下，再依模組分子目錄（例如 `internal/model/member/`）。**不使用 `pkg/`**。HTTP 層（handler / logic / types）仍由 goctl 管理；持久化與業務規則在 `model/{module}/` 內。

```
internal/model/
└── member/                  # 模組名稱（member、order…）
    ├── entity/              # MongoDB document（Account、User…）
    ├── enum/                # 列舉 / 值物件（Platform、Status…）
    ├── repository/          # Repository 介面 + 實作（Mongo / cache）
    ├── usecase/             # UseCase 介面、Request/Response DTO、實作
    ├── config/              # 模組用設定 struct（不含 go-zero RestConf）
    ├── errors.go            # 模組 sentinel（如 ErrNotFound），非第二套錯誤碼
    ├── const.go             # 模組常數
    ├── redis.go             # Redis key 命名與 helper
    └── mock/                # mockgen 產物，勿手改
```

**依賴方向：**

```
handler → logic → model/{module}/usecase（介面）
                      ↓
                model/{module}/repository（介面）
                      ↓
                entity / enum / MongoDB·Redis

entity、enum 不依賴 repository、usecase、logic
logic 不 import model/{module}/repository 或 model/{module}/entity
```

**請求鏈：**

```
HTTP Request
  → handler（response.Write）
  → logic（types ↔ usecase DTO）
  → model/{module}/usecase
  → model/{module}/repository
  → MongoDB / Redis
```

更細的 entity / repository / usecase 撰寫規則見 [docs/model.md](docs/model.md)。

更細的說明見各子目錄 README：

- [generate/api/README.md](generate/api/README.md) — `.api` 與 `@respdoc` 約定
- [internal/response/README.md](internal/response/README.md) — Handler / Logic 分工
- [internal/library/errors/README.md](internal/library/errors/README.md) — 錯誤碼與 HTTP 對照
- [internal/library/mongo/README.md](internal/library/mongo/README.md) — MongoDB / Redis cache 流程與用法
- [docs/model.md](docs/model.md) — `internal/model/{module}` 分層（entity / repository / usecase）
- [docs/identity-member-design.md](docs/identity-member-design.md) — **Draft** Identity / Member / Permission 模組架構（ZITADEL、LDAP、SCIM、B2B 自定義權限）

## 開發約定

### 1. 新增 API 流程

1. 在 `generate/api/` 新增或修改 `.api`（並在 `gateway.api` import）。
2. `make gen-api` 生成程式碼（**新** handler 會自動使用 `response.Write`；已存在檔案不會覆寫，需手動刪除後再生成或自行修改）。
3. 在 `internal/logic/` 做 types 映射並呼叫模組 UseCase，只回傳 **data** 與 **error**。
4. `make gen-doc` 更新 OpenAPI 文件。
5. `go test ./...`

### 2. Logic 與 Handler

```go
// internal/logic/... — 編排與映射；有持久化時呼叫 svcCtx.{Module}UC
var errb = errs.For(code.Facade)

func (l *PingLogic) Ping() (*types.PingData, error) {
    return &types.PingData{Pong: "ok"}, nil // 簡單 API 可直接回 types
}

// internal/handler/... — 由模板生成
data, err := l.Ping()
response.Write(r.Context(), w, data, err)
```

有 request 的 API 會自動包含 `httpx.Parse`；解析失敗會映射為 **400** `InputInvalidFormat`。

### 3. HTTP JSON 格式

**成功（HTTP 200）**

```json
{
  "code": 0,
  "message": "SUCCESS",
  "data": { }
}
```

**失敗（HTTP 依錯誤類別，如 404）**

```json
{
  "code": 10301000,
  "message": "user not found",
  "error": {
    "biz_code": "10301000",
    "scope": 10,
    "category": 301,
    "detail": 0
  }
}
```

### 4. 錯誤處理（全專案單一型別）

對外 API 只使用 `gateway/internal/library/errors` 的 `*errs.Error`（8 碼 `SSCCCDDD`）。**不要**在模組內再維護第二套業務錯誤碼套件。

各層職責：

| 層 | 職責 | 回傳 |
|----|------|------|
| **repository** | 忠實反映基礎設施（Mongo / Redis / driver） | `*errs.Error`（DB*、ResInvalidMeasureID 等）+ `WithCause`；可預期「無資料」可回模組 `errors.go` 的 **sentinel** |
| **usecase** | 業務規則（狀態、權限、組合多 repo） | `*errs.Error`（Res*、Auth*、Svc* 等）；sentinel 轉成對外語意；已是正確的 `*errs.Error` 可原樣往上傳 |
| **logic** | HTTP 輸入檢查、types 映射 | 僅在進 usecase 前用 `Input*`；其餘 **原樣** `return nil, err`，不二次包裝 |
| **handler** | 序列化 | `response.Write`（內建 `errs.FromError`） |

模組頂層 sentinel 範例（`internal/model/member/errors.go`，`package member`）：

```go
var (
    ErrNotFound        = errors.New("member: not found")
    ErrInvalidObjectID = errors.New("member: invalid object id")
)
```

Repository 對照建議：

| 狀況 | 回傳 |
|------|------|
| `mongo.ErrNoDocuments` | `member.ErrNotFound`（由 usecase 轉 `ResNotFound`） |
| ObjectID 格式錯 | `errb.ResInvalidMeasureID("account_id")` |
| duplicate key | `errb.DBDuplicate(...)` |
| 連線 / 暫時不可用 | `errb.DBUnavailable(...).WithCause(err)` |
| 其他 driver 錯 | `errb.DBError(...).WithCause(err)` |

Usecase 範例：

```go
var errb = errs.For(code.Facade)

acc, err := uc.Account.FindOne(ctx, id)
if err != nil {
    if errors.Is(err, member.ErrNotFound) {
        return nil, errb.ResNotFound("member", id).WithCause(err)
    }
    if e := errs.FromError(err); e != nil {
        return nil, err // DB* 等基礎設施錯誤原樣傳遞
    }
    return nil, errb.DBError("get member failed").WithCause(err)
}
```

Logic 只做輸入與映射，錯誤直接往上：

```go
out, err := l.svcCtx.MemberUC.GetByID(l.ctx, &memberusecase.GetByIDRequest{ID: req.Id})
if err != nil {
    return nil, err
}
```

**禁止：** repository 回傳裸 `fmt.Errorf` 給上層；logic 再包一層無語意錯誤；logic 直接操作 Mongo / repository 實作。

### 5. Lint 與自動修正

設定檔：`.golangci.yml`（golangci-lint v2，`standard` + revive / gosec / errorlint 等）。

```bash
make lint-fix   # 自動修（goimports、部分 linter auto-fix）
make lint       # 僅檢查
make fix        # fmt + lint-fix + lint
make check      # fix + test（建議每次改 Go 後執行）
```

無法自動修的須手改；AI / 協作者應以 `make check` 通過為完成條件（見 `.cursor/rules/golangci-lint.mdc`）。

### 6. 請求驗證（`library/validate`）

- `svc.ServiceContext.Validator`：啟動時以 `validate.NewWithDefaultEN()` 建立，可傳入 `validate.Option` 註冊自訂 tag。
- **Handler 模板**（`generate/goctl/api/handler.tpl`）在 `httpx.Parse` 之後自動 `ValidateAll(&req)`，失敗經 `WrapRequestError` → **400** `InputInvalidFormat`；Logic 通常不必再驗證。
- 自訂規則放在 `internal/library/validate/custom/`（依業務新增），透過 `NewWithDefaultEN(custom.YourOption)` 註冊。
- `validate.ValidationErrors` 含 `field` / `message`；勿與 `internal/library/errors/validate.go`（驗證 8 碼組成）混淆。

```go
if err := l.svcCtx.Validator.ValidateAll(req); err != nil {
    return nil, err // handler: response.WrapRequestError(err)
}
```

### 7. 新增業務模組檢查清單

1. 建立 `internal/model/{module}/`，依上方目錄放置 `entity`、`enum`、`repository`、`usecase`。
2. 在 `internal/svc/service_context.go` 組裝 repository → usecase，掛上介面欄位。
3. 在 `generate/api/` 定義路由，`make gen-api`。
4. 在 `internal/logic/` 實作：types ↔ usecase DTO，呼叫 `svcCtx.{Module}UC`。
5. `make gen-doc`、`go test ./...`；介面變更後執行 mockgen 更新 `internal/model/{module}/mock/`。

完整步驟見 [docs/model.md](docs/model.md) 第 11 節。

### 8. 錯誤碼 API 速查

```go
import (
    errs "gateway/internal/library/errors"
    "gateway/internal/library/errors/code"
)

var errb = errs.For(code.Facade)

return nil, errb.ResNotFound("user", id)
return nil, errb.InputMissingRequired("email").WithCause(err)
```

Category 與 HTTP 對照見 [internal/library/errors/README.md](internal/library/errors/README.md)。

### 9. API 文件（`@` 註解）

在 `.api` 中：

- `returns (FooVO)`：只描述 **data**（給 goctl / Logic）。
- `/* @respdoc-200 (FooOKStatus) ... */`：描述實際 HTTP body（給 OpenAPI）。
- `@doc(summary, description)`：單一接口說明。

範例見 `generate/api/normal.api`。

### 10. OpenAPI 產物與 Git

預設 `.gitignore` 會忽略 `docs/openapi/*.yaml`。若需提交給前端，請在 `.gitignore` 註解相關規則後執行 `make gen-doc` 並加入版本控制。

## 設定

主設定檔：`etc/gateway.yaml`

```yaml
Name: gateway
Host: 0.0.0.0
Port: 8888
```

本地覆寫可新增 `etc/gateway-local.yaml`（已列入 `.gitignore`，勿提交機密）。

## 測試

```bash
go test ./...
```

## 授權

內部專案，授權依組織規範為準。