改表单字段前，让 Codex 从 UI 到数据库追完整数据流

教程定位

这篇教程解决什么问题

前端工程师改表单字段，最容易低估的不是页面本身，而是字段离开页面之后发生了什么。一个看起来很小的需求，例如“把联系人备注改成客户偏好说明”“新增一个可选的跟进时间”“把收货地址里的楼层字段拆出来”，往往不只是改一个 input、一个 label、一个校验规则。字段可能先被表单库收集，再经过前端 schema 校验、默认值补齐、命名转换、请求体拼装、API client 封装、后端 DTO 校验、service 层清洗、ORM mapping，最后才落到数据库字段或事件表里。任何一层漏改，都可能出现“页面显示正常但接口没收到”“接口收到但被后端丢掉”“数据库写入了旧字段”“编辑页回显失败”“列表页还在读旧字段”这些问题。

这篇文章讲一个很窄但很实用的 Codex 用法：从一个表单字段出发，让 Codex 顺着 UI、表单状态、校验、请求体、接口定义、服务端 DTO、业务转换和数据库 schema 建立字段流转链路。它不是让 Codex 直接替你改提交逻辑，而是先让它做一张可复核的“字段流转表”和一份“修改点列表”。你可以拿这两份产物判断这次字段改动到底涉及哪些文件，哪些地方需要同步改，哪些地方只需要确认，哪些边界需要补测试。

本文的读者是要修改提交逻辑的前端工程师。你可能熟悉页面组件，却不一定熟悉后端 DTO、数据库迁移和接口生成代码；你可能能快速找到 `CustomerForm.tsx`，但不知道 `preferredContactNote` 在提交时被改名成了 `contact_note`，服务端又映射成 `customer_preference_note`。这时候让 Codex 只看前端组件是不够的。它应该沿字段名、label 文案、schema 名称、接口路径、请求体字段、DTO 属性、数据库列名和测试用例一起搜索，把“字段经过哪里”说清楚。

这里的关键原则是：先追链路，再改代码。不要上来就说“帮我把字段 A 改成字段 B”。如果字段被多个层级转换，Codex 很可能只改最显眼的一层。更稳的做法是让它第一轮只读：列出字段从 UI 到存储的全部候选位置，标出每一层的证据、转换规则、是否需要修改、人工待确认点。等你确认链路后，再让它按清单逐项修改。这样做看起来多一步，但能显著降低提交逻辑改漏、回显不一致、接口字段错配和历史数据兼容问题。

本文会用一个安全虚构的客户跟进表单举例：页面里有一个“跟进偏好”字段，前端字段名叫 `followUpPreference`，产品希望拆成 `preferredChannel` 和 `preferredTimeWindow`。我们不会使用真实邮箱、手机号、客户名、密钥或公司内部数据。你可以把这个方法迁移到报名表、审批表、线索表、订单补充信息、用户资料表和后台配置表单中。

使用场景

什么情况下最适合用这一套

你负责一个 CRM 类后台里的“新建客户跟进记录”表单。产品提了一个需求：原来表单里只有一个文本框“跟进偏好”，现在希望拆成两个字段，一个是“偏好渠道”，可选值包括站内消息、电话、邮件；另一个是“方便联系时间”，允许填写简短文本。用户提交后，这两个字段要在详情页展示，也要进入后端保存，后续还会被运营导出。

你打开页面，很快找到 `LeadFollowUpForm.tsx`。表单里确实有 `followUpPreference`。如果只从前端视角看，这个需求似乎很简单：删掉一个输入框，新增一个 select 和一个 input，提交时把字段放进 payload。问题是，这个字段已经在多个地方被使用：

如果你只改表单组件，可能前端显示没问题，后端却不接受新字段。如果你只改请求类型，详情页回显可能还在读旧字段。如果你直接删数据库旧列，导出任务可能失败。如果你保留旧字段但没做映射，历史数据可能在编辑页消失。字段改动的风险来自“链路不完整”，不是来自 input 本身。

Codex 在这个场景里适合做三件事：

第一，帮你从已知字段名出发，找到它在代码里的所有形态。包括 `followUpPreference`、`follow_up_preference`、`FollowUpPreference`、表单 label “跟进偏好”、翻译 key、API 类型和数据库列名。

