给列表加一个字段前，让 Codex 先找清它从哪来

教程定位

这篇教程解决什么问题

线上后台里有一种改动特别容易被轻视：列表多展示一个字段。产品说“订单列表加一列发票状态”，你打开页面，看到表格组件，心里觉得也就多一个 column。真正动手后才发现，字段不只在 UI 上出现一次。接口响应里可能已经有 `invoice_status`，前端类型里却没有；API client 可能把 snake_case 映射成 camelCase；列表组件拿的是二次加工后的 `OrderListRow`；状态文案还要走枚举字典；空值要显示短横线；移动端窄屏可能不能直接塞一列。

这篇教程讲一个很小但很能体现纪律的 Codex 用法：只新增一个列表字段展示时，也让 Codex 先定位字段来源，再按最小路径改类型定义、数据映射和 UI 展示。最终产物不是大而全的重构建议，而是一份“小步修改计划”和一份“验收截图清单”。你会知道该让 Codex 先读哪些材料、怎么让它停在调查阶段、什么时候允许它改代码、改完要截哪些图证明没有顺手扩大影响。

本文使用一个安全虚构的例子：运营后台订单列表要新增“发票状态”列。后端接口样例里已经返回 `invoice_status`，状态值包括 `not_required`、`pending`、`issued`、`failed`。前端现有列表只展示订单号、客户名、金额、订单状态和创建时间。你的任务不是设计新后端，也不是重写列表表格，而是把这个已有字段低风险地展示出来。

这种小步流程适合需要低风险改动线上功能的工程师。你可能只想改三处：接口类型、映射函数、表格列。但越是小改动，越要避免 Codex “顺手补全很多它觉得合理的东西”。它可以帮你找字段、列计划、补测试和写验收清单；它不应该在没有证据时改接口路径、改后端 schema、改全局表格组件，或把所有相似的发票字段都一起整理。

使用场景

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

你负责一个订单运营后台。产品提了一个很明确的小需求：订单列表新增一列“发票状态”，方便运营在列表上快速判断哪些订单还没开票。详情页里已经能看到发票状态，后端同事说列表接口也已经返回字段，只是前端没有展示。

你手上有四类材料。第一，字段说明：列名叫“发票状态”，字段来自接口 `invoice_status`，展示文案是“不需要开票”“待开票”“已开票”“开票失败”，空值显示 `-`。第二，接口样例：`GET /api/admin/orders` 返回每条订单里的 `invoice_status`。第三，组件线索：列表组件可能在 `apps/admin/src/features/orders/OrderListPage.tsx`，列定义可能在 `OrderTableColumns.tsx`。第四，现有类型：`packages/api-client/src/orders/types.ts` 里有 `OrderListItemResponse` 和 `OrderListRow`。

这个需求看起来窄，但仍有几个容易踩的点：

这就是 Codex 适合介入的地方。你不让它一上来写 column，而是让它先回答：“字段从哪里来，经过哪一层变成 UI 可用的数据，最小改动应该落在哪些文件，哪些相似位置不该碰。”等这张小计划确认后，再让它只按计划改。

本文的核心不是“AI 帮你省十分钟写代码”，而是“AI 帮你把十分钟小改动做得像一个可审查的工程动作”。如果最后 diff 只有三五处，那很好；重点是你能解释为什么只改这些地方，为什么没有动后端，为什么没有改全局表格，为什么验收截图能覆盖风险。

1. 接口返回字段是 `invoice_status`，UI 里想用 `invoiceStatus`，中间是否已有转换函数不确定。
2. 响应类型可能是手写的，也可能由 OpenAPI 生成。生成文件不能直接手改。
3. 表格列可能不在页面文件里，而在共享列工厂里，直接加列会影响其他列表。
4. 发票状态可能已有枚举文案字典，重复写一套会造成后续不一致。
5. 列宽、排序、导出、权限和移动端展示可能有额外约束，不应凭空补功能。
6. 接口样例有字段，不代表所有环境都有值。空值和未知枚举要能安全显示。

材料准备

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

开始前，把材料整理成一张“单字段展示卡”。字段越小，输入越要具体。不要只写“帮我在订单列表加发票状态”。这个说法会让 Codex 自己猜字段名、接口路径和展示规则，它猜得越多，改动越容易跑偏。

建议准备以下输入材料。

