前端模块拆分：基于现有代码结构的架构设计

[xyh202131]

Windup MS2 前端模块拆分（完善版）

本文以业务功能拆分 Windup 前端模块，结合现有 Windup 工作台能力、frontend-module-breakdown.md 和已确认的产品方向整理。模块划分用于明确功能与依赖，不代表代码必须按相同目录拆分。

阶段标识：

• MS2：本阶段需要形成完整用户闭环。
• MS2 支撑：本阶段为核心流程提供基础能力，但后续可能替换实现方式。
• 后续：保留产品位置，本阶段不要求落地。

主线流程

Quick Start / 从项目开始 → 创建固定工作流运行 → 项目约束 → 角色与造型基准帧 → 动作生成 → 系统质检 → 人工确认入库 → 逐帧审核与修复 →（建议：网页手感模拟质检）→ 导出

Quick Start 只简化输入和生成过程。生成完成后，候选确认、入库、资产管理、逐帧审核、修复、网页手感模拟和导出仍由人工完成。

核心术语

• 角色：游戏中的人物身份，如“守夜人”。
• 造型：角色的一套装扮。MS2 每个角色只支持一套造型。
• 造型基准帧（母版）：该造型的定妆参考，后续动作必须继承其身份、比例、服装和色彩。
• 动作：Idle、Walk、Run、Jump 等动画语义及其帧序列。
• 候选资产：生成完成但尚未被用户确认入库的结果。
• 项目资产：用户确认进入项目资产库的结果；入库后仍可能处于待审核状态。
• 工作流运行：一次具体生产过程，包含节点状态、任务、候选和人工操作。
• 工作流模板：可复用的配置，不包含旧任务和候选产物。

A. 应用基座模块（MS2 支撑）

为所有页面提供统一的应用外壳、导航、当前上下文和服务访问入口。

前端功能：

• 应用外壳：统一顶部导航、侧栏、工作区和全局操作区。
• 页面路由：项目、创作、工作流、生成、资产、审核、手感模拟和导出页面导航。
• 当前上下文：展示并维护当前项目、角色、造型、动作和工作流运行。
• 全局反馈：成功提示、错误提示、确认弹窗和全局加载状态。
• 统一请求：封装请求、错误映射、凭据会话和资产 URL。
• 运行时配置：管理 API 地址、网页预览地址和通信命名空间。
• 契约读取：统一视角、动作、FPS、模型和生成方式定义。
• 页面恢复：通过 URL 和服务端 ID 恢复项目、任务和审核位置。

功能边界：

• 应用基座不保存具体业务规则。
• 项目、任务、审核和资产的权威状态来自服务端，浏览器缓存只用于改善交互。

B. 创作入口与工作流编排模块（MS2）

负责创建工作流运行、展示固定节点、处理节点连接和同步各业务步骤状态，不重复实现项目、生成、审核或导出的具体业务。

B1. Quick Start

前端功能：

• 输入自然语言描述角色、风格、视角、方向、动作和交付要求。
• 提供示例指令和参考图上传入口。
• 回显识别出的角色名称、造型描述、项目约束、动作和画布参数。
• 允许用户在提交前修正识别结果。
• 确认后创建一条固定工作流运行，并自动执行可自动完成的生成步骤。
• 实时展示母版、Idle 帧和 Walk 帧的到达过程。
• 在候选生成和系统质检结束后停止，等待人工确认。
• 人工确认后进入项目资产库，后续管理和审核不由 Quick Start 自动完成。

需要后端能力：

• 解析自然语言需求。
• 创建工作流运行和生成任务。
• 按 Job ID 返回任务状态与产物。

B2. 从项目开始

前端功能：

• 选择项目或创建项目。
• 选择已有角色，或创建新角色。
• 选择已有动作模板或新增动作要求。
• 选择从零创建、上传参考图或复用当前项目资产。
• 确认后创建工作流运行并进入画布。

需要后端能力：

