# Boss To B 管理后台接入记录

更新时间：`2026-04-27`

## 目标

为 Boss To B 场景新增系统管理后台，供平台侧查看和管理不同客户公司的账号、设备、权限和风险状态，重点支持快速发现客户电脑 Codex 节点掉线、主 Agent 任务失败、线程上下文风险和运维故障。

## 技术选型

- 使用 `@refinedev/core` 作为管理后台资源抽象层。
- 使用 `antd` 原生组件作为后台 UI 组件库。
- 不使用 `@refinedev/antd`，原因是当前版本会传递引入 `@ant-design/pro-layout -> path-to-regexp@8.2.0` 高危 audit 链。
- 不直接接入 `ant-design-pro` 工程，避免把 Umi/Max 路由和权限体系引入现有 `Next.js 16 + App Router` 主工程。

## 企业级后台独立化方向

2026-04-30 起，Boss 后台进入独立 PC 管理后台阶段。调研 `YunaiV/yudao-cloud` 后，当前策略是借鉴它的租户、用户、角色、菜单、日志和工作台信息架构，但不直接接入 YuDao 的 Java 微服务后端，避免把现有 `Next.js + 文件状态账本 + local-agent` 运行时拆碎。

第一批新增：

- `apps/boss-admin-web`：独立 Vue + Vite + Ant Design Vue 后台工程，面向平台侧运营和客户成功人员。
- `/api/v1/admin/backoffice`：企业后台 BFF，把 Boss 当前账本聚合成 YuDao 风格的菜单、工作台、租户、账号、角色权限、资源授权、Skill 中心、风险和审计数据。
- `/enterprise-admin`：Next 主站内的受保护入口，只允许 `highest_admin` 访问，并跳转到独立后台静态产物 `/admin-web/index.html`。
- `admin:web:dev` / `admin:web:build` / `admin:web:publish`：根工程脚本入口。`admin:web:publish` 会把 Vue 构建产物写入 `public/admin-web`，随 Next standalone 的 `public` 一起发布。

边界：

- 旧 `/admin` UI 已删除，`/admin` 仅保留为跳转到根路径 `/` 的兼容入口；生产域名 `https://admin.boss.hyzq.net/` 直接承载新独立 PC 后台。
- 独立后台只消费 Admin BFF，不直接读取 `boss-state.json`。
- 独立后台当前复用 Boss Cookie 登录态，后续再绑定 `admin.boss.hyzq.net` 的独立部署。
- `/api/v1/admin/backoffice` 仍只允许 `highest_admin`，并过滤 `passwordHash`、`mfaSecret` 和 session token。

## 当前落地范围

- `/admin` 页面收敛为兼容跳转，不再承载旧 Next 管理 UI。
- 新增 `/api/v1/admin/overview` 聚合接口。
- 新增 `/api/v1/admin/backoffice` 独立企业后台聚合接口。
- 新增 `/api/v1/admin/risks/actions` 风险处理动作接口。
- 新增 `/api/v1/admin/notifications/dispatch` 风险通知派发接口。
- 新增 `buildAdminOverview(state)` 纯函数，负责从当前文件状态聚合后台数据。
- 新增显式 `adminCompanies` 租户账本，支持把账号和设备直接绑定到客户公司，不再只能依赖账号邮箱域名推断。

当前页面已在 `2026-04-30` 升级为 PC To B 总后台结构，不再是简单的 3 个表格页签。新结构包含 4 个一级区：

- `平台运营驾驶舱`：平台全局健康、待处理风险、客户健康、节点健康、最近事件。
- `客户与账号`：客户公司、账号列表、设备归属和客户开通任务流。
- `授权工作台`：复用既有账号 / 设备 / 项目 / Skill 授权能力，但放在更清晰的权限上下文里。
- `风险与治理`：风险战情室、SLA、负责人、修复工单，以及 Skill 生命周期治理。

### 平台运营驾驶舱

- 展示今日待处理：客户公司、账号、在线设备、开放风险和风险通知。
- 展示客户健康排行：按开放风险和设备在线情况优先排列。
- 展示关键风险队列：只展示最值得处理的风险，完整队列进入风险战情室。
- 展示节点健康：集中查看客户电脑、Codex GUI / CLI 和最近心跳。
- 展示最近事件：风险通知和风险时间线，避免平台侧漏跟进。

### 客户与账号

- 展示客户公司列表、健康状态、账号数、在线设备、开放风险和客户成功负责人。
- 展示客户开通任务流：创建客户公司、开通老板账号、绑定客户电脑、分配项目与 Skill 权限。
- 展示账号列表：账号、角色、公司、状态和最近登录。
- 展示客户设备：设备状态、GUI / CLI 在线状态、风险数和最近心跳。

### 授权工作台

- 继续复用 `/api/v1/admin/access`。
- 支持创建 / 更新子账号、公司管理、批量导入、账号归属、设备归属、权限模板、设备 / 项目 / Skill 授权和离职回收。
- 高危动作继续保留二次确认和审计记录。

### 风险与治理

- 风险战情室按严重程度、客户影响、负责人和 SLA 组织风险。
- 风险处理不再使用浏览器 `window.prompt`，改成页面内处理面板。
- 处理面板支持指派负责人、设置 SLA、确认、关闭和创建修复工单。
- 对暂不支持动作的风险类型保持只读提示，不假装处置成功。
- Skill 生命周期治理作为同一区域的第二页签，继续复用 `/api/v1/admin/skills/requests`。

## 旧版落地范围记录

以下是第一版落地内容，仍保留作为能力来源说明：

### 总览

