- 闭环状态流转自动记录接单/闭环时间,状态值校验;按断站分级判定响应时限 (及时/超时/超时未响应/未到期/无记录),新增及时响应率、平均闭环时长、超时未闭环指标与筛选 - 新增治理成效评估 /api/effect:分界日期前后指标对比与问题站点逐站改善判定 - 新增站型阈值系数(实际阈值 = 场景阈值 × 站型系数)及配置接口与页面 - 样例数据新增接单/闭环时间(独立随机数,原字段不变),导入支持并校验 - 新增 tests/test_api.py(权限、导入模板、闭环流程、站型系数、成效评估、无数据边界) - 修复:新流水无告警匹配时根因分析报错;空筛选时超长站点清单返回 500 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
146 lines
13 KiB
Markdown
146 lines
13 KiB
Markdown
# 5G 基站退服时长智能分析与故障闭环管控系统
|
||
|
||
Python + Flask + SQLite 后端,React 19 + [Liquid Glass UI](https://tsdsj.github.io/liquid-glass-react/)(`@ttqtt/liquid-glass-react`)+ ECharts 前端。
|
||
|
||
## 用 PyCharm 运行
|
||
|
||
1. PyCharm → `File > Open`,选择 `Local-sever` 文件夹。
|
||
2. 配置解释器(Python 3.9+),在 Terminal 中安装依赖:
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
3. 右键 `app.py` → `Run 'app'`,浏览器打开 <http://127.0.0.1:5000>。
|
||
|
||
前端免构建:`static/js/` 下就是浏览器直接运行的源码,**运行和修改都不需要 Node.js**,改完刷新浏览器即可。
|
||
|
||
首次启动会自动创建 `data/outage.db`,并生成样例数据(约 1 秒)。删除该文件即可重置数据库。
|
||
|
||
| 账号 | 密码 | 角色 |
|
||
|---|---|---|
|
||
| admin | admin123 | 管理员:全部功能(含用户管理,系统不开放自助注册) |
|
||
| user | user123 | 普通用户:查询、统计、看板、导出,以及更新闭环进度 |
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
Local-sever/
|
||
├── app.py Flask 路由:认证与权限、增删改查、导入、统计、导出、日志、用户;托管前端页面
|
||
├── core.py 核心算法:建库入库、时间窗标定、三级根因关联、告警关联量化、时长与考核指标
|
||
├── importer.py 数据导入:读取 Excel/CSV、自动识别文件类型、逐行校验(见下方“支持导入的文件”)
|
||
├── data_gen.py 第 18 题数据生成器(Data-Generated-Core-Py/data.py 的改进版,字段口径一致)
|
||
├── bench.py 性能与时长准确率测试(对应开题报告预期目标)
|
||
├── tests/ 根因准确率扰动测试、考核指标口径测试(见下方“测试”)
|
||
├── data/ sites.csv / data_outage.csv / data_alarm.csv 种子数据,outage.db 自动生成
|
||
├── static/ 前端(全部可直接阅读和修改)
|
||
│ ├── index.html 页面入口,importmap 把 'vendor' / 'echarts' 指向 vendor/ 下的文件
|
||
│ ├── app.css 全部样式(Apple 系统色与背景、布局、响应式)
|
||
│ ├── js/
|
||
│ │ ├── main.js 入口:GlassProvider(跟随系统深浅色)+ ToastProvider;含 html`` 写法说明
|
||
│ │ ├── App.js 外壳:登录判断、分组侧边栏(窄屏为抽屉)、顶栏全局筛选、页面切换(#/页面id)
|
||
│ │ ├── Login.js 登录页
|
||
│ │ ├── api.js api() 请求、useFetch() 页面取数、download() 导出、useApp() 全局上下文
|
||
│ │ ├── format.js 数字格式、Apple 系统色、根因颜色
|
||
│ │ ├── components/ ui(卡片/指标/标签/下拉)、DataTable(表格+分页)、FormDialog、EChart、icons
|
||
│ │ └── pages/ index.js 页面注册表 + 10 个业务页面,一页一个文件
|
||
│ └── vendor/ 第三方库(React、液态玻璃组件库、htm、ECharts),压缩文件,不要手改
|
||
```
|
||
|
||
## 修改前端
|
||
|
||
前端是 React,但**不需要编译**:组件用 `html\`...\`` 模板([htm](https://github.com/developit/htm))书写,浏览器直接运行。和 JSX 的区别只有三点:
|
||
|
||
```js
|
||
// JSX: <Section title="标题" span={6}><EChart option={opt}/></Section>
|
||
// htm:
|
||
html`<${Section} title="标题" span=${6}><${EChart} option=${opt}/></${Section}>`
|
||
```
|
||
|
||
1. 组件名写成 `<${Section}>`,结束标签写成 `</${Section}>`;
|
||
2. 变量和表达式写成 `${...}`;
|
||
3. 嵌套模板也用 `html\`...\``;一个模板有多个并列根元素时用 `<${Fragment}>…</${Fragment}>` 包起来。
|
||
|
||
### 新增一个页面
|
||
|
||
1. 在 `static/js/pages/` 新建 `Xxx.js`,默认导出组件;用 `useApp()` 取全局筛选,`useFetch(url, 参数)` 请求数据。
|
||
2. 在 `pages/index.js` 中加一行注册(选择所属分组);需要图标时在 `components/icons.js` 加一条路径。
|
||
3. 刷新浏览器。
|
||
|
||
### 升级第三方库(很少需要)
|
||
|
||
`static/vendor/` 由 `tools/vendor-build/`(不在本仓库中)一次性生成。只有升级 React、组件库或 ECharts,或需要新的 React API / 新的图表类型时才需要 Node.js 20.19+:
|
||
|
||
```bash
|
||
cd tools/vendor-build
|
||
npm install
|
||
npm run build # 重新生成 ../../static/vendor/
|
||
```
|
||
|
||
## 前端设计说明
|
||
|
||
- **Apple 风格**:背景 #f5f5f7(深色 #000),卡片纯白(深色 #1c1c1e),颜色全部取自 Apple 系统色(systemBlue #007aff 等),字体优先 SF / 苹方。
|
||
- **分层**:玻璃材质只用于侧边栏、顶栏、弹窗、提示等浮动操作层;指标、图表、表格放在不透明卡片上(层级清晰,也避免大面积 `backdrop-filter` 的性能开销)。
|
||
- **窄屏**:侧边栏收进抽屉,顶栏只有菜单、标题、筛选三个控件,筛选项点开才显示,首屏直接看到数据。
|
||
- **性能**:页面按需懒加载;ECharts 只注册 4 种图表并在登录后才加载;图表配置内容不变时不重绘;后端明细缓存到数据变化为止。
|
||
- **无障碍**:跟随系统深浅色、减少动效;状态标签除颜色外始终带文字。
|
||
|
||
## 数据说明(对齐 _数据集总索引.md 第 18 题)
|
||
|
||
索引中推荐的 HuggingFace 数据集(COOPER、TelecomTS)在本机网络下无法访问,而且国内退服台账没有公开数据集。因此按索引的建议,用 `data.py` 的第 18 题口径生成合成数据,并在以下几处做了改进:
|
||
|
||
- **字段完全一致**:`record_id, ne_id, cell_id, district, vendor, start_time, end_time, duration_min, cause_category, cause_detail, ticket_id, closed`,按索引要求新增原因码 `cause_code`(参照《中兴 5G NR 基站日常故障处理指导手册》章节编码)。告警流字段与 data.py 的 `gen_alarm` 一致。
|
||
- **站点库**:data.py 原版每条记录随机生成站号,无法按站点汇聚统计。改进版生成固定站点库,覆盖南宁 7 个城区、5 类场景(商圈 / 高校 / 交通枢纽 / 城中村 / 工业园区)和 3 类站型(宏站 / 室分 / 分布式皮基站)。
|
||
- **退服与告警联动**:每次退服都会产生“小区退服”告警和对应的根因告警,约 65% 带有 `parent_alarm_id` 衍生关系;另外混入背景告警和时间窗内的干扰告警,用于检验算法。
|
||
- **贴近现网的分布**:沿用 data.py 的长尾时长分段;约 12% 为问题站点(重复退服);夏季停电高发;割接集中在凌晨窗口;约 1.5% 的上报时长存在人工计算错误,用于验证系统重算时长的功能。
|
||
- 论文中请注明数据为“合成数据”。
|
||
|
||
重新生成数据:`python data_gen.py --rows 6000`,然后删除 `data/outage.db` 并重启。
|
||
|
||
样例流水含接单时间 `handle_time` 与闭环时间 `close_time`(独立随机数生成,不影响其他字段)。旧版数据库启动时会自动补字段,但旧记录没有这两个时间,及时响应率显示为“—”;删除 `data/outage.db` 重启即可载入带闭环时间的样例数据。
|
||
|
||
## 支持导入的文件(「数据导入校验」页,上传后自动识别)
|
||
|
||
| 类型 | 文件 | 入库方式 |
|
||
|---|---|---|
|
||
| 退服流水 | 系统模板(页面可下载)或 `data_outage.csv` 口径,支持中文表头 | 校验后追加,按起止时间重算时长,并对新记录做根因分析 |
|
||
| 告警流 | `data_alarm.csv` 口径(含 `alarm_code` 列) | 告警编号相同则覆盖,入库后对全部流水重新关联 |
|
||
| 网管告警 | `Reference-data/参数及告警检查工具/新建当前告警浏览结果*.csv`(华为网管导出,GBK 编码,表头前的说明行自动跳过) | 同上;按告警名称关键字归入根因类别(如 SCTP/X2/用户面承载→传输中断,射频单元/BBU/单板→设备硬件,驻波→天馈,交流掉电/直流→电源,小区不可用/退服→小区退服);没有 eNodeB ID 的网管系统告警列为问题行 |
|
||
| 站点工参 | `Reference-data/电信5G工参.xlsx`、`移动5G工参.xlsx` | 按基站汇总小区;按站名关键字推断场景(学院→高校、客运/东站→交通枢纽、产业园→工业园区、广场/营业厅→商圈,其余→城中村);已有基站只更新基础信息,保留页面上设置过的场景 |
|
||
|
||
`Reference-data` 中其余文件与本课题的退服分析无关,未做导入支持:KPI 日通报(地市级 GSM/TD/LTE 汇总)、质差小区分析(接入/掉话类)、MML 命令与参数查询结果、Access 数据库、故障处理手册 PDF(已用于处置建议的原因码编码)。
|
||
|
||
注意:参考目录里的网管告警来自其他地市的 LTE 网络,基站编号与站点库对不上,导入后会留档但不参与根因判定(预览时显示“匹配站点库”条数)。导入工参会增加站点总数,退服率的分母随之变大。
|
||
|
||
## 核心算法(core.py)
|
||
|
||
- **退服时长**:一律按“恢复时间 − 开始时间”重算;上报时长保存为 `reported_min`,两者相差超过 1 分钟即标记为“时长差错”。
|
||
- **统计周期**:顶栏筛选了月份 / 日期范围时取筛选范围(同时有则取交集),否则取全部流水首日 0 点到末日 24 点。
|
||
- **退服率** = 总退服时长 ÷(站点数 × 统计周期);**网络可用率** = 1 − 退服率。站点数按场景、片区、站型、厂家、站名关键字筛选。看板、对标与导出用同一口径。
|
||
- **站型分级阈值**:站点实际阈值 = 场景阈值 × 站型系数。默认室分超长时长 ×0.75(重点楼宇从严),分布式皮基站两项 ×1.5(覆盖小、有宏站兜底),宏站 ×1;可在「场景与站点分级」页修改。
|
||
- **超长退服站点**:月均超长退服 ≥ 1 次(单次时长 ≥ 站点实际阈值)。**高频重复站点**:月均退服次数 ≥ 站点实际次数阈值。“月均”按统计周期的自然月数计算。**重复退服率** = 高频重复站点数 ÷ 站点数。
|
||
- **根因判定分三级**(每条结果带置信度 高 / 中 / 低):
|
||
0. 衍生告警归并:带 `parent_alarm_id` 的告警按父告警类别计(停电引起的传输告警归为电源故障)。
|
||
1. 衍生关系(高):与退服开始相差 ≤ 2 分钟的“小区退服”告警带父告警时,取父告警类别。
|
||
2. 时间窗(中):同站在退服时仍未清除、提前量在该类时间窗内的告警。
|
||
3. 疑似(低):时间窗放宽到 3 倍才命中,提示人工复核。
|
||
|
||
多条命中时依次比较:级别 → 是否随业务恢复清除(±15 分钟)→ 规则优先级(割接施工 → 电源故障 → 机房环境 → 传输中断 → 天馈故障 → 设备硬件)→ 时间早;都没有命中判为“其他”。
|
||
- **时间窗标定**:每次全量分析前,用已闭环流水中同站同类告警的提前量 95% 分位数标定各类时间窗(不小于默认值 30/300/180/15/30/15 分钟,不大于 720 分钟;样本少于 30 条时沿用默认值)。
|
||
- **告警—退服关联量化**:对每类告警计算支持度(退服前 W 分钟内有该类告警的退服占比)、置信度(该类告警其后 W 分钟内发生退服的比例)、提升度(置信度 ÷ 随机窗口遇到退服的概率)。
|
||
- **断站分级**:重要 / 主要 / 次要,对应不同的处置响应时限(2 / 4 / 24 小时,从退服开始算到接单)。
|
||
- **闭环时限**:状态改为“处理中 / 已闭环”时自动记录接单时间,改为“已闭环”时自动记录闭环时间,重新打开时清空闭环时间。每条流水判定为 及时 / 超时 / 超时未响应 / 未到期 / 无记录(历史数据没有接单时间);看板给出及时响应率、平均闭环时长、超时未闭环条数,流水管理可筛选“仅超时未闭环”。
|
||
- **治理成效评估**:以分界日期把统计周期分为治理前后两段,各按自身天数折算后比较 8 项指标;治理前被判为超长 / 高频的站点逐站比较月均退服次数与时长,变化超过 ±10% 记为改善或恶化。退服有季节性,跨季节对比需结合同期数据判断。
|
||
- **影响评估**:受影响用户 = 小区数 × 单小区在线用户 × 忙闲时系数 × 覆盖补偿系数;受影响用户·小时 = 受影响用户 × 退服时长;业务损失 = 小区话务 × 忙闲时系数 × 覆盖补偿系数 × 退服时长。覆盖补偿:500 米内每有一个邻站下降 10%(室分 5%),最低 40%。
|
||
|
||
## 测试
|
||
|
||
测试都在 `tests/_work/` 下建临时数据库,不影响 `data/outage.db`。
|
||
|
||
```bash
|
||
python tests/test_rootcause.py # 根因判定准确率:基线 + 6 组扰动数据(去父告警、时钟偏移、告警缺失、干扰告警、提前量变宽、综合)
|
||
python tests/test_kpi.py # 统计周期、稀疏筛选、月均口径、看板与导出一致、影响评估、关联量化
|
||
python tests/test_api.py # 登录与权限、导入模板校验、闭环流程与响应时限、站型系数、治理成效、无数据边界
|
||
python bench.py # 单批 1 万条导入耗时、全量分析耗时、时长计算准确率
|
||
```
|
||
|
||
根因测试的时间窗只用 1~6 月流水标定,在 7~9 月流水上计分(留出检验)。数据为合成数据,准确率反映的是算法在设定扰动下的表现,论文中应同时说明扰动设置。
|