# MiragenFlow 当前实现与 Holopix 对齐摘要

## 1. 结论先行

MiragenFlow 当前是一个**服务端网关 + 本地优先资产的图片、文本、音频 AI 无限画布工作台**：

- 用户从首页进入画布项目库，在一个项目中放置文本、图片、音频、生成配置和分组节点。
- 生成请求由配置节点触发，浏览器通过同源 `/api/v1` 异步任务网关提交；服务端按公开模型目录路由到供应商，WebSocket 提供进度，结果再写回画布节点。
- 生成图片可以继续做反推提示词、多角度、裁剪、蒙版编辑、切分和本地放大，并把结果连成新的节点。
- 画布项目和“我的资产”默认保存在浏览器；WebDAV 是可选的跨设备同步，不是项目自带的云端账户或云存储服务。
- `/admin/` 已替换为元境幻生业务台，接入用户、认证消息、渠道、渠道组、模型、套餐、审批、账本、任务、存储和审计 API；旧 TDesign mock 路由和示例页面已移除。

与 Holopix 的核心差距不在“有没有一个画布”，而在于 Holopix 把**游戏美术专用算法、3D/自由视角、模型训练、语义拆分、云端资产与商业账户体系**做成了产品级工作流。MiragenFlow 目前只有其中一部分通用能力，尤其还没有真正的 3D、自由摄像机、语义拆图、抠图、风格模型训练和云端任务体系。

本轮界面回归还修复了用户端资产/画布列表的嵌套滚动、资产标题居中、浅色滚动条与控件硬编码深色、共享 Dialog/Drawer 的 ESC 关闭，以及移动导航遮罩；菜单文字与标题保持左对齐，画布库操作区可在窄屏换行，业务列表在手机端保留紧凑横滑。近期又将画布音频/文字设置弹层改为窄屏自适应宽度，并为创建/右键菜单补齐 ESC、外部点击和菜单语义；管理台详情请求失败会保留抽屉并提供重试，设置与调用记录抽屉显式支持关闭按钮、遮罩和 ESC，且管理台抽屉在窄屏会保留可点击的遮罩区域。共享 TDesign Switch 已改为非嵌套 label 的可点击布局，带文字开关保留可读名称和受控切换。开发者组件中心继续只在开发路由中独立渲染，不进入正式用户壳层或导航；用户端固定为中文，目录错误、任务错误和图片用量均以中文字段化展示。桌面与 390px 公开页面截图已保存，登录态资产/画布截图仍需在授权测试会话中补齐。

> 本轮实现状态：服务端已具备异步任务/WS、公开目录、渠道快照/fallback、unknown 对账、余额 bucket、签名 mock 支付、套餐权益、管理员 audience/RBAC 菜单、审批式人工充值、上传幂等/quarantine 扫描、WebDAV manifest/ETag、冲突副本、到期清理和离线重试队列。临时生产配置 smoke 已验证 PostgreSQL/Redis 就绪、任务 snapshot、dispatch outbox、领域任务创建/余额预扣持久化重载和队列租约；支付订单/webhook 已纳入 Store 事务，任务结算/释放/未知对账也统一经过任务事务边界；消息 outbox lease、发送期续租、provider message ID、错误状态和死信边界可跨重启恢复。管理员预览登录默认仅需邮箱和密码，MFA/管理员人机验证码为默认关闭的后台增强开关；普通用户验证/MFA 默认关闭，关闭后前端不渲染验证码、动态码或恢复码输入；真实 provider/消息/支付服务仍必须在部署环境中配置，不能用本地 fixture 结果代替。任务详情/审批驳回、认证开关 stale challenge 清理、审计保留和任务 PostgreSQL 心跳/过期恢复已补齐；管理台增加近 7 日任务趋势、运行告警、按业务维度/状态/日期筛选及 API 403 恢复路由，401 自动刷新重试会保留原始幂等键，渠道生成测试会把平台显示模型 ID 转成供应商请求模型 ID；跨实例 dispatch 可回载缺失任务投影，快照保存使用捕获时不可变 revision fencing；WebDAV PG worker 完成事务与保留期扫描器已使用增量行锁路径持久化文件、manifest、保留/归档状态和冲突副本；用户控制台视觉基础已从 `MiragenFlow-front` 迁移到 `web/src/user-console/`，首页作品流读取真实资产库，搜索框与模型广场入口按当前产品边界隐藏，登录/注册/验证/重置及图片/音频创作页统一使用组件中心视觉，现有画布/资产/创作 API 保持不变；真正按领域表实现全量 task/worker CAS 和远端多实例 WebDAV/消息验证仍是生产扩容前的后续硬化项。

## 2. 当前产品边界

### 2.1 已保留范围

