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>

响应格式

{
  "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调用频率
• 监控异常请求模式
• 定期更新依赖包版本