# 设计文档：标准化ERPTurbo_Poster API响应格式

## 架构决策

### 1. 响应格式选择

#### 选项1：REST风格响应
- 成功响应：{data: {...}}
- 错误响应：{error: {message, code, details}}

#### 选项2：状态明确响应
- 成功响应：{success: true, data: {...}, message: "...", code: 200}
- 错误响应：{success: false, data: null, message: "...", code: 400}

#### 选项3：简化状态响应
- 成功响应：{success: true, data: {...}}
- 错误响应：{success: false, message: "..."}

**决策**：采用选项2（状态明确响应），因为：
- 明确的状态标志便于客户端处理
- 包含详细信息便于调试
- 代码字段便于错误分类和处理
- 与HTTP状态码保持一致

### 2. 工具函数实现策略

#### 选项1：全局工具函数
- 实现在 utils.js 中，作为全局工具函数
- 优点：全局可用，易于重用
- 缺点：可能与其他工具混杂

#### 选项2：专用响应模块
- 创建专门的 response.js 模块
- 优点：职责明确，专门用于处理响应
- 缺点：需要额外的导入

#### 选项3：Express中间件
- 创建响应格式中间件
- 优点：自动应用到所有响应
- 缺点：可能不够灵活

**决策**：采用选项2（专用响应模块），因为：
- 专门用于响应格式处理
- 清晰的职责分离
- 灵活的使用方式

### 3. 错误代码设计

#### 通用错误代码
- 1000-1999: 通用错误
- 2000-2999: 认证相关错误
- 3000-3999: 参数验证错误
- 4000-4999: 服务处理错误
- 5000-5999: 存储相关错误

#### 特定错误代码
- 3001: 缺少必需参数
- 3002: 参数格式错误
- 4001: 海报生成失败
- 4002: PDF生成失败
- 5001: 文件上传失败

### 4. HTTP状态码与响应格式的一致性

#### 状态码映射
- 200: 成功操作
- 400: 客户端错误（参数验证失败等）
- 401: 认证失败
- 403: 授权失败
- 404: 资源未找到
- 500: 服务器错误

### 5. 与现有API的兼容性

#### 向后兼容考虑
- 分析现有客户端使用情况
- 考虑提供版本控制（如需要）
- 评估直接修改的影响

**决策**：采用直接修改方式，因为：
- 这是一个重要的规范改进
- 可以通过发布说明告知客户端开发者
- 统一的响应格式对长期维护更有利

### 6. 存储模块响应统一

#### 当前实现
- 本地存储：返回 {name, path}
- COS存储：返回 {name, path, data}
- OSS存储：返回 {name, path, data}

**决策**：统一所有存储模块返回格式为 {name, path}，data字段可作为扩展使用但不是必需。

### 7. 国际化考虑

#### 问题
- 当前错误消息是中文
- 需要考虑国际化支持

**决策**：当前阶段使用英文错误消息，保留国际化扩展能力：
- 在响应结构中添加 language 字段（可选）
- 错误消息使用英文为主
- 将来可通过 Accept-Language 头或请求参数确定语言

## 实现安全考虑

### 1. 错误信息泄露
- 确保错误响应中不包含敏感系统信息
- 对于500错误，使用通用错误消息

### 2. 响应大小控制
- 避免在响应中包含过大的数据
- 对于失败请求，限制错误详情的大小