huang
8ab5ebc3af
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m2s
主要变更： - 在 StandaloneIotCardResponse 和 DeviceResponse 中添加 series_name 字段 - 在 iot_card 和 device service 中添加 loadSeriesNames 方法批量加载系列名称 - 更新相关方法以支持 series_name 的填充 其他变更： - 新增 OpenSpec 测试生成和共识锁定 skill - 新增 MCP 配置文件 - 更新 CLAUDE.md 项目规范文档 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
448 lines
16 KiB
Markdown
448 lines
16 KiB
Markdown
|
||
---
|
||
|
||
# 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` | 规范文档流程和维护规则 |
|
||
|
||
### ⚠️ 新增 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
|
||
- **必须为所有常量添加中文注释**
|
||
|
||
### 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 测试 │ ← 手动/自动化 UI（很少）
|
||
─┴─────────────┴─
|
||
┌─────────────────┐
|
||
│ 业务流程测试 │ ← 15%：多 API 组合验证
|
||
│ tests/flows/ │ 来源：Spec Business Flow
|
||
─┴─────────────────┴─
|
||
┌─────────────────────┐
|
||
│ 验收测试 │ ← 30%：单 API 契约验证
|
||
│ tests/acceptance/ │ 来源：Spec Scenario
|
||
─┴─────────────────────┴─
|
||
┌───────────────────────────┐
|
||
│ 集成测试 │ ← 25%：组件集成
|
||
─┴───────────────────────────┴─
|
||
┌─────────────────────────────────┐
|
||
│ 单元测试（精简） │ ← 30%：仅复杂逻辑
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
### 三层测试体系
|
||
|
||
| 层级 | 测试类型 | 来源 | 验证什么 | 位置 |
|
||
|------|---------|------|---------|------|
|
||
| **L1** | 验收测试 | Spec Scenario | 单 API 契约 | `tests/acceptance/` |
|
||
| **L2** | 流程测试 | Spec Business Flow | 业务场景完整性 | `tests/flows/` |
|
||
| **L3** | 单元测试 | 复杂逻辑 | 算法/规则正确性 | 模块内 `*_test.go` |
|
||
|
||
### 验收测试规范
|
||
|
||
- **来源于 Spec**：每个 Scenario 对应一个测试用例
|
||
- **测试先于实现**：在功能实现前生成，预期全部 FAIL
|
||
- **必须有破坏点**：每个测试注释说明什么代码变更会导致失败
|
||
- **使用 IntegrationTestEnv**：不要 mock 依赖
|
||
|
||
详见：[tests/acceptance/README.md](tests/acceptance/README.md)
|
||
|
||
### 流程测试规范
|
||
|
||
- **来源于 Spec Business Flow**：每个 Flow 对应一个测试
|
||
- **跨 API 验证**：多个 API 调用的组合行为
|
||
- **状态共享**：流程中的数据在 steps 之间传递
|
||
- **依赖声明**：每个 step 声明依赖哪些前置 step
|
||
|
||
详见：[tests/flows/README.md](tests/flows/README.md)
|
||
|
||
### 单元测试精简规则
|
||
|
||
**保留**：
|
||
- ✅ 纯函数（计费计算、分佣算法）
|
||
- ✅ 状态机（订单状态流转）
|
||
- ✅ 复杂业务规则（层级校验、权限计算）
|
||
- ✅ 边界条件（时间、金额、精度）
|
||
|
||
**删除/不再写**：
|
||
- ❌ 简单 CRUD（已被验收测试覆盖）
|
||
- ❌ DTO 转换
|
||
- ❌ 配置读取
|
||
- ❌ 重复测试同一逻辑
|
||
|
||
### ⚠️ 测试真实性原则（严格遵守）
|
||
|
||
**测试必须真正验证功能，禁止绕过核心逻辑：**
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| ❌ 禁止传递 nil 绕过依赖 | 如果功能依赖外部服务（如对象存储、第三方 API），测试必须验证该依赖的调用 |
|
||
| ❌ 禁止只测试部分流程 | 如果功能包含 A → B → C 三步，不能只测试 B 而跳过 A 和 C |
|
||
| ❌ 禁止声称"测试通过"但未验证核心逻辑 | 测试通过必须意味着功能真正可用 |
|
||
| ❌ 禁止擅自使用 Mock | 尽量使用真实服务进行集成测试，如需使用 Mock 必须先询问用户并获得同意 |
|
||
| ✅ 必须验证端到端流程 | 新增功能必须有完整的集成测试覆盖整个调用链 |
|
||
| ✅ 缺少配置时必须询问 | 如果测试需要的配置（如 API Key、环境变量）缺失，必须询问用户而非跳过测试 |
|
||
|
||
**反面案例**：
|
||
```go
|
||
// ❌ 错误：传递 nil 绕过 storageService，只测试了 processImport
|
||
handler := NewIotCardImportHandler(db, redis, store1, store2, nil, logger)
|
||
result := handler.processImport(ctx, task) // 跳过了 downloadAndParseCSV
|
||
|
||
// ✅ 正确：使用真实服务测试完整流程
|
||
handler := NewIotCardImportHandler(db, redis, store1, store2, realStorageService, logger)
|
||
handler.HandleIotCardImport(ctx, asynqTask) // 测试完整流程，验证真实上传/下载
|
||
```
|
||
|
||
**测试超时 = 生产超时**：
|
||
- 集成测试超时意味着生产环境也可能超时
|
||
- 发现超时必须排查原因，不能简单跳过或增加超时时间
|
||
|
||
### 测试连接管理（必读）
|
||
|
||
**详细规范**: [docs/testing/test-connection-guide.md](docs/testing/test-connection-guide.md)
|
||
|
||
**⚠️ 运行测试必须先加载环境变量**:
|
||
```bash
|
||
# ✅ 正确
|
||
source .env.local && go test -v ./internal/service/xxx/...
|
||
|
||
# ❌ 错误（会因缺少配置而失败）
|
||
go test -v ./internal/service/xxx/...
|
||
```
|
||
|
||
**标准模板**:
|
||
```go
|
||
func TestXxx(t *testing.T) {
|
||
tx := testutils.NewTestTransaction(t)
|
||
rdb := testutils.GetTestRedis(t)
|
||
testutils.CleanTestRedisKeys(t, rdb)
|
||
|
||
store := postgres.NewXxxStore(tx, rdb)
|
||
// 测试代码...
|
||
}
|
||
```
|
||
|
||
**核心函数**:
|
||
- `NewTestTransaction(t)`: 创建测试事务，自动回滚
|
||
- `GetTestRedis(t)`: 获取全局 Redis 连接
|
||
- `CleanTestRedisKeys(t, rdb)`: 自动清理测试 Redis 键
|
||
|
||
**集成测试环境**（HTTP API 测试）:
|
||
```go
|
||
func TestAPI_Create(t *testing.T) {
|
||
env := testutils.NewIntegrationTestEnv(t)
|
||
|
||
t.Run("成功创建", func(t *testing.T) {
|
||
resp, err := env.AsSuperAdmin().Request("POST", "/api/admin/resources", jsonBody)
|
||
require.NoError(t, err)
|
||
assert.Equal(t, 200, resp.StatusCode)
|
||
})
|
||
}
|
||
```
|
||
|
||
- `NewIntegrationTestEnv(t)`: 创建完整测试环境（事务、Redis、App、Token）
|
||
- `AsSuperAdmin()`: 以超级管理员身份请求
|
||
- `AsUser(account)`: 以指定账号身份请求
|
||
|
||
**禁止使用（已移除）**:
|
||
- ❌ `SetupTestDB` / `TeardownTestDB` / `SetupTestDBWithStore`
|
||
|
||
## 性能要求
|
||
|
||
- 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. ✅ 文档更新计划
|
||
9. ✅ 中文优先
|
||
|
||
## Code Review 检查清单
|
||
|
||
### 错误处理
|
||
- [ ] Service 层无 `fmt.Errorf` 对外返回
|
||
- [ ] Handler 层参数校验不泄露细节
|
||
- [ ] 错误码使用正确（4xx vs 5xx）
|
||
- [ ] 错误日志完整（包含上下文）
|
||
|
||
### 代码质量
|
||
- [ ] 遵循 Handler → Service → Store → Model 分层
|
||
- [ ] 函数长度 ≤ 100 行（核心逻辑 ≤ 50 行）
|
||
- [ ] 常量定义在 `pkg/constants/`
|
||
- [ ] 使用 Go 惯用法（非 Java 风格）
|
||
|
||
### 测试覆盖
|
||
- [ ] 核心业务逻辑测试覆盖率 ≥ 90%
|
||
- [ ] 所有 API 端点有集成测试
|
||
- [ ] 测试验证真实功能（不绕过核心逻辑）
|
||
|
||
### 文档和注释
|
||
- [ ] 所有注释使用中文
|
||
- [ ] 导出函数/类型有文档注释
|
||
- [ ] API 路径注释与真实路由一致
|
||
|
||
### 越权防护规范
|
||
|
||
**适用场景**：任何涉及跨用户、跨店铺、跨企业的资源访问
|
||
|
||
**三层防护机制**：
|
||
|
||
1. **路由层中间件**（粗粒度拦截）
|
||
- 用于明显的权限限制（如企业账号禁止访问账号管理）
|
||
- 示例：
|
||
```go
|
||
group.Use(func(c *fiber.Ctx) error {
|
||
userType := middleware.GetUserTypeFromContext(c.UserContext())
|
||
if userType == constants.UserTypeEnterprise {
|
||
return errors.New(errors.CodeForbidden, "无权限访问账号管理功能")
|
||
}
|
||
return c.Next()
|
||
})
|
||
```
|
||
|
||
2. **Service 层业务检查**（细粒度验证）
|
||
- 使用 `middleware.CanManageShop(ctx, targetShopID, shopStore)` 验证店铺权限
|
||
- 使用 `middleware.CanManageEnterprise(ctx, targetEnterpriseID, enterpriseStore, shopStore)` 验证企业权限
|
||
- 类型级权限检查（如代理不能创建平台账号）
|
||
- 示例见 `internal/service/account/service.go`
|
||
|
||
3. **GORM Callback 自动过滤**（兜底）
|
||
- 已有实现，自动应用到所有查询
|
||
- 代理用户：`WHERE shop_id IN (自己店铺+下级店铺)`
|
||
- 企业用户：`WHERE enterprise_id = 当前企业ID`
|
||
- 无需手动调用
|
||
|
||
**统一错误返回**：
|
||
- 越权访问统一返回：`errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")`
|
||
- 不区分"不存在"和"无权限"，防止信息泄露
|
||
|
||
### 审计日志规范
|
||
|
||
**适用场景**：任何敏感操作（账号管理、权限变更、数据删除等）
|
||
|
||
**使用方式**：
|
||
|
||
1. **Service 层集成审计日志**：
|
||
```go
|
||
type Service struct {
|
||
store *Store
|
||
auditService AuditServiceInterface
|
||
}
|
||
|
||
func (s *Service) SensitiveOperation(ctx context.Context, ...) error {
|
||
// 1. 执行业务操作
|
||
err := s.store.DoSomething(ctx, ...)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
|
||
// 2. 记录审计日志（异步）
|
||
s.auditService.LogOperation(ctx, &model.OperationLog{
|
||
OperatorID: middleware.GetUserIDFromContext(ctx),
|
||
OperationType: "operation_type",
|
||
OperationDesc: "操作描述",
|
||
BeforeData: beforeData, // 变更前数据
|
||
AfterData: afterData, // 变更后数据
|
||
RequestID: middleware.GetRequestIDFromContext(ctx),
|
||
IPAddress: middleware.GetIPFromContext(ctx),
|
||
UserAgent: middleware.GetUserAgentFromContext(ctx),
|
||
})
|
||
|
||
return nil
|
||
}
|
||
```
|
||
|
||
2. **审计日志字段说明**：
|
||
- `operator_id`, `operator_type`, `operator_name`: 操作人信息（必填）
|
||
- `target_*`: 目标资源信息（可选）
|
||
- `operation_type`: 操作类型（create/update/delete/assign_roles等）
|
||
- `operation_desc`: 操作描述（中文，便于查看）
|
||
- `before_data`, `after_data`: 变更数据（JSON 格式）
|
||
- `request_id`, `ip_address`, `user_agent`: 请求上下文
|
||
|
||
3. **异步写入**：
|
||
- 审计日志使用 Goroutine 异步写入
|
||
- 写入失败不影响业务操作
|
||
- 失败时记录 Error 日志，包含完整审计信息
|
||
|
||
**示例参考**：`internal/service/account/service.go`
|
||
|
||
---
|
||
|
||
### ⚠️ 任务执行规范（必须遵守）
|
||
|
||
**提案中的 tasks.md 是契约，不可擅自变更：**
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| ❌ 禁止跳过任务 | 每个任务都是经过规划的，不能因为"简单"或"显而易见"而跳过 |
|
||
| ❌ 禁止简化任务 | 不能将多个任务合并或简化执行，除非获得明确许可 |
|
||
| ❌ 禁止自作主张优化 | 发现可以优化的地方，必须先询问是否可以调整 |
|
||
| ✅ 必须逐项完成 | 按照 tasks.md 中的顺序逐一执行并标记完成 |
|
||
| ✅ 必须询问后变更 | 如需调整任务（简化/跳过/合并/优化），先询问用户确认 |
|
||
|
||
**询问示例**：
|
||
> "我注意到任务 2.1 和 2.2 可以合并为一步完成，是否可以这样优化？"
|
||
> "任务 3.1 在当前实现中可能不需要，是否可以跳过？"
|
||
|
||
**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`
|