happy-life-star/.kiro/specs/coze-ai-integration/requirements.md

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