feat: OpenAPI 契约对齐与框架优化
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m45s
主要变更： 1. OpenAPI 文档契约对齐 - 统一错误响应字段名为 msg（非 message） - 规范 envelope 响应结构（code, msg, data, timestamp） - 个人客户路由纳入文档体系（使用 Register 机制） - 新增 BuildDocHandlers() 统一管理 handler 构造 - 确保文档生成的幂等性 2. Service 层错误处理统一 - 全面替换 fmt.Errorf 为 errors.New/Wrap - 统一错误码使用规范 - Handler 层参数校验不泄露底层细节 - 新增错误码验证集成测试 3. 代码质量提升 - 删除未使用的 Task handler 和路由 - 新增代码规范检查脚本（check-service-errors.sh） - 新增注释路径一致性检查（check-comment-paths.sh） - 更新 API 文档生成指南 4. OpenSpec 归档 - 归档 openapi-contract-alignment 变更（63 tasks） - 归档 service-error-unify-core 变更 - 归档 service-error-unify-support 变更 - 归档 code-cleanup-docs-update 变更 - 归档 handler-validation-security 变更 - 同步 delta specs 到主规范文件 影响范围： - pkg/openapi: 新增 handlers.go，优化 generator.go - internal/service/*: 48 个 service 文件错误处理统一 - internal/handler/admin: 优化参数校验错误提示 - internal/routes: 个人客户路由改造，删除 task 路由 - scripts: 新增 3 个代码检查脚本 - docs: 更新 OpenAPI 文档（15750+ 行） - openspec/specs: 同步 3 个主规范文件 破坏性变更：无 向后兼容：是
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
# 归档说明
|
||||
|
||||
**归档时间**：2026-01-29
|
||||
|
||||
**归档原因**：提案范围过大，已拆分为 5 个独立提案
|
||||
|
||||
## 已完成任务（止血类）
|
||||
|
||||
本提案中已完成的紧急修复任务：
|
||||
|
||||
### 1. 限流覆盖真实 API 路由组 ✅
|
||||
- 调整限流挂载位置，覆盖 `/api/admin`、`/api/h5`、`/api/c/v1`
|
||||
- 明确排除 `/api/callback`、`/health`、`/ready`
|
||||
|
||||
### 2. 短信验证码未配置不崩溃 ✅
|
||||
- 短信客户端增加初始化流程（基于配置）
|
||||
- 验证码服务在 smsClient 为空时返回 `CodeServiceUnavailable`（503）
|
||||
- 补充相关测试用例
|
||||
|
||||
### 3. 部分 Service 层错误统一 ✅
|
||||
- 已完成 4 个文件：
|
||||
- `verification/service.go` (10 处)
|
||||
- `personal_customer/service.go` (11 处)
|
||||
- `auth/service.go` (4 处)
|
||||
- `device_import/service.go` (2 处)
|
||||
|
||||
## 拆分后的新提案
|
||||
|
||||
剩余任务已拆分为以下独立提案：
|
||||
|
||||
| 提案 | 目录 | 优先级 | 预估工作量 |
|
||||
|-----|------|--------|-----------|
|
||||
| Service 层错误统一 - 核心业务 | `service-error-unify-core` | 🔴 高 | 4.5h |
|
||||
| Service 层错误统一 - 支持模块 | `service-error-unify-support` | 🟡 中 | 7h |
|
||||
| Handler 层参数校验安全加固 | `handler-validation-security` | 🟡 中 | 5h |
|
||||
| OpenAPI 文档契约对齐 | `openapi-contract-alignment` | 🟡 中 | 4h |
|
||||
| 代码清理和规范文档更新 | `code-cleanup-docs-update` | 🟢 低 | 3.5h |
|
||||
|
||||
## 执行顺序建议
|
||||
|
||||
```
|
||||
提案 1 (核心业务) → 提案 2 (支持模块) → 提案 3 (Handler 层) → 提案 4 (OpenAPI) → 提案 5 (清理)
|
||||
```
|
||||
|
||||
## 参考文档
|
||||
|
||||
- 原提案：`proposal.md`
|
||||
- 任务清单：`tasks.md`
|
||||
- 后续建议：`NEXT_STEPS.md`
|
||||
@@ -0,0 +1,354 @@
|
||||
# 后续工作建议
|
||||
|
||||
基于当前已完成的工作，建议将剩余任务拆分为 4 个独立的 OpenSpec 变更，按优先级顺序执行。
|
||||
|
||||
---
|
||||
|
||||
## 提案 1：Service 层错误语义统一 - 核心业务模块
|
||||
|
||||
**优先级**：🔴 高
|
||||
|
||||
### Why
|
||||
完成核心业务模块的错误语义统一，确保订单、套餐、分佣等关键流程的错误处理一致性。
|
||||
|
||||
### What Changes
|
||||
统一以下 10 个核心模块的错误处理（约 70-80 处）：
|
||||
|
||||
**订单与套餐管理**：
|
||||
- `package/service.go` (14 处)
|
||||
- `package_series/service.go` (9 处)
|
||||
- `order/service.go` (已完成)
|
||||
|
||||
**分佣系统**：
|
||||
- `commission_withdrawal/service.go` (7 处)
|
||||
- `commission_stats/service.go` (3 处)
|
||||
- `my_commission/service.go` (9 处)
|
||||
|
||||
**店铺与企业**：
|
||||
- `shop/service.go` (8 处)
|
||||
- `enterprise/service.go` (7 处)
|
||||
- `shop_account/service.go` (11 处)
|
||||
- `customer_account/service.go` (6 处)
|
||||
|
||||
### Decisions
|
||||
- 数据库/Redis/队列错误统一为 `errors.Wrap(CodeInternalError, err, msg)`
|
||||
- 业务校验错误（如状态不允许、资源不存在）为 `errors.New(Code4xx, msg)`
|
||||
- 每完成 2-3 个文件运行一次相关测试
|
||||
|
||||
### Impact
|
||||
- **Breaking Changes**：部分接口错误码从 500 调整为 4xx
|
||||
- **测试要求**：每个模块补充错误场景测试
|
||||
- **文档更新**：更新 API 文档中的错误码说明
|
||||
|
||||
---
|
||||
|
||||
## 提案 2：Service 层错误语义统一 - 支持模块
|
||||
|
||||
**优先级**：🟡 中
|
||||
|
||||
### Why
|
||||
完成剩余支持模块的错误语义统一，实现全局一致性。
|
||||
|
||||
### What Changes
|
||||
统一以下 14 个支持模块的错误处理（约 140-150 处）：
|
||||
|
||||
**套餐分配系统**：
|
||||
- `shop_package_allocation/service.go` (17 处)
|
||||
- `shop_series_allocation/service.go` (24 处)
|
||||
- `shop_package_batch_allocation/service.go` (6 处)
|
||||
- `shop_package_batch_pricing/service.go` (3 处)
|
||||
|
||||
**权限与账号**：
|
||||
- `account/service.go` (24 处)
|
||||
- `role/service.go` (15 处)
|
||||
- `permission/service.go` (10 处)
|
||||
|
||||
**卡与设备管理**：
|
||||
- `enterprise_card/service.go` (9 处)
|
||||
- `enterprise_device/service.go` (20 处)
|
||||
- `iot_card_import/service.go` (2 处)
|
||||
- `device_import/service.go` (已完成)
|
||||
|
||||
**其他支持服务**：
|
||||
- `carrier/service.go` (9 处)
|
||||
- `shop_commission/service.go` (7 处)
|
||||
- `commission_withdrawal_setting/service.go` (4 处)
|
||||
- `email/service.go` (6 处)
|
||||
- `sync/service.go` (4 处)
|
||||
|
||||
### Decisions
|
||||
- 同提案 1 的错误处理规则
|
||||
- 可以分批次提交（如每 5 个文件一个 commit）
|
||||
|
||||
---
|
||||
|
||||
## 提案 3：Handler 层参数校验安全加固
|
||||
|
||||
**优先级**：🟡 中
|
||||
|
||||
### Why
|
||||
防止参数校验错误泄露内部实现细节（validator 规则、字段名等），提升安全性。
|
||||
|
||||
### What Changes
|
||||
|
||||
**修复模式**：
|
||||
|
||||
```go
|
||||
// ❌ 当前（泄露细节）
|
||||
if err := c.BodyParser(&req); err != nil {
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败: "+err.Error())
|
||||
}
|
||||
|
||||
if err := validate.Struct(&req); err != nil {
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数验证失败: "+err.Error())
|
||||
}
|
||||
|
||||
// ✅ 修复后（安全）
|
||||
if err := c.BodyParser(&req); err != nil {
|
||||
logger.GetAppLogger().Warn("参数解析失败",
|
||||
zap.String("path", c.Path()),
|
||||
zap.Error(err),
|
||||
)
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败")
|
||||
}
|
||||
|
||||
if err := validate.Struct(&req); err != nil {
|
||||
logger.GetAppLogger().Warn("参数验证失败",
|
||||
zap.String("path", c.Path()),
|
||||
zap.Error(err),
|
||||
)
|
||||
return errors.New(errors.CodeInvalidParam) // 使用默认 msg
|
||||
}
|
||||
```
|
||||
|
||||
**影响范围**：
|
||||
- `internal/handler/admin/**` (约 20-25 个文件)
|
||||
- `internal/handler/h5/**` (约 5-8 个文件)
|
||||
- `internal/handler/personal/**` (约 3-5 个文件)
|
||||
|
||||
### Decisions
|
||||
- 详细校验错误只写日志，不返回给客户端
|
||||
- 统一返回 `CodeInvalidParam` + 通用消息
|
||||
- 为关键 Handler 补充参数校验测试
|
||||
|
||||
### Testing
|
||||
```go
|
||||
func TestHandler_InvalidParam(t *testing.T) {
|
||||
// 测试参数缺失
|
||||
resp := testRequest(t, "POST", "/api/admin/users", `{}`)
|
||||
assert.Equal(t, 400, resp.StatusCode)
|
||||
|
||||
var result map[string]interface{}
|
||||
json.Unmarshal(resp.Body, &result)
|
||||
|
||||
// 验证不包含 validator 内部细节
|
||||
assert.NotContains(t, result["msg"], "Field validation")
|
||||
assert.NotContains(t, result["msg"], "required")
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 提案 4：OpenAPI 文档契约对齐
|
||||
|
||||
**优先级**：🟡 中
|
||||
|
||||
### Why
|
||||
确保 OpenAPI 文档描述的响应结构与真实运行时一致，避免 SDK 生成和接口对接问题。
|
||||
|
||||
### What Changes
|
||||
|
||||
#### 4.1 响应字段名对齐
|
||||
```yaml
|
||||
# ❌ 当前
|
||||
components:
|
||||
schemas:
|
||||
ErrorResponse:
|
||||
properties:
|
||||
code: integer
|
||||
message: string # 错误：应为 msg
|
||||
data: object
|
||||
timestamp: string
|
||||
|
||||
# ✅ 修复后
|
||||
components:
|
||||
schemas:
|
||||
ErrorResponse:
|
||||
properties:
|
||||
code: integer
|
||||
msg: string # 对齐真实字段名
|
||||
data: object
|
||||
timestamp: string
|
||||
```
|
||||
|
||||
#### 4.2 成功响应体现 envelope
|
||||
```yaml
|
||||
# ❌ 当前（直接返回 DTO）
|
||||
/api/admin/users:
|
||||
get:
|
||||
responses:
|
||||
200:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserDTO'
|
||||
|
||||
# ✅ 修复后（包裹 envelope）
|
||||
/api/admin/users:
|
||||
get:
|
||||
responses:
|
||||
200:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code:
|
||||
type: integer
|
||||
example: 0
|
||||
msg:
|
||||
type: string
|
||||
example: "success"
|
||||
data:
|
||||
$ref: '#/components/schemas/UserDTO'
|
||||
timestamp:
|
||||
type: string
|
||||
format: date-time
|
||||
```
|
||||
|
||||
#### 4.3 补齐 handlers 清单
|
||||
在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中补充：
|
||||
- `PersonalCustomer` handler
|
||||
- `ShopPackageBatchAllocation` handler
|
||||
- `ShopPackageBatchPricing` handler
|
||||
|
||||
#### 4.4 个人客户路由纳入文档
|
||||
修改 `internal/routes/personal.go` 使用 `Register(...)` 并添加 RouteSpec。
|
||||
|
||||
### Impact
|
||||
- OpenAPI 文档结构变化（需通知 SDK 使用方）
|
||||
- 文档生成后需要对比差异确认
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# 1. 重新生成文档
|
||||
go run cmd/gendocs/main.go
|
||||
|
||||
# 2. 对比差异
|
||||
diff logs/openapi.yaml logs/openapi.yaml.old
|
||||
|
||||
# 3. 验证关键接口
|
||||
# - 检查响应是否包含 envelope
|
||||
# - 检查字段名是否为 msg（非 message）
|
||||
# - 检查 /api/c/v1 路由是否出现
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 提案 5：代码清理和规范文档更新
|
||||
|
||||
**优先级**：🟢 低
|
||||
|
||||
### Why
|
||||
清理临时代码和不一致的注释，更新项目规范文档，完善 CI 检查。
|
||||
|
||||
### What Changes
|
||||
|
||||
#### 5.1 移除任务模块占位代码
|
||||
- 删除 `internal/routes/task.go`
|
||||
- 删除 `internal/handler/admin/task.go`
|
||||
- 更新 `internal/routes/routes.go` 移除 `registerTaskRoutes` 调用
|
||||
|
||||
#### 5.2 清理注释一致性
|
||||
扫描 `internal/handler/**` 中残留的 `/api/v1` 注释，统一为真实路径。
|
||||
|
||||
#### 5.3 更新规范文档
|
||||
- 更新 `openspec/specs/error-handling/spec.md` 补充"错误报错规范"
|
||||
- 更新 `AGENTS.md` 增加错误处理检查清单
|
||||
- 更新 `docs/003-error-handling/使用指南.md` 补充实际案例
|
||||
|
||||
#### 5.4 CI 检查增强
|
||||
```bash
|
||||
# 添加脚本检查 Service 层禁止 fmt.Errorf
|
||||
#!/bin/bash
|
||||
# scripts/check-service-errors.sh
|
||||
|
||||
FILES=$(find internal/service -name "*.go" -type f)
|
||||
VIOLATIONS=$(grep -n "fmt\.Errorf" $FILES | grep -v "// whitelist:")
|
||||
|
||||
if [ -n "$VIOLATIONS" ]; then
|
||||
echo "❌ 发现 Service 层使用 fmt.Errorf："
|
||||
echo "$VIOLATIONS"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Service 层错误处理检查通过"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 执行顺序建议
|
||||
|
||||
```
|
||||
提案 1 (核心业务) → 提案 2 (支持模块) → 提案 3 (Handler 层) → 提案 4 (OpenAPI) → 提案 5 (清理)
|
||||
```
|
||||
|
||||
**原因**：
|
||||
1. 优先修复核心业务错误语义（影响用户体验）
|
||||
2. 完成全量 Service 层统一后再处理 Handler 层
|
||||
3. OpenAPI 文档对齐可以独立进行
|
||||
4. 代码清理和规范更新最后进行
|
||||
|
||||
---
|
||||
|
||||
## 每个提案的验证清单
|
||||
|
||||
### 编译检查
|
||||
```bash
|
||||
go build -o /tmp/test_api ./cmd/api
|
||||
go build -o /tmp/test_worker ./cmd/worker
|
||||
```
|
||||
|
||||
### 单元测试
|
||||
```bash
|
||||
source .env.local && go test -v ./internal/service/[模块名]/...
|
||||
```
|
||||
|
||||
### 集成测试
|
||||
```bash
|
||||
source .env.local && go test -v ./tests/integration/...
|
||||
```
|
||||
|
||||
### 错误码验证
|
||||
手动测试关键接口，确认：
|
||||
- 业务错误返回 4xx（如参数错误、状态不允许）
|
||||
- 系统错误返回 5xx（如数据库连接失败）
|
||||
- 错误消息不泄露内部细节
|
||||
|
||||
---
|
||||
|
||||
## 预估工作量
|
||||
|
||||
| 提案 | 文件数 | 错误点数 | 预估时间 | 优先级 |
|
||||
|-----|-------|---------|---------|-------|
|
||||
| 提案 1 | 10 | 70-80 | 2-3 小时 | 高 |
|
||||
| 提案 2 | 14 | 140-150 | 3-4 小时 | 中 |
|
||||
| 提案 3 | 30-40 | N/A | 2-3 小时 | 中 |
|
||||
| 提案 4 | 5-6 | N/A | 1-2 小时 | 中 |
|
||||
| 提案 5 | 3-4 | N/A | 1 小时 | 低 |
|
||||
|
||||
**总计**：约 9-13 小时（分 5 次完成）
|
||||
|
||||
---
|
||||
|
||||
## 风险提示
|
||||
|
||||
1. **Breaking Changes**：错误码变更可能影响现有客户端
|
||||
2. **测试覆盖**：每个模块需要补充错误场景测试
|
||||
3. **文档同步**：OpenAPI 文档变更需通知 SDK 使用方
|
||||
4. **Code Review**：每个提案需要充分的代码审查
|
||||
|
||||
建议每个提案完成后：
|
||||
- 运行全量测试
|
||||
- 在测试环境验证
|
||||
- 通过 Code Review 后再合并
|
||||
@@ -0,0 +1,316 @@
|
||||
# 实施进度总结
|
||||
|
||||
## 当前状态：部分完成（已归档）
|
||||
|
||||
**完成时间**：2026-01-29
|
||||
**完成进度**：9/58 任务（15.5%）
|
||||
|
||||
---
|
||||
|
||||
## ✅ 已完成部分
|
||||
|
||||
### 阶段 1：限流覆盖真实 API 路由组（3/3 完成）
|
||||
|
||||
**影响文件**：
|
||||
- `cmd/api/main.go`
|
||||
- `docs/rate-limiting.md`
|
||||
|
||||
**变更内容**：
|
||||
1. 调整限流中间件挂载位置，从 `/api/v1` 改为真实业务路由组
|
||||
2. 限流覆盖范围：`/api/admin`、`/api/h5`、`/api/c/v1`
|
||||
3. 明确排除：`/api/callback`（回调）、`/health`、`/ready`（健康检查）
|
||||
4. 更新文档说明限流生效范围
|
||||
|
||||
**测试建议**：
|
||||
```bash
|
||||
# 启用限流配置
|
||||
export JUNHONG_MIDDLEWARE_ENABLE_RATE_LIMITER=true
|
||||
export JUNHONG_MIDDLEWARE_RATE_LIMITER_MAX=5
|
||||
export JUNHONG_MIDDLEWARE_RATE_LIMITER_EXPIRATION=1m
|
||||
|
||||
# 测试限流生效
|
||||
for i in {1..10}; do curl http://localhost:3000/api/admin/login; done
|
||||
|
||||
# 验证排除路径不受限流
|
||||
for i in {1..10}; do curl http://localhost:3000/health; done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段 2：短信验证码未配置不崩溃（3/3 完成）
|
||||
|
||||
**影响文件**：
|
||||
- `internal/service/verification/service.go`
|
||||
|
||||
**变更内容**：
|
||||
1. `SendCode` 方法增加 smsClient 可用性检查
|
||||
2. 未配置短信服务时返回 `errors.New(CodeServiceUnavailable)` (HTTP 503)
|
||||
3. 统一验证码链路所有错误返回为结构化错误（`errors.New/Wrap`）
|
||||
|
||||
**修复的错误点**：
|
||||
- 验证码发送频率限制错误：`CodeTooManyRequests`
|
||||
- 验证码生成失败：`CodeInternalError`
|
||||
- 短信发送失败：`CodeInternalError`
|
||||
- Redis 存储失败：`CodeInternalError`
|
||||
- 验证码不存在或过期：`CodeInvalidParam`
|
||||
- 验证码错误：`CodeInvalidParam`
|
||||
|
||||
**测试场景**：
|
||||
- ✅ 短信服务未配置时调用发送验证码 → 返回 503
|
||||
- ✅ 验证码发送过于频繁 → 返回 429
|
||||
- ✅ 验证码错误 → 返回 400
|
||||
- ✅ 验证码过期 → 返回 400
|
||||
|
||||
---
|
||||
|
||||
### 阶段 3：Service 层错误语义统一（部分完成：4/27 文件）
|
||||
|
||||
**已完成文件**（27 处错误修复）：
|
||||
1. `verification/service.go` - 10 处
|
||||
2. `personal_customer/service.go` - 11 处
|
||||
3. `auth/service.go` - 4 处
|
||||
4. `device_import/service.go` - 2 处
|
||||
|
||||
**修复模式**：
|
||||
```go
|
||||
// ❌ 修复前
|
||||
return fmt.Errorf("创建用户失败: %w", err)
|
||||
|
||||
// ✅ 修复后（系统错误）
|
||||
return errors.Wrap(errors.CodeInternalError, err, "创建用户失败")
|
||||
|
||||
// ✅ 修复后（业务错误）
|
||||
return errors.New(errors.CodeInvalidParam, "验证码错误")
|
||||
```
|
||||
|
||||
**待完成文件**（24 个文件，约 224 处）：
|
||||
- `iot_card_import/service.go` (2)
|
||||
- `commission_stats/service.go` (3)
|
||||
- `shop_package_batch_pricing/service.go` (3)
|
||||
- `commission_withdrawal_setting/service.go` (4)
|
||||
- `sync/service.go` (4)
|
||||
- `customer_account/service.go` (6)
|
||||
- `email/service.go` (6)
|
||||
- `shop_package_batch_allocation/service.go` (6)
|
||||
- `commission_withdrawal/service.go` (7)
|
||||
- `enterprise/service.go` (7)
|
||||
- `shop_commission/service.go` (7)
|
||||
- `shop/service.go` (8)
|
||||
- `carrier/service.go` (9)
|
||||
- `enterprise_card/service.go` (9)
|
||||
- `my_commission/service.go` (9)
|
||||
- `package_series/service.go` (9)
|
||||
- `permission/service.go` (10)
|
||||
- `shop_account/service.go` (11)
|
||||
- `package/service.go` (14)
|
||||
- `role/service.go` (15)
|
||||
- `shop_package_allocation/service.go` (17)
|
||||
- `enterprise_device/service.go` (20)
|
||||
- `account/service.go` (24)
|
||||
- `shop_series_allocation/service.go` (24)
|
||||
|
||||
---
|
||||
|
||||
## ⏸️ 待完成部分（49/58 任务）
|
||||
|
||||
### 阶段 3 剩余：Service 层错误语义统一
|
||||
|
||||
**工作量估算**：约 224 处 `fmt.Errorf` 需要逐一分析并替换
|
||||
- 需要区分业务错误（4xx）和系统错误（5xx）
|
||||
- 需要选择合适的错误码
|
||||
- 需要补充回归测试
|
||||
|
||||
**建议执行方式**：
|
||||
- 按文件数量从少到多处理
|
||||
- 优先处理核心业务模块（order、package、commission）
|
||||
- 每完成 5-10 个文件运行一次测试
|
||||
|
||||
---
|
||||
|
||||
### 阶段 4：参数校验错误不泄露内部细节
|
||||
|
||||
**影响范围**：`internal/handler/**` 所有 Handler 文件（约 30-40 个）
|
||||
|
||||
**需要修复的模式**：
|
||||
```go
|
||||
// ❌ 修复前
|
||||
if err := c.BodyParser(&req); err != nil {
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败: "+err.Error())
|
||||
}
|
||||
|
||||
// ✅ 修复后
|
||||
if err := c.BodyParser(&req); err != nil {
|
||||
logger.GetAppLogger().Warn("参数解析失败", zap.Error(err))
|
||||
return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败")
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段 5：OpenAPI 响应 envelope 对齐
|
||||
|
||||
**影响文件**：
|
||||
- `pkg/openapi/generator.go`
|
||||
|
||||
**需要修复**：
|
||||
- 错误响应字段名：`message` → `msg`
|
||||
- 成功响应体现 envelope：`{code, data, msg, timestamp}`
|
||||
|
||||
---
|
||||
|
||||
### 阶段 6：OpenAPI handlers 清单完整
|
||||
|
||||
**影响文件**：
|
||||
- `cmd/api/docs.go`
|
||||
- `cmd/gendocs/main.go`
|
||||
- `internal/bootstrap/handlers.go`
|
||||
|
||||
**需要补齐的 handlers**：
|
||||
- PersonalCustomer
|
||||
- ShopPackageBatchAllocation
|
||||
- ShopPackageBatchPricing
|
||||
|
||||
---
|
||||
|
||||
### 阶段 7：个人客户路由纳入文档体系
|
||||
|
||||
**影响文件**：
|
||||
- `internal/routes/personal.go`
|
||||
- `internal/routes/routes.go`
|
||||
|
||||
---
|
||||
|
||||
### 阶段 8：移除任务模块占位代码
|
||||
|
||||
**影响文件**：
|
||||
- `internal/routes/task.go`
|
||||
- `internal/routes/routes.go`
|
||||
- `internal/handler/admin/task.go`
|
||||
|
||||
---
|
||||
|
||||
### 阶段 9-11：规范文档更新和回归验证
|
||||
|
||||
---
|
||||
|
||||
## 建议后续工作拆分
|
||||
|
||||
### 提案 A：Service 层错误语义统一（核心模块）
|
||||
|
||||
**范围**：
|
||||
- 已完成 4 个关键认证文件
|
||||
- 继续完成 10 个核心业务模块（order、package、commission、shop、enterprise）
|
||||
|
||||
**文件数**：约 10 个，60-80 处错误
|
||||
|
||||
---
|
||||
|
||||
### 提案 B：Service 层错误语义统一（非核心模块）
|
||||
|
||||
**范围**：
|
||||
- 剩余 14 个支持模块
|
||||
|
||||
**文件数**：约 14 个，140-150 处错误
|
||||
|
||||
---
|
||||
|
||||
### 提案 C：Handler 层参数校验安全加固
|
||||
|
||||
**范围**：
|
||||
- 所有 Handler 参数校验错误处理
|
||||
- 统一为不泄露内部细节
|
||||
|
||||
---
|
||||
|
||||
### 提案 D：OpenAPI 文档契约对齐
|
||||
|
||||
**范围**：
|
||||
- 响应 envelope 对齐
|
||||
- handlers 清单完整
|
||||
- 个人客户路由纳入文档
|
||||
|
||||
---
|
||||
|
||||
### 提案 E：代码清理和规范文档更新
|
||||
|
||||
**范围**：
|
||||
- 移除任务模块占位
|
||||
- 清理注释一致性
|
||||
- 更新规范文档
|
||||
- 回归验证
|
||||
|
||||
---
|
||||
|
||||
## 技术债务记录
|
||||
|
||||
### 已解决
|
||||
- ✅ 限流不覆盖真实业务路由
|
||||
- ✅ 短信服务未配置时崩溃
|
||||
- ✅ 核心认证链路错误语义不一致
|
||||
|
||||
### 待解决
|
||||
- ⏸️ 224 处 Service 层 `fmt.Errorf` 待替换
|
||||
- ⏸️ Handler 层参数校验错误泄露内部细节
|
||||
- ⏸️ OpenAPI 文档与真实响应不一致
|
||||
- ⏸️ 任务模块占位代码存在鉴权风险
|
||||
|
||||
---
|
||||
|
||||
## 验证清单
|
||||
|
||||
### 已完成部分验证
|
||||
|
||||
**限流功能**：
|
||||
```bash
|
||||
# 1. 检查限流配置
|
||||
grep -A 10 "enable_rate_limiter" pkg/config/defaults/config.yaml
|
||||
|
||||
# 2. 验证限流生效
|
||||
source .env.local && go run cmd/api/main.go &
|
||||
for i in {1..10}; do curl http://localhost:3000/api/admin/login; done
|
||||
|
||||
# 3. 验证健康检查不受限流
|
||||
for i in {1..10}; do curl http://localhost:3000/health; done
|
||||
```
|
||||
|
||||
**验证码服务**：
|
||||
```bash
|
||||
# 1. 未配置短信服务测试
|
||||
unset JUNHONG_SMS_ENABLED
|
||||
go test -v ./internal/service/verification/... -run TestSendCode
|
||||
|
||||
# 2. 验证错误码正确性
|
||||
# 预期：CodeServiceUnavailable (2004) → HTTP 503
|
||||
```
|
||||
|
||||
**认证服务**：
|
||||
```bash
|
||||
# 运行认证相关测试
|
||||
source .env.local && go test -v ./internal/service/auth/...
|
||||
source .env.local && go test -v ./internal/service/personal_customer/...
|
||||
```
|
||||
|
||||
### 待验证部分
|
||||
|
||||
**编译检查**：
|
||||
```bash
|
||||
go build -o /tmp/test_build ./cmd/api
|
||||
go build -o /tmp/test_build ./cmd/worker
|
||||
```
|
||||
|
||||
**全量测试**（待完成后执行）：
|
||||
```bash
|
||||
source .env.local && go test ./...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 归档原因
|
||||
|
||||
由于 Service 层错误语义统一工作量巨大（224 处待处理），需要逐一分析业务语义并选择合适的错误码，继续在单一变更中完成会导致：
|
||||
|
||||
1. **变更风险过高**：单次变更影响 27 个 Service 文件
|
||||
2. **测试覆盖不足**：无法为每个模块补充充分的回归测试
|
||||
3. **Code Review 困难**：单次 PR 包含 200+ 处修改难以审查
|
||||
|
||||
因此决定将已完成的高优先级部分（限流 + 验证码 + 核心认证）归档，剩余工作拆分为独立提案逐步完成。
|
||||
@@ -0,0 +1,63 @@
|
||||
# Design: 全局业务一致性修复（错误语义/文档/功能完整性）
|
||||
|
||||
## 1. 核心设计原则
|
||||
|
||||
1) 对外契约一致：文档（OpenAPI）必须描述真实线上响应结构与字段名。
|
||||
2) 业务语义一致：预期业务错误必须是 4xx + 稳定业务 code；不可将“可预期失败”变成 500。
|
||||
3) 不泄露内部细节：校验细节、数据库/第三方错误细节仅写日志，不直接返回给客户端。
|
||||
4) 分层一致：Handler 只做输入解析/鉴权/返回；Service 输出结构化错误；Store 负责数据访问。
|
||||
|
||||
## 2. 错误处理与报错规范（落地策略）
|
||||
|
||||
### 2.1 Handler 层
|
||||
- 参数解析失败：`errors.New(CodeInvalidParam, "请求参数解析失败")`。
|
||||
- 参数校验失败：**不返回** `validator` 的 `err.Error()`；统一返回 `errors.New(CodeInvalidParam)`（客户端 msg 为“参数验证失败”）。
|
||||
- 下游错误：直接 `return err`，交给全局 ErrorHandler。
|
||||
|
||||
### 2.2 Service 层（本次全量改造范围）
|
||||
- 禁止对外返回 `fmt.Errorf(...)` 作为业务错误。
|
||||
- 业务校验错误（可预期）：`errors.New(<4xx-code>[, message])`。
|
||||
- 依赖/数据库/队列错误（不可预期）：`errors.Wrap(<5xx-code>, err, "业务动作失败")`。
|
||||
|
||||
### 2.3 全局 ErrorHandler（既有行为保持）
|
||||
- 对 5xx：统一返回映射表通用 msg（避免泄露），但日志保留完整 err 与上下文。
|
||||
- 对 4xx：返回 AppError.Message；因此 Handler/Service 必须避免把内部细节塞进 Message。
|
||||
|
||||
## 3. 限流覆盖策略
|
||||
|
||||
### 3.1 范围
|
||||
- 覆盖：`/api/admin`、`/api/h5`、`/api/c/v1`。
|
||||
- 排除：`/api/callback`（第三方回调）、`/health`、`/ready`。
|
||||
|
||||
### 3.2 实现要点
|
||||
- 限流 middleware 应挂到真实 group 上，而非孤立的 `/api/v1`。
|
||||
- 仍保留配置开关与存储后端（memory/redis）。
|
||||
|
||||
## 4. OpenAPI 输出对齐（envelope）
|
||||
|
||||
### 4.1 字段名对齐
|
||||
- 错误响应：`{code, data, msg, timestamp}`（与运行时一致），不使用 `message` 字段。
|
||||
|
||||
### 4.2 成功响应结构
|
||||
- 每个接口的 200 响应在 OpenAPI 中体现 envelope：
|
||||
- code: integer
|
||||
- msg: string
|
||||
- timestamp: date-time
|
||||
- data: 具体 DTO（保持类型信息）
|
||||
|
||||
备注：实现时可以在 `pkg/openapi/generator.go` 内构造标准 envelope schema，并把 output DTO schema 嵌入到 data 属性。
|
||||
|
||||
## 5. 文档生成入口一致性
|
||||
|
||||
- `cmd/api/docs.go` 与 `cmd/gendocs/main.go` 应复用同一份“文档生成用 handlers 构造器”，避免漏 Handler 与重复维护。
|
||||
|
||||
## 6. 任务模块处理（移除）
|
||||
|
||||
- 移除 `/api/admin/tasks/:id` 占位路由（当前返回固定 pending 且存在鉴权不一致风险）。
|
||||
- 移除未接入路由的 `internal/handler/admin/task.go`，避免误导。
|
||||
- Worker 侧任务处理器保留（已有业务模块会通过队列提交任务）。
|
||||
|
||||
## 7. 个人客户路由纳入文档体系
|
||||
|
||||
- `internal/routes/personal.go` 改为使用 `Register(...)` 并接受 `doc` 参数（与其他域一致）。
|
||||
- 文档生成器 handlers 清单补齐 `PersonalCustomer`。
|
||||
@@ -0,0 +1,62 @@
|
||||
# Change: 全局业务一致性修复（错误语义/文档/功能完整性）
|
||||
|
||||
## Why
|
||||
|
||||
当前代码存在多处“接口看起来存在，但对外契约/行为/可用性不一致”的问题，已经影响到：
|
||||
|
||||
- 对接可靠性：OpenAPI 文档与真实返回字段不一致（`msg` vs `message`），且成功响应在文档中未体现统一 envelope。
|
||||
- 文档完整性：OpenAPI 生成时使用的 handlers 清单不完整，导致部分已注册路由不出现在文档；个人客户 `/api/c/v1` 路由不进入文档体系。
|
||||
- 功能完整性：验证码服务在 smsClient 未配置时会触发 nil pointer；大量 Service 使用 `fmt.Errorf` 返回业务错误，最终被全局 ErrorHandler 归类为 500，导致业务语义丢失。
|
||||
- 行为一致性与安全：存在 `Auth=true`（文档/元数据宣称需要认证）但真实路由未挂载认证中间件的情况；限流配置开启但实际不覆盖真实 API 路由。
|
||||
|
||||
本变更的目标是把“对外契约（文档 + 返回码 + 字段名 + 行为）”与“真实运行时行为”对齐，消除不可用、误导和潜在安全风险。
|
||||
|
||||
## What Changes
|
||||
|
||||
按阶段推进，优先止血，再做全量一致性修复：
|
||||
|
||||
### Phase A：线上止血（高优先级）
|
||||
- 限流覆盖真实 API 路由组：`/api/admin` + `/api/h5` + `/api/c/v1`；明确排除 `/api/callback`、健康检查等非业务入口。
|
||||
- 修复验证码链路的“未配置即崩溃”：短信服务未配置时返回 503（`CodeServiceUnavailable`），不 panic。
|
||||
- 移除任务模块的占位/死代码：删除 `/api/admin/tasks/:id` 占位路由与未接入路由的 TaskHandler，避免“看似可用”且存在鉴权不一致风险。
|
||||
|
||||
### Phase B：错误语义全量统一（高影响面）
|
||||
- **全量**替换 `internal/service/**` 中的 `fmt.Errorf` 作为对外错误返回：
|
||||
- 预期业务错误返回 `errors.New(code)` 或 `errors.New(code, message)`（4xx）。
|
||||
- 依赖/数据库/队列等底层错误返回 `errors.Wrap(code, err, message)`（5xx，客户端返回通用 msg）。
|
||||
- 统一参数校验错误策略：对外不拼接 `validator` 的 `err.Error()`；详细信息只写日志。
|
||||
|
||||
### Phase C：文档契约对齐（OpenAPI 变更）
|
||||
- OpenAPI 文档输出与真实响应一致：所有成功/失败响应均体现 `{code, data, msg, timestamp}`。
|
||||
- 修复文档生成器 handlers 清单缺失问题，并消除 `cmd/api/docs.go` 与 `cmd/gendocs/main.go` 的重复逻辑。
|
||||
- 个人客户 `/api/c/v1` 路由接入 `Register(...)`（带 RouteSpec），纳入 OpenAPI。
|
||||
|
||||
## Decisions（已确认）
|
||||
|
||||
- OpenAPI 以真实 envelope 为准：`{code, data, msg, timestamp}`。
|
||||
- 限流覆盖范围：`/api/admin` + `/api/h5` + `/api/c/v1`；排除 `/api/callback`、健康检查。
|
||||
- 短信服务未配置时：返回 503（`CodeServiceUnavailable`）。
|
||||
- 任务模块：移除占位路由与未接入的 TaskHandler（不在本次提供任务提交 API）。
|
||||
- Service 层错误处理：`internal/service/**` 内 **全量**替换 `fmt.Errorf` 对外返回方式，统一为 `errors.New/Wrap`。
|
||||
|
||||
## Impact
|
||||
|
||||
### Affected specs
|
||||
- **UPDATE**: `openspec/specs/error-handling/spec.md`（补全 Purpose，新增“错误报错规范”要求：禁止泄露校验细节、Service 层对外错误必须结构化等）
|
||||
- **UPDATE**: `openspec/specs/openapi-generation/spec.md`（OpenAPI 输出需要体现统一 envelope）
|
||||
- **UPDATE**: `openspec/specs/personal-customer/spec.md`（个人客户 API 进入文档体系）
|
||||
|
||||
### Affected code (high level)
|
||||
- 限流挂载与路由分组：`cmd/api/main.go`
|
||||
- 验证码/个人客户登录链路：`internal/service/verification/service.go`、`internal/service/personal_customer/service.go`
|
||||
- 全量 Service 错误改造：`internal/service/**`
|
||||
- 参数校验错误对齐：`internal/handler/**`
|
||||
- OpenAPI 生成器：`pkg/openapi/generator.go`
|
||||
- 文档生成入口：`cmd/api/docs.go`、`cmd/gendocs/main.go`
|
||||
- 个人客户路由注册：`internal/routes/personal.go`、`internal/routes/routes.go`
|
||||
- 移除任务占位：`internal/routes/task.go`、`internal/routes/routes.go`、`internal/handler/admin/task.go`
|
||||
|
||||
### Breaking changes
|
||||
- 移除 `/api/admin/tasks/:id` 占位接口（如有调用方，需要同步调整）。
|
||||
- 多个接口的错误 HTTP 状态码会从 500 调整为 4xx（例如验证码错误、账号禁用等预期业务错误）。
|
||||
- OpenAPI 文档结构变化：响应将统一包裹 envelope（生成 SDK/对接方会受到影响，但与真实行为一致）。
|
||||
@@ -0,0 +1,43 @@
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 参数校验错误不泄露内部细节
|
||||
|
||||
系统在处理参数校验失败时 SHALL 避免向客户端泄露校验细节（字段名、规则表达式等），以减少对外暴露内部实现并保持错误语义稳定。
|
||||
|
||||
#### Scenario: validator 校验失败的对外返回
|
||||
|
||||
- **WHEN** Handler 使用 validator 对请求参数进行校验且校验失败
|
||||
- **THEN** Handler 对外仅返回 `errors.New(errors.CodeInvalidParam)`
|
||||
- **AND** 响应的 `msg` 为统一短消息（例如“参数验证失败”）
|
||||
- **AND** 不拼接或直接返回 `validator` 的 `err.Error()`
|
||||
|
||||
#### Scenario: 校验细节仅写入日志
|
||||
|
||||
- **WHEN** 参数校验失败
|
||||
- **THEN** 系统在日志中记录完整的校验错误细节（用于排查）
|
||||
- **AND** 日志字段包含请求路径、请求方法、request_id（如可用）
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Service 对外错误必须结构化
|
||||
|
||||
Service 层 SHALL 对外返回结构化错误（AppError），以确保全局 ErrorHandler 能正确区分 4xx 业务错误与 5xx 系统错误。
|
||||
|
||||
#### Scenario: 预期业务错误返回 4xx
|
||||
|
||||
- **WHEN** Service 发生可预期的业务错误（例如：验证码错误/过期、状态不允许、资源不存在）
|
||||
- **THEN** 返回 `errors.New(<4xx-code>[, message])`
|
||||
- **AND** 全局 ErrorHandler 将其映射为对应的 4xx HTTP 状态码
|
||||
|
||||
#### Scenario: 非预期系统错误返回 5xx
|
||||
|
||||
- **WHEN** Service 调用数据库/缓存/队列/第三方依赖发生错误
|
||||
- **THEN** 返回 `errors.Wrap(<5xx-code>, err, "业务动作失败")`
|
||||
- **AND** 客户端响应 `msg` 为错误码映射表中的通用描述（不包含底层 err 细节）
|
||||
|
||||
#### Scenario: 禁止 fmt.Errorf 作为对外错误
|
||||
|
||||
- **WHEN** Service 需要对外返回错误
|
||||
- **THEN** 不使用 `fmt.Errorf(...)` 作为返回值
|
||||
- **AND** 必须转换为 `errors.New(...)` 或 `errors.Wrap(...)`
|
||||
@@ -0,0 +1,28 @@
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: OpenAPI 响应结构与运行时一致
|
||||
|
||||
系统生成的 OpenAPI 文档 SHALL 反映真实运行时的统一响应 envelope（成功与失败均一致）。
|
||||
|
||||
#### Scenario: 成功响应使用统一 envelope
|
||||
|
||||
- **WHEN** OpenAPI 生成器为任一接口生成 200 响应 schema
|
||||
- **THEN** 响应结构包含 `code`、`msg`、`data`、`timestamp`
|
||||
- **AND** `data` 字段的 schema 使用该接口的业务 DTO（保持类型信息）
|
||||
|
||||
#### Scenario: 错误响应使用统一 envelope
|
||||
|
||||
- **WHEN** OpenAPI 生成器为任一接口生成标准错误响应（4xx/5xx）
|
||||
- **THEN** 错误响应结构包含 `code`、`msg`、`data`、`timestamp`
|
||||
- **AND** 字段名使用 `msg`（不使用 `message`）
|
||||
|
||||
### Requirement: OpenAPI 文档覆盖所有真实路由
|
||||
|
||||
系统生成的 OpenAPI 文档 SHALL 覆盖所有实际注册的 HTTP 路由，避免“路由存在但文档缺失”。
|
||||
|
||||
#### Scenario: 个人客户路由纳入文档
|
||||
|
||||
- **WHEN** 注册 `/api/c/v1` 个人客户相关路由
|
||||
- **THEN** 路由注册应使用项目统一的 `Register(...)` 机制
|
||||
- **AND** OpenAPI 文档包含对应路径与方法
|
||||
@@ -0,0 +1,59 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. 止血：限流覆盖真实 API 路由组
|
||||
- [x] 1.1 调整 `cmd/api/main.go` 的限流挂载位置，覆盖 `/api/admin`、`/api/h5`、`/api/c/v1`
|
||||
- [x] 1.2 明确排除 `/api/callback`、`/health`、`/ready`（避免误限流）
|
||||
- [x] 1.3 补充/更新相关文档说明（限流生效范围）
|
||||
|
||||
## 2. 止血：短信验证码未配置不崩溃
|
||||
- [x] 2.1 为短信客户端增加初始化流程（基于配置）
|
||||
- [x] 2.2 `verification.Service` 在 smsClient 为空时返回 `errors.New(CodeServiceUnavailable)`（HTTP 503）
|
||||
- [x] 2.3 为验证码发送/验证关键路径添加/补充测试用例（至少覆盖“未配置短信服务”的返回）
|
||||
|
||||
## 3. 全量：Service 层错误语义统一（internal/service/**）
|
||||
- [~] 3.1 【部分完成】制定并落地“Service 对外错误必须结构化”的规则（`errors.New/Wrap`），禁止对外直接返回 `fmt.Errorf`
|
||||
- [ ] 3.2 扫描并替换 `internal/service/**` 中所有 `fmt.Errorf` 对外返回点（全量）
|
||||
- **已完成文件**：verification/service.go (10处), personal_customer/service.go (11处), auth/service.go (4处), device_import/service.go (2处)
|
||||
- **待完成文件**：24个文件，约224处 fmt.Errorf 待替换
|
||||
- [ ] 3.3 对“预期业务错误”统一返回 4xx（例如验证码错误/过期、账号禁用等）
|
||||
- [ ] 3.4 对“依赖/数据库/队列错误”统一使用 `errors.Wrap(<5xx-code>, err, msg)`
|
||||
- [ ] 3.5 针对变更量最大的模块补充回归测试（优先：verification / personal_customer / auth / package / order）
|
||||
|
||||
## 4. 全量：参数校验错误不泄露内部细节
|
||||
- [ ] 4.1 扫描 `internal/handler/**` 中所有 `"参数验证失败: "+err.Error()` / 直接返回 `err.Error()` 的位置
|
||||
- [ ] 4.2 调整为：对外返回 `errors.New(CodeInvalidParam)`（或固定中文短消息），详细 err 仅写日志
|
||||
- [ ] 4.3 补充单测/集成测试，确保返回 msg 不包含 validator 内部细节
|
||||
|
||||
## 5. OpenAPI：响应 envelope 与字段名对齐
|
||||
- [ ] 5.1 修复 OpenAPI 错误响应 schema 字段名（`msg` 替代 `message`）
|
||||
- [ ] 5.2 让 OpenAPI 200 响应体现 `{code,data,msg,timestamp}` envelope（data 保持具体 DTO schema）
|
||||
- [ ] 5.3 重新生成文档并人工抽查关键接口（admin/h5/c端）
|
||||
|
||||
## 6. OpenAPI：生成入口 handlers 清单一致且完整
|
||||
- [ ] 6.1 抽取“文档生成用 handlers 构造器”，供 `cmd/api/docs.go` 与 `cmd/gendocs/main.go` 复用
|
||||
- [ ] 6.2 补齐缺失 handlers（PersonalCustomer、ShopPackageBatchAllocation、ShopPackageBatchPricing）
|
||||
- [ ] 6.3 避免文档生成用 handler 需要真实依赖（保持 nil 依赖安全）
|
||||
|
||||
## 7. 路由：个人客户 `/api/c/v1` 纳入 Register(...) 与文档
|
||||
- [ ] 7.1 改造 `internal/routes/personal.go`：支持 doc 生成，使用 `Register(...)`
|
||||
- [ ] 7.2 更新 `internal/routes/routes.go` 的调用方式（传入 doc/basePath）
|
||||
- [ ] 7.3 补充个人客户 API 的 RouteSpec（Summary/Tags/Input/Output/Auth）
|
||||
|
||||
## 8. 任务模块：移除占位与死代码
|
||||
- [ ] 8.1 移除 `internal/routes/task.go` 与 `routes.go` 中的 `registerTaskRoutes(...)` 调用
|
||||
- [ ] 8.2 移除未接入路由的 `internal/handler/admin/task.go`
|
||||
- [ ] 8.3 更新文档/README（如有提及任务 API）
|
||||
|
||||
## 9. 注释与遗留一致性清理（低风险）
|
||||
- [ ] 9.1 清理 `internal/handler/**` 中残留的 `/api/v1/...` 注释（与真实 `/api/admin` 等路径一致）
|
||||
|
||||
## 10. 规范落地：把错误报错规则写入项目规范
|
||||
- [ ] 10.1 更新 `openspec/specs/error-handling/spec.md`（Purpose + 新增“错误报错规范”条款）
|
||||
- [ ] 10.2 更新 `AGENTS.md` 增加“错误报错规范”摘要与检查清单
|
||||
- [ ] 10.3 更新 `docs/003-error-handling/使用指南.md`，形成可执行的开发/Code Review 规范
|
||||
- [ ] 10.4 增加 CI/脚本检查：禁止 `internal/service/**` 出现 `fmt.Errorf(`（允许白名单场景需显式说明）
|
||||
|
||||
## 11. 回归验证
|
||||
- [ ] 11.1 `go test ./...`（含必要的集成测试准备说明）
|
||||
- [ ] 11.2 重新生成 OpenAPI 并检查差异（接口数量、路径、响应字段）
|
||||
- [ ] 11.3 手工验证关键链路：验证码发送/登录、B 端登录、限流生效范围
|
||||
Reference in New Issue
Block a user