1024XEngineer · xyh202131 · Aug 4, 2026 · Aug 7, 2026
diff --git a/.gitignore b/.gitignore
@@ -25,3 +25,6 @@ output/
 .ruff_cache/
 .pytest_cache/
 .import_linter_cache/
+
+# 本地数据库初始化脚本
+init.sql
diff --git a/README.md b/README.md
@@ -1,120 +1,2 @@
-<p align="center">
-  <img src=".github/assets/windup-mark.svg" width="96" alt="Windup 机械小鸟标志">
-</p>
-
-<h1 align="center">Windup</h1>
-
-<p align="center">
-  面向国产小游戏开发者的 2D 角色动态素材生成与资产工作台
-</p>
-
-<p align="center"><strong>交付的是资产，而不是图片。</strong></p>
-
-Windup 面向缺少美术产能的个人开发者和小型团队，把角色构思、动作生成、逐帧质检、试玩与引擎导出收进同一条生产链。用户从文字描述或参考图出发，最终得到可以持续补充动作、修正缺陷和重新导出的角色资产。
-
-## 产品链路 / Product Workflow
-
-```text
-新角色：文字描述 / 参考图 → 项目约束 → 角色母版
-已有角色：从资产库继续生产 ─────────────┘
-                              ↓
-                     动作序列帧 → 逐帧审核 / 局部重生成
-                              ↓
-             Playtest 试玩 → PNG / Sprite Sheet / 元数据 → 游戏引擎
-```
-
-Windup 用角色母版约束跨帧、跨动作的视觉一致性，再用确定性的工程后处理完成去背景、切帧、对齐和打包。出现缺陷时，返工可以缩小到具体帧或节点，已通过的结果继续保留。
-
-## 核心对象 / Core Concepts
-
-| 对象 | 职责 |
-| --- | --- |
-| `Project` | 统一管理题材、美术风格、视角与精灵尺寸等项目级约束 |
-| `Character` | 角色资产本体；造型、动作实例与帧属于它的资产树 |
-| `ActionTemplate` | 可在不同角色间复用的动作规格与生产配方 |
-| `Generation` | 一次生成任务及其输入、状态和结果，用于恢复与追溯 |
-| `WorkflowRun` | 一次前端制作流程的运行记录，连接生成、确认、回退与导出 |
-
-产品提供两种入口：`Quick Start` 用自然语言建立标准生产流程；`Workflow Editor` 在系统预置的成熟管线上追加动作分支、微调参数和局部返工。两者共用同一套流程状态和质量门禁，分别服务快速创建与精细控制。
-
-## 当前阶段 / Project Status
-
-MS2 已完成 Windup 的产品 MVP，验证了角色资产生产的核心链路。MS3 的重点从“完成一次生成”转向“持续完善已有角色资产”：用户可以从资产库回到已有角色，为它补充动作、重做有问题的分支，并保留未受影响的资产。
-
-| 状态 | 内容 |
-| --- | --- |
-| MS2 产出 | 完成产品 MVP，跑通并验证角色资产生产的核心体验 |
-| MS3 产品主线 | 已有角色补动作；工作流采用固定成熟管线，通过卡片加号追加分支，支持参数微调与局部重跑 |
-| MS3 工程重点 | 持久化 `WorkflowRun` 并关联角色，串起工作流编辑、产物审核、节点回退与 Playtest |
-| 后续探索 | Quick Start Agent、3D 动作生成路线、多视角资产与项目级导出 |
-
-项目进度见 [`main`](https://github.com/1024XEngineer/Windup/tree/main) 与 [Issues](https://github.com/1024XEngineer/Windup/issues)。
-
-## 技术栈 / Tech Stack
-
-- 前端：React 19、TypeScript 6、Vite 8、Tailwind CSS 4、Vitest
-- 后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、uv workspace
-- 工程约束：GitHub Actions、Ruff、Pytest、Import Linter、oxlint、oxfmt
-
-## 本地开发 / Local Development
-
-前端支持 Node.js `^20.19.0`、`^22.12.0` 或 `>=24.0.0`；CI 使用 Node.js 24：
-
-```bash
-cd frontend
-npm ci
-npm run dev
-```
-
-后端使用 Python 3.12 和 [uv](https://docs.astral.sh/uv/)：
-
-```bash
-cd backend
-uv sync --frozen
-uv run uvicorn windup_app.bootstrap.app:create_app --factory --reload
-```
-
-## 质量检查 / Quality Checks
-
-```bash
-# frontend/
-npm run format:check
-npm run lint
-npm run typecheck
-npm run test
-npm run build
-
-# backend/
-uv run ruff check .
-uv run lint-imports
-uv run pytest -q
-```
-
-## 仓库结构 / Repository Structure
-
-```text
-Windup/
-├── frontend/                  # React 前端、页面与制作流程
-├── backend/                   # Python 工作区、领域服务与 API
-├── docs/                      # 后端模块划分等工程文档
-├── frontend-architecture-v3.md
-└── README.md
-```
-
-## 相关文档 / Documentation
-
-- [Windup 产品策划案](https://github.com/1024XEngineer/Windup/issues/37)
-- [核心流程与工作流](https://github.com/1024XEngineer/Windup/issues/25)
-- [前端架构与模块边界](frontend-architecture-v3.md)
-- [前后端 API 契约差异](frontend/API_CONTRACT.md)
-- [后端模块划分](docs/module-split.md)
-
-## 参与贡献 / Contributing
-
-问题、需求和实验记录统一进入 [Issues](https://github.com/1024XEngineer/Windup/issues)。功能和核心改动按 `Proposal → Issue → Branch → Pull Request → Review` 推进，开发前请先查看对应 Issue 与领域契约。
-
-项目的维护与历史贡献见 [Contributors](https://github.com/1024XEngineer/Windup/graphs/contributors)。
-
-## 许可证 / License
-
-[Apache License 2.0](LICENSE)
+# game-asset-character
+Generate high-quality 2D game characters.
diff --git a/_PR说明.md b/_PR说明.md
@@ -0,0 +1,70 @@
+# Generation + SSE Adapter
+
+Refs #78
+
+Issue #78 已补 `mile3` 标签并关联 `milestone/4`。本变更只实现前端 Generation
+实体适配器与 SSE 传输封装，不修改后端、页面、Controller、共享入口或构建产物。
+
+## 变更范围
+
+- 将创建、按项目查询和状态订阅统一收口到 `GenerationApis`。
+- `createGenerationApis` 必须由宿主注入 `userId` 与 `transport`；模块不写死用户身份，
+  也不直接持有 `fetch` 或 `EventSource`。
+- 新增业务无关的 `shared/api/stream.ts`，封装命名 SSE 事件、取消、终态关闭、
+  非法消息错误和断线通知。临时断线保留浏览器 EventSource 的协议级自动重连，
+  不恢复 2 秒业务轮询。
+- 查询与订阅要求调用方传入 WorkflowRun 已知的阶段期望；动作阶段还必须带上
+  `actionType`，避免把其他动作的帧误接到当前任务。
+- 角色母版由宿主通过 `resolveImageSize(projectId)` 提供项目画布尺寸；Generation 不直接
+  依赖 Project，也不会回退到可能冲突的 1024 默认值。
+
+## 三阶段合同
+
+| 前端阶段             | 后端请求                  | 固定/可配置数量           | 结果映射                     |
+| -------------------- | ------------------------- | ------------------------- | ---------------------------- |
+| `character_template` | `POST /generation/image`  | 固定 `num_images: 4`      | 严格校验并映射 4 个候选      |
+| `first_frame`        | `POST /generation/action` | 固定 `num_frames: 1`      | 严格校验并映射 1 帧动作首帧  |
+| `complete_animation` | `POST /generation/action` | 当前固定 `num_frames: 16` | 按后端 `frames[].index` 排序 |
+
+`CompleteAnimationGenerationInput` 当前没有 `frameCount` 字段，因此无法由调用输入表达
+帧数。本次保守沿用后端合同默认值 16；后续若合同加入可配置字段，应改为透传输入并补充
+边界校验，而不是继续保留常量。
+
+## SSE 行为
+
+- 端点：`/generation/tasks/{taskId}/stream?project_id=...`。
+- 只监听 `task_update` 命名事件，事件 DTO 在 Generation 边界解析和校验。
+- `completed`、`failed` 都视为终态；事件先交付调用方，再由传输层关闭连接。
+- `onError` 必传，非法事件关闭连接时不能静默留下永远等待的工作流。
+- 显式取消返回幂等函数，并移除监听器、清空错误处理器、关闭 EventSource。
+- 非法 JSON、非法 DTO 或调用方事件处理异常会报告错误并关闭连接。
+- 浏览器连接中断会报告 `SSE 连接中断`，连接保持给 EventSource 自动重连；没有定时
+  GET、退避 GET 或其他业务轮询。
+
+## DTO 校验
+
+- 校验响应 envelope 的 `code/message/data`，业务错误不会被当作成功数据。
+- 校验任务与事件的正整数 ID、项目归属、用户归属、任务类型和四个合法状态。
+- 未知状态直接抛 `GenerationApiError`，绝不降级为 `pending`。
+- 校验完成结果的判别字段、图片 URL、候选/首帧数量、动作类型、16 帧数量与连续索引、
+  时长格式与状态/错误一致性；非完成任务携带结果同样视为非法合同。
+
+## 测试覆盖
+
+- 三阶段请求体映射与注入用户身份。
+- 角色母版四候选、动作一首帧、完整动画帧排序。
+- 未知状态与非法完成结果 DTO。
+- SSE URL、`task_update` 映射、主动取消、终态关闭、事件解析错误和断线恢复语义。
+
+## 验证结果
+
+- `npx oxfmt --check` 定向检查本次 5 个 TypeScript 文件：通过。
+- `npm run format:check` 全量检查：已执行，但被基线中 41 个本次所有权外文件阻断；
+  未批量重写这些文件，以免覆盖其他工作者的修改。
+- `npm run lint`：通过。
+- `npm run typecheck`：通过。
+- `npm test`：通过，4 个测试文件、12 个测试，其中本模块新增 10 个。
+- `npm run build`：通过，Vite 8.1.5 共转换 88 个模块。
+
+后端 `/generation/tasks/{taskId}/stream` 的实现与真实联调不在本前端-only 变更范围内；
+本次测试通过注入 transport 验证前端合同，不把它表述为后端 SSE 已可用。