【寻迹校园 HarmonyOS NEXT 实战 20】标准值与历史文本共存分类词表升级时如何避免静默改坏旧数据这是“寻迹校园 HarmonyOS NEXT 实战”系列第 20 篇。本文结合ReportTaxonomy.ets与发布表单的编辑恢复逻辑说明新建记录如何只写权威分类和地点旧记录如何临时保留已下线文本以及为什么词表升级不能顺手批量改库。上图为原创生成的技术插画不是项目截图。左侧是当前标准词表右侧是历史记录中间的兼容层允许旧值被看见和确认但不会悄悄把它伪装成新的标准值。一、词表升级为什么会伤到旧数据校园失物应用上线后分类和地点一定会变化“电子产品”统一改成“数码”“一卡通”合并到“证卡”“一教”规范为“第一教学楼附近”新增宿舍区服务站下线已经撤销的临时领取点。如果页面只渲染最新选项打开旧记录编辑时历史值可能没有任何选项被选中。用户保存其他字段后页面又可能把分类清空或强制替换成默认项。更危险的是自动模糊映射。系统若仅凭文字相似把“一教东门”改成“第一教学楼附近”就可能改变事件真实地点。二、先区分 label、value 与 filterKeyword项目为地点定义三类字段exportclassReportAreaOption{label:string;value:string;filterKeyword:string;}newReportAreaOption(第一教学楼,第一教学楼附近,第一教学楼)label页面上的短标签value写入报告的标准文本filterKeyword首页筛选时使用的稳定片段。发布页可以显示“第一教学楼”保存“第一教学楼附近”首页按“第一教学楼”片段匹配。三者语义明确后页面文案变化不需要直接改坏历史数据。三、当前权威分类和地点项目统一导出 9 个分类箱包、证卡、数码、钥匙、衣物、雨具、水杯、书籍、其他地点则包含第一教学楼、图书馆、体育馆、食堂、保卫处、宿舍区和其他区域并分别配置保存值与筛选关键词。发布页和首页筛选都从ReportTaxonomy.ets导入不再分别维护数组。这样新增或重命名选项时至少不会出现“能发布但筛不到”的页面级分叉。权威词表只是当前单校演示合同不是全国高校通用标准。四、新建记录只提供标准值新建发布页初始category与area都为空。categoryOptions()和areaOptions()首先复制权威集合因此用户只能从当前标准选项中选择。这能保证新数据持续收敛而不是继续产生“一教”“一号教学楼”“第一教学楼东边”等多个同义文本。标准化带来的收益包括类别可以精确筛选地点可以用稳定关键词匹配统计结果不需要大量同义词清洗匹配理由更容易解释后续迁移有明确源版本。如果产品需要自由文本补充应增加单独的详细地点字段而不是破坏标准值字段。五、编辑旧记录时把历史值临时追加进去编辑模式先从 Repository 加载原记录。若历史分类不在当前权威数组中页面把它追加到本次选项privatecategoryOptions():string[]{constoptions:string[][];REPORT_CATEGORY_OPTIONS.forEach((value:string)options.push(value));if(this.category.trim().length0!options.includes(this.category)){options.push(this.category);}returnoptions;}地点也做相同处理但会明确标记“保留”if(this.area.trim().length0!options.some((option:ReportAreaOption)option.valuethis.area)){options.push(newReportAreaOption(保留${this.area},this.area,this.area));}临时选项只属于当前记录的编辑会话不会被写回全局词表也不会让后续新建页面出现这个旧值。六、为什么“保留旧值”比自动替换更安全用户打开旧记录时可能只想更换照片。如果系统在后台自动把分类或地点映射成新值这次无关编辑就会改变历史事实。保留策略把决定权交给用户不改分类地点原值继续保存明确选择新标准项保存为新值无法确认映射保持原值不猜测需要批量治理进入独立迁移流程。这种做法牺牲了一点数据整齐度但避免静默数据损坏。对于地点、状态、身份和金额等关键字段保守通常比自动“纠正”更安全。上图展示两条路径新建记录只从标准词表写入编辑旧记录时兼容层把当前历史值作为临时选项恢复只有用户明确选择后才迁移到新的标准值。七、分类精确筛选会如何处理历史值第 18 篇介绍过类别筛选采用精确匹配。若旧记录类别是“电子产品”当前筛选项只有“数码”选择“数码”不会自动命中它。这是已知兼容边界。当前项目仍可以通过关键词搜索标题、类别、地点和公开描述找到历史文本但不会把“电子产品”擅自解释成“数码”。若产品明确确认两者等价应建立版本化映射表旧值新值生效版本是否自动迁移说明电子产品数码v2需确认范围大体一致一卡通证卡v2可评估需要检查其他证件类型一教东门第一教学楼附近v2不自动可能丢失方位信息映射必须有产品语义不应只靠字符串相似度。八、地点片段匹配也不是万能兼容标准地点保存“图书馆服务台”筛选关键词“图书馆”片段匹配可以覆盖同一地点的标准文本。但历史记录若写“老馆南门”它不包含“图书馆”当前标准筛选不会命中。可以通过关键词搜索找到也可以在迁移时由用户确认映射。不要为了兼容所有旧文本把地点筛选改成大量模糊 OR。规则越宽误命中越多用户越难理解为什么结果出现。九、词表唯一性必须自动测试共享词表一旦出现重复 valueArkUIForEachKey、选择状态和筛选结果都可能异常。项目测试固定检查assert.equal(newSet(REPORT_CATEGORY_OPTIONS).size,REPORT_CATEGORY_OPTIONS.length);assert.equal(newSet(REPORT_AREA_OPTIONS.map(optionoption.value)).size,REPORT_AREA_OPTIONS.length);assert.ok(REPORT_AREA_OPTIONS.every(optionoption.labeloption.valueoption.filterKeyword));这类断言成本低却能在词表提交时立刻发现重复、空字段或不完整配置。若未来引入稳定 ID还应检查 ID 唯一、显示文案非空、旧值映射无环、版本号单调和默认项存在。十、不要用显示文案作为长期主键当前演示项目使用中文标准值代码直观但跨校、国际化和长期演进时更推荐稳定内部 IDcategoryId: DIGITAL categoryLabel: 数码 areaId: CAMPUS_A_LIBRARY_DESK areaLabel: 图书馆服务台 taxonomyVersion: 2显示文案可以从资源或配置读取ID 保持稳定。筛选、统计和远端接口围绕 ID不因中文文案调整而变化。但把现有数据升级到 ID 也需要显式迁移。不能在没有映射和备份时直接把文本列删除。十一、一次安全词表迁移应该包含什么正式迁移至少分为六步冻结旧词表版本与所有真实旧值给出确定映射、需用户确认和不可映射三类清单备份或保留原始字段幂等执行迁移并记录版本对不可映射记录继续提供编辑回显验证筛选、统计、匹配和回滚。如果数据已同步到云端还要考虑多版本客户端并存。旧客户端可能继续写旧值新客户端必须识别来源版本服务端也要进行合同校验。十二、草稿同样需要历史值兼容词表升级时不只有正式报告存在旧值未提交草稿也可能保存旧分类和地点。发布页恢复草稿后同样通过categoryOptions()与areaOptions()合并当前值因此不会因为应用升级把用户尚未提交的内容清空。但用户最终提交旧值是否允许需要产品策略。当前实现允许保留并提交因为 Service 只检查文本长度没有强制校验值必须属于当前词表。这保证兼容性也意味着数据标准化不是强制门禁。未来若要求新提交必须标准化应区分“历史正式记录编辑”和“旧草稿重新提交”并给用户明确转换提示。十三、Service 校验与词表校验的边界当前ReportService.validateDraft()验证标题、分类、区域、日期、公开描述、私密特征、敏感内容和图片数量但分类与地点只做最小长度检查。这是为了允许历史文本继续保存。若直接改成REPORT_CATEGORY_OPTIONS.includes(category)旧记录编辑会全部失败。更稳的接口可以携带上下文新建模式要求标准值编辑模式允许“原历史值或标准值”迁移模式则要求用户确认。规则放在 Service页面只展示原因。十四、跨学校后不应继续硬编码当前词表服务单校演示7 个区域可以在代码里稳定维护。跨学校后校园区域、校区、服务点和别名会快速增长。届时需要新的配置合同schoolId/campusIdtaxonomy 版本稳定 category/area ID多语言 label筛选关键词或别名启用/停用时间客户端缓存与离线回退旧版本兼容期限。配置化不等于把一段 JSON 下载到页面。仍应经过 Repository/Service 校验避免重复 ID、空字段或恶意配置破坏筛选。十五、运行现有契约测试共享词表唯一性、六维筛选和历史文本相关基础契约可以通过powershell-ExecutionPolicy Bypass-File.\scripts\test-report-filter.ps1该测试能证明权威数组与纯筛选规则不能证明真实旧库迁移、ArkUI 编辑回显、草稿跨版本恢复或远端配置。设备层应准备至少三条旧数据旧分类、旧地点、两者同时为旧值。分别验证打开编辑、只改照片保存、主动换为标准值、取消编辑和重新启动后的结果。十六、发布前检查清单每次调整词表前应确认新建页只出现当前标准项首页筛选和发布表单引用同一权威源label/value/filterKeyword 没有混用历史正式记录能完整回显旧草稿不会被清空未确认的旧值不会自动替换唯一性与空字段测试通过搜索和分类筛选的兼容差异已有说明是否需要版本化迁移、备份与回滚跨校需求是否已经超过硬编码边界。十七、词表变更前的影响分析修改一个分类名称会同时影响新建表单、编辑回显、首页筛选、匹配理由、统计聚合、草稿恢复和远端接口。变更评审应先列出当前标准值、真实历史值、拟映射值与不可映射值再明确哪些允许自动迁移、哪些必须由用户确认。尤其要区分显示文案调整和业务语义调整。只改 label 通常不应触碰历史数据合并或拆分类别则会改变统计口径需要版本号、迁移说明和回滚方案。若没有这些证据宁可暂时保留旧值也不要为了界面整齐静默重写事实。十八、迁移失败、回滚与脏数据处理批量迁移必须幂等同一版本重复执行不会二次改写执行中断后可以从记录的进度继续。原始值应保留到验收完成映射失败的记录进入明确清单不能被默认值覆盖。只有迁移数量、未映射数量和抽样复核都满足预期后才提升 taxonomy 版本。确定等价的旧值可按版本映射信息可能丢失的地点必须人工确认空值和非法值要单独统计新旧客户端并存时服务端要识别来源版本回滚时恢复原始字段与旧词表不能只降客户端代码。这种流程比模糊字符串相似更慢但能避免不可逆的数据污染也让运营、产品和开发对迁移结果使用同一份证据。十九、可追踪验收与长期治理验收记录应包含词表版本、变更原因、映射表、迁移脚本哈希、执行数量、异常数量、回滚演练和筛选回归结果。设备测试还要覆盖旧正式记录、旧草稿、新建记录和主动改选标准值四条路径确认显示、保存与再次启动后一致。长期看分类和地点应成为带稳定 ID、启停时间和别名的配置合同。页面只消费经 Repository 与 Service 校验后的有效模型配置下载失败时使用最后一次可信版本并向运维暴露版本差异而不是让页面直接解析任意远端 JSON。二十、本文小结词表升级的目标不是让数据库看起来更整齐而是在新数据标准化与旧数据真实性之间建立可解释边界。“寻迹校园”让新建记录只选择当前权威分类和地点编辑旧记录时把非标准历史值临时追加为可保留选项筛选坚持明确的精确/片段语义不做未经确认的模糊映射自动化则守住 value 唯一与字段完整性。当产品进入跨校或云端阶段应升级为稳定 ID、版本合同和显式迁移而不是继续扩大硬编码数组。系列导航第 20 篇 / 共 50 篇。上一篇《今天/近 3 天/近 7 天的自然日边界》下一篇《可解释匹配评分模型》。