• 获取项目、角色、造型和动作列表。
• 创建工作流运行。

B3. 固定工作流画布

前端功能：

• 展示项目、角色、造型基准帧、动作、生成、审核、建议手感模拟和导出阶段节点。
• 展示节点连线、先后关系和当前运行位置。
• 支持画布拖动、缩放、适应视图和节点位置调整。
• 允许建立系统预定义的连接，非法连接显示原因。
• 展示节点状态：锁定、可处理、运行中、等待确认、已完成和失败。
• 点击节点进入对应业务模块处理当前步骤。
• 展示生成中的中间产物和任务进度，不只显示最终结果。
• 上游连接有效且运行结果已确认后，才解锁下游节点。

当前边界：

• MS2 使用固定节点和允许连接，不支持任意新增、删除或组合节点。
• 自定义节点、复杂分支、自定义端口、撤销重做和通用低代码能力属于后续。

B4. 工作流运行状态

前端功能：

• 展示工作流总体进度和每个节点的完成情况。
• 区分图结构连接状态和业务运行状态。
• 保存节点人工确认结果和当前处理位置。
• 页面刷新后根据运行 ID 恢复状态。
• 失败节点提供错误原因和重新处理入口。

需要后端能力：

• 获取工作流运行和节点状态。
• 提交节点处理结果。
• 恢复未完成运行。

C. 项目、角色与动作模块（MS2）

管理项目约束以及项目内的角色、造型基准帧和动作定义。

C1. 项目

前端功能：

• 查看、创建、编辑和切换项目。
• 设置项目名称、题材、美术风格和补充说明。
• 上传、预览、替换和删除风格参考图。
• 设置侧视、俯视或 2.5D 视角。
• 设置单向、四向或八向，并校验与视角的兼容关系。
• 设置角色资产画布尺寸。
• 在工作台顶栏展示当前项目约束。
• 修改已有项目约束时展示对现有资产的影响并要求确认。

需要后端能力：

• 获取项目列表和详情。
• 创建和修改项目。

C2. 角色、造型与基准帧

前端功能：

• 创建或选择角色。
• 填写角色名称、身份、定位和外观描述。
• 选择从零创建、上传参考图或使用已有角色。
• 默认继承当前项目的风格、视角、方向和画布约束。
• 按项目的视角与方向组合展示和管理对应的造型基准帧。
• 提交造型基准帧生成要求，实际生成交给生成任务模块。
• 展示候选基准帧，支持选择、重新生成和人工确认；候选数量不写死。
• 查看已确认基准帧和角色已有动作。

当前边界：

• MS2 每个角色只支持一套造型。
• 单造型表示一套装扮；四向或八向项目仍可为同一造型保存多个方向基准帧。
• 多造型切换、换装继承和造型版本比较属于后续。

需要后端能力：

• 获取、创建和修改角色。
• 获取候选基准帧并保存人工确认结果。

C3. 动作

前端功能：

• 查看动作模板和动作说明。
• 选择动作模板应用到当前造型基准帧。
• 展示动作是否循环、默认 FPS 和目标帧数。
• 查看动作生成、审核、修复和可导出状态。
• 从角色详情发起补充动作。

当前边界：

• MS2 基础角色包默认生成 Idle 和 Walk，各 8 帧、8 FPS。
• Run、Jump 和其他动作可作为扩展动作接入，但不作为基础包完成标准。
• 网页手感模拟按实际已审核动作动态提供绑定，不假设每个角色都已有跳跃或攻击。

需要后端能力：

• 获取动作模板。
• 创建动作并获取动作详情。

D. AI 服务接入与生成任务模块（MS2 支撑）

统一管理 Provider 连接、模型选择、基准帧生成、动作生成、任务进度和失败重试。前端不直接执行底层 AI 请求。

D1. Provider 连接与模型设置

前端功能：

