Просмотр исходного кода

feat(T03): utils 指标时间轴工具函数 — resolveChange 单一事实来源 + X 轴抽稀/缺失期合并

- indicator-change.js: 新增 resolveChange/resolveTextChange/formatDelta(含unitMismatch)/roundSig/formatCompareDate/chartRenderConfig/axisLabelIndices;resolveChangeStyle/colorClassFor 保留(@deprecated)
- indicator-timeline.js: 新建,mergePeriodDates/computeAxisLabelIndices/sortByDate/formatAxisDate(走parseDate)/hasUnitMismatch/hasUploadDate
- 修复 S7 缺失导出由本次 api.js 变更一并完成(见下一 commit)
E2E Test Bot 2 недель назад
Родитель
Сommit
6ea9588516
2 измененных файлов с 213 добавлено и 26 удалено
  1. 121 26
      cfc-frontend/utils/indicator-change.js
  2. 92 0
      cfc-frontend/utils/indicator-timeline.js

+ 121 - 26
cfc-frontend/utils/indicator-change.js

@@ -2,28 +2,139 @@
  * 指标变化展示规则纯函数
  * 规则来源:design.md §8 变化颜色与箭头规则
  * 颜色映射:改善=绿 / 恶化=红 / 中性=灰
+ *
+ * 单一事实来源:前端不自行推导改善/恶化,只消费后端下发的 trendCode。
+ * 参见 design.md §6.6、§1.4 原则 2。
  */
 
 /**
- * 由 good_direction × movement 推导展示样式
- * @param {string} goodDirection higher_is_better|lower_is_better|in_range_is_better|neutral
- * @param {string} movement up|down|flat
- * @returns {{trendLabel:string, cssClass:string, arrow:string}}
+ * 【单一事实来源】由后端 trendCode + movement 推导展示样式。
+ * 所有展示变化的位置(报告详情/身维度/速查/菌群/时间轴/管理端)必须走这里。
+ *
+ * trendCode 五值枚举(含 D12 的 pending_backfill):
+ *   'improved' | 'worsened' | 'flat' | 'first_record' | 'pending_backfill'
+ *
+ * 关键约定:
+ *   1. trendLabel 优先取后端下发的值,前端不改写(合规:文案统一)
+ *   2. 前端【禁止】用 previous == null 自行判断是"首次"还是"整理中" —— 只能看 trendCode
+ *   3. movement === 'none' 时不渲染箭头
+ *
+ * @param {string} trendCode
+ * @param {string} movement 'up'|'down'|'flat'|'changed'|'unchanged'|'none'
+ * @param {string} backendLabel 后端下发的 trendLabel(优先使用,为空时才用本地兜底)
+ * @returns {{trendLabel:string, cssClass:string, arrow:string, colorClass:string, showArrow:boolean}}
  */
