RuView QE 修复计划全解读：从 ADR-080 看 305K 行代码库的质量治理与安全边界验证

本文以 RuView（WiFi-DensePose 传感项目）的 ADR-080: QE Analysis Remediation Plan 为核心档案，逐条剖析一次 8 智能体 QE（质量工程）群评打出的 15 项问题清单及其三波次修复方案，并深入 Rust 传感服务器（sensing-server）源码与测试用例，验证三个 P0 级安全问题的真实处置边界与回归测试防线。读者读完可以掌握：一次大规模代码库质量体检的完整产出结构（P0/P1/P2 分级与修复节奏）、CWE-209/CWE-598 等安全缺陷的"验证式修复"方法论，以及 RuView 从 55/100 质量分走向 75+ 目标分的具体落点。

一、背景：55/100 分背后的 305K 行代码体检

2026-04-05，一个由 8 个专职智能体组成的 QE 群（fleet-02558e91）对 RuView 约 305K 行代码进行了全谱系质量评估，范围覆盖 Rust（153K）、Python（39K）、C 固件（9K）与 TypeScript/JavaScript（33K）。结论被记录为 ADR-080，其中最重要的量化结果是：

• 总体质量分 55/100（C+）——Quality Gate（质量门禁）判定失败；
• 代码质量与复杂度：55–82/100（有条件通过）；
• 安全：68/100（有条件通过）；
• 性能：临界风险（实测 37–54ms，逼近 50ms 帧预算）；
• 测试套件质量：混合（共清点 3,353 个测试，但重复严重）；
• 覆盖率：文件级 77%，但 Python 仅 30%、固件仅 19%；
• 产品因素（SFDIPOT）：时间因素判定 CRITICAL。

该档案对应的完整 QE 报告已归档于仓库 docs/qe-reports（共 9 个文件、4,914 行，详见下文"报告族谱"一节）。ADR-080 将体检发现的 15 项优先问题组织成三个修复波次：P0（立即修复）、P1（本 sprint）、P2（本季度），并逐一给出了修复动作与目标分预测——P0+P1 完成后期望从 55 分提升到 75+。

二、先厘清修复边界：Python v1 已归档，验证落在 Rust 主边界

阅读本档案前必须先理解一个关键背景（档案 Status 行与 2026-06-13 补充说明均有明确记载）：

• 体检打出的三个 P0 安全问题（XFF 绕过、异常泄露、URL 中的 JWT）最初是针对 Python v1 API（archive/v1/src 目录树）记录的，定位点如 archive/v1/src/middleware/rate_limit.py:200-206、archive/v1/src/api/routers/pose.py:140 等；
• 但 v1 已归档，不是对外交付面。因此 ADR-164 的 G11 项把这三项重新定位到真正上线的边界：Rust 传感服务器 wifi-densepose-sensing-server（位于 v2/crates/wifi-densepose-sensing-server）；
• 2026-06-13 在 fix/adr-080-sensing-server-security 分支上完成了验证与收口：每项修复（或"本就不存在该漏洞面"的确认）都由一个"在旧行为上必然失败"的回归测试钉死；
• Python v1 路径保持原样不动——该收口只管辖线上的 Rust 服务器。

这一"重定界（re-scope）"思路是质量治理中非常实用的取舍：不为一套已归档、不再交付的代码继续支付修复成本，而是把资源对准当前真实受攻击面。

三、P0 安全项深度拆解：三项 HIGH 的验证式修复

3.1 #1 Rate Limiter Bypass / XFF 欺骗（Security HIGH）——已解决（Rust 边界验证为"不存在该漏洞面"）

v1 原始问题：archive/v1/src/middleware/rate_limit.py:200-206 无条件信任 X-Forwarded-For 头，任何客户端都能通过伪造该头绕过限流。

Rust 边界验证结论（2026-06-13）：Rust sensing-server 根本没有可被 XFF 绕过的控制面——

1. 不存在基于 IP 的限流器，也不存在 IP 白名单；
2. 两个安全中间件都不读取转发头：
   • bearer_auth.rs 中的 require_bearer 只检查 AUTHORIZATION 头做鉴权；
   • host_validation.rs 只依据真正的 Host 头做 DNS-rebinding 白名单判定（详见 3.4）；
