boss/docs/superpowers/specs/2026-04-30-admin-backoffice-redesign.md

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。
• 没有要求新增大后端能力，优先复用现有接口。
• 关键交互从数据表改成工作台与战情室，解决“后台管理不太好”的主要问题。