feat: 完善API文档系统和Swagger集成

- 集成Swagger文档生成和UI界面
- 为所有API端点添加详细的文档注解
- 添加统一的响应装饰器和DTO类型定义
- 优化API路由结构和全局验证配置
- 新增文档生成和服务脚本命令

docs/API_DOCUMENTATION_SETUP.md

@@ -0,0 +1,198 @@
+# API 文档配置指南
+
+## 概览
+
+本项目使用 Swagger/OpenAPI 3.0 规范生成完整的 API 文档，支持在线测试和接口调试。
+
+## 访问文档
+
+启动项目后，可通过以下地址访问API文档：
+
+- **交互式文档**: http://localhost:3000/api/docs
+- **JSON格式**: http://localhost:3000/api/docs-json
+- **YAML格式**: http://localhost:3000/api/docs-yaml
+
+## 文档配置
+
+### 1. 主配置文件
+
+文件位置: `src/config/swagger.config.ts`
+
+包含以下配置：
+- API基础信息（标题、描述、版本）
+- JWT认证配置
+- 标签分类
+- 多环境服务器配置
+- UI自定义选项
+
+### 2. DTO文档化
+
+#### 通用响应格式
+- `src/dto/common-response.dto.ts` - 统一响应格式
+- `src/dto/error-response.dto.ts` - 错误响应格式
+
+#### 模板系统DTO
+- `src/dto/template.dto.ts` - 模板相关数据传输对象
+  - `CreateTemplateDto` - 创建模板
+  - `UpdateTemplateDto` - 更新模板
+  - `TemplateExecuteDto` - 执行模板
+  - `TemplateListDto` - 模板列表
+  - `BatchExecuteDto` - 批量执行
+
+#### 平台用户DTO
+- `src/platform/dto/platform-login.dto.ts` - 平台登录相关
+
+### 3. Controller文档化
+
+#### 装饰器使用
+```typescript
+@ApiTags('功能模块') // 分组标签
+@ApiOperation({ summary: '接口摘要', description: '详细描述' })
+@ApiResponse({ status: 200, description: '成功', type: ResponseDto })
+@ApiParam({ name: 'id', description: '参数描述' })
+@ApiQuery({ name: 'filter', required: false })
+@ApiBody({ type: RequestDto })
+@ApiBearerAuth('JWT-auth') // JWT认证
+```
+
+#### 通用装饰器
+- `src/decorators/api-common-responses.decorator.ts`
+  - `@ApiCommonResponses()` - 通用错误响应
+  - `@ApiAuthResponses()` - 认证相关错误
+
+## 支持的功能模块
+
+### 1. 用户管理 (`用户管理`)
+- 多平台统一登录
+- 用户信息获取与更新
+- 平台账号绑定/解绑
+- 支持的平台列表查询
+
+### 2. AI模板系统 (`AI模板系统`)
+- 模板列表查询（支持类型筛选）
+- 模板详情获取
+- 模板执行（单个/批量）
+- 模板推荐
+- 模板管理（创建/更新/删除）
+
+### 3. 平台适配 (`平台适配`)
+- 各平台特定接口
+- 数据同步功能
+
+### 4. 积分系统 (`积分系统`)
+- 积分获取、消耗、查询管理
+
+### 5. 扩展服务 (`扩展服务`)
+- 预留的扩展功能接口
+
+## API 规范
+
+### 统一响应格式
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {},
+  "timestamp": 1703001000000,
+  "traceId": "trace-uuid"
+}
+```
+
+### 错误码规范
+
+- **1000-1999**: 系统级错误
+- **2000-2999**: 业务级错误  
+- **3000-3999**: 平台特定错误
+- **4000-4999**: 客户端错误
+- **5000-5999**: 服务端错误
+
+### 认证方式
+
+使用 JWT Bearer Token 进行接口认证：
+
+```bash
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+## 开发指南
+
+### 1. 添加新接口文档
+
+1. **创建DTO类**：
+```typescript
+export class NewFeatureDto {
+  @ApiProperty({ description: '字段描述', example: '示例值' })
+  @IsString()
+  field: string;
+}
+```
+
+2. **Controller添加装饰器**：
+```typescript
+@ApiTags('功能模块')
+@ApiCommonResponses()
+export class NewController {
+  @Post()
+  @ApiOperation({ summary: '接口摘要', description: '详细描述' })
+  @ApiBody({ type: NewFeatureDto })
+  @ApiResponse({ status: 200, description: '成功' })
+  async newEndpoint() {}
+}
+```
+
+### 2. 生成静态文档
+
+```bash
+# 生成 Swagger JSON 文档
+npm run docs:generate
+
+# 启动文档服务
+npm run docs:serve
+```
+
+### 3. 文档验证
+
+启动项目后访问 http://localhost:3000/api/docs 验证：
+- 接口分组是否正确
+- 参数描述是否完整
+- 响应格式是否标准
+- 认证配置是否生效
+
+## 部署注意事项
+
+### 生产环境配置
+
+生产环境默认禁用 Swagger 文档，确保安全性：
+
+```typescript
+// 仅在非生产环境启用 Swagger
+if (process.env.NODE_ENV !== 'production') {
+  setupSwagger(app);
+}
+```
+
+### 自定义域名配置
+
+需要在 `swagger.config.ts` 中更新服务器配置：
+
+```typescript
+.addServer('https://your-domain.com', '生产环境')
+```
+
+## 维护指南
+
+### 1. 定期更新
+- 新增接口后及时添加文档
+- 保持DTO和实际接口同步
+- 更新示例数据和错误信息
+
+### 2. 版本管理
+- API版本变更时更新文档版本号
+- 重要变更添加changelog说明
+- 保持向后兼容性文档说明
+
+### 3. 团队协作
+- 代码审查包含文档完整性检查
+- 新团队成员参考文档快速上手
+- 前端开发基于文档进行接口对接