第二，帮你按层级整理证据。它应该告诉你：UI 在哪里，表单状态在哪里，校验在哪里，请求体在哪里，接口定义在哪里，后端 DTO 在哪里，数据库列在哪里，测试在哪里，导出或详情回显在哪里。

第三，帮你把“应该修改”和“只需要确认”分开。比如表单组件和请求类型需要改，详情页回显需要改，数据库是否新增列要看后端方案，导出任务是否本期改要看产品要求，历史旧字段是否迁移要人工决定。

你要避免让 Codex 做两件事。不要让它在没有链路表的情况下直接批量替换字段名；也不要让它替你决定数据兼容策略。字段拆分、字段合并、枚举值变更、必填变可选、可选变必填、历史数据迁移，这些都需要人确认业务口径。Codex 可以把证据找齐，但不能替团队决定旧数据怎么解释。

1. 表单初始化时从详情接口的 `follow_up_preference` 回填。
2. 前端校验 schema 要求这个字段最多 120 个字符。
3. 提交函数会把 camelCase 转成 snake_case。
4. API client 里有一个 `CreateFollowUpRequest` 类型。
5. 后端 DTO 里有 `followUpPreference?: string`。
6. service 层会 trim 空白，并在字段为空时写入默认值。
7. 数据库列名是 `follow_up_preference`。
8. 导出任务读取同一个字段生成 CSV。
9. 测试里有一条断言，提交后请求体包含 `follow_up_preference`。

材料准备

开始前先把材料和边界备齐

开始前，先把输入材料整理成一个小的“字段调查卡”。字段链路追踪不需要你一开始就知道全部答案，但至少要给 Codex 足够稳定的起点。最少准备五类材料。

第一类是表单截图或截图转写。截图本身如果包含真实客户信息，不要直接上传或粘贴。你可以用文字描述：页面名称、字段 label、字段所在区域、提交按钮文案、错误提示、是否编辑态回显。比如：“新建跟进记录页，字段 label 是跟进偏好，输入框 placeholder 是填写客户希望的联系渠道或时间，提交按钮是保存跟进。”

第二类是字段名。至少提供你已经看到的前端字段名。如果你知道接口字段名或数据库字段名，也一起给。字段名可能有多种形态，最好写成列表：`followUpPreference`、`follow_up_preference`、`跟进偏好`。如果你只知道 label，也可以让 Codex 先从文案反查字段。

第三类是相关组件和接口定义。你可以提供候选路径，例如 `apps/web/src/features/leads/LeadFollowUpForm.tsx`、`packages/api-client/src/leads.ts`、`services/api/src/modules/leads`。如果不确定路径，就给项目根目录和业务模块名称，让 Codex 先只读搜索。

第四类是数据库 schema 或迁移线索。字段最终是否存储，要看数据库列、ORM model、迁移脚本或 schema 文件。给 Codex 的材料可以是 `schema.prisma`、`db/migrations`、`typeorm entity`、`drizzle schema`、`sql` 文件路径。不要贴真实连接串、生产库地址或数据库密码。

第五类是现有测试和接口样例。包括单元测试、集成测试、Playwright 测试、OpenAPI 文档、请求响应示例。测试里常常能看到字段的真实请求体和回显格式，比页面代码更接近提交行为。

建议把材料写成下面这种格式。它不包含真实隐私，但保留了足够结构：

准备时还有几个安全边界要写清楚。不要把真实用户邮箱、手机号、身份证件、客户名称、合同编号、订单号、访问 token、cookie、数据库连接串贴进去。请求样例可以用 `user_demo_001`、`lead_demo_001`、`followup_demo_001`。如果涉及生产日志，只保留字段结构、接口路径和脱敏 request id。

同时要告诉 Codex 本轮产物是什么。不要只说“帮我看看这个字段”。更好的目标是：“输出字段流转表、字段形态映射、修改点列表、待人工确认点，不修改代码。”目标越明确，Codex 越不容易跳到修复阶段。

目标：
先不要改代码。请从字段 followUpPreference 出发，追踪它从表单 UI 到数据库存储的完整链路，并输出字段流转表和修改点列表。

业务变化：
旧字段：跟进偏好 followUpPreference，一个文本框。
新字段：preferredChannel，一个枚举选择；preferredTimeWindow，一个短文本。