1. 首页和产品导航。
2. 画布项目库：创建、重命名、导出、导入、删除；画布内支持节点和图片组复制，当前没有项目级“一键复制”入口。
3. 无限画布：节点、连线、分组、平移、缩放、选择、拖拽、调整大小、小地图、撤销/重做。
4. 图片、文本、音频、生成配置、分组五种内置节点。
5. 图片、文本和音频生成；参考图编辑；生成失败重试和取消。
6. 反推提示词、多角度生成、裁剪、蒙版编辑、异步图片切分和异步放大。
7. “我的资产”：文本、图片和音频资产的增删改查、搜索、筛选、导入导出和画布插入，并与平台资产目录镜像。
8. 公开模型目录、能力 schema、分辨率、价格和套餐；provider 渠道、凭证和路由顺序只在管理端。
9. WebDAV 同步画布、资产及引用到的图片/音频文件。
10. 简体中文、浅色/深色主题、版本变更查看、文档入口。
11. V1 仅保留内置画布节点；扩展菜单、全局插件 runtime、远程插件市场和 URL 安装不进入用户界面。

说明：旧功能文档按“19 个顶层功能、保留 12 个”统计；本文件按代码入口和调用链重新分组，因此这里列出的 11 项是梳理口径，不是对旧统计数字的重新改写。

### 2.2 已明确移除或暂不纳入

- 独立图片工作台、独立视频工作台和视频节点。
- 远程提示词系统、Prompt Center。
- Local Agent、Codex、MCP、Skill 和 Codex App 接入。
- 远程插件市场。
- 视频/动画生成暂不作为当前产品范围；音频生成保留。

## 3. 应用结构和路由

| 地址 | 入口 | 当前作用 |
| --- | --- | --- |
| `/` | `web/src/pages/home/index.tsx` | 首页说明、进入画布项目库、进入画布。无业务请求。 |
| `/canvas` | `web/src/pages/canvas/index.tsx` | 本地画布项目列表，创建、导入、导出、批量删除。 |
| `/canvas/:id` | `web/src/pages/canvas/project.tsx` | 单个项目的无限画布和全部节点操作；进入项目时隐藏普通顶部导航。 |
| `/assets` | `web/src/pages/assets/index.tsx` | 文本/图片/音频资产库，搜索、编辑、导入导出、下载、复制和删除。 |
| 其他前台地址 | `web/src/pages/not-found/index.tsx` | 404 页面。 |
| `/admin/` | `admin/src/router/index.ts` | 元境幻生管理后台，默认跳转 `/admin/dashboard/base`。 |

前台路由由 `web/src/router.tsx` 统一注册，正常页面包在 `UserLayout` 和 `AnalyticsTracker` 中。顶部只保留画布和资产导航；存储、主题和文档入口通过右上角操作区提供，前台不显示版本更新入口。

开发时：

```text
浏览器 :3000
  /       -> web Vite :3000
  /admin  -> web Vite 代理到 admin Vite :3003
```

`scripts/dev-all.mjs` 并行启动两个 Vite，`web/vite.config.ts` 将 `/admin` 代理到 `3003`。生产构建由 `scripts/build-all.mjs` 把 `admin/dist` 复制到 `web/dist/admin`，Nginx 只暴露一个 3000 端口。

## 4. 主要数据模型和持久化

### 4.1 画布项目

`useCanvasStore`（`web/src/stores/canvas/use-canvas-store.ts`）保存：

```text
CanvasProject
  id, title, createdAt, updatedAt
  nodes: CanvasNodeData[]
  connections: CanvasConnection[]
  backgroundMode: dots | lines | blank
  showImageInfo
  viewport: { x, y, k }
```

数据使用 `localforage` 写入 IndexedDB 的 `miragenflow:canvas_store`，画布状态变化后延迟约 400ms 写入；项目页的 viewport 另有约 500ms 防抖。刷新浏览器后会从 IndexedDB 恢复，媒体引用再从 `image_files`/`media_files` 存储中恢复为 Object URL。

### 4.2 资产

`useAssetStore`（`web/src/stores/use-asset-store.ts`）支持三种 `AssetKind`：

- `text`：标题、标签、来源、备注和文本内容。
- `image`：data URL/Object URL、`storageKey`、宽高、字节数和 MIME 类型。
- `audio`：媒体 URL、`storageKey`、字节数、时长和 MIME 类型。

资产记录写入 `miragenflow:asset_store`，图片二进制写入 `image_files`。删除资产会异步扫描画布和资产引用，清理未使用的图片/音频文件。

### 4.3 平台目录和配置

`useConfigStore` 仅保存公开模型选择、创作参数、主题和 WebDAV 脱敏状态；不再保存 provider 配置。平台目录由 `useCatalogStore` 从 `/api/v1/catalog/models` 加载，包含：