• 输入并提交用户自己的 Provider API Key。
• 展示未连接、验证中、已连接和连接失败状态。
• 读取并过滤后端返回的可用模型。
• 选择本次生成使用的模型。
• 展示服务健康状态和重新连接入口。
• 区分密钥无效、模型不可用、服务异常和网络错误。

安全边界：

• API Key 提交后立即清空输入框。
• API Key 不写入浏览器存储、任务、流程、日志或导出文件。
• 凭据由后端内存和安全会话管理。
• 平台模型积分模式上线后，普通用户不再接触 Provider API Key。

D2. 生成确认

前端功能：

• 基准帧生成前展示项目、角色、造型和参考图。
• 动作生成前展示已确认基准帧、动作模板和生成要求。
• 展示模型、生成方式和预计产物。
• 平台积分模式上线后展示预计积分；当前 BYOK 模式不展示虚假扣费。
• 用户确认后发起生成任务。

D3. 生成进度与产物

前端功能：

• 展示任务状态：排队、生成、处理中、系统质检、等待人工确认、完成和失败。
• 基准帧任务展示需求理解、生成和系统质检步骤。
• 动作任务展示动作生成、动作条切分或逐帧到达、归一化和系统质检步骤。
• 按实际到达顺序展示候选基准帧和候选动作帧。
• 展示 Job ID、模型、生成方式、来源入口、耗时和错误原因。
• 页面刷新后通过 Job ID 恢复任务状态。

D4. 重试与修复任务

前端功能：

• 失败任务保留原参数并创建新的重试任务。
• 支持完整动作条重新生成。
• 支持单帧修复，并提交原帧、相邻帧、动作约束和人工修改意见。
• 新候选返回后回到原审核位置继续人工审核。

需要后端能力：

• 创建基准帧、动作和单帧修复任务。
• 获取任务状态和增量产物。
• 执行模型路由、回退、图像处理、任务持久化和成本统计。

E. 资产库模块（MS2）

管理用户确认进入项目的角色基准帧和动作资产，并提供浏览、审核、补充和修复入口。

前端功能：

• 按项目展示角色列表、基准帧、动作组数和总帧数。
• 展示角色身份、造型、视角、方向和项目约束。
• 按角色、视角、动作和审核状态浏览资产。
• 展示动作帧数、FPS、循环类型、生成批次和当前状态。
• 展示来源 Job ID、工作流运行、模型、生成时间和质检摘要。
• 从动作资产进入审核台。
• 为当前角色继续补充动作。
• 从需要修复的资产进入修复流程。
• 提供空状态、加载状态和错误重试。

资产状态：

• 候选：属于生成任务，尚未进入项目资产库。
• 待审核：用户确认入库，但尚未完成逐帧审核。
• 需要修复：存在退回帧或动作问题。
• 逐帧审核通过：所有目标帧已通过人工审核，可以导出；建议先完成网页手感模拟。

网页手感模拟结果作为独立验收记录，分为未验收、通过和发现问题。它不改变资产的导出资格，但发现问题时应突出提示并建议返回审核或修复。

当前边界：

• 候选资产不得直接出现在项目资产库。
• 删除角色或动作、跨项目复用和复杂版本回滚属于后续。

需要后端能力：

• 获取项目资产概览、角色详情和动作资产。
• 获取生成来源和状态。

F. 审查与修复模块（MS2）

负责动作预览、自动质检结果展示、逐帧人工审核和退回修复。

F1. 审核对象与动画预览

前端功能：

• 切换角色、视角和动作。
• 大尺寸展示当前帧和完整动作。
• 播放、暂停、循环、上一帧和下一帧。
• 默认按 8 FPS 播放，并显示动作循环属性。
• 提供洋葱皮、透明背景、脚底线和锚点辅助检查。

F2. 系统质检结果

前端统一展示 7 项检查：

1. 画布尺寸一致性。
2. 透明背景有效性。
3. 脚底线偏差。
4. 主体高度偏差。
5. 相邻帧位移连续性。
6. 轮廓面积波动。
7. 循环首尾接缝；非循环动作显示“不适用”。