已知页面：
新建客户跟进记录页，组件可能是 apps/web/src/features/leads/LeadFollowUpForm.tsx。

已知接口：
POST /api/leads/:leadId/follow-ups
GET /api/leads/:leadId/follow-ups/:followUpId

已知字段形态：
followUpPreference
follow_up_preference
跟进偏好

可能相关目录：
apps/web/src/features/leads
packages/api-client/src
services/api/src/modules/leads
db/schema.sql
tests/leads

边界：
只读搜索，不修改代码，不写入数据库，不运行会改变外部状态的命令。

实操流程

按这套步骤把工作跑起来

第一步，让 Codex 确认字段的全部形态。

表单字段不会只以一种名字存在。前端表单状态常用 camelCase，接口可能用 snake_case，后端 DTO 可能又变回 camelCase，数据库列可能带前缀，翻译文件可能只出现中文 label。你要让 Codex 先列搜索计划：围绕 `followUpPreference`、`follow_up_preference`、`跟进偏好`、`preference`、`preferred`、接口路径和组件名搜索。第一轮输出不要直接下结论，只要列出命中的文件、字段形态和证据片段。

这一步的好输出长这样：

| 字段形态 | 可能层级 | 证据位置 | 说明 | | --- | --- | --- | --- | | `followUpPreference` | 前端表单状态、后端 DTO | `LeadFollowUpForm.tsx`、`CreateFollowUpDto.ts` | 表单字段和 DTO 属性同名 | | `follow_up_preference` | 请求体、数据库 | `leadsApi.ts`、`schema.sql` | 请求字段和数据库列名 | | `跟进偏好` | UI 文案 | `leadFollowUp.zh-CN.ts` | label 和错误提示 |

如果 Codex 只找到前端字段，不要急着改。你应该要求它继续从接口路径、请求类型、DTO 和 schema 方向搜索，因为没有命中不等于不存在，可能只是名字发生了转换。

第二步，从 UI 组件追到表单状态和校验。

让 Codex 打开候选组件，找字段在哪里渲染、默认值在哪里设置、表单库如何注册字段、校验 schema 在哪里、提交函数拿到的值是什么。它要特别关注这些信号：`defaultValues`、`initialValues`、`register`、`Controller`、`name`、`zod`、`yup`、`rules`、`resolver`、`onSubmit`、`handleSubmit`、`setValue`、`watch`。

字段拆分时，这一层通常需要改四类内容：UI 控件、默认值、校验规则、提交前的数据组装。比如旧字段是一个文本框，新字段一个枚举一个短文本，那么校验要从“最多 120 字符”变成“渠道只能是允许枚举，时间说明最多 80 字符”。如果编辑页复用同一个组件，还要检查旧数据如何回显到新字段。

第三步，从提交函数追到请求体。

表单提交函数往往不是直接调用 `fetch`。它可能先执行 `normalizeFormValues`，再调用 `leadApi.createFollowUp`，再由 API client 把字段转成 snake_case。让 Codex 沿着 `onSubmit` 或 mutation 函数继续追踪，回答三个问题：

这里要特别小心“空值过滤”。很多项目会有 `removeEmptyFields(payload)`，它会把空字符串、`null` 或 `undefined` 删除。一个新字段如果默认值设置不对，可能在页面上存在，但提交时被过滤掉。还有一些项目会有 `camelToSnake` 自动转换，这时你不应该手写两个字段名的转换，而应该确认转换工具是否覆盖新字段。

第四步，从 API client 追到接口类型或 OpenAPI 定义。

前端请求体通过 API client 后，通常会进入类型定义、OpenAPI 生成代码或共享 SDK。让 Codex 找 `CreateFollowUpRequest`、`LeadFollowUpPayload`、`POST /follow-ups`、`operationId`、`paths`、`requestBody`。这一步的目标是确认前端编译期类型和接口契约是否允许新字段。

如果 API 类型来自后端生成，不要让 Codex 直接手改生成文件。它应该标记为“生成文件，源头可能在 OpenAPI schema 或后端 DTO”。修改点列表里要写清楚：改源 schema 后重新生成，还是本仓库手写类型。很多字段改动出问题，正是因为有人改了生成产物，下次生成又被覆盖。

