数据库字段变更后前端需同步更新：先用codex scan定位所有引用点，再修改TS接口或Zod Schema使display_name可选，接着逐页替换渲染逻辑并验证API响应，最后清理旧字段残留引用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
数据库字段新增或删除后，前端页面仍按旧结构读取数据，导致空白、报错或显示错乱，必须同步更新页面的数据消费逻辑才能恢复功能。
先确认哪些页面受影响
打开 Codex CLI 或桌面版，执行：codex scan --impact database.display_name。该命令会扫描整个项目，找出所有直接引用 【display_name】 字段的 JSX/TSX 文件、Vue 模板、API 调用封装函数和表单校验规则。
如果未安装 Codex CLI，手动全局搜索 display_name 和 name（注意别漏掉驼峰、下划线、JSON key 字符串等变体），重点检查 fetchUser()、userSchema、UserCard.tsx、ProfileForm.vue 这类高频交互文件。
这一步跳过会导致后续修改只覆盖部分调用点，页面在某个分支路径下依然崩溃。
更新前端数据结构定义
方法一：修改 TypeScript 接口（推荐用于强类型项目）
找到 types/user.ts 或类似定义文件，将原接口：
interface User { name: string; }
改为：
interface User { name: string; display_name?: string; }
【必须加 ? 号，否则旧代码读取未赋值字段时会触发 runtime 类型错误】
方法二：修改 Zod Schema（用于表单校验与 API 响应解析）
在 schemas/user.ts 中定位 userSchema，添加可选字段：
通过 codex-reset-radar.pages.dev 监控 Codex 使用重置窗口。轮询 current.json，检测窗口开启/关闭、预测等级变化以及概率跳变。
.optional().nullable() 不能省略——因为数据库迁移期间，老记录 display_name 为空，后端可能返回 null 或缺失字段。
逐个修复页面渲染逻辑
第一步：打开 UserCard.tsx，定位到姓名展示区域。
第二步：将原写法 {user.name} 替换为 {user.display_name ?? user.name}。
第三步：保存后立即在本地开发服务器中刷新该卡片所在页面，确认新字段有值时显示 display_name，无值时回退到 name。
第四步：检查控制台是否出现 Cannot read property 'display_name' of undefined —— 若有，说明 user 对象本身是 undefined 或未完成加载，需在组件顶层加 if (!user) return null; 守卫。
方法二（Vue 项目）：在 ProfileForm.vue 的 <template></template> 中，将 {{ user.name }} 改为 {{ user.display_name || user.name }}；同时在 <script setup></script> 的表单提交逻辑里，确保 POST /api/users 请求体中包含 display_name: form.display_name || null —— 后端接收空字符串和 null 的处理方式不同，必须对齐。
验证 API 响应兼容性
启动本地开发服务后，打开浏览器开发者工具 → Network 标签页，筛选 XHR 请求，找到获取用户信息的接口（如 /api/user/123）。点击请求，查看 Response 内容：
✅ 正确响应应同时包含 "name": "Alice" 和 "display_name": "Alice Chen" 字段；
❌ 若只返回 name，说明后端未启用新字段回填逻辑，前端强行读取 display_name 必然 undefined；
⚠️ 若返回 "display_name": ""（空字符串），而前端用了 ?? 操作符，则不会回退到 name，此时应改用 || 或显式判断 user.display_name?.trim()。
这一步必须做，否则你以为页面修好了，其实只是靠 fallback 侥幸显示，真实数据一来就露馅。
清理旧字段残留引用
全局搜索 .name（带点号，避免匹配单词内子串），特别关注以下三类易漏位置：
• 表格列配置：{ title: '姓名', dataIndex: 'name' } → 改为 dataIndex: 'display_name'；
• GraphQL 查询片段：name 字段需升级为 display_name name 并在组件中适配双字段逻辑；
• Mock 数据脚本：mock/user.js 中的 name: faker.person.fullName() 行，必须补上 display_name: faker.person.fullName()，否则单元测试始终走不到新分支。
漏掉任意一类，都会造成“页面看起来正常，但某处点击就炸”的间歇性故障。
