知识库

需求设计文档.md

document
2026年7月27日阅读约 8 分钟1,429 字
5g2b_new
项目文档

更新于 2026年7月27日

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

1. 需求背景与建设目标

1.1 需求背景

随着中国移动 5G 2B 政企专网（智慧工厂、智慧港口等）规模的爆发式增长，网管中心和政企客户经理面临巨大的网络 SLA 履约压力 。
传统专网运维在面对数百个小区时，有以下痛点：

*
无法主动防范：缺乏主动预测能力，往往是专网客户（如工厂厂长）电话投诉 AGV 停摆后，移动运维才开始被动响应 。

*
定界扯皮时间长：专网环境复杂，当无线链路出现质量问题时，难以快速厘清是“移动侧网络问题”还是“厂区侧强电磁干扰”，导致客情关系紧张 。

*
固定阈值不灵活：工业专网具有强烈的“潮汐效应”（如生产班次差异），固定阈值告警会导致网管控制台产生严重的告警风暴或隐性漏报 。

1.2 建设目标

  • 打造移动标准网管系统：适配中国移动网管系统的 UI/UX 规范，提供规范化的白底蓝标管理后台，实现“全网监控、故障定界、趋势预测、专家应对”的一站式闭环。

  • 基于动态基线的隐性故障预测：通过轻量化算法构建动态基线，自动屏蔽潮汐周期波动，超出基线即判定为潜在故障 。

  • 多指标关联一键定界：基于移动通信专家经验，融合“性能指标”与“干扰指标”，实现故障秒级定界定因，秒出诊断报告 。

  • 轻量高效低成本：采用 MySQL 8 + Spring Boot 3.x + React 18 架构，通过预计算缓存机制，在几百个小区、千万级数据的体量下，依然保持极致的系统响应与低维护成本。

2. 系统整体技术架构

系统采用分层解耦架构。前端、后端和数据库各司其职，核心优化点在于将复杂的时序计算和预测异步化/预计算化，确保前台管理系统查询的极速响应。

数据源说明：性能和干扰数据由外部系统处理完成后，以固定字段模板 CSV 交付。本系统只使用 MySQL，直接导入与 性能表数据样例.csv、干扰表数据样例.csv 一致的 CSV 数据；不对接或引入其他数据库。

CSV 导入边界：本系统不改变 CSV 的字段值、单位、粒度或统计口径，也不执行清洗或聚合。导入功能只识别性能表和干扰表两类固定模板，检查文件类型、表头、必填列和重复文件后写入 MySQL。datatime 按 CSV 中的中国标准时间原样保存；文件名、哈希、导入时间、行数和结果记录在 tb_import_batch，用于追溯和防止重复导入。

graph TD
    subgraph Data_Layer [数据源与接入层]
        External[外部系统已处理数据] --> CSV[性能表 / 干扰表固定模板 CSV]
        CSV --> Import[CSV 模板校验与直接导入]
        Import -->|批量入库| DB_MySQL[(MySQL 8.0 唯一业务数据库)]
    end

    subgraph Service_Layer [Spring Boot 核心业务层]
        DB_MySQL -->|历史数据聚合| Scheduler[Spring Task 调度中心]
        Scheduler -->|每日凌晨| BaseCalc[Median/MAD 动态基线预计算]
        Scheduler -->|每 12 小时| PredictEngine[XGBoost 预测服务]
        
        BaseCalc -->|保存中位数、尺度、上下限和版本| DB_MySQL
        PredictEngine -->|保存未来48h预测走势| DB_MySQL

        DiagnosisEngine[规则诊断与工单建议] <-->|指标越界触发| DB_MySQL
    end

    subgraph Frontend_Layer [React 18 标准管理后台]
        React[React 18 Ant Design 框架] <-->|HTTP RESTful API| Service_Layer
        React <-->|WebSocket 实时告警推送| Service_Layer
        
        subgraph UI_Components [标准政企网管组件]
            UI_Filter[多维面包屑 & 多条件筛选区]
            UI_Line[ECharts 动态阈值区间图]
            UI_List[AntD 虚拟滚动表格]
            UI_Dialog[专家诊断与处置方案抽屉]
        end
        React --- UI_Components
    end

