feat：module-split

[xiaocheny214]

后端模块拆分

当前阶段：各模块定义抽象接口（ABC）+ Pydantic 领域模型。部分模块已有具体实现（media）。
每个模块包含 interface.py（接口）、model.py（领域模型），有实现的模块额外包含 service.py。

项目层级

backend/
├── packages/
│   ├── common/        # 共享：Response、BizException、BizCode 枚举
│   ├── framework/     # 基础设施：KodoStorage、ChatProvider、DB 配置
│   ├── ai_engine/     # 生成管线（独立包）
│   └── app/           # 业务应用
│       └── src/windup_app/
│           ├── web/api/              # FastAPI 路由
│           │   ├── generation.py     # 生成任务 API + SSE 进度推送
│           │   ├── media.py          # 媒体上传 API
│           │   ├── workflow_run.py   # 执行记录 API
│           │   └── agent.py          # LLM 代理 API（POST /ai/chat）
│           ├── bootstrap/app.py      # 组装入口（composition root）
│           └── server/               # 业务域（按域分组）
│               ├── media/            # 用户素材上传
│               ├── project/          # 项目约束配置
│               ├── character/        # 角色资产数据
│               ├── orchestrator/     # 生成任务调度
│               └── workflow_run/     # 工作流执行记录

已删除的模块：

• workflow（旧卡片体系，被 workflow_run 替代）
• agent（后端不做 agent 编排，简化为 LLM 代理端点 POST /ai/chat）
• web/sse/（SSE 模块，合并到 generation API）

---

依赖方向

        common
          ▲
        framework
          ▲
   ┌──────┴──────┐
ai_engine     foundation
   ▲          ▲
   │          │
   │     workflow_run
   │          │
   └───── orchestrator

模块关系：

• workflow_run（执行记录）：存储前端维护的节点树 JSONB，不感知节点结构
• orchestrator（生成任务调度）：管理生成任务生命周期，调用 ai_engine
• ai_engine（生成管线）：实际 AI 生成，被 orchestrator 调用

规则：

• foundation → framework, common
• workflow_run → foundation, framework, common
• orchestrator → ai_engine, foundation, framework, common
• ai_engine → framework.providers（接口）, common
• 禁止：foundation → orchestrator / ai_engine
• 禁止：ai_engine → foundation / orchestrator

---

基础业务域

media — 用户素材上传

对应表： windup_media 接口： MediaService 实现： ObjectStorageMediaService

方法	说明
upload(data, metadata)	上传文件到对象存储，返回 URL

文件分类 MediaCategory：reference-image / outfit-preview / action-frame / general

project — 项目约束配置

对应表： windup_project 接口： ProjectService

方法	说明
create_project(project)	创建项目
project_name_exists(user_id, name)	名称唯一性校验
get_project(id)	按 ID 查询
list_projects(page, page_size, user_id)	分页查询
delete_project(id)	删除

character — 角色资产数据

对应表： windup_character 接口： CharacterService

character_data JSONB 三层嵌套：outfit → action → frame

方法	说明
create_character(session, **fields)	创建角色
get_character(session, character_id)	按 ID 查询
list_characters(session, *, project_id, page, page_size)	分页查询
update_character(session, character_id, **fields)	更新角色
delete_character(session, character_id)	删除角色

---

工作流域

orchestrator — 生成任务调度

对应表： windup_generation_task 接口： GenerationService

管理生成任务生命周期：创建任务 → 加载项目约束 → 调 ai_engine → 上传结果 → 回写状态。

方法	说明
generate_character_image(input)	提交角色图片生成任务
generate_character_action(input)	提交角色动作生成任务
get_task(project_id, task_id)	查询任务状态与结果

SSE 推送：

端点：GET /generation/tasks/{task_id}/stream

事件类型：

• progress：生成进度 {stage, current, total, note}
• completed：任务完成，携带 result
• failed：任务失败，携带 error

SSE 端点和 EventBus 内置于 web/api/generation.py，不单独维护 SSE 模块。

workflow_run — 工作流执行记录

对应表： windup_workflow_run 接口： WorkflowRunService

设计原则： 后端不感知节点结构。节点树由前端维护，通过 nodes JSONB 字段全量读写。

数据模型：

字段	类型	说明
id	BigInteger	主键
project_id	BigInteger	关联项目
parent_run_id	BigInteger	父执行记录（版本链）
root_capability	VARCHAR(50)	根节点能力类型
root_input	JSONB	根节点输入
root_output	JSONB	根节点输出
nodes	JSONB	节点树（前端自定义结构，后端不校验）
status	VARCHAR(20)	active / soft_deleted
version	INTEGER	版本号
created_at	TIMESTAMPTZ	创建时间