- 基础/高级/旗舰公开模型 ID、能力矩阵和参数 schema。
- 分辨率预设、生成数量上限和金币价格。
- 套餐名称、时长、包含金币、并发和队列优先级。
- 图片质量、尺寸、比例、透明背景、数量。
- 文本 reasoning effort。
- 音频 voice、format、speed、instructions。
- 全局 system prompt 和 WebDAV 配置。

浏览器不导出 provider Key、Base URL、内部模型 ID 或 WebDAV 密码；WebDAV 凭证只在服务端密文保存，用户端仅保存目录和脱敏连接状态。

## 5. 功能调用逻辑和实际效果

### 5.1 首页和导航

```text
打开 /
  -> HomePage 渲染品牌、真实工作流入口和公开模型目录
  -> ClientRootInit 通过 catalog API 加载启用的公开 modelProduct
  -> 点击图片、音频、画布或任务入口进入对应真实路由
```

效果：首页不再使用演示作品、视频/动画/3D宣传位或假对话框；公开目录为空时明确展示状态，所有工作流按钮都进入真实功能路由。

### 5.2 项目库

```text
点击新建
  -> useCanvasStore.createProject()
  -> 创建空 nodes/connections、lines 背景和默认 viewport
  -> navigate('/canvas/:id')

导入 ZIP
  -> readZip()
  -> 读取 projects.json
  -> 恢复 image/media Blob 到 IndexedDB
  -> importProject() 为每个项目生成本地新 id
```

导出项目时，`canvas-export.ts` 会把项目 JSON、节点引用到的图片/音频文件一起写入 ZIP；导出选中节点时，文本写入 `.txt`，媒体写入对应文件，无法识别的节点写入 `.json`。

效果：项目可离线保存、迁移和回滚；没有服务器项目列表、账号隔离、协作和云端历史。

### 5.3 无限画布

画布不是 React Flow 或真正的 WebGL 场景，而是 DOM 节点加 SVG 连线：

```text
MiragenFlowCanvas
  -> viewport { x, y, k } 做 CSS translate + scale
  -> CanvasGrid 绘制点/线背景
  -> CanvasNode 渲染节点 DOM
  -> CanvasConnection 渲染 SVG 贝塞尔连线
```

主要操作：

- 选择工具/移动工具；拖拽节点、框选、调整尺寸。
- 滚轮缩放，画布平移，Control/空格临时切换工具。
- 节点之间创建和删除连接；连接只表达引用/工作流关系，不是后端任务依赖图。
- 复制粘贴、重复节点、分组、解组、删除、清空。
- 画布背景切换为点、线、空白；小地图定位；撤销/重做最多保留近期快照。
- 节点 hover 工具条可查看信息/JSON、下载、保存资产、重试、打开编辑器。

效果：适合把提示词、参考图、生成配置和结果排成探索图；目前没有 Holopix 那种 3D 视口、相机轨道、图层时间线、骨骼/动画轨道或真实场景编辑。

### 5.4 内置节点

`builtin-nodes.tsx` 注册五种内置节点：

| 节点 | 作用 | 结果 |
| --- | --- | --- |
| 文本 | 输入提示词、展示文本生成结果 | 可编辑、复制、保存为文本资产，也可一键创建图片配置节点。 |
| 图片 | 上传、展示生成/编辑图片 | 支持比例保持、批量图片组、下载、编辑、保存资产。 |
| 音频 | 上传或展示生成音频 | 可播放/替换/下载；音频二进制保存在本地媒体库。 |
| 配置 | 选择 image/text/audio 模式、模型和参数 | 作为工作流执行节点，没有 source handle，接收上游文本/图片/音频。 |
| 分组 | 组织多个节点 | 只影响画布组织和拖动，不产生 AI 请求。 |

内部节点 registry 支持源码级注册/卸载扩展节点，`use-plugin-host.tsx` 负责运行时和面板；当前没有面向用户的远程插件安装入口。

### 5.5 图片生成、参考图编辑和批量结果

统一入口是 `project.tsx` 的 `handleGenerateNode`：

```text
点击配置节点生成
  -> buildGenerationConfig()
  -> 检查 Base URL / API Key / model
  -> buildNodeGenerationInputs()
       收集入边上的 text、image、audio
  -> hydrateNodeGenerationContext()
       把 storageKey 媒体恢复为可请求 URL/data URL
  -> 有参考图 ? requestEdit() : requestGeneration()
  -> 每个结果 uploadImage()
  -> 更新 image node 的 content/storageKey/images/primaryImageId/status
  -> useCanvasStore 持久化项目
```

图片 API（`web/src/services/api/image.ts`）支持：

