中国移动 5G 专网智能运维与故障诊断系统 - 前端建设方案

项目名称：5G 2B 政企专网智能运维与故障诊断系统
文档版本：V2.2
修订日期：2026-07-16
依据文档：需求设计文档.md、需求文档修订说明.md

---

1. 文档定位与边界

本文档只定义前端的视觉规范、通用交互、工程实现和交付约束，不重复定义业务功能。

数据口径、SLA 计算、基线与预测规则、诊断规则、告警生命周期、PDF 内容、CSV 导入规则和权限范围，以 需求设计文档.md 为唯一依据。前端不得在页面中自行推导、修改或覆盖这些规则。

前端建设应遵循以下边界：

• 前端只通过后端接口使用固定 CSV 导入后的 MySQL 数据；不在浏览器中做 CSV 转换、清洗、聚合或外部数据回写。
• 所有时间按中国标准时间展示，指标比较和阈值计算由后端按原始小数口径完成，前端仅负责格式化展示。
• 诊断结果按需求文档展示为“候选原因”或“待人工确认”，并呈现后端返回的证据、建议和状态。
• 前端不能直接下发参数调整、重启或其他网元操作；涉及变更时只展示后端返回的工单建议和审批状态。
• PDF 由后端的 MySQL 报告任务、Spring Task 和 PDFBox 生成。前端只提交任务、查询状态和下载已授权快照。
• 页面菜单只适配 ROLE_ADMIN 和 ROLE_USER 两类角色。前端隐藏菜单不构成安全控制，后端权限校验是唯一安全边界。

---

2. 视觉设计系统

2.1 风格原则

采用中国移动标准网管风格：白底蓝标、浅色扁平化、信息高密度、PC 后台布局。页面以表格、筛选和图表为主，不采用大屏化、重装饰、渐变玻璃态或消费级大圆角设计。

默认采用左侧导航、顶部操作区和主内容区的 B/S 布局。内容区保持固定的信息层级：筛选与状态在上，趋势或结果在中，明细表在下。

2.2 色彩

用途	色值	使用要求
主色	#0085D0	主按钮、激活导航、主折线和链接
主色深色	#006BA6	悬停和按下状态
浅蓝	#E6F7FF	选中背景、动态基线区间
页面背景	#F4F6F9	页面底色
内容底色	#FFFFFF	表格、抽屉、弹窗和内容面板
边框	#E5E7EB	1px 边框和分割线
正常	#52C41A	正常和达标状态
预警	#FA8C16	预测性告警和需关注状态
严重	#F5222D	严重异常和错误状态
主文字	#1F2937	标题和主要数据
次文字	#6B7280	辅助说明、时间和单位

颜色必须与文字、图标或标签共同表达状态，不允许只依赖颜色。严重状态不使用持续闪烁，避免干扰长时间值守。

2.3 字体、间距与形状

项目	规范
中文字体	PingFang SC、Microsoft YaHei、系统无衬线字体
数值字体	Consolas、Monaco 等等宽字体
常规正文	14px / 22px
页面标题	20px / 28px，600 字重
区块标题	16px / 24px，600 字重
辅助文字	12px-13px
间距	以 4px 为基本单位，常用 8px、12px、16px、24px
圆角	默认 4px；表格和数据密集区域使用 0px-2px
阴影	仅用于下拉菜单、弹窗和抽屉层级，不作为卡片装饰

数值、单位和时间需对齐展示。比例指标可以按百分比显示，但不得改变后端返回的小数含义。

2.4 图标与可访问性

优先使用 Ant Design Icons。图标按钮必须有文字标签或悬浮提示；表格内操作使用清晰的文本或图标加文字，不用无说明的自定义符号替代关键动作。

键盘焦点、错误信息、加载状态和空状态必须可见。表单控件须关联标签，状态颜色与文字说明同时出现。

---

3. 通用交互规范

3.1 加载、错误与空状态

• 请求期间显示局部加载状态，避免整页无反馈。
• 查询失败时展示可读错误和重试入口，不静默吞掉错误。
• 无数据、基线数据不足、无权限和任务处理中使用不同的空状态文案。
• 失败或未完成的报告任务展示后端返回的原因和可用的重试状态，不伪造进度或结果。

3.2 筛选与时间

筛选条件由当前页面的需求决定。时间范围统一支持近 24 小时、近 7 天、近 30 天和自定义日期范围，并按中国标准时间显示。

场景筛选使用后端提供的 first_scene_name 和 second_scene_name。上级条件变化时，下级条件清空。筛选、排序和分页参数必须随查询一起提交，由后端完成结果计算。

3.3 表格与长列表

