AI 漫剧后端协作规范

AI 漫剧采用 Java + Python 双服务协作。Java 管理业务数据和业务流程，Python 提供 AI 生成能力。

1. 服务职责

Java 主业务后端

代码位置：

text

backend/java/src/main/java/com/zyease/modules/drama/

Java 负责：

漫剧项目、剧本、章节、角色、分镜、素材和剧集等业务实体。
用户、项目成员和权限校验。
业务事务、状态流转和数据一致性。
创建、取消、重试和查询 AI 生成任务。
保存生成结果、资源地址和业务关联关系。
对前端提供稳定的 /api/v1/drama/** 接口。

Python AI 服务

代码位置：

text

backend/python/app/modules/drama_ai/

Python 负责：

Prompt 编排和版本管理。
大语言模型、图片、音频和视频模型调用。
不同模型供应商的适配。
模型响应解析、内容校验和失败重试。
长耗时 AI 任务执行。

Python 不直接承担 Java 漫剧业务实体的生命周期管理。

Agent 适配层

Java 的 com.zyease.modules.agent 负责：

调用 Python AI 服务的 HTTP 客户端。
跨服务请求和响应 DTO。
超时、重试、鉴权和调用日志。

不要把漫剧业务实体全部放到 agent 模块中。

2. 目录约定

Java 漫剧模块：

text

backend/java/src/main/java/com/zyease/modules/drama/
  project/          # 漫剧项目
  script/           # 剧本、章节、场景、对白
  storyboard/       # 分镜镜头
  character/        # 角色设定
  asset/            # 图片、音频、视频等素材
  generation/       # AI 生成任务
  episode/          # 漫剧集数、审核和发布
  constant/         # 模块状态和常量

Python AI 模块：

text

backend/python/app/modules/drama_ai/
  router.py         # 内部 HTTP 接口
  schema.py         # 跨服务请求和响应契约
  service.py        # AI 编排入口
  providers/        # LLM、图片、音频、视频供应商适配
  prompts/          # Prompt 模板和版本
  tasks/            # 异步任务、重试和超时处理

Java 业务子模块内部按需要使用以下包：

text

controller/         # HTTP 入参和响应
service/            # 业务编排和事务
service/impl/       # Service 实现
mapper/             # MyBatis-Plus 数据访问
entity/             # 数据库实体
dto/                # 请求对象
vo/                 # 响应对象
converter/          # DTO、Entity、VO 转换

3. 推荐调用流程

text

前端
  -> @fx/ic 业务画布封装
  -> Java /api/v1/drama/**
  -> Java 创建 drama_generation_task
  -> Java agent client 调用 Python
  -> Python 调用模型供应商
  -> 返回 task_id/result 或回调 Java
  -> Java 更新任务并保存业务结果

长耗时的剧本、图片、配音和视频生成不能让前端同步等待。接口应返回任务 ID，由前端查询任务状态，或由 Java 接收 Python 回调。

当前已提供 AI 能力检查接口：

text

GET /api/v1/internal/drama-ai/capabilities

该接口仅用于联调和运维检查。正式生成接口上线前，需要补充服务间鉴权、请求签名或网关访问限制。

4. 前端画布业务层

packages/ic（包名 @fx/ic）是产品级画布业务封装，位于底层画布引擎和具体页面之间：

text

业务页面
  -> @fx/ic
  -> @fuxishi/infinite-canvas-vue
  -> @fuxishi/infinite-canvas-core

各层职责：

infinite-canvas-core：图模型、命令、撤销重做、DSL、拓扑执行和渲染内核。
infinite-canvas-vue：Vue 3 适配、受控 nodes/edges、事件和引擎 expose。
@fx/ic：产品画布、工具栏、添加菜单、默认节点卡片和产品动作事件。
业务页面：调用 Java API、维护项目数据、处理素材库和生成任务。

当前 @fx/ic 已注册的基础节点类型：

text

text-gen
image-gen
audio-gen
video-gen

当前产品动作包括：

text

open-workflow
open-asset
character-library
history
upload
pick-from-history

节点 type、data 和菜单 value 都属于前后端协作契约。新增或修改前应同步更新：

packages/ic/src/nodes/
packages/ic/src/types.ts
Java 漫剧模块的节点白名单和 DTO
Python AI 能力映射
本文档和前端类型测试

第一阶段以当前前端已注册的 text-gen/image-gen/audio-gen/video-gen 为准。后续如果需要调整节点命名，必须通过 DSL 版本迁移兼容已保存数据，不能直接修改历史数据。

节点业务参数放在 node.data，生成结果和大文件不放入节点：

json

{
  "id": "node_01",
  "type": "text",
  "data": {
    "assetId": 1001,
    "generationTaskId": 2001,
    "promptTemplateId": "drama-script-v1"
  }
}

assetId 和 generationTaskId 是 Java 业务数据引用，图片、音频、视频内容由 drama_asset 管理。

@fx/ic 支持通过 getDocument() 导出 DSL v1、通过 setDocument(document) 导入 DSL v1，并提供 v-model:nodes、v-model:edges、v-model:groups 和 viewport 接口。业务页面负责调用后端 API、维护项目和 revision；@fx/ic 不直接请求后端。

当前管理端画布页面已经完成第一版接入：

text

frontend/web/src/views/drama/canvas.vue
  -> adminApi.drama
  -> Java drama canvas API

5. 数据库表规范

Java 正式迁移脚本统一放在：

text

backend/java/src/main/resources/db/migration/

漫剧表统一使用 drama_ 前缀，字段使用 snake_case：

表名	用途
`drama_project`	漫剧项目
`drama_script`	项目剧本
`drama_script_chapter`	剧本章节
`drama_character`	角色设定
`drama_storyboard`	分镜镜头
`drama_asset`	图片、音频、视频等素材引用
`drama_generation_task`	AI 生成任务和状态
`drama_episode`	漫剧成片和发布信息

普通业务表原则上包含：

sql

id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
creator_id BIGINT NULL

约束：

外键字段使用对应的 _id 后缀。
状态字段统一使用 status，取值在 Java constant 包和文档中同步维护。
Prompt 快照、模型原始响应等非固定结构数据使用 JSON 字段。
图片、音频和视频不直接存入 MySQL，只保存对象存储 key、访问 URL、MIME 类型、大小和校验值。
业务表不能依赖 Python 专有模型字段。
新表、新字段和新索引必须通过新的 Flyway migration 提交。
禁止直接修改已经执行过的历史 migration。

6. AI 生成任务规范

建议 drama_generation_task.status 统一使用：

状态	含义
`PENDING`	已创建，等待执行
`RUNNING`	执行中
`SUCCEEDED`	执行成功
`FAILED`	执行失败，可重试
`CANCELLED`	已取消

任务至少需要追踪：

project_id、user_id、creator_id
task_type，例如 SCRIPT、STORYBOARD、IMAGE、AUDIO、VIDEO
status、progress、retry_count
provider、model
Prompt 版本和脱敏后的请求摘要
错误信息、开始时间和结束时间
结果关联 ID 或资源地址

每个生成请求都应支持幂等键，避免前端重复点击产生重复任务。

7. Python 模型适配规范

供应商 SDK 调用只能放在 providers/，不能直接写在 router.py 中：

text

providers/
  llm/
  image/
  audio/
  video/

新增模型供应商时：

定义统一的能力接口和结构化返回值。
在供应商适配器中处理 SDK、认证、超时和错误映射。
在 service.py 中完成业务无关的能力编排。
增加最小单元测试和失败场景测试。
通过环境变量或密钥管理系统注入密钥。

禁止把 API Key、完整用户隐私数据或未脱敏模型响应提交到代码仓库。

8. 协作规则

修改跨服务 DTO、任务状态或数据库结构前，先更新本文档。
Java 和 Python 的字段名、枚举值和错误语义必须保持一致。
Java Controller 只做入参校验、权限入口和 Service 调用。
Python Router 只做协议处理，不直接写模型 SDK 调用。
新增接口必须补充 OpenAPI 描述。
新增数据库结构必须新增 Flyway migration。
破坏性字段变更采用兼容期，先增加字段并双读或双写，再删除旧字段。
提交代码时在 PR 中说明影响的 Java 模块、Python 模块、接口和数据库迁移。

9. 当前实现状态

Java com.zyease.modules.drama 已建立业务领域包骨架。
Python app.modules.drama_ai 已建立 AI 服务骨架。
Python 已注册能力检查接口 /api/v1/internal/drama-ai/capabilities。
具体生成请求协议、模型供应商、异步执行框架和正式业务表结构尚未固化。
建议下一步先完成“文本生成剧本”闭环，再确定任务协议和第一版表结构。

10. 当前联调进度（2026-09-10）

Redis

开发环境已配置远程 Redis：

yaml

spring:
  data:
    redis:
      host: 124.223.140.99
      port: 6379
      database: 0
      password: ${REDIS_PASSWORD:}

服务端检查结果：

Redis 监听地址为 0.0.0.0:6379。
服务器本机使用认证信息执行 PING，返回 PONG。
开发机访问 124.223.140.99:6379 的 TCP 测试未通过。

当前结论：Redis 进程和密码认证正常，公网访问仍需检查云平台安全组或云防火墙。宝塔面板和系统 firewalld 已确认包含 6379/tcp 放行记录，因此下一步优先检查云平台入方向规则。

下一次工作

云平台安全组放行 6379/TCP，来源优先限制为开发机公网 IP。
使用 Test-NetConnection 验证公网 TCP 连接。
启动 Java 后端验证 Redis 实际连接。
Redis 正常后继续画布数据库迁移和真实接口联调。

注意：Redis 密码不写入文档和 Git，统一通过 REDIS_PASSWORD 环境变量提供。

AI 漫剧后端协作规范 ​

1. 服务职责 ​

Java 主业务后端 ​

Python AI 服务 ​

Agent 适配层 ​

2. 目录约定 ​

3. 推荐调用流程 ​

4. 前端画布业务层 ​

5. 数据库表规范 ​

6. AI 生成任务规范 ​

7. Python 模型适配规范 ​

8. 协作规则 ​

9. 当前实现状态 ​

10. 当前联调进度（2026-09-10） ​

Redis ​

下一次工作 ​

AI 漫剧后端协作规范

1. 服务职责

Java 主业务后端

Python AI 服务

Agent 适配层

2. 目录约定

3. 推荐调用流程

4. 前端画布业务层

5. 数据库表规范

6. AI 生成任务规范

7. Python 模型适配规范

8. 协作规则

9. 当前实现状态

10. 当前联调进度（2026-09-10）

Redis

下一次工作