02 无线性能分析端到端实现任务

执行要求：直接补齐“无线性能分析”页面的真实接口和前端适配，运行测试与联调后交付。先修现有链路，不复制一套新的性能领域框架。

共同门禁：不执行数据库草案，不修改 V1，不 DROP/清库或插入客户测试数据；g5b2-mysql 仅用于 SHOW、SELECT 和 EXPLAIN。接口统一使用 X-Trace-Id，缺失时后端生成并写响应头；同一动作的前端日志、后端日志、错误响应、备注和审计必须同值。

1. 目标与完成判定

• 菜单：监控分析 / 无线性能分析。
• 路由：/performance。
• 完成页面状态、摘要、小区-KPI 矩阵、单 CGI 趋势、负荷与流量、同键散点、已发布箱线摘要、分页明细和指标备注。
• 所有图表只绘制后端发布值；静态阈值和动态基线分别显示。
• 雷达归一化、跨小区比例均值和“RRC连接总数”继续降级，不得为凑页面效果实现。

2. 开工前必读与现状核对

1. 设置 PowerShell UTF-8，完整阅读仓库门禁、需求 V2.0、数据库设计第 9.2/10/11/12 节和数据库草案相关表。
2. 阅读 PerformancePage、PublishedChart、PageFeedback、types/index.ts、services/api.ts/http.ts/presentation.ts。
3. 阅读现有 performance Controller/Service/Mapper/XML、DTO、备注写操作和相关测试。
4. 用 rg 查找 performance、MetricDetail、MetricMatrix、Trend、MetricNote 的全部调用方和 SQL。
5. 当前已有 state、summary、matrix、trend、details、notes 契约；逐项验证后补缺，禁止重复建同义接口。

3. 现有接口基线

能力	当前接口
页面状态	GET /api/v1/performance/state
摘要	GET /api/v1/performance/summary
异常矩阵	GET /api/v1/performance/matrix
单 CGI 趋势	GET /api/v1/performance/trend
分页明细	GET /api/v1/performance/details
备注	GET/POST /api/v1/metrics/{metricResultId}/notes

本任务必须为负荷流量和同键散点提供页面实际消费的只读契约；即使业务表为空也应正确返回空集合。箱线只在 tb_metric_stat_result 有已发布、可追溯算法结果时返回数据，否则明确降级。扩展接口仍放在性能领域，不创建通用图表接口。

4. 指标和业务边界

• 支持源指标：WIRELESS_ACCESS_RATE、WIRELESS_DROP_RATE、RRC_SETUP_SUCCESS_RATE、RRC_CONNECTION_MAX、PRB_UL_USAGE_RATE、PRB_DL_USAGE_RATE、HANDOVER_SUCCESS_RATE、PDCP_UL_BYTES、PDCP_DL_BYTES。
• 比例存储为 0~1，按后端 displayMultiplier 展示；越界原值为空并带 N/A 原因，不能截断为 100%。
• RRC_SETUP_SUCCESS_RATE 按低值劣化方向参与动态基线与预测；静态阈值未配置时保持 NOT_CONFIGURED。
• RRC_CONNECTION_MAX 必须显示“RRC连接最大数”，禁止求和或改名为总数。
• 缺少分子分母，禁止跨小区或跨时间平均接通率、掉线率和切换成功率；趋势限定单 CGI，或最多展示 5 条独立 CGI 原值线。
• PRB 任一侧 N/A 时只阻断完整负荷候选，不抹掉仍有效的 PDCP 源值；两类 PDCP 按高值劣化方向参与动态基线与预测。
• 静态、动态状态分别返回、筛选和计数；无阈值是 NOT_CONFIGURED，基线不足不是 NORMAL。
• 箱线只读 tb_metric_stat_result 的 PUBLISHED 五数和样本数；若未发布算法版本或离群点证据，返回 N/A/NA_UNSUPPORTED，不在同步请求计算分位数。
• 雷达归一化未确认，页面隐藏或明确 NA_UNSUPPORTED。

