统一码 + 上传文件：一张 jpeg 逼我重新认 API 的券码改造复盘

没有接口文档的时候，人很容易用 UI 现象反推后端语义。我（以及 AI 助手）早期走的就是这条路：

• orderType === ORDER_UNIFIED 像是统一码 ✓
• displayType !== SHOW_TEXT 像是"非纯数字码"→ 当成上传文件？✗
• voucherValue 是个 jpeg URL → 有图就是文件型？✗

全仓搜 deliveryType、redemptionType、git 历史、Jest 缓存……有效信息密度低得可怜。后端仓库当时还是空的，没法交叉验证。

转折点来了：你扔过来两样东西——订单详情接口文档截图（vouchers 字段枚举），再加一条样例响应 JSON。局面才从"推断"变成"对照"：

JSON 里 orderType: ORDER_UNIFIED、displayType: SHOW_FILE、voucherValue 指向 jpeg——和文档严丝合缝。这次改造最关键的质量保障，就在这一张截图 + 一条 JSON 上。

// 层级回退：?? 只对 null/undefined 生效，0 不会被误判成"缺失"
item?.orderType ?? subOrderType ?? orderData?.orderType

1. 业务规则绑后端契约，不绑 UI 现象

voucherValue 有 URL → 有图，不能说明"兑换方式 = 上传文件"。displayType === SHOW_FILE → 文档定义"文件"，才是契约。宽条件（比如 displayType !== SHOW_TEXT）的典型后果：统一码 + 二维码被误隐藏数字码。

2. 空字符串驱动 UI，结构分支防空壳

getVoucherDisplayCode 在统一码+文件型返回 ''，renderCode / renderCopy 用 if (!couponCode) return null。数据层空值驱动不渲染，比在多处重复 if (isUnifiedFileVoucher) 更 DRY；renderCodeSection 仍对整个红框做分支，是为了避免只剩"券码"标题、下面啥也没有的空壳 DOM——数据驱动和结构分支的折中。

3. 单测金字塔

纯函数单测：快、稳，11 条已够判定逻辑回归。组件测试要 mock i18n / CopyToClipboard，成本高，但适合锁 UI 契约。E2E 用真实统一码+文件型订单走查。三层各干各的，别指望一层包打天下。

4. 遗留类组件上的最小 diff

VoucherDetail.tsx 还扛着轮播、Popup、CopyToClipboard、路由跳转。这次只动 renderCodeSection 分支，没重构 Hooks——交付风险可控。规则外置到 voucherPolicy.ts，已经为将来抽 useVoucherDisplayPolicy(orderData, item) 留了接口。

这次改造的价值，不在于又隐藏了一个红框，而在于用后端明确枚举替代前端推断，再用纯函数 + 精准分支实现"只改上传文件场景"。

下次接到"枚举型展示规则"的需求，我会先把文档或一条 orderDetail JSON 甩到聊天框里，再让 AI 写第一行代码。推断可以留着当草稿，但别把它当交付标准——不然你和我都会在前仓里多绕好几圈。