第五步，从接口定义追到后端 DTO 和校验。

服务端可能用 DTO 接收请求，也可能用 request schema、validator、controller 参数装饰器。让 Codex 沿接口路径找到 handler/controller，再找 request DTO。重点检查字段是否会被白名单过滤。例如一些后端框架启用了 `whitelist: true`，DTO 没声明的新字段会被直接丢掉。前端请求体里有 `preferred_channel`，后端 DTO 没有对应属性，最终 service 层就永远拿不到。

这一层要输出这些信息：请求字段名、DTO 属性名、是否必填、类型、枚举限制、默认值、错误提示、是否允许未知字段。如果新字段是枚举，必须找枚举定义和反序列化逻辑。如果旧字段要保留兼容，也要标记 DTO 是否同时接收旧字段和新字段。

第六步，从 service 层追到数据库字段。

DTO 之后通常还有 service 层转换。字段可能在这里被 trim、拼接、映射到 ORM model，或者写入 JSON column。让 Codex 搜索 DTO 属性在 service、repository、mapper、entity、model、migration、schema 中的使用。它要回答：最终落到哪个数据库列，字段是否被改名，是否有默认值，是否进入审计日志、事件表、搜索索引或导出表。

如果数据库只存一个旧列 `follow_up_preference`，新需求要拆成两个字段，就有几种方案：新增两列、存 JSON、继续拼接成旧字段、服务端兼容旧列同时读写新列。Codex 可以列出代码现状和方案影响，但不能替你决定迁移策略。修改点列表要把“需要产品或后端确认”的项标出来。

第七步，反向追详情页、编辑页和导出读取。

提交链路只覆盖“写入”。字段改动还会影响“读取”。让 Codex 从数据库列、接口响应 DTO 或详情接口字段反向搜索，找到详情页、编辑页、列表页、导出任务、打印模板、通知模板等读取方。尤其是编辑页，如果它从旧字段回填表单，新字段可能显示为空；导出任务如果仍读取旧字段，运营看到的列就不会变。

这一轮可以按“必须同步改、可能受影响、只需确认”三类输出。比如详情页展示和编辑页回显通常必须改；导出任务要看本次需求是否包含；历史通知模板可能只需确认。

第八步，让 Codex 生成字段流转表。

字段流转表不要写成散文。它最好有固定列：层级、文件位置、字段名、转换动作、证据、修改建议、人工检查点。这样你可以逐行审查。示例结构如下：

| 层级 | 文件位置 | 当前字段 | 转换动作 | 修改建议 | 人工检查点 | | --- | --- | --- | --- | --- | --- | | UI 控件 | `LeadFollowUpForm.tsx` | `followUpPreference` | 用户输入文本 | 拆成 `preferredChannel` 和 `preferredTimeWindow` | 枚举选项是否与产品一致 | | 表单校验 | `followUpSchema.ts` | `followUpPreference` | 最多 120 字符 | 新增渠道枚举和时间文本长度 | 空值和必填规则 | | 请求体 | `leadsApi.ts` | `follow_up_preference` | camelCase 转 snake_case | 确认新字段请求名 | 是否保留旧字段兼容 | | 后端 DTO | `CreateFollowUpDto.ts` | `followUpPreference` | DTO 白名单接收 | 新增两个属性或兼容旧字段 | DTO 未声明字段会不会被过滤 | | 数据库存储 | `schema.sql` | `follow_up_preference` | 写入文本列 | 后端确认新增列或兼容策略 | 历史数据迁移 |

第九步，让 Codex 生成修改点列表。

修改点列表要比字段流转表更行动化。建议分成：

最后一步，再进入实际修改。实际修改时仍然要求 Codex 按清单逐项改，不要让它在全仓库里做模糊替换。每改完一层，就运行对应检查：类型检查、单元测试、接口测试、表单交互测试，至少确认请求体和回显都符合预期。

1. 提交时读取的是哪个表单值对象？
2. 字段是否在提交前被 trim、过滤空字符串、合并、重命名或删除？
3. 最终发给接口的请求体字段是什么？