3. 后端落地方案

3.0 SLA 达标率计算定义

SLA 达标判定标准（默认值，最终以客户合同为准）：

核心指标 应用层存储值 默认达标阈值 统计粒度
无线接通率 0~1 小数 >= 0.990 小区小时级
无线掉线率 0~1 小数 <= 0.005 小区小时级
切换成功率 0~1 小数 >= 0.950 小区小时级

前端可按百分比显示，但所有比较、基线和配置均使用小数值，禁止直接把 1.0 与 99.0 比较。

有效时间片与达标率公式：

$$\text{小区SLA达标率} = \frac{\text{该小区通过的有效时间片数}}{\text{该小区有效时间片数}} \times 100\%$$
$$\text{场景SLA达标率} = \frac{\sum \text{场景内各小区通过的有效时间片数}}{\sum \text{场景内各小区有效时间片数}} \times 100\%$$
$$\text{数据完整率} = \frac{\text{按计划收到且校验通过的小时记录数}}{\text{应收到的小时记录数}} \times 100\%$$

说明：

  • 有效时间片：记录存在、批次校验通过，且该指标的原始分母大于 0。原始分母为 0、关键字段为空或未收到记录时，结果为 N/A，不得默认记为达标。
  • 综合 SLA：仅当合同要求的三个 KPI 均可评价时判定通过/失败；N/A 的处理由 tb_sla_config.no_data_policy 明确为“排除并展示”或“计为失败”。默认“排除并展示”，但数据完整率低于 min_data_completeness（默认 99%）时，报告状态为“数据不足，不出具达标结论”。
  • 统计周期默认为近 7 天，支持近 24 小时、近 30 天和自定义日期范围；所有时间范围以中国标准时间展示。
  • 场景筛选使用 first_scene_name、second_scene_name，并维护在 tb_cell_meta 中。
  • tb_sla_config 按客户和小区范围配置小数阈值、no_data_policy、min_data_completeness、生效时间和配置版本；配置变更需审计。

3.1 标准 CSV 直接入库

外部系统保证 CSV 表头、字段含义和数值单位与样例文件一致。本系统只按固定模板读取并写入 MySQL，不做字段转换、清洗、聚合或外部数据回写。

  • 固定模板与主键：

    • 性能表至少包含 datatime、cgi、nci、小区名称、场景字段、无线接通率、无线掉线率（小区级）、切换成功率、RRC连接最大数、上下行 PDCP PDU 字节数和 PRB 占用率。
    • 干扰表至少包含 datatime、cgi、nci、小区名称、场景字段、频段和平均底噪。
    • cgi 作为应用内小区标识，datatime 作为采集时间，均按 CSV 原值保存。tb_perf_hour 与 tb_interference_hour 的唯一键均为 (cgi, datatime)；tb_cell_meta 也以 cgi 为主键保存应用侧容量和展示元数据。

  • 导入规则：

    • 导入前检查 CSV 类型、UTF-8 编码、固定表头和必填列；缺列、格式错误或重复文件直接拒绝并记录到 tb_import_batch。
    • 导入时源字段按固定模板原样写入目标列，不改变字段值或单位。同一 (cgi, datatime) 已存在时拒绝该重复记录，不自动覆盖历史数据。
    • tb_import_batch 只保存文件名、文件哈希、导入时间、表类型、行数、成功数、失败数和错误摘要，不依赖外部数据库或清单文件。

  • 流量业务计算：CSV 中的 PDCP PDU 字节数原样保存。兼容旧系统口径，上、下行分别按 /1024/1024 展示为 GB，合计流量在后端按以下公式得到，不修改源 CSV 数据：

$$\text{流量(GB，旧系统口径)} = \frac{\text{上行PDCP PDU字节数} + \text{下行PDCP PDU字节数}}{1024 \times 1024}$$
  • MySQL 热数据边界：性能、干扰、基线、预测、告警、报告和配置均存于 MySQL。小时表按 datatime 月分区，所有查询必须带时间范围；原始小时数据保留 90 天，日 SLA 汇总、报告快照和审计数据按合同保留期保存，默认不少于 24 个月。