- OpenAI 兼容 `/images/generations`。
- OpenAI 兼容 `/images/edits`，以 multipart 上传参考图和可选 mask。
- Gemini `generateContent`，把参考图转成 inline data。
- 用户自定义 model script。
- 返回 `data`、`images`、`results`、`b64_json`、URL 等多种响应形态。
- 图片数量限制为 1-15；尺寸按 16px 对齐，最长边不超过 3840，比例不超过 3:1，总像素在约 65 万到 829 万之间。

效果：一次生成可以产生一个可展开的图片组，每张图片可以单独设置主图、下载、复制、重试或删除；失败节点保留错误状态和错误信息，AbortController 支持取消。

### 5.6 文本生成和反推提示词

文本节点由配置节点以 `text` 模式执行：

```text
上游文本/图片 + 配置节点
  -> buildNodeGenerationContext()
  -> requestImageQuestion()
  -> OpenAI Responses 或 Gemini 流式接口
  -> onDelta() 持续更新文本节点
  -> 完成后保存 prompt/status/metadata
```

图片节点的“反推提示词”不是独立的云端 Prompt Center：

```text
图片工具条“反推提示词”
  -> createImageReversePromptNodes()
  -> 创建一个文本节点和一个 text 模式配置节点
  -> 将图片节点、文本节点连到配置节点
  -> 打开配置面板，等待用户执行文本生成
```

效果：能把一张图接入多模态模型并生成可复用的描述，但当前不是专用的图像标签/结构化提示词引擎，也不会自动产生角色、材质、镜头、风格等游戏美术字段。

文本节点还可以直接生成图片：代码会自动创建配置节点、连线并打开图片参数面板，用户确认后再走图片生成链路。

### 5.7 音频生成

```text
音频配置节点
  -> requestAudioGeneration()
  -> OpenAI 兼容 /audio/speech 或自定义 audio script
  -> Blob 校验
  -> storeGeneratedAudio()
  -> uploadMediaFile(..., 'audio')
  -> 写回音频节点 content/storageKey/duration/status
```

当前支持 voice、格式、速度和 instructions。Gemini 格式暂不支持音频生成；音频资产可以在画布和资产库中创建、编辑、播放、下载、导入导出，并通过 WebDAV 同步。

### 5.8 图片工具

#### 反推提示词

见 5.6。输出是新的文本节点和 text 配置节点，不会修改原图。

#### 多角度生成

`canvas-node-angle-dialog.tsx` 提供水平角度、俯仰角、相机距离、宽视角等参数；`generateAngleNode()` 把参数转换成提示词，然后调用 `requestEdit()` 生成新的图片节点。

效果：能生成“正面/侧面/俯视”等视角近似图，但本质是参考图 + 文本的图像重绘，不是 3D 模型或真实可旋转相机。

#### 裁剪

`canvas-node-crop-dialog.tsx` 在浏览器预览中拖动裁剪框，可选自由、固定、原图、1:1、4:3、16:9、9:16；确认后 `cropDataUrl()` 在本地生成新图片并创建子节点。

效果：无 API 消耗、结果可复现；只改变像素范围，不做内容理解。

#### 蒙版编辑

`canvas-node-mask-edit-dialog.tsx` 使用两个 HTML Canvas 记录涂抹/擦除笔画，支持笔刷大小、撤销/重做；提交时生成 mask data URL，`maskEditImageNode()` 调用 `/images/edits` 生成子节点。

效果：具备基础局部重绘；Gemini 通道不支持 mask，部分模型也可能拒绝 mask。

#### 图片切分

`canvas-node-split-dialog.tsx` 支持行列网格和可拖动分割线，最多 12×12；`splitDataUrl()` 本地切成多个 PNG，每块上传到 IndexedDB 并创建带连线的图片子节点。

效果：适合规则 Sprite Sheet/九宫格切分；没有 Holopix“全能拆分”所需的语义识别、自动边界、透明背景、角色/图标检测、图层恢复或命名。

#### 本地放大

`upscaleDataUrl()` 在浏览器本地生成放大图片，再创建子节点。

效果：是本地像素放大/重采样，不等同于 AI 重绘放大、无损 4K 或细节重建。

### 5.9 资产库和画布插入

```text
画布节点工具条“保存到资产”
  -> addAsset({ source: 'Canvas', metadata: { nodeId, prompt } })
  -> asset store 持久化

资产页新建/编辑图片
  -> uploadImage()
  -> 写入图片 Blob + asset record

画布侧栏选择资产
  -> AssetPickerModal
  -> insertCanvasText() / insertCanvasImage()
  -> 新节点写入当前画布
```

资产页支持关键词搜索、text/image 筛选、分页、预览抽屉、编辑、文本复制、图片下载、删除、ZIP 导入导出。导入时会丢弃原资产 id 和时间戳，重新生成本地记录。

