AG Grid 校验增强说明

1. 背景与本次目标

项目 AG Grid 表格统一使用 steelTradeAggrid 组件，数值列的编辑与粘贴校验通过 numberValidator + extractNumericRule 体系完成（详见 docs/AG-Grid编辑功能改造说明.md）。

在期现业务弹窗（分配方式 / 分配本次使用金额）的落地过程中，暴露了 4 个问题：

2. 增强点总览

3. 增强点一：CndInputNumber 新增 maxField 上限能力 新增

3.1 能力说明

新增 prop maxField（String，默认 ''，不传时行为完全不变）。 语义是「上限取自当前行的某个字段」——例如本次使用金额不能超过本行的可用金额 sPickAmt。

3.2 使用方式（列配置）

cellEditorFramework: Vue.extend(customMiddleware.createComponent(
  'CndInputNumber',
  {
    mark: 'vCurAmt',
    type: 'number',
    decimalDigit: 2,
    maxField: 'sPickAmt'   // ← 上限 = 本行 sPickAmt 字段值
  }
))

3.3 生效效果：输入即截断 + 气泡提示

在 setVal() 中实时判断（每次输入都执行，等效旧 TableInput 的 v-limit，但改为组件内实现）：

3.4 实现要点

// 取 maxField 指定字段的行值作为上限
getMaxFieldValue() {
  if (!this.maxField) return null
  const data = this.params && this.params.data
  if (!data) return null
  const max = Number(data[this.maxField])
  return Number.isFinite(max) ? max : null
}

// setVal() 中（整数位截断之后、emit 之前）
const maxFieldVal = this.getMaxFieldValue()
if (maxFieldVal !== null && this.childValue !== '' && ... && Number(this.childValue) > maxFieldVal) {
  this.childValue = String(maxFieldVal)
  this.showLimitTip(`不能超过${maxFieldVal}。`)
}

4. 增强点二：编辑器配置自动反推校验规则 增强

4.1 改动

extractNumericRule 的 CndInputNumber 分支新增 maxField 映射：

// 改前
max: props.range && props.range[1]

// 改后：maxField（字段引用）优先于 range[1]（静态上限）
max: props.maxField ? props.maxField : (props.range && props.range[1])

4.2 效果：单一配置来源

createComponent('CndInputNumber', {
  decimalDigit: 2,
  ...
}),
numericRule: {          // ← 需重复声明
  scale: 2,
  max: 'sPickAmt',
  allowNegative: false
}

createComponent('CndInputNumber', {
  decimalDigit: 2,
  maxField: 'sPickAmt'   // ← 校验规则由此反推
})

5. 修复点三：粘贴报错信息完善 修复

validateNumber 本已算出具体原因（result.message），但旧实现把它丢弃了， 报错只显示行列和原值，用户不知道「为什么不合法」。

各校验维度均可透出（由 validateNumber 提供）：

弹窗标题同步由「以下单元格格式不正确」改为「以下单元格数据不合法」（原因可能是超金额而非格式）。

6. 修复点四：批量粘贴校验漏检 修复

6.1 问题现象

6.2 根本原因

旧实现假设「剪贴板第 r 行 → 选区起点 + r 行」的简单线性映射；而 AG Grid v25 真实写入规则是 逐行遍历选区、剪贴板循环填充，且行数不整除时超出部分不写入。两者错位，导致校验行号与 实际写入行号不一致，取到的上限字段值（sPickAmt）张冠李戴。

6.3 修复：逐条对齐 AG Grid v25 写入规则

重写 processClipboardData，按三种规则收集「待校验单元格」，再统一校验：

// 规则② 核心（对齐 ag-grid pasteIntoActiveRange）
const abortRepeating = rangeRowCount % data.length !== 0
let indexOffset = 0, dataRowIndex = 0
for (let rowIndex = startRow; rowIndex <= endRow; rowIndex++) {
  const index = rowIndex - startRow
  let currentIndex = index - indexOffset
  if (currentIndex >= data.length) {
    if (abortRepeating) continue      // 不整除，该行不写入、不校验
    indexOffset += dataRowIndex; dataRowIndex = 0
    currentIndex = index - indexOffset
  }
  const clipboardRow = data[currentIndex]
  range.columns.forEach((column, colIdx) => {
    if (colIdx >= clipboardRow.length) return
    cells.push({ value: clipboardRow[colIdx], column, rowIndex })
  })
  dataRowIndex++
}

6.4 附带修复：行数据获取的虚拟滚动兜底

getRowDataByIndex 原先只用 getDisplayedRowAtIndex，虚拟滚动下未渲染行返回空， 导致上限字段取不到 → 上限校验被静默跳过（另一处漏检原因）。现增加行模型兜底：

getRowDataByIndex(rowIndex) {
  const api = this._lastFocusedGrid.api
  let node = api.getDisplayedRowAtIndex(rowIndex)
  if (!node && api.getModel) node = api.getModel().getRow(rowIndex)  // 兜底
  return node ? node.data : null
}

7. 业务落地：期现弹窗 vCurAmt 列

「本次使用金额」（vCurAmt）列由旧 TableInput 迁移至 CndInputNumber，并配置 maxField：

// 改前
{
  field: 'vCurAmt',
  editable: true,
  max: 'sPickAmt',
  cellEditor: 'TableInput'
}

// 改后
{
  field: 'vCurAmt',
  editable: true,
  cellEditorFramework: Vue.extend(customMiddleware.createComponent(
    'CndInputNumber',
    { mark: 'vCurAmt', type: 'number', decimalDigit: 2, maxField: 'sPickAmt' }
  ))
}

7.1 三条路径的最终行为

7.2 与旧 TableInput 的差异

8. 文件清单与影响面

本文档为 docs/AG-Grid编辑功能改造说明.md 的演进补充，描述 2026-09-11 的校验增强。