36 KiB
36 KiB
元境幻生系统图示
本文覆盖一期用户端、管理端、系统请求链路和整体架构。
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 全局壳层
+--------------------------------------------------------------------------------+
| 元境幻生 | 首页 | 工作台 | 画布 | 资产 | 任务 | 余额 | 账户 | 主题/语言 |
+--------------------------------------------------------------------------------+
| 当前页面内容 |
+--------------------------------------------------------------------------------+
| Toast | 任务事件 | 登录过期 | 模型不可用 | 余额不足 |
+--------------------------------------------------------------------------------+
[Browser]
+--> [UserLayout]
| +--> [AuthGuard for billable routes]
| +--> [CatalogStore] [BalanceStore] [TaskEventClient]
| +--> [WebDAVSyncClient]
+--> [Public Home]
2.2 首页 /
+------------------------------------------------------------------------------+
| 元境幻生 |
| 游戏美术 / 艺术资产 / 多视图工作流 |
| |
| [开始创作] [打开画布] [查看资产] [登录/注册] |
| |
| [万能渲染] [游戏资产] [反推/多角度] [音频] |
+------------------------------------------------------------------------------+
[首页] --> [工作台/模型目录]
+--> [认证页]
+--> [/canvas]
+--> [/assets]
2.3 认证 /auth/*
+-----------------------------------------------+
| 元境幻生 | 登录 / 注册 / 验证 / 重置密码 |
+-----------------------------------------------+
| 邮箱或手机号 [.........................] |
| 密码/验证码 [.........................] |
| 人机挑战 [ 7 + 5 = ? ] [.............] |
| [发送验证码] [登录] [注册] |
| 忘记密码 | 重新发送验证 | 返回首页 |
+-----------------------------------------------+
[注册] --> [规范化身份] --> [人机挑战（IP/设备/目标绑定）] --> [验证码 Outbox] --> [一次性验证] --> [建立会话]
[登录] --> [人机挑战] --> [Access Token 内存 + HttpOnly Refresh Cookie] --> [工作台]
[重置] --> [单次 Reset Token] --> [修改密码] --> [撤销其他会话]
2.4 工作台 /workspace
+------------------------------------------------------------------------------+
| 创作类型 [图片] [音频] |
| 模型档位 [基础] [高级] [旗舰] 分辨率 [低] [中] [高] [超高] |
| 能力 [文生图] [图生图] [局部] [反推] [多角度] [抠图] [拆分] |
| 数量 [ 1 ] 预计消耗 [ ] 当前余额 [ ] [开始任务] [进入画布] |
| 参考图 [上传] Mask [上传] 参数 [编辑] |
+------------------------------------------------------------------------------+
[目录 API] --> [公开产品/能力/分辨率/价格] --> [控件]
[控件] --> [参数校验] --> [POST /api/v1/tasks/*] --> [任务详情]
2.5 画布项目库 /canvas
+------------------------------------------------------------------------------+
| 画布项目库 [新建] [导入] [导出] [删除] |
+------------------------------------------------------------------------------+
| [搜索项目.................................................................] |
| +------------------+ +------------------+ +------------------+ |
| | 缩略图/名称 | | 缩略图/名称 | | 缩略图/名称 | |
| | 更新时间 | | 更新时间 | | 更新时间 | |
| | [打开] [更多] | | [打开] [更多] | | [打开] [更多] | |
| +------------------+ +------------------+ +------------------+ |
+------------------------------------------------------------------------------+
[新建] --> [本地 hydrated] --> [/canvas/:id]
[导入] --> [ZIP projects.json + files] --> [IndexedDB] --> [项目卡]
[导出] <-- [项目 + 媒体] <-- [IndexedDB]
[删除] --> [确认] --> [清理未引用媒体] --> [列表]
2.6 画布编辑器 /canvas/:id
+------------------------------------------------------------------------------+
| < 返回 | 撤销/重做 | 缩放 | 小地图 | 保存/同步 | 任务状态 | 余额 |
+------------------------------------------------------------------------------+
| 节点面板 | 无限画布 | 信息 |
| [Text] | [Text] ---> [Config] ---> [Image Batch] | 面板 |
| [Image] | | | | |
| [Audio] | [Reference] [Output] | |
| [Config] | ... | |
| [Group] | ... | |
+------------------------------------------------------------------------------+
| 生成/编辑/反推/多角度/抠图/拆分/放大/扩图/保存资产/下载 |
+------------------------------------------------------------------------------+
[节点输入] --> [收集文字/图片/音频/mask 引用]
--> [上传对象或使用 objectId]
--> [估价 + 余额预扣]
--> [任务队列] --> [事件/轮询]
--> [结果节点] --> [资产] / [WebDAV] / [下一节点]
2.7 图片工具 /tools/image
+------------------------------------------------------------------------------+
| [万能渲染] [局部编辑] [反推提示词] [多角度] [抠图] [智能拆分] [放大] [扩图] |
+------------------------------------------------------------------------------+
| 输入参考图/提示词/mask | 模型/分辨率/数量/专属参数 | 结果预览/版本/下载/资产 |
+------------------------------------------------------------------------------+
[图片工具] --> [capability + taskType] --> [任务详情]
--> [image / mask / split manifest / prompt / angle group]
2.8 音频工具 /tools/audio
+------------------------------------------------------------------------------+
| 文本 [.................................................................] |
| voice [ ] 格式 [mp3/wav] 速度 [---] instructions [..................] |
| 预计消耗 [ ] 当前余额 [ ] [开始生成] |
| 状态 [排队/生成中/成功/失败] [播放] [下载] [插入画布] |
+------------------------------------------------------------------------------+
[文本 + voice + format] --> [Audio Adapter] --> [音频对象]
--> [播放器] + [画布节点] + [WebDAV]
2.9 3D 契约预留 /tools/3d（V1 禁用）
+------------------------------------------------------------------------------+
| 入口状态: [CAPABILITY_NOT_ENABLED] |
| 三视图/自由视角的 V1 能力请使用图片工具；真正图生3D/文生3D暂不开放。 |
| adapter 预留: GLB/GLTF、OBJ、纹理、缩略图、导出和 Three.js/WebGL 视口 |
+------------------------------------------------------------------------------+
[参考图/提示词] --> [3D task contract]
--> [CAPABILITY_NOT_ENABLED]
-. 后续启用 .-> [GLB/GLTF + texture + thumbnail]
2.10 任务历史 /tasks 和任务详情 /tasks/:id
+------------------------------------------------------------------------------+
| 任务历史 [状态] [类型] [模型] [时间] [项目] [搜索任务 ID] |
+------------------------------------------------------------------------------+
| taskId | 类型 | 产品 | 状态 | 预扣/实扣 | 创建时间 | [详情] [重试] [取消] |
+------------------------------------------------------------------------------+
| 任务详情: 输入摘要 | attempt 时间线 | 输出 | 计费 | 错误建议 | 保存/下载 |
+------------------------------------------------------------------------------+
[任务列表] --> [GET /api/v1/tasks] --> [任务详情]
[详情] --> [事件流/轮询] --> [取消或重试] --> [输出签名 URL]
2.11 资产 /assets
+------------------------------------------------------------------------------+
| 我的资产 [新建] [导入] [导出] [筛选] [搜索] |
+------------------------------------------------------------------------------+
| 类型 [全部/图片/文本/音频] 标签 [........] (3D 资产 V1 仅预留) |
| +----------------+ +----------------+ +----------------+ |
| | 缩略图/标题 | | 缩略图/标题 | | 缩略图/标题 | |
| | 标签/来源 | | 标签/来源 | | 标签/来源 | |
| | [预览] [编辑] | | [下载] [画布] | | [删除] | |
| +----------------+ +----------------+ +----------------+ |
+------------------------------------------------------------------------------+
[生成输出] --> [保存资产] --> [所有权校验] --> [Asset + outputId]
--> [资产列表] --> [插入画布] / [签名下载] / [WebDAV]
2.12 账户/余额/WebDAV /account、/settings
+------------------------------------------------------------------------------+
| 账户 [个人资料] [安全/会话] [余额与账单] [充值] [WebDAV] |
+------------------------------------------------------------------------------+
| 可用余额 [ ] 预扣余额 [ ] [充值] |
| 流水: reserve | settle | release | refund | manual_adj |
| 套餐: [名称] [时长] [包含金币] [价格] [模型/能力] [购买] |
| WebDAV URL [脱敏] 状态 [已连接/失败] [测试] [同步] [冲突列表] |
+------------------------------------------------------------------------------+
[充值] --> [recharge order] --> [签名 webhook] --> [payment_events] --> [账本]
[WebDAV] --> [加密凭证引用] --> [连接策略] --> [manifest/checksum]
--> [上传/下载/冲突副本/离线重试]
2.13 用户错误页 /error
+-----------------------------------------------+
| 401/403/404/429/500 |
| 登录过期 / 无权限 / 页面不存在 / 系统繁忙 |
| [重新登录] [返回首页] [查看任务] |
+-----------------------------------------------+
错误页只显示公共错误码和可执行建议，不显示 provider 地址、Key、原始模型 ID 或内部 attempt 细节。
3. 管理端 SSI（ASCII）
3.1 管理壳层
+--------------------------------------------------------------------------------+
| 管理台 | 面包屑 | requestId | 告警 | 管理员 | 退出 |
+--------------------------------------------------------------------------------+
| [总览] [用户] [认证消息] [渠道] [渠道组] [模型产品] [价格] [金币/换算] |
| [套餐] [任务] [余额] [充值/支付] [存储] [审计] [管理员 MFA] [系统设置] |
+--------------------------------------------------------------------------------+
| 内容区: 表格 / 表单 / 详情 / 时间线 / 审批 |
+--------------------------------------------------------------------------------+
[Admin Browser] --> [Admin Session Guard] --> [RBAC + Object Scope] --> [Admin API]
--> [Audit Log]
3.2 管理员登录 /admin/login、/admin/mfa
+-----------------------------------------------+
| 元境幻生管理台 |
| 账号 [.................................] |
| 密码 [.................................] |
| [登录] |
| MFA [........] [确认] | IP/设备策略 |
+-----------------------------------------------+
[登录] --> [密码校验] --> [MFA/IP/设备策略] --> [admin audience session] --> [总览]
[管理员 MFA] --> [当前动态码 + 权限校验] --> [setup / verify / disable] --> [审计]
3.3 总览 /admin/dashboard
+--------------------------------------------------------------------------------+
| 用户数 | 活跃数 | 余额总额 | 充值额 | 任务数 | 队列积压 |
+--------------------------------------------------------------------------------+
| 模型成功率/P95 | 渠道组健康/熔断 | 邮件/SMS/支付告警 |
| [图表] | [图表] | [事件列表] |
+--------------------------------------------------------------------------------+
3.4 用户/认证消息 /admin/users、/admin/auth-messages
+--------------------------------------------------------------------------------+
| 用户 [搜索] [状态] [注册时间] [余额] |
+--------------------------------------------------------------------------------+
| userId | 脱敏身份 | 状态 | 余额 | 额度 | 最近活动 | [详情] [冻结] |
+--------------------------------------------------------------------------------+
| 详情: 身份/验证 | 会话设备 | 任务 | 消费 | WebDAV | 审计 |
+--------------------------------------------------------------------------------+
| 认证消息: Provider | 模板 | 验证码策略 | Outbox | 成功率 | 重试 |
+--------------------------------------------------------------------------------+
[用户管理] --> [用户/会话/额度] --> [冻结/退出/重置/重发]
[消息管理] --> [Provider + Template] --> [Outbox] --> [邮件/SMS]
3.5 渠道/渠道组 /admin/channels、/admin/channel-groups
+--------------------------------------------------------------------------------+
| 渠道 [新增] [测试] [启用/禁用] [轮换凭证] |
+--------------------------------------------------------------------------------+
| channelId | 供应商 | capability | 状态 | 并发 | 失败/熔断 | 最近成功 |
+--------------------------------------------------------------------------------+
| 旗舰组 vN [编辑] [预览] [发布] [回滚] |
| 1 -> channel A -> providerModel A |
| 2 -> channel B -> providerModel B |
| 3 -> channel C -> providerModel C |
| retry budget | 熔断 | fallback | 公共错误文案 |
+--------------------------------------------------------------------------------+
[渠道] --> [加密凭证 + provider model] --> [探活]
--> [显示模型 ID ↔ 供应商请求模型 ID 映射]
--> [有序渠道组] --> [不可变路由版本] --> [新任务快照]
--> [生成测试使用供应商请求模型 ID]
3.6 模型产品/价格 /admin/model-products、/admin/pricing
+--------------------------------------------------------------------------------+
| 产品 [基础] [高级] [旗舰] [专项] [新增] [上架/下架] |
+--------------------------------------------------------------------------------+
| 产品 | 能力 | 渠道组 | 分辨率 | 数量上限 | 价格版本 | 状态 |
+--------------------------------------------------------------------------------+
| 详情: 公开说明 | capability schema | 像素限制 | 价格 | 替代模型 | [发布/回滚] |
+--------------------------------------------------------------------------------+
[草稿] --> [能力/价格校验] --> [影响预览] --> [发布版本] --> [目录 API]
3.7 金币单位、换算和套餐 /admin/billing/units、/admin/plans
+--------------------------------------------------------------------------------+
| 金币单位 [名称] [短代码] [图标] [精度] [显示小数位] [启用] |
| 换算规则 [支付货币] [金币比例] [舍入] [最低/最高充值] [生效版本] |
+--------------------------------------------------------------------------------+
| 套餐 [新增] [复制] [上架/下架] |
| 名称 | 时长 | 购买价格 | 包含金币 | 模型/渠道组权益 | 并发 | 队列优先级 |
| 介绍 | 保留上限 | 可延长/归档 | 生效版本 | [发布] [回滚] |
+--------------------------------------------------------------------------------+
[金币单位/换算发布] --> [新充值订单快照]
[套餐发布] --> [购买订单 + 权益快照]
--> [用户目录/账户] --> [并发与队列准入]
3.8 任务 /admin/tasks
+--------------------------------------------------------------------------------+
| 任务 [用户] [状态] [模型] [时间] [requestId] |
+--------------------------------------------------------------------------------+
| taskId | 用户 | 产品 | 状态 | 预扣/实扣 | 创建时间 | [详情] |
+--------------------------------------------------------------------------------+
| 详情: 快照 | attempt 时间线 | provider 状态 | 输出 | 账本 | 脱敏审计日志 |
| [取消] [重试] [标记异常] |
+--------------------------------------------------------------------------------+
3.9 余额/支付 /admin/balance、/admin/recharges、/admin/payments
+--------------------------------------------------------------------------------+
| 账本: reserve | settle | release | refund | manual_adj |
| 不变量: available + reserved = confirmed balance |
| 调账: 申请人 -> 审批人 -> 执行人 | 原因 | 幂等键 | 审计 |
+--------------------------------------------------------------------------------+
| 充值订单 | provider | 金额/币种 | 状态 | webhook | 对账 | 退款 |
+--------------------------------------------------------------------------------+
[调账] --> [申请] --> [第二审批人] --> [账本事务] --> [审计]
[支付] --> [签名/订单金额校验] --> [唯一 eventId] --> [订单状态] --> [余额]
3.10 存储/设置/审计 /admin/storage、/admin/settings、/admin/audit、/admin/audit-logs
+--------------------------------------------------------------------------------+
| 邮件/SMS | 目录 | 渠道健康 | 限流 | 对象存储 | WebDAV | TTL/GC | 安全 |
+--------------------------------------------------------------------------------+
| 审计 [管理员] [对象] [操作] [requestId] [时间] [导出] |
| 时间 | 操作者 | 动作 | 对象 | before/after 摘要 | IP | correlationId | 校验链 |
+--------------------------------------------------------------------------------+
4. 用户侧逻辑 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
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
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
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]
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
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
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。
当前管理台重构约束：
- 左侧菜单必须使用一级分组 + 二级页面，不再把全部业务页面平铺成单层菜单。
- 消息供应商、消息模板本期不进入可见菜单；认证消息只展示 outbox 状态和多行内容详情。
- 新增/编辑渠道、分组、模型产品、用户、价格规则、套餐等都从按钮打开弹窗或抽屉，首屏不铺开全部配置字段。
- 403/404 必须渲染可恢复页面，不允许白板；权限过滤和后端 scope 必须一致。