用途:在重构涉及字段映射(dataIndex、columns、枚举映射、类型转换、render/formatter)时触发,防止根据类型定义推测字段名而引入错误,并避免外部数据同步覆盖用户手动调整。
主要能力:提供字段名验证、枚举映射完整性检查、运行时测试与对比验证清单;给出常见陷阱示例,包括类型定义歧义、枚举遗漏、TypeScript 无法检测的字段错误、rowKey 使用可选字段,以及同步覆盖时源端缺失清空目标值、人工调整被下次同步覆盖。
使用方式:重构前用 git show HEAD~1:src/components/InvoiceHistoryTab.tsx 查看原始代码实际使用;对照原始 dataIndex、后端 API 字段名与枚举值;优先使用必填字段;运行 npm run type-check 与 npm run lint,并在开发环境检查 Invalid Date、undefined、空白及 rowKey 唯一性。同步场景中,写 entity.setXxx 前判断 null,用户可编辑字段采用 last-sync-value 伴随策略,在 mapping 表记录 last_xxx,覆盖前判断目标是否仍等于上次同步值,跳过时打 log.info。
适用场景:表格列定义重构、枚举类型映射重构、数据转换逻辑重构、类型定义存在多个相似字段,以及从外部源(雷珏、ERP、CRM)定时或手动同步数据到本系统。
限制:TypeScript 类型检查通过是必要但不充分;不可由用户编辑的字段、计算字段、主数据强一致场景不需要伴随策略;具体项目字段与实现细节需以实际代码为准。