Files
Gset/README.md
T
treeandClaude Opus 5.5 e9616af34d 修复 P0:根因判定、退服率口径、影响评估与告警关联量化
- 根因判定改为三级(衍生关系/时间窗/疑似)并带置信度;小区退服告警 ±2 分钟匹配;
  衍生告警按父告警归类;优先选随业务恢复清除的告警;时间窗按历史流水 95% 分位数标定
- 退服率按日历统计周期计算;站点数分母支持站名关键字;重复退服率除以全部站点;
  月均按统计周期自然月数;导出与看板同一口径
- 影响评估新增受影响用户·小时与 500 米邻站覆盖补偿
- 新增告警—退服关联量化(支持度/置信度/提升度)及 /api/association,根因页展示
- 新增 tests/(扰动数据集留出检验、指标口径检验)与 bench.py;旧库启动时自动迁移

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 14:43:34 +08:00

140 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 并重启。
## 支持导入的文件(「数据导入校验」页,上传后自动识别)
| 类型 | 文件 | 入库方式 |
|---|---|---|
| 退服流水 | 系统模板(页面可下载)或 `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 − 退服率。站点数按场景、片区、站型、厂家、站名关键字筛选。看板、对标与导出用同一口径。
- **超长退服站点**:月均超长退服 ≥ 1 次(单次时长 ≥ 场景阈值)。**高频重复站点**:月均退服次数 ≥ 场景次数阈值。“月均”按统计周期的自然月数计算。**重复退服率** = 高频重复站点数 ÷ 站点数。
- **根因判定分三级**(每条结果带置信度 高 / 中 / 低):
0. 衍生告警归并:带 `parent_alarm_id` 的告警按父告警类别计(停电引起的传输告警归为电源故障)。
1. 衍生关系(高):与退服开始相差 ≤ 2 分钟的“小区退服”告警带父告警时,取父告警类别。
2. 时间窗(中):同站在退服时仍未清除、提前量在该类时间窗内的告警。
3. 疑似(低):时间窗放宽到 3 倍才命中,提示人工复核。
多条命中时依次比较:级别 → 是否随业务恢复清除(±15 分钟)→ 规则优先级(割接施工 → 电源故障 → 机房环境 → 传输中断 → 天馈故障 → 设备硬件)→ 时间早;都没有命中判为“其他”。
- **时间窗标定**:每次全量分析前,用已闭环流水中同站同类告警的提前量 95% 分位数标定各类时间窗(不小于默认值 30/300/180/15/30/15 分钟,不大于 720 分钟;样本少于 30 条时沿用默认值)。
- **告警—退服关联量化**:对每类告警计算支持度(退服前 W 分钟内有该类告警的退服占比)、置信度(该类告警其后 W 分钟内发生退服的比例)、提升度(置信度 ÷ 随机窗口遇到退服的概率)。
- **断站分级**:重要 / 主要 / 次要,对应不同的处置响应时限。
- **影响评估**:受影响用户 = 小区数 × 单小区在线用户 × 忙闲时系数 × 覆盖补偿系数;受影响用户·小时 = 受影响用户 × 退服时长;业务损失 = 小区话务 × 忙闲时系数 × 覆盖补偿系数 × 退服时长。覆盖补偿:500 米内每有一个邻站下降 10%(室分 5%),最低 40%。
## 测试
测试都在 `tests/_work/` 下建临时数据库,不影响 `data/outage.db`。
```bash
python tests/test_rootcause.py # 根因判定准确率:基线 + 6 组扰动数据(去父告警、时钟偏移、告警缺失、干扰告警、提前量变宽、综合)
python tests/test_kpi.py # 统计周期、稀疏筛选、月均口径、看板与导出一致、影响评估、关联量化
python bench.py # 单批 1 万条导入耗时、全量分析耗时、时长计算准确率
```
根因测试的时间窗只用 1~6 月流水标定,在 7~9 月流水上计分(留出检验)。数据为合成数据,准确率反映的是算法在设定扰动下的表现,论文中应同时说明扰动设置。