3.2 动态基线与预测算法（离线预计算）

  • 稳健动态基线（Median/MAD）：每天凌晨按 (cgi, metric_code, hour_of_day) 汇总近 30 个自然日的健康有效样本。少于 14 个有效日、数据完整率不足或样本已处于告警期时，不生成新基线，前端显示“基线数据不足”。
$$\text{center} = \operatorname{median}(x), \quad \text{scale} = \max(1.4826 \times \operatorname{MAD}(x), \text{floor})$$
  • 比值 KPI 的 floor=0.003，均以 0~1 小数计算；k=3 为默认可配置倍数。
  • 对“低值为劣化”的接通率和切换成功率：$\text{lower}=\max(0, \text{center}-k\times\text{scale})$；对“高值为劣化”的掉线率：$\text{upper}=\min(1, \text{center}+k\times\text{scale})$。
  • 平均底噪为高值劣化指标：$\text{upper}=\text{center}+k\times\text{scale}$，不使用固定 -105dBm。提供的 9 小时样例不足 14 个有效日，因此只能显示数据不足，不能据此生成 -113dBm 等阈值。
  • tb_cell_baseline 保存中心值、尺度、上下限、样本数、有效日期范围、参数版本和计算时间。合同阈值越界与动态基线越界分别产生“SLA 告警”和“趋势异常”，不混为同一种告警。

  • 趋势预测（XGBoost）：每 12 小时运行一次。每个小区-KPI 模型使用小时、星期、1/2/24/168 小时滞后值、流量、PRB 占用和当前基线特征预测未来 48 小时；训练条件为至少 30 天历史数据且近 30 天数据完整率不低于 95%。不满足条件时只展示动态基线。

    • tb_cell_prediction 保存预测值、目标时间、训练截止时间、特征版本、模型版本和验证状态；离线验证未通过的模型不得发布告警。
    • 当已发布模型在未来 12 小时连续两个时间片跨越动态阈值时，生成黄色预测性告警，告警包含预计劣化时间、预测值、基线值和建议核查窗口。

  • 预测告警处置原则：预测告警只生成核查建议和关联诊断，不直接执行参数调整、重启或其他网元操作。普通用户可认领并提交处置记录；需要参数变更时系统创建变更工单建议，由管理员按既有变更流程审批和回填验证结果。

3.3 规则诊断与分级响应机制（移动网管规范）

当核心 KPI 越界时，后台运行可解释规则进行辅助定界。规则输出的是“待核验原因”，不是自动确认的根因。

诊断触发条件：

  1. 合同 SLA 阈值或动态基线上下限越界
  2. 预测指标在未来 12 小时内预判将跌破基线（预测性告警）
  3. 手动触发：运维人员在故障历史表中点击"一键诊断"

诊断分类树逻辑：

graph TD
    A[无线掉线率/接通率劣化触发异常] --> B{排查物理层干扰: 平均底噪是否超出该小区动态阈值?}
    B -->|是，且上行质量/负荷证据齐全| C[候选: 上行噪声或干扰异常]
    B -->|否或证据不足| D{切换成功率低于动态下限且切换尝试数达到最小样本?}
    D -->|是| E[候选: 邻区关系或覆盖问题]
    D -->|否| F{RRC峰值/配置容量达到阈值且PRB负荷持续偏高?}
    F -->|是| G[候选: 容量瓶颈]
    F -->|否| H[待观察或人工补充证据]

    C -->|工单建议| C_S[核查上行频谱、现场干扰源和设备告警；不得以调整PCI作为干扰处置]
    E -->|工单建议| E_S[核验邻区、切换参数和覆盖测试；参数变更须审批]
    G -->|工单建议| G_S[核验RRC配置容量、PRB趋势和终端规模；按扩容流程处理]

诊断结果输出：

  • 候选原因、命中规则、阈值版本、原始指标值、样本量和缺失证据项
  • 关联指标与处置建议；无充分证据时明确显示“待人工确认”
  • 变更工单建议、处置记录、验证结果和关闭原因
  • 诊断时间、规则版本和操作审计号

tb_cell_meta 必须维护 rrc_capacity 等配置容量。切换判断使用 tb_sla_config.min_ho_attempts，不再使用固定 92%；所有网元参数调整均由既有变更流程执行，系统只记录建议和结果。