第一类是字段说明。写清楚字段中文名、接口字段名、前端期望字段名、字段类型、枚举值、空值显示、未知值显示、是否需要排序或筛选。本例可以写成：字段中文名“发票状态”；接口字段 `invoice_status`；前端字段 `invoiceStatus`；类型为枚举字符串；空值显示 `-`；未知值显示“未知状态”；本次不做排序、不做筛选、不影响导出。

第二类是接口样例。给 Codex 一段脱敏响应，比只给字段名更有用。样例里要保留字段结构，但不要放真实客户名、订单号、手机号、地址、邮箱、支付流水号。可以使用 `ORDER_DEMO_001`、`customer_demo` 这类占位值。

第三类是候选文件。至少给列表页面、表格列文件、类型定义、API client 或 mapper 的路径。如果你不确定，可以给目录和模块名，让 Codex 先只读搜索。不要让它从全仓库盲目猜。

第四类是现有约束。比如“只展示，不改后端”“不要改生成文件”“不要新增筛选条件”“不要改导出”“如果字段来源不明先停止说明”“只允许在确认最小文件后再改”。这些限制能把 Codex 锁在小步范围内。

第五类是验收要求。单字段展示最少要有三张截图或截图检查项：正常枚举值展示、空值展示、未知值或失败值展示。如果项目有本地 mock 或 storybook，可以让 Codex 补对应 mock；如果没有，至少让它列出人工用哪些测试数据检查。

整理后的材料可以像这样：

这一步的目标是让 Codex 有足够上下文做“窄判断”。你不是让它想象一个完整发票模块，而是让它围绕一个字段回答：已有接口有没有字段，前端哪里丢了字段，展示应该放在哪里，最小验证是什么。

字段说明：
- 列名：发票状态
- 接口字段：invoice_status
- 前端字段：invoiceStatus
- 枚举值：
  - not_required: 不需要开票
  - pending: 待开票
  - issued: 已开票
  - failed: 开票失败
- 空值显示：-
- 未知枚举显示：未知状态
- 本次不做排序、不做筛选、不改导出

接口：
GET /api/admin/orders

候选文件：
- apps/admin/src/features/orders/OrderListPage.tsx
- apps/admin/src/features/orders/OrderTableColumns.tsx
- apps/admin/src/features/orders/orderMappers.ts
- packages/api-client/src/orders/types.ts

限制：
先只读定位字段来源，不要修改文件。确认最小改动计划后，再只改类型、映射和列表展示。

实操流程

按这套步骤把工作跑起来

第一步，让 Codex 只读定位字段来源。

第一轮提示词要明确“不要改代码”。让它搜索 `invoice_status`、`invoiceStatus`、`发票状态`、`InvoiceStatus`、`OrderListItemResponse`、`OrderListRow`、接口路径和候选组件。它需要输出字段来源表，而不是直接给 patch。

你要它重点回答四个问题：接口响应类型里是否有这个字段；是否有 mapper 把响应转成 UI row；表格列定义从哪里读取 row；项目里是否已有发票状态文案或枚举字典。一个好的调查结果会把证据写得很具体，例如“`OrderListItemResponse` 缺少 `invoice_status`，但接口样例包含它”“`mapOrderListItem` 当前只映射 `order_no`、`customer_name`、`amount`，未映射发票状态”“`InvoiceStatusBadge` 已在详情页使用，可以复用展示字典，但不应该改详情页。”

第二步，让 Codex 输出最小修改计划。

计划必须小到可审查。对于本例，理想计划通常是：

这个计划里有一个关键纪律：不把“新增展示字段”扩大成“完善发票功能”。如果 Codex 建议顺手新增筛选、改导出、改后端 DTO、加数据库字段，你要让它标成“非本次范围”。

第三步，先改类型，再改映射，最后改 UI。

单字段展示的安全顺序是从数据契约到展示层。先让类型能表达接口返回值，再让 mapper 把它带到 UI row，最后让表格列读取 row。这样每一步都能用编译或测试暴露问题。如果先写 UI column，Codex 可能为了让它编译，临时在组件里从原始响应对象上取字段，绕过项目原有的数据整理层。

类型改动要分清手写和生成。手写类型可以改；生成类型要回到 OpenAPI schema、接口契约文件或生成源头。如果当前仓库只消费生成后的 SDK，而源头不在本仓库，本次前端展示就不能假装类型已经存在。你可以先用局部扩展类型临时承接，但要在计划里写清楚这是兼容动作，后续需要更新 SDK。

