92 lines
5.3 KiB
Markdown
92 lines
5.3 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
本文档定义了优化爽文剧本创建接口（EpicScriptServiceImpl#createScript）的需求，通过调用Coze AI API来生成剧本内容。同时重构AiChatServiceImpl中的AI调用封装，使其成为通用的AI接口调用服务，支持根据配置信息调用不同的AI接口。
|
||
|
||
## Glossary
|
||
|
||
- **Coze_API**: 扣子AI平台提供的工作流流式调用接口
|
||
- **AiConfig**: AI配置实体，存储在t_ai_config表中，包含API地址、Token、工作流ID等配置信息
|
||
- **config_key**: AI配置的唯一标识键，用于获取特定场景的配置
|
||
- **workflow_id**: Coze工作流ID，用于指定调用哪个AI工作流
|
||
- **Stream_Response**: 流式响应，Coze API以SSE（Server-Sent Events）格式返回数据
|
||
- **EpicScript**: 爽文剧本实体，存储用户创建的剧本信息
|
||
- **input_parameter**: 传递给Coze工作流的输入参数，包含用户填写的信息
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: 通用AI接口调用服务
|
||
|
||
**User Story:** As a developer, I want to have a generic AI API calling service, so that I can easily call different AI configurations without duplicating code.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE AiChatService SHALL provide a generic method to call Coze workflow API by config_key
|
||
2. WHEN a config_key is provided, THE AiChatService SHALL retrieve the corresponding AiConfig from database
|
||
3. WHEN the AiConfig is retrieved, THE AiChatService SHALL construct the request using api_base_url, api_token, and workflow_id from the config
|
||
4. THE AiChatService SHALL support passing custom input parameters to the workflow
|
||
5. THE AiChatService SHALL handle stream response by default and extract the output content from the response
|
||
6. IF the AiConfig is not found or disabled, THEN THE AiChatService SHALL throw an appropriate exception with clear error message
|
||
|
||
### Requirement 2: Coze工作流请求构建
|
||
|
||
**User Story:** As a developer, I want the system to correctly build Coze workflow requests, so that the AI can process my input and return expected results.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN building a Coze workflow request, THE System SHALL include workflow_id from AiConfig
|
||
2. WHEN building a Coze workflow request, THE System SHALL include user_id parameter
|
||
3. WHEN building a Coze workflow request, THE System SHALL set stream to true for streaming response
|
||
4. WHEN building a Coze workflow request, THE System SHALL include the input parameter in the parameters object
|
||
5. THE System SHALL set Authorization header with Bearer token from AiConfig.api_token
|
||
6. THE System SHALL set Content-Type header to application/json
|
||
|
||
### Requirement 3: 流式响应解析
|
||
|
||
**User Story:** As a developer, I want the system to correctly parse Coze streaming responses, so that I can get the AI-generated content.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN receiving a stream response, THE System SHALL parse SSE format data (event: and data: lines)
|
||
2. WHEN the event is "Message" and node_type is "End", THE System SHALL extract the content field
|
||
3. WHEN the content contains JSON with output field, THE System SHALL extract the output value as the final result
|
||
4. WHEN the event is "Done", THE System SHALL complete the stream processing
|
||
5. IF parsing fails, THEN THE System SHALL log the error and return an appropriate error message
|
||
|
||
### Requirement 4: 爽文剧本AI生成
|
||
|
||
**User Story:** As a user, I want to create epic scripts using AI, so that I can get professionally generated story content based on my input.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN creating an epic script, THE EpicScriptService SHALL call Coze AI using config_key "coze.course.life.generate"
|
||
2. THE EpicScriptService SHALL assemble user input (title, theme, style, length, plotIntro, plotTurning, plotClimax, plotEnding) into a formatted input string
|
||
3. WHEN the AI returns the generated content, THE EpicScriptService SHALL parse and store the result in the EpicScript entity
|
||
4. THE EpicScriptService SHALL store the AI-generated content in appropriate fields (plotJson or dedicated content field)
|
||
5. IF the AI call fails, THEN THE EpicScriptService SHALL log the error and return null or throw an exception
|
||
|
||
### Requirement 5: 配置管理
|
||
|
||
**User Story:** As an administrator, I want to manage AI configurations in the database, so that I can easily update API settings without code changes.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE System SHALL retrieve AiConfig by config_key using AiConfigService
|
||
2. THE System SHALL validate that the AiConfig is enabled (is_enabled = 1) before use
|
||
3. THE System SHALL use custom_params from AiConfig to merge with runtime parameters
|
||
4. THE System SHALL respect timeout_ms setting from AiConfig for API calls
|
||
5. THE System SHALL support retry logic based on retry_count and retry_delay_ms from AiConfig
|
||
|
||
### Requirement 6: 错误处理
|
||
|
||
**User Story:** As a developer, I want proper error handling for AI API calls, so that I can diagnose and fix issues quickly.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. IF the API returns non-200 status code, THEN THE System SHALL log the error with status code and response body
|
||
2. IF the stream parsing fails, THEN THE System SHALL log the raw stream data for debugging
|
||
3. IF the network request times out, THEN THE System SHALL retry based on configuration
|
||
4. THE System SHALL provide meaningful error messages to the caller
|
||
5. THE System SHALL not expose sensitive information (like API tokens) in error messages
|