qilincloud168/ERPTurbo_Poster
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
ERPTurbo_Poster/openspec/changes/archive/2025-11-20-standardize-api-responses/specs/response-format/spec.md
shenyifei dc940d2598 feat(api): 添加海报和PDF生成功能 
- 新增海报生成接口，支持从网页URL或HTML内容生成海报图像
- 新增PDF生成接口，支持从网页URL或HTML内容生成PDF文档
- 添加Swagger API文档注释，完善接口描述和参数说明
- 实现HTML内容参数支持，允许直接传入HTML结构生成海报/PDF
- 添加输入验证和标准化响应格式
- 引入DOMPurify库对HTML内容进行安全过滤
- 更新环境变量配置，支持API密钥认证和CORS设置
- 优化上传逻辑，统一返回标准响应结构
- 添加构建脚本支持Docker镜像打包和推送
2025-11-20 17:51:35 +08:00

5.1 KiB
Raw Permalink Blame History

规范：API响应格式标准化

ADDED Requirements

Requirement: Standard Response Format

  • The system SHALL use a consistent response format for all API endpoints
  • The response format SHALL include success flag, data, message, and code fields
  • The response structure SHALL be: {success: boolean, data: object|null, message: string, code: number}

Scenario: Successful API response

  • WHEN an API request is processed successfully
  • THEN the response SHALL include success: true
  • AND data field SHALL contain the actual response data or null if not applicable
  • AND message field SHALL contain a descriptive message about the operation
  • AND code field SHALL match the HTTP status code

Scenario: Failed API response

  • WHEN an API request fails
  • THEN the response SHALL include success: false
  • AND data field SHALL be null
  • AND message field SHALL contain a descriptive error message
  • AND code field SHALL contain an application-specific error code

Requirement: Response Utility Functions

  • The system SHALL provide utility functions for creating standardized responses
  • SHALL include a successResponse(data, message?, code?) function
  • SHALL include an errorResponse(message, code?, details?) function

Scenario: Creating successful response

  • WHEN successResponse is called with data
  • THEN it SHALL return {success: true, data: provided_data, message: provided_message, code: provided_code}
  • AND if message is not provided, it SHALL default to "Operation successful"
  • AND if code is not provided, it SHALL default to 200

Scenario: Creating error response

  • WHEN errorResponse is called with a message
  • THEN it SHALL return {success: false, data: null, message: provided_message, code: provided_code}
  • AND if code is not provided, it SHALL default to 400
  • AND if details are provided, they SHALL be included in the response

Requirement: Updated Poster Generation Response

  • The POST /api/v1/poster endpoint SHALL return standardized responses
  • SUCCESS response SHALL have: {success: true, data: {name, path}, message: "Poster generated successfully", code: 200}

Scenario: Successful poster generation

  • WHEN a poster is generated successfully
  • THEN the response SHALL follow the standard format with success: true
  • AND data SHALL contain the generated poster information (name, path)

Scenario: Failed poster generation

  • WHEN poster generation fails
  • THEN the response SHALL follow the standard format with success: false
  • AND appropriate error message and code SHALL be included

Requirement: Updated PDF Generation Response

  • The POST /api/v1/pdf endpoint SHALL return standardized responses
  • SUCCESS response SHALL have: {success: true, data: {name, path}, message: "PDF generated successfully", code: 200}

Scenario: Successful PDF generation

  • WHEN a PDF is generated successfully
  • THEN the response SHALL follow the standard format with success: true
  • AND data SHALL contain the generated PDF information (name, path)

Scenario: Failed PDF generation

  • WHEN PDF generation fails
  • THEN the response SHALL follow the standard format with success: false
  • AND appropriate error message and code SHALL be included

Requirement: Updated Health Check Response

  • The GET /status SHALL endpoint response MAY be updated to use the standard format
  • If updated, SUCCESS response SHALL have: {success: true, data: {}, message: "Service is running", code: 200}

Scenario: Health check successful

  • WHEN the health check endpoint is called
  • THEN it SHALL return either the original empty object or the standard format

Requirement: Consistent Error Handling

  • All error responses across the API SHALL follow the standardized format
  • System errors SHALL return generic messages to prevent information leakage
  • Validation errors SHALL return meaningful messages to aid developers

Scenario: Parameter validation error

  • WHEN invalid parameters are sent to an API endpoint
  • THEN the system SHALL return a standardized error response
  • AND the response SHALL have appropriate error code (e.g., 3001 for missing params, 3002 for format errors)

Scenario: Internal server error

  • WHEN an internal server error occurs
  • THEN the system SHALL return a standardized error response
  • AND the response SHALL have code 5000 and a generic message
  • AND system-specific error details SHALL NOT be exposed in the response

MODIFIED Requirements

Requirement: API Endpoint Responses

  • The existing POST /api/v1/poster, POST /api/v1/pdf, and GET /status endpoints MUST be modified to return standardized responses
  • The response format SHALL change from current inconsistent formats to the new standard format
  • Associated: Response Format Standardization

Scenario: Standardized poster generation

  • WHEN requesting POST /api/v1/poster with valid parameters
  • THEN the endpoint SHALL return standardized response format
  • AND the response SHALL include success flag, data, message, and code

Scenario: Standardized PDF generation

  • WHEN requesting POST /api/v1/pdf with valid parameters
  • THEN the endpoint SHALL return standardized response format
  • AND the response SHALL include success flag, data, message, and code