3.4 应用层数据模型与留存

表 主键/关键约束 用途
tb_import_batch 文件哈希唯一 CSV 文件名、导入结果和错误摘要
tb_cell_meta cgi 主键 小区、场景、频段、RRC 配置容量和状态
tb_perf_hour (cgi, datatime) 唯一 CSV 原始性能字段、SLA 计数、流量和负荷
tb_interference_hour (cgi, datatime) 唯一 CSV 原始干扰字段和平均底噪
tb_sla_config 作用域、版本、生效期唯一 小数阈值、最小样本、无数据策略和完整率要求
tb_sla_daily (cgi, stat_date, config_version) 唯一 可评价/通过/N/A 时间片、完整率和日 SLA 汇总
tb_cell_baseline / tb_cell_prediction 小区、指标、目标时段、版本唯一 基线、预测和模型发布记录
tb_alarm / tb_alarm_action 告警指纹唯一 / 动作序号唯一 告警状态、认领、处置、验证、关闭和重开
tb_event_log event_id 主键 告警、操作、投诉和备注的时序标注
tb_report_task / tb_report_snapshot 任务号 / 报告版本唯一 PDF 异步生成、下载授权和不可变报告快照
tb_user / tb_audit_log 用户名唯一 / 审计号主键 两类角色、登录和敏感操作追溯

所有高频小时表按月分区；所有业务查询必须包含时间范围。报告快照与审计日志不随 90 天原始热数据清理。

4. 前端落地方案（中国移动标准网管风格）

前端设计采用中国移动官方后台管理系统风格：白底蓝标、灰青边框、浅色扁平化、信息高密度。整体给人以严谨、专业、高效的业务系统质感。

4.1 界面配色方案 (Color Palette)

模块/状态 官方颜色名称 推荐十六进制 (Hex) 视觉用途与效果
主背景 移动纯净白 (Pure White) #FFFFFF 页面卡片底色、表格背景、弹窗底色，极简素雅。
系统背景 浅网管灰 (Light Grey) #F4F6F9 整个页面底色，与白色卡片形成微弱阴影对比。
主色调 中移经典蓝 (China Mobile Blue) #0085D0 导航栏、主按钮、标签页激活态、核心折线。
辅助/基线色 科技天蓝 (Sky Blue) #E6F7FF 动态阈值阴影带色、表格选中的高亮背景色。
边框/分割线 浅石墨灰 (Border Grey) #E5E7EB 极细边框（1px），用于面包屑、表头分割。
正常状态 5G 达标绿 (Success Green) #52C41A SLA 100% 达标、基线以内指标、服务运行良好状态。
中度告警 预警琥珀黄 (Warning Orange) #FA8C16 预测未来瓶颈、临界值超标状态。
严重故障 警示中国红 (Danger Red) #F5222D 超出动态基线、高危告警触发状态。
文字 (主) 商务深灰 (Primary Text) #1F2937 页面主标题、表格数据、强对比文字。
文字 (副) 哑光中灰 (Muted Text) #6B7280 面包屑导航、小图标、表格列头说明。

4.2 经典 B/S 后端管理布局方案

系统弃用大屏设计，使用标准后台管理系统的 100% 宽度自适应网格布局（左侧导航 + 右侧内容区），信息高密度平铺，更符合运维人员日常在 PC 端的排查习惯：