映射改动要保持简单。不要在 mapper 里写复杂业务判断。它只负责把 `invoice_status` 变成 `invoiceStatus`，最多做空值归一。状态文案最好放在已有字典或展示组件里，不要在 mapper 里把 `pending` 直接变成“待开票”，否则后续换语言或统一文案会很难。

UI 改动要只碰当前列表列定义。新增列时要看现有列的模式：项目是对象数组、列工厂、render 函数还是配置表。列宽、对齐、固定列、响应式隐藏都跟着现有风格走。不要为了一个字段改全局表格组件，也不要把其他列顺手整理。

第四步，让 Codex 自己做一次“越界检查”。

改完代码后，不要只问“测试过了吗”。让它按计划反查：实际修改的文件是否都在计划内；有没有动生成文件；有没有改后端；有没有新增筛选、排序、导出；有没有改共享状态字典导致详情页变化；有没有为了编译绕过 mapper。这个自查能抓住很多 AI 写代码时的手滑。

第五步，运行本地检查并生成验收截图清单。

检查分两类。自动检查包括类型检查、相关单元测试、表格渲染测试或 lint。人工检查包括打开订单列表，分别确认正常状态、空值和异常状态。截图清单不需要很复杂，但要具体：

| 场景 | 测试数据 | 预期展示 | 截图重点 | | --- | --- | --- | --- | | 待开票 | `invoice_status: "pending"` | 发票状态列显示“待开票” | 列标题、行内容、未挤压其他列 | | 已开票 | `invoice_status: "issued"` | 显示“已开票” | 文案和详情页一致 | | 空值 | `invoice_status: null` | 显示 `-` | 不出现 `null`、`undefined` | | 未知值 | `invoice_status: "archived"` | 显示“未知状态”或安全降级 | 页面不报错 |

第六步，把小步计划和截图清单放进交付说明。

这类小改动的交付说明可以很短，但要能说明边界：本次只展示接口已有字段；修改范围是类型、映射和订单列表列定义；未改后端、导出、筛选和排序；验收覆盖四种展示状态。评审者看到这些信息，会更容易相信这不是一个被 AI 扩大的改动。

1. 在手写响应类型中补 `invoice_status?: InvoiceStatus | null`。如果文件是生成文件，则停止，改为找到生成源头。
2. 在 mapper 中把 `invoice_status` 映射为 `invoiceStatus`，并保留 `null` 或未知值。
3. 在订单列表列定义中新增“发票状态”列，使用已有状态文案函数或徽标组件。
4. 补一个 mapper 单元测试或表格渲染测试，覆盖 `pending` 和空值。
5. 给人工验收列截图清单，不新增排序、筛选或导出。

输入示例

可以直接参考的输入材料

下面是一份可以直接交给 Codex 的输入材料。它使用虚构字段和脱敏数据，可以按你的项目替换路径和枚举。

这份输入有几个刻意设计的细节。它给了字段枚举，防止 Codex 自己发明文案；它写明“只展示”，防止 Codex 顺手做筛选；它给了空值和未知枚举，防止页面上出现 `undefined`；它给了候选文件，但仍要求先定位来源，防止直接在页面里硬写。

你先不要改代码，只做只读调查和最小修改计划。

任务：
订单列表新增一列“发票状态”。后端同事说列表接口已经返回字段，前端目前没有展示。

字段说明：
- 中文列名：发票状态
- 接口字段：invoice_status
- 前端字段建议：invoiceStatus
- 枚举值：
  - not_required: 不需要开票
  - pending: 待开票
  - issued: 已开票
  - failed: 开票失败
- 空值显示：-
- 未知枚举显示：未知状态
- 本次只展示，不做筛选、不做排序、不改导出、不改后端。

接口样例：
GET /api/admin/orders

{
  "items": [
    {
      "order_no": "ORDER_DEMO_001",
      "customer_name": "customer_demo",
      "amount_cents": 129900,
      "order_status": "paid",
      "invoice_status": "pending",
      "created_at": "2026-06-18T09:20:00Z"
    },
    {
      "order_no": "ORDER_DEMO_002",
      "customer_name": "customer_demo_2",
      "amount_cents": 89000,
      "order_status": "paid",
      "invoice_status": null,
      "created_at": "2026-06-19T11:30:00Z"
    }
  ]
}

