4.4 KiB
4.4 KiB
卡若AI 网站全站测试经验沉淀
日期：2026-03-13 | 执行者：卡若AI · 火炬（全栈开发）
项目：卡若AI 官网（Next.js 14 + MongoDB）| 端口：3102
一、测试范围
全站 15 个控制台页面 + 1 个登录页 + 2 个营销页，逐页点击所有按钮、编辑项、链接，验证前端渲染、后端 API、数据库一致性。
二、发现并修复的关键问题
P0 严重（影响可用性）
| # | 问题 | 根因 | 修复方式 |
|---|---|---|---|
| 1 | 登录页不可达 | middleware 对 /console/login 也做了重定向 |
白名单放行 LOGIN_PATH |
| 2 | 开放重定向漏洞 | login 的 next 参数未校验 |
限制只允许 / 开头且非 // 的相对路径 |
| 3 | 技能数据翻倍（146 vs 73） | storage-mongo.ts 缺唯一索引 + writeData 用 deleteMany+insertMany 竞态 | 恢复 id 唯一索引 + replaceOne upsert |
| 4 | 心跳页崩溃风险 | exec.actions 可能为 undefined | 全部加 ?? [] 防御 |
P1 重要（影响体验）
| # | 问题 | 修复方式 |
|---|---|---|
| 1 | 基因胶囊删除 API 缺失 | 补 DELETE handler |
| 2 | 全站 API 调用无错误处理 | 统一加 try/catch + res.ok 检查 |
| 3 | 删除操作无确认弹窗 | 所有 remove/batchDelete 加 confirm() |
| 4 | API Key 明文展示 | 脱敏显示（首8末4） |
| 5 | 导航缺"文档操作"入口 | ConsoleShell navGroups 补回 |
| 6 | 仪表盘快捷操作文案误导 | "同步技能"→"技能配置"等 |
| 7 | 基因胶囊营销页 CTA 链接错误 | 修正为 /console/chat 和 /console/skills |
三、经验总结
3.1 MongoDB 并发写入必须加唯一索引
deleteMany({})+insertMany模式在并发下必然产生重复- 正确做法：唯一索引 +
replaceOne({ upsert: true }) - 索引要在
getDb()初始化时createIndex，且需持久化标记避免重复创建
3.2 Next.js middleware 白名单模式
- middleware 拦截
/console/*时，必须显式放行/console/login - 开发环境可自动种 cookie（
karuo_role=owner），生产需严格验证
3.3 客户端渲染页面的 Loading 状态
- 所有
useEffect+fetch的页面首次渲染都是空状态 - 这是 Next.js CSR 的正常行为，不是 bug
- 重要的是确保 fetch 完成后数据正确加载
3.4 全站 API 调用规范
- 每个 fetch 都必须 try/catch + 检查 res.ok
- 删除操作必须有 confirm 确认
- 失败时给用户可读反馈，不要静默失败
3.5 安全审计清单
- 登录重定向参数必须校验（防开放重定向）
- API Key 只做脱敏展示（首8末4）
- 默认密码和 API Key 不应硬编码在源码中，应走 .env
四、页面清单与最终状态
| 页面 | 路径 | 状态 |
|---|---|---|
| 仪表盘 | /console | ✅ 正常 |
| AI 对话 | /console/chat | ✅ 正常 |
| 技能配置 | /console/skills | ✅ 正常（73项） |
| 基因胶囊 | /console/gene-capsule | ✅ 正常（106项） |
| 流程编排 | /console/workflows | ✅ 正常（16项） |
| 任务控制台 | /console/tasks | ✅ 正常（24项） |
| 定时调度 | /console/scheduler | ✅ 正常 |
| 心跳机制 | /console/heartbeat | ✅ 正常 |
| API 网关 | /console/gateway | ✅ 正常（7项） |
| 开放 API | /console/api-open | ✅ 正常（5个端点） |
| 平台集成 | /console/integrations | ✅ 正常 |
| 账号权限 | /console/users | ✅ 正常 |
| 平台治理 | /console/platform | ✅ 正常 |
| 文档操作 | /console/docs | ✅ 正常 |
| 登录页 | /console/login | ✅ 可达 |
五、修改文件清单
src/middleware.ts— 登录白名单 + 开发自动登录src/app/(console)/console/login/page.tsx— 开放重定向修复src/lib/storage-mongo.ts— 唯一索引 + replaceOne upsertsrc/components/console/ConsoleShell.tsx— 导航补回文档操作src/app/(console)/console/page.tsx— 仪表盘文案 + 任务可点击src/app/(console)/console/workflows/page.tsx— 错误处理 + 空状态文案src/app/(console)/console/gateway/page.tsx— Key 脱敏 + 错误处理src/app/(console)/console/heartbeat/page.tsx— actions 空值防护 + 确认弹窗src/app/(console)/console/scheduler/page.tsx— 确认弹窗 + 错误处理src/app/(console)/console/integrations/page.tsx— 校验 + 确认 + 错误处理src/app/api/platform/gene-capsules/[id]/route.ts— 补 DELETE handlersrc/app/(marketing)/gene-capsule/page.tsx— CTA 链接修正