# 元境幻生系统图示

> 本文覆盖一期用户端、管理端、系统请求链路和整体架构。
>
> SSI 在本文中指 ASCII 页面图示；Mermaid 图用于可渲染的流程图、时序图和架构图。
> current 表示仓库已有页面，phase 1 表示 develop.md 规划的一期页面。

> 管理台实现状态同步：渠道、渠道组、模型产品支持编辑抽屉，渠道健康支持全部探活，审批支持状态筛选与驳回，任务支持脱敏详情；详情请求失败会保留抽屉并提供重试，设置与调用记录抽屉显式支持关闭按钮、遮罩和 ESC。管理台 401 自动刷新后的重试会复用原始请求头和幂等键，渠道生成测试会把平台显示模型 ID 映射为供应商请求模型 ID。用户端画布设置弹层已按窄屏视口收缩，创建/右键菜单补齐 ESC 与菜单语义；这些页面仍需浏览器逐页验收，详见 `docs/content/docs/progress/pending-test.mdx`。

## 1. 页面清单

### 1.1 用户端

| 页面/路由 | 状态 | 一期职责 |
| --- | --- | --- |
| / | current | 首页、产品定位、开始创作、登录注册 |
| /auth/login、/auth/register、/auth/verify、/auth/reset | phase 1 | 注册、验证、登录、密码重置 |
| /workspace | phase 1 | 模型档位、分辨率、能力和价格选择 |
| /canvas | current | 画布项目列表、导入、导出、删除 |
| /canvas/:id | current | 无限画布、节点编排、任务和结果回写 |
| /tools/image | phase 1 | 万能渲染、局部编辑、反推、多角度、抠图、拆分、放大、扩图 |
| /tools/audio | phase 1 | 音频生成、播放、下载、画布引用 |
| /tools/3d | reserved / not V1 | 仅保留禁用契约；真正图生 3D、文生 3D、预览和导出后续再启用 |
| /tasks、/tasks/:id | phase 1 | 任务历史、进度、attempt、结果和计费 |
| /assets | current | 图片/文本/音频资产、筛选、导入导出、平台镜像、画布插入 |
| /account、/account/plans | phase 1 | 身份、会话、金币余额、账单、充值和套餐购买 |
| /settings | phase 1 | WebDAV 连接、同步、冲突和本地存储状态 |
| /404、/error | current/phase 1 | 统一错误、权限和模型不可用提示 |

### 1.2 管理端

| 页面/路由 | 模板来源 | 一期职责 |
| --- | --- | --- |
| /admin/login | Login | 管理员独立会话；默认邮箱密码，按后台开关追加 CAPTCHA/MFA |
| /admin/dashboard/base | BusinessPage | 用户、任务、余额、队列、渠道和告警统计 |
| /admin/users | BusinessPage | 用户状态、脱敏身份、冻结/解冻 |
| /admin/auth-messages | BusinessPage | 邮件/SMS outbox 和发送状态；供应商接入暂缓 |
| /admin/channels | BusinessPage | 渠道启停、健康和脱敏配置 |
| /admin/channel-groups | BusinessPage | priority、fallback 和版本 |
| /admin/model-products、/admin/pricing | BusinessPage | 公开模型、能力、分辨率和价格 |
| /admin/billing/units、/admin/plans | BusinessPage | 金币单位、换算、套餐和权益 |
| /admin/tasks | BusinessPage | 任务、attempt、结果、重试、取消、unknown 对账 |
| /admin/billing、/admin/recharges、/admin/payments | BusinessPage | 账本、充值申请、支付事件 |
| /admin/payment-providers | BusinessPage | mock/adapter 支付配置；第三方支付待接入 |
| /admin/approvals | BusinessPage | 人工充值和高风险操作审批，双人职责分离 |
| /admin/storage、/admin/settings、/admin/ws-metrics | BusinessPage | staging/WebDAV 策略、系统开关和实时指标 |
| /admin/audit、/admin/audit-logs | BusinessPage | 日志大板、详细审计列表和链式审计详情 |
| /admin/security/mfa | BusinessPage | 管理员 MFA 状态、启用/验证/审计关闭（受全局策略约束） |
| /admin/403、/admin/404 | Result | 权限和路由错误 |

## 2. 用户端 SSI（ASCII）

> V1 实现注记：图片/音频/文本以及反推、多角度、拆分、放大均通过 `/api/v1/tasks/*` 异步执行；本地画布只负责编排和缓存。资产页和任务详情同时读取平台资产 API，WebDAV 同步由存储设置触发并显示状态。

### 2.1 全局壳层

~~~text
+--------------------------------------------------------------------------------+
| 元境幻生 | 首页 | 工作台 | 画布 | 资产 | 任务 | 余额 | 账户 | 主题/语言         |
+--------------------------------------------------------------------------------+
|                            当前页面内容                                      |
+--------------------------------------------------------------------------------+
| Toast | 任务事件 | 登录过期 | 模型不可用 | 余额不足                             |
+--------------------------------------------------------------------------------+
~~~

