实现服务启动时自动生成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>

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（别名已删除）
+