1. 背景迁移不是重写兼容才是难点在一次 WalkBy 抄表 APP 迁移中我们需要把一套运行多年的移动端抄表能力接入新的后端平台。从技术上看这件事很容易被误解成“把旧接口改成新平台的 REST API”。但真正落地时核心目标并不是重写 APP而是让旧 APP 尽量不改页面、不改本地数据库、不改任务下载结构、不改上传结构只调整服务地址后继续使用。这类迁移的难点在于新平台有自己的统一响应格式、命名规范和数据模型而旧 APP 已经依赖了一套历史接口契约。后端如果按新平台习惯“顺手优化”APP 反而会立刻出问题。典型风险包括风险点具体表现影响返回体格式变化旧 APP 直接读取根字段新平台习惯统一包装响应登录、任务下载解析失败JSON 字符串被改成对象旧 APP 对部分字段二次解析新接口直接返回数组或对象本地数据入库失败历史字段被重命名后端认为字段名不规范改成新模型字段上传回写、任务记录定位异常Long ID 精度问题后端直接返回数字型大 ID移动端 JS 存在精度风险任务、记录、设备定位错误上传结构被“规范化”旧 APP 上传的是嵌套数组新平台改成标准 DTOAPP 上传失败或数据丢失所以这类迁移不是“把接口写得更漂亮”而是先把旧 APP 的兼容契约识别出来并把它保护起来。2. 问题兼容规则太细靠口口相传不可靠项目推进过程中我们发现很多兼容规则并不复杂但非常容易被忽略。例如旧 APP 的某些接口返回字段必须放在 JSON 根节点不能被统一响应对象包起来。某些字段虽然看起来像数组但历史上实际返回的是 JSON 字符串APP 会再次JSON.parse。某些 ID 在后端是 Long/BIGINT但给 APP 时必须转成字符串。某些字段名已经和旧 APP 本地数据库绑定不能因为新平台语义更清晰就改名。上传时必须保留“点位数组 明细数组”的结构不能随意拍平成新平台的标准请求体。这些规则如果只写在迁移评审文档里后续开发、修复缺陷或新人接手时仍然容易遗漏。尤其是使用 AI 辅助开发时通用模型往往会倾向于生成“更标准”的 REST 风格代码但这恰好可能破坏旧 APP 的兼容性。因此我们做了一个小的工程化动作把这些兼容规则沉淀成一个 AI 可读取、可复用、可检查的规则库。3. 做法把迁移经验整理成 AI 规则库这个规则库可以理解为一个面向特定业务模块的 AI Skill。它不是简单的提示词而是把“适用范围、不可变规则、接口契约、数据落库关系、代码检查清单”拆成结构化文档。整体结构可以抽象为ai-skill/ SKILL.md references/ app-interface-contract.md business-storage-rules.md agents/ openai.yaml各文件职责如下文件作用SKILL.md描述这个规则库适用于哪些 APP 兼容接口哪些行为必须保留开发时按什么步骤检查app-interface-contract.md记录旧 APP 的接口契约路由类型、请求参数、响应字段、状态码、上传结构business-storage-rules.md记录任务、抄表记录、设备数据、冻结数据、告警诊断等业务落库关系openai.yaml提供工具展示名称、简短说明和默认调用提示规则库的目标很明确当开发者或 AI 修改 APP 相关接口时必须先知道这里不是普通的新平台接口而是旧 APP 兼容接口。4. 兼容规则应该写到什么程度我的经验是不要只写抽象原则要写到“足够阻止误改”的程度。例如规则库中会明确写出这些红线保留旧 APP 的接口风格不强行改成新平台 REST 风格。保留旧请求参数名除非 APP 同步改造。APP 响应字段直接放在根节点不套统一响应包装。某些列表字段保持 JSON 字符串不改成对象或数组。旧状态码保持原语义不重新定义成功、失败、禁用等状态。移动端可见的大整数 ID 统一按字符串处理。旧字段名即使不符合新平台命名习惯也不能随意重命名。上传结构保持兼容先更新抄表任务记录再写入平台设备数据、冻结数据或告警数据。这些规则看起来细但它们正是联调时最容易踩坑的地方。5. 让 AI 参与代码修改时规则库能解决什么问题没有领域规则时AI 很可能会做出“看起来更合理”的改动比如把旧接口统一包装成{ code, message, data }。把 JSON 字符串字段改成数组对象。把历史字段名改成更符合新平台语义的字段名。把 Long ID 直接作为数字返回。把上传结构改造成标准 DTO。这些改动从普通后端开发视角看并不一定错但在兼容迁移场景下就是破坏性变更。有了规则库之后AI 在处理代码前会先加载该模块的兼容约束生成代码时就会主动避开这些问题。更重要的是它还能在代码评审时按清单检查路由和 HTTP 方法有没有变化请求参数名有没有变化响应体有没有被平台统一包装JSON 字符串字段有没有被改成对象APP 可见 ID 是否仍然是字符串上传结构是否仍然兼容旧 APP任务记录、实时数据、冻结数据、告警数据的写入顺序是否符合业务规则这相当于把个人经验变成了可重复执行的检查规则。6. 一个简化后的规则示例下面是脱敏后的规则片段展示这种 AI Skill 大概怎么写# Legacy WalkBy APP Compatibility Use this skill when changing or reviewing APP-facing APIs for the legacy WalkBy APP. The goal is to keep the existing APP contract stable while migrating backend services to the new platform. ## Non-Negotiable Rules - Preserve legacy APP routes and request parameter names. - Do not wrap APP responses in the platform unified response object. - Keep legacy JSON-string fields as strings; do not change them to arrays or objects. - Return APP-visible Long/BIGINT IDs as strings. - Preserve legacy field names even if the new platform has cleaner names. - Keep upload payload shape compatible with the existing APP. - Update the reading task record first, then write platform device data. ## Review Checklist - Route and HTTP method are unchanged. - Request parameter names are unchanged. - Response body is not platform-wrapped. - JSON-string fields remain strings. - IDs visible to APP are strings. - Upload accepts the legacy nested payload. - Data writes preserve task record, realtime, freeze and alarm relationships.实际项目中的规则会更细但公开文章里不建议暴露真实接口名、真实字段全集、真实表名和内部路径。7. 带来的收益这件事的价值不在于“写了一个文档”而在于把一次迁移项目中的隐性经验变成了团队可复用资产。具体收益包括维度收益新人上手不需要翻大量评审稿和历史文档先读规则库就能知道兼容红线联调质量提前阻止统一响应包装、字段改名、JSON 字符串变对象等高频问题AI 辅助质量让 AI 不再只按通用 REST 习惯生成代码而是遵守业务上下文代码评审评审可以基于清单而不是依赖个人记忆知识沉淀把项目经验从个人脑子里沉淀为工程资产尤其是在遗留系统迁移中很多“不能改”的规则比“怎么重构”更重要。AI 规则库的价值就是把这些不能改的边界明确下来。8. 适合推广到哪些场景这种方法不只适用于 WalkBy 抄表 APP。只要项目具备以下特征都可以考虑沉淀成 AI 规则库遗留系统迁移需要兼容旧接口。移动端或第三方系统不方便同步改造。业务字段语义复杂不能只看新平台模型。接口契约、数据映射、落库顺序分散在多份文档中。多人协作维护容易出现实现风格不一致。希望用 AI 辅助开发但担心 AI 按通用模式误改业务契约。沉淀步骤可以简化为四步梳理接口契约哪些路由、参数、返回字段不能变。梳理业务规则哪些字段有历史语义哪些数据有写入顺序。梳理常见错误过去联调踩过哪些坑。写成 AI 可读取的规则文件让开发和评审都能复用。9. 总结遗留 APP 迁移中最危险的不是代码写不出来而是“自以为优化”的改动破坏了旧端兼容。AI 辅助开发不能只依赖通用模型能力还需要把项目中的接口契约、业务边界和历史包袱整理成可执行的规则上下文。当这些规则沉淀下来后AI 才能从“会写代码”进一步变成“懂这个模块不能怎么改”。对于复杂迁移项目来说这种 AI 规则库的投入并不大但能显著降低交接、联调和维护成本。它适合作为团队级工程资产持续积累而不是停留在一次性的项目文档里。