🔄 卡若AI 同步 2026-03-14 09:31 | 更新：水溪整理归档、运营中枢工作台 | 排除 >20MB: 11 个

02_卡人（水）/水溪_整理归档/经验库/待沉淀/卡若AI网站全站测试经验_20260313.md

@@ -0,0 +1,94 @@
+# 卡若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 upsert
+- `src/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 handler
+- `src/app/(marketing)/gene-capsule/page.tsx` — CTA 链接修正