增量质检报告 · dzs/dzs-api v1.0.71

• 基线（base）：cc8d2bed2974dc41bf82fe43de2148f0dbae0ca3
• 目标（head）：5509cab5bcc22f4a8659a982749ba021f27afb3e
• 变更面：git diff 仅命中 1 个文件 src/services/data_service.rs（新增 ~55 行实现 + ~40 行测试，另少量 let → let mut），无其他文件改动。
• 数据来源：本报告“修复/新增问题”两章严格取自 codescan.issues_diff 的真实结果；代码逻辑结论来自对 data_service.rs 相关函数的逐段阅读。

---

一、变更意图与实现概述

本次是一次单一功能迭代：为数据占位符接口（GET /api/v1/data/{articleId}/{shortCode}）返回的表格响应新增「环比」列（MoM），口径为“与同一系列上一期相比的百分比”，对应工单 dzs-admin#33 v2 带环比卡。

核心新增件（src/services/data_service.rs）：

设计契约（注释声明）：响应结构“只加不改”——老客户端忽略多出来的这一列，已发布文章不受影响。

---

二、修改点逐条说明

1. 指标表（resolve_metric，约 data_service.rs:708 处）

// 环比列（带环比卡 / 标准表「值 ＋ 环比」）：与同系列上一期比（行已按期升序）
let value_index = if attr_prefix.is_some() { 2 } else { 1 };
let table_rows = with_mom(table_rows, value_index, attr_prefix.map(|_| 1));
columns.push(mom_column());

• 行结构：无分类 [期, 值]（value_index=1、单系列）；有分类 [期, 分类, 值]（value_index=2、按“分类”列分组）。下标与 metric_columns 一致，正确。
• 注意：empty_metric_resp 在此之前 return，因此空数据响应不含 mom 列（见风险 R3）。

2. 公开价分桶明细表（price_buckets，约 data_service.rs:885）

let table_rows = with_mom(table_rows, 2, Some(1));   // 行 [日期, 属性组合, 价格]
columns.push(mom_column());

• public_price_rows 按 price_date DESC, id DESC 查询后 rows.reverse() → 全局按日期升序，同一“属性组合”跨期有序；分组键为列 1 的属性组合标签（见风险 R1）。

3. 公开价按日均值表（price_daily，约 data_service.rs:1005）

// 环比列：仅均值表加（PriceDaily::Range 无单一数值列，加了也没有可比口径）
let (mut columns, table_rows) = if matches!(mode, PriceDaily::Range) {
    (columns, table_rows)
} else {
    let mut cols = columns;
    cols.push(mom_column());
    (cols, with_mom(table_rows, 1, None))   // 行 [日期, 均价, 最低, 最高]，取“均价”列，单系列
};

• 仅 Average / WholeCommodity 加环比，Range 口径有意不加（注释已说明，合理）。

4. 行业指数表（index_series，约 data_service.rs:1770）

// 环比列：多字段（现货/期货指数并排）按「指数」列分组，单字段恒一条系列
let value_index = if multi { 2 } else { 1 };
let table_rows = with_mom(table_rows, value_index, multi.then_some(1));
columns.push(mom_column());

• 调用发生在 if multi { table_rows.sort_by((date, label)) } 之后，行按 (日期, 指数名) 升序，同一指数跨期有序；multi=false 时 resolve_index 只解析单个行业、单字段 → 单系列，None 正确。

5. with_mom 实现要点（正确性核验，均通过）

• 追加次序安全：先在 cells 里按原下标读值、算环比，最后统一 row.push(cell)，不会因边算边 push 造成下标漂移。
• 除零/NaN：prev != 0.0 守卫，前值为 0 → null；serde_json 的 Value::from(NaN/inf) 落为 Null，不会 panic。
• 舍入：((cur-prev)/prev*10_000.0).round()/100.0 即“百分数保留 2 位小数”（测试用 1.224 → 1.22 验证）。
• 列/行长度一致：正常路径下，columns 与每行都各 +1，长度对齐。

---

三、修复的问题（取自 codescan.issues_diff）

工具判定：修复 10 条，全部集中在 src/services/data_service.rs，类型均为 Medium/Complexity 或 Low/Maintainability：

⚠️ 复核结论（重要）：这 10 条并非真正的修复，而是行号平移导致的“假修复”。本次在 data_service.rs 前部插入了若干行（各调用点 + with_mom 块），使原问题的行号整体后移（+78 行的那些：2445→2523、2718→2796、3066→3144、3183→3261、3456→3534、3823→3901、3934→4012；前部的 1770→1793 为 +23）。工具以“行号”匹配问题，行号一变即被同时记为“删除(修复)”与“新增”。对照第四章可见它们一一对应、性质完全一致。

---

四、新增的问题（取自 codescan.issues_diff）

工具判定：新增 11 条，全部为 Medium/Low，无 Critical/High：

