实现服务启动时自动生成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/changes/archive/2026-01-09-refactor-framework-cleanup/specs/auth/spec.md
+++ b/openspec/changes/archive/2026-01-09-refactor-framework-cleanup/specs/auth/spec.md
@@ -0,0 +1,61 @@
+## ADDED 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/changes/archive/2026-01-09-refactor-framework-cleanup/specs/data-permission/spec.md
+++ b/openspec/changes/archive/2026-01-09-refactor-framework-cleanup/specs/data-permission/spec.md
@@ -0,0 +1,61 @@
+## ADDED 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/changes/archive/2026-01-09-refactor-framework-cleanup/specs/dependency-injection/spec.md
+++ b/openspec/changes/archive/2026-01-09-refactor-framework-cleanup/specs/dependency-injection/spec.md
@@ -0,0 +1,52 @@
+## ADDED 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/changes/archive/2026-01-09-refactor-framework-cleanup/specs/error-handling/spec.md
+++ b/openspec/changes/archive/2026-01-09-refactor-framework-cleanup/specs/error-handling/spec.md
@@ -0,0 +1,92 @@
+## ADDED 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（别名已删除）
+
+## REMOVED Requirements
+
+### Requirement: Manual Error Response Construction
+
+~~Handler 可以手动调用 response.Error() 构造错误响应。~~
+
+**Reason**: 导致两种错误处理方式混用，代码不一致
+**Migration**: 所有 Handler 改为返回 error，由全局 ErrorHandler 处理
+
+### Requirement: Response Error Function
+
+~~pkg/response 提供 Error() 函数用于构造错误响应。~~
+
+**Reason**: 与全局 ErrorHandler 功能重复，增加复杂度
+**Migration**: 删除 Error() 函数，Handler 统一返回 error