# MiragenFlow 架构分析

## 1. 系统定位

MiragenFlow 是一个本地优先的 AI 创作工作台，并在服务端提供统一的任务网关、计费、渠道路由和管理能力。

- 用户端负责画布编排、图片/文本/音频创作、任务查看、资产管理和 WebDAV 同步。
- 管理台负责用户、渠道、模型产品、套餐、计费、审批、任务、存储、指标和审计。
- 服务端负责认证、目录、任务、余额、队列、供应商调用、对象落地、事件和后台作业。
- `packages/contracts` 维护浏览器和服务端共享的会话、任务、事件、上传对象等 TypeScript 合约。

当前系统不是“浏览器直接持有供应商 Key”的纯前端工具：计费任务默认通过 `/api/v1` 服务端网关执行。另一方面，画布项目和“我的资产”仍主要保存在浏览器本地，WebDAV 是可选同步层，不是平台自带云端项目库。

## 2. 运行时边界

```text
用户端 web/ ─┐
             ├─ shared contracts ─> server HTTP /api/v1
管理台 admin/ ┘                         │
                                       ├─ Auth / CSRF / MFA / Scope
                                       ├─ Store + PersistenceRepository
                                       ├─ Task Dispatch Outbox + Queue
                                       ├─ Task Worker + Provider Adapter
                                       ├─ Staging / Object / Asset
                                       ├─ Task WebSocket Events
                                       └─ Message / WebDAV / GC / Reconcile Workers
```

服务端启动时加载配置、迁移和持久化状态，恢复任务租约、消息 outbox、WebDAV 作业和排队任务，再启动 HTTP、任务 WebSocket 及周期性恢复/GC 作业。证据入口：`server/src/index.ts:13`。

## 3. 用户端架构

### 3.1 页面和启动

- `web/src/main.tsx:1` 组合 `AppProviders` 与 `RouterProvider`。
- `web/src/router.tsx:29` 集中注册公开页面、认证页面和受保护工作台路由。
- `AuthGuard` 在认证 store 完成 hydrate 前保持加载态，未登录则跳到登录页并保留 redirect。
- `ClientRootInit` 启动时并行恢复会话并加载公开模型目录。

### 3.2 状态与本地持久化

- `useAuthStore` 管理内存 access token、用户、余额、MFA challenge 和 refresh 恢复。
- `useCatalogStore` 缓存 `/api/v1/catalog/models` 的公开模型目录。
- `useCanvasStore` 通过 localForage 持久化项目，约 400ms 防抖写入。
- `useAssetStore` 持久化文本、图片和音频资产，并在删除时清理无引用媒体。
- `local-data-namespace` 以用户 ID 或 anonymous 区分本地命名空间，并用 epoch 防止切换竞态。

因此账号登录和服务端任务是云端边界，画布及本地资产不是。清理站点数据仍可能丢失未同步的本地内容。

### 3.3 API 与任务体验

`web/src/services/api/platform.ts:81` 是统一请求边界：

- 同源 `/api/v1` 请求带 `credentials: include`。
- access token 只放内存并以 Bearer 发送。
- Cookie 会话存在时，写请求附带 CSRF token。
- 401 时只刷新一次，失败后触发统一会话过期处理。

任务创建链路位于同文件 `runPlatformTask`：创建任务后优先订阅 `/api/v1/ws/tasks`；WebSocket 失败时以 250ms 轮询任务详情。任务页另以 5 秒可见刷新维护列表。

### 3.4 上传、对象和 WebDAV

- 小于等于 50MB 的图片可走 multipart；其他对象走预签名/complete 链路。
- 任务结果通过带认证的 `/api/v1/objects/*` 读取。
- `app-sync.ts` 在画布/资产 hydration 后合并远端 manifest，补齐媒体并上传变化。
- WebDAV 同步是用户主动配置的跨设备同步，不是多人协作或实时云存储。

## 4. 管理台架构

### 4.1 入口、状态和路由

- `admin/src/main.tsx:3` 组合 Redux `Provider`、BrowserRouter 和应用入口。
- Redux 只维护 `global` 与 `user` 两个 slice；业务列表不进入大型全局 store。
- `admin/src/router/index.ts:36` 为路由声明 `requiredScope`。
- 用户安全、财务、审计等页面分别需要 `admin:security`、`admin:finance`、`admin:audit`；其他页面默认 `admin:read`。
- `PermissionGate` 读取角色和 scope，`super_admin` 直接通过，其余不足权限时进入 `/403`。

### 4.2 请求与业务页

