From bf92bb2ac2cca04b40c30600ffdd6758fe4958ba Mon Sep 17 00:00:00 2001 From: karuo Date: Sat, 14 Mar 2026 09:31:19 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=84=20=E5=8D=A1=E8=8B=A5AI=20=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=202026-03-14=2009:31=20|=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=EF=BC=9A=E6=B0=B4=E6=BA=AA=E6=95=B4=E7=90=86=E5=BD=92=E6=A1=A3?= =?UTF-8?q?=E3=80=81=E8=BF=90=E8=90=A5=E4=B8=AD=E6=9E=A2=E5=B7=A5=E4=BD=9C?= =?UTF-8?q?=E5=8F=B0=20|=20=E6=8E=92=E9=99=A4=20>20MB:=2011=20=E4=B8=AA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../经验库/待沉淀/卡若AI网站全站测试经验_20260313.md | 94 +++++++++++++++++++ 运营中枢/工作台/gitea_push_log.md | 1 + 运营中枢/工作台/代码管理.md | 1 + 3 files changed, 96 insertions(+) create mode 100644 02_卡人（水）/水溪_整理归档/经验库/待沉淀/卡若AI网站全站测试经验_20260313.md diff --git a/02_卡人（水）/水溪_整理归档/经验库/待沉淀/卡若AI网站全站测试经验_20260313.md b/02_卡人（水）/水溪_整理归档/经验库/待沉淀/卡若AI网站全站测试经验_20260313.md new file mode 100644 index 00000000..cda59527 --- /dev/null +++ b/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 链接修正 diff --git a/运营中枢/工作台/gitea_push_log.md b/运营中枢/工作台/gitea_push_log.md index 1a7dcfe4..7c7b74af 100644 --- a/运营中枢/工作台/gitea_push_log.md +++ b/运营中枢/工作台/gitea_push_log.md @@ -351,3 +351,4 @@ | 2026-03-13 22:58:28 | 🔄 卡若AI 同步 2026-03-13 22:58 | 更新：运营中枢工作台 | 排除 >20MB: 11 个 | | 2026-03-13 23:06:24 | 🔄 卡若AI 同步 2026-03-13 23:06 | 更新：火炬、总索引与入口、运营中枢、运营中枢工作台 | 排除 >20MB: 11 个 | | 2026-03-13 23:26:44 | 🔄 卡若AI 同步 2026-03-13 23:26 | 更新：运营中枢工作台 | 排除 >20MB: 11 个 | +| 2026-03-13 23:54:53 | 🔄 卡若AI 同步 2026-03-13 23:54 | 更新：运营中枢工作台 | 排除 >20MB: 11 个 | diff --git a/运营中枢/工作台/代码管理.md b/运营中枢/工作台/代码管理.md index afbff5f4..22657372 100644 --- a/运营中枢/工作台/代码管理.md +++ b/运营中枢/工作台/代码管理.md @@ -354,3 +354,4 @@ | 2026-03-13 22:58:28 | 成功 | 成功 | 🔄 卡若AI 同步 2026-03-13 22:58 | 更新：运营中枢工作台 | 排除 >20MB: 11 个 | [仓库](http://open.quwanzhi.com:3000/fnvtk/karuo-ai) [百科](http://open.quwanzhi.com:3000/fnvtk/karuo-ai/wiki) | | 2026-03-13 23:06:24 | 成功 | 成功 | 🔄 卡若AI 同步 2026-03-13 23:06 | 更新：火炬、总索引与入口、运营中枢、运营中枢工作台 | 排除 >20MB: 11 个 | [仓库](http://open.quwanzhi.com:3000/fnvtk/karuo-ai) [百科](http://open.quwanzhi.com:3000/fnvtk/karuo-ai/wiki) | | 2026-03-13 23:26:44 | 成功 | 成功 | 🔄 卡若AI 同步 2026-03-13 23:26 | 更新：运营中枢工作台 | 排除 >20MB: 11 个 | [仓库](http://open.quwanzhi.com:3000/fnvtk/karuo-ai) [百科](http://open.quwanzhi.com:3000/fnvtk/karuo-ai/wiki) | +| 2026-03-13 23:54:53 | 成功 | 成功 | 🔄 卡若AI 同步 2026-03-13 23:54 | 更新：运营中枢工作台 | 排除 >20MB: 11 个 | [仓库](http://open.quwanzhi.com:3000/fnvtk/karuo-ai) [百科](http://open.quwanzhi.com:3000/fnvtk/karuo-ai/wiki) |