AI配置增加字段适配处理

2025-12-23 16:51:53 +08:00
parent 2d033e6a3e
commit 7f89fd17d3
22 changed files with 2951 additions and 4 deletions
@@ -0,0 +1,294 @@
+# Design Document
+
+## Overview
+
+本设计文档描述了Coze AI通用接口调用服务的架构设计，以及爽文剧本AI生成功能的实现方案。核心目标是重构AiChatServiceImpl，提供一个通用的、可配置的AI接口调用方法，支持通过config_key获取配置并调用Coze工作流API。
+
+## Architecture
+
+### 系统架构图
+
+```mermaid
+graph TB
+    subgraph "Controller Layer"
+        EC[EpicScriptController]
+    end
+    
+    subgraph "Service Layer"
+        ESS[EpicScriptServiceImpl]
+        ACS[AiChatServiceImpl]
+        AICS[AiConfigServiceImpl]
+    end
+    
+    subgraph "Data Layer"
+        ACM[AiConfigMapper]
+        ESM[EpicScriptMapper]
+    end
+    
+    subgraph "External"
+        COZE[Coze API]
+    end
+    
+    EC --> ESS
+    ESS --> ACS
+    ACS --> AICS
+    AICS --> ACM
+    ESS --> ESM
+    ACS --> COZE
+```
+
+### 调用流程图
+
+```mermaid
+sequenceDiagram
+    participant C as Controller
+    participant ESS as EpicScriptService
+    participant ACS as AiChatService
+    participant AICS as AiConfigService
+    participant DB as Database
+    participant COZE as Coze API
+    
+    C->>ESS: createScript(request)
+    ESS->>ESS: assembleInput(request)
+    ESS->>ACS: callWorkflowByConfigKey(configKey, input, userId)
+    ACS->>AICS: getByConfigKey(configKey)
+    AICS->>DB: SELECT * FROM t_ai_config WHERE config_key = ?
+    DB-->>AICS: AiConfig
+    AICS-->>ACS: AiConfig
+    ACS->>ACS: buildWorkflowRequest(config, input, userId)
+    ACS->>COZE: POST /v1/workflow/stream_run
+    COZE-->>ACS: SSE Stream Response
+    ACS->>ACS: parseStreamResponse(response)
+    ACS-->>ESS: AI Generated Content
+    ESS->>ESS: parseAndSaveScript(content)
+    ESS->>DB: INSERT INTO t_epic_script
+    ESS-->>C: EpicScriptResponse
+```
+
+## Components and Interfaces
+
+### 1. AiChatService 接口扩展
+
+```java
+/**
+ * AI聊天服务接口 - 新增通用工作流调用方法
+ */
+public interface AiChatService {
+    
+    // ... 现有方法 ...
+    
+    /**
+     * 通过配置键调用Coze工作流API
+     * 
+     * @param configKey AI配置键（如：coze.course.life.generate）
+     * @param input 输入参数，将作为parameters.input传递给工作流
+     * @param userId 用户ID
+     * @return AI生成的内容
+     */
+    String callWorkflowByConfigKey(String configKey, String input, String userId);
+    
+    /**
+     * 通过配置键调用Coze工作流API（带自定义参数）
+     * 
+     * @param configKey AI配置键
+     * @param parameters 自定义参数Map，将合并到请求的parameters中
+     * @param userId 用户ID
+     * @return AI生成的内容
+     */
+    String callWorkflowByConfigKey(String configKey, Map<String, Object> parameters, String userId);
+}
+```
+
+### 2. AiConfigService 接口扩展
+
+```java
+/**
+ * AI配置服务接口 - 新增按配置键获取方法
+ */
+public interface AiConfigService {
+    
+    // ... 现有方法 ...
+    
+    /**
+     * 根据配置键获取AI配置
+     * 
+     * @param configKey 配置键
+     * @return AI配置，如果不存在或已禁用则返回null
+     */
+    AiConfig getByConfigKey(String configKey);
+}
+```
+
+### 3. EpicScriptService 接口（无变化）
+
+现有接口保持不变，实现层调用新的AI服务方法。
+
+## Data Models
+
+### Coze工作流请求格式
+
+```json
+{
+    "workflow_id": "7586262962160762926",
+    "user_id": "user_123",
+    "stream": true,
+    "parameters": {
+        "input": "用户填写的信息组装后的字符串",
+        "user_id": "user_123"
+    }
+}
+```
+
+### Coze工作流响应格式（SSE）
+
+```
+id: 0
+event: Message
+data: {"node_title":"End","node_execute_uuid":"","usage":{"token_count":1571,"output_count":812,"input_count":759},"node_is_finish":true,"node_seq_id":"0","content":"{\"output\":\"AI生成的内容...\"}","content_type":"text","node_type":"End","node_id":"900001"}
+
+id: 1
+event: Done
+data: {"node_execute_uuid":"","debug_url":"..."}
+```
+
+### 用户输入组装格式
+
+```
+剧本标题：{title}
+主题/渴望：{theme}
+风格：{style}
+篇幅：{length}
+序幕（低谷回响）：{plotIntro}
+转折（契机出现）：{plotTurning}
+高潮（命运抉择）：{plotClimax}
+结局（新的开始）：{plotEnding}
+```
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: Request Format Correctness (请求格式正确性)
+
+*For any* valid AiConfig and input parameters, the generated Coze workflow request SHALL contain:
+- workflow_id from the AiConfig
+- user_id from the call parameters
+- stream set to true
+- parameters.input containing the input string
+- Authorization header with "Bearer {api_token}"
+- Content-Type header set to "application/json"
+
+**Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.6**
+
+### Property 2: Stream Response Parsing (流式响应解析)
+
+*For any* valid Coze SSE stream response containing an "event: Message" line followed by a "data:" line with JSON containing "node_type": "End" and a "content" field with nested JSON containing "output", the parser SHALL extract and return the output value.
+
+**Validates: Requirements 3.1, 3.2, 3.3**
+
+### Property 3: Input Assembly Completeness (输入组装完整性)
+
+*For any* EpicScriptCreateRequest with non-null field values, the assembled input string SHALL contain all provided field values (title, theme, style, length, plotIntro, plotTurning, plotClimax, plotEnding).
+
+**Validates: Requirements 4.2**
+
+### Property 4: Configuration Application (配置应用正确性)
+
+*For any* AiConfig retrieved by config_key:
+- If is_enabled = 0, the system SHALL reject the config and throw an exception
+- The api_base_url, api_token, and workflow_id SHALL be used in the request construction
+- The custom_params SHALL be merged with runtime parameters
+
+**Validates: Requirements 1.3, 5.2, 5.3**
+
+### Property 5: Error Message Quality (错误消息质量)
+
+*For any* error that occurs during AI API calls:
+- The error message SHALL be meaningful and descriptive
+- The error message SHALL NOT contain sensitive information such as API tokens
+- The error message SHALL include relevant context (config_key, status code if applicable)
+
+**Validates: Requirements 6.4, 6.5**
+
+## Error Handling
+
+### 错误类型和处理策略
+
+| 错误类型 | 处理策略 | 返回值 |
+|---------|---------|--------|
+| 配置不存在 | 抛出RuntimeException | "未找到AI配置: {configKey}" |
+| 配置已禁用 | 抛出RuntimeException | "AI配置已禁用: {configKey}" |
+| API调用超时 | 重试（根据配置） | 重试失败后返回错误消息 |
+| HTTP非200响应 | 记录日志，返回错误 | "AI服务调用失败: {statusCode}" |
+| 流式解析失败 | 记录原始数据，返回错误 | "AI响应解析失败" |
+| JSON解析失败 | 返回原始内容 | 原始content字符串 |
+
+### 日志记录规范
+
+```java
+// 请求日志
+log.info("调用Coze工作流: configKey={}, workflowId={}, userId={}", configKey, workflowId, userId);
+
+// 响应日志
+log.info("Coze工作流响应: configKey={}, contentLength={}", configKey, content.length());
+
+// 错误日志
+log.error("Coze工作流调用失败: configKey={}, statusCode={}, error={}", configKey, statusCode, errorMsg);
+```
+
+## Testing Strategy
+
+### 单元测试
+
+1. **AiConfigService测试**
+   - 测试getByConfigKey返回正确配置
+   - 测试配置不存在时返回null
+   - 测试配置禁用时返回null
+
+2. **请求构建测试**
+   - 测试buildWorkflowRequest生成正确的请求格式
+   - 测试参数合并逻辑
+
+3. **响应解析测试**
+   - 测试parseStreamResponse正确解析SSE格式
+   - 测试extractOutputFromContent正确提取output字段
+
+4. **输入组装测试**
+   - 测试assembleInput正确组装用户输入
+
+### 属性测试
+
+使用JUnit 5进行属性测试，每个属性测试至少运行100次迭代：
+
+1. **Property 1: Request Format Correctness**
+   - 生成随机的AiConfig和输入参数
+   - 验证生成的请求包含所有必需字段
+   - 验证请求头正确设置
+   - **Feature: coze-ai-integration, Property 1: Request Format Correctness**
+
+2. **Property 2: Stream Response Parsing**
+   - 生成各种有效的SSE格式响应
+   - 验证正确提取output内容
+   - 测试边界情况（空content、嵌套JSON等）
+   - **Feature: coze-ai-integration, Property 2: Stream Response Parsing**
+
+3. **Property 3: Input Assembly Completeness**
+   - 生成随机的EpicScriptCreateRequest
+   - 验证所有非空字段都出现在组装结果中
+   - **Feature: coze-ai-integration, Property 3: Input Assembly Completeness**
+
+4. **Property 4: Configuration Application**
+   - 生成随机的AiConfig
+   - 验证配置值正确应用到请求
+   - 验证禁用配置被拒绝
+   - **Feature: coze-ai-integration, Property 4: Configuration Application**
+
+5. **Property 5: Error Message Quality**
+   - 模拟各种错误场景
+   - 验证错误消息有意义且不包含敏感信息
+   - **Feature: coze-ai-integration, Property 5: Error Message Quality**
+
+### 集成测试
+
+1. 端到端测试：从Controller到Coze API的完整调用流程
+2. 配置变更测试：验证配置更新后立即生效