• 必改：不改就会导致提交失败、字段丢失或页面错误。
• 待确认后改：涉及数据库迁移、历史数据、导出范围、接口兼容。
• 可后续：不影响本次提交链路，但可能影响体验或文档。
• 不建议改：生成文件、历史迁移、测试 fixture 源数据等不该直接手动改的地方。

输入示例

可以直接参考的输入材料

下面是一段可以直接交给 Codex 的输入样例。它使用虚构项目和脱敏数据，适合复制后替换成你自己的字段、路径和接口。

如果你已经有表单截图，也可以把截图转写成文字补进去：

如果你有接口样例，也要脱敏后给出：

这些输入的价值在于给 Codex 多个锚点。它可以从组件名搜，也可以从字段名搜，还可以从接口路径、错误提示、数据库列名反向搜。字段链路越多锚点，越不容易漏掉转换层。

你先不要改代码，只做只读追踪。

背景：
我要修改“新建客户跟进记录”表单。旧字段是“跟进偏好”，前端字段名 followUpPreference。产品希望拆成两个字段：
1. preferredChannel：偏好渠道，枚举值 in_app_message / phone_call / email_message。
2. preferredTimeWindow：方便联系时间，短文本，不超过 80 字。

用户场景：
用户在 CRM 后台创建跟进记录，提交后详情页要展示这两个字段。编辑旧记录时，如果只有旧字段 followUpPreference，需要标出兼容风险，不要擅自决定迁移方案。

已知线索：
- 页面组件可能是 apps/web/src/features/leads/LeadFollowUpForm.tsx
- API client 可能是 packages/api-client/src/leads.ts
- 接口：POST /api/leads/:leadId/follow-ups
- 详情接口：GET /api/leads/:leadId/follow-ups/:followUpId
- 旧字段可能有这些形态：followUpPreference、follow_up_preference、跟进偏好
- 后端目录可能是 services/api/src/modules/leads
- 数据库 schema 可能在 db/schema.sql 或 services/api/prisma/schema.prisma

请输出：
1. 字段形态映射。
2. 从 UI 到数据库的字段流转表。
3. 必改、待确认后改、可后续、不建议直接改的修改点列表。
4. 需要人工确认的问题。

限制：
只读搜索，不修改文件，不运行会改变外部系统的命令。不要使用真实邮箱、手机号、客户名或密钥。

截图转写：
页面标题：新增跟进记录。
字段区域：客户状态、跟进方式、跟进偏好、备注。
跟进偏好 placeholder：例如“希望下午通过站内消息联系”。
提交按钮：保存跟进。
错误提示：跟进偏好不能超过 120 个字符。

{
  "method": "POST",
  "path": "/api/leads/lead_demo_001/follow-ups",
  "body": {
    "content": "已完成首次沟通",
    "follow_up_preference": "下午用站内消息联系",
    "next_action_date": "2026-08-15"
  }
}

提示词

可复制使用的提示词

下面这段提示词可以直接复制给 Codex。使用时把方括号里的内容换成你的真实项目线索，但不要填入真实隐私或密钥。

如果你已经确认要进入修改阶段，可以在链路表通过人工检查后，再追加第二段提示词：

这两段提示词不要混在一起用。第一段是调查，第二段是实施。把调查和实施分开，是减少字段改漏的核心动作。

你是代码库里的字段链路调查助手。请先不要改代码，只做只读追踪。

我要修改一个表单字段，担心它在 UI、表单校验、请求体、后端 DTO 和数据库之间被多次转换，直接改容易漏。

业务变化：
- 旧字段：[旧字段中文名]，[旧前端字段名]，[旧接口字段名或未知]
- 新字段：[新字段 1]，[新字段 2]，[字段类型和是否必填]

已知材料：
- 表单页面或组件：[路径或页面描述]
- 相关接口：[method + path]
- 已知字段形态：[camelCase / snake_case / 中文 label / enum]
- 可能相关目录：[前端目录]、[API client 目录]、[后端目录]、[数据库 schema 目录]、[测试目录]
- 截图转写：[字段 label、placeholder、错误提示、提交按钮文案]