+-----------------------------------------------------------------------------------------------------------------+
| 【顶部导航】  [logo] 中国移动5G政企专网智能运维中心     |   [菜单] SLA总览  [菜单] 故障分析  [菜单] 性能预测  [🔔14]  [用户头像 👤] |
+-----------------------------------------------------------------------------------------------------------------+
|  【左导航栏】  |  【右侧内容区】 面包屑: 首页 / 5G专网分析 / 小区深度透视                                                         |
|               | ----------------------------------------------------------------------------------------------- |
|   SLA 核心看板 |  【筛选控制栏 (卡片白底)】                                                                       |
|   - 综合达标率 |   区域: [全部 ⬇]   覆盖场景: [工厂 ⬇]   严重程度: [全部 ⬇]  时间范围: [近7天 ⬇]   [查询 🔍] [导出报告 📄]  |
|               | ----------------------------------------------------------------------------------------------- |
|   性能指标监控 |  【核心卡片组 (白底蓝字)】                                                                       |
|   - 无线接通率 |   [卡片1: 监测小区数] 524个  [卡片2: 当前告警数] 14个  [卡片3: 工厂场景达标率] 99.2%                      |
|   - 无线掉线率 | ----------------------------------------------------------------------------------------------- |
|   - 多小区对比 |  【主分析面板 (左右两栏分栏)】                                                                     |
|   - 小区拓扑   |   (左侧 65%) : [Tab: 无线接通率基线 | Tab: 48h流量预测]   (右侧 35%) : [一键规则诊断面板]              |
|   干扰水平监控 |   [ECharts 图表: 白底 + 蓝色实线 + 天蓝基线带 + 事件标注]  [抽屉卡片: 候选原因、证据、处置建议]            |
|   - 平均底噪   | ----------------------------------------------------------------------------------------------- |
|               |  【底部面板 (100% 展开)】                                                                        |
|   告警通知中心 |   [故障历史分析大表 (AntD 虚拟滚动)] 包含: 小区名 | 时间 | 触发算法 | 候选原因 | 严重度 | 状态 | 操作 (认领 / 一键诊断 / 提交处置)  |
+-----------------------------------------------------------------------------------------------------------------+

说明：

  • 顶部导航栏铃铛图标 🔔 后的数字"14"表示当前未读告警数量，点击展开告警通知中心下拉列表。
  • 筛选控制栏中"覆盖场景"筛选器替代了原"业务场景: AGV"，数据来源为 first_scene_name 和 second_scene_name 字段，支持"工厂/港口/园区"等一级场景和"AGV区域/生产线/仓储区"等二级场景的二级联动筛选。
  • 左侧导航提供"多小区对比"、"小区拓扑"和"告警通知中心"功能入口；不设置专家知识库模块。
  • 右侧筛选栏新增"导出报告"按钮，用于一键生成 PDF 格式月度 SLA 报告。

4.3 标准管理后台交互细节设计

4.3.1 移动白底风格动态阈值基线图 (ECharts)

  • 背景设计：采用纯白背景，去除所有不必要的网格阴影。
  • 基线带渲染：利用 ECharts 的二阶面积堆叠（areaStyle），将动态基线上下限渲染为一层淡淡的天蓝色半透明填充带（rgba(0, 133, 208, 0.06)），代表安全的动态波动范围 。
  • 实际指标线：采用代表中国移动官方的中移蓝实线（#0085D0）。一旦接通率/掉线率跌出蓝色安全带，线上的转折拐点自动转为红色，直观明了，没有任何视觉干扰。
  • 时序事件标注层：在折线图上叠加事件标注点（ECharts markPoint），用于展示关键运维事件：
    • 🔴 红色三角标：系统触发告警的时间点，hover 显示告警类型和触发值
    • 🟡 黄色菱形标：预测性告警的时间点，hover 显示预测值和建议处置时间窗口
    • ⚙️ 灰色齿轮标：运维操作记录（参数调整、重启、切换优化），hover 显示操作人、操作内容和工单号
    • 📞 紫色电话标：客户投诉记录，hover 显示投诉时间和投诉内容摘要
    • 事件标注数据来源于 tb_event_log 事件日志表，支持运维人员手动添加备注事件