+export function resolveChange(trendCode, movement, backendLabel) {
+  var mv = movement || 'flat'
+  var arrow = mv === 'up' ? '↑' : (mv === 'down' ? '↓' : '→')
+  var label = backendLabel || ''
+
+  // D12 新增两档:无对比对象。灰色、无箭头。
+  if (trendCode === 'first_record') {
+    return { trendLabel: label || '首次记录 · 暂无对比', cssClass: 'degrade', arrow: '', colorClass: 'gray-text', showArrow: false }
+  }
+  if (trendCode === 'pending_backfill') {
+    return { trendLabel: label || '历史数据整理中,暂无法对比', cssClass: 'degrade', arrow: '', colorClass: 'gray-text', showArrow: false }
+  }
+
+  if (trendCode === 'improved') {
+    return { trendLabel: label || '改善', cssClass: 'impr', arrow: arrow, colorClass: 'green-text', showArrow: true }
+  }
+  if (trendCode === 'worsened') {
+    return { trendLabel: label || '恶化', cssClass: 'worst', arrow: arrow, colorClass: 'red-text', showArrow: true }
+  }
+  return { trendLabel: label || '基本持平', cssClass: 'flat', arrow: mv === 'none' ? '' : arrow, colorClass: 'gray-text', showArrow: mv !== 'none' }
+}
+
+/**
+ * 非数值指标:有变化 / 无变化,不给颜色(合规红线)
+ */
+export function resolveTextChange(movement) {
+  return movement === 'unchanged'
+    ? { trendLabel: '无变化', cssClass: 'flat', arrow: '→', colorClass: 'gray-text' }
+    : { trendLabel: '有变化', cssClass: 'flat', arrow: '→', colorClass: 'gray-text' }
+}
+
+// ---------- 格式化 ----------
+
+/**
+ * Δ 展示文本(PRD §6.4)。列表窄位省略单位由调用方传 unit='' 实现。
+ * @param {number|null} delta
+ * @param {number|null} deltaPct
+ * @param {boolean} unitMismatch 单位跨期不一致 → 百分比显示 '—'
+ */
+export function formatDelta(delta, deltaPct, unitMismatch) {
+  if (delta === null || delta === undefined || isNaN(delta)) return '--'
+  var sign = delta > 0 ? '+' : ''
+  var d = roundSig(delta)                       // PRD §6.4 有效数字规则
+  if (unitMismatch || deltaPct === null || deltaPct === undefined || isNaN(deltaPct)) {
+    return sign + d + ' (—)'
+  }
+  var pctSign = deltaPct > 0 ? '+' : ''
+  return sign + d + ' (' + pctSign + deltaPct + '%)'
+}
+
+/** PRD §6.4 有效数字:≥100 整数;10–100 一位小数;<10 两位小数 */
+export function roundSig(v) {
+  var a = Math.abs(v)
+  if (a >= 100) return String(Math.round(v))
+  if (a >= 10)  return v.toFixed(1)
+  return v.toFixed(2)
+}
+
+/**
+ * 「较 MM-DD」日期文案(PRD §6.6)
+ * @param {string} prevDate 'yyyy-MM-dd'
+ * @param {string} currDate 'yyyy-MM-dd' 用于判断是否同年
+ * @param {string} dateSource 'real'|'upload'|'confirm'|'unknown'
+ */
+export function formatCompareDate(prevDate, currDate, dateSource) {
+  if (!prevDate) return '日期未知'
+  var star = (dateSource && dateSource !== 'real' && dateSource !== 'unknown') ? '*' : ''
+  if (!currDate) return prevDate + star
+  var sameYear = String(prevDate).slice(0, 4) === String(currDate).slice(0, 4)
+  return (sameYear ? String(prevDate).slice(5) : prevDate) + star
+}
+
+/**
+ * 图表形态 → 是否画图 / 是否标值(消费后端 chartMode,不自行判断)
+ * @param {string} chartMode 'empty'|'single'|'pair'|'line'|'line_aggregated'
+ * @param {number} n 期数
+ */
+export function chartRenderConfig(chartMode, n) {
+  if (chartMode === 'empty' || chartMode === 'single') return { draw: false, showValues: false, labelMode: 'none' }
+  if (chartMode === 'pair')                            return { draw: false, showValues: true,  labelMode: 'all' }
+  if (chartMode === 'line_aggregated')                 return { draw: true,  showValues: false, labelMode: 'sparse' }
+  return { draw: true, showValues: n <= 8, labelMode: n <= 8 ? 'all' : 'sparse' }
+}
+
+/** X 轴标签下标抽稀(PRD §5.2 选型表) */
+export function axisLabelIndices(n) {
+  if (n <= 8) { var all = []; for (var i = 0; i < n; i++) all.push(i); return all }
+  if (n <= 19) return unique([0, Math.floor((n - 1) / 3), Math.floor(2 * (n - 1) / 3), n - 1])
+  return unique([0, Math.floor(n / 2), n - 1])
+}
+
+function unique(arr) {
+  return arr.filter(function(v, i, self) { return self.indexOf(v) === i })
+}
+
+// ---------- 兼容保留(老接口兜底,不删) ----------
+
+/** @deprecated 仅供无 trendCode 的老数据兜底(如 member_indicator_current.trend)。
+ *  新代码一律用 resolveChange(trendCode, movement)。 */
 export function resolveChangeStyle(goodDirection, movement) {
   var gd = goodDirection || 'neutral'
   var mv = movement || 'flat'
   if (mv === 'flat') {
     return { trendLabel: '中性', cssClass: 'flat', arrow: '→' }
   }
-  // 是否"改善":higher_is_better 升=改善;lower_is_better 降=改善;in_range 视区间判定(此处交给 withRange 变体)
   var isImprove = false
   if (gd === 'higher_is_better') {
     isImprove = mv === 'up'
   } else if (gd === 'lower_is_better') {
     isImprove = mv === 'down'
   } else {
-    // neutral / in_range_is_better(一期 in_range 的管理端手配方向;区间内移动判定留二期,先按中性展示)
     return {
       trendLabel: '中性',
       cssClass: gd === 'in_range_is_better' ? 'neutral-up' : mv === 'up' ? 'neutral-up' : 'neutral-down',
@@ -36,29 +147,13 @@ export function resolveChangeStyle(goodDirection, movement) {
   return { trendLabel: '恶化', cssClass: gd === 'higher_is_better' ? 'worst-down' : 'worst-up', arrow: mv === 'up' ? '↑' : '↓' }
 }
 
-/**
- * Δ 展示文本 "±x (±x%)"
- * @param {number|null} delta
- * @param {number|null} deltaPct
- * @returns {string}
- */
-export function formatDelta(delta, deltaPct) {
-  if (delta === null || delta === undefined || isNaN(delta)) return '--'
-  var sign = delta > 0 ? '+' : ''
-  if (deltaPct === null || deltaPct === undefined || isNaN(deltaPct)) {
-    return sign + delta
-  }
-  var pctSign = deltaPct > 0 ? '+' : ''
-  return sign + delta + ' (' + pctSign + deltaPct + '%)'
-}
-
 /**
  * CSS 颜色类:改善=green-text 恶化=red-text 中性=gray-text
- * @param {string} cssClass resolveChangeStyle 返回的类
+ * @param {string} cssClass resolveChangeStyle 返回的类(兼容老 cssClass:impr-up/worst-down/neutral-up/flat/degrade)
  * @returns {string}
  */
 export function colorClassFor(cssClass) {
-  if (cssClass.indexOf('impr') === 0) return 'green-text'
-  if (cssClass.indexOf('worst') === 0) return 'red-text'
+  if (cssClass === 'impr' || cssClass.indexOf('impr') === 0) return 'green-text'
+  if (cssClass === 'worst' || cssClass.indexOf('worst') === 0) return 'red-text'
   return 'gray-text'
-}
+}

+ 92 - 0
cfc-frontend/utils/indicator-timeline.js

@@ -0,0 +1,92 @@
+/**
+ * 指标时间轴工具函数
+ * 职责:X 轴抽稀、缺失期合并、日期格式化
+ * 约束:日期一律走 parseDate,禁止 new Date(string)
+ */
+import { parseDate, formatDate } from './format.js'
+import { axisLabelIndices } from './indicator-change.js'
+
+/**
+ * 合并 points 与 missingPeriods,得到完整的 X 轴日期序列(去重、升序)
+ * 用于 TrendChart 的 allPeriodDates prop。
+ *
+ * @param {Array} points          [{ reportDate, ... }]
+ * @param {Array} missingPeriods  [{ reportDate, ... }]
+ * @returns {string[]}  yyyy-MM-dd 字符串数组,升序、去重
+ */
+export function mergePeriodDates(points, missingPeriods) {
+  var set = {}
+  ;(points || []).forEach(function(p) {
+    if (p && p.reportDate) set[p.reportDate] = true
+  })
+  ;(missingPeriods || []).forEach(function(m) {
+    if (m && m.reportDate) set[m.reportDate] = true
+  })
+  return Object.keys(set).sort()
+}
+
+/**
+ * 按 allPeriodDates.length 返回要显示标签的下标(复用 indicator-change.js)
+ * @param {string[]} allPeriodDates  完整日期序列(升序)
+ * @returns {number[]}
+ */
+export function computeAxisLabelIndices(allPeriodDates) {
+  var n = (allPeriodDates && allPeriodDates.length) || 0
+  return axisLabelIndices(n)
+}
+
+/**
+ * 把点集按时间升序排列,返回排序结果与首/末点索引
+ * @param {Array} points  [{ reportDate, numericValue, unit, dateSource, ... }]
+ * @returns {{firstIdx:number, lastIdx:number, sorted:Array}}
+ */
+export function sortByDate(points) {
+  if (!points || points.length === 0) return { firstIdx: 0, lastIdx: 0, sorted: [] }
+  var sorted = points.slice().sort(function(a, b) {
+    return String(a.reportDate || '').localeCompare(String(b.reportDate || ''))
+  })
+  return { firstIdx: 0, lastIdx: sorted.length - 1, sorted: sorted }
+}
+
+/**
+ * 把日期字符串格式化为展示用文案(MM-DD 或 yyyy-MM-dd)
+ * 走 parseDate 解析,返回格式化后字符串。
+ *
+ * @param {string} dateStr  'yyyy-MM-dd' 或 ISO 格式
+ * @param {boolean} short   true → 'MM-DD',false → 'yyyy-MM-dd'
+ * @returns {string}
+ */
+export function formatAxisDate(dateStr, short) {
+  if (!dateStr) return ''
+  var d = parseDate(dateStr)
+  if (!d) return String(dateStr)
+  if (short) {
+    var m = ('0' + (d.getMonth() + 1)).slice(-2)
+    var day = ('0' + d.getDate()).slice(-2)
+    return m + '-' + day
+  }
+  return formatDate(dateStr)
+}
+
+/**
+ * 判断 points 中是否存在与 latest.unit 不一致的 unit(供 * 标记)
+ * @param {Array} points
+ * @param {string} latestUnit
+ * @returns {boolean}
+ */
+export function hasUnitMismatch(points, latestUnit) {
+  if (!points || !latestUnit) return false
+  return points.some(function(p) { return p && p.unit && p.unit !== latestUnit })
+}
+
+/**
+ * 判断是否存在 dateSource 非 real 的观测(用于上传日 * 标记)
+ * @param {Array} points
+ * @returns {boolean}
+ */
+export function hasUploadDate(points) {
+  if (!points) return false
+  return points.some(function(p) {
+    return p && p.dateSource && p.dateSource !== 'real' && p.dateSource !== 'unknown'
+  })
+}