~~~text
[Browser]
   +--> [UserLayout]
   |       +--> [AuthGuard for billable routes]
   |       +--> [CatalogStore] [BalanceStore] [TaskEventClient]
   |       +--> [WebDAVSyncClient]
   +--> [Public Home]
~~~

### 2.2 首页 /

~~~text
+------------------------------------------------------------------------------+
| 元境幻生                                                                     |
| 游戏美术 / 艺术资产 / 多视图工作流                                           |
|                                                                              |
| [开始创作] [打开画布] [查看资产] [登录/注册]                                 |
|                                                                              |
| [万能渲染] [游戏资产] [反推/多角度] [音频]                                   |
+------------------------------------------------------------------------------+
~~~

~~~text
[首页] --> [工作台/模型目录]
      +--> [认证页]
      +--> [/canvas]
      +--> [/assets]
~~~

### 2.3 认证 /auth/*

~~~text
+-----------------------------------------------+
| 元境幻生 | 登录 / 注册 / 验证 / 重置密码        |
+-----------------------------------------------+
| 邮箱或手机号 [.........................]       |
| 密码/验证码  [.........................]       |
| 人机挑战   [ 7 + 5 = ? ] [.............]       |
| [发送验证码] [登录] [注册]                    |
| 忘记密码 | 重新发送验证 | 返回首页             |
+-----------------------------------------------+
~~~

~~~text
[注册] --> [规范化身份] --> [人机挑战（IP/设备/目标绑定）] --> [验证码 Outbox] --> [一次性验证] --> [建立会话]
[登录] --> [人机挑战] --> [Access Token 内存 + HttpOnly Refresh Cookie] --> [工作台]
[重置] --> [单次 Reset Token] --> [修改密码] --> [撤销其他会话]
~~~

### 2.4 工作台 /workspace

~~~text
+------------------------------------------------------------------------------+
| 创作类型 [图片] [音频]                                                       |
| 模型档位 [基础] [高级] [旗舰]     分辨率 [低] [中] [高] [超高]               |
| 能力 [文生图] [图生图] [局部] [反推] [多角度] [抠图] [拆分]                  |
| 数量 [ 1 ]   预计消耗 [ ]   当前余额 [ ]          [开始任务] [进入画布]       |
| 参考图 [上传]   Mask [上传]   参数 [编辑]                                    |
+------------------------------------------------------------------------------+
~~~