4.3.2 告警通知中心（WebSocket 实时推送）

  • 入口设计：顶部导航栏右侧放置铃铛图标 🔔，右上角红色角标显示未读告警数量。
  • 告警列表面板：点击铃铛图标，下拉展开告警列表（最近 20 条），每条告警包含：
    • 告警级别图标（🔴 严重 / 🟡 预警 / 🔵 提示）
    • 小区名称、告警类型、触发时间
    • 快捷操作按钮：[查看详情] [认领] [一键诊断] [标记已读]
  • 告警状态流转：
    • 新建：告警首次触发，推送到通知中心，角标计数+1；查看详情只记录“已读”，不改变处置状态。
    • 已确认/已认领：普通用户或管理员主动确认并认领，记录责任人和首次响应时间。
    • 处理中：认领人填写处置记录、关联工单号或提交核查结果后进入处理中。
    • 待验证：处置完成后等待连续有效 KPI 恢复或现场验证；源侧恢复事件不能直接关闭预测性告警。
    • 已关闭/已重开：管理员核验关闭原因、处置记录和验证结果后关闭；同一告警再次满足触发条件时重开并保留完整生命周期。
    • 同一小区、指标、告警类型在配置的去重窗口内合并为一条告警，tb_alarm_action 保存每次认领、升级、处置、验证和关闭动作。
  • 告警升级规则（可配置）：
    • 严重告警超过 30 分钟未认领，预警告警超过 2 小时未认领时，按内网已接入的企业微信、短信或邮件通道发送提醒。
    • 每次外部通知的投递结果、失败原因和重试次数必须记录；通道不可用时在值班台显示失败状态，不得静默丢弃。
  • 告警过滤与搜索：告警列表支持按级别、小区、时间范围、处理状态筛选，支持关键词搜索小区名称和告警类型

4.3.3 多小区横向对比功能

  • 交互入口：在”性能指标监控”左侧导航中新增子菜单”多小区对比”。
  • 小区选择器：顶部提供多选下拉框，支持最多同时选择 5 个小区进行对比（基于 Ant Design Select 组件，mode=”multiple”，showSearch 支持小区名模糊搜索）。
  • 对比视图布局：
    • 上半部分：5 条折线叠加在同一个 ECharts 图表内，每个小区用不同颜色区分（中移蓝 #0085D0、橙色 #FA8C16、绿色 #52C41A、紫色 #722ED1、青色 #13C2C2），legend 图例可点击切换显示/隐藏。
    • 下半部分：对比表格，横向展示 5 个小区的关键指标统计值（近 7 天平均接通率、掉线率、告警次数、SLA 达标率），支持按列排序快速识别最差小区。
  • 应用场景：排查同站多小区干扰、对比邻区切换性能、识别区域性劣化问题。

4.3.4 “卡片式”一键诊断抽屉 (Drawer)

  • 交互逻辑：在底部的”故障历史分析大表”中，运维人员点击任意一行的”一键诊断”操作，页面右侧会优雅地滑出一个标准抽屉（Drawer）。
  • 内容设计：
    • 候选原因标签：顶部以红色或黄色标签展示“上行噪声待核验”“邻区/覆盖待核验”等候选原因，不把规则命中展示为已确认根因。
    • 证据区：展示命中指标、阈值、样本量、规则版本和缺失证据；不展示无统计定义的“贡献度百分比”。
    • 处置建议区：展示核查、变更工单建议和验证条件；参数调整均标记为“需审批”，不能由页面直接下发。
    • 处置记录区：认领人填写现场处置、外部工单号和验证结果后提交，记录自动关联到告警生命周期日志。

4.3.5 信息高密度与 Ant Design 虚拟滚动表格

  • 问题解决：面对几百个小区的长周期时序表格，前端不采用整页刷新或极长下拉。
  • 实现逻辑：后端按筛选条件、排序字段和游标分页查询，单次最多返回 200 条；前端使用 Ant Design 原生虚拟表格。虚拟滚动只解决 DOM 数量，不替代数据库分页、索引和聚合查询。

4.3.6 月度 SLA 报告一键导出（PDF 格式）

  • 交互入口：在”SLA 核心看板”页面顶部，放置”生成月度报告”按钮（蓝底白字，icon 为文件图标 📄）。
  • 报告生成流程：
    1. 用户点击按钮，弹出配置对话框，选择报告周期（默认上月，支持自定义起止日期）、客户名称（从 tb_customer 客户表拉取）、覆盖小区范围（默认该客户关联的所有小区）。
    2. 点击”生成报告”后创建 tb_report_task 任务，由 Spring Task 使用 Apache PDFBox 异步生成；生成过程不依赖 Redis。
    3. 生成完成后写入不可变 tb_report_snapshot，记录报告参数、数据截止时间、配置版本、文件哈希和下载授权；前端下载文件名为 5G专网SLA月报_{客户名称}_{YYYYMM}.pdf。
  • 报告内容模板：
    • 封面：中国移动 Logo、报告标题、客户名称、报告周期、生成日期
    • 第1页：SLA 达标率总览：饼图展示达标/未达标小区占比，折线图展示月度达标率趋势
    • 第2页：故障记录汇总：表格列出本月所有告警记录（时间、小区、诊断结论〔候选/确认〕、处置情况、闭环时长）
    • 第3页：关键指标统计：接通率/掉线率/切换成功率的月度均值、最大值、最小值，柱状图对比各小区表现
    • 第4页：处置情况说明：汇总本月运维操作记录、优化措施和效果评估
    • 尾页：移动方经办人签名栏、客户方确认签名栏
    • PDF 使用内网已部署的中文字体，生成失败时保留失败原因并允许重试；报告快照不随 90 天原始数据清理。

