# 全系统统一加载实现与验收 ## 范围与约束 六类查询、来源明细、数据接入、规则、对应关系、基础数据、权限审计、任务监控、智能分析和导出共用现有 api.ts 的请求协调层。保留现有布局、主题、计算公式和来源数据;保留完整下载及前端分页、全范围搜索排序、Excel 全量导出。 ## 实现契约 - GET 同键合并、最多 4 个在途读取;订阅者独立取消,最后一个退出才取消底层请求。身份、授权和版本变化中止旧读取,旧响应不得提交或导出。 - 会话内存 LRU 上限 32 MiB;按用户、权限、数据发布及规范化参数隔离,不持久化业务结果。工作区校验合并,按资源失效,隐藏页面和未选管理页签不主动刷新。 - 工作区授权变化立即撤下旧结果;工作区本身 403 同样阻断,恢复后重新核实身份并重建页面。单资源 403 仅触发重验,避免重复预读循环。 - 普通读取 30 秒、身份/连接校验 8 秒,预算覆盖正文读取;只读网络失败和 502/503/504 最多延迟 1 秒重试一次。写入、上传、任务提交不自动重发。文件传输 900 秒;模型事件流不套普通查询超时。 - 首次加载保留框架,150 毫秒后才显示忙碌;更新保留成功结果并标注其期间。首次错误有重试,更新错误保留旧结果并阻断旧范围的明细、钻取和导出;只有成功的空结果显示空态。 - 页面返回保留筛选、页码及滚动位置;表格按查询条件识别分页范围,缓存读取的新对象不重置分页。隐藏时保留表格已知高度,避免返回时滚动被临时零高度夹紧。 - 轮询按上次请求完成后排下一轮:任务 15 秒、活动操作 2 秒、分析会话 5 秒;隐藏暂停、返回立即核对。已知任务编号继续恢复,未保存输入保留。 - 保留 280 毫秒页面淡化、520 毫秒数值/图表过渡及减少动态效果设置;图表接近可见区域才初始化,不良构成按需读取。 - GET /api/metrics/trend 直接按期间聚合,返回 release/context/trend/coverage,不计算或返回产品完整表。汇总与趋势绑定同一 release 并行读取;原 /api/metrics 契约保留。 - 后端对超过 1 KiB 的 JSON/problem+json 开 gzip;Nginx 仅补静态文本压缩,保留 HTTPS、事件流不缓冲及 900 秒代理时限。Excel、压缩包、SSE 不参与 JSON 压缩。 - 诊断仅保存类别、耗时、字节、状态、重试次数;不记录业务正文、凭据及完整查询地址。 ## 验证证据 隔离当前发布快照,关闭分析及报告后台写入;原接口与轻量趋势 36 组对照通过,覆盖维度、月/季/年、黑片/亮片、期间、产品选择/排除及来源字段。趋势最大解压 JSON 17,286 字节;原产品接口 7,485,818 字节,gzip 后 1,381,397 字节。 真实 Chrome、1440×900、10 Mbps、100 毫秒延迟、4 倍 CPU 降速、禁用浏览器缓存,每类独立冷加载 20 次。计时从导航开始,到趋势响应正文完成且非忙碌 SVG 的首个绘制帧: | 页面 | 次数 | 趋势可见 P95 | 最大原始趋势响应 | |---|---:|---:|---:| | 产品 | 20 | 1,762.8 ms | 17,251 B | | 黑片 | 20 | 1,996.4 ms | 11,856 B | | 亮片 | 20 | 1,899.1 ms | 13,276 B | 黑片最慢单次为 2,026.4 ms,P95 仍小于 2 秒。该单次从导航到请求开始 1,732.4 ms;请求至正文结束 141.1 ms(其中首字节前 135.5 ms,包含模拟往返与服务端等待,未冒充独立服务端耗时);正文结束到可见帧 152.9 ms。性能数据是隔离快照的实验结果,不承诺所有设备或完整表格首屏都在 2 秒内。 真实返回验收:亮片第 2 页、scrollY=939.5,切产品再返回后页码与 scrollY 不变;返回期间指标/趋势底层请求数量不增加。六查询视图及桌面/390×844 手机六主题均有图表,无页面横向溢出。首次趋势失败显示错误和重试,汇总表仍可读,重试后恢复。竞态、共享取消、权限变更、首错/更新错、轮询与任务恢复由行为回归覆盖。 完整记录保存在本机 output/unified-loading-20261102:interface-comparison.json、browser-performance.json、cache-navigation.json、visual-checks.json、query-smoke.json 和截图。 ## 发布与回退 一次集成发布:验证和冻结源码/产物 → 同步 Gitea → 备份实际运行 JAR、前端真实目标和 Nginx 配置 → 确认无活动任务 → 启动兼容旧前端的新后端 → 合并静态压缩配置并验证 Nginx → 原子切换新前端 → HTTPS/资源哈希/真实页面验收。 回退使用发布时捕获的实际运行 JAR 路径及 SHA、旧前端目录、原 Nginx 配置,不能依据陈旧 manifest 推断后端。保留旧哈希资源供已打开浏览器继续加载。无需数据库结构迁移,不恢复或重写业务数据。