ERPTurbo_Poster/openspec/project.md

# 项目上下文

## 项目目的
ERPTurbo_Poster 是一个基于 Web 的服务，可以从网页内容生成海报和 PDF。该服务使用 Puppeteer 渲染网页并将其转换为图像（海报）或 PDF。它设计用于处理 HTML 内容转换并支持适当的字体嵌入，还支持多种存储后端，包括本地存储、腾讯云 COS 和阿里云 OSS。该服务特别适用于需要将网页内容转换为视觉呈现形式的场景，如营销海报生成、报告PDF生成、电子书制作、网页存档等。

**核心价值**：
- 将动态网页内容转换为静态视觉格式
- 支持批量文档生成和处理
- 提供RESTful API接口，易于集成
- 多云存储支持，灵活的部署选项

## 技术栈
- **运行时环境**: Node.js (v20+)
- **Web 框架**: Express.js (v5.0.0)
- **浏览器自动化**: Puppeteer v24.29.1（用于网页渲染和截图）
- **云存储 SDK**:
  - ali-oss v6.17.1 (阿里云对象存储)
  - cos-nodejs-sdk-v5 v2.8.3 (腾讯云对象存储)
- **开发工具**:
  - dotenv v8.2.0 (环境变量管理)
  - body-parser v2.2.0 (请求体解析，支持10MB限制)
  - node-fetch v3.3.2 (HTTP 请求)
  - swagger-jsdoc v6.2.8 & swagger-ui-express v5.0.1 (API 文档)
  - dompurify v3.3.0 (HTML清理，防止XSS攻击)
  - jsdom v27.2.0 (DOM操作，用于HTML处理和清理)
- **模块系统**: ES6+ JavaScript 模块 (ESM)，使用 .mjs 和 .js 扩展名

## 项目约定

### 代码风格
- **模块系统**: ES6+ JavaScript 模块（文件扩展名为 .mjs 和 .js）
- **变量声明**: 尽可能使用 const 进行变量声明，需要可变时使用 let
- **函数定义**: 使用函数声明定义路由处理程序和工具函数
- **异步操作**: 统一使用 async/await 模式
- **错误处理**: 在 Puppeteer 操作周围使用 try/catch 块进行错误处理，并在 finally 块中进行资源清理
- **命名约定**:
  - 类名使用 PascalCase（例如，BrowserManager、StorageManager）
  - 函数和变量名使用 camelCase
- **文档**: 为函数使用 JSDoc 风格的注释，包含参数文档
- **代码安全**: 添加安全头部（X-Content-Type-Options、X-Frame-Options、X-XSS-Protection）和内容类型验证
- **代码结构**: 每个模块导出具体的函数或类，通过 import/export 进行模块化管理

### 架构模式
- **模块化架构，关注点分离**：
  - `server.mjs`：主要应用程序入口点和 Express 服务器设置，整合各模块
  - `lib/`：包含可重用模块
    - `browser.js`：Puppeteer 浏览器管理，包含页面池和浏览器生命周期管理
    - `storage.js`：多提供商存储抽象（本地/COS/OSS），提供统一的存储接口
    - `routes.js`：海报/PDF 生成的 API 路由处理程序，包含业务逻辑
    - `constants.js`：应用程序常量和配置，如字体样式定义
    - `params.js`：请求参数处理和验证，生成截图参数
    - `utils.js`：用于字符串操作和 HTML 转换的工具函数
    - `auth.js`：API认证中间件，支持多种认证方式（Bearer Token、API Key Header、Query Parameter）
    - `response.js`：标准化API响应格式，包含错误处理和成功响应结构
    - `swagger.js`：Swagger API文档配置和注释定义
- **单例模式**: BrowserManager 和 StorageManager 实例使用单例模式
- **资源管理**: 请求范围的资源管理（在处理程序中获取页面，在 finally 块中返回到池）
- **API 文档**: 使用 Swagger 注解进行 API 文档生成，定义了 POST /api/v1/poster 和 POST /api/v1/pdf 等接口
- **安全设计**:
  - API密钥认证机制，支持Bearer Token和X-API-Key Header两种方式
  - DOMPurify集成用于HTML内容清理，防止XSS攻击
  - 请求大小限制（10MB）和内容类型验证
  - 安全HTTP头部配置（CSP、XSS保护等）
- **响应标准化**: 统一的API响应格式，包含success、data、message、code字段

### 测试策略
- **单元测试**: [当前未实现 - 建议添加 Jest 或 Mocha 测试框架]
- **集成测试**: [当前未实现 - 建议添加 Supertest 进行 API 接口测试]
- **端到端测试**: [当前未实现 - 建议添加 Puppeteer 集成测试]
- **安全测试**: [当前未实现 - 建议添加 OWASP ZAP 或类似工具进行安全扫描]
- **性能测试**: [当前未实现 - 建议添加 Artillery 或 K6 进行负载测试]
- **手动测试**: 在开发环境进行功能验证，通过 Swagger UI 进行接口测试

### Git 工作流
- **分支策略**: 使用功能分支模型，主分支为 main，开发在 feature 分支进行
- **提交信息**: 使用约定式提交格式 (e.g., feat: add pdf generation, fix: resolve memory leak)
- **代码审查**: 通过 Pull Request 进行代码审查和合并
- **版本管理**: 使用语义化版本控制 (Semantic Versioning)
- **发布流程**: 通过 Git 标签管理版本发布，支持自动化部署

