From 5861e646f459b51e98121f977765bc5f7cb36cda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=98=BF=E7=94=B7?= Date: Sat, 2 May 2026 10:38:12 +0800 Subject: [PATCH] docs: add E2E debugging principles to CLAUDE.md Document vconsole visibility rules (SYS_TESTER label / SYS_CAN_SUDO tag), existing debug data injection patterns, and the norm for inserting new debug data in frontend (console.warn + localStorage), backend (tracing), and database fixtures. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 4b51301..95dd2de 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,6 +34,36 @@ **Why:** 大部分问题在步骤 2-3 就能发现，避免反复触发 CI 浪费排队时间和 GitHub Actions 配额。 +## E2E 调试原则 + +排查不了的 E2E 问题时，可以往前后端插入 debug 数据辅助排查。 + +### vConsole（小程序前端调试面板） + +- **打开条件**：用户有 `SYS_CAN_SUDO` tag（root 标签）或角色上有 `SYS_TESTER` label → 自动显示 vConsole 面板 +- **实现位置**：`huike-front/src/App.vue` → `watch(() => store.current)` +- **使用方式**：打开 vConsole 后，可在 Console 面板查看 `console.warn` / `console.log` 输出，Storage 面板查看 `localStorage` 数据 + +### 已有 debug 数据注入模式 + +项目中已存在以下 debug 注入模式，可直接复用： + +| 模式 | 注入位置 | 查看方式 | +|------|----------|----------| +| `window.__cp_debug` | `pick.vue`、`add.vue`（课包相关） | vConsole Console 输入 `__cp_debug` | +| `localStorage.setItem("OrgSwitchDebug", ...)` | `store/org.ts` | vConsole Storage 面板 | +| `localStorage.setItem("ClazzPayloadDebug", ...)` | `store/clazz.ts` | vConsole Storage 面板 | +| `localStorage.setItem("CourseSectionPayloadDebug", ...)` | `store/qumu-section.ts` | vConsole Storage 面板 | +| `console.warn("[OrgSwitchDebug]", ...)` | `store/org.ts` | vConsole Console 面板 | + +### 插入新 debug 数据的规范 + +**前端**：参考已有模式，用 `console.warn("[TagName]", data)` + `window.__tagName = data` 或 `localStorage.setItem("TagName", JSON.stringify(data))` 注入。vConsole 自动捕获 console 输出。 + +**后端（Rust）**：用 `tracing::warn!("[TagName] {:?}", data)` 或 `tracing::info!(...)` 打印关键中间数据。日志会出现在服务启动的 nohup 输出（`/tmp/htykc.log` / `/tmp/htyuc.log`）以及 CI 的收尾日志步骤中。 + +**数据库**：可在 `huike-unit/ci/fixtures/` 下添加 SQL fixture 文件，插入特定测试数据。在 `e2e.yml` 中新增步骤运行即可。 + ## 部署原则 **禁止使用 scp/rsync 部署代码。** 所有部署必须走 GitHub push → 服务器 git pull 的流程。