csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

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

Browse Source 
主要变更：
- 新增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模式）
This commit is contained in:
huang
2026-01-15 18:15:17 +08:00
parent 7ccd3d146c
commit 18f35f3ef4
64 changed files with 11875 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files

380
docs/api-doc-update-summary.md Normal file
View File

@@ -0,0 +1,380 @@
# API 文档自动生成更新总结
## 📝 更新概述
为了将 B 端认证系统的所有端点包含在自动生成的 OpenAPI 文档中，我们进行了以下更新：
---
## 🔧 更新内容
### 1. **路由注册函数更新**
**文件**:
- `internal/routes/admin.go`
- `internal/routes/h5.go`
**改动**：将认证端点从直接注册改为使用 `Register` 辅助函数，以便生成文档
**修改前**:
```go
router.Post("/login", h.Login)
router.Post("/refresh-token", h.RefreshToken)
```
**修改后**:
```go
Register(router, doc, basePath, "POST", "/login", h.Login, RouteSpec{
Summary: "后台登录",
Tags: []string{"认证"},
Input: new(model.LoginRequest),
Output: new(model.LoginResponse),
})
```
**新增端点文档**（共 10 个）:
- ✅ `POST /api/admin/login` - 后台登录
- ✅ `POST /api/admin/logout` - 登出
- ✅ `POST /api/admin/refresh-token` - 刷新 Token
- ✅ `GET /api/admin/me` - 获取当前用户信息
- ✅ `PUT /api/admin/password` - 修改密码
- ✅ `POST /api/h5/login` - H5 登录
- ✅ `POST /api/h5/logout` - 登出
- ✅ `POST /api/h5/refresh-token` - 刷新 Token
- ✅ `GET /api/h5/me` - 获取当前用户信息
- ✅ `PUT /api/h5/password` - 修改密码
---
### 2. **OpenAPI 生成器增强**
**文件**: `pkg/openapi/generator.go`
**新增功能**: 自动添加 Bearer Token 认证定义
**新增代码**:
```go
// addBearerAuth 添加 Bearer Token 认证定义
func (g *Generator) addBearerAuth() {
bearerFormat := "JWT"
g.Reflector.Spec.ComponentsEns().SecuritySchemesEns().WithMapOfSecuritySchemeOrRefValuesItem(
"BearerAuth",
openapi3.SecuritySchemeOrRef{
SecurityScheme: &openapi3.SecurityScheme{
HTTPSecurityScheme: &openapi3.HTTPSecurityScheme{
Scheme: "bearer",
BearerFormat: &bearerFormat,
},
},
},
)
}
```
**效果**: 在 `openapi.yaml` 中自动生成：
```yaml
components:
securitySchemes:
BearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
```
---
### 3. **文档生成脚本更新**
**文件**: `cmd/api/docs.go`
**新增 Handler**:
- ✅ `AdminAuth` - 后台认证 Handler
- ✅ `H5Auth` - H5 认证 Handler
- ✅ `Shop` - 店铺管理 Handler
- ✅ `ShopAccount` - 店铺账号 Handler
**修改前**（只有 3 个 Handler）:
```go
accHandler := admin.NewAccountHandler(nil)
roleHandler := admin.NewRoleHandler(nil)
permHandler := admin.NewPermissionHandler(nil)
handlers := &bootstrap.Handlers{
Account: accHandler,
Role: roleHandler,
Permission: permHandler,
}
```
**修改后**（7 个 Handler）:
```go
adminAuthHandler := admin.NewAuthHandler(nil, nil)
h5AuthHandler := h5.NewAuthHandler(nil, nil)
accHandler := admin.NewAccountHandler(nil)
roleHandler := admin.NewRoleHandler(nil)
permHandler := admin.NewPermissionHandler(nil)
shopHandler := admin.NewShopHandler(nil)
shopAccHandler := admin.NewShopAccountHandler(nil)
handlers := &bootstrap.Handlers{
AdminAuth: adminAuthHandler,
H5Auth: h5AuthHandler,
Account: accHandler,
Role: roleHandler,
Permission: permHandler,
Shop: shopHandler,
ShopAccount: shopAccHandler,
}
```
**新增路由注册**:
```go
// 注册后台路由到文档生成器
adminGroup := app.Group("/api/admin")
routes.RegisterAdminRoutes(adminGroup, handlers, &bootstrap.Middlewares{}, adminDoc, "/api/admin")
// 注册 H5 路由到文档生成器
h5Group := app.Group("/api/h5")
routes.RegisterH5Routes(h5Group, handlers, &bootstrap.Middlewares{}, adminDoc, "/api/h5")
```
---
## 📊 生成的文档内容
### 认证端点示例
#### 1. 后台登录
```yaml
/api/admin/login:
post:
summary: 后台登录
tags:
- 认证
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ModelLoginRequest'
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModelLoginResponse'
```
#### 2. 获取当前用户
```yaml
/api/admin/me:
get:
summary: 获取当前用户信息
tags:
- 认证
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModelUserInfo'
```
### 请求/响应模型
自动生成的数据模型包括：
- ✅ `ModelLoginRequest` - 登录请求
- ✅ `ModelLoginResponse` - 登录响应
- ✅ `ModelRefreshTokenRequest` - 刷新 Token 请求
- ✅ `ModelRefreshTokenResponse` - 刷新 Token 响应
- ✅ `ModelChangePasswordRequest` - 修改密码请求
- ✅ `ModelUserInfo` - 用户信息
---
## 🎯 如何使用生成的文档
### 查看文档
生成的 OpenAPI 文档位于项目根目录：
```bash
cat openapi.yaml
```
### 使用 Swagger UI 查看
1. **在线工具**:
- 访问 https://editor.swagger.io/
- 将 `openapi.yaml` 内容粘贴进去
2. **本地启动 Swagger UI**:
```bash
docker run -p 8080:8080 \
-e SWAGGER_JSON=/openapi.yaml \
-v $(pwd)/openapi.yaml:/openapi.yaml \
swaggerapi/swagger-ui
```
然后访问 http://localhost:8080
### 导入到 Postman
1. 打开 Postman
2. 点击 "Import"
3. 选择 `openapi.yaml` 文件
4. 自动生成所有 API 请求集合
---
## 🔄 文档生成流程
### 自动生成
文档在每次启动 API 服务时自动生成：
```go
// cmd/api/main.go
func main() {
// ...
// 12. 生成 OpenAPI 文档
generateOpenAPIDocs("./openapi.yaml", appLogger)
// 13. 启动服务器
startServer(app, cfg, appLogger, cancelWatch)
}
```
### 手动生成
如果只想生成文档而不启动服务：
```bash
# 编译
go build -o /tmp/api_docs ./cmd/api/
# 运行并立即停止（文档会在启动时生成）
timeout 3s /tmp/api_docs || true
# 查看生成的文档
cat openapi.yaml
```
---
## 🎨 文档分类（Tags）
生成的文档按以下标签分类：
- **认证** - 所有认证相关端点（登录、登出、刷新等）
- **H5 认证** - H5 端认证端点
- **账号相关** - 账号管理（CRUD、角色分配等）
- **角色** - 角色管理
- **权限** - 权限管理
- **店铺** - 店铺管理
- **店铺账号** - 店铺账号管理
---
## ✅ 验证清单
- [x] 所有认证端点已包含在文档中
- [x] Bearer Token 认证方式已定义
- [x] 请求/响应模型完整
- [x] 端点描述清晰（中文 Summary）
- [x] 端点按标签正确分类
- [x] 后台和 H5 端点都已包含
---
## 📌 注意事项
### 1. **文档与实际路由同步**
由于使用了统一的 `Register` 函数，所有注册的路由都会自动出现在文档中。
确保不会出现文档与实际路由不一致的情况。
### 2. **nil 依赖 Handler**
文档生成时使用 `nil` 依赖创建 Handler：
```go
adminAuthHandler := admin.NewAuthHandler(nil, nil)
```
这是安全的，因为文档生成只需要路由结构，不会实际执行 Handler 逻辑。
### 3. **安全认证标记**
目前文档中的 `BearerAuth` 安全方案已定义，但未自动标记哪些端点需要认证。
**未来改进**（可选）:
可以在 `RouteSpec` 中添加 `RequireAuth bool` 字段，自动为需要认证的端点添加：
```yaml
security:
- BearerAuth: []
```
---
## 🔮 后续可能的改进
### 1. **错误响应文档**
当前只定义了 200 成功响应，可以添加错误响应：
```go
// 在 RouteSpec 中添加
type RouteSpec struct {
Summary string
Tags []string
Input interface{}
Output interface{}
ErrorOutput interface{} // 新增
}
```
### 2. **安全端点标记**
为需要认证的端点自动添加安全要求：
```go
// 在 AddOperation 中添加逻辑
if spec.RequireAuth {
op.Security = []openapi3.SecurityRequirement{
{"BearerAuth": []string{}},
}
}
```
### 3. **示例值**
为请求/响应添加示例值，便于前端开发者理解：
```yaml
examples:
LoginExample:
value:
username: "admin"
password: "Admin@123456"
```
---
## 📖 相关文档
- [API 文档](docs/api/auth.md) - 手写的详细 API 文档
- [使用指南](docs/auth-usage-guide.md) - 认证系统使用指南
- [架构说明](docs/auth-architecture.md) - 认证系统架构设计
---
## 总结
通过这次更新，我们实现了：
1. ✅ **认证端点完整性** - 所有 10 个认证端点都已包含
2. ✅ **安全定义** - Bearer Token 认证方式已定义
3. ✅ **自动同步** - 路由与文档自动保持一致
4. ✅ **易于维护** - 使用统一的 Register 函数
**OpenAPI 文档现在已经完整，可以直接用于前端开发、API 测试和文档展示！** 🎉