增量质检报告 · dzs/dzs-ai-content · v1.0.30

• 分支：v1.0.30
• 对比区间：7733b85c（base）→ 6818538c（head）
• 变更规模：8 个文件（含 2 个新增文件：internal/agent/format_pick.go、internal/agent/format_pick_test.go）
• 数据来源：codescan_git_diff、codescan_issues_diff（base/head 两版本对比）

---

一、增量结论速览

本次为一次功能性增量：把数据卡样式（占位符第 8 段 format）从「固定写死 chart」改为工具层按数据形态确定性选择，并把 format 取值枚举由 3 个扩为 7 个、同步对齐后台用词。质量层面本次无修复项（无消除的历史问题），新增 2 条均为新增文件中的 Low 级重复代码块，无 Critical/High/Medium 级回归。

---

二、修复的问题（0 条）

本次对比区间内，base 版本存在、head 版本已消除的问题 0 条。

即：本次改动是「新增能力 + 文案对齐」，并未顺带清理旧版历史问题；此前 internal/agent/tools.go 等文件中既有的复杂度/耦合类问题（如 GetPriceDataTool、GetIndexDataTool、GetMetricDataTool 的圈复杂度与高耦合）在本次推送中仍存在，属存量债务，非本次引入。

---

三、新增的问题（2 条）

均为 Low / Maintainability「重复代码块」，全部落在本次新增文件中，来源为工具真实对比数据：

3.1 internal/agent/format_pick.go:43

• 类型：Low / Maintainability — 重复代码块
• 描述：duplicated block of 4 lines (2 occurrences)
• 定位：pickDataFormat 中「单期返回 metric_card、否则返回 chart」的 4 行逻辑分别在 DataKindMetric 分支与 DataKindPrice, DataKindIndex 分支各出现一次：

  if shape.Periods == 1 {
      return placeholder.FormatMetricCard
  }
  return placeholder.FormatChart
  

• 影响：纯风格问题，无功能/正确性风险；两处逻辑当前一致，若后续调整「单期阈值」需两处同步修改，存在漏改隐患。
• 建议：抽出一个私有小助手（如 pickByPeriods(periods int) string）供两分支复用，消除重复并收敛单一修改点。

3.2 internal/agent/format_pick_test.go:46

• 类型：Low / Maintainability — 重复代码块
• 描述：duplicated block of 4 lines (3 occurrences)
• 定位：TestPickDataFormat 表驱动用例中，多条 dataFormatShape{...} + want: ... 结构体字面量形态高度雷同（3 处重复块）。
• 影响：测试用例的固有重复，可读性/维护性层面；不影响测试有效性。
• 建议：可保留（表驱动测试的重复通常可接受），如需消除可提取构造辅助函数或复用公共 shape 变量；若判定为可接受噪声，可登记为已知误报。

说明：以上 2 条即 codescan_issues_diff 返回的全部新增问题，未发现任何由本次改动引入的 Bug、安全、性能或复杂度类新增问题。

---

四、本次核心变更解读

4.1 业务逻辑：数据卡样式按形态确定性选择（新增 format_pick.go）

新增 pickDataFormat(shape dataFormatShape) string，依据工具已握有的字段（DataPoints 期数、ClassCode 是否分类维度、价格条件）由代码确定样式，不让模型自选，保证可测、不飘：

本期明确不产出的 3 个值（table_detail / table_compare / metric_card_mom），因 AI 工具取不到对应数据（属性明细桶 / 多品类对比 / C 端环比出口缺失），报告与注释中已显式标注边界，避免后续「顺手补上」造成契约违背。

4.2 调用点接入（internal/agent/tools.go）

3 处数据元素构造函数由原先统一写死 placeholder.FormatChart 改为调用 pickDataFormat(...)：

• buildPriceElement → 按 r.DataPoints + in.HasFilters 选择；
• buildIndexElement → 按 r.DataPoints 选择；
• buildMetricElement → 按 r.DataPoints + ClassCode 非空选择。

关键契约点：仅第 8 段取值变化，8 段结构、各段取值口径、时间档、维度段等均逐字未变，向后兼容（默认样式沿用原值 chart/table/metric_card）。

4.3 契约与文案对齐（pkg/placeholder/placeholder.go）

• format 常量由 3 个（chart/table/metric_card）扩为 7 个，新增 FormatChartBar/FormatTableCompare/FormatTableDetail/FormatMetricCardMom，均带基形态前缀，符合「客户端按前缀回落」约定。
• 展示层用词与后台 src/lib/placeholder.ts 对齐：FormatLabel（图表→折线图、表格→标准表、指标卡→数值卡 等）、DataKindLabel（期货→期货行情、指数→行业指数）、FieldLabel（代表价(全品类)→代表价、公开价→对外公开价 等）、RowDimensionLabel（日期×筛选条件→日期 × 筛选条件、属性值组合→属性明细 等）。
• 范围边界：仅「展示层 label」变化，不进 C 端响应白名单；段位与取数口径未变。

4.4 测试同步

format_pick_test.go（11 组形态 → 样式 + 7 值中文标签）、tools_test.go、placeholder_test.go、writer_test.go 中的元素标签断言随用词更新；tools_test.go 新增「指标 + 分类维度 → chart_bar」的 key 断言，覆盖新逻辑。

4.5 文档

AGENTS.md 新增「数据卡样式按形态选择」章节，记录背景、规则、本期边界与单测，便于后续维护。

---

五、风险与建议

1. 低风险改动：本次为「新增选择函数 + 替换写死值 + 文案对齐」，逻辑封闭、有表驱动单测覆盖（含零期/未知类型的安全默认分支），未发现新增 Bug/安全类问题。
2. 契约一致性需回归：format 段取值范围扩为 7 个且涉及客户端展示，建议在联调时确认 C 端对 chart_bar 的渲染与未知值回落行为符合预期；metric_card_mom/table_compare/table_detail 本期不产出，属预期，非缺陷。
3. 存量债务（非本次引入）：tools.go 的 GetPriceDataTool/GetIndexDataTool/GetMetricDataTool 圈复杂度偏高（26~29）、main.go 高耦合等为历史问题，可按版本规划单独排期治理。
4. 新增 2 条 Low 重复代码：建议对 format_pick.go 的重复分支做一次小重构（提取 helper）；测试文件的重复可评估后决定是否保留/登记误报。

---

六、附：影响面清单（本次变更文件）