### 5.10 配置与模型目录

用户端只读取服务端公开目录：模型公开 ID、能力矩阵、分辨率、数量和预计金币消耗。供应商渠道、Base URL、API Key、内部模型 ID 和自定义调用脚本不再属于用户端配置，服务端 adapter 负责统一调用和故障切换。

### 5.11 WebDAV 同步

```text
配置 WebDAV URL/目录/账号密码
  -> MKCOL 确保目录存在
  -> PROPFIND 测试连接
  -> 读取 canvas/manifest.json 与 assets/manifest.json
  -> 按 id + updatedAt 合并本地和远端记录
  -> 下载缺失图片/音频 Blob
  -> 上传新增或大小变化的媒体，最多 3 个并发
  -> 上传新的 manifest.json
```

效果：同一 WebDAV 目录可以在不同浏览器间恢复项目、资产和媒体；远端清单会被校验为 `app=miragenflow` 且 domain 正确。服务端保存 ETag/版本，冲突返回 409 并保留冲突信息；连接失败进入离线重试队列，后台可查看保留和归档策略。

### 5.12 后台管理台

后台源码位于 `admin/`，保留 TDesign 的布局和组件能力，但路由已经收敛为真实业务域：Dashboard、用户/认证消息、渠道/渠道组/健康、模型/分辨率/价格、套餐/换算、任务/attempt、余额/充值/支付/审批、存储/WS 指标和审计。所有请求通过 `/api/v1/admin/*`，管理员会话、MFA、RBAC、幂等、版本校验和审计由服务端负责；模板 mock 页面和示例接口已删除。

## 6. Holopix 已确认的功能

本节根据 `https://holopix.cn/` 首页 HTML、其公开的 `5.0.3` 前端 bundle（`index-WzmJSrLD.js`）和页面元描述整理。未登录状态下无法验证所有按钮的实际权限和任务结果，因此区分“公开文案”和“bundle 路由/功能名”。

### 6.1 官网公开定位

首页元描述明确强调：

- 游戏角色、场景、三视图和游戏 ICON 生成。
- 中文生成、欧美卡通、二次元、Q 版、国风等游戏动漫风格模型。
- 图像风格转换、模型自定义训练。
- 局部细化、局部替换/擦除。
- 一键无损 4K 提升。
- 3D 转换视角。
- 智能拆补图层、一键抠图、线稿提取。

结合你此前对网站的观察，可以把它的产品面拆成四类：

- **游戏资产**：角色、场景、ICON、三视图/六视图、Sprite/拆分和透明素材。
- **艺术资产**：风格模型、万能渲染、调色板、像素化、表情和相似图变体。
- **3D 化工作流**：3D 转换、3D 生成、自由视角和模型预览。
- **动画/动效**：公开 bundle 能确认多条视频、首尾帧、图生视频和文生视频路线；完整动画时间轴、动效编辑器和导出细节需要登录后继续核验，不能仅凭首页宣传文案判定为已完整开放。

### 6.2 公开 bundle 中可确认的功能名

普通工作台/工具：

- 一键成稿、丰富细节、局部细化、智能编辑、全能编辑 V1/V2/V3。
- 万能渲染、自由视角、风格渲染调试。
- 3D 模型、3D 转换、3D 生成。
- 线稿提取、相似图裂变、一键抠图、局部编辑。
- 快速放大、重绘放大、智能扩图。
- 生成调色板、像素图转换、表情生成。
- 全能拆分、Klein 一致性编辑、Klein 图像修补。

自由画布工作流：

- 自由画布-万能渲染。
- 自由画布-智能模型。
- 自由画布-一键成稿、自由画布-一键抠图。
- 自由画布-相似图裂变、智能扩图、局部修改、重绘放大。
- 自由画布-自由视角、自由画布-3D 生成、自由画布-Seedream V5 Pro。
- 多种参考图/图生视频/文生视频/首尾帧视频路线（视频当前不纳入 MiragenFlow 范围）。

视角参数：

- 正视图、斜侧图、侧视图、俯视图、仰视图、背视图。
- 一键三视图、一键六视图。

模型和商业能力：

- 风格模型、组合风格、万能渲染模型、视频模型。
- 模型定制、模型训练、风格渲染模型训练、模型组合、模型广场。
- 公开 bundle 还包含会员套餐、并行任务、算力/权益、作品历史保存和云空间等产品线索。

## 7. 能力对齐矩阵