4.3.7 小区拓扑与厂区平面视图（内网可用）

  • 数据来源：优先使用 tb_cell_meta 的小区经纬度、邻区关系和客户提供的厂区平面图；不依赖公网地图服务。
  • 交互方式：支持按告警状态、覆盖场景、频段过滤小区，在拓扑或平面图上查看告警数量、相邻关系和最近 KPI；无坐标数据时自动降级为基于小区/邻区关系的拓扑图。
  • 资产管理：离线底图、厂区图片和字体统一随部署包或内网文件服务发布，并记录版本和更新时间。

5. 部署与非功能要求

5.1 容量、性能与留存

  • 以 500 小区、90 天、性能/干扰两张小时表估算，热数据约 216 万行；MySQL 8 采用月分区、(cgi, datatime) 唯一键和日 SLA 汇总后可承载。所有本系统需要的性能、干扰和应用结果均保存于 MySQL，不引入其他数据库。
  • 验收压测基线为 500 小区、90 天热数据、50 个并发会话：告警列表和 SLA 总览 P95 <= 2 秒，近 7 天趋势和多小区对比 P95 <= 3 秒。PDF 为异步任务，不纳入同步接口时延。
  • 所有高频查询必须含时间范围和分页/游标；超过 90 天的原始趋势不在本系统在线查询范围内，如合同要求更长查询期，须在上线前调整 MySQL 留存策略和容量预算。

5.2 内网部署与外部依赖

  • 生产环境不依赖公网：外部系统 CSV 交付目录或上传接口、Maven/NPM 镜像、离线底图、厂区图片、中文字体和容器/安装包均部署在内网可访问位置。
  • 企业微信、短信、邮件等通知通道按实际内网能力启用；未接入或投递失败时，告警仍在值班台可见并记录失败原因。
  • PDF、地图和静态资源必须在隔离环境完成渲染验证，禁止运行时从外网下载字体、底图或脚本。

5.3 可用性、安全与审计

  • 多实例部署时，Spring Task 通过 MySQL 锁表保证同一批次、基线和预测任务只执行一次；任务状态、失败和重试次数写入业务表。
  • 所有服务使用内网 HTTPS 证书，密码使用强哈希保存；系统时间与内网 NTP 同步，保证告警、报告和审计的时间可追溯。
  • 每日备份配置、报告快照和审计日志，并至少每季度执行一次恢复演练；审计日志只允许追加，普通用户无修改和删除权限。

6. 用户角色与权限设计

6.1 角色定义

V2.1 采用固定的两类角色，不实现地市、客户经理或多租户行级权限。系统部署范围内的业务数据对已认证用户可见；客户信息仅用于筛选和生成报告，不作为权限维度。

角色名称 角色编码 数据权限范围 功能权限
管理员 ROLE_ADMIN 当前部署范围内全部数据 全部查看与处置能力；用户管理、SLA/基线/告警配置、批次回补、映射发布、审计查询、告警最终关闭和重开
普通用户 ROLE_USER 当前部署范围内全部数据 SLA 总览、故障分析、性能预测、多小区对比、拓扑视图、告警查看/认领/诊断、处置记录、报告生成和下载；不可修改配置、用户、映射或最终关闭告警

