Module Document

基础架构 · 管理后台详细设计文档

基础架构 · 管理后台详细设计文档

版本: v0.1
日期: 2026-07-06
归属: 基础架构 / 管理后台

1. 模块定位与目标

管理后台是运营、IT 和售后的统一操作界面，聚合设备管理、用户管理、内容审核、工单、配置下发和数据看板，对接各业务系统后端 API，本身不存业务数据事实源。

目标 说明
统一操作入口 运营/IT/售后无需直接操作数据库或 API，通过后台完成日常工作。
权限精细 按角色/模块/操作三级权限，敏感操作（批量删除/配置变更）需二次确认。
操作可审计 所有写操作有操作人、时间、变更内容、结果审计记录。
可扩展 新业务模块可以注册到后台框架，不需要重新搭平台。

2. 执行计划

阶段 时间 交付物 Owner 工作量
P0 框架搭建 0–14 天 后台框架（React Admin / Ant Design Pro）、SSO 接入、菜单权限 前端+后端 2人×2周
P1 用户管理 15–30 天 用户列表、设备列表、账号状态管理、基础查询 后端+前端 2人×2周
P2 设备管理 31–55 天 SN 查询、设备状态、固件版本、激活记录、工单入口 后端+前端 2人×3周
P3 配置下发 56–80 天 配置模板管理、灰度下发、下发记录查询 后端+前端 2人×3周
P4 数据看板 81–110 天 设备在线率、激活趋势、告警汇总、用户增长看板 后端+前端 2人×4周
P5 审核模块 111–140 天 内容审核工单、举报处理、批量操作、审核队列 后端+前端 2人×4周

3. 困难点与复杂度分析

困难点 复杂度 应对
聚合多个后端系统，数据一致性 高 后台 API 层做数据聚合，不直连多个 DB；各业务系统提供独立 API，后台聚合展示。
权限颗粒度与落地效率的平衡 中 v0.1 先按角色/模块/读写三级，后期逐步细化到字段级和行级。
批量操作的安全风险 中 批量操作设置上限（单次≤1000 条），需二次确认，执行前展示影响范围预览。
配置下发灰度策略复杂 中 v0.1 支持按设备 ID 列表和百分比灰度两种方式，灰度效果可回滚。
看板数据实时性要求 低 大多数看板允许 5 分钟延迟，走定时任务预聚合，不做实时流计算。

4. 核心流程

flowchart LR
  A["运营/IT 登录后台"] --> B["菜单权限过滤"]
  B --> C["选择操作模块"]
  C --> D["查询 / 搜索"]
  D --> E{写操作?}
  E -->|否| F["展示数据"]
  E -->|是| G["填写变更内容"]
  G --> H{敏感操作?}
  H -->|是| I["二次确认 + 影响预览"]
  H -->|否| J["直接提交"]
  I --> J
  J --> K["后台 API 调用业务系统"]
  K --> L["写入操作审计"]
  L --> M["结果反馈"]

5. 系统架构

flowchart LR
  subgraph Frontend["管理后台前端"]
    WEB["React Admin SPA"]
  end
  subgraph BFF["后台 API 层 (BFF)"]
    AUTH["SSO 鉴权中间件"]
    RBAC_MW["权限校验"]
    AUDIT_MW["操作审计写入"]
    ROUTER["API 路由聚合"]
  end
  subgraph Backends["业务系统 API"]
    USER_API["用户中心"]
    DEVICE_API["设备云"]
    CONTENT_API["社区内容"]
    CONFIG_API["配置中心"]
  end
  WEB --> AUTH --> RBAC_MW --> ROUTER
  ROUTER --> AUDIT_MW
  ROUTER --> USER_API
  ROUTER --> DEVICE_API
  ROUTER --> CONTENT_API
  ROUTER --> CONFIG_API

6. 关键技术决策

决策点 选择 理由
前端框架 Ant Design Pro / React Admin 后台组件完善，表格/表单/权限开箱即用，上手快。
BFF 层 Go (Gin) 轻量，与业务系统 gRPC/HTTP API 对接成熟，性能好。
权限模型 RBAC（基于 Casdoor/casbin） 与 SSO 模块复用同一 IdP，权限统一管理。
审计存储 写入统一审计日志 ES 与备份/监控/审计模块共用，不独立建审计 DB。
看板数据 定时预聚合 + Redis 缓存 满足 5 分钟延迟要求，成本低，后期可升实时。

7. 数据模型

模型 关键字段 说明
AdminMenu id、name、path、parent_id、required_roles、risk_level 菜单定义及权限要求。
AdminOperationLog id、operator_id、module、action、target_id、diff、result、occurred_at 操作审计日志。
BatchJob id、type、operator_id、scope、status、total、succeeded、started_at 批量操作任务。
ConfigDeployment id、template_id、scope_type、scope_value、status、rollback_id、deployed_at 配置下发记录。

8. 接口设计

接口 方法 说明
/admin/users GET 用户列表查询（代理到用户中心）。
/admin/devices GET 设备列表，含 SN/状态/固件版本（代理到设备云）。
/admin/configs/deployments GET/POST 配置下发记录 / 触发新一轮下发。
/admin/configs/deployments/{id}/rollback POST 回滚配置下发。
/admin/operations GET 操作审计日志查询。
/admin/dashboards/{name} GET 看板数据（预聚合结果）。

9. 验收点

验收点 量化标准
SSO 接入 管理后台 100% 经 SSO 登录，无本地账号体系。
菜单权限 不同角色看到的菜单和操作按钮 100% 与权限配置一致。
敏感操作二次确认 批量删除/配置下发/账号禁用 100% 有二次确认弹窗和影响预览。
操作可审计 所有写操作 100% 有操作人、时间、变更内容记录，可检索。
配置回滚 配置下发支持一键回滚，回滚 5 分钟内生效。
看板延迟 所有看板数据延迟 ≤ 5 分钟。

10. 风险与应对

风险 应对
后台 BFF 成为单点瓶颈 BFF 无状态，水平扩容；核心操作加请求限流（per user/per role）。
权限模型设计过早过细 v0.1 先跑通核心场景，权限颗粒度按需迭代，不做 over-engineering。
批量操作误操作影响大 设置上限+二次确认+操作日志+支持部分回滚，高危操作加 dry-run 预览。
各业务 API 返回格式不统一 BFF 层做适配标准化，业务 API 变更时 BFF 优先兼容，不直接暴露给前端。