| Holopix 能力 | MiragenFlow 当前状态 | 差距判断 |
| --- | --- | --- |
| 无限/自由画布 | 有 2D DOM/SVG 无限画布、节点连线、分组和导出 | **部分对齐**：缺少 Holopix 的专用任务节点、3D 视口、时间轴和云端任务。 |
| 万能渲染 | 无专用渲染工作流；只有通用 image generation 和自定义脚本 | **缺失**：需要风格/构图/参考控制模型和专用参数面板。 |
| 自由视角 | 有多角度参数和参考图重绘 | **部分对齐**：只是 2D prompt + edit，不是真实相机、深度或 3D 一致性。 |
| 三视图/六视图 | 可手动生成一个角度结果 | **缺失/弱对齐**：需要固定视角批量生成、视图一致性和结果组管理。 |
| 3D 转换/3D 生成 | 无 Three.js/WebGL/3D 模型节点和模型文件导出 | **缺失**：需要图生 3D/文生 3D 服务、GLB/OBJ/纹理和 3D 预览。 |
| 游戏角色/场景/ICON | 可以用通用提示词生成图片 | **部分对齐**：缺少游戏资产模板、结构化字段、透明背景、批量规范和可复用风格。 |
| 全能拆分/智能拆补 | 只有规则网格切分，最多 12×12 | **部分对齐**：需要语义检测、自动边界、透明图层、Sprite/ICON/角色分件和命名。 |
| 一键抠图 | 无背景移除功能 | **缺失**：蒙版编辑是局部重绘，不是前景分割/透明 PNG 输出。 |
| 线稿提取 | 无 | **缺失**：需要边缘/线稿模型和可调阈值、导出透明线稿。 |
| 局部细化/局部编辑 | 有蒙版编辑，调用 `/images/edits` | **部分对齐**：有基础 inpainting，但没有 Holopix 的局部细化模型、区域预览和一致性控制。 |
| 智能扩图 | 无 | **缺失**：需要 outpainting 参数、边缘融合和多方向扩展。 |
| 相似图裂变 | 有参考图编辑，但无专门变体控制 | **部分对齐**：需要相似度、变化幅度和批量变体参数。 |
| AI 4K/重绘放大 | 有浏览器本地放大 | **部分对齐**：不是 AI 超分、细节重绘和无损 4K。 |
| 调色板/像素图/表情 | 无专用工具 | **缺失**：需要颜色提取、像素化和表情分类/生成工作流。 |
| 风格模型/模型训练/模型广场 | 无 | **缺失**：需要训练任务、数据集、模型版本、审核、发布和商业权限。 |
| PSD/图层/动画资产 | 当前只输出图片、文本、音频和 ZIP | **缺失**：需要图层数据模型、PSD/序列帧/动画导出和预览。 |
| 视频与动画 | 已按当前范围删除/暂不做 | **明确不对齐**：除非后续重新纳入视频产品线。 |
| 账户、会员、算力、并行任务、作品历史、云空间 | 无登录；前台只有空的 user store，项目主要在浏览器 | **缺失且是商业化基础设施**：需要账户、配额、任务队列、计费、云存储和权限。 |
| 后台业务管理 | TDesign 壳 + 真实 `/api/v1/admin/*` 业务资源 | **V1 已接入**：用户、认证、渠道、模型、套餐、任务、账本、支付、存储、WS 指标和审计均有管理入口。 |

## 8. 建议的对齐顺序

### P0：先建立商业化可用的基础

1. 明确“项目、资产、生成任务、模型、用户、组织、配额”的服务端数据模型。
2. 将浏览器直连 API 抽象为可选的服务端任务代理，避免 API Key、脚本和计费完全暴露在浏览器。
3. 为前台增加登录、任务记录、失败重试、并发限制、用量统计和云端作品历史。
4. 把后台模板改成真实业务后台：用户/组织、模型渠道、任务、资产、审核、套餐/算力、WebDAV 配置和操作日志。

### P1：游戏美术最有辨识度的能力

1. 语义拆分：角色、武器、道具、ICON、Sprite Sheet 自动检测，输出透明 PNG、边界框和命名结果。
2. 一键抠图和线稿提取，支持透明背景和可调边缘。
3. AI 重绘放大、智能扩图、局部细化和相似图裂变。
4. 结构化角色/场景/ICON 模板，统一尺寸、透明背景、视角、风格和批量数量。
5. 三视图/六视图任务：正面、侧面、背面、俯视/仰视批量生成，并把结果作为关联资产组。

### P1/P2：3D 和自由视角

1. 引入真正的 3D 资产格式和预览：GLB/GLTF、OBJ、纹理、材质和骨骼元数据。
2. 接入图生 3D/文生 3D 模型，建立异步任务、进度、失败重试和结果版本。
3. 在无限画布中加入 Three.js 3D 节点或独立 3D 视口，支持 orbit/free camera、视角预设和深度/法线参考。
4. 将当前“多角度 prompt 重绘”保留为轻量模式，和真正的 3D 自由视角明确区分。