候选文件：
- apps/admin/src/features/orders/OrderListPage.tsx
- apps/admin/src/features/orders/OrderTableColumns.tsx
- apps/admin/src/features/orders/orderMappers.ts
- apps/admin/src/features/orders/invoiceStatus.ts
- packages/api-client/src/orders/types.ts

请输出：
1. 字段来源定位结果：接口、类型、mapper、UI 分别在哪里。
2. 最小修改计划：只列必须改的文件和理由。
3. 不改清单：哪些相似文件或功能本次不碰。
4. 验收截图清单：至少覆盖 pending、issued、null、未知枚举。

限制：
不要修改文件。如果发现类型文件是生成文件，标出来，不要手改生成产物。

提示词

可复制使用的提示词

下面这段提示词可以直接复制使用。建议分成两轮：第一轮只读计划，第二轮才允许改代码。

确认计划后，再发第二轮：

这段提示词的重点是“允许”和“不允许”都写清楚。单字段改动最怕范围弹开，尤其是 AI 看到相似模式后会主动完善它认为缺的功能。把边界放在提示词里，能让后续 diff 保持轻。

第一轮：只读定位和计划

你是这个代码库里的小步改动助手。请先不要改代码。

我要在一个已有列表里新增一个字段展示。这个改动看起来很小，但我希望先确认字段来源、类型、映射和 UI 展示位置，避免误改共享组件或生成文件。

字段材料：
[粘贴字段说明、枚举、空值规则、未知值规则]

接口样例：
[粘贴脱敏接口响应]

候选文件或目录：
[粘贴列表组件、列定义、mapper、类型定义、状态字典位置]

请输出：
1. 字段来源定位表：层级、文件、当前证据、是否需要修改。
2. 最小修改计划：按类型定义、数据映射、UI 展示、测试或验收顺序列出。
3. 不改清单：本次不碰哪些文件或功能，并说明原因。
4. 风险点：生成文件、共享组件、空值、未知枚举、列宽或响应式问题。
5. 验收截图清单：用具体数据说明要截哪些状态。

限制：
不要修改文件。不要新增筛选、排序、导出、后端字段或数据库迁移。证据不足时先停下说明。

第二轮：按计划小步修改

请只按照刚才确认的最小修改计划改代码。

允许修改：
- [类型定义文件，如果确认不是生成文件]
- [mapper 文件]
- [当前列表列定义文件]
- [相关最小测试或 mock，如项目已有模式]

不允许修改：
- 后端接口、数据库、导出、筛选、排序
- 全局表格组件
- 与当前列表无关的详情页或其他页面
- 生成文件，除非你已经定位到生成源头并说明原因

实现要求：
1. 先补类型，再补 mapper，最后加 UI 列。
2. 复用已有枚举文案或状态展示组件；如果没有，新增局部小字典，不要放进无关全局模块。
3. 空值显示为 [空值规则]，未知枚举安全降级为 [未知值规则]。
4. 改完后列出实际修改文件、检查命令、验收截图清单。
5. 如果发现必须超出允许范围，先停止并说明，不要继续改。

输出样例

AI 应该输出到什么程度

下面是一份较理想的 Codex 输出样例。它不是最终代码，而是第一轮只读定位后应该给你的计划。

这份输出值得保留的地方，是它把“已有字段展示”拆成了可检查的小层级。它没有因为任务小就跳过类型，也没有因为接口样例里有字段就默认 UI 能直接取到。它还把不改清单写清楚，避免把单字段展示扩成发票模块改造。

字段来源定位表：

1. 接口响应
   证据：输入样例中的 GET /api/admin/orders items[] 包含 invoice_status。
   结论：字段来源是列表接口已有响应，本轮不需要改后端。

2. 响应类型
   文件：packages/api-client/src/orders/types.ts
   证据：OrderListItemResponse 当前包含 order_no、customer_name、amount_cents、order_status、created_at，未包含 invoice_status。
   结论：如果该文件是手写类型，需要新增 invoice_status?: InvoiceStatus | null；如果文件顶部有 generated 标记，则不直接手改。

3. 数据映射
   文件：apps/admin/src/features/orders/orderMappers.ts
   证据：mapOrderListItem 将 order_no 映射为 orderNo，将 order_status 映射为 orderStatus，未处理 invoice_status。
   结论：需要新增 invoiceStatus: item.invoice_status ?? null。

