junhong_cmp_fiber/CLAUDE.md

---

# junhong_cmp_fiber 项目开发规范

**重要**: 本文件包含核心规范。详细规范已提取为 Skills，在特定任务时按需加载。

## 专项规范 Skills（按需加载）

以下规范在相关任务时**自动触发**，无需手动加载：

| 任务类型 | 触发 Skill | 说明 |
|---------|-----------|------|
| 创建/修改 DTO 文件 | `dto-standards` | description 标签、枚举字段、验证标签规范 |
| 创建/修改 Model 模型 | `model-standards` | GORM 模型结构、字段标签、TableName 规范 |
| 注册 API 路由 / **新增 Handler** | `api-routing` | Register() 函数、RouteSpec、**文档生成器更新** |
| 测试接口/验证数据 | `db-validation` | PostgreSQL MCP 使用方法和验证示例 |
| 数据库迁移 | `db-migration` | 迁移命令、文件规范、执行流程、失败处理 |
| 维护规范文档 | `doc-management` | 规范文档流程和维护规则 |
| 调试 bug / 排查异常 | `systematic-debugging` | 四阶段根因分析流程、逐层诊断、场景速查表 |
| 编写 Go 代码注释/文档注释 | `comment-standards` | 包/结构体/接口/函数/内联注释完整规范与示例 |
| 创建涉及接口的 OpenSpec 提案 | `openspec-api-contract` | 探索阶段引导清单、提案必填章节与完成标准 |

---

### ⚠️ 新增 Handler 时必须同步更新文档生成器

新增 Handler 后，接口不会自动出现在 OpenAPI 文档中。**必须手动更新以下两个文件**：

```go
// cmd/api/docs.go 和 cmd/gendocs/main.go
handlers := &bootstrap.Handlers{
    // ... 添加新 Handler
    NewHandler: admin.NewXxxHandler(nil),
}
```