### P2：资产生产链

1. Sprite Sheet、序列帧、动画动效节点和导出。
2. PSD/分层图、图层拆补、批量命名和版本对比。
3. 游戏引擎常用导出规格、透明边缘检查、尺寸/命名/格式校验。
4. 风格模型、模型组合、模型市场/团队共享；这部分要建立在账户、审核和计费系统之后。

## 9. 当前限制和风险

- 前台商业认证和任务网关已建立；生产部署必须使用 PostgreSQL、Redis、真实邮件/SMS 适配器和外部风控服务配置。
- 供应商 API Key、Base URL、自定义模型脚本已从用户端运行链路和配置入口移除；真实 provider adapter 仍需在服务端完成。
- 本地 IndexedDB 不是跨设备存储；清理站点数据会影响项目和资产。WebDAV 需要用户主动配置和同步。
- WebDAV 使用 manifest、ETag、删除墓碑和离线重试状态；当前仍是用户主动同步，不提供多人实时协作。
- 当前无限画布的“无限”是 2D DOM/SVG 组织能力，不等于 3D 场景、游戏引擎编辑器或真实自由视角渲染。
- 图片切分是规则网格切分；本地放大是像素重采样；多角度是图像重绘。这三项都不能直接宣传成 Holopix 的语义拆图、AI 4K 或 3D 相机能力。
- `admin/` 的 TDesign 依赖仅用于 UI 壳，模板 README、mock 路由、Tencent 业务文案和示例业务页面已清理。
- 音频生成、音频结果、资产类型、下载和 WebDAV 同步已纳入统一媒体链路。

## 10. 关键代码索引

- 路由和应用壳：`web/src/router.tsx`、`web/src/layouts/user-layout.tsx`、`web/src/components/layout/app-top-nav.tsx`
- 项目状态：`web/src/stores/canvas/use-canvas-store.ts`、`web/src/pages/canvas/index.tsx`
- 画布入口：`web/src/pages/canvas/project.tsx`、`web/src/components/canvas/miragenflow-canvas.tsx`
- 节点定义：`web/src/types/canvas.ts`、`web/src/constant/canvas.ts`、`web/src/components/canvas/nodes/builtin-nodes.tsx`
- 生成上下文：`web/src/components/canvas/canvas-node-generation.ts`、`web/src/lib/canvas/canvas-generation-helpers.ts`
- 平台图片任务 API：`web/src/services/api/platform-image.ts`、`web/src/services/api/platform.ts`
- 音频 API：`web/src/services/api/audio.ts`、`web/src/lib/audio-generation.ts`
- 服务端 provider adapter：`server/src/adapters/provider.ts`
- 图片工具：`web/src/components/canvas/canvas-node-*-dialog.tsx`、`web/src/lib/canvas/canvas-image-data.ts`
- 资产：`web/src/pages/assets/index.tsx`、`web/src/stores/use-asset-store.ts`、`web/src/pages/assets/asset-transfer.ts`
- 本地媒体：`web/src/services/image-storage.ts`、`web/src/services/file-storage.ts`
- WebDAV：`web/src/services/webdav-sync.ts`、`web/src/services/app-sync.ts`
- 配置：`web/src/stores/use-config-store.ts`、`web/src/pages/settings/index.tsx`
- 后台：`admin/src/router/index.ts`、`admin/src/pages/Business/index.tsx`、`admin/src/services/platform.ts`
- 同端口启动/构建：`scripts/dev-all.mjs`、`scripts/build-all.mjs`、`web/vite.config.ts`、`Dockerfile`、`nginx.conf`

## 11. 当前 V1 落地状态

本轮已建立 `packages/contracts/` 与 `server/`：共享错误码、公开/管理员 DTO、认证、防刷、MFA、公开模型目录、金币余额、任务状态/attempt、WS 事件和能力契约；服务端提供注册验证、密码重置、Refresh Cookie 轮换、管理员独立 audience/RBAC/MFA、人工充值审批、mock/adapter 支付 webhook 契约、套餐权益、四渠道顺序故障切换、Redis lease fencing、unknown 自动对账入口、事件 cursor 和 WS 实时订阅，并补齐 PostgreSQL 领域行投影、迁移锁/revision 冲突检测、保留期归档/GC 与 WebDAV 冲突任务。