3. 对 wifi-densepose-sensing-server 全 crate 以 x-forwarded-for|forwarded|peer_addr|client_ip|real-ip 做仓库级 grep，零命中；
4. 整个 crate 里唯一的"限流器"是 MQTT 的采样率门控（mqtt/state.rs），按实体（entity）做发布节流，不接收 IP/头输入。

因此无需改代码。回归测试从两个方向钉死"免疫性"：

• bearer_auth.rs 的 xff_header_never_affects_auth_decision：伪造的 XFF 永远无法把 401↔200 的鉴权结论翻转——错误/缺失 token 加伪造 X-Forwarded-For: 127.0.0.1 仍是 401，正确 token 即便带 X-Forwarded-For: evil-proxy 也仍是 200；
• host_validation.rs 的 forwarded_headers_never_bypass_host_allowlist：用 X-Forwarded-Host: localhost + 真实 Host: evil.com 组合发送，请求仍返回 421 Misdirected Request，伪造转发头无法放行白名单之外的主机。

残留指引：文档明确要求，未来若真要加 IP 级控制，对端身份必须取自 socket（ConnectInfo<SocketAddr>），且只在显式配置 --trusted-proxy CIDR 时才信任 XFF——这段约束被写进了上述测试的 docstring，作为对后续开发者的强制性提醒。

3.2 #2 异常细节泄露进响应体（Security HIGH，CWE-209）——已解决

v1 原始问题：archive/v1/src/api/routers/pose.py:140、stream.py:297 及另外 5 个端点把内部错误/堆栈细节直接序列化进客户端响应。

Rust 边界发现：sensing-server 的 main.rs 中有 6 个 handler 曾把内部错误的 Display 直接写进 JSON 响应体：

• edge_registry_endpoint：把 panic 的 spawn_blocking 任务返回的 JoinError（形如 task … panicked）放进 500 响应，上游原始错误则进了 503 响应；
• delete_model / delete_recording / start_recording：返回 std::io::Error 的字符串（带 OS 错误细节与文件路径）；
• calibration_start / calibration_stop：返回 FieldModel 的错误链。

修复方案：新增独立模块 error_response.rs，定义三个带"泄漏防护契约"的辅助函数：

• internal_error(context, detail)：返回 HTTP 500 + 通用体；
• internal_error_json(context, detail)：给那些类型为 Json<serde_json::Value>、靠 "success": false 表达失败的历史 handler 使用；
• upstream_unavailable(context, detail)：503 上游不可用专用变体，避免泄露可携带内部 URL/连接串的原始上游错误。

其核心机制是细节只留在服务端：完整 detail 以 error/warn 级别写入服务端日志，并打上 16 位十六进制小写关联 ID（correlation id）；返回给客户端的统一只有：

{ "error": "internal_error", "correlation_id": "a1b2c3d4e5f60718", "success": false }

该 body 刻意不包含底层错误的 Display/Debug、不包含文件路径、永不出现 panicked 字样。关联 ID 由纳秒时间戳异或单调计数器生成（error_response.rs），足以让运维把客户端报障 ID 与服务端日志行精确对上。

回归测试防线（同一文件的 tests 模块）：internal_error_body_does_not_leak_detail 用一条携带文件路径、OS 错误与 panicked 字样的"泄漏样串"（LEAKY_DETAIL）做泄漏子串守卫——递归收集 JSON 全部字符串值，断言不出现 panicked、secret、os error、.rvf 中的任何一项；文档明确记载该测试在回退到旧响应体时必然失败。另有 4 个兄弟测试分别验证：通用体带合法关联 ID（internal_error_body_is_generic_with_correlation_id）、internal_error_json 变体同享泄漏保证、503 上游路径不泄露内部主机/连接细节（upstream_unavailable_does_not_leak_detail）、快速连续调用下关联 ID 不重复（correlation_ids_are_unique）。