## 领域上下文
- **核心功能**:
  - 从网页 URL 或直接 HTML 内容生成海报图像和 PDF 文档
  - 支持自定义参数：宽度、高度、设备缩放、图片质量、编码格式等
  - 支持 JSON 格式输入转 HTML（通过 jsonToHtml 工具函数）
  - 提供健康检查接口 /status 和 API 文档接口 /api-docs
  - 多格式输出：PNG、JPEG图片格式，A4标准PDF格式
  - 批量处理能力：支持通过API调用进行批量文档生成
- **内容转换类型**:
  - 网页截图（海报），可自定义视口尺寸和设备缩放
  - 从网页或直接 HTML 内容生成 PDF（A4 格式）
- **字体渲染**: 包含通过嵌入的 font-face 声明对中文字体的特殊处理，确保中文字符的正确显示，支持PingFang字体家族
- **资源管理**: 浏览器页面使用池化管理以高效处理并发请求，避免浏览器实例过多导致的资源消耗，支持动态调整池大小
- **存储策略**: 支持多提供商存储抽象，允许在本地、腾讯云 COS 或阿里云 OSS 存储之间切换，通过环境变量灵活配置
- **API安全**: 完整的API密钥认证体系，支持多种密钥配置和临时禁用认证的开发模式

## 重要约束
- **Puppeteer 环境**: 在部署环境中需要安装 Chrome/Chromium 浏览器，或使用系统已安装的 Chrome
- **并发限制**: 并发性受池中可用浏览器页面数量的限制，可以通过调整 browser.js 中的 initBrowser 参数来改变页面数
- **存储配置**: 存储配置必须通过环境变量正确设置，否则可能导致上传失败
- **内存管理**: 需要定期清理浏览器实例以防止内存泄漏，browser.js 包含了自动清理机制
- **大文件处理**: 大文件上传可能需要调整 Express body parser 限制（当前设置为 10MB）
- **中文字体支持**: 中文字体渲染需要特定的 font-face 样式注入，以确保在不同环境中正确显示
- **安全性**: 为防止请求伪造和 XSS 攻击，添加了安全头、内容类型验证和DOMPurify HTML清理
- **API认证**: 生产环境必须配置API密钥，开发环境可通过DISABLE_API_AUTH=true临时禁用认证
- **字体依赖**: 依赖外部字体CDN（阿里云图标字体），需要确保网络连接正常
- **端口配置**: 默认端口3000，可通过PORT环境变量自定义

## 外部依赖
- **云服务**:
  - 腾讯云对象存储（COS）- 通过 cos-nodejs-sdk-v5 访问
  - 阿里云对象存储服务（OSS）- 通过 ali-oss 访问
- **浏览器引擎**: Chrome/Chromium 浏览器用于 Puppeteer 渲染
- **字体服务**: 阿里云图标字体CDN（at.alicdn.com）用于中文字体支持
- **包管理**: NPM registry 用于包管理，使用pnpm作为包管理器
- **配置管理**: 环境变量用于服务配置（端口、存储凭据、API密钥等）
- **文档生成**: Swagger UI 用于 API 文档展示，访问路径 /api-docs
- **Docker**: 支持通过 Docker 进行容器化部署
- **运行时依赖**: Node.js v20+ 运行环境

## API 接口概览

### 核心端点
- **GET /status**: 健康检查接口，返回服务运行状态
- **GET /api-docs**: Swagger API 文档界面
- **POST /api/v1/poster**: 生成海报图片接口
- **POST /api/v1/pdf**: 生成PDF文档接口

### 认证方式
- **Bearer Token**: `Authorization: Bearer <api-key>`
- **API Key Header**: `X-API-Key: <api-key>`
- **Query Parameter**: `?api_key=<api-key>`

### 响应格式
```json
{
  "success": boolean,
  "data": object|null,
  "message": string,
  "code": number
}
```

## 部署架构

### 推荐部署环境
- **开发环境**: 本地Node.js运行，使用本地存储
- **测试环境**: Docker容器化部署，模拟生产配置
- **生产环境**: 云服务器部署，使用COS/OSS云存储

### 容器化支持
- 支持Docker多阶段构建
- 包含Chrome/Chromium浏览器镜像
- 环境变量配置外部化
- 健康检查和优雅关闭

### 监控和日志
- 应用级日志输出到stdout
- 支持结构化日志格式
- 错误追踪和性能监控
- 资源使用情况监控

## 性能指标

### 关键性能指标
- **响应时间**: 海报生成通常3-10秒，PDF生成5-15秒
- **并发处理**: 受浏览器页面池大小限制（默认2个页面）
- **内存使用**: 每个Chrome实例约100-200MB内存
- **存储吞吐**: 依赖云存储服务商的网络性能

### 优化建议
- 根据服务器规格调整浏览器页面池大小
- 使用CDN加速字体和静态资源加载
- 定期清理临时文件和浏览器缓存
- 监控内存使用并设置合理的重启策略

## 安全考虑

### 已实现的安全措施
- API密钥认证机制
- DOMPurify HTML内容清理
- 请求大小限制（10MB）
- 安全HTTP头部配置
- 输入参数验证和清理

### 安全最佳实践
- 定期轮换API密钥
- 使用HTTPS传输
- 限制API调用频率
- 监控异常请求模式
- 定期更新依赖包版本