**完整检查清单**: 参见 [`docs/api-documentation-guide.md`](docs/api-documentation-guide.md#新增-handler-检查清单)

---

## 语言要求

**必须遵守:**

- 永远用中文交互
- 注释必须使用中文
- 文档必须使用中文
- 日志消息必须使用中文
- 用户可见的错误消息必须使用中文
- 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范）
- GIT提交的commit必须使用中文

## 技术栈

**必须严格遵守，禁止替代方案:**

| 类型 | 技术 |
|------|------|
| HTTP 框架 | Fiber v2.x |
| ORM | GORM v1.25.x |
| 配置管理 | Viper |
| 日志 | Zap + Lumberjack.v2 |
| JSON 序列化 | sonic（优先），encoding/json（必要时） |
| 验证 | Validator |
| 任务队列 | Asynq v0.24.x |
| 数据库 | PostgreSQL 14+ |
| 缓存 | Redis 6.0+ |

**禁止:**

- 直接使用 `database/sql`（必须通过 GORM）
- 使用 `net/http` 替代 Fiber
- 使用 `encoding/json` 替代 sonic（除非必要）

## 架构分层

必须遵循以下分层架构：

```
Handler → Service → Store → Model
```

- **Handler**: 只处理 HTTP 请求/响应，不包含业务逻辑
- **Service**: 包含所有业务逻辑，支持跨模块调用
- **Store**: 统一管理所有数据访问，支持事务处理
- **Model**: 定义数据结构和 DTO

## 核心原则

### 错误处理

- 所有错误必须在 `pkg/errors/` 中定义
- 使用统一错误码系统
- Handler 层通过返回 `error` 传递给全局 ErrorHandler

#### 错误报错规范（必须遵守）

- Handler 层禁止直接返回/拼接底层错误信息给客户端（例如 `"参数验证失败: "+err.Error()`、`err.Error()`）
- 参数校验失败：对外统一返回 `errors.New(errors.CodeInvalidParam)`（详细校验错误写日志）
- Service 层禁止对外返回 `fmt.Errorf(...)`，必须返回 `errors.New(...)` 或 `errors.Wrap(...)`
- 约定用法：`errors.New(code[, msg])`、`errors.Wrap(code, err[, msg])`

### 响应格式

- 所有 API 响应使用 `pkg/response/` 的统一格式
- 格式: `{code, msg, data, timestamp}`

### 常量管理

- 所有常量定义在 `pkg/constants/`
- Redis key 使用函数生成: `Redis{Module}{Purpose}Key(params...)`
- 禁止硬编码字符串和 magic numbers
- **必须为所有常量添加中文注释**

### 注释规范

- **所有注释使用中文**，导出符号必须有文档注释（包、函数、类型、接口、常量）
- 复杂逻辑解释"为什么"而非"做了什么"，禁止废话注释（复述代码本身）
- Handler 方法注释必须包含 HTTP 方法和路径（`// Create 创建账号` + `// POST /api/admin/accounts`）
- 未导出函数：< 15 行可省略，≥ 15 行或非显而易见算法必须注释
- 修改代码时必须同步更新注释，过时注释比没有注释更有害

**详细规范与示例**：见 `comment-standards` skill

### Go 代码风格

- 使用 `gofmt` 格式化
- 遵循 [Effective Go](https://go.dev/doc/effective_go)
- 包名: 简短、小写、单数、无下划线
- 接口命名: 使用 `-er` 后缀（Reader、Writer、Logger）

## 数据库设计

**核心规则:**

- ❌ 禁止建立外键约束
- ❌ 禁止使用 GORM 关联关系标签（foreignKey、hasMany、belongsTo）
- ✅ 关联通过存储 ID 字段手动维护
- ✅ 关联数据在代码层面显式查询

## Go 惯用法 vs Java 风格

### ✅ Go 风格（推荐）

- 扁平化包结构（最多 2-3 层）
- 小而专注的接口（1-3 个方法）
- 直接访问导出字段（不用 getter/setter）
- 组合优于继承
- 显式错误返回和检查

### ❌ Java 风格（禁止）

- 过度抽象（不必要的接口、工厂）
- Getter/Setter 方法
- 深层继承层次
- 异常处理（panic/recover）
- 类型前缀（IService、AbstractBase、ServiceImpl）

## ⚠️ 测试禁令（强制执行）

**本项目禁止任何形式的自动化测试**（单元/集成/E2E/`*_test.go` 文件），规划和文档中也不讨论测试。
**唯一例外**：用户明确说"请写测试"时。
**替代验证**：PostgreSQL MCP 手动验证数据、Postman/curl 手动测试 API。

## 性能要求

- API P95 响应时间 < 200ms
- API P99 响应时间 < 500ms
- 数据库查询 < 50ms
- 列表查询必须分页（默认 20，最大 100）
- 避免 N+1 查询，使用批量操作

## 文档要求

- 每个功能在 `docs/{feature-id}/` 创建总结文档
- 文档文件名和内容使用中文
- 同步更新 README.md
- 为导出的函数、类型编写文档注释

## 函数复杂度

- 函数长度 ≤ 100 行（核心逻辑建议 ≤ 50 行）
- `main()` 函数只做编排，不含具体实现
- 遵循单一职责原则

## 访问日志

- 所有 HTTP 请求记录到 `access.log`
- 记录完整的请求/响应（限制 50KB）
- 包含: method, path, query, status, duration, request_id, ip, user_agent, user_id, bodies
- 使用 JSON 格式，配置自动轮转

## OpenSpec 工作流

创建提案前的检查清单：

1. ✅ 技术栈合规
2. ✅ 架构分层正确
3. ✅ 使用统一错误处理
4. ✅ 常量定义在 pkg/constants/
5. ✅ Go 惯用法（非 Java 风格）
6. ✅ 性能考虑
7. ✅ 文档更新计划
8. ✅ 中文优先

## Code Review 检查清单

### 错误处理

- [ ] Service 层无 `fmt.Errorf` 对外返回
- [ ] Handler 层参数校验不泄露细节
- [ ] 错误码使用正确（4xx vs 5xx）
- [ ] 错误日志完整（包含上下文）

### 代码质量

- [ ] 遵循 Handler → Service → Store → Model 分层
- [ ] 函数长度 ≤ 100 行（核心逻辑 ≤ 50 行）
- [ ] 常量定义在 `pkg/constants/`
- [ ] 使用 Go 惯用法（非 Java 风格）

### 文档和注释

- [ ] 所有注释使用中文
- [ ] 导出函数/类型有文档注释
- [ ] API 路径注释与真实路由一致

### 幂等性

- [ ] 创建类写操作有 Redis 业务键防重
- [ ] 状态变更使用条件更新（`WHERE status = expected`）
- [ ] 余额/库存变更使用乐观锁（version 字段）
- [ ] 分布式锁使用 `defer` 确保释放
- [ ] Redis Key 定义在 `pkg/constants/redis.go`

### 越权防护规范

**三层防护机制**（基础设施已就绪，无需自建）：
1. **路由层中间件**：粗粒度拦截（如企业账号禁止访问账号管理）
2. **Service 层业务检查**：`middleware.CanManageShop()` / `middleware.CanManageEnterprise()` 细粒度验证；示例见 `internal/service/account/service.go`
3. **GORM Callback 自动过滤**：代理按店铺层级、企业按企业ID，已自动应用无需手动调用

统一错误返回：`errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")`（不区分"不存在"与"无权限"，防止信息泄露）

### 幂等性规范

写操作按场景选择策略：
- **状态流转操作** → 状态条件更新（首选）
- **创建类操作（无状态可依赖）** → Redis 业务键防重 + 分布式锁（三层检测）
- **余额/库存数值更新** → 乐观锁（`version` 字段）

```go
// 策略1示例（首选）：通过 WHERE 条件确保幂等，RowsAffected=0 说明已被处理
result := tx.Model(&model.Order{}).
    Where("id = ? AND payment_status = ?", orderID, model.PaymentStatusPending).
    Updates(map[string]any{"payment_status": model.PaymentStatusPaid})
if result.RowsAffected == 0 { /* 已处理，检查当前状态 */ }
```

- Redis Key 定义在 `pkg/constants/redis.go`，分布式锁必须用 `defer` 释放
- 参考实现：`internal/service/order/service.go`

### 异步任务载荷规范（Asynq）

**必须遵守：**

- ✅ 调用 `queueClient.EnqueueTask()` 时，`payload` 必须传入 **struct 或 map**
- ❌ **禁止传入 `[]byte`**：`EnqueueTask` 内部统一调用 `sonic.Marshal`，若传入 `[]byte` 会被 base64 编码成字符串，Handler 反序列化时类型不匹配直接崩溃

```go
// ✅ 正确：传 struct
queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, MyPayload{OrderID: id})

// ❌ 错误：预先序列化后传 []byte（二次 Marshal → base64 编码）
payloadBytes, _ := sonic.Marshal(MyPayload{OrderID: id})
queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes)
```

直接用 `asynq.NewTask` 入队时（绕过 `EnqueueTask`）才需要自己 Marshal。

---

### 审计日志规范

**适用场景**：任何敏感操作（账号管理、权限变更、数据删除等）

- Service 层注入 `auditService AuditServiceInterface`，操作成功后调用 `LogOperation()`
- 必填字段：`OperatorID`、`OperationType`、`OperationDesc`、`BeforeData`、`AfterData`
- 异步写入（Goroutine），写入失败不影响业务，失败时记录 Error 日志

**示例参考**：`internal/service/account/service.go`

---

### ⚠️ 任务执行规范（必须遵守）

**提案中的 tasks.md 是契约，不可擅自变更：**

| 规则 | 说明 |
|------|------|
| ❌ 禁止跳过任务 | 每个任务都是经过规划的，不能因为"简单"或"显而易见"而跳过 |
| ❌ 禁止简化任务 | 不能将多个任务合并或简化执行，除非获得明确许可 |
| ❌ 禁止自作主张优化 | 发现可以优化的地方，必须先询问是否可以调整 |
| ✅ 必须逐项完成 | 按照 tasks.md 中的顺序逐一执行并标记完成 |
| ✅ 必须询问后变更 | 如需调整任务（简化/跳过/合并/优化），先询问用户确认 |

**询问示例**：
> "我注意到任务 2.1 和 2.2 可以合并为一步完成，是否可以这样优化？"
> "任务 3.1 在当前实现中可能不需要，是否可以跳过？"

**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`