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