dc940d2598
- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像 - 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档 - 添加Swagger API文档注释，完善接口描述和参数说明 - 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF - 添加输入验证和标准化响应格式 - 引入DOMPurify库对HTML内容进行安全过滤 - 更新环境变量配置，支持API密钥认证和CORS设置 - 优化上传逻辑，统一返回标准响应结构 - 添加构建脚本支持Docker镜像打包和推送
3.5 KiB
3.5 KiB
规范：API 认证功能
ADDED Requirements
Requirement: API密钥验证中间件
- 描述：MUST 系统必须包含一个中间件函数，用于验证传入 API 请求的认证凭据
- 验证方法：中间件应能从请求头或查询参数中提取认证凭据
- 依赖项：无
Scenario: 提取Bearer令牌
- 当客户端在Authorization头中发送Bearer令牌时
- 系统应能正确提取令牌值
- 例如：Authorization: Bearer abc123def456
Scenario: 提取自定义API密钥头
- 当客户端在X-API-Key头中发送API密钥时
- 系统应能正确提取密钥值
- 例如：X-API-Key: abc123def456
Requirement: API密钥验证
- 描述：MUST 系统必须验证提供的API密钥是否在允许的密钥列表中
- 验证方法：通过与环境变量中配置的允许密钥进行比较
- 依赖项：Environment Configuration
Scenario: 有效API密钥验证
- 当请求包含有效的API密钥时
- 系统应允许请求继续处理
- 应返回200状态码或继续执行业务逻辑
Scenario: 无效API密钥验证
- 当请求包含无效的API密钥时
- 系统应拒绝请求
- 应返回401未授权状态码
Scenario: 缺失API密钥验证
- 当请求未包含API密钥时
- 系统应拒绝请求
- 应返回401未授权状态码
Requirement: 环境变量配置
- 描述：SHALL 系统应通过环境变量配置允许的API密钥
- 验证方法：从ALLOWED_API_KEYS环境变量读取密钥列表
- 依赖项：无
Scenario: 配置单个API密钥
- 当环境变量ALLOWED_API_KEYS设置为单个密钥时
- 系统应仅接受该密钥的请求
Scenario: 配置多个API密钥
- 当环境变量ALLOWED_API_KEYS设置为多个用逗号分隔的密钥时
- 系统应接受任一密钥的请求
Requirement: 选择性应用认证
- 描述：SHALL 系统应仅对需要保护的API端点应用认证
- 验证方法：认证中间件应仅应用到特定路由
- 依赖项：API密钥验证中间件
Scenario: 保护海报生成端点
- 当请求POST /api/v1/poster端点时
- 系统应验证API密钥
Scenario: 保护PDF生成端点
- 当请求POST /api/v1/pdf端点时
- 系统应验证API密钥
Scenario: 不保护健康检查端点
- 当请求GET /status端点时
- 系统不应要求API密钥验证
Requirement: 错误响应处理
- 描述：SHALL 系统应返回适当的标准错误响应，而不泄露敏感信息
- 验证方法：错误响应不应揭示认证失败的具体原因
- 依赖项：API密钥验证
Scenario: 无效凭证响应
- 当提供无效API密钥时
- 系统应返回标准的401未授权响应
- 响应体应包含通用错误消息，不透露认证失败的详细原因
Scenario: 缺失凭证响应
- 当请求缺少API密钥时
- 系统应返回标准的401未授权响应
- 响应体应包含通用错误消息，不透露认证失败的详细原因
MODIFIED Requirements
Requirement: API端点定义
- 描述：MUST 现有的POST /api/v1/poster和POST /api/v1/pdf端点需要修改以包含认证要求
- 验证方法：端点应验证API密钥后才处理业务逻辑
- 关联：API密钥验证
Scenario: 成功认证的海报生成
- 当请求POST /api/v1/poster包含有效API密钥时
- 端点应继续执行海报生成逻辑
- 应返回与之前相同的响应格式和内容
Scenario: 成功认证的PDF生成
- 当请求POST /api/v1/pdf包含有效API密钥时
- 端点应继续执行PDF生成逻辑
- 应返回与之前相同的响应格式和内容