412 lines
30 KiB
Markdown
412 lines
30 KiB
Markdown
# MiragenFlow 管理台重构 Goal
|
||
|
||
> 本轮综合长任务入口：[`docs/miragenflow-long-task-goal-prompt.md`](docs/miragenflow-long-task-goal-prompt.md)。本文继续维护管理台 22 页、权限和业务闭环细节；前后台组件统一规则见该入口及 `docs/miragenflow-tdesign-unification-goal.md`。如本文与综合入口的渠道交互描述冲突，以综合入口的“OpenAI 单一供应方式 + 三个可自由切换 Tab”规则为准。
|
||
|
||
## 0. 目标状态
|
||
|
||
- **目标对象**：`/Users/qiu/Desktop/MiragenFlow`
|
||
- **目标名称**：管理台商业业务工作台重构
|
||
- **当前阶段**：目标文档与逐页 SSII 基线已完成；代码已完成 P0 壳层/权限、认证开关、独立系统设置、用户详情分 Tab、任务详情/审批驳回、渠道/分组/模型产品编辑抽屉、渠道健康批量探活、任务并发投递、跨实例任务 dispatch 回载、系统概览趋势/告警、业务维度筛选、PostgreSQL 任务租约心跳/过期恢复、消息 outbox 发送期续租与业务幂等键、WebDAV 完成事务与保留期行锁扫描、管理员 MFA 开关门禁。仍需浏览器逐页验收，以及完整 PostgreSQL 领域表 CAS、远端 WebDAV/消息竞态、管理台列表跨路由异步回写保护和真实 provider 的部署验证。未完成项不得按“已完成”发布。
|
||
- **依据**：`AGENTS.md`、`develop.md`、`system-diagrams.md`、`admin-plan.md`、`summary.md`
|
||
- **跨端组件目标**：用户端与管理端统一 TDesign 的长期执行基线见 `docs/miragenflow-tdesign-unification-goal.md`；本文继续只负责管理台业务目标，不把两端页面、路由、权限或状态合并。
|
||
- **禁止结果**：白屏、无恢复路径的 403、假按钮、首屏堆满配置字段、mock 冒充业务、未接入供应商伪装成已接入。
|
||
|
||
## 1. 最终目标
|
||
|
||
把当前平铺的 TDesign Starter 管理台重构为商业化 V1 管理工作台：
|
||
|
||
1. 管理员从 `/admin/login` 默认只使用邮箱和密码登录（本地默认 `admin@admin.com` / `admin`）；MFA/CAPTCHA 仅在后台增强开关显式开启时追加，关闭时界面不得出现验证码、动态码或恢复码输入框。
|
||
2. 用户端认证提供密码登录（邮箱、手机号、用户名）和手机号验证码登录；注册提供邮箱、手机号两条路径，注册邮箱验证与注册手机号验证由 `/admin/settings` 独立开关控制，开启后先完成验证码验证再设置并确认密码。
|
||
3. 登录后加载管理员角色、scope、MFA 状态和可见菜单；权限不足隐藏菜单，不能白屏。
|
||
4. 左侧使用一级分组 + 二级页面，URL 统一为 `/admin/...`。
|
||
5. 新增、编辑、启停、调价、审批、调账全部通过 Modal/Drawer 完成。
|
||
6. 用户、渠道、分组、模型产品、价格、套餐、余额、支付、任务、存储、审计形成真实业务闭环。
|
||
7. 供应商消息暂不接入；消息供应商和模板页面隐藏，只保留认证消息 outbox 状态和详情。
|
||
8. 状态、能力、错误码、按钮全部中文；长文本和 capability 不能撑高表格。
|
||
9. 所有写操作提供成功、加载、空态、403、409、422、503、网络断开和重试反馈。
|
||
|
||
## 2. 必读文件
|
||
|
||
实施前依次读取以下绝对路径：
|
||
|
||
- `/Users/qiu/Desktop/MiragenFlow/AGENTS.md`
|
||
- `/Users/qiu/Desktop/MiragenFlow/develop.md`
|
||
- `/Users/qiu/Desktop/MiragenFlow/system-diagrams.md`
|
||
- `/Users/qiu/Desktop/MiragenFlow/admin-plan.md`
|
||
- `/Users/qiu/Desktop/MiragenFlow/summary.md`
|
||
- `/Users/qiu/Desktop/MiragenFlow/admin/src/router/index.ts`
|
||
- `/Users/qiu/Desktop/MiragenFlow/admin/src/layouts/components/Menu.tsx`
|
||
- `/Users/qiu/Desktop/MiragenFlow/admin/src/layouts/components/AppRouter.tsx`
|
||
- `/Users/qiu/Desktop/MiragenFlow/admin/src/components/ErrorPage/index.tsx`
|
||
- `/Users/qiu/Desktop/MiragenFlow/admin/src/pages/Business/index.tsx`
|
||
- `/Users/qiu/Desktop/MiragenFlow/admin/src/services/platform.ts`
|
||
- `/Users/qiu/Desktop/MiragenFlow/server/src/app/http.ts`
|
||
- `/Users/qiu/Desktop/MiragenFlow/server/src/shared/auth.ts`
|
||
- `/Users/qiu/Desktop/MiragenFlow/packages/contracts/src/index.ts`
|
||
- 根目录、`admin/`、`web/`、`server/` 的 `package.json`
|
||
- `/Users/qiu/Desktop/MiragenFlow/scripts/dev-all.mjs`
|
||
- `/Users/qiu/Desktop/MiragenFlow/scripts/build-all.mjs`
|
||
|
||
页面/API变更必须同步 `admin-plan.md`、`system-diagrams.md`、`summary.md`、`CHANGELOG.md`、`docs/content/docs/progress/todo.mdx` 和 `docs/content/docs/progress/pending-test.mdx`。
|
||
|
||
## 3. 产品边界
|
||
|
||
### 必须进入 V1
|
||
|
||
管理员登录/RBAC/审计、菜单分组、系统概览、用户管理、认证消息、管理员安全、渠道、渠道健康、渠道组、模型产品、价格、金币单位、换算、套餐、余额账本、充值订单、支付事件、支付适配器、审批、任务中心、WS 指标、存储策略、系统设置、审计日志。
|
||
|
||
### 不进入可见菜单
|
||
|
||
消息供应商、消息模板、视频、动画、真实 3D、团队、云端项目 CRUD、内容治理、Local Agent、Codex、MCP、Skill、远程 Prompt、插件市场。支付只保留人工充值、mock 和 adapter 接口，等待第三方支付文档。
|
||
|
||
前台、公开 API、日志和导出不得暴露 provider 名称、Base URL、API Key、内部 provider model ID、渠道顺序、Cookie、WebDAV 密文或完整敏感提示词。
|
||
|
||
## 4. 菜单信息架构
|
||
|
||
```text
|
||
元境幻生管理台
|
||
├─ 总览
|
||
│ └─ 系统概览 /admin/dashboard/base
|
||
├─ 用户与认证
|
||
│ ├─ 用户管理 /admin/users
|
||
│ ├─ 认证消息 /admin/auth-messages
|
||
│ └─ 管理员安全 /admin/security/mfa
|
||
├─ 渠道与模型
|
||
│ ├─ 渠道管理 /admin/channels
|
||
│ ├─ 渠道健康 /admin/channel-health
|
||
│ ├─ 渠道分组 /admin/channel-groups
|
||
│ ├─ 模型产品 /admin/model-products
|
||
│ └─ 价格规则 /admin/pricing
|
||
├─ 计费与套餐
|
||
│ ├─ 金币单位与换算 /admin/billing/units
|
||
│ ├─ 余额与账本 /admin/billing
|
||
│ ├─ 套餐管理 /admin/plans
|
||
│ ├─ 充值订单 /admin/recharges
|
||
│ ├─ 支付事件 /admin/payments
|
||
│ ├─ 支付适配器 /admin/payment-providers
|
||
│ └─ 审批中心 /admin/approvals
|
||
├─ 任务与运行
|
||
│ ├─ 任务中心 /admin/tasks
|
||
│ └─ 实时指标 /admin/ws-metrics
|
||
├─ 存储与系统
|
||
│ ├─ 存储策略 /admin/storage
|
||
│ └─ 系统设置 /admin/settings
|
||
└─ 审计
|
||
├─ 日志大板 /admin/audit
|
||
└─ 详细日志 /admin/audit-logs
|
||
```
|
||
|
||
菜单规则：一级节点可展开/收起；收起时侧栏完全隐藏，不保留窄图标栏；刷新 URL 自动展开；无 scope 的二级项不渲染；`admin:read` 只读，写操作需 `admin:write` 或 `admin:finance`；登录、403、404 不入业务菜单。
|
||
|
||
## 5. 统一布局与交互
|
||
|
||
```text
|
||
+--------------------------------------------------------------------------------+
|
||
| 元境幻生 | 一级菜单/二级菜单 | 面包屑 | 刷新 | 帮助 | 管理员菜单 |
|
||
+--------------------------------------------------------------------------------+
|
||
| 页面标题+描述 [搜索] [筛选] [批量操作] [新增/配置] |
|
||
+--------------------------------------------------------------------------------+
|
||
| KPI/统计卡/当前版本/告警 |
|
||
+--------------------------------------------------------------------------------+
|
||
| 固定列宽表格：选择 | 关键字段 | 中文状态 | 更新时间 | 操作 |
|
||
+--------------------------------------------------------------------------------+
|
||
| 右侧 Drawer/Modal：字段分组 | 校验 | 风险提示 | 取消 | 保存/提交 |
|
||
+--------------------------------------------------------------------------------+
|
||
```
|
||
|
||
全页面必须有加载骨架、空态、网络错误重试、403权限卡、提交中禁用、成功 Toast、422 字段错误、409 版本冲突、503 保留表单重试；支持 Tab/Enter/Escape 和焦点回收。窄屏页面整体不得产生无意义的横向溢出，但业务表格允许在局部容器内横向滚动，以保留列表语义和列可读性。长文本用摘要/Tooltip/详情抽屉，不能撑高表格。
|
||
|
||
## 6. 页面目标、布局和验收
|
||
|
||
### 6.1 登录/错误
|
||
|
||
- `/admin/login`：居中邮箱密码卡片；开关开启时追加 CAPTCHA/MFA；成功进入 `/admin/dashboard/base`；失败保留输入并显示错误。
|
||
- `/admin/403`、`/admin/404`：错误码、角色、所需 scope、`返回系统概览`、`重新登录`、`切换管理员`；按钮必须可用，禁止静态白板。
|
||
|
||
### 6.2 系统概览 `/admin/dashboard/base`
|
||
|
||
顶部时间范围/刷新；KPI 展示用户、活跃用户、任务、金币消耗、充值金额、队列深度、WS 在线；图表展示任务成功/失败率、P50/P95、模型可用率、渠道错误率、邮件/SMS 成功率和支付回调异常；卡片可带筛选跳转，单卡片可重试。
|
||
|
||
### 6.3 用户管理 `/admin/users`
|
||
|
||
搜索、状态/等级/验证/创建时间筛选；表格展示脱敏身份、验证状态、MFA、套餐、并发、每日额度、余额、最近登录；`新增用户` 打开 Drawer，填写用户名、邮箱、手机号和初始密码；详情包含账户/会话/任务/账本/权益/审计 Tab；支持冻结、解冻、重置密码、重发认证和调账申请。新增成功只显示一次初始密码，冻结后计费任务必须拒绝。
|
||
|
||
### 6.4 认证消息 `/admin/auth-messages`
|
||
|
||
状态/通道/用途/时间筛选；表格展示目标脱敏、用途、通道、状态、重试次数、错误摘要、时间；详情 Drawer 展示状态时间线和完整多行内容；重试需确认；内容使用 `white-space: pre-wrap`；供应商配置不在此页面实现。
|
||
|
||
### 6.5 管理员安全 `/admin/security/mfa`
|
||
|
||
状态卡、全局策略、启用/验证/关闭操作和恢复码 Drawer；关闭需要当前 TOTP/原因；开关关闭时登录只需邮箱密码，开启时追加 MFA；恢复码只显示一次，全部操作写审计。
|
||
|
||
### 6.6 渠道管理 `/admin/channels`
|
||
|
||
列表首屏仅展示搜索/筛选/`新增渠道`按钮和固定列；列使用中文业务字段（名称、供应方式、环境、区域、能力、状态、健康、优先级、并发/限流、成本、维护窗口、版本），不直接展示密钥、Base URL 或供应商内部模型 ID。新增和编辑共用同一风格的 Drawer，内部只有三个可自由切换的 Tab：`基础信息`、`模型列表`、`模型映射`；不使用上一步/下一步，也不提供没有真实逻辑的“通用”供应商模板。支持编辑、启停、凭证轮换、手动探活和 If-Match；密钥不回显。
|
||
|
||
基础信息填写名称、完整请求地址（示例 `https://example.com` 或 `https://example.com/v1`）和 API Key；API Key 只校验去除首尾空白后非空。模型列表仅在管理员主动点击按钮后请求 `{基础地址}/v1/models`，结果由管理员勾选加入渠道模型列表；模型映射是可选的，分别保存平台显示模型 ID 与供应商请求模型 ID，不能自动把拉取结果变成映射。切换 Tab、编辑回填、保存失败和关闭重开都必须保留或恢复正确草稿。
|
||
|
||
### 6.7 渠道健康 `/admin/channel-health`
|
||
|
||
状态/分组/时间筛选、健康统计卡和固定表格；列为渠道、中文状态、延迟、成功率、连续失败、熔断剩余、探活时间、维护窗口；映射 `healthy=健康`、`degraded=降级`、`open=熔断`、`disabled=已停用`；支持单项/批量探活和错误时间线。
|
||
|
||
### 6.8 渠道分组 `/admin/channel-groups`
|
||
|
||
分组列表和 `新增分组`；详情 Drawer 包含用途/档位、启停、可用渠道池、拖拽顺序、重试预算、超时、并发、熔断、退避、half-open、公共失败文案、替代模型、发布和回滚。保存前校验渠道存在、启用、顺序唯一；模拟首渠道失败必须展示 fallback 顺序。
|
||
|
||
### 6.9 模型产品 `/admin/model-products`
|
||
|
||
列表和 `新增产品`；Drawer 配置公开 ID、名称、档位、默认质量、能力、分辨率、最大数量、参考图数量、mask、渠道组、价格、替代模型、生效时间、状态和版本。能力用中文标签，超出显示 `+N` 和详情 Drawer；启用产品必须绑定启用渠道组；公开 API 只显示公开 ID。
|
||
|
||
### 6.10 价格规则 `/admin/pricing`
|
||
|
||
产品/分辨率/档位筛选；价格版本表；`新增规则`/`调整价格`弹窗包含基础价、数量阶梯、分辨率倍率、金币单位、生效时间、原因；提交携带 If-Match；旧版本返回 409，展示当前版本并允许重载；成功刷新且保留筛选。
|
||
|
||
### 6.11 金币单位与换算 `/admin/billing/units`
|
||
|
||
单位卡展示图标、名称、短码、精度、比例、版本；换算规则表支持新增/编辑/停用/生效期；账本使用最小整数金币，比例变更有审计和版本。
|
||
|
||
### 6.12 套餐 `/admin/plans`
|
||
|
||
卡片/表格切换；新增和编辑 Drawer 配置公开编码、名称、图标、介绍、排序、时长、包含金币、购买金额、并发、队列优先级、保留期、最大延长、允许模型/渠道组、上架、归档、版本；上下架即时影响公开目录，支持回滚。
|
||
|
||
### 6.13 余额 `/admin/billing`
|
||
|
||
余额统计、用户/流水类型筛选、账本表和调账申请；展示 available/reserved、reserve/settle/release/refund，支持按用户/任务/订单追踪；调账必须申请→审批→执行，`available + reserved` 不变量成立。
|
||
|
||
### 6.14 充值/支付 `/admin/recharges`、`/admin/payments`
|
||
|
||
充值表展示订单、用户、金额、金币、渠道、状态、创建/回调时间；支付表展示 eventId、订单、签名、金额/币种、状态、重放结果和异常；重复 webhook 必须幂等，状态和账本同事务。
|
||
|
||
### 6.15 支付适配器 `/admin/payment-providers`
|
||
|
||
列表展示名称、mock/adapter 模式、状态、密钥状态、版本；Drawer 支持新增 mock、启停、测试 webhook、服务端加密签名密钥；第三方支付等待文档，不伪造 provider。
|
||
|
||
### 6.16 审批 `/admin/approvals`
|
||
|
||
待审批/已执行/已驳回/已过期 Tab；详情显示申请人、审批人、原因、金额/对象、审计；人工充值、退款、调账和高风险配置要求申请人/审批人分离，过期自动标记，策略开启时要求审批 MFA。
|
||
|
||
### 6.17 任务 `/admin/tasks`
|
||
|
||
状态/类型/模型/用户/时间筛选；列表展示 taskId、用户、类型、公开模型、状态、预扣/实扣、attempt、更新时间；详情 Drawer 展示输入快照、状态时间线、attempt、输出、账本、错误、脱敏 provider request ID；支持取消、重试、unknown 对账。
|
||
|
||
### 6.18 实时指标 `/admin/ws-metrics`
|
||
|
||
展示在线连接、订阅、事件吞吐、心跳、断线、轮询降级、事件积压；支持时间窗口、自动刷新暂停、断线恢复和实例/任务筛选；重连 cursor 不重复。
|
||
|
||
### 6.19 存储/系统 `/admin/storage`、`/admin/settings`
|
||
|
||
存储策略配置 staging TTL、结果/原图保留、WebDAV manifest 保留、最大延长、归档模式、GC、扫描/quarantine、对象存储 adapter；系统设置必须是独立资源（不能复用 `storage-policies`），配置用户验证/MFA/CAPTCHA、管理员 MFA/CAPTCHA、限流、队列和审计保留；默认关闭所有认证增强，开关即时影响认证并写入版本/审计，状态可追踪，对象存储默认关闭。
|
||
|
||
### 6.20 审计 `/admin/audit`、`/admin/audit-logs`
|
||
|
||
`/admin/audit` 展示分类、HTTP 结果和时间趋势，`/admin/audit-logs` 展示具体操作人、动作、对象和请求来源；两者均可打开详情 Drawer，展示脱敏 before/after、IP、requestId、correlationId、hash 链和摘要导出。绝不展示密钥、密码、Cookie、完整提示词、原图或 WebDAV 凭证。
|
||
|
||
## 6.21 逐页 SSII 索引
|
||
|
||
详细 ASCII/SSII 线框统一维护在 `/Users/qiu/Desktop/MiragenFlow/admin-plan.md` 第 4-5 节；每页验收按以下结构执行：顶部标题与筛选、统计/告警区、固定列宽列表、详情 Drawer/Modal、加载/空/错误/冲突状态。
|
||
|
||
| 页面 | 主布局 | 关键交互 |
|
||
|---|---|---|
|
||
| 系统概览 | KPI 卡 + 趋势 + 告警 | 时间范围、单卡跳转、局部重试 |
|
||
| 用户管理 | 筛选栏 + 用户表 + 详情 Drawer | 新增、冻结、重置、重发、强退、调账 |
|
||
| 认证消息 | 状态筛选 + outbox 表 + 消息 Drawer | 多行详情、失败重试 |
|
||
| 管理员安全 | 策略卡 + MFA 操作 Drawer | setup/verify/disable、恢复码一次性展示 |
|
||
| 渠道管理 | 渠道表 + 三 Tab 新增/编辑 Drawer | 地址校验、手动拉取模型、勾选加入、可选映射、启停、轮换密钥 |
|
||
| 渠道健康 | 健康 KPI + 渠道表 | 中文状态、单项/全部探活、日志 |
|
||
| 渠道分组 | 分组表 + 拖拽排序 Drawer | 成员校验、fallback 预览、版本保存 |
|
||
| 模型产品 | 产品表 + 产品 Drawer | 能力折叠、分辨率、渠道绑定、上下架 |
|
||
| 价格规则 | 版本表 + 价格 Modal | 新增/调价、If-Match 冲突重载 |
|
||
| 金币单位/换算 | 单位卡 + 规则表 | 比例、精度、舍入和生效期 |
|
||
| 套餐管理 | 卡片/表格 + 套餐 Drawer | 权益、发布/回滚、归档 |
|
||
| 余额与账本 | 余额 KPI + 流水表 | 调账申请、审批链、reserve/settle/release 追踪 |
|
||
| 充值订单/支付事件 | 订单表 + 事件详情 | 失败标记、退款申请、webhook 幂等 |
|
||
| 支付适配器 | 适配器表 + 配置 Drawer | mock/adapter、启停、密钥状态 |
|
||
| 审批中心 | 状态 Tab + 审批详情 | 申请人/审批人分离、条件 MFA、过期处理 |
|
||
| 任务中心 | 任务表 + 任务 Drawer | attempt、取消、重试、unknown 对账 |
|
||
| 实时指标 | 指标卡 + 时间序列 | WS 心跳、断线恢复、cursor 去重 |
|
||
| 存储策略/系统设置 | 策略表 + 设置 Drawer | TTL、WebDAV、归档、增强开关 |
|
||
| 审计日志 | 筛选表 + 审计 Drawer | 脱敏 before/after、hash 链和导出摘要 |
|
||
|
||
## 6.22 22 个页面的逐页 SSII 骨架
|
||
|
||
以下矩阵是开发与浏览器验收的逐页“图片蓝本”。每行对应一张页面线框：`头部` 固定标题/面包屑/刷新，`筛选` 固定在标题下方，`主体` 使用固定列宽表格或指标卡，`侧栏` 使用 Drawer/Modal；加载、空、403、409、422、503 都在同一位置替换主体，不改变页面骨架。
|
||
|
||
| # | 页面 | 头部与筛选 | 主体与详情 | 强交互验收 |
|
||
|---:|---|---|---|---|
|
||
| 1 | `/admin/dashboard/base` | 时间范围、刷新、告警过滤 | KPI 卡、趋势图、异常列表 | 卡片跳转、单卡重试、断线恢复 |
|
||
| 2 | `/admin/users` | 搜索、状态、等级、验证、时间 | 用户表、账户 Drawer、六个详情 Tab | 新增、冻结、重置、重发、强退、调账 |
|
||
| 3 | `/admin/auth-messages` | 状态、通道、用途、时间 | outbox 表、消息详情 Drawer | 多行内容、失败重试、目标脱敏 |
|
||
| 4 | `/admin/security/mfa` | 管理员 MFA 状态/策略 | 策略卡、setup/verify/disable Drawer | 开关门禁、恢复码一次性展示 |
|
||
| 5 | `/admin/channels` | 供应方式、环境、区域、状态 | 渠道表、三 Tab 新增/编辑 Drawer | 地址校验、手动 `/v1/models`、勾选模型、可选映射、启停、轮换密钥 |
|
||
| 6 | `/admin/channel-health` | 健康、分组、时间 | 健康 KPI、渠道表、错误时间线 | 单项/批量探活、中文状态、重试 |
|
||
| 7 | `/admin/channel-groups` | 用途、档位、状态 | 分组表、成员排序/fallback Drawer | 拖拽排序、成员启用校验、模拟故障 |
|
||
| 8 | `/admin/model-products` | 档位、能力、渠道组、状态 | 产品表、产品配置 Drawer | 能力折叠、渠道绑定、发布/回滚 |
|
||
| 9 | `/admin/pricing` | 产品、分辨率、档位、版本 | 价格版本表、调价 Modal | If-Match 409 展示当前版本并重载 |
|
||
| 10 | `/admin/billing/units` | 单位、状态、版本 | 金币单位卡与换算规则表、编辑 Drawer | 比例/舍入/精度校验、版本审计 |
|
||
| 11 | `/admin/billing` | 用户、流水类型、时间 | 余额 KPI、账本表、调账 Drawer | reserve/settle/release/refund 追踪 |
|
||
| 12 | `/admin/plans` | 上架、归档、版本 | 套餐卡/表、套餐 Drawer | 权益配置、发布、回滚、归档 |
|
||
| 13 | `/admin/recharges` | 用户、状态、时间 | 充值订单表、订单 Drawer | 失败标记、退款申请、幂等重放 |
|
||
| 14 | `/admin/payments` | provider、状态、时间 | 支付事件表、事件 Drawer | 签名/金额/币种校验、异常重试 |
|
||
| 15 | `/admin/payment-providers` | 模式、状态、版本 | 适配器表、配置 Drawer | mock 测试 webhook、密钥只显示状态 |
|
||
| 16 | `/admin/approvals` | 待处理/已执行/已驳回/已过期 Tab | 审批表、申请详情 Drawer | 申请人/审批人分离、条件 MFA、驳回 |
|
||
| 17 | `/admin/tasks` | 状态、类型、模型、用户、时间 | 任务表、任务详情/attempt Drawer | 取消、重试、unknown 对账、脱敏 |
|
||
| 18 | `/admin/ws-metrics` | 时间窗、实例、任务 | WS KPI、吞吐/心跳/积压趋势 | 暂停刷新、断线恢复、cursor 去重 |
|
||
| 19 | `/admin/storage` | adapter、保留期、GC 状态 | 存储策略表、配置 Drawer | TTL、归档、扫描/quarantine、GC |
|
||
| 20 | `/admin/settings` | 安全增强、限流、队列、审计 | 系统设置表、版本化编辑 Drawer | 默认关闭、即时生效、If-Match |
|
||
| 21 | `/admin/audit` | 操作者、动作、对象、结果、时间 | 日志大板、分类占比和趋势 | 200/4xx/5xx 统计、中文分类、局部重试 |
|
||
| 22 | `/admin/audit-logs` | 操作者、动作、对象、结果、时间 | 详细日志表、脱敏详情 Drawer | 中文行为、requestId、hash 链、详情重试 |
|
||
|
||
## 7. 服务端契约工作项
|
||
|
||
### 权限和总览
|
||
|
||
- 统一 `super_admin/operator/finance/support/auditor` 到 scopes；未知角色不能得到空权限。
|
||
- `/api/v1/admin/dashboard`、`me`、菜单权限和前端 scope 一致。
|
||
- 403/404 返回稳定错误码和 requestId，前端必须有可恢复页面。
|
||
|
||
### 用户
|
||
|
||
- 增加管理员创建用户 API，校验身份唯一、初始密码、状态、套餐和限制字段；密码只显示一次并只存哈希。
|
||
- 冻结、解冻、重置、重发认证、强退和调账申请审计；详情数据脱敏并按对象权限返回。
|
||
|
||
### 渠道和模型
|
||
|
||
- 渠道新增校验 HTTPS、DNS/私网、协议、密钥、超时、并发和限流；密钥服务端密文保存。
|
||
- 渠道组校验成员存在、启用、排序唯一；模型产品校验渠道组存在且可用；价格支持 If-Match 和幂等。
|
||
- 公共 DTO 不得包含 provider model ID、Base URL、Key 或渠道顺序。
|
||
|
||
### 计费、任务、存储、审计
|
||
|
||
- 余额、账本、支付订单、支付事件和审批保持一致事务；任务取消/重试/unknown 不重复扣款。
|
||
- WS 指标、attempt、队列租约、WebDAV/GC/归档状态可查询。
|
||
- 审计 before/after 递归脱敏，日志和导出不包含真实密钥或完整敏感内容。
|
||
|
||
## 8. 实施阶段
|
||
|
||
### P0 壳层与权限
|
||
|
||
嵌套路由、一级/二级菜单、权限加载、403/404恢复、角色映射、真实总览指标和错误态。
|
||
|
||
### P1 核心配置闭环
|
||
|
||
用户新增；渠道新增/探活/启停；健康中文化；渠道组排序/fallback；模型产品能力/分辨率/绑定；价格调整/版本冲突。
|
||
|
||
### P2 商业和运维
|
||
|
||
金币、换算、套餐、余额、充值、支付、支付适配器、审批、任务、WS 指标、存储、设置、审计、认证消息多行详情。
|
||
|
||
### P3 统一体验
|
||
|
||
加载/空/错/403/409/503、固定列宽、能力折叠、中文状态、响应式 Drawer、键盘无障碍、敏感扫描、同源回归。
|
||
|
||
## 9. 验收标准
|
||
|
||
### 静态和构建
|
||
|
||
```bash
|
||
npm --prefix server run typecheck
|
||
npm --prefix server test
|
||
npm --prefix web run typecheck
|
||
npm --prefix web run build
|
||
npm --prefix admin run typecheck
|
||
npm --prefix admin run build
|
||
npm --prefix admin run lint
|
||
npm run build:all
|
||
git diff --check
|
||
```
|
||
|
||
### 路由和菜单
|
||
|
||
- `/admin/` 自动进入 `/admin/dashboard/base`。
|
||
- 22 个可见二级页面均能进入；刷新后一级展开、二级高亮、面包屑正确。
|
||
- 无权限角色不显示对应菜单；403/404 有返回总览和重新登录按钮。
|
||
- 消息供应商/模板不出现在菜单。
|
||
|
||
### 业务闭环
|
||
|
||
1. 创建用户→列表→详情→冻结；冻结后计费任务拒绝。
|
||
2. 新增渠道→探活→分组拖拽→模型绑定→调价。
|
||
3. 首渠道失败→fallback→任务 attempt 时间线。
|
||
4. 旧 If-Match 调价→409→重载→成功。
|
||
5. 重放 webhook→订单/余额/账本不重复增加。
|
||
6. 调账→审批→执行→完整审计。
|
||
7. 取消/失败/unknown→释放或按实际结算，不重复扣款。
|
||
8. WebDAV 保留/归档/删除→队列/GC 状态可见。
|
||
|
||
### 视觉和交互
|
||
|
||
- 首屏不铺满配置字段，新增/编辑只能通过按钮打开弹窗/抽屉。
|
||
- 认证消息保留换行，capability 不撑高表格，状态均为中文。
|
||
- 所有操作在加载、失败、403、409、503 有明确反馈。
|
||
- Tab/Enter/Escape 和焦点回收可用；宽屏、窄窗口和缩放下页面整体不产生无意义的横向溢出，业务表格在局部容器内允许横向滚动以保留列可读性。
|
||
- 路由、筛选或分页切换期间，旧列表请求不会回写当前页面的行数据、加载态或错误态；必须有延迟请求回归证据。
|
||
|
||
### 安全扫描
|
||
|
||
```bash
|
||
git ls-files | rg '(^|/)(\.env|.*\.(pem|key))$|(^|/)(uploads?|staging|snapshots?)(/|$)'
|
||
rg -n -i 'api[_ -]?key|authorization:|bearer |providerModelId|baseUrl|BEGIN (RSA|EC|OPENSSH) PRIVATE KEY' \
|
||
web/dist admin/dist server/src web/src admin/src --glob '!*.map'
|
||
```
|
||
|
||
## 10. 交付物
|
||
|
||
- 嵌套路由、一级/二级菜单和权限安全壳层。
|
||
- 22 个可见页面的真实布局、弹窗/抽屉、错误态和业务闭环。
|
||
- 用户、渠道、分组、模型、价格、计费、任务、存储、审计 API 对齐。
|
||
- 更新 `admin-plan.md`、`system-diagrams.md`、`summary.md`、`CHANGELOG.md`、`todo.mdx`、`pending-test.mdx`。
|
||
- 完整构建、测试、同源启动和浏览器验收记录；未完成内容继续记录在 TODO/Pending Test。
|
||
|
||
## 10.1 进度反馈格式
|
||
|
||
每完成一个可独立验收的小任务，立即用以下格式反馈，不把未验证内容计入完成度：
|
||
|
||
```text
|
||
已完成：{小任务名称}
|
||
验收证据：{命令、页面、API 或截图路径}
|
||
当前进度：██████▎░░░ {整数}%
|
||
剩余阻塞：{没有则写“无”；有则列出具体文件/接口}
|
||
```
|
||
|
||
百分比按“已通过验收的交付项 / 全部交付项”计算；文档规划、代码实现、自动化测试、同源运行和浏览器人工验收分别计项，不能用文档完成替代功能完成。
|
||
|
||
## 11. 目标引导提示词
|
||
|
||
```text
|
||
你现在负责完成 /Users/qiu/Desktop/MiragenFlow 的管理台重构 Goal。
|
||
|
||
先完整读取：AGENTS.md、develop.md、system-diagrams.md、admin-plan.md、goal.md、summary.md；
|
||
再读取 admin/src/router/index.ts、Menu.tsx、AppRouter.tsx、ErrorPage、Business/index.tsx、
|
||
admin/src/services/platform.ts、server/src/app/http.ts、server/src/shared/auth.ts、
|
||
packages/contracts/src/index.ts，以及各 package.json、scripts/dev-all.mjs、scripts/build-all.mjs。
|
||
|
||
必须实现：
|
||
1. 路由统一为 /admin/...，实现 7 个一级菜单和 22 个二级页面；逐页同步 `admin-plan.md` 的 ASCII SSII 与 `system-diagrams.md` 的 Mermaid；权限不足隐藏菜单并显示可恢复 403 页面。
|
||
2. 管理员默认只显示邮箱/账号和密码输入；MFA、验证码、恢复码均由后台增强开关控制，关闭时不得渲染输入框。完成真实系统概览（含 P50/P95、渠道/模型/消息/支付异常指标）、用户新增/详情分 Tab/冻结/重置密码/重发认证、认证消息多行详情和管理员安全。
|
||
3. 完成渠道新增弹窗、编辑/探活/启停、中文健康状态、分组拖拽排序与 fallback。
|
||
4. 完成模型产品能力/分辨率/渠道组绑定、发布/回滚和价格 If-Match 冲突处理。
|
||
5. 完成金币、换算、套餐、余额、充值失败/退款申请、支付事件、支付适配器和审批中心；管理员 MFA 增强开关关闭时审批不追加动态码，开启时才校验。
|
||
6. 完成任务 attempt/unknown/取消/重试、WS 指标、独立 `/api/v1/admin/settings` 系统设置 API/持久化/If-Match、存储策略和审计；系统设置不能复用 `storage-policies`。
|
||
7. 消息供应商和模板本期隐藏，不接入第三方 provider，不伪造可用配置。
|
||
8. 所有新增/编辑/启停/调价/审批/调账均用弹窗或 Drawer；固定列宽，中文状态，长文本和 capability 不撑表格。
|
||
9. 不向前台、公开 API、日志或导出暴露 provider 名称、Base URL、API Key、内部模型 ID、渠道顺序。
|
||
|
||
按 P0 壳层权限 → P1 渠道/分组/模型/价格 → P2 用户/计费/任务/存储/审计 → P3 视觉回归实施。
|
||
不要做视频、动画、真实 3D、团队、内容治理、Local Agent、远程 Prompt 或插件市场。
|
||
不要回滚已有改动，不要用 mock 冒充业务，不要把配置字段永久铺在首屏。
|
||
|
||
每个阶段执行并记录：
|
||
npm --prefix server run typecheck
|
||
npm --prefix server test
|
||
npm --prefix web run typecheck && npm --prefix web run build
|
||
npm --prefix admin run typecheck && npm --prefix admin run build && npm --prefix admin run lint
|
||
npm run build:all
|
||
git diff --check
|
||
|
||
最终启动 npm run dev:all，用同一 origin 验证 /、/admin/、/api/health、/api/ready；
|
||
逐页验证 22 个页面、权限角色、弹窗/抽屉、ASCII SSII 对应布局、加载/空/错误/403/409/503、中文排版、
|
||
渠道→分组→模型→价格、用户新增、任务、余额、审批、WebDAV 和审计；执行敏感扫描，
|
||
同步更新 admin-plan.md、system-diagrams.md、summary.md、CHANGELOG.md、todo.mdx、pending-test.mdx。
|
||
未完成内容必须明确记录，不能宣布全部完成。
|
||
```
|