请按下面步骤执行：
1. 先列出你会搜索的字段形态和关键词，不要跳到结论。
2. 只读搜索并整理命中文件，按 UI、表单状态、校验、提交函数、API client、接口契约、后端 DTO、service/mapper、数据库 schema、读取方、测试 这些层级归类。
3. 输出字段形态映射表：字段形态、出现层级、证据位置、说明。
4. 输出字段流转表：层级、文件位置、当前字段名、转换动作、是否需要修改、修改建议、人工检查点。
5. 输出修改点列表，分成必改、待确认后改、可后续、不建议直接改。
6. 标出你没有证据确认的地方，不要用猜测填满。

限制：
- 本轮不要修改文件。
- 不要运行会写入数据库、调用外部服务或改变远程状态的命令。
- 不要把生成文件当成源头，遇到 OpenAPI 或 SDK 生成文件要继续找源 schema。
- 涉及历史数据迁移、接口兼容、字段是否必填时，只列待确认问题，不替业务拍板。

现在可以按刚才确认过的修改点列表改代码。请只修改“必改”和我明确确认的项目。每改完一层，说明对应的文件和原因。不要做全局模糊替换，不要修改生成文件源头不明的内容。完成后运行与本次字段相关的类型检查和测试；如果测试不可运行，请说明原因。

输出样例

AI 应该输出到什么程度

下面是一份理想输出的缩短样例。真实项目里会更长，但结构应该类似。

这份输出的重点不是“答案看起来完整”，而是每一行都有证据位置和人工检查点。你拿到后应该能逐行问：这个文件真的存在吗？这个转换真的发生吗？这个修改是否属于本次需求？没有证据的地方有没有被标出来？如果 Codex 输出了一堆没有路径的解释，就让它重做。

字段形态映射

| 字段形态 | 出现层级 | 证据位置 | 说明 |
| --- | --- | --- | --- |
| followUpPreference | 表单状态、前端类型、后端 DTO | apps/web/.../LeadFollowUpForm.tsx；services/api/.../CreateFollowUpDto.ts | 旧字段的 camelCase 形态 |
| follow_up_preference | 请求体、数据库列、接口测试 | packages/api-client/src/leads.ts；db/schema.sql；tests/leads/create-follow-up.test.ts | 旧字段的 snake_case 形态 |
| 跟进偏好 | UI label、错误提示 | apps/web/src/i18n/leads.zh-CN.ts | 展示文案 |

字段流转表

| 层级 | 文件位置 | 当前字段名 | 转换动作 | 是否需要修改 | 修改建议 | 人工检查点 |
| --- | --- | --- | --- | --- | --- | --- |
| UI 控件 | LeadFollowUpForm.tsx | followUpPreference | 文本输入 | 是 | 拆成 preferredChannel select 和 preferredTimeWindow input | 渠道枚举文案需产品确认 |
| 表单校验 | followUpSchema.ts | followUpPreference | string().max(120) | 是 | 新增 channel enum 和 timeWindow max(80) | 两个字段是否必填需确认 |
| 提交函数 | useCreateFollowUp.ts | followUpPreference | trim 后传给 API client | 是 | 改为传两个新字段，避免空字符串被误删 | 空值策略需确认 |
| API client | leads.ts | follow_up_preference | camelToSnake 后进入请求体 | 是 | 确认请求字段为 preferred_channel 和 preferred_time_window | 是否保留旧字段兼容 |
| 后端 DTO | CreateFollowUpDto.ts | followUpPreference | DTO 白名单接收 | 是 | 新增 preferredChannel、preferredTimeWindow，或兼容旧字段 | 未声明字段会被过滤 |
| Service/Mapper | follow-up.service.ts | followUpPreference | trim 并写入 model | 是 | 映射到新存储字段 | 旧记录读取策略 |
| 数据库 | schema.sql | follow_up_preference | text column | 待确认 | 需要后端决定新增列、JSON 或兼容旧列 | 是否迁移历史数据 |
| 详情回显 | FollowUpDetail.tsx | followUpPreference | 读取详情响应展示 | 是 | 展示两个新字段，旧字段只做兼容提示 | 旧记录展示口径 |
| 导出任务 | export-follow-ups.ts | follow_up_preference | 导出 CSV 列 | 待确认 | 产品确认本次是否改导出列 | 运营是否依赖旧列名 |
| 测试 | create-follow-up.test.ts | follow_up_preference | 断言请求体和保存结果 | 是 | 更新提交、DTO、回显测试 | 增加旧数据兼容测试 |

