dc940d2598
- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像 - 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档 - 添加Swagger API文档注释，完善接口描述和参数说明 - 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF - 添加输入验证和标准化响应格式 - 引入DOMPurify库对HTML内容进行安全过滤 - 更新环境变量配置，支持API密钥认证和CORS设置 - 优化上传逻辑，统一返回标准响应结构 - 添加构建脚本支持Docker镜像打包和推送
3.1 KiB
3.1 KiB
设计文档：标准化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. 响应大小控制
- 避免在响应中包含过大的数据
- 对于失败请求，限制错误详情的大小