`admin/src/services/platform.ts:65` 的 `adminRequest` 统一处理：

- Bearer access token、管理员 CSRF Cookie、`credentials: include`。
- 非 GET 请求自动生成 Idempotency-Key。
- 401 只触发一次并发去重的 refresh。
- 错误对象保留 status、code、details 和 requestId。

当前大多数业务路由懒加载 `admin/src/pages/Business/index.tsx`。该页面根据 section 映射读取 `/api/v1/admin/*`，写操作统一处理 `If-Match`、幂等、刷新列表及 409/422/503。

管理台的“实时指标”并非 WebSocket 客户端：页面每 10 秒 GET `/api/v1/admin/ws/metrics`，服务端即时聚合订阅数、队列和事件积压。审计大板和详细日志都读取 `/api/v1/admin/audit-logs`。

## 5. HTTP、安全与权限

HTTP 入口在 `server/src/app/http.ts:1174`：

- 每个请求分配 requestId，并统一处理 CORS、body limit、健康和就绪检查。
- `/api/v1` 写请求先经过 CSRF 检查；纯 Bearer 且没有 refresh Cookie 的请求不强制双重提交。认证引导端点可以恢复缺少 CSRF Cookie 的旧 refresh 会话并补发缺失 Cookie，普通业务写请求仍受双提交保护。
- 用户 token 需要校验 JWT、session family、撤销状态和账号状态。
- 管理 token 使用独立 audience、角色和 scopes。
- 管理资源 scope 由 `adminRequiredScope` 统一映射，不依赖前端菜单作为安全边界。
- 非读取管理请求必须带合法 Idempotency-Key，并以 body fingerprint 防止同键异体重放。

密码使用 scrypt；JWT 使用 HS256 并包含 aud、scope、jti、sid、roles/scopes 等声明。登录策略还支持 CAPTCHA、TOTP 和 recovery code。

生产配置会强制检查 JWT secret、管理员密码、渠道加密密钥、PostgreSQL 和 Redis 配置；本地开发允许 memory/file persistence 与 memory queue。

## 6. 任务主链

### 6.1 创建与预留

`server/src/app/http.ts:751` 的任务创建先完成：

1. 校验公开模型、能力、输入引用、mask、数量、分辨率和参数。
2. 解析产品、价格、渠道组和套餐权益快照。
3. 计算预计金币并检查并发限制。
4. 在账本中把 available 移到 reserved。
5. 原子写入 task、幂等记录、task event、dispatch outbox 和队列信息。
6. 返回 `202` 与公开任务投影。

### 6.2 队列和租约

`server/src/infra/queue.ts` 定义统一队列接口。开发可使用内存队列；生产 Redis 适配器使用 sorted set、hash 和 Lua 原子 claim/renew/nack，并维护 dead-letter 集合。

PostgreSQL 模式使用 task dispatch outbox：事务提交后再由 dispatcher 以 `SKIP LOCKED` claim 并投递唯一 taskId，避免“数据库已提交但队列未写入”的双写问题。

### 6.3 Worker、重试和未知结果

`server/src/jobs/task-worker.ts:400`：

- Worker claim durable lease 后把 queued 改为 running，并周期性续租。
- 路由快照生成按渠道优先级、重试预算和断路器状态排列的 attempt plan。
- 每个 attempt 带平台幂等键，调用 provider adapter 后分类为 success、retryable、permanent 或 unknown。
- 可重试错误切换渠道；预算耗尽才失败并释放剩余预留。
- 网络超时、租约丢失或结果不确定不会直接重复请求，而是进入 unknown/reconciliation，防止供应商已完成但平台重复扣费。
- 续租失败会 fence 后续副作用，避免两个 Worker 同时结算同一任务。

### 6.4 输出与结算

成功输出先写 staging/object，再创建用户 asset 和 output 记录；结算按实际成功输出和价格快照扣除 reserved，释放多余预留。结算失败会进入 unknown，等待一致性恢复。

## 7. 供应商适配

`server/src/adapters/provider.ts` 是供应商边界：

- 平台显示模型 ID 与供应商请求模型 ID 分开解析，模型映射只在出站时生效。
- OpenAI 兼容图片适配器支持 `/images/generations`、`/images/edits`、多参考图、mask、参数和 idempotency header。
- 出站 URL 在生产要求 HTTPS 与公网 DNS；请求固定解析地址、禁用重定向，并限制超时和响应字节数。
- transport/timeout 归类为 unknown，而不是轻率判为 failed。
- admin 模型探测会明确请求 `/v1/models` 并返回 requestAttempted 与分类诊断。