修改点列表

必改：
- 表单 UI、默认值和校验 schema。
- 提交函数和 API request 类型。
- 后端 DTO 或接口 schema，否则新字段可能被白名单过滤。
- 详情页和编辑页回显。
- 与提交和回显相关的测试。

待确认后改：
- 数据库新增字段还是复用旧字段。
- 历史 follow_up_preference 如何拆分或展示。
- 导出 CSV 是否本期同步改列。
- preferredChannel 是否必填，preferredTimeWindow 是否允许为空。

可后续：
- 帮助文案和空状态提示。
- 旧字段清理计划。
- 运营报表字段命名统一。

不建议直接改：
- OpenAPI 生成后的 SDK 文件，除非确认生成源头。
- 历史迁移文件。
- 与本字段无关的全局 camelToSnake 工具。

人工验收

人要怎么检查和改到可用

拿到字段流转表后，不要马上照单全改。先做人工检查，把每一行分成“确认成立”“需要补证据”“与本次无关”。这个步骤很重要，因为 Codex 搜索出来的是线索，不是最终事实。

第一，检查路径和字段是否真实存在。打开表里列出的关键文件，确认字段名、接口路径、DTO 属性、数据库列确实存在。尤其要小心同名字段出现在测试 fixture、旧页面、废弃模块或 demo 代码里。不要因为 Codex 找到 `follow_up_preference` 就默认它是当前生产链路。

第二，检查链路方向是否正确。字段从表单到数据库是写入链路，字段从数据库到详情页是读取链路。两条链路可能共用 DTO，也可能完全分开。修改提交逻辑时，写入链路必查；如果需求涉及编辑回显和详情展示，读取链路也必查。不要把“搜索到读取方”误当成“提交方已经修改完”。

第三，检查命名转换是否自动发生。很多前端项目会在请求层统一做 camelCase 和 snake_case 转换。如果工具是递归转换，新字段可能不需要手动写 snake_case；如果工具只转换一层，嵌套对象里的字段可能会漏。人工要看转换函数的实现或测试，而不是只看调用名。

第四，检查后端是否会丢弃未知字段。使用 DTO 白名单、schema validator、OpenAPI request parser 的后端，未声明字段通常不会进入 service 层。你可以让 Codex 找配置，例如 `whitelist`、`stripUnknown`、`additionalProperties: false`。如果存在这些配置，新字段必须进入接口契约，否则前端提交再多也没用。

第五，检查数据库策略是否已被确认。字段拆分不是纯前端问题。如果后端决定新增两列，需要迁移脚本、读写兼容和回滚策略。如果决定暂时仍存旧列，前端可能要把两个新字段合成旧文本。无论哪种方案，都要在修改点列表里写清楚“谁确认、确认了什么”。不要让 Codex 擅自新增迁移或删除旧列。

第六，检查测试覆盖。至少要有三类测试：表单提交请求体、后端接收和保存、详情或编辑回显。如果项目已有测试，就更新相关断言；如果没有测试，也要留一个手动验证清单：填写两个新字段、只填写渠道、只填写时间、编辑旧记录、提交空值、接口返回校验错误。

实际修改时，建议按层级小步走：

每一步都要看 diff。字段改动很容易产生大面积格式化或无关重构，这些会增加审查成本。你可以要求 Codex “只改字段链路表中确认的文件，不做顺手重构”。如果它改了无关文件，要让它解释原因；没有原因就不要保留。

1. 先改前端表单和校验，让本地类型检查暴露表单值类型问题。
2. 再改请求体和 API 类型，让提交函数的 payload 明确。
3. 再改后端 DTO 和 service 映射，确认接口能接收字段。
4. 再改读取和回显，确认详情页和编辑页一致。
5. 最后改测试、导出和文案。

失败反例

这些失败反例要提前避开

【反例一：只搜前端字段名，漏掉接口和数据库字段】

错误做法是只让 Codex 搜 `followUpPreference`，然后它只找到表单组件和前端类型，于是直接把这两个地方改成新字段。上线后发现后端仍然只接收 `follow_up_preference`，新字段被 DTO 白名单过滤，数据库没有任何变化。页面看起来提交成功，是因为接口没有把未知字段当成错误，但实际保存的仍是旧字段或空值。