3.3 #3 WebSocket JWT 放进 URL（Security HIGH，CWE-598）——已解决（Rust 边界验证为"不存在该路径"）

v1 原始问题：archive/v1/src/api/routers/stream.py:74 与 archive/v1/src/middleware/auth.py:243 允许令牌出现在查询字符串中——令牌会随之进入日志、代理记录与浏览器历史。

Rust 边界验证：Rust sensing-server 从不从 URL 读取令牌：

• require_bearer 只检查 Authorization 头；
• WebSocket handler（ws_sensing_handler / ws_introspection_handler / ws_pose_handler）只接收裸的 WebSocketUpgrade，没有 Query 提取器；
• 全 crate 中唯一的 Query 提取是 EdgeRegistryParams，其内容是非敏感的 refresh 标志位。

结论同样是无需改代码。回归测试 query_string_token_is_never_accepted（bearer_auth.rs）证明了：即使把正确的 token 放在 ?token= 或 ?access_token= 里，请求仍然 401；而同一 token 放进 Authorization 头则返回 200。文档记录该测试在"query-token 路径被重新引入"时会失败，起到行为锁的作用。

3.4 补充说明：P0 安全验证所依托的另外两道防线

虽然 #1、#3 在 Rust 边界的结论是"无需修改"，但要理解为什么这两项能干净关闭，还需看到 host/bearer 两层中间件本身的当代设计——它们正是 ADR-080 之后的产物（相关演进见 ADR-272: WebSocket Authentication Tickets）：