设计文档中的 `@图片X` 文本重写、固定 1K/2K/4K 模型后缀和比例矩阵属于产品设计要求；当前源码已确认参考图数组、mask、分辨率模型映射和 OpenAI 兼容调用，但本次没有在服务端调用链中确认独立的 `@图片X -> 第X张图` 文本重写器。

## 8. 一致性、持久化与数据

### 8.1 Store 与事务

Store 聚合用户、会话、模型、渠道、任务、attempt、事件、余额 bucket、ledger、订单、审批、审计和 WebDAV 状态。

- 内存事务保存 snapshot，失败时回滚，提交后才发布缓冲事件。
- 文件适配器使用临时文件 + rename 原子替换，并以 0600 权限写入。
- PostgreSQL Repository 使用 revision/advisory lock、乐观冲突重试和领域行投影。
- task lease、dispatch outbox、message outbox 和 WebDAV job 都有独立 durable claim/renew/complete 接口。

### 8.2 余额与审批

账本使用 bucket slice 记录 reserve、settle、release、refund 和 adjustment。人工充值、退款及高风险调账先创建审批单；默认禁止申请人自批，执行时可要求管理员 TOTP，并把账本、订单、审批状态和审计放入同一事务。

支付 webhook 校验签名、金额、币种和唯一 eventId；订单、payment event、余额 bucket 和 ledger 原子提交。非生产 mock 支付与真实 adapter 路径明确分开。

### 8.3 审计

审计 helper 会脱敏凭证、provider 内部标识和路由快照，并用 previousHash/hash 形成链式校验。管理读审计列表本身也会写入 `audit.read`，因此审计读取是可追踪操作。

## 9. 事件、指标与后台作业

### 9.1 用户任务事件

`server/src/app/ws.ts` 只接受 `/api/v1/ws/tasks`：

- 校验同源与用户会话；生产拒绝 query access_token。
- 每连接最多 8 个任务订阅，20 秒 heartbeat。
- 订阅时先按 cursor 回放，再接收实时事件。
- 以 eventId 和每任务 sequence 去重。
- HTTP 事件与 WS 事件都经过 `publicTaskEvent` 白名单投影，隐藏 channel/provider 等敏感字段。

### 9.2 后台作业

服务端还运行消息 outbox、WebDAV sync/retention、staging GC、租约恢复、reservation 恢复和 unknown reconciliation。WebDAV 适配器校验公网 HTTPS、清理路径穿越，并使用 ETag、租约、指数退避和冲突副本。

## 10. 部署形态

| 环境 | 持久化 | 队列 | 外部依赖 |
| --- | --- | --- | --- |
| 本地开发 | memory/file | memory | 可使用本地 fixture，但不会自动创建展示渠道 |
| 生产 | PostgreSQL | Redis | 公网 HTTPS provider、真实支付/消息/WebDAV 配置 |

已确认的生产硬要求来自 `server/src/config.ts:76`。`system-diagrams.md` 提到可选 S3，但当前源码中实际确认的是本地 staging/object 处理；不能把外部 S3 视为已经实现。

## 11. 已确认事实与未确认边界

### 已确认

- 用户端、管理台、共享合约和服务端是四个明确代码边界。
- 任务采用余额预留、dispatch outbox、队列 lease、attempt、重试/断路器和 unknown 对账。
- 用户任务事件有 WS + cursor replay + HTTP fallback。
- 管理台实时指标为 HTTP 轮询。
- 画布与本地资产以 localForage/IndexedDB 为主，WebDAV 可选同步。
- 生产要求 PostgreSQL 与 Redis。

### 未确认或不应过度承诺

- 没有确认外部 S3 对象存储实现；当前应按本地 staging/object 理解。
- 没有确认设计文档中的 `@图片X` 服务端重写器已经落地。
- 没有确认真正的 3D/视频生成；现有范围以图片、文本、音频和 2D DOM/SVG 画布为主。
- AGENTS.md 提到的 Agent 对话 `threadId/turnId/itemId` 协议未在当前 `server/` 与 `packages/contracts/` 中找到实现。
- 多实例扩展仍依赖 PostgreSQL/Redis、租约 fencing 和外部服务的生产验证，不能以本地 fixture 代替。

## 12. 图示产物

- `docs/miragenflow-architecture.html`：全平台组件、边界、请求和异步主链。
- `docs/miragenflow-task-lifecycle.html`：任务状态主线、失败重试、unknown 保护和取消出口。
- 对应 JSON 规格位于同目录，可继续用 Archify 验证和生成。