4. UI 列定义
   文件：apps/admin/src/features/orders/OrderTableColumns.tsx
   证据：列表列从 OrderListRow 读取字段，现有列包括订单号、客户、金额、订单状态、创建时间。
   结论：在订单状态后新增“发票状态”列，使用现有 renderInvoiceStatus 或局部 formatInvoiceStatus。

最小修改计划：
1. 补充 InvoiceStatus 类型和值集合，如果项目已有 invoiceStatus.ts，则优先复用。
2. 在 OrderListItemResponse 和 OrderListRow 中补字段，不改生成文件。
3. 在 mapOrderListItem 中把 invoice_status 映射到 invoiceStatus。
4. 在 OrderTableColumns.tsx 新增发票状态列，空值显示 '-'，未知值显示 '未知状态'。
5. 补 mapper 测试：pending 正常映射，null 保持 null。
6. 补人工验收截图清单，不新增筛选、排序和导出。

不改清单：
- 不改后端接口和数据库，因为输入材料说明接口已有字段。
- 不改订单详情页，因为详情页已有展示，不是本次问题。
- 不改导出逻辑，因为本次目标只要求列表展示。
- 不改全局 Table 组件，因为新增列可以在当前列表列定义完成。
- 不改筛选器和排序参数，因为产品没有要求，贸然新增会改变接口契约。

风险点：
- 如果 types.ts 是生成文件，需要回到生成源头或等待 SDK 更新。
- 如果发票状态文案在详情页已有一套字典，重复新增字典会造成文案漂移。
- 如果列表列很多，需要确认窄屏下是否隐藏低优先级列或允许横向滚动。
- 如果接口某些环境返回未知枚举，UI 必须安全降级。

验收截图清单：
1. ORDER_DEMO_001: invoice_status = pending，发票状态列显示“待开票”。
2. ORDER_DEMO_003: invoice_status = issued，显示“已开票”。
3. ORDER_DEMO_002: invoice_status = null，显示“-”。
4. ORDER_DEMO_004: invoice_status = archived，显示“未知状态”且页面不报错。
5. 截图需包含表头、发票状态列和相邻的订单状态列，确认列没有挤压主要信息。

人工验收

人要怎么检查和改到可用

Codex 给出计划和代码后，人要做一次很小但很硬的复核。建议按下面这份人工复核清单逐项过。

第一，复核字段来源。确认接口样例里的 `invoice_status` 真的对应列表接口，而不是详情接口、导出接口或 mock 数据。很多小改动失败，是因为拿错了接口样例。列表页用的是分页接口，就不要把详情页响应里的字段当成列表字段。

第二，复核类型文件性质。打开类型定义文件，看它是不是生成产物。如果有 `generated`、`do not edit`、OpenAPI 生成脚本痕迹，不能因为 Codex 补了一行类型就接受。生成文件被手改，下一次生成会覆盖，问题还会回来。

第三，复核 mapper。确认 UI 列读取的是 `OrderListRow.invoiceStatus`，而不是在列 render 里直接访问原始接口对象。项目既然已有 mapper，就要让字段走同一条数据整理路径。直接在 UI 里混用 snake_case 和 camelCase，后续会让列表越来越难维护。

第四，复核状态文案。确认 `pending`、`issued` 等枚举文案和详情页、运营口径一致。不要让 Codex 自己翻译成“等待发票”“发票完成”这类看似合理但和产品口径不一致的词。未知值和空值要分开处理，空值不是未知状态。

第五，复核 UI 影响。看新增列是否破坏表格宽度、固定列、批量操作栏、横向滚动和移动端布局。如果后台表格已经很宽，可能需要让该列只在中宽以上显示，或调整列宽。这个判断通常要人工看截图，不适合只靠类型检查。

第六，复核未越界。检查实际 diff 是否只落在计划内：类型、mapper、当前列表列定义、相关测试或 mock。若出现后端、数据库、导出、筛选、排序、全局表格组件、详情页大改，就要让 Codex 解释证据。没有证据的扩大改动应撤回。

第七，复核验收截图。截图不只是“看起来有列”。至少要覆盖正常值、空值、未知值或失败值。截图中要能看到表头和相邻列，确认字段没有错位，也没有把订单状态和发票状态混淆。

人工修改时可以保持一个简单原则：如果这次改动不能用一句话说清楚，就说明范围可能变大了。本例的一句话应该是：“订单列表展示接口已有的发票状态字段，前端补齐类型、映射和一列表格列。”如果变成“顺便统一发票状态能力”，那就已经不是本文的方法了。