前台新增服务端会话、认证守卫、账户页、公开模型目录、余额和任务保留操作；普通用户默认账号密码直登，邮箱/短信验证、验证码和 MFA 通过 `/api/v1/auth/policy` 及后台开关启用，增强开启后仍展示对应导入/验证信息。图片/文本/音频及图片工具默认经过 `/api/v1/tasks/*`，浏览器不保存 provider Key；管理员 MFA 的 CAPTCHA 豁免绑定当前管理员会话，支付适配器凭证仅在服务端加密保存，用户支付响应不暴露内部适配器标识，退款按原到账 bucket 幂等入账。后台移除示例 GitHub 入口、模板 mock 和远程 Tencent API，菜单覆盖用户、认证消息、渠道、分组、健康、模型、套餐、换算、任务、余额支付、存储、WS 指标和审计业务域。前台不再提供版本更新面板。

管理台重构已进入实现阶段：`admin/src/router/index.ts` 使用七个视觉一级分组承载 22 个业务二级页面，Vite `/admin/` basename 对外形成 `/admin/...` 地址；`AppRouter` 会在已有 token 但缺少用户信息时重新拉取 `/admin/me`，服务端对旧管理员会话按角色补齐 scope，403/404 页面提供可用的返回概览/重新登录按钮。用户新增、渠道、渠道组、模型产品和价格规则改为按钮触发的弹窗，认证消息提供脱敏详情、换行内容和失败重试，表格使用固定列宽与中文状态/能力摘要；渠道生成测试会按独立模型映射将平台显示模型 ID 转成供应商请求模型 ID，管理台 401 刷新后的重试会保留原始幂等键；日志大板和详细日志在具备审计权限且记录有详情编号时显示右侧固定的日志详情操作列。供应商消息与模板仍隐藏，不代表已接入。

管理台用户工作台已补充管理员重置密码、重发认证消息、用户会话 ID、套餐权益、任务/账本/审计详情 Tab 和余额详情；重置仅返回一次性密码并撤销旧会话，重发消息进入认证 outbox。系统概览接口新增任务 P50/P95、渠道成功率/P95、模型错误、消息失败率和支付回调异常等聚合指标，渠道健康接口返回调用次数、成功率和 P95 延迟（无样本时不伪造探活时间）。新增独立版本化 `/api/v1/admin/settings` 资源，认证增强开关、限流和保留字段支持 If-Match，并在关闭用户增强时即时清理旧状态。写操作失败会保留当前弹窗以便处理 409/503 后重试，认证消息/套餐说明/分辨率配置使用多行输入，字段摘要不会撑高表格。

已验证：服务端类型检查、102 个服务端测试（新增缺失 CSRF Cookie 的旧管理员会话恢复与业务写请求仍受保护回归，另含普通用户默认策略关闭、账户修改密码、其他会话撤销和注销匿名化、独立系统设置 If-Match/即时策略、健康/就绪、生产 fixture 隔离、认证/充值/套餐支付/退款/支付凭证脱敏/任务幂等、公开模型 ID/3D 目录过滤、渠道故障切换、取消、账本 bucket、部分结算 release、未知预扣回收、staging 保留、上传幂等、消息 provider 故障切换、lease、JWT header、WS access/refresh family 与撤销断开、事务回滚/提交后事件、管理员 RBAC/MFA/CAPTCHA、WebDAV 冲突/路径/到期清理、会话族 token 撤销、套餐/资产/审批/保留期、管理契约别名和充值状态转换、出站 URL 公网解析与固定地址）、前台/后台类型检查和构建、统一构建脚本及同源开发入口。临时生产配置 smoke 验证了 PostgreSQL/Redis、23 个 SQL 迁移文件、canonical 用户/余额/账本/渠道/任务/attempt/event 行、任务 snapshot、dispatch outbox、消息指纹/lease 字段、领域任务创建/余额预扣、支付指纹持久化与 PostgreSQL 写入后重新加载、Redis lease claim/renew/ack/nack；PostgreSQL revision fencing、失败后可恢复的持久化队列、bucket 关系和计费字段投影也已补齐。同源路由 `/`、`/admin/`、`/api/v1/`、`/api/ready` 也已核验，并以独立浏览器页面验证默认账号密码注册/登录、账户/套餐/设置和桌面移动导航；当前预览还通过 curl 核验 `/admin/` 下 22 个页面均返回 200，并实际调用管理员登录、概览、渠道健康、用户新增和重置密码接口；增强开关开启后的验证码/MFA、真实外部服务联调仍属于部署环境验收。生产 Compose 已改为缺少密钥时拒绝启动；活动 staging 对象会按对象保留期保护，不被固定 GC TTL 提前删除。
另经独立未登录浏览器标签逐一访问管理台 22 个可见业务路由，均稳定呈现登录主体，未暴露业务页面；该证据只覆盖路由门禁，不替代登录后的逐页视觉、权限、写操作、错误/重试和窄屏验收。
普通开发存储现在不再自动创建模拟支付适配器，支付 fixture 只在测试模式或显式 `MIRAGENFLOW_TEST_MODE=true` 下存在；真实开发环境仍需管理员显式配置支付适配器。