• Host 头白名单防 DNS rebinding：默认绑定回环地址时，恶意网页可把 DNS 指向 127.0.0.1 冒充同源请求，从而偷读实时姿态/呼吸/心率流或触发状态变更 POST。host_validation.rs 对不在白名单内的 Host 一律回 421 Misdirected Request；默认白名单覆盖 localhost/127.0.0.1/[::1]（带或不带 :PORT），对外绑定时（--bind-addr 0.0.0.0 或局域网 IP）用 --allowed-host 或 SENSING_ALLOWED_HOSTS 环境变量扩展，且决定信号只有真实 Host 头，任何客户端转发头一律无视。
• Bearer 鉴权的 deny-by-default 与作用域门：require_bearer 在设置了 RUVIEW_API_TOKEN 时保护 /api/v1/* 树，未设置时保持默认的"仅局域网"无鉴权姿态；WebSocket 升级路径（/ws/sensing、/ws/introspection、/api/v1/stream/pose）则接受 bearer 或单次使用票据。required_scope_for 采用"读开放、写默认关闭"的作用域极性——凡变更类方法默认要求 sensing:admin，只有进入显式 READ_SAFE_MUTATIONS 白名单的路径才降到 sensing:read，从设计上杜绝"新增一条破坏性路由却意外落在读作用域"的漏洞。

四、P0 其余两项：CI 与移动端 WebSocket

4.1 #4 Rust 测试从未进 CI

最大代码库（153K 行 Rust）里躺着 2,618 个测试，却零个在任何 GitHub Actions 工作流中运行——回归可以无感上线。修复动作极简：在 CI 中加入 cargo test --workspace --no-default-features，预估工作量 1–2 小时。

4.2 #5 WebSocket 路径不一致（Bug）

• 移动端 ws.service.ts 构造的是 /ws/sensing；
• 而常量文件 constants/websocket.ts 定义的 WS_PATH = '/api/v1/stream/pose'。

后果是移动端 WebSocket 静默失败。修复方向是统一路径，并核实服务器真正服务的端点。值得注意的是，后续演进中 /ws/sensing 与 /api/v1/stream/pose 都成为了受保护/可发的升级端点（见上节及 bearer_auth.rs 的 WS_PATHS），印证了文档中"Verify which endpoint the server actually serves"的务实提醒。

五、P1（本 sprint）与 P2（本季度）清单

P1 五项：性能与代码健康

#	问题	定位	影响
6	God 文件：4,846 行、圈复杂度 CC=121	sensing-server/src/main.rs（对应现仓库 v2/crates/wifi-densepose-sensing-server/src/main.rs）	不可测试的单体
7	每帧 O(L×V) 体素扫描	ruvsense/tomography.rs:345-383	每帧浪费约 10ms；应改用 DDA 光线步进
8	串行神经网络推理	wifi-densepose-nn inference.rs:334-336	2–4 倍 GPU 延迟惩罚
9	全工作区 720 处 .unwrap()	工作区	每个都可能成为实时路径上的 panic
10	Python 每帧 112KB 分配	csi_processor.py:412-414	每帧 Deque→list→numpy 转换

P2 五项：覆盖缺口与生产加固

#	问题	影响
11	12 个 Python 模块中 11 个零单元测试（12,280 LOC）	服务、中间件、DB 均未测试
12	固件覆盖率仅 19%（WASM 运行时、OTA、swarm）	安全关键代码未测试
13	MAT 屏自动回退到模拟数据	救灾人员可能监控到假数据
14	认证期间从不查询 token 黑名单	已吊销 token 仍有效
15	50ms 帧预算从未基准化	实时性要求未被验证

六、档案背面：值得保留的 Bright Spots

一次质量体检如果只报问题是不完整的。ADR-080 同时明确记录了该项目的六项亮点，可与前文中的修复细节相互印证：

• 79 份 ADR（出众的治理记录——本档案正是其一）；
• Witness bundle 系统（ADR-028 体系）带 SHA-256 证明；
• 2,618 个数学严谨度高的 Rust 测试（数量与质量并存的证据，也解释了为何 #4"测试不进 CI"是重大痛点）；
• 每日安全扫描（Bandit、Semgrep、Safety）；
• 固件上的 Ed25519 WASM 签名验证；
• 干净、测试覆盖良好的移动端状态管理。

七、完整 QE 报告族谱（9 文件 / 4,914 行）

ADR-080 只是"索引卡"，体检全量产出保留在 docs/qe-reports，每一份报告解决一类体检视角，可对应 P0–P2 各项来源：

报告	覆盖内容
EXECUTIVE-SUMMARY.md	顶层综合：全部分数与优先级矩阵
00-qe-queen-summary.md	总协调、质量姿态、测试金字塔
01-code-quality-complexity.md	圈复杂度、代码坏味、Top 20 热点
02-security-review.md	15 项安全发现（3 HIGH、7 MEDIUM）、OWASP 覆盖
03-performance-analysis.md	23 项性能发现（4 CRITICAL）、帧预算分析
04-test-analysis.md	3,353 个测试清点、重复度、质量分级
05-quality-experience.md	API/CLI/Mobile/DX 用户体验评估
06-product-assessment-sfdipot.md	SFDIPOT 分析、57 个测试构想、14 个 session charter
07-coverage-gaps.md	覆盖率矩阵、Top 20 风险缺口、8 周路线图

八、结论与预期收益

ADR-080 在 Consequences 中给出明确的修复收益账：

• P0 修复消除 3 个安全漏洞与 2 个功能 Bug；
• P1 修复改善性能、可靠性与可维护性；
• P2 修复补上覆盖缺口、为生产环境加固系统；
• 目标分：P0+P1 完成后从 55 → 75+。

截至本档案 Status 行标注（2026-06-13），三个 P0 安全项已在 Rust sensing-server 边界收口，其中两项（#1 XFF、#3 URL 令牌）的结论是"无此漏洞面、回归测试钉死免疫"，一项（#2 异常泄露）以 error_response.rs 的通用错误体 + 服务端日志 + 关联 ID 机制落地，并同步关闭了 ADR-164 的 G11 项。该 crate 的安全边界整体说明可在 SECURITY.md 查阅。

对读者而言，这份档案最有借鉴价值的不是"修了什么"，而是一套可复用的质量治理方法：多智能体体检的量化打分与分级定责（P0/P1/P2 对应时间刻度）、对已归档代码的"重定界不背债"决策、以及"修复即测试"的验证纪律——每一个安全结论（哪怕是"本就不存在"）都要有回归测试作证，而测试必须设计成在旧行为上会失败，才能真正锁死历史漏洞的重现路径。