init: taotie-api 项目初始化

CODEBUDDY.md

@@ -0,0 +1,64 @@
+# CODEBUDDY.md
+
+本文件为 CodeBuddy Code 在本仓库中工作时提供指导。
+
+## 构建与运行命令
+
+| 操作 | 命令 |
+|---|---|
+| 构建 | `go build -o tmp/main .` |
+| 运行 | `go run .` |
+| Wire 代码生成 | `go generate ./...`（修改 `wire.go` 后必须运行） |
+| 整理依赖 | `go mod tidy` |
+| 测试 | `go test ./...`（暂无测试文件） |
+
+应用启动端口为 8000（配置在 `config/config.dev.yml`）。环境由 `.env` 控制（`ENV=dev` 对应 `config/config.{env}.yml`）。
+
+## 架构
+
+Go 后端 API，使用 Gin + MongoDB + Wire 依赖注入。经典三层架构，DTO/DO/PO 模型分离。
+
+### 请求流程
+
+```
+Client → Gin Router → wrap.Wrap[R,P]（绑定/校验/响应）→ API Handler → Service → Repo → MongoDB
+```
+
+### 各层职责
+
+- **API**（`api/`）：路由、中间件、HTTP 处理器。`wrap.Wrap[R,P]()` 泛型包装器统一处理 JSON 绑定、参数校验（gookit/validate）和统一响应格式（`Resp{code, msg, data, ok, time}`）。
+- **Service**（`service/`）：业务逻辑。Wire 注入集定义在 `service.go`。
+- **Repo**（`repo/`）：数据访问。`BaseRepo[T]` 泛型仓储提供 CRUD 操作，支持软删除和租户隔离。子类添加实体特定查询。
+- **Model**（`model/`）：
+  - `dto/` — API 请求/响应结构体
+  - `do/` — Service 层输入/输出结构体
+  - `po/` — 数据库实体，均嵌入 `TBase`（OID、时间戳、创建人、tenantId）
+
+### 关键设计模式
+
+- **多租户隔离**：`BaseRepo.RawProcessFilter` 自动从 context 注入 `tenantId`（通过 `sctx` 包）。所有 PO 实体继承 `TBase.Tenant_OID`。
+- **Wire 依赖注入**：`wire.go`（构建标签 `wireinject`）定义注入图，`wire_gen.go` 为自动生成代码。注入链：`Configuration → MongoDb → Repos → Services → APIs → Router → Engine`。
+- **泛型 wrap 处理器**：`wrap.Wrap[R, P]()` 将请求绑定到 R，校验后调用 `func(context.Context, *R) (*P, error)`，成功返回 `Ok(c, data)`，失败返回 `Err(c, err)`。
+- **错误码**：系统错误定义在 `common/errsys.go`（0=成功，50-53=内部错误，s0xxx=业务通用），用户错误定义在 `common/erruser.go`（u001-u004）。
+
+### API 路由
+
+```
+GET  /                    → Hello World
+POST /api/v1/login        → 用户登录（需 tenantNo + userName + password）
+POST /api/v1/register     → 用户注册
+GET  /api/v1/user/current → 获取当前用户信息（需认证）
+```
+
+### 配置加载
+
+1. `.env` 设置 `ENV` 变量
+2. 通过 Viper 加载 `config/config.{ENV}.yml`
+3. 详见 `core/config.go` 中的 `Configuration` 结构体和默认值
+
+## 开发约定
+
+- 修改 `wire.go` 后，务必运行 `go generate ./...` 重新生成 `wire_gen.go`。
+- 新增 API 端点：在 `model/dto/` 定义 DTO，在 `api/v1/` 添加处理器，在 `api/api.go` 注册路由，实现 service 方法，按需添加 repo 方法。
+- 新增实体：在 `model/po/` 创建 PO（嵌入 `TBase`），在 `model/do/` 创建 DO，创建 `XxxRepo` 继承 `BaseRepo[T]`，添加 Wire provider。
+- 新增错误码：按现有模式在 `common/errsys.go` 或 `common/erruser.go` 中添加业务错误。