症状与真相的距离
代码：请把附件写进 AgentFileAttachment
数据库：我没有这张表
用户看到：附件上传失败
- 「上传失败」是前端把后端错误统一收口后的提示，它只说明「这一层失败了」，不说明失败在哪一层。
- 同一句提示背后可能是完全不同的原因：迁移未执行、key 没配、请求打到了别的服务、文件格式不走该链路。先分层，别按提示字面猜。
判据
- 直连库看表是否存在 /
migrate status 是否 up to date，而不是看仓库里有没有那个 migration 目录。
- 应用迁移前先确认
DATABASE_URL 指向的是哪个库 —— 这个动作会改真实数据库结构，不能对生产库盲跑。
相关
- Schema是声明Migration是历史 —— 那条讲 schema 与 migration 的分工；本条讲「文件存在 ≠ 已执行」
- 通过只证明它实际驱动的路径 —— 同源：迁移文件“存在”只证明“写过了”，不证明“跑过了”
- 先定位归属层再动手 —— 「上传失败」只是收口后的症状，归属层要靠便宜观测划出来
- 存量不会自动跟上新逻辑 —— 同源：新逻辑要显式落到存量对象上
- 功能缺失先确认运行的是哪份产物 —— 同源：代码里有什么，和运行时在用什么是两件事
- 本地测试要显式覆盖数据源 —— 迁移要作用在正确的库上