正确做法是同时搜索 camelCase、snake_case、中文 label、接口路径、DTO 名称和数据库列。字段流转表里必须覆盖请求体、后端接收和存储层。只找到 UI 不能开始改提交逻辑。

【反例二：把生成文件当成源头，手改后又被覆盖】

有些项目的 `packages/api-client` 是从 OpenAPI 或后端 schema 生成的。Codex 看到 `CreateFollowUpRequest` 类型缺少新字段，直接手动修改生成文件。短期内类型检查过了，但下次运行生成命令，手动修改被覆盖，字段又消失。更糟的是，后端真实接口契约仍然没改，前端类型和服务端行为不一致。

正确做法是让 Codex 标记“疑似生成文件”，继续追源头：OpenAPI yaml、controller 装饰器、DTO schema 或生成脚本。修改点列表里要写“改生成源头并重新生成”，而不是直接改产物。

【反例三：只改写入，不改读取和编辑回显】

字段拆分后，新建记录可以提交，但详情页仍然读取旧字段 `followUpPreference`。用户新建后看到详情页空白，以为保存失败。编辑旧记录时更麻烦：旧字段里有“下午站内消息联系”，新表单的渠道和时间都没有值，用户保存一次后旧信息被覆盖为空。

正确做法是把读取链路也纳入追踪：详情接口响应、详情页展示、编辑页默认值、列表列、导出任务。对于旧数据，要明确兼容策略：只展示旧文本、尝试人工迁移、还是在编辑页提示需要重新选择。这个策略必须人工确认。

【反例四：让 Codex 做全局替换，误伤无关字段】

有些字段名很普通，例如 `preference`、`note`、`channel`。如果让 Codex 全局替换，很可能改到用户通知偏好、营销渠道、客服备注等无关模块。更隐蔽的是测试 fixture 或历史迁移被改掉，导致测试含义变化或迁移不可追溯。

正确做法是以字段流转表为边界，只改确认属于本次链路的文件。历史迁移、无关模块、生成产物、旧 fixture 是否修改都要单独说明。模糊替换不是字段重构，证据链才是。

【反例五：让 AI 决定历史数据迁移口径】

旧字段是自由文本，新字段是枚举加短文本。Codex 可能建议把包含“电话”的旧文本迁移成 `phone_call`，包含“邮件”的迁移成 `email_message`。这看起来聪明，但很危险，因为旧文本可能有歧义，也可能包含用户隐私或特殊约定。错误迁移会改变业务事实。

正确做法是让 Codex 只列迁移候选和风险，不自动决定。历史数据是否迁移、如何映射、是否保留原文、是否需要人工审核，必须由产品、后端和数据负责人确认。

主题边界

它和相邻主题的区别

这个主题和“让 Codex 找页面、路由和接口对应关系”相邻，但重点不同。页面入口追踪关注的是“这个页面由哪些路由、组件和接口组成”，适合排查页面报错或定位功能入口。本文关注的是“一个表单字段在提交后如何被转换和存储”，即使你已经知道页面和接口，也仍然需要追字段形态、校验、请求体、DTO、service mapping 和数据库列。

它也和“让 Codex 挖业务规则”相邻，但粒度更小。业务规则调查通常围绕限制、权限、额度、状态机，例如“基础套餐最多能邀请几个人”。字段流转调查围绕数据结构和转换，例如“followUpPreference 从 UI 到数据库经历了哪些命名和校验变化”。前者最终产物是业务规则索引和影响范围，后者最终产物是字段流转表和修改点列表。

它还和“接口联调问题排查”不同。接口联调通常从失败响应、状态码、日志 request id 出发，目标是定位为什么请求失败。本文即使没有报错也值得做，因为字段改动常常在编译和提交时都不报错，只是在后续回显、导出或数据分析时才暴露问题。

如果你要新增一个完全独立的表单，可以先用页面入口追踪找到组件和接口，再用本文的方法确认字段链路。如果你要修改已有字段、拆分字段、合并字段、改枚举、改必填规则，优先使用本文的方法。它的核心不是让 Codex 写更多代码，而是让它在写代码前把“字段从哪里来、到哪里去、中间被谁改名或丢弃”讲清楚。