6.2 权限控制实现

  • 功能权限：基于 Spring Security 注解控制接口。角色名称已经包含 ROLE_ 前缀，因此统一使用 hasAuthority/hasAnyAuthority，避免 hasRole 的二次前缀问题。

    • 管理接口示例：@PreAuthorize("hasAuthority('ROLE_ADMIN')")。
    • 读写运维接口示例：@PreAuthorize("hasAnyAuthority('ROLE_ADMIN', 'ROLE_USER')")。
    • 告警最终关闭、映射发布、批次回补和阈值修改只允许管理员；普通用户的关闭申请进入待验证状态。

  • 数据访问：V2.1 不使用 MyBatis 动态拼接行级过滤。所有 API 仍必须按用户身份认证并按上述功能权限授权；如后续引入跨客户/跨地市隔离，需单独设计数据域模型和回归测试，不在本版本隐式实现。

  • 前端菜单渲染：前端根据 JWT 中的两类角色隐藏管理菜单，但隐藏菜单不是安全边界，后端注解必须覆盖全部受保护接口。

6.3 用户管理与审计

  • 用户管理界面（仅管理员可访问）：

    • 创建用户必填用户名、密码、真实姓名、手机号、角色和启用状态；角色只允许 ROLE_ADMIN 或 ROLE_USER。
    • 支持 CSV 批量导入，两类角色之外的值直接拒绝；密码按平台安全策略加密存储。

  • 操作审计日志：

    • 系统记录登录成功/失败、权限变更、批次回补、告警认领/关闭/重开、诊断、阈值修改、报告生成和下载。
    • 日志包含操作人、时间、类型、对象、前后值、IP、请求号和结果；普通用户不可修改或删除审计记录。
    • 管理员可查询和导出审计日志；日志与报告快照按合同保留期保存，不少于 24 个月。

7. 系统演进与落地计划

V2.2 以固定 CSV 模板先行、并行开发、集成后试运行为原则。以下任务关系和里程碑一致，所有日期按项目日历确认后执行。

gantt
    title 中移 5G 专网运维管理后台 V2.2 落地路线
    dateFormat  YYYY-MM-DD
    section 1. 数据契约与基础能力
    数据模型、SLA口径、固定CSV模板    :active, p1, 2026-07-16, 7d
    两类角色、审计和前端框架           :p2, 2026-07-16, 5d
    CSV模板校验、直接导入与批量落库   :p3, after p1, 8d
    SLA汇总与Median/MAD基线            :p4, after p1, 8d
    看板、筛选和时序图                 :p5, after p2, 10d

    section 2. 核心业务并行开发
    XGBoost预测与规则诊断              :p6, after p4, 8d
    告警状态机、处置与PDF报告          :p7, after p3, 8d
    多小区对比与离线拓扑视图           :p8, after p5, 7d

    section 3. 集成、试运与上线
    端到端联调、权限和容量压测         :p9, after p7, 7d
    内网部署、安全检查和UAT            :p10, after p9, 5d
    生产部署与用户培训                 :p11, after p10, 3d
    试运行、问题修复和回归             :p12, after p11, 10d
    验收资料与上线评审                 :p13, after p12, 5d

关键里程碑节点：

  • M1（数据通路可用）：固定 CSV 模板校验、MySQL 标准表、两类账号和基础看板可用，预计 2026-07-31 完成。
  • M2（核心算法和闭环就绪）：SLA、基线、预测、规则诊断、告警和报告可联调，预计 2026-08-08 完成。
  • M3（集成验收完成）：前后端、权限、容量和内网部署验证通过，预计 2026-08-20 完成。
  • M4（正式上线）：试运行、回归和上线评审完成，预计 2026-09-07 正式上线。

关键风险与应对：

  1. CSV 模板变更风险：上线前须由外部系统确认性能表和干扰表模板与样例一致；表头、必填列或数值单位变化时，导入直接拒绝并由双方更新接口约定。
  2. 数据质量与模型准确率：少于 30 天历史、完整率低于 95% 或离线验证不通过的小区不发布预测，只展示基线和数据质量状态。
  3. 内网依赖限制：CSV 交付通道、通知通道、离线地图、中文字体和部署依赖须在 UAT 前完成内网验证；外部通知失败必须可见、可重试。
  4. PDF 报告生成性能：使用 MySQL tb_report_task 加 Spring Task 异步执行，生成后保存报告快照；高峰期按任务队列限流，不阻塞 API 请求。