通用版「一次检查-定位-解决-验证」流程
（兼容 Python / Node.js / Java，保留原文所有细节，仅把语言相关处用占位符标注）
0 前置说明
- 本流程面向“后端服务或全栈项目”均可，浏览器端性能部分如用不到可跳过。
- 每个占位符【】需按实际技术栈替换，文末附常见映射表。
- 所有 git 命令、字段核对顺序、脚本命名规则均与原文保持一致，已验证。
一、一次性检查（最大限度用完一次 token）
- 页面/接口性能
a. 加载速度
‑ 浏览器场景：用 Lighthouse / WebPageTest。
‑ 纯后端：用【】压测一次，记录 p95 延迟。
b. 内存使用
‑ 浏览器：Chrome DevTools Memory。
‑ 后端：【】采样一次。
c. JavaScript 加载（仅浏览器）
‑ DevTools Network → JS 资源瀑布图。
d. CSS 资源（仅浏览器）
‑ 检查是否存在复杂 calc / @apply / 深层嵌套。
e. 数据处理效率
‑ 打开【】跑一次 CPU profile，确认无多层嵌套或冲突逻辑。 - 统一记录
‑ 把以上结果一次性写入perf-check.md，作为后续 token 上下文。
二、问题定位（一旦报错立即执行，顺序不可乱）
- 字段一致性核对
前端 → 后端 → 数据库，三层对照：
‑ 字段名、类型、顺序、大小写。
‑ 检查文件：
• 前端：请求 DTO / Type / Schema
• 后端：【】
• 数据库：迁移脚本或表结构 - 返回值错误
‑ 格式：JSON key 缺失 / 类型对不上。
‑ 方法：确认序列化配置（Python: DRF / Pydantic；Node: JSON.stringify / class-transformer；Java: Jackson）。
‑ 字段：与第1步交叉验证。 - 访问 URL 错误
‑ 路由表、路由字段、数据库功能开关（如 is_active）三项逐一核对。 - AI 幻觉防御（出现莫名 500）
a. 立刻git diff看最近 3 次提交。
b. 若发现字段被 AI 误改 → 立即git revert或手工校正。
c.git commit -m "fix: rollback AI hallucination"，再跑一次最小复现脚本验证。
三、问题解决（节省 token 原则：先看代码，再跑测试）
- 检查顺序
‑ 先肉眼读代码，再写最小复现脚本，无效再调试。 - 最小复现脚本
‑ 文件名统一为repro.<EXT>，只保留 1~2 个核心函数/接口。
‑ 运行命令：
Python:python repro.py
Node.js:node repro.mjs（或 ts-node）
Java:mvn test -Dtest=ReproTest或gradle test --tests ReproTest - 调试方式
‑ Python:pdb/ IDE 断点
‑ Node.js:--inspect+ Chrome DevTools
‑ Java: IDE 断点 / jdb - 修改原则
‑ 每次修改必须让最小复现脚本先通过，再回归主流程。
四、解决之后的验证（循环直到真正修复）
- 脚本测试
‑ 如果是后端服务，挑选对应语言脚本：
• Python:pytest -q tests/
• Node.js:npm test（jest / mocha / tap）
• Java:mvn test或gradle test
‑ 若项目含前端，另跑npm run test:e2e（Cypress / Playwright）。 - 测试结果判定
‑ 通过：标记修复完成，输出报告。
‑ 失败：
a. 立即定位失败用例位置（堆栈 / 断言）。
b. 回到“三、问题解决”二次修复。
c. 再次跑脚本，直到 100% 通过才终止。 - 提交规范
‑ commit message 格式：fix(scope): {问题简述}（repro script passed）
附录：占位符快速替换表
| 占位符 | Python 示例 | Node.js 示例 | Java 示例 |
|---|---|---|---|
| locust / wrk | autocannon / wrk | wrk / JMH | |
| memory_profiler | clinic.js --collect-only | VisualVM / jmap -histo | |
| py-spy / cProfile | 0x / clinic doctor | async-profiler / JFR | |
| models.py / schema.py | dto.ts / schema.js | Entity.java / DTO.java | |
| .py | .mjs / .ts | .java |
使用方式
- 复制本流程到项目根目录
ONCE-FLOW.md。 - 按技术栈把占位符一次性全局替换。
- 任何人处理 Bug 时，逐条打钩即可，确保不遗漏原文验证过的细节。