新人入职第一周最痛苦的事遇到问题不知道找谁问、不知道去哪看日志、不知道常见报错是什么原因。我把团队常见的 debug 场景整理成一份急救手册放在 steering 里。新人遇到问题时 AI 能直接给出排查路径不用等老员工有空回复。新人 debug 的典型困境新人看到报错 TypeError: Cannot read properties of undefined (reading map) 内心活动 ├── 这个报错什么意思知道 ├── 发生在哪里看 stack trace...看不太懂 ├── 为什么数据是 undefined不知道 ├── 接口没返回还是传参有问题不确定 ├── 去问谁老员工在开会 └── 等了 2 小时... 有了急救手册后 ├── AI 根据报错类型匹配排查路径 ├── 这类错误 90% 是接口返回数据为 null请检查... ├── 给出具体的检查步骤 └── 20 分钟自行解决急救手册结构# Debug 急救手册steering 文件 ## 常见报错 → 排查路径 ### TypeError: Cannot read properties of undefined **最常见原因按概率排序** 1. 接口返回的 data 为 null/undefined60% - 检查Network 面板看接口响应 - 修复加可选链 data?.list?.map() 2. 组件 mount 时异步数据还没回来25% - 检查是否有 loading 状态判断 - 修复加 if (!data) return Loading / 3. 解构了不存在的字段15% - 检查console.log 打印接口返回结构 - 修复加默认值 const { list [] } data || {} ### 页面白屏无报错 **排查步骤** 1. 打开 Console 看有没有静默错误 2. 看 Network 有没有 HTML/JS 404 3. 检查路由配置是否正确src/route/routes/ 4. 清浏览器缓存可能加载了旧 JS ### 接口 401/403 **含义** - 401 token 过期 → 重新登录 - 403 无权限 → 检查角色配置 **排查** 1. Application → Cookie 里的 token 是否存在 2. 是否切换了品牌/环境但 token 没刷新 3. 找后端确认角色权限配置 ### 样式错乱CSS 冲突 **常见原因** 1. 没用 CSS Modules.less 而非 .m.less→ 全局污染 2. antd 组件样式被覆盖 → 检查是否有 :global 滥用 3. 组件库版本冲突 → 检查 node_modules 有没有多个 antd 版本环境相关问题### 本地 npm test 启动失败 **常见原因** 1. node 版本不对 → nvm use看 .nvmrc 2. 依赖没装 → npm install 3. 端口 8009 被占用 → lsof -i :8009 或换端口 4. 环境变量缺失 → 检查 env/ 目录 ### 代理接口报 502/504 **含义** 后端服务挂了或网关超时 **确认方法** 1. 用 Postman 直接请求后端地址绕过代理 2. 问后端是不是在发版 3. 切换环境试试test → poc ### 构建成功但页面空白 **排查** 1. publicPath 配置是否正确 2. nginx 转发规则是否匹配 hash 路由 3. dist/index.html 里的资源路径是否可访问业务逻辑相关### brandId 相关问题 项目是多品牌架构很多接口需要 brandId header。 **如果接口返回空数据或 400** 1. 检查请求 header 里有没有 X-Brand-Id 2. 检查当前选择的品牌是否正确 3. 确认这个接口是否需要 brandId看后端文档 ### 权限按钮不显示 **排查** 1. 确认当前账号角色配置了该权限 2. 检查权限 key 是否拼写正确看 permissions/ 目录 3. 确认 useAuth().hasPermission 返回值 4. 测试环境可能权限数据不全 → 让后端加AI 如何使用这份手册当新人问 AI 问题时新人页面报错了 Cannot read properties of undefined ↓ AI有 steering 上下文 根据项目经验这个错误最常见的原因是接口返回数据为 null。 请按以下步骤排查 1. 打开 DevTools → Network找到对应接口 2. 查看 Response确认 data 字段是否有值 3. 如果 data 是 null在代码中加可选链保护 data?.list?.map(...) 或加 loading 判断 4. 如果 data 有值但结构和预期不同console.log 打印确认字段名新人不需要看文档、不需要等人回复AI 直接给排查路径。手册的维护策略来源 ├── 每次新人问的问题 → 总结加进手册 ├── 线上 bug 的根因 → 提炼为排查路径 ├── 团队 retro 中提到的坑 → 记录下来 └── 随着项目演进持续更新 维护频率 ├── 新人入职时集中补充一波 ├── 每个迭代结束回顾一次 ├── 遇到新类型问题随时追加 └── 约每月更新 1-2 次效果数据指标 使用前 使用后 变化 ────────────── ────── ────── ──── 新人首周日均提问数 8-10 次 3-4 次 -60% 问题平均解决时间 2h 20min -83% 老员工被打断次数/天 4-5 次 1-2 次 -60% 新人首个需求完成时间 5 天 3 天 -40%给团队维护手册的建议Do ├── 按报错信息组织方便搜索 ├── 给出具体步骤不是去看看接口而是打开 Network 面板→找到 xxx 接口→看 Response ├── 标注概率60% 是因为 A25% 是因为 B ├── 放在 steering 里让 AI 可以引用 └── 让新人参与维护他们遇到问题最多 Dont ├── 写成大而全的文档太长没人看 ├── 只写原因不写步骤新人不知道怎么操作 ├── 一次写完不再更新会过时 └── 放在飞书文档里AI 无法引用 你们团队是怎么帮新人快速上手 debug 的有类似的知识沉淀吗完整 Skills 源码已开源github.com/sleepyccat/ai-native-workflow欢迎 Star ⭐ 和 PR。
新人入职第一周最痛苦的事遇到问题不知道找谁问、不知道去哪看日志、不知道常见报错是什么原因。我把团队常见的 debug 场景整理成一份急救手册放在 steering 里。新人遇到问题时 AI 能直接给出排查路径不用等老员工有空回复。新人 debug 的典型困境新人看到报错 TypeError: Cannot read properties of undefined (reading map) 内心活动 ├── 这个报错什么意思知道 ├── 发生在哪里看 stack trace...看不太懂 ├── 为什么数据是 undefined不知道 ├── 接口没返回还是传参有问题不确定 ├── 去问谁老员工在开会 └── 等了 2 小时... 有了急救手册后 ├── AI 根据报错类型匹配排查路径 ├── 这类错误 90% 是接口返回数据为 null请检查... ├── 给出具体的检查步骤 └── 20 分钟自行解决急救手册结构# Debug 急救手册steering 文件 ## 常见报错 → 排查路径 ### TypeError: Cannot read properties of undefined **最常见原因按概率排序** 1. 接口返回的 data 为 null/undefined60% - 检查Network 面板看接口响应 - 修复加可选链 data?.list?.map() 2. 组件 mount 时异步数据还没回来25% - 检查是否有 loading 状态判断 - 修复加 if (!data) return Loading / 3. 解构了不存在的字段15% - 检查console.log 打印接口返回结构 - 修复加默认值 const { list [] } data || {} ### 页面白屏无报错 **排查步骤** 1. 打开 Console 看有没有静默错误 2. 看 Network 有没有 HTML/JS 404 3. 检查路由配置是否正确src/route/routes/ 4. 清浏览器缓存可能加载了旧 JS ### 接口 401/403 **含义** - 401 token 过期 → 重新登录 - 403 无权限 → 检查角色配置 **排查** 1. Application → Cookie 里的 token 是否存在 2. 是否切换了品牌/环境但 token 没刷新 3. 找后端确认角色权限配置 ### 样式错乱CSS 冲突 **常见原因** 1. 没用 CSS Modules.less 而非 .m.less→ 全局污染 2. antd 组件样式被覆盖 → 检查是否有 :global 滥用 3. 组件库版本冲突 → 检查 node_modules 有没有多个 antd 版本环境相关问题### 本地 npm test 启动失败 **常见原因** 1. node 版本不对 → nvm use看 .nvmrc 2. 依赖没装 → npm install 3. 端口 8009 被占用 → lsof -i :8009 或换端口 4. 环境变量缺失 → 检查 env/ 目录 ### 代理接口报 502/504 **含义** 后端服务挂了或网关超时 **确认方法** 1. 用 Postman 直接请求后端地址绕过代理 2. 问后端是不是在发版 3. 切换环境试试test → poc ### 构建成功但页面空白 **排查** 1. publicPath 配置是否正确 2. nginx 转发规则是否匹配 hash 路由 3. dist/index.html 里的资源路径是否可访问业务逻辑相关### brandId 相关问题 项目是多品牌架构很多接口需要 brandId header。 **如果接口返回空数据或 400** 1. 检查请求 header 里有没有 X-Brand-Id 2. 检查当前选择的品牌是否正确 3. 确认这个接口是否需要 brandId看后端文档 ### 权限按钮不显示 **排查** 1. 确认当前账号角色配置了该权限 2. 检查权限 key 是否拼写正确看 permissions/ 目录 3. 确认 useAuth().hasPermission 返回值 4. 测试环境可能权限数据不全 → 让后端加AI 如何使用这份手册当新人问 AI 问题时新人页面报错了 Cannot read properties of undefined ↓ AI有 steering 上下文 根据项目经验这个错误最常见的原因是接口返回数据为 null。 请按以下步骤排查 1. 打开 DevTools → Network找到对应接口 2. 查看 Response确认 data 字段是否有值 3. 如果 data 是 null在代码中加可选链保护 data?.list?.map(...) 或加 loading 判断 4. 如果 data 有值但结构和预期不同console.log 打印确认字段名新人不需要看文档、不需要等人回复AI 直接给排查路径。手册的维护策略来源 ├── 每次新人问的问题 → 总结加进手册 ├── 线上 bug 的根因 → 提炼为排查路径 ├── 团队 retro 中提到的坑 → 记录下来 └── 随着项目演进持续更新 维护频率 ├── 新人入职时集中补充一波 ├── 每个迭代结束回顾一次 ├── 遇到新类型问题随时追加 └── 约每月更新 1-2 次效果数据指标 使用前 使用后 变化 ────────────── ────── ────── ──── 新人首周日均提问数 8-10 次 3-4 次 -60% 问题平均解决时间 2h 20min -83% 老员工被打断次数/天 4-5 次 1-2 次 -60% 新人首个需求完成时间 5 天 3 天 -40%给团队维护手册的建议Do ├── 按报错信息组织方便搜索 ├── 给出具体步骤不是去看看接口而是打开 Network 面板→找到 xxx 接口→看 Response ├── 标注概率60% 是因为 A25% 是因为 B ├── 放在 steering 里让 AI 可以引用 └── 让新人参与维护他们遇到问题最多 Dont ├── 写成大而全的文档太长没人看 ├── 只写原因不写步骤新人不知道怎么操作 ├── 一次写完不再更新会过时 └── 放在飞书文档里AI 无法引用 你们团队是怎么帮新人快速上手 debug 的有类似的知识沉淀吗完整 Skills 源码已开源github.com/sleepyccat/ai-native-workflow欢迎 Star ⭐ 和 PR。
`/`login_legacy()` 双流程与私有 HTTP/2 传输切换)