教程正文

适用边界

这个流程适合“已有数据源上的单字段展示”。典型场景包括：订单列表加发票状态、客户列表加归属销售、工单列表加 SLA 状态、活动报名列表加审核结果、库存列表加安全库存标记。共同特点是字段来源已有或基本明确，需求目标只是展示，不要求新的业务写入链路。

它不适合三类情况。

第一，字段来源不存在。比如后端还没有返回字段，数据库也没有对应数据。这时就不是前端单字段展示，而是接口契约和数据建模问题，需要走更完整的需求拆解。

第二，字段会改变业务决策。比如新增“风控状态”后要影响可退款、可发货、可审批，这就不只是展示字段，必须追业务规则和权限边界。

第三，字段展示牵涉大范围产品体验。比如新增列会改变列表默认排序、筛选条件、导出模板、统计口径、权限可见性和移动端布局。这时仍可以让 Codex 帮忙，但应该升级为多步骤计划，而不是套用单字段最小改动。

还有一个边界要记住：小步不是偷懒。小步的意思是每次只改能证明目标的最少层级，并把未做事项写清楚。它不是忽略测试，也不是不管空值。相反，越是小改动，越要把“我没有改什么”讲明白。

失败反例

这些失败反例要提前避开

**反例 1：直接在表格列里读 `record.invoice_status`。**

Codex 看到接口样例里有 `invoice_status`，就在 `OrderTableColumns.tsx` 的 render 里写 `record.invoice_status`。页面可能一时能跑，但项目其他列都读取 `OrderListRow` 的 camelCase 字段。这样会破坏数据层约定，也可能在真实运行时拿不到字段，因为 mapper 已经把原始响应包了一层。正确做法是先补类型和 mapper，再让 UI 读 `invoiceStatus`。

**反例 2：手改 OpenAPI 生成文件。**

类型文件缺字段，Codex 直接加了一行 `invoice_status?: string`。但文件顶部写着由 OpenAPI 生成。短期编译过了，下一次 SDK 生成又把这行冲掉。遇到生成文件，要么回到 schema 源头，要么在计划中标记依赖 SDK 更新；不能把生成产物当普通代码改。

**反例 3：为了一个展示字段，顺手新增筛选和排序。**

AI 觉得列表字段应该能筛选，于是新增了筛选器、URL 参数和接口 query。结果后端并不支持，线上请求带了未知参数，或者筛选结果和运营预期不一致。本次需求只是展示，就不要扩展查询能力。筛选、排序、导出都应该有单独需求和接口确认。

**反例 4：空值和未知枚举混成一种展示。**

有些订单确实不需要开票，可能返回 `not_required`；有些是数据缺失，返回 `null`；还有些是后端新增了前端未知的枚举。把它们都显示成“未知状态”会误导运营。字段说明里应提前写清空值、已知枚举和未知枚举的不同展示，Codex 也要按这个规则实现。

**反例 5：改了共享状态字典却没有检查详情页。**

为了列表展示，Codex 修改了全局 `invoiceStatusLabels`，把 `failed` 从“开票失败”改成“失败”。列表看起来更短，但详情页、导出说明和客服话术都被一起改了。复用字典可以，但修改共享字典要有全局影响评估。若只是列表列宽问题，优先在列表展示层做样式处理，不要随便改业务文案。

主题边界

它和相邻主题的区别

这篇文章和“从一个表单开始追数据流”不同。表单追踪关注用户输入如何经过校验、提交、后端 DTO 和数据库，核心风险是写入链路漏改。本文关注的是已有接口字段如何进入列表 UI，核心风险是类型、映射和展示层之间断开，以及为了一个展示字段扩大范围。

它也不同于“小 bug 也要控范围”。小 bug 那篇从错误现象出发，重点是找到最小修复边界和不改清单；本文从明确的新展示需求出发，重点是先确认字段来源，再按类型、mapper、UI 的顺序做小步实现。

它还不同于“大功能拆成小改动”。大功能拆解会处理数据库、接口、权限、灰度和回滚。本文故意站在更窄的位置：一个字段，一张列表，已有数据源，目标是把最小改动纪律练熟。练熟这种单字段节奏后，再把它放进更大的功能拆解里，Codex 才不容易把每个小口子都撕成大改造。