~~~text
[目录 API] --> [公开产品/能力/分辨率/价格] --> [控件]
[控件] --> [参数校验] --> [POST /api/v1/tasks/*] --> [任务详情]
~~~

### 2.5 画布项目库 /canvas

~~~text
+------------------------------------------------------------------------------+
| 画布项目库                                      [新建] [导入] [导出] [删除]     |
+------------------------------------------------------------------------------+
| [搜索项目.................................................................]   |
| +------------------+ +------------------+ +------------------+               |
| | 缩略图/名称      | | 缩略图/名称      | | 缩略图/名称      |               |
| | 更新时间         | | 更新时间         | | 更新时间         |               |
| | [打开] [更多]    | | [打开] [更多]    | | [打开] [更多]    |               |
| +------------------+ +------------------+ +------------------+               |
+------------------------------------------------------------------------------+
~~~

~~~text
[新建] --> [本地 hydrated] --> [/canvas/:id]
[导入] --> [ZIP projects.json + files] --> [IndexedDB] --> [项目卡]
[导出] <-- [项目 + 媒体] <-- [IndexedDB]
[删除] --> [确认] --> [清理未引用媒体] --> [列表]
~~~

### 2.6 画布编辑器 /canvas/:id

~~~text
+------------------------------------------------------------------------------+
| < 返回 | 撤销/重做 | 缩放 | 小地图 | 保存/同步 | 任务状态 | 余额               |
+------------------------------------------------------------------------------+
| 节点面板       |                         无限画布                         | 信息 |
| [Text]         | [Text] ---> [Config] ---> [Image Batch]                  | 面板 |
| [Image]        |    |                    |                                  |      |
| [Audio]        | [Reference]          [Output]                              |      |
| [Config]       |                                                          ... |      |
| [Group]        |                                                          ... |      |
+------------------------------------------------------------------------------+
| 生成/编辑/反推/多角度/抠图/拆分/放大/扩图/保存资产/下载                        |
+------------------------------------------------------------------------------+
~~~

~~~text
[节点输入] --> [收集文字/图片/音频/mask 引用]
           --> [上传对象或使用 objectId]
           --> [估价 + 余额预扣]
           --> [任务队列] --> [事件/轮询]
           --> [结果节点] --> [资产] / [WebDAV] / [下一节点]
~~~

### 2.7 图片工具 /tools/image

~~~text
+------------------------------------------------------------------------------+
| [万能渲染] [局部编辑] [反推提示词] [多角度] [抠图] [智能拆分] [放大] [扩图]     |
+------------------------------------------------------------------------------+
| 输入参考图/提示词/mask | 模型/分辨率/数量/专属参数 | 结果预览/版本/下载/资产     |
+------------------------------------------------------------------------------+
~~~

~~~text
[图片工具] --> [capability + taskType] --> [任务详情]
            --> [image / mask / split manifest / prompt / angle group]
~~~

### 2.8 音频工具 /tools/audio

~~~text
+------------------------------------------------------------------------------+
| 文本 [.................................................................]     |
| voice [ ]  格式 [mp3/wav]  速度 [---]  instructions [..................]     |
| 预计消耗 [ ]  当前余额 [ ]                         [开始生成]                 |
| 状态 [排队/生成中/成功/失败] [播放] [下载] [插入画布]                         |
+------------------------------------------------------------------------------+
~~~

~~~text
[文本 + voice + format] --> [Audio Adapter] --> [音频对象]
                          --> [播放器] + [画布节点] + [WebDAV]
~~~

### 2.9 3D 契约预留 /tools/3d（V1 禁用）

~~~text
+------------------------------------------------------------------------------+
| 入口状态: [CAPABILITY_NOT_ENABLED]                                          |
| 三视图/自由视角的 V1 能力请使用图片工具；真正图生3D/文生3D暂不开放。          |
| adapter 预留: GLB/GLTF、OBJ、纹理、缩略图、导出和 Three.js/WebGL 视口          |
+------------------------------------------------------------------------------+
~~~

~~~text
[参考图/提示词] --> [3D task contract]
                 --> [CAPABILITY_NOT_ENABLED]
                 -. 后续启用 .-> [GLB/GLTF + texture + thumbnail]
~~~

### 2.10 任务历史 /tasks 和任务详情 /tasks/:id

~~~text
+------------------------------------------------------------------------------+
| 任务历史 [状态] [类型] [模型] [时间] [项目] [搜索任务 ID]                     |
+------------------------------------------------------------------------------+
| taskId | 类型 | 产品 | 状态 | 预扣/实扣 | 创建时间 | [详情] [重试] [取消]      |
+------------------------------------------------------------------------------+
| 任务详情: 输入摘要 | attempt 时间线 | 输出 | 计费 | 错误建议 | 保存/下载        |
+------------------------------------------------------------------------------+
~~~

~~~text
[任务列表] --> [GET /api/v1/tasks] --> [任务详情]
[详情] --> [事件流/轮询] --> [取消或重试] --> [输出签名 URL]
~~~

### 2.11 资产 /assets

~~~text
+------------------------------------------------------------------------------+
| 我的资产                    [新建] [导入] [导出] [筛选] [搜索]                |
+------------------------------------------------------------------------------+
| 类型 [全部/图片/文本/音频]  标签 [........]  (3D 资产 V1 仅预留)               |
| +----------------+ +----------------+ +----------------+                      |
| | 缩略图/标题    | | 缩略图/标题    | | 缩略图/标题    |                      |
| | 标签/来源      | | 标签/来源      | | 标签/来源      |                      |
| | [预览] [编辑]  | | [下载] [画布]  | | [删除]          |                      |
| +----------------+ +----------------+ +----------------+                      |
+------------------------------------------------------------------------------+
~~~

~~~text
[生成输出] --> [保存资产] --> [所有权校验] --> [Asset + outputId]
            --> [资产列表] --> [插入画布] / [签名下载] / [WebDAV]
~~~

### 2.12 账户/余额/WebDAV /account、/settings

~~~text
+------------------------------------------------------------------------------+
| 账户 [个人资料] [安全/会话] [余额与账单] [充值] [WebDAV]                      |
+------------------------------------------------------------------------------+
| 可用余额 [ ]  预扣余额 [ ]                              [充值]              |
| 流水: reserve | settle | release | refund | manual_adj                       |
| 套餐: [名称] [时长] [包含金币] [价格] [模型/能力] [购买]                    |
| WebDAV URL [脱敏] 状态 [已连接/失败] [测试] [同步] [冲突列表]                 |
+------------------------------------------------------------------------------+
~~~

~~~text
[充值] --> [recharge order] --> [签名 webhook] --> [payment_events] --> [账本]
[WebDAV] --> [加密凭证引用] --> [连接策略] --> [manifest/checksum]
         --> [上传/下载/冲突副本/离线重试]
~~~

### 2.13 用户错误页 /error

~~~text
+-----------------------------------------------+
| 401/403/404/429/500                            |
| 登录过期 / 无权限 / 页面不存在 / 系统繁忙      |
| [重新登录] [返回首页] [查看任务]               |
+-----------------------------------------------+
~~~

错误页只显示公共错误码和可执行建议，不显示 provider 地址、Key、原始模型 ID 或内部 attempt 细节。

## 3. 管理端 SSI（ASCII）

### 3.1 管理壳层

~~~text
+--------------------------------------------------------------------------------+
| 管理台 | 面包屑 | requestId | 告警 | 管理员 | 退出                              |
+--------------------------------------------------------------------------------+
| [总览] [用户] [认证消息] [渠道] [渠道组] [模型产品] [价格] [金币/换算]         |
| [套餐] [任务] [余额] [充值/支付] [存储] [审计] [管理员 MFA] [系统设置]         |
+--------------------------------------------------------------------------------+
| 内容区: 表格 / 表单 / 详情 / 时间线 / 审批                                     |
+--------------------------------------------------------------------------------+
~~~

~~~text
[Admin Browser] --> [Admin Session Guard] --> [RBAC + Object Scope] --> [Admin API]
                                                                    --> [Audit Log]
~~~

### 3.2 管理员登录 /admin/login、/admin/mfa

~~~text
+-----------------------------------------------+
| 元境幻生管理台                                 |
| 账号 [.................................]       |
| 密码 [.................................]       |
| [登录]                                         |
| MFA [........] [确认] | IP/设备策略            |
+-----------------------------------------------+
~~~

~~~text
[登录] --> [密码校验] --> [MFA/IP/设备策略] --> [admin audience session] --> [总览]
[管理员 MFA] --> [当前动态码 + 权限校验] --> [setup / verify / disable] --> [审计]
~~~

### 3.3 总览 /admin/dashboard

~~~text
+--------------------------------------------------------------------------------+
| 用户数 | 活跃数 | 余额总额 | 充值额 | 任务数 | 队列积压                        |
+--------------------------------------------------------------------------------+
| 模型成功率/P95       | 渠道组健康/熔断       | 邮件/SMS/支付告警                 |
| [图表]               | [图表]                | [事件列表]                        |
+--------------------------------------------------------------------------------+
~~~

### 3.4 用户/认证消息 /admin/users、/admin/auth-messages

~~~text
+--------------------------------------------------------------------------------+
| 用户 [搜索] [状态] [注册时间] [余额]                                           |
+--------------------------------------------------------------------------------+
| userId | 脱敏身份 | 状态 | 余额 | 额度 | 最近活动 | [详情] [冻结]              |
+--------------------------------------------------------------------------------+
| 详情: 身份/验证 | 会话设备 | 任务 | 消费 | WebDAV | 审计                       |
+--------------------------------------------------------------------------------+
| 认证消息: Provider | 模板 | 验证码策略 | Outbox | 成功率 | 重试                 |
+--------------------------------------------------------------------------------+
~~~

~~~text
[用户管理] --> [用户/会话/额度] --> [冻结/退出/重置/重发]
[消息管理] --> [Provider + Template] --> [Outbox] --> [邮件/SMS]
~~~

### 3.5 渠道/渠道组 /admin/channels、/admin/channel-groups

~~~text
+--------------------------------------------------------------------------------+
| 渠道 [新增] [测试] [启用/禁用] [轮换凭证]                                      |
+--------------------------------------------------------------------------------+
| channelId | 供应商 | capability | 状态 | 并发 | 失败/熔断 | 最近成功          |
+--------------------------------------------------------------------------------+
| 旗舰组 vN [编辑] [预览] [发布] [回滚]                                         |
| 1 -> channel A -> providerModel A                                             |
| 2 -> channel B -> providerModel B                                             |
| 3 -> channel C -> providerModel C                                             |
| retry budget | 熔断 | fallback | 公共错误文案                                |
+--------------------------------------------------------------------------------+
~~~

~~~text
[渠道] --> [加密凭证 + provider model] --> [探活]
      --> [显示模型 ID ↔ 供应商请求模型 ID 映射]
      --> [有序渠道组] --> [不可变路由版本] --> [新任务快照]
      --> [生成测试使用供应商请求模型 ID]
~~~

### 3.6 模型产品/价格 /admin/model-products、/admin/pricing

~~~text
+--------------------------------------------------------------------------------+
| 产品 [基础] [高级] [旗舰] [专项] [新增] [上架/下架]                            |
+--------------------------------------------------------------------------------+
| 产品 | 能力 | 渠道组 | 分辨率 | 数量上限 | 价格版本 | 状态                     |
+--------------------------------------------------------------------------------+
| 详情: 公开说明 | capability schema | 像素限制 | 价格 | 替代模型 | [发布/回滚]  |
+--------------------------------------------------------------------------------+
~~~

~~~text
[草稿] --> [能力/价格校验] --> [影响预览] --> [发布版本] --> [目录 API]
~~~

### 3.7 金币单位、换算和套餐 /admin/billing/units、/admin/plans

~~~text
+--------------------------------------------------------------------------------+
| 金币单位 [名称] [短代码] [图标] [精度] [显示小数位] [启用]                     |
| 换算规则 [支付货币] [金币比例] [舍入] [最低/最高充值] [生效版本]              |
+--------------------------------------------------------------------------------+
| 套餐 [新增] [复制] [上架/下架]                                                |
| 名称 | 时长 | 购买价格 | 包含金币 | 模型/渠道组权益 | 并发 | 队列优先级       |
| 介绍 | 保留上限 | 可延长/归档 | 生效版本 | [发布] [回滚]                    |
+--------------------------------------------------------------------------------+
~~~

~~~text
[金币单位/换算发布] --> [新充值订单快照]
[套餐发布] --> [购买订单 + 权益快照]
             --> [用户目录/账户] --> [并发与队列准入]
~~~

### 3.8 任务 /admin/tasks

~~~text
+--------------------------------------------------------------------------------+
| 任务 [用户] [状态] [模型] [时间] [requestId]                                   |
+--------------------------------------------------------------------------------+
| taskId | 用户 | 产品 | 状态 | 预扣/实扣 | 创建时间 | [详情]                  |
+--------------------------------------------------------------------------------+
| 详情: 快照 | attempt 时间线 | provider 状态 | 输出 | 账本 | 脱敏审计日志         |
| [取消] [重试] [标记异常]                                                       |
+--------------------------------------------------------------------------------+
~~~

### 3.9 余额/支付 /admin/balance、/admin/recharges、/admin/payments

~~~text
+--------------------------------------------------------------------------------+
| 账本: reserve | settle | release | refund | manual_adj                        |
| 不变量: available + reserved = confirmed balance                             |
| 调账: 申请人 -> 审批人 -> 执行人 | 原因 | 幂等键 | 审计                        |
+--------------------------------------------------------------------------------+
| 充值订单 | provider | 金额/币种 | 状态 | webhook | 对账 | 退款               |
+--------------------------------------------------------------------------------+
~~~

~~~text
[调账] --> [申请] --> [第二审批人] --> [账本事务] --> [审计]
[支付] --> [签名/订单金额校验] --> [唯一 eventId] --> [订单状态] --> [余额]
~~~

### 3.10 存储/设置/审计 /admin/storage、/admin/settings、/admin/audit、/admin/audit-logs

~~~text
+--------------------------------------------------------------------------------+
| 邮件/SMS | 目录 | 渠道健康 | 限流 | 对象存储 | WebDAV | TTL/GC | 安全         |
+--------------------------------------------------------------------------------+
| 审计 [管理员] [对象] [操作] [requestId] [时间] [导出]                         |
| 时间 | 操作者 | 动作 | 对象 | before/after 摘要 | IP | correlationId | 校验链  |
+--------------------------------------------------------------------------------+
~~~

## 4. 用户侧逻辑 Mermaid

~~~mermaid
flowchart TD
  HOME[首页 /]
  AUTH[认证 /auth/*]
  WORK[工作台 /workspace]
  CL[画布项目库 /canvas]
  CANVAS[画布 /canvas/:id]
  IMAGE[图片工具]
  AUDIO[音频工具]
  THREE[3D 契约预留<br/>V1 禁用]
  TASKS[任务历史 /tasks]
  ASSET[资产 /assets]
  ACCOUNT[账户与余额]
  PLANS[套餐购买 /account/plans]
  DAV[WebDAV 设置]
  ERROR[公共错误页]

  HOME -->|开始创作| WORK
  HOME -->|打开画布| CL
  HOME -->|登录注册| AUTH
  AUTH -->|会话成功| WORK
  WORK --> IMAGE
  WORK --> AUDIO
  WORK --> THREE
  WORK --> CL
  CL -->|打开项目| CANVAS
  IMAGE -->|提交 task| TASKS
  AUDIO -->|提交 task| TASKS
  THREE -.->|CAPABILITY_NOT_ENABLED| ERROR
  CANVAS -->|提交 task| TASKS
  TASKS -->|结果| ASSET
  TASKS -->|结果回写| CANVAS
  ASSET -->|插入| CANVAS
  ASSET -->|同步| DAV
  CANVAS -->|同步| DAV
  ACCOUNT -->|充值/账单| TASKS
  ACCOUNT --> PLANS
  PLANS -->|购买订单| TASKS
  WORK -.->|未登录或余额不足| AUTH
  IMAGE -.-> ERROR
  AUDIO -.-> ERROR
  THREE -.-> ERROR
~~~

## 5. 管理员侧逻辑 Mermaid

~~~mermaid
flowchart TD
  LOGIN[管理员登录]
  MFA[MFA/IP/设备策略]
  RBAC[RBAC 与对象范围]
  DASH[总览]
  USERS[用户与会话]
  MSG[邮件/SMS/验证码]
  CHANNELS[渠道]
  GROUPS[渠道组/健康]
  PRODUCTS[模型产品/分辨率]
  PRICE[价格版本]
  UNIT[金币单位/换算]
  PLANS[套餐与权益]
  TASKS[任务与 attempt]
  BALANCE[余额与人工调账]
  PAY[充值/支付/退款]
  STORAGE[存储/WebDAV/TTL]
  ADMIN_MFA[管理员 MFA 管理]
  AUDIT[审计]
  AUDIT_DASH[日志大板]
  AUDIT_LOGS[详细日志]
  API[Admin API]

  LOGIN --> MFA --> RBAC --> DASH
  DASH --> USERS
  DASH --> MSG
  DASH --> CHANNELS
  DASH --> GROUPS
  DASH --> PRODUCTS
  DASH --> PRICE
  DASH --> TASKS
  DASH --> BALANCE
  DASH --> PAY
  DASH --> STORAGE
  DASH --> ADMIN_MFA
  DASH --> AUDIT
  AUDIT --> AUDIT_DASH
  AUDIT --> AUDIT_LOGS
  USERS --> API
  MSG --> API
  CHANNELS --> API
  GROUPS --> API
  PRODUCTS --> API
  PRICE --> API
  UNIT --> API
  PLANS --> API
  TASKS --> API
  BALANCE -->|申请/审批/执行| API
  PAY --> API
  STORAGE --> API
  ADMIN_MFA --> API
  API -->|所有写操作| AUDIT
  GROUPS -->|路由版本| PRODUCTS
  PRODUCTS -->|目录/价格版本| TASKS
  RBAC -.->|拒绝越权| API
~~~

## 6. 系统请求逻辑 Mermaid

~~~mermaid
sequenceDiagram
  autonumber
  participant B as Browser
  participant G as API Gateway
  participant A as Auth/RBAC
  participant C as Catalog
  participant L as Balance Ledger
  participant Q as Queue/Worker
  participant R as Router
  participant P as Provider Adapter
  participant S as Object Storage
  participant E as Task Events

  B->>G: POST task + Access Token + Idempotency-Key
  G->>A: token/account/scope
  A-->>G: user identity
  G->>C: resolve product/resolution/capability
  C-->>G: catalog/price/route snapshot
  G->>G: validate inputs, ownership, MIME, scan
  G->>L: reserve expected amount
  L-->>G: available/reserved updated
  G->>Q: enqueue task with snapshot and lease
  G-->>B: taskId + queued + expected charge
  Q->>R: resolve ordered channels
  R->>P: attempt #1 + provider request ID
  P-->>R: success/retryable/permanent/unknown
  alt success
    R->>S: store normalized outputs
    R->>L: settle per successful output
    R->>E: succeeded/partial
  else retryable
    R->>R: backoff + budget + breaker
    R->>P: next channel attempt
  else unknown
    R->>P: query/reconcile provider request ID
    P-->>R: confirmed result/failure
    R->>L: settle or release exactly once
  else permanent
    R->>L: release unused reserve
    R->>E: failed + public error
  end
  E-->>B: WebSocket event with sequence/cursor
  B->>G: HTTP polling fallback after WS disconnect
~~~

~~~mermaid
flowchart LR
  U[用户] --> AUTH[Auth API]
  AUTH --> CODE[验证码哈希/限流]
  CODE --> OUTBOX[Message Outbox]
  OUTBOX --> MAIL[邮件适配器]
  OUTBOX --> SMS[短信适配器]
  U --> ORDER[充值订单]
  ORDER --> PAYMENT[Payment Adapter]
  PAYMENT --> WEBHOOK[签名 Webhook]
  WEBHOOK --> EVENTS[唯一 eventId]
  EVENTS --> LEDGER[Balance Ledger]
~~~

~~~mermaid
sequenceDiagram
  participant U as User Browser
  participant API as Platform API
  participant DAV as WebDAV Adapter
  participant W as User WebDAV
  participant DB as Manifest/Metadata

  U->>API: PUT /me/webdav
  API->>DAV: HTTPS/allowlist/private-network validation
  DAV->>W: PROPFIND connection test
  W-->>DAV: status
  DAV-->>API: redacted status
  U->>API: POST /me/webdav/sync
  API->>DB: load manifest cursor
  API->>DAV: merge remote manifest/checksums
  DAV->>W: GET/PUT user namespace files
  W-->>DAV: files/conflicts
  DAV-->>API: merge result/conflict copies
  API->>DB: persist cursor and status
  API-->>U: progress/result
~~~

## 7. 系统总览架构 Mermaid

~~~mermaid
flowchart TB
  subgraph Clients[客户端]
    WEB[用户前台 Vite/React]
    ADMIN[管理台 TDesign React]
    CANVAS[DOM/SVG Canvas + future Three.js]
  end

  subgraph Edge[统一 Origin]
    PROXY[Reverse Proxy]
    STATIC[Static / and /admin/]
    API[API Gateway /api/v1]
    EVENTS[WebSocket /ws task events]
  end

  subgraph Domain[服务端领域]
    AUTH[User/Admin Auth + RBAC]
    CATALOG[Catalog + Pricing]
    TASK[Task API + State Machine]
    ROUTER[Channel Router + Circuit Breaker]
    ADAPTER[Provider Adapters]
    LEDGER[Balance Ledger + Recharge]
    MESSAGE[Email/SMS Outbox]
    ASSET[Upload/Object/Asset]
    DAV[WebDAV Sync]
    AUDIT[Audit + Correlation]
  end

  subgraph Infra[基础设施]
    PG[(PostgreSQL)]
    REDIS[(Redis Queue/Locks)]
    STAGING[(Isolated local staging<br/>TTL/GC)]
    OBJECT[(Optional S3 Object Storage<br/>V1 adapter off)]
    PROVIDERS[Image/Text/Audio Providers]
    FUTURE3D[Future 3D Provider Adapter]
    MAIL[Email Provider]
    SMS[SMS Provider]
    PAY[Payment Provider]
    USERDAV[Per-user WebDAV]
    KMS[KMS/Secret Store]
  end

  WEB --> PROXY
  ADMIN --> PROXY
  CANVAS --> WEB
  PROXY --> STATIC
  PROXY --> API
  PROXY --> EVENTS
  API --> AUTH
  API --> CATALOG
  API --> TASK
  API --> LEDGER
  API --> ASSET
  API --> DAV
  API --> AUDIT
  EVENTS --> TASK
  TASK --> REDIS
  TASK --> ROUTER
  TASK --> ASSET
  TASK --> LEDGER
  ROUTER --> ADAPTER
  ADAPTER --> PROVIDERS
  ADAPTER -. V1 disabled .-> FUTURE3D
  AUTH --> PG
  AUTH --> KMS
  CATALOG --> PG
  TASK --> PG
  LEDGER --> PG
  LEDGER --> PAY
  MESSAGE --> PG
  MESSAGE --> MAIL
  MESSAGE --> SMS
  ASSET --> OBJECT
  ASSET --> STAGING
  DAV --> USERDAV
  DAV --> KMS
  AUDIT --> PG
~~~

## 8. 数据关系 Mermaid

~~~mermaid
erDiagram
  USERS ||--o{ SESSIONS : owns
  USERS ||--o{ GENERATION_TASKS : submits
  USERS ||--|| BALANCE_ACCOUNTS : has
  USERS ||--o{ UPLOAD_OBJECTS : uploads
  USERS ||--o{ ASSETS : owns
  MODEL_PRODUCTS }o--|| CHANNEL_GROUPS : routes_to
  MEMBERSHIP_PLANS ||--o{ PLAN_PURCHASES : sold_as
  USERS ||--o{ PLAN_PURCHASES : buys
  CHANNEL_GROUPS ||--o{ CHANNEL_BINDINGS : contains
  PROVIDER_CHANNELS ||--o{ CHANNEL_BINDINGS : binds
  GENERATION_TASKS ||--o{ GENERATION_ATTEMPTS : tries
  GENERATION_TASKS ||--o{ GENERATION_OUTPUTS : produces
  BALANCE_ACCOUNTS ||--o{ BALANCE_LEDGER : records
  BALANCE_UNITS ||--o{ BALANCE_CONVERSION_RULES : defines
  BALANCE_UNITS ||--o{ BALANCE_LEDGER : denominates
  BALANCE_CONVERSION_RULES ||--o{ RECHARGE_ORDERS : snapshots
  RECHARGE_ORDERS ||--o{ PAYMENT_EVENTS : receives
  USERS ||--o{ RECHARGE_ORDERS : creates
  USERS ||--o{ WEBDAV_CONNECTIONS : configures

  USERS {
    uuid id PK
    string status
    datetime created_at
  }
  SESSIONS {
    uuid id PK
    uuid user_id FK
    string audience
    string refresh_hash
    datetime expires_at
    datetime revoked_at
  }
  MODEL_PRODUCTS {
    uuid id PK
    string public_code
    string tier
    int version
    string status
  }
  CHANNEL_GROUPS {
    uuid id PK
    int published_version
    string circuit_state
  }
  CHANNEL_BINDINGS {
    uuid id PK
    uuid group_id FK
    uuid channel_id FK
    int priority
    string provider_model_id
  }
  GENERATION_TASKS {
    uuid id PK
    uuid user_id FK
    uuid product_id FK
    string status
    string idempotency_key
    decimal reserved_amount
    int snapshot_version
  }
  GENERATION_ATTEMPTS {
    uuid id PK
    uuid task_id FK
    string status
    string provider_request_id
    string error_class
  }
  BALANCE_ACCOUNTS {
    uuid id PK
    uuid user_id FK
    decimal available
    decimal reserved
    int version
  }
  BALANCE_LEDGER {
    uuid id PK
    uuid account_id FK
    string type
    decimal amount
    string idempotency_key
  }
  BALANCE_UNITS {
    uuid id PK
    string code
    string display_name
    string icon_key
    int scale
  }
  BALANCE_CONVERSION_RULES {
    uuid id PK
    uuid unit_id FK
    string payment_currency
    decimal rate
    int version
  }
  PROVIDER_CHANNELS {
    uuid id PK
    string provider
    string status
  }
  UPLOAD_OBJECTS {
    uuid id PK
    uuid owner_id FK
    string mime
    string scan_status
  }
  ASSETS {
    uuid id PK
    uuid owner_id FK
    string kind
    string object_id
  }
  GENERATION_OUTPUTS {
    uuid id PK
    uuid task_id FK
    string object_id
    decimal charged_amount
  }
  RECHARGE_ORDERS {
    uuid id PK
    uuid user_id FK
    decimal amount
    string status
  }
  PAYMENT_EVENTS {
    uuid id PK
    uuid order_id FK
    string provider_event_id
    string status
  }
  WEBDAV_CONNECTIONS {
    uuid id PK
    uuid user_id FK
    string base_url_redacted
    string status
  }
  MEMBERSHIP_PLANS {
    uuid id PK
    string public_code
    decimal purchase_amount
    decimal included_balance
    int duration_days
    string status
  }
  PLAN_PURCHASES {
    uuid id PK
    uuid user_id FK
    uuid plan_id FK
    decimal granted_balance
    datetime expires_at
    string status
  }
~~~

## 9. 页面与请求对照

| 页面 | 主要读取 | 主要写入/异步 | 用户可见错误 |
| --- | --- | --- | --- |
| 首页 | 公开能力和目录摘要 | 无 | 公共服务错误 |
| 认证 | 会话和账户状态 | 注册、验证、登录、刷新、重置 | 验证码失效、冻结、限流 |
| 工作台 | 目录、余额、上传限制 | 任务提交 | 参数错误、余额不足、模型不可用 |
| 画布 | 本地项目、任务、资产、同步 | 任务、保存资产、WebDAV | 公共错误码和任务建议 |
| 图片/音频/多视图 | 目录、余额、上传对象 | 对应 taskType | 任务失败和重试建议 |
| 任务详情 | 快照、事件、输出、账单 | 取消、重试、保存资产 | 不展示 provider attempt |
| 资产 | 资产列表、下载授权 | 新建、编辑、删除、同步 | 过期、无权限、扫描失败 |
| 账户/余额 | 账户、账本、充值订单 | 充值订单、会话撤销 | 支付待确认、余额不足 |
| WebDAV | 连接和 manifest | 测试、同步、冲突处理 | 连接失败、冲突副本 |
| 管理后台 | 列表、指标、审计 | 配置发布、审批、调账、重试 | 权限不足、版本冲突、需审批 |

## 10. 图示维护规则

- 新增页面时，同时更新 1.1/1.2 页面清单、对应 ASCII 页面图和至少一张相关 Mermaid 图。
- 新增 API、任务状态或账本状态时，同时更新第 6、7、8 节，保证请求链路、架构节点和数据关系一致。
- 本文的页面范围必须与 develop.md 第 1、2、5、6、9 节保持一致；不开发的视频、动画、3D 生成、Local Agent、远程 Prompt、插件市场等功能不得重新出现在用户导航。
- 一期固定使用本地画布/资产 + WebDAV；云端项目 CRUD 不进入 V1，仅保留 develop.md 中的团队/云端扩展预留契约。

## 11. 管理台重构图示索引

管理台一级/二级菜单、权限分组、每个页面的强交互 ASCII（SSII）线框、渠道→分组→模型产品→价格规则流程、版本冲突状态机和逐页验收清单，统一维护在 [`admin-plan.md`](./admin-plan.md)。

当前管理台重构约束：

- 左侧菜单必须使用一级分组 + 二级页面，不再把全部业务页面平铺成单层菜单。
- 消息供应商、消息模板本期不进入可见菜单；认证消息只展示 outbox 状态和多行内容详情。
- 新增/编辑渠道、分组、模型产品、用户、价格规则、套餐等都从按钮打开弹窗或抽屉，首屏不铺开全部配置字段。
- 403/404 必须渲染可恢复页面，不允许白板；权限过滤和后端 scope 必须一致。