# 规范：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