系统质检只检查可计算的文件和几何问题。动作语义、解剖、衣装细节和跨帧身份一致性仍由人工判断。

F3. 逐帧人工审核

前端功能：

• 在时间轴中区分待审核、通过和退回帧。
• 单帧通过、单帧退回和填写修改意见。
• 批量通过确认无问题的帧。
• 展示审核进度和未处理问题。
• 保存并恢复未完成的审核会话。
• 所有帧通过后，将动作标记为“逐帧审核通过”。

F4. 退回修复

前端功能：

• 选择需要修复的单帧；单段修复作为后续扩展。
• 填写修改要求并发起修复任务。
• 查看修复进度和新候选。
• 采用新帧后继续原审核流程。

需要后端能力：

• 获取动作帧、系统质检和审核状态。
• 保存单帧或批量审核结果。
• 创建修复任务并返回修复后的帧。

G. 网页手感模拟质检模块（MS2 建议验收）

在浏览器中模拟角色试玩，检查按键触发、动作循环、动作衔接、方向和锚点。它是建议执行的导出验收标准，不是导出硬门禁，也不是目标游戏引擎中的最终运行验证。

G1. 动作与按键绑定

前端功能：

• 选择已通过逐帧审核的动作参与模拟。
• 为移动、待机和其他实际可用动作绑定按键。
• 展示并修改当前按键映射。
• 检测按键冲突并提供恢复默认映射。

G2. 浏览器内模拟

前端功能：

• 在独立预览页面中试玩角色。
• 使用 WASD 和已绑定按键触发动作。
• 展示当前按键、当前动作、方向和循环状态。
• 检查动作循环、切换衔接、锚点漂移和操作反馈。
• 时间轴切帧与 WASD 操作分离，避免输入冲突。

G3. 手感质检结论

前端功能：

• 记录手感模拟是否完成、是否通过，以及测试动作和按键映射。
• 将问题定位到具体动作；能定位到帧时携带帧信息返回审核台。
• 发现问题时建议回到审核或修复流程。
• 未执行或发现问题时，在导出页展示提醒，但不自动锁定导出。

需要后端能力：

• 获取可模拟动作及资源。
• 获取和保存按键绑定。
• 保存手感模拟质检结果。

当前边界：

• MS2 基础包至少验证 Idle 和 Walk。
• Jump、Attack 等动作只有在资产真实存在并通过逐帧审核后才出现在绑定列表。
• Cocos、Unity 等真实引擎运行验证属于引擎适配阶段。

H. 导出模块（MS2）

将通过逐帧人工审核的动作导出为 GIF、SpriteSheet PNG 和 JSON metadata。网页手感模拟是建议验收标准，不是导出硬门禁。

前端功能：

• 从资产详情、手感质检结果或工作流导出节点进入导出流程。
• 仅选择“逐帧审核通过”的动作。
• 导出前展示角色、视角、动作、帧数、FPS、循环方式和文件列表。
• 展示网页手感模拟状态；未验收或发现问题时给出明确提醒，用户确认后仍可继续导出。
• 生成 GIF，用于动画预览和分享。
• 将动作帧合成为透明背景的 SpriteSheet PNG。
• 生成与 SpriteSheet 对应的 JSON metadata。
• 展示导出进度、成功结果和失败原因。
• 分别下载 GIF、PNG 和 JSON。
• 导出后返回项目、资产详情或当前工作流。

JSON metadata 内容：

• 角色、造型、视角和动作标识。
• FPS 和循环标记。
• 帧名称、帧序号、坐标和尺寸。
• sourceSize、spriteSourceSize 和锚点。

当前边界：

• MS2 不提供独立序列帧压缩包、目标引擎包或一键导入插件。
• Cocos、Unity、Godot 等引擎专用包结构和导入步骤属于后续。

需要后端能力：

