用 AI 规则库沉淀遗留 APP 兼容经验：一次 WalkBy 抄表 APP 迁移实践

1. 背景：迁移不是重写，兼容才是难点

在一次 WalkBy 抄表 APP 迁移中，我们需要把一套运行多年的移动端抄表能力接入新的后端平台。

从技术上看，这件事很容易被误解成"把旧接口改成新平台的 REST API"。但真正落地时，核心目标并不是重写 APP，而是让旧 APP 尽量不改页面、不改本地数据库、不改任务下载结构、不改上传结构，只调整服务地址后继续使用。

这类迁移的难点在于：新平台有自己的统一响应格式、命名规范和数据模型，而旧 APP 已经依赖了一套历史接口契约。后端如果按新平台习惯"顺手优化"，APP 反而会立刻出问题。

典型风险包括：

风险点	具体表现	影响
返回体格式变化	旧 APP 直接读取根字段，新平台习惯统一包装响应	登录、任务下载解析失败
JSON 字符串被改成对象	旧 APP 对部分字段二次解析，新接口直接返回数组或对象	本地数据入库失败
历史字段被重命名	后端认为字段名不规范，改成新模型字段	上传回写、任务记录定位异常
Long ID 精度问题	后端直接返回数字型大 ID，移动端 JS 存在精度风险	任务、记录、设备定位错误
上传结构被"规范化"	旧 APP 上传的是嵌套数组，新平台改成标准 DTO	APP 上传失败或数据丢失

所以，这类迁移不是"把接口写得更漂亮"，而是先把旧 APP 的兼容契约识别出来，并把它保护起来。

2. 问题：兼容规则太细，靠口口相传不可靠

项目推进过程中，我们发现很多兼容规则并不复杂，但非常容易被忽略。

例如：

旧 APP 的某些接口返回字段必须放在 JSON 根节点，不能被统一响应对象包起来。
某些字段虽然看起来像数组，但历史上实际返回的是 JSON 字符串，APP 会再次 JSON.parse。
某些 ID 在后端是 Long/BIGINT，但给 APP 时必须转成字符串。
某些字段名已经和旧 APP 本地数据库绑定，不能因为新平台语义更清晰就改名。
上传时必须保留"点位数组 + 明细数组"的结构，不能随意拍平成新平台的标准请求体。

这些规则如果只写在迁移评审文档里，后续开发、修复缺陷或新人接手时仍然容易遗漏。尤其是使用 AI 辅助开发时，通用模型往往会倾向于生成"更标准"的 REST 风格代码，但这恰好可能破坏旧 APP 的兼容性。

因此，我们做了一个小的工程化动作：把这些兼容规则沉淀成一个 AI 可读取、可复用、可检查的规则库。

3. 做法：把迁移经验整理成 AI 规则库

这个规则库可以理解为一个面向特定业务模块的 AI Skill。它不是简单的提示词，而是把"适用范围、不可变规则、接口契约、数据落库关系、代码检查清单"拆成结构化文档。

整体结构可以抽象为：

text 复制代码

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 大概怎么写：

md 复制代码

# 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 规则库的投入并不大，但能显著降低交接、联调和维护成本。它适合作为团队级工程资产持续积累，而不是停留在一次性的项目文档里。