# 规范：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生成逻辑
- 应返回与之前相同的响应格式和内容