- 总览统计：公司数、账号数、在线设备、开放风险。
- 风险通知：展示由 SLA 扫描生成的超时通知，避免平台侧只看到风险列表、漏掉需要主动跟进的客户事项。
- 风险时间线：展示风险通知生成、派发、确认、关闭、负责人和 SLA 调整等最近事件。
- 关键风险：展示最高优先级风险。
- 风险表：离线设备、未关闭运维故障、线程上下文告警、失败主 Agent 任务。
- 风险动作：`ops_fault` 支持指派负责人、设置 SLA、确认、关闭和创建修复工单；`thread_context_alert` 支持指派负责人、设置 SLA、确认和关闭；暂不支持的风险类型会显式失败，不假成功。
- 设备表：设备在线状态、CLI/GUI 连接状态、最近心跳和风险数量。
- 公司表：优先使用显式 `adminCompanies`，账号和设备未绑定公司时才回退到账号域名或默认公司。
- 公司表补齐 To B 运营字段：套餐等级、合同到期时间、客户负责人和客户成功负责人。
- 账号表：展示账号、角色、公司、状态、创建/更新时间，不暴露 `passwordHash`。

### 账号与授权

- 复用 `/api/v1/admin/access`，支持创建 / 更新 `member` 或 `admin` 子账号。
- 支持查看账号状态，并对非主账号执行启用 / 停用；停用账号会同步撤销该账号当前活跃会话。
- 支持公司管理、账号归属、设备归属和公司列表。
- 支持按公司批量导入成员账号，并支持先预览新增 / 更新 / 异常数量，预览不会写入状态账本。
- 支持 CSV 文件导入账号清单，表头为 `account,displayName,role,password`。
- 支持对子账号开启 / 关闭 MFA；后台 GET 不返回 `mfaSecret`，仅开启时在本次响应返回一次 `mfaSetupSecret` 供初始化。
- 支持最高管理员重置子账号密码；重置后会撤销该账号所有活跃会话，响应不暴露 `passwordHash`。
- 支持停用 / 启用客户公司；停用公司会同步禁用该租户下的普通子账号并撤销活跃会话，不会波及平台最高管理员。
- 支持离职回收：停用账号、撤销活跃会话，并清理设备 / 项目 / Skill 授权。
- 公司停用 / 授权撤销 / 密码重置 / 离职回收等高危动作均在 PC 后台做二次确认。
- 支持套用内置权限模板。
- 支持设备、项目、Skill 三类授权。
- 支持撤销单条授权。
- 支持查看最近权限审计记录。

### Skill 治理

- 复用 `/api/v1/admin/skills/requests`，支持创建 `install / update / uninstall / rollback / version_lock` 请求。
- 设备端仍由 `local-agent` 按既有 lifecycle 链路认领和完成。
- 管理后台只负责下发治理请求与查看请求状态，不绕过设备端 allowlist、checksum、备份和回滚约束。
- 2026-04-30 起，PC 总后台的 Skill 治理入口改为 `Skill 中心`：先展示 Skill 目录、详情、授权对象和执行轨迹，再通过右侧安装向导创建生命周期请求。
- `Skill 中心` 会优先使用 `/api/v1/admin/access` 返回的 `skillCatalog`，没有聚合目录时再由设备 Skill 清单前端兜底聚合，避免最高管理员必须记住每台电脑的原始 `skillId`。
- 创建请求仍提交到 `/api/v1/admin/skills/requests`，只是把 `sourceUrl / trustedSourceId / checksum` 等字段放入向导步骤中，降低误操作和填表成本。

## 权限边界

- `/admin` 页面直接跳转根路径 `/`，生产根路径由 `admin.boss.hyzq.net` 站点内部 rewrite 到独立后台静态入口。
- 非 `highest_admin` 访问 `/enterprise-admin` 时只看到“仅最高管理员可用”提示。
- `/api/v1/admin/overview` 未登录返回 `401`，非最高管理员返回 `403`。
- `/api/v1/admin/risks/actions` 未登录返回 `401`，非最高管理员返回 `403`。
- `/api/v1/admin/risks/scan` 未登录返回 `401`，非最高管理员返回 `403`。
- `/api/v1/admin/notifications/dispatch` 未登录返回 `401`，非最高管理员返回 `403`。
- 后台 mutation 路由和认证 mutation 路由会拒绝显式跨站浏览器请求；原生 APP 请求通过 `x-boss-native-app: 1` 豁免浏览器 CSRF 检查。
- 后台 mutation 路由会把 `x-forwarded-for / x-real-ip / user-agent / x-request-id` 写入 `permissionAuditLogs`；高危动作会额外写入安全化 `beforeJson / afterJson` 快照，便于企业客户追责和回放。

## 数据来源

- `authAccounts`：账号与角色。
- `adminCompanies`：客户公司 / 租户实体。
- `devices`：电脑与 Codex CLI/GUI 能力状态。
- `projects`：项目与设备关联。
- `opsFaults`：未关闭运维故障。
- `threadContextAlerts`：未解决线程上下文告警。
- `masterAgentTasks`：失败任务。
- `accountDeviceGrants`、`accountProjectGrants`、`accountSkillGrants`：授权汇总和过期授权统计。
- `adminNotifications`：风险 SLA 超时通知账本，由 `/api/v1/admin/risks/scan` 幂等生成，并由 `/api/v1/admin/notifications/dispatch` 派发。
- `adminRiskTimeline`：风险处理时间线，记录通知生成、派发和人工处置动作。

## 后续扩展

- 下一期应接入企业微信 / 飞书 / 短信等更多通知渠道；当前 `BOSS_ADMIN_NOTIFICATION_MODE=email` 可走服务器 sendmail，默认 `disabled` 只记录派发状态。
- PostgreSQL 切换仍建议先用 `scripts/boss-state-store-maintenance.mjs` 做备份、dry-run 迁移和回滚演练，再设置 `BOSS_STATE_STORE=postgres`。