• 获取可导出动作及其质检状态。
• 如果导出在服务端执行，则创建导出任务并返回下载链接。

I. 流程库模块（MS2 后）

保存并复用经过验证的项目约束和固定工作流配置。现有原型已具备部分能力，但不作为 MS2 交付范围。

前端功能：

• 查看流程名称、版本、项目规格、动作、节点摘要和运行次数。
• 保存已验证流程。
• 加载项目约束、角色来源、动作参数、节点连接、位置和视口。
• 由用户明确启动模板运行，每次创建新的工作流运行和生成任务。
• 自动运行仍在人工确认前停止。

模板不保存 API Key、会话 Cookie、上传原图、候选图片、旧 Job 输出或正式资产副本。

后续能力：

• 流程编辑、删除、版本比较、跨角色重放和团队共享。

J. 用户账户模块（后续）

提供注册、登录、会话恢复、登出和账户设置。MS2 保留产品位置，不落地完整账户系统。

前端功能：

• 邮箱密码和邮箱验证码登录。
• GitHub/Google OAuth 登录。
• 用户注册、忘记密码和重置密码。
• 当前用户、登录状态和自动恢复。
• 未登录访问拦截和登录后返回原页面。
• 个人资料和修改密码。

安全边界：

• 登录态优先使用后端设置的 HttpOnly Cookie。
• 前端不保存可被脚本读取的长期 Token。

K. 积分与计费模块（后续）

平台统一提供模型后，为用户展示积分余额、生成报价、套餐购买和消费记录。

前端功能：

• 展示当前余额、可用额度和余额不足提醒。
• 生成前展示预计积分并在余额不足时拦截任务。
• 生成完成后展示实际积分消耗。
• 展示套餐、当前套餐和购买入口。
• 按时间、任务、模型和消费类型查看记录。

功能边界：

• 支付确认、积分扣减和余额计算由后端完成。
• 积分按模型、生成方式、分辨率、动作数量和实际调用成本计算。

跨模块状态规则

不同对象使用独立状态，不能混成一个“成功/失败”：

• 工作流节点：锁定、可处理、运行中、等待确认、已完成、失败。
• 生成任务：排队、生成中、处理中、系统质检中、等待人工确认、完成、失败。
• 候选资产：等待确认、已放弃、已确认入库。
• 项目动作资产：待审核、需要修复、逐帧审核通过。
• 网页手感模拟：未验收、通过、发现问题；作为建议验收记录，不决定导出资格。
• 导出任务：准备中、生成中、可下载、失败。

关键门禁：

• Quick Start 和从项目开始必须复用同一工作流运行和生成任务机制。
• 候选资产经人工确认后才能进入项目资产库。
• 入库不等于审核通过；后续资产管理和逐帧审核仍由人工完成。
• 全部目标帧通过人工审核后，即可导出 GIF、SpriteSheet PNG 和 JSON metadata。
• 导出前建议完成网页手感模拟；未验收或发现问题时显示提醒，但不阻止用户导出。
• 系统质检和人工审核结果必须分开展示，自动分数不能代替人工通过。
• API Key 不得进入浏览器存储、任务、模板、日志或导出文件。

MS2 范围汇总

MS2 纳入：

• 应用基座和项目上下文。
• Quick Start、从项目开始和固定工作流画布。
• 项目、角色、单造型及其方向基准帧和基础动作。
• BYOK Provider 连接和统一生成任务。
• 候选人工确认、资产库、7 项系统质检、逐帧人工审核和单帧修复。
• 网页手感模拟质检及建议验收记录。
• GIF、SpriteSheet PNG 和 JSON metadata 导出。

MS2 不纳入：

• 流程库正式交付、跨角色模板重放和灵活工作流。
• 完整用户账户和积分计费。
• 多造型、跨项目复用和复杂版本管理。
• 独立序列帧包、多引擎专用包和一键导入插件。
• 生产级分布式任务队列和多人协作。