# Boss To B 总后台重构设计

日期：2026-04-30

## 背景

当前 `/admin` 已经具备最高管理员访问控制、总览聚合、账号授权、风险处理和 Skill 生命周期治理能力，但页面仍像“几个数据表拼在一起”。对于 To B 交付场景，平台侧需要的是一套能服务客户成功、运维值守和权限开通的 PC 总后台，而不是一个调试看板。

本次重构不新增大业务边界，优先重组现有 `/api/v1/admin/overview`、`/api/v1/admin/access`、`/api/v1/admin/risks/actions`、`/api/v1/admin/skills/requests` 数据和动作，把后台做成可用、可读、可处置的运营控制台。

## 目标

1. 最高管理员进入后台后，能在 10 秒内看出哪些客户、设备、主 Agent 任务或线程风险需要处理。
2. 客户开通从“多个分散表单”收口成可理解的工作台：公司、老板账号、子账号、设备、项目、Skill 授权有清晰入口和状态。
3. 风险处理从“表格按钮”升级为战情室：按严重程度、客户影响、负责人、SLA 和下一步动作组织。
4. Skill 治理保留安全约束，但展示成可追踪的生命周期队列。
5. UI 风格从移动端微信效率风改为 PC To B 管理后台：高密度、强层级、清晰状态、少装饰。

## 非目标

- 不引入新的 Umi / Ant Design Pro 工程。
- 不切换 PostgreSQL 或重写状态存储。
- 不改 Android APP 端交互。
- 不绕过 local-agent 的 Skill allowlist、checksum、备份和回滚约束。
- 不把客户侧 Web 控制台和平台总后台混成一个产品。

## 信息架构

后台改为 4 个一级区：

1. `驾驶舱`：平台全局健康、关键风险、客户影响、在线设备、主 Agent 失败、待处理通知。
2. `客户与账号`：公司列表、客户详情、账号开通、角色状态、登录与安全概览。
3. `授权工作台`：设备、项目、Skill 授权，权限模板，过期授权，离职回收和审计。
4. `风险与治理`：风险战情室、SLA、负责人、修复工单、风险时间线、Skill 生命周期请求。

现有 `账号与授权` 和 `Skill 治理` 不是删除，而是拆到更合理的上下文里：账号归客户，授权归权限，风险和 Skill 请求归治理。

## 页面设计

### 驾驶舱

顶部保留平台身份和刷新动作，但标题从“Boss 管理后台”升级为“平台运营驾驶舱”。主区域按优先级展示：

- `今日待处理`：关键风险数、超 SLA 通知、离线设备、主 Agent 失败。
- `客户健康排行`：按开放风险、在线设备比例、合同/套餐状态排序。
- `关键风险队列`：只展示最值得处理的风险，提供负责人、SLA、确认、关闭、工单动作。
- `设备与节点健康`：GUI/CLI、Browser、Computer Use 能力状态集中展示。
- `最近事件`：风险时间线和权限审计摘要。

驾驶舱默认不展示大分页表，避免用户一打开就被表格淹没。

### 客户与账号

采用左侧客户列表 + 右侧详情的结构：

- 客户列表显示公司名、套餐、账号数、设备数、开放风险、客户成功负责人。
- 右侧详情显示老板账号、子账号、绑定设备、项目数量和最近风险。
- 新建客户流程拆成三步：创建公司、创建老板账号、绑定设备/项目。
- 子账号管理支持启用/停用、重置密码、MFA 状态和登录会话摘要。

这部分复用现有 `/api/v1/admin/access`，但前台从表单堆叠改成任务流。

### 授权工作台

授权页面按“给谁授权”而不是“授权类型”组织：

- 先选择账号或客户。
- 再选择设备、项目、Skill。
- 最后套用权限模板或手动勾选权限。

页面底部保留最近授权审计和过期授权提醒。高危动作继续二次确认。

### 风险与治理

风险页面采用“战情室”结构：

- 左侧风险队列：按 `critical / warning / info`、客户、负责人、SLA 筛选。
- 中间风险详情：影响对象、错误摘要、最近时间线、建议动作。
- 右侧处理面板：指派、设置 SLA、确认、关闭、创建工单。

Skill 生命周期治理放在同一区域的第二页签，展示为请求队列：

- 待认领、执行中、成功、失败分栏。
- 每条请求展示设备、Skill、动作、来源、checksum、结果摘要。
- 创建请求表单保留，但根据动作动态收敛字段。

## 组件边界

建议拆出以下组件，降低当前 `boss-admin-app.tsx` 的复杂度：

- `AdminShell`：PC 后台壳、顶部栏、一级导航。
- `AdminDashboard`：驾驶舱。
- `AdminCustomerWorkspace`：客户与账号工作台。
- `AdminPermissionWorkspace`：授权工作台。
- `AdminRiskCommandCenter`：风险战情室。
- `AdminSkillGovernance`：Skill 生命周期治理，可复用并改造当前组件。
- `AdminStatusBadge`、`AdminMetricCard`、`AdminActionRail`：统一状态、指标和动作区。

数据请求先继续使用现有 fetch，不强制引入新的客户端状态库。

## 数据和接口

第一批不要求新增后端字段，但前台应完整使用现有字段：

- `summary`
- `companies`
- `accounts`
- `devices`
- `risks`
- `notifications`
- `riskTimeline`
- `grantsSummary`

如果发现页面需要客户健康分数，可先在前端由 `openRiskCount / onlineDeviceCount / deviceCount / status` 计算，不改状态 schema。

## 错误处理

- 后台总览读取失败时展示一张明确的恢复卡，提供重试按钮。
- 风险动作失败时保留原行状态，不做乐观关闭。
- 指派负责人和 SLA 不再使用 `window.prompt`，改成右侧处理面板或弹窗表单。
- 空状态要表达下一步，例如“暂无风险，可以查看设备在线情况”，不要只写“暂无数据”。

## 测试策略

- 保留并更新 `tests/admin-refine-page.test.ts`，验证新的一级区和关键文案。
- 增加组件 source 测试，确认不再使用 `window.prompt` 做风险指派和 SLA。
- 复跑 `tests/admin-overview-route.test.ts`、`tests/admin-risk-actions-route.test.ts`、`tests/admin-skill-lifecycle-panel-source.test.ts`。
- 最后跑 `npm run lint` 和相关 Node 测试。

## 分批落地

第一批直接做到可用：

1. 重构 `BossAdminApp` 外壳和一级导航。
2. 做新版驾驶舱。
3. 做风险战情室，替换 `window.prompt`。
4. 账号授权和 Skill 治理先迁入新结构，并压缩视觉层级。

第二批再增强：

1. 客户详情抽屉。
2. 新建客户三步流程。
3. 风险筛选和搜索。
4. 客户健康分数和趋势。

## 自检

- 无 TBD / TODO。
- 范围聚焦 `/admin` PC 总后台，不触碰 APP。
- 没有要求新增大后端能力，优先复用现有接口。
- 关键交互从数据表改成工作台与战情室，解决“后台管理不太好”的主要问题。