feat: 完成B端认证系统和商户管理模块测试补全

主要变更： - 新增B端认证系统（后台+H5）：登录、登出、Token刷新、密码修改 - 完善商户管理和商户账号管理功能 - 补全单元测试（ShopService: 72.5%, ShopAccountService: 79.8%） - 新增集成测试（商户管理+商户账号管理） - 归档OpenSpec提案（add-shop-account-management, implement-b-end-auth-system） - 完善文档（使用指南、API文档、认证架构说明）测试统计： - 13个测试套件，37个测试用例，100%通过率 - 平均覆盖率76.2%，达标 OpenSpec验证：通过（strict模式）
2026-01-15 18:15:17 +08:00
parent 7ccd3d146c
commit 18f35f3ef4
64 changed files with 11875 additions and 242 deletions
--- a/docs/openapi-enhancement-summary.md
+++ b/docs/openapi-enhancement-summary.md
@@ -0,0 +1,317 @@
+# OpenAPI 文档增强总结
+
+## 更新日期
+2026-01-15
+
+## 增强内容
+
+### 1. 自动认证标记
+
+为所有需要认证的端点自动添加 `security` 标记。
+
+**实现方式**：
+- 在 `RouteSpec` 中使用 `Auth: true` 字段标记需要认证的端点
+- `Register` 函数自动传递 `Auth` 字段到 OpenAPI 生成器
+- 生成器自动添加 `security: [BearerAuth: []]` 到操作定义
+
+**示例**：
+
+公开端点（`Auth: false`）：
+```yaml
+/api/admin/login:
+  post:
+    summary: 后台登录
+    # 无 security 字段
+```
+
+认证端点（`Auth: true`）：
+```yaml
+/api/admin/logout:
+  post:
+    summary: 登出
+    security:
+      - BearerAuth: []
+```
+
+### 2. 标准错误响应
+
+为所有端点自动添加标准错误响应。
+
+**错误响应规则**：
+- **所有端点**：400 (请求参数错误), 500 (服务器内部错误)
+- **认证端点**：额外添加 401 (未认证或认证已过期), 403 (无权访问)
+
+**ErrorResponse Schema**：
+```yaml
+ErrorResponse:
+  type: object
+  required:
+    - code
+    - message
+    - timestamp
+  properties:
+    code:
+      type: integer
+      description: 错误码
+    message:
+      type: string
+      description: 错误消息
+    timestamp:
+      type: string
+      format: date-time
+      description: 时间戳
+```
+
+**示例**：
+
+公开端点错误响应：
+```yaml
+responses:
+  "200":
+    description: OK
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/ModelLoginResponse'
+  "400":
+    description: 请求参数错误
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/ErrorResponse'
+  "500":
+    description: 服务器内部错误
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/ErrorResponse'
+```
+
+认证端点错误响应：
+```yaml
+responses:
+  "200":
+    description: OK
+  "400":
+    description: 请求参数错误
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/ErrorResponse'
+  "401":
+    description: 未认证或认证已过期
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/ErrorResponse'
+  "403":
+    description: 无权访问
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/ErrorResponse'
+  "500":
+    description: 服务器内部错误
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/ErrorResponse'
+```
+
+### 3. Bearer Token 认证定义
+
+在 OpenAPI 规范中添加 Bearer Token 认证方案定义。
+
+```yaml
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+## 修改的文件
+
+### 核心文件
+
+1. **pkg/openapi/generator.go**
+   - 修改 `AddOperation` 方法，新增 `requiresAuth` 参数
+   - 新增 `addSecurityRequirement` 方法：为操作添加认证要求
+   - 新增 `addStandardErrorResponses` 方法：添加标准错误响应
+   - 新增 `addErrorResponseSchema` 方法：添加错误响应 Schema 定义
+   - 新增 `ptrString` 辅助函数
+
+2. **internal/routes/registry.go**
+   - 更新 `Register` 函数，传递 `spec.Auth` 到生成器
+
+### 路由注册文件
+
+更新以下文件中的 `RouteSpec`，为所有端点添加 `Auth` 字段：
+
+1. **internal/routes/admin.go**
+   - 公开端点（login, refresh-token）：`Auth: false`
+   - 认证端点（logout, me, password）：`Auth: true`
+
+2. **internal/routes/h5.go**
+   - 公开端点（login, refresh-token）：`Auth: false`
+   - 认证端点（logout, me, password）：`Auth: true`
+
+3. **internal/routes/account.go**
+   - 所有账号管理端点：`Auth: true` (17 个端点)
+
+4. **internal/routes/role.go**
+   - 所有角色管理端点：`Auth: true` (9 个端点)
+
+5. **internal/routes/permission.go**
+   - 所有权限管理端点：`Auth: true` (6 个端点)
+
+### 文档生成脚本
+
+**cmd/gendocs/main.go**
+- 添加 `AdminAuth` Handler 到 handlers 结构体
+- 确保认证端点包含在生成的文档中
+
+## 验证结果
+
+### 1. 编译验证
+```bash
+✅ go build ./... - 编译通过
+✅ go build ./pkg/openapi/... - OpenAPI 包编译通过
+✅ go build ./internal/routes/... - 路由包编译通过
+```
+
+### 2. 文档生成验证
+```bash
+✅ CONFIG_ENV=dev go run cmd/gendocs/main.go
+✅ 文档生成成功：docs/admin-openapi.yaml
+✅ 包含所有端点（认证 + 业务端点）
+```
+
+### 3. 内容验证
+
+**Security Scheme**：
+```bash
+✅ grep "securitySchemes:" docs/admin-openapi.yaml
+✅ BearerAuth 定义存在
+```
+
+**ErrorResponse Schema**：
+```bash
+✅ grep "ErrorResponse:" docs/admin-openapi.yaml
+✅ 包含 code, message, timestamp 字段
+✅ Required 字段定义正确
+```
+
+**公开端点（login）**：
+```bash
+✅ 只有 400, 500 错误响应
+✅ 没有 security 标记
+✅ 没有 401, 403 错误响应
+```
+
+**认证端点（logout）**：
+```bash
+✅ 有 400, 401, 403, 500 错误响应
+✅ 有 security: [BearerAuth: []]
+✅ 错误响应引用 ErrorResponse schema
+```
+
+## 使用方法
+
+### 1. 注册新端点
+
+在路由注册时，显式设置 `Auth` 字段：
+
+```go
+// 公开端点
+Register(router, doc, basePath, "POST", "/public", handler, RouteSpec{
+    Summary: "公开端点",
+    Tags:    []string{"公开"},
+    Input:   new(RequestModel),
+    Output:  new(ResponseModel),
+    Auth:    false,  // 不需要认证
+})
+
+// 认证端点
+Register(authGroup, doc, basePath, "GET", "/protected", handler, RouteSpec{
+    Summary: "受保护端点",
+    Tags:    []string{"业务"},
+    Input:   nil,
+    Output:  new(ResponseModel),
+    Auth:    true,  // 需要认证
+})
+```
+
+### 2. 生成文档
+
+```bash
+# 开发环境
+CONFIG_ENV=dev go run cmd/gendocs/main.go
+
+# 生产环境
+CONFIG_ENV=prod go run cmd/gendocs/main.go
+```
+
+生成的文档位于 `docs/admin-openapi.yaml`。
+
+### 3. 查看文档
+
+**方法 1：使用 Swagger UI**
+```bash
+# 访问 https://editor.swagger.io/
+# 将 docs/admin-openapi.yaml 内容粘贴到编辑器
+```
+
+**方法 2：使用 Postman**
+```bash
+# File → Import → Upload Files
+# 选择 docs/admin-openapi.yaml
+```
+
+**方法 3：使用 Redoc**
+```bash
+npx @redocly/cli preview-docs docs/admin-openapi.yaml
+```
+
+## 后续优化（可选）
+
+当前已完成的高优先级任务：
+- ✅ 自动添加 security 标记
+- ✅ 自动添加标准错误响应
+- ✅ 定义 ErrorResponse schema
+- ✅ 更新所有路由注册
+
+低优先级增强（可在后续迭代完成）：
+- [ ] 为请求/响应模型添加示例值（example）
+- [ ] 为字段添加详细的验证规则说明（自动从 validator 标签提取）
+
+这些低优先级功能不影响当前文档的可用性，可以根据需要在后续版本中添加。
+
+## 影响范围
+
+**破坏性变更**：无
+
+**向后兼容**：是
+- 旧代码不需要修改即可工作
+- 未设置 `Auth` 字段的 RouteSpec 默认为 `false`（公开端点）
+
+**API 变更**：无
+- 只影响 OpenAPI 文档生成
+- 不影响运行时行为
+
+## 总结
+
+本次增强为 OpenAPI 文档自动生成系统添加了以下关键功能：
+
+1. **自动认证标记**：通过 `Auth` 字段自动为认证端点添加 `security` 标记
+2. **标准错误响应**：自动为所有端点添加统一的错误响应定义
+3. **错误响应 Schema**：定义了标准的 `ErrorResponse` 结构
+
+这些增强使得：
+- 文档更加完整和规范
+- API 使用者能清楚了解哪些端点需要认证
+- 错误处理文档化，提升 API 可用性
+- 减少手动维护文档的工作量
+
+所有高优先级功能已完成并验证通过，可以投入使用。