实现服务启动时自动生成OpenAPI文档

主要变更: 1. 新增 cmd/api/docs.go 实现文档自动生成逻辑 2. 修改 cmd/api/main.go 在服务启动时调用文档生成 3. 重构 cmd/gendocs/main.go 提取生成函数 4. 更新 .gitignore 忽略自动生成的 openapi.yaml 5. 新增 Makefile 支持 make docs 命令 6. OpenSpec 框架更新和变更归档功能特性: - 服务启动时自动生成 OpenAPI 文档到项目根目录 - 保留独立的文档生成工具 (make docs) - 生成失败时记录错误但不影响服务启动 - 所有代码已通过 openspec validate --strict 验证 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-09 12:25:50 +08:00
parent ddbc69135d
commit 6fc90abeb6
47 changed files with 1095 additions and 5519 deletions
--- a/openspec/specs/auth/spec.md
+++ b/openspec/specs/auth/spec.md
@@ -0,0 +1,65 @@
+# auth Specification
+
+## Purpose
+TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.
+## Requirements
+### Requirement: Unified Authentication Middleware
+
+系统 SHALL 提供统一的认证中间件，支持可配置的 Token 提取和验证。
+
+#### Scenario: Token 验证成功
+- **WHEN** 请求携带有效的 Token
+- **THEN** 中间件提取并验证 Token
+- **AND** 将用户信息同时设置到 Fiber Locals 和 Context
+- **AND** 请求继续执行
+
+#### Scenario: Token 缺失
+- **WHEN** 请求未携带 Token
+- **AND** 路径不在跳过列表中
+- **THEN** 返回 AppError（CodeMissingToken）
+- **AND** 由全局 ErrorHandler 处理错误响应
+
+#### Scenario: Token 无效
+- **WHEN** 请求携带的 Token 无效或过期
+- **THEN** 返回 AppError（CodeUnauthorized）
+- **AND** 由全局 ErrorHandler 处理错误响应
+
+#### Scenario: 跳过路径
+- **WHEN** 请求路径在 SkipPaths 配置中
+- **THEN** 中间件跳过认证
+- **AND** 请求直接继续执行
+
+### Requirement: User Context Management
+
+认证中间件 SHALL 提供用户上下文管理函数，支持从 Context 获取用户信息。
+
+#### Scenario: 获取用户 ID
+- **WHEN** 调用 GetUserIDFromContext(ctx)
+- **AND** 认证已通过
+- **THEN** 返回当前用户的 ID
+
+#### Scenario: 检查 Root 用户
+- **WHEN** 调用 IsRootUser(ctx)
+- **THEN** 返回当前用户是否为 Root 用户
+
+#### Scenario: 设置用户到 Fiber Context
+- **WHEN** 调用 SetUserToFiberContext(c, userInfo)
+- **THEN** 用户信息被设置到 Fiber Locals
+- **AND** 用户信息被设置到请求 Context（供 GORM 等使用）
+
+### Requirement: Auth Middleware Configuration
+
+认证中间件 SHALL 支持灵活的配置选项。
+
+#### Scenario: 自定义 Token 提取
+- **WHEN** 配置了 TokenExtractor 函数
+- **THEN** 使用自定义函数从请求中提取 Token
+
+#### Scenario: 默认 Token 提取
+- **WHEN** 未配置 TokenExtractor
+- **THEN** 从 Authorization Header 提取 Bearer Token
+
+#### Scenario: 自定义验证函数
+- **WHEN** 配置了 Validator 函数
+- **THEN** 使用自定义函数验证 Token 并返回用户信息
+
--- a/openspec/specs/data-permission/spec.md
+++ b/openspec/specs/data-permission/spec.md
@@ -0,0 +1,65 @@
+# data-permission Specification
+
+## Purpose
+TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.
+## Requirements
+### Requirement: GORM Callback Data Permission
+
+系统 SHALL 使用 GORM Callback 机制自动为所有查询添加数据权限过滤。
+
+#### Scenario: 自动应用权限过滤
+- **WHEN** 执行 GORM 查询
+- **AND** Context 包含用户信息
+- **AND** 表包含 owner_id 字段
+- **THEN** 自动添加 WHERE owner_id IN (subordinateIDs) 条件
+
+#### Scenario: Root 用户跳过过滤
+- **WHEN** 当前用户是 Root 用户
+- **THEN** 不添加任何数据权限过滤条件
+- **AND** 可查询所有数据
+
+#### Scenario: 无 owner_id 字段的表
+- **WHEN** 表不包含 owner_id 字段
+- **THEN** 不添加数据权限过滤条件
+
+### Requirement: Skip Data Permission
+
+系统 SHALL 支持通过 Context 绕过数据权限过滤。
+
+#### Scenario: 显式跳过权限过滤
+- **WHEN** 调用 SkipDataPermission(ctx) 获取新 Context
+- **AND** 使用该 Context 执行 GORM 查询
+- **THEN** 不添加任何数据权限过滤条件
+
+#### Scenario: 内部操作跳过过滤
+- **WHEN** 执行内部同步、批量操作或管理员操作
+- **THEN** 应使用 SkipDataPermission 绕过过滤
+
+### Requirement: Subordinate IDs Caching
+
+系统 SHALL 缓存用户的下级 ID 列表以提高查询性能。
+
+#### Scenario: 缓存命中
+- **WHEN** 获取用户下级 ID 列表
+- **AND** Redis 缓存存在
+- **THEN** 直接返回缓存数据
+
+#### Scenario: 缓存未命中
+- **WHEN** 获取用户下级 ID 列表
+- **AND** Redis 缓存不存在
+- **THEN** 执行递归 CTE 查询获取下级 ID
+- **AND** 将结果缓存到 Redis（30 分钟过期）
+
+### Requirement: Callback Registration
+
+系统 SHALL 在应用启动时注册 GORM 数据权限 Callback。
+
+#### Scenario: 注册 Callback
+- **WHEN** 调用 RegisterDataPermissionCallback(db, accountStore)
+- **THEN** 注册 Query Before Callback
+- **AND** Callback 名称为 "data_permission"
+
+#### Scenario: AccountStore 依赖
+- **WHEN** 注册 Callback 时
+- **THEN** 需要传入 AccountStore 实例用于获取下级 ID
+
--- a/openspec/specs/dependency-injection/spec.md
+++ b/openspec/specs/dependency-injection/spec.md
@@ -0,0 +1,56 @@
+# dependency-injection Specification
+
+## Purpose
+TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.
+## Requirements
+### Requirement: Bootstrap Package
+
+系统 SHALL 提供 bootstrap 包，统一管理所有业务组件的初始化和依赖注入。
+
+#### Scenario: 初始化所有组件
+- **WHEN** 调用 Bootstrap(deps)
+- **THEN** 自动初始化所有 Store、Service 和 Handler
+- **AND** 返回可直接用于路由注册的 Handlers 结构体
+
+#### Scenario: 依赖注入
+- **WHEN** 初始化 Service 时
+- **THEN** 自动注入所需的 Store 依赖
+- **AND** 自动注入所需的其他 Service 依赖
+
+#### Scenario: 添加新业务模块
+- **WHEN** 需要添加新的业务模块
+- **THEN** 只需修改 bootstrap 包
+- **AND** main.go 无需任何修改
+- **AND** TODO 注释标记扩展点
+
+### Requirement: Main Function Simplification
+
+main 函数 SHALL 只负责编排，不包含具体业务组件初始化逻辑。
+
+#### Scenario: 标准启动流程
+- **WHEN** 应用启动
+- **THEN** main 函数执行以下步骤：
+  1. 加载配置
+  2. 初始化基础依赖（DB、Redis、Logger）
+  3. 调用 bootstrap.Bootstrap() 初始化业务组件
+  4. 设置路由和中间件
+  5. 启动服务器
+
+#### Scenario: 启动失败处理
+- **WHEN** 任何初始化步骤失败
+- **THEN** 记录错误日志
+- **AND** 程序以非零状态码退出
+
+### Requirement: Dependencies Encapsulation
+
+系统 SHALL 使用结构体封装基础依赖和业务组件。
+
+#### Scenario: Dependencies 结构体
+- **WHEN** 传递基础依赖时
+- **THEN** 使用 Dependencies 结构体封装 DB、Redis、Logger
+
+#### Scenario: Handlers 结构体
+- **WHEN** 返回业务处理器时
+- **THEN** 使用 Handlers 结构体封装所有 Handler
+- **AND** 结构体包含 TODO 注释标记未来扩展点
+
--- a/openspec/specs/error-handling/spec.md
+++ b/openspec/specs/error-handling/spec.md
@@ -0,0 +1,80 @@
+# error-handling Specification
+
+## Purpose
+TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.
+## Requirements
+### Requirement: Simplified AppError Structure
+
+系统 SHALL 简化 AppError 结构，删除冗余的 HTTPStatus 字段。
+
+#### Scenario: AppError 字段
+- **WHEN** 创建 AppError
+- **THEN** 结构体只包含 3 个字段：
+  - Code: 业务错误码
+  - Message: 错误消息
+  - Err: 底层错误（可选）
+
+#### Scenario: HTTP 状态码获取
+- **WHEN** ErrorHandler 处理 AppError
+- **THEN** 通过 GetHTTPStatus(code) 实时获取 HTTP 状态码
+- **AND** 不从 AppError 字段中读取
+
+#### Scenario: 禁止手动设置状态码
+- **WHEN** 创建 AppError
+- **THEN** 不提供 WithHTTPStatus() 方法
+- **AND** Code 和 HTTPStatus 始终保持一致
+
+### Requirement: Unified Error Response Format
+
+系统 SHALL 使用统一的 JSON 响应格式（错误和成功均使用相同字段）。
+
+#### Scenario: 响应结构
+- **WHEN** 返回任何响应时
+- **THEN** JSON 结构仅包含 4 个字段：
+  - code: 业务错误码（0 表示成功）
+  - msg: 消息（错误消息或 "success"）
+  - data: 响应数据（成功时有数据，错误时为 null）
+  - timestamp: ISO 8601 时间戳
+
+#### Scenario: 不返回 HTTP 状态码字段
+- **WHEN** 返回响应时
+- **THEN** JSON 不包含 httpstatus 或 http_status 字段
+- **AND** HTTP 状态码仅在响应头中体现
+
+#### Scenario: Handler 返回错误
+- **WHEN** Handler 函数返回 error
+- **THEN** 全局 ErrorHandler 拦截错误
+- **AND** 根据错误类型构造统一格式响应
+
+### Requirement: Handler Error Return Convention
+
+所有 Handler 函数 SHALL 通过返回 error 传递错误，由全局 ErrorHandler 统一处理。
+
+#### Scenario: 业务错误
+- **WHEN** Handler 遇到业务错误
+- **THEN** 返回 errors.New(code, message) 创建的 AppError
+- **AND** 不直接调用 response.Error()
+
+#### Scenario: 参数验证错误
+- **WHEN** 请求参数验证失败
+- **THEN** 返回 errors.New(CodeInvalidParam, "具体错误描述")
+
+#### Scenario: 成功响应
+- **WHEN** Handler 执行成功
+- **THEN** 调用 response.Success(c, data)
+- **AND** 返回 nil
+
+### Requirement: Standardized Error Codes
+
+系统 SHALL 使用标准化的错误码，删除向后兼容的别名。
+
+#### Scenario: 参数验证错误码
+- **WHEN** 参数验证失败
+- **THEN** 使用 CodeInvalidParam
+- **AND** 不使用 CodeBadRequest（别名已删除）
+
+#### Scenario: 服务不可用错误码
+- **WHEN** 服务不可用
+- **THEN** 使用 CodeServiceUnavailable
+- **AND** 不使用 CodeAuthServiceUnavailable（别名已删除）
+
--- a/openspec/specs/openapi-generation/spec.md
+++ b/openspec/specs/openapi-generation/spec.md
@@ -0,0 +1,83 @@
+# openapi-generation Specification
+
+## Purpose
+TBD - created by archiving change auto-generate-openapi-docs. Update Purpose after archive.
+## Requirements
+### Requirement: 服务启动时自动生成OpenAPI文档
+
+系统启动时SHALL自动生成OpenAPI 3.0规范文档并保存到项目根目录。
+
+#### Scenario: 服务正常启动时生成文档
+
+- **WHEN** 服务启动流程执行到路由注册之后
+- **THEN** 系统自动调用文档生成逻辑
+- **AND** 在项目根目录生成 `openapi.yaml` 文件
+- **AND** 文件内容包含所有已注册的API端点定义
+
+#### Scenario: 文档生成失败时的优雅处理
+
+- **WHEN** 文档生成过程中发生错误（如文件写入失败、权限问题）
+- **THEN** 系统记录错误日志到应用日志
+- **AND** 错误日志包含完整的错误信息和堆栈
+- **AND** 服务启动流程继续执行，不因文档生成失败而中断
+
+#### Scenario: 文档生成的时机控制
+
+- **WHEN** 服务在任何环境下启动（开发、测试、生产）
+- **THEN** 文档生成逻辑都会执行
+- **AND** 无需额外的配置或启动参数
+
+### Requirement: 文档输出路径规范
+
+系统SHALL将生成的OpenAPI文档输出到固定的、可预测的位置。
+
+#### Scenario: 文档保存到项目根目录
+
+- **WHEN** 文档生成成功
+- **THEN** 文件保存到项目根目录（相对于工作目录的 `./openapi.yaml`）
+- **AND** 如果文件已存在则覆盖旧版本
+- **AND** 文件权限设置为 0644（所有者可读写，其他用户只读）
+
+#### Scenario: 确保输出目录存在
+
+- **WHEN** 输出路径的父目录不存在
+- **THEN** 系统自动创建必要的目录结构
+- **AND** 目录权限设置为 0755
+
+### Requirement: 复用现有生成逻辑
+
+文档生成功能SHALL复用项目中已有的OpenAPI生成机制，避免代码重复。
+
+#### Scenario: 调用现有的Registry机制
+
+- **WHEN** 执行文档生成
+- **THEN** 使用 `pkg/openapi.Generator` 创建文档生成器
+- **AND** 调用 `internal/routes` 中的路由注册函数
+- **AND** 传入非nil的Generator实例以激活文档收集逻辑
+- **AND** 使用Generator的Save方法输出YAML文件
+
+#### Scenario: 模拟路由注册但不启动服务
+
+- **WHEN** 生成文档时调用路由注册函数
+- **THEN** 创建临时的Fiber应用实例用于路由注册
+- **AND** 传入nil的依赖项（因为不会执行实际的Handler逻辑）
+- **AND** 注册完成后丢弃Fiber应用实例（不调用Listen）
+
+### Requirement: 向后兼容独立生成工具
+
+系统SHALL保留独立的文档生成工具，支持离线生成文档的用例。
+
+#### Scenario: 通过make命令生成文档
+
+- **WHEN** 用户执行 `make docs` 命令
+- **THEN** 调用 `cmd/gendocs/main.go`
+- **AND** 生成文档到指定位置（默认 `./docs/admin-openapi.yaml`）
+- **AND** 生成过程独立于服务运行状态
+
+#### Scenario: 独立工具与自动生成共享代码
+
+- **WHEN** 独立工具和自动生成都需要执行文档生成
+- **THEN** 两者调用相同的底层生成函数
+- **AND** 通过参数区分输出路径
+- **AND** 避免逻辑重复
+