5. 后端实施顺序

1. 页面状态：统一 DataState，返回发布运行号、发布时间、三个状态轴和 traceId。
2. 只读查询：筛选支持区域、两级场景、厂家、基站、CGI、频段、带宽、metricCode、时间范围和 HOUR；DAY/MONTH 无发布聚合时拒绝或不开放。
3. 矩阵与摘要：只读 PUBLISHED 指标及评估结果，稳定排序；矩阵单元同时含源值、单位、qualityStatus、staticStatus、dynamicStatus、evidenceStatus、业务时间和运行号。
4. 趋势：必须要求 CGI+metricCode，historyHours 有上限，不插值、不跨 CGI 平均。
5. 负荷/流量：按同一 CGI/时间轴返回 RRC 最大数、两类 PRB、两类 PDCP 的已发布点；PDCP 保留 byte 存储并按旧系统 /1024/1024 展示 GB，单位分层且不用混合单位暗示因果。
6. 散点：每点必须来自同一 (cgi,businessTime) 的下行 PRB、掉线率和 RRC连接最大数；任一必需值 N/A 时不造点并返回缺失计数或原因。
7. 箱线：只读标准发布窗口的 tb_metric_stat_result；不得为任意查询窗口同步扫描明细算分位数。
8. 明细：服务端分页、白名单排序和真实 total；列表与 count 使用完全相同条件及最终稳定键。
9. 备注：只允许附加到 PUBLISHED 指标；按同一 traceId 幂等，追加 tb_metric_note 和 tb_audit_log，不修改指标、基线或告警。

6. 数据追溯

能力	主要来源
源值、单位、质量	tb_metric_publish_result、tb_metric_definition
维度快照	已发布结果关联的性能事实快照；不得作为无发布结果的回退
静态/动态状态	tb_metric_evaluation_result、tb_baseline_result、tb_threshold_rule
箱线/标准窗口统计	tb_metric_stat_result
同小时底噪证据	PUBLISHED 性能与干扰指标按 CGI+business_time 配对
关联告警、备注	tb_alarm、tb_metric_note
运行和版本	tb_publish_run、阈值/分析配置版本

7. 前端适配

• 筛选、分页、排序、时间窗口必须进入请求；矩阵、图表和明细共享同一已应用条件。
• 选择矩阵单元、趋势点或明细行后，稳定同步 CGI、businessTime、metricCode；跨页只传共享 URL 参数。
• 删除任何 filter/length、随机点、固定阈值、固定日期、前端分位数和按名称判状态。
• 空数据、N/A、NOT_CONFIGURED、基线不足、403 和请求错误均显示服务端 traceId。
• 图表 connectNulls=false；N/A 点留空。最多 5 个 CGI，超限要求缩小范围。
• 备注提交成功后以服务端响应刷新，不乐观改写业务结论。

8. 最小验证门禁

1. 后端测试覆盖：空库、分页 total、排序白名单、单 CGI 限制、比例/N/A、静态动态分离、散点同键、备注幂等与不存在/非发布结果。
2. 只读 EXPLAIN：当前发布趋势、矩阵、分页明细、统计结果读取；记录实际索引，不强写客户数据。
3. 真实 HTTP：成功、非法时间、缺 CGI 趋势、无数据、备注重复 traceId；核对响应头、错误体、日志、备注和审计的 traceId。
4. 运行相关 Maven 测试、Mapper XML 配对检查和注解 SQL 禁止扫描。
5. 运行 cd frontend; npm run build，并用浏览器验证筛选、分页、图表空点和备注操作。

9. 交付报告

列出修改文件、已实现接口、每个页面字段的 DTO/Service/Mapper/XML/发布表追溯、实际测试结果，以及箱线离群点、雷达、跨小区比例等仍降级能力。不得声称未发布统计或未验证图表已完成。