接口方法：

方法	说明
create_run(project_id, root_capability, root_input, nodes?)	创建执行记录
get_run(run_id)	获取执行记录（含 nodes）
update_run(run_id, root_output?, nodes?, status?)	全量更新（含 nodes）
delete_run(run_id)	软删除
diff_runs(new_run_id, old_run_id)	对比新旧 run

API 端点：

POST   /workflow-runs                     创建执行记录
GET    /workflow-runs/{id}                 获取执行记录（含 nodes）
PATCH  /workflow-runs/{id}                 全量更新（含 nodes）
DELETE /workflow-runs/{id}                 软删除
POST   /workflow-runs/{id}/diff/{old_id}   对比新旧 run

版本链： 修改角色模板时，创建新 run（parent_run_id 指向旧 run），前端可通过 diff 判断哪些节点可复用。

---

AI Proxy

agent — LLM 代理

端点： POST /ai/chat

后端是无状态 LLM 代理，不做 agent 编排。前端维护 conversation history，传完整 messages 数组。

请求体：

{
  "system": "系统提示词",
  "messages": [{"role": "user", "content": "..."}],
  "model": "gpt-4o",
  "tools": [{"type": "function", "function": {...}}]
}

响应： OpenAI 兼容 SSE 流式格式。

后端职责： 认证 → 调用 LLM → 流式转发。不解析 tool_calls、不执行工具、不存对话历史。

前端职责： 维护对话历史、定义 tools、解析 tool_calls、调用原子能力 API 执行工具。

---

生成管线域

ai_engine — 生成管线

接口： CharacterGeneratorPort

生成管线：提示词 → 出图 → 抠图 → 截帧 → 返回产物。

组件	职责
strategy/	策略分发（VIDEO_I2V / PER_FRAME / PROC_IDLE）
prompt/	提示词构建（walk / jump / attack）
slicing/	帧提取（imageio/pyav）
postprocess/	像素化、脚线对齐、sprite sheet 打包
master_prep.py	母版预处理

---

设计哲学

后端不与前端 UI 耦合

后端提供固定的原子能力（生成图片、生成动画、导出）和存储能力（workflow_run），前端负责节点定义、拼装、推进。前端交互变更不影响后端。

workflow_run 只做记录

后端不感知节点结构，nodes JSONB 由前端全量读写。回滚、版本管理由前端逻辑驱动，后端只提供存储和 diff 能能。

SSE 不单独维护

SSE 端点内置于 generation 模块（GET /generation/tasks/{task_id}/stream），EventBus 也内置于同一文件。不抽象为通用基础设施。

Agent 在前端

后端只提供 POST /ai/chat LLM 代理。agent 编排逻辑（意图识别、工具调度、对话管理）全部在前端实现，前端调用后端原子能力 API 执行工具。

[johnnyzhang-eng]

这份拆分我整体认同，分层链和禁止依赖写得很清楚。下面五条，第一条建议在动手实现前先定，因为它会直接让前端收不到事件。

一、SSE 事件名：现在场上有三个版本，互不兼容（最急）

来源	事件名
agent-sse-api-design 文档	status / progress / completed / failed（4 个）
已部署实例的实际行为 + 前端 #110 的实现	单一 task_update，靠 payload 里的 status 区分状态
本 Issue	progress / completed / failed（3 个）

线上抓到的原始报文（2026-08-05，真实部署实例，订阅一个已完成任务）：

event: task_update
data: {"task_id": 4, "task_type": "character_image", "status": "completed",
       "result": {"type": "character_image", "image_urls": ["..."]},
       "error_message": null}
retry: 3000

前端 #110 entities/generation/api.ts 只 addEventListener('task_update', ...)。按本 Issue 的三事件实现，前端一个事件都收不到，而且不会报错——表现为"任务永远不动"。

建议：把事件名定为单一真源并写进接口文档（我倾向沿用线上已跑通、前端已实现的 task_update + payload 内 status；若要改成三事件，需要同步改 #110 并作废那份四事件文档）。三份文档并存的状态本身就是下次撞车的原因。

顺带一个实测缺陷（不管选哪套事件名都要处理）：服务端发完终态事件就关流，但响应带了 retry: 3000。浏览器原生 EventSource 把关流当断线，实测 45 秒内重连 15 次，每次重收同一条 completed，业务回调被重复触发。需要前端在终态显式 close()，或服务端终态不下发 retry。