• 表头、状态列和操作列保持稳定宽度；数值右对齐，时间使用统一格式。
• 后端使用分页或游标返回结果，单次最多 200 条；虚拟滚动只减少浏览器 DOM 数量，不代替后端分页、索引或聚合。
• 支持需求已定义的筛选、排序和查看详情入口，不在本文档扩展业务动作。
• 操作状态以服务端结果为准；前端不因用户点击而预先把告警标为关闭。

3.4 图表与状态呈现

• ECharts 负责趋势、基线区间、预测和事件标注的可视化，不在浏览器中计算基线、预测或诊断结果。
• 图表必须区分实际值、后端返回的基线范围和预测数据；数据不足时明确展示“基线数据不足”或对应状态。
• 事件标注只展示后端记录的告警、操作、投诉和备注，不虚构事件类型或业务数据。
• 图表和表格共享同一时间范围及筛选条件，避免同页数据口径不一致。

3.5 弹窗、抽屉与异步任务

弹窗用于确认或填写表单；抽屉用于查看详情和提交需求已定义的处置记录。危险操作必须显示影响对象与权限限制。

告警状态、诊断内容和报告任务状态均由后端返回。普通用户提交处置记录后，页面应呈现待验证状态；只有管理员完成后端定义的验证和关闭流程后，界面才显示已关闭或已重开。

---

4. 前端工程实现

4.1 技术基线

层面	选型或约束
框架	React 18
语言	TypeScript
组件库	Ant Design
图表	ECharts
构建	Vite
路由	React Router
通信	HTTPS RESTful API、WebSocket 告警推送
部署	内网环境，静态资源和字体不在运行时从公网加载

以 React 组件状态和 Context 管理页面级、会话级状态。只有在项目已有依赖且确实无法满足跨页面同步时，才引入额外状态管理或请求缓存库。

4.2 最小目录结构

src/
  app/          # 应用入口、路由和权限壳
  pages/        # 需求已定义页面的视图组合
  components/   # 通用布局、表单、图表和表格封装
  services/     # HTTP、WebSocket 和接口类型
  styles/       # 设计令牌与全局样式
  types/        # 共享类型

通用组件优先复用 Ant Design。仅当同一视觉或交互模式在多个页面重复出现时，才抽取本地组件；本地组件不定义诊断规则、通信契约或业务数据结构。

4.3 接口、鉴权与实时消息

• 接口契约由后端与需求文档确定；本文档不定义接口地址、请求字段或前端模拟数据。
• 所有接口调用携带既有认证信息，统一处理 401、403、网络异常和服务端业务错误。
• 根据 JWT 中的 ROLE_ADMIN、ROLE_USER 渲染菜单和可操作态；收到权限变化或鉴权失败后重新拉取会话状态。
• WebSocket 只用于后端推送的告警和任务状态更新。连接断开时按有限退避重连，恢复后重新获取服务端权威状态。
• 内网通知通道及投递结果由后端处理和审计，前端在恢复连接后重新获取服务端权威状态。

---

5. 性能、质量与部署

5.1 性能责任边界

以 需求设计文档.md 的 500 小区、90 天热数据、50 个并发会话为验收基线：

场景	验收目标
告警列表与 SLA 总览	P95 <= 2 秒
近 7 天趋势与多小区对比	P95 <= 3 秒
PDF 生成	异步任务，不纳入同步接口时延

前端通过路由懒加载、按需渲染图表、取消失效请求和服务器分页控制资源占用。不得以本地降采样、缓存或虚构统计替代后端的真实查询结果。

5.2 最小质量检查

上线前至少验证：

• 两类角色的菜单可见性和受限操作提示正确；后端拒绝时页面正确处理。
• 筛选、分页、图表和明细表使用同一查询条件。
• 告警、诊断、报告任务和下载状态以服务端返回为准。
• 长列表在分页和虚拟滚动条件下保持可用，图表在无数据和数据不足状态下正确展示。
• 内网部署后无运行时公网字体、CDN、地图或脚本依赖。

5.3 部署约束

生产构建产物、字体、图标和其他静态资源必须随内网部署包或内网文件服务发布。前端配置仅保存环境地址等部署参数，不保存 SLA 阈值、角色规则或诊断规则。

---

6. 交付与验收对齐

前端工作与 V2.2 里程碑同步，不另行定义业务范围或排期：

里程碑	日期	前端交付重点
M1	2026-07-31	工程基础、两类角色界面、基础看板与导入管理界面接入
M2	2026-08-08	SLA、基线、预测、诊断、告警和报告的界面联调
M3	2026-08-20	端到端联调、权限、容量与内网部署验证
M4	2026-09-07	试运行、回归和上线评审支持

交付物包括：设计令牌与通用交互规范、前端源代码和构建产物、内网部署说明、核心流程验证记录。业务规则、接口明细、页面功能原型和处置方案由原始需求设计文档及后端接口契约维护，不在本文档重复定义。