结论：真正由本次变更引入的新问题只有 1 条——with_mom 的“高耦合”告警。

对该唯一新增告警的判定：大概率误报（FP，低价值）。

• with_mom 是一个纯函数（输入 Vec<Vec<Value>> → 输出同类型），其“依赖 15 个函数”统计的是对 Value::from / as_f64 / as_str / HashMap::get / insert / round / ... 等标准库/内建方法与 Value 相关 API 的调用，属启发式“函数级扇出”计数，不代表真实模块耦合。
• 同一文件内既有大量同类告警且长期存在（describe 依赖 19、latest_value 依赖 12、load_attr_resolver 依赖 31……），with_mom 的 15 与代码库既有风格一致，不构成新增风险。
• 建议：无需为消除该告警重构 with_mom（无收益）；若要求清零，可将其保留为当前形态并在告警白名单中登记。

---

五、人工正确性 / 风险分析（超出扫描器覆盖）

以下为阅读代码后发现的语义/健壮性风险，扫描器未报告，供评审参考：

R1｜系列分组用“显示标签”，而非稳定 key（建议关注，中） with_mom 的分组键取自表格里的显示文本列（指标=“分类”名、价格=“属性组合”描述、指数=“指数”名），而各调用点构造 series 用的是稳定 key（attr_value_code / bucket_key / source_type）。二者不一致：

• 若两个不同系列（不同 code / 不同 attr_values / 不同 source_type）解析出的显示文本相同（例如属性名、属性值名重名导致 describe() / value_name() 输出碰撞），with_mom 会把它们当作同一条系列，从而产生跨系列的错误环比。
• 概率取决于数据，但这是“用展示串当主键”的固有隐患。建议：让 with_mom 接受稳定的系列 key（或让调用点传入 key 列并在输出前剥离），或在代码注释中显式声明“标签在同一响应内唯一”为前置条件。

R2｜空值/缺失期采用“跨空期 carry-forward”，与“上一期”字面口径可能不符（建议确认，中） 实现中当某期数值为 null 时，不更新 last[key]；因此下一期的环比会与“最近一个非空期”比较，而非“相邻上一期”。同理，若中间整期缺失（行不存在），环比也跨期比较。测试用例仅覆盖了“末尾为 null”，未覆盖“中间空洞”。若产品口径要求“环比=与日历相邻上一期”，则空期后应输出 null 而非跨期百分比。建议：与产品确认，并补一条“中间空期”的单测固化预期。

R3｜空数据响应不含 mom 列，列集合前后不一致（轻微，低） empty_metric_resp / empty_price_resp / empty_futures_resp 均在 columns.push(mom_column()) 之前返回，故空数据时无 mom 列。对有缓存/按列渲染的前端，可能造成同一短码“有数据/无数据”两种列头。功能上影响有限（空表无行），但属契约不一致，建议确认前端是否依赖列集合稳定。

R4｜期货表未加环比，范围一致性存疑（观察，低） 本次给 指标 / 公开价分桶 / 公开价均值 / 指数 四类表加了 mom，但 futures_main_series（行 [交易日, 值]）与 futures_contract_series（行 [交易日, 合约, 值]，形态与 price_buckets 几乎一致）未加。若工单期望“所有标准表”都有环比，则期货表属覆盖遗漏；若有意排除，建议在注释中标注范围边界。建议：与需求方核对期货表是否在范围内。

R5｜已核验为“无问题”的点（正向确认）

• 追加单元格采用“先算后 push”，下标不会漂移；
• 除零守卫 + serde_json 对 NaN/inf → Null 的行为，不会 panic / 不会产出非法数值；
• 方差不限于：Range 口径显式不加环比（口径正确）；各调用点 value_index 与实际列结构匹配；
• 舍入与测试期望一致（保留 2 位小数）。

附：版本内存在的 Critical 0 条 / High 15 条（market_service/cache.rs、metric_service/cache.rs 的 MD5 弱算法，response_cache.rs 的 token 日志泄露，redis_util.rs 不可达代码）均为存量问题，不在本次 diff 范围内，本报告不计入增量；如需处理请另行立项。

---

六、结论与建议

1. 本次变更聚焦、无回归面：仅动 data_service.rs，为表格响应“只加不改”地追加环比列，逻辑正确、边界（除零/空值/舍入）已由单测覆盖。
2. 未引入 Critical/High 问题；“新增 11 条”中 10 条为行号平移的假新增，唯一真实新增（with_mom 高耦合）判定为启发式误报，无需重构。
3. “修复 10 条”实为行号平移的假修复，不应作为本次“问题减少”的业绩口径（对比报告时请注意此噪声）。
4. 建议跟进 3 项人工风险：R1（分组键用显示标签的碰撞隐患）、R2（跨空期环比语义，需产品确认+补测）、R4（期货表是否应加环比）。
5. R2/R3 各补 1~2 条单测（中间空期、空数据列集合）即可显著提升契约确定性。