二、web/sse/ 删除：我这边的 PR 受影响，处置说明

我在 feat/backend-dev 上的 SSE PR（DireSoul#31）核心就是 web/sse/__init__.py + web/sse/stream.py 两个文件，正是本 Issue 要删的模块；而且它当前已 mergeable=false。

方向我认同（少一层间接），所以不打算保它——我会按本 Issue 的形态重做：SSE 端点与 EventBus 内置到 web/api/generation.py，原 PR 关掉。这样避免"合了又要拆"的返工。如果你已经在写这块，告诉我一声，我就不重复做了。

三、character_data 三层嵌套缺一层：角色级派生资产（Refs #121）

本 Issue 写的是 outfit → action → frame 三层。渲染出帧路线在母版确认后还有一段角色级、一次性的工作：图生3D → 减面 → 绑骨，产物（GLB + 骨架规范 + 挂点）必须持久化并被该角色所有后续动作复用，现有三层里无处存放。

实测成本口径（2026-08-05，真实调用）：图生3D 专业版 20 积分 ≈ ¥2.4、绑骨 10 积分 ≈ ¥1.2、套动作走外部免费动作库 + 本地重定向 ¥0。

• 有角色级存储：¥3.6 一次性 + 每动作 ¥0 → 10 个动作 ≈ ¥3.6
• 无角色级存储：每动作都要重跑前两段 → 10 个动作 ≈ ¥36

一次性成本被变成每动作成本，10 倍差距。

细节和建议字段（model_3d / render_profile / sockets，全部可选、默认 null，逐帧与视频路线行为不变）在 #121。你们正在建表，这是留位的最便宜窗口——字段可选，留位代价接近零，等表上线再加就要迁移。

另外 ai_engine 的 ports 侧还有三处装不下 3D 输入/渲染期几何量/存储边界的问题，在 #122，与本 Issue 的 ai_engine → framework.providers 依赖规则相关。

四、workflow_run.nodes 由前端定义：这个设计对渲染路线是利好，但 root_capability 需要约定取值

「后端不感知节点结构、nodes 全量 JSONB 读写」这条对我们是好事——渲染路线要新增的节点类型（图生3D / 绑骨 / 复用已有骨架资产）不需要后端建模就能落进工作流，接入门槛比预期低。

但 root_capability VARCHAR(50) 是个跨端契约点：它是字符串而非枚举，前后端各写各的就会漂。建议在本 Issue 里列出当前认可的取值集合（哪怕只有两三个），新增走 Issue 追加。

同时想确认一条设计意图：nodes 后端不校验，那么服务端将来若需要按节点做查询/统计/迁移（例如"找出所有用过某能力的 run"），退路是什么？现在全量 JSONB 是最灵活的形态，但也意味着这类需求只能靠全表扫 JSONB 或前端兜。这条不是反对，是想知道失败退路，以免将来被迫改存储结构。

五、两条已经修对的，确认一下

• get_task(project_id, task_id) 带上了 project_id。之前的实现忽略它，拿到 task_id 就能读任意任务的输入、产物 URL 与错误详情（自动评审和我都独立报过），新签名把归属校验的位置留出来了。
• SSE 不再单独维护模块、合并进 generation API——少一层，赞成。

补充：文档规范上的两点建议

• 「已删除的模块」列了 workflow / agent / web/sse 三项，但只有 agent 写了理由（后端不做 agent 编排）。另两项建议补一句为什么，否则后来人（包括我这种在上面开了 PR 的）无法判断是"这条路走不通"还是"暂时不做"。
• 事件类型、root_capability 这类跨端契约项，建议标注依据与日期（是设计决定、还是对齐过某个实现）。第一条那三版本并存，根子就在没有单一带日期的真源。

[xiaocheny214]

SSE 事件名：现在场上有三个版本，互不兼容（最急）

现使用本issue定义好的版本。我们会发现，实际上用到sse推送的就仅是任务调度模块。其他模块是没有用到的，我们是不用把sse单独抽象出来作为一个模块的，将其合并到任务调度模块即可。而之前那个文档的定义的，我们是综合考虑了agent是放在后端来做逻辑的，包括后续agent的响应流的推送逻辑，我们是用到sse的。但实际上我们把agent逻辑放在前端来做了，后端仅仅需要提供一个中转大语言模型的接口即可。所以最终sse推送就只有一个模块，即任务调度模块用到。
线上部署的，发现前端采用的接收格式，与我们后来定义的不同，估计是赶进度遗落出来的问题。现统一采用本Issue的sse推送流程。