证券交易时延分析报告生成

概述

将客户的"逐笔委托-行情时延"明细与整体统计 CSV，转化为一份带 ECharts 可视化的专业 HTML 分析报告。报告覆盖整体趋势、日内时段(开盘高峰)、波动原因自动归因、通道维度、极端时延明细与优化建议。核心脚本 scripts/build_report.py 自包含：读 CSV → 校验单位 → 多维统计 → 自动检测数据模式并生成归因结论 → 生成 HTML，可直接执行或被调用。报告第三、六节的结论由 generate_conclusions() 函数根据实际数据自动生成，无需人工补充归因文字。

何时使用

用户提供时延明细 CSV（字段含 date, tickOrderLatency, securityId, orderTime, mdTime, orderSysId, fundAccountId, orderSide, mdSide, channelNo, applSeqNum）与整体 CSV（字段含 资金账号, 交易日期, P50时延/us, P90时延/us, 平均时延/us, 最大时延/us），要求生成时延分析报告。
关键词：交易时延、tickOrderLatency、逐笔行情时延、委托时延、时延趋势、时延波动、开盘时延、P50/P90 时延。
用户要求"分析最近 N 天时延趋势 / 是否波动 / 波动原因"。

数据与单位约定（关键）

明细 tickOrderLatency 原始单位为皮秒(ps)，换算为微秒(us)：latency_us = tickOrderLatency / 1_000_000。整体表已标注 us，二者应吻合（比值≈1.0）。
时延口径：每笔委托发送时间戳 − 该笔委托对应的最近一笔逐笔行情时间戳。
orderTime/mdTime 为 YYYYMMDDHHMMSS 整数串，秒级；亚秒差值即 tickOrderLatency。
详细字段说明与分析方法论见 references/data_schema.md，处理前务必先读。

工作流程

定位文件：向用户确认明细 CSV 与整体 CSV 的绝对路径；客户名称；输出 HTML 路径（默认与 CSV 同目录，命名<客户>交易时延分析报告.html）。
环境：使用受管 Python C:\Users\gtht\.workbuddy\binaries\python\envs\default\Scripts\python.exe（需 pandas/numpy；若缺失先 pip install pandas numpy）。
执行脚本：运行 scripts/build_report.py，传参：
```
python build_report.py --mingxi <明细CSV> --zhengti <整体CSV> --customer <客户名> --output <输出HTML>
```
脚本内部完成单位校验、每日/时段/通道/方向/极端值统计并生成单文件 HTML（ECharts CDN）。
校验：检查输出无 NaN/Infinity；确认日级 P50/P90/平均/最大与整体 CSV 一致（脚本已优先采用整体表数值）。
解读增强：脚本已内置 generate_conclusions() 自动归因引擎，会根据数据自动检测以下模式并生成结论嵌入报告第三、六节：
- 飙升后恢复：检测某日 P50 > 基准×1.5 且后续日回落至飙升日×0.5 以下 → 自动判定为"一次性事件，已恢复"。
- 采样结构失真：检测某日开盘 10 分钟委托占比 >50% 且 P50 偏高 → 自动计算同口径开盘段 P50 实际升幅。
- 冷启动效应：检测飙升日距上一交易日间隔 ≥3 天或为周一 → 自动标注冷启动。
- 极端长尾拉偏均值：检测某日均值 > P50×5 → 自动标注极端值数量与最大值。
- 通道均衡性：计算各通道 P50 极差，<20% 良好 / <40% 关注 / ≥40% 异常。
- 稳态性能评估：基于开盘段外 P50 评估系统基础性能。
- 长尾收敛：最新日 P90/最大值优于基准日时自动标注改善。
- 若自动结论需补充特定业务背景，可在交付时口头增强。 5b. 自动告警引擎（最高优先级前置）：脚本内置 detect_alerts() + generate_alert_findings()，在核心分析摘要与深度分析节独立前置生成红色告警，区别于普通归因发现。两类告警：
- 系统性退化（严重告警，深红标签）：检测 P50 ≥ 15μs 且 ≥ 基准×3、5通道极差<30%、非开盘集中（开盘占比<50%）→ 判定为链路/行情源级故障特征（如 08-21、08-24 案例），自动生成最高优先级排查卡片。
- 极端长尾（长尾告警，琥珀标签）：检测单日最大时延 ≥ 20ms（高优先级）或 ≥ 100ms（critical）且 P50 正常 → 判定为尾部偶发，建议关注是否持续。
- 已恢复标记：前一日异常、当日 P50<12μs 且最大<20ms → 自动标注"已恢复"，确认前序异常为偶发。
- 阈值常量集中在 detect_alerts() 顶部，可按客户实际基线调整（TAIL_HIGH=20ms / TAIL_CRIT=100ms / SYS_P50_ABS=15μs / SYS_P50_MULT=3.0）。
- 与归因引擎的一致性：generate_conclusions() / generate_summary_findings() 的飙升检测分支已加 spike_is_sys 守卫——系统性退化日不再套用"冷启动效应"话术；若周期内出现多日连续系统性退化（len(systemic_days)>1），该分支跳过与严重告警卡片重复的发现，避免"冷启动"与"系统性退化"判定冲突。
交付：用 present_files 呈现 HTML（自动预览），文字回复给出趋势结论与波动归因摘要。

分析方法论要点

优先用分位数(P50/P90/P99)而非均值判断典型时延：均值受极端长尾拉偏严重。
**区分"开盘段(9:30-9:40)"与"稳态段"**分别评估，避免采样占比干扰日级结论。
趋势对比：以监测周期首日为基准，计算 P50/平均时延变化百分比；同时报告 P90/P99/最大。
波动判定：P50 较基准 ±20% 以内视为稳定；>50% 需归因；最大时延进入毫秒级需专项排查。
配色：遵循中国证券惯例，涨(时延上升/告警)用红色系，正常/下降用绿色系。

资源

scripts/build_report.py

自包含报告生成器。CLI 参数：--mingxi、--zhengti、--customer、--output。可直接 python build_report.py 无参运行示例（默认展宏数据）。依赖 pandas/numpy。输出单文件 HTML（ECharts CDN，亮色主题）。

内置 generate_conclusions() 自动归因引擎，检测 7 种数据模式（飙升后恢复、采样失真、冷启动、极端长尾、通道均衡、稳态性能、长尾收敛），自动生成数据驱动的结论与建议嵌入报告。另含独立自动告警引擎 detect_alerts() + generate_alert_findings()：区分"系统性退化（链路级故障特征，深红严重告警）"与"极端长尾（P50正常尾部偶发，琥珀长尾告警）"，并支持"已恢复"自动标记，在核心分析摘要与深度分析节前置红色告警卡片。可在不读入上下文的情况下直接执行；必要时可读取并按数据字段差异做适配 patch。

references/data_schema.md

明细/整体 CSV 字段定义、单位换算、时段时间窗口定义、波动归因方法论与示例话术。处理数据前应加载参考。

输出报告结构

概要卡片（最新日 P50/P90/平均/最大、日均笔数、较基准变化%）
整体时延趋势（日度 P50/P90/P99/平均/最大折线 + 明细表）
日内时段分布与开盘高峰效应（开盘 10 分钟 vs 其余时段、分钟级趋势、开盘占比）
波动原因深度分析（自动归因：飙升后恢复、采样结构失真、冷启动、极端长尾、通道均衡、稳态性能、长尾收敛）
交易通道维度（基准日 vs 最新日各通道 P50）
极端时延明细 TOP15
结论与优化建议（自动生成：总体判断 + 分优先级建议，建议条目根据实际数据条件触发）