From 6b0cc81ded49448349996568c51dcffd7de57525 Mon Sep 17 00:00:00 2001 From: m4 Date: Fri, 31 Jul 2026 16:59:14 +0800 Subject: [PATCH] docs(webui): design doc for per-user error logging Records the approved four-part design (store, collection, BFF API, bell UI) and the current implementation status. Co-Authored-By: Claude Opus 4.7 --- docs/user-error-logging.md | 42 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/user-error-logging.md diff --git a/docs/user-error-logging.md b/docs/user-error-logging.md new file mode 100644 index 0000000..c8fce5a --- /dev/null +++ b/docs/user-error-logging.md @@ -0,0 +1,42 @@ +# 用户错误日志设计方案 + +> 2026-07-31 确认的方案。目标：显示**当前用户**的错误日志，删除也只删除当前用户的错误日志。 +> 范围决策：记录全部错误（含前端 toast 错误与服务端 BFF 错误）；查看入口放在顶部通知图标。 + +## 1. 存储（服务端，按用户隔离） + +复用 userStore/usageStore 的 better-sqlite3 模式：`src/lib/server/errorLogStore.ts`，库文件 `~/.evoscientist/webui-error-logs.sqlite3`。 + +- 表：`id, user_id, created_at, source, code, message, details` +- 按 `user_id` 查询/删除；每用户保留最近 200 条，超出自动裁剪 +- 用户身份来自现有 auth session（与 userStore 同一套，`requireActor` 的 `actor.sub`；未启用认证时为内置 `local-admin`） + +## 2. 采集（两端上报） + +- 前端：`src/lib/errorReporter.ts` 提供 `reportError()`（fire-and-forget POST）与 `errorToast()`（toast.error + 上报）；逐点接入 useChat、ThreadList、各面板。纯表单校验提示仍用 `toast.error`，不上报。 +- 服务端：BFF 路由错误在 `src/lib/server/routeErrors.ts` 统一出口处顺带写入（调用方传入 actor 时）；旧格式 `{error}` 路由逐步纳入。 +- 字段：`source`（如 `chat.send` / `api`）、`code`（可选）、`message`、`details`（可选 stack/context）。 + +## 3. BFF API + +`src/app/api/error-logs/route.ts`： + +- `GET /api/error-logs?limit=100` — 当前用户的日志（id 倒序） +- `POST /api/error-logs` — 前端上报入口 +- `DELETE /api/error-logs` — 清空当前用户全部日志 + +## 4. UI（顶部通知图标） + +- 头部加铃铛图标 + 未读角标（新错误到达 +1，打开面板清零，`localStorage` 记录已读游标，key：`evoscientist.errorLogs.lastSeenId`） +- 点击弹出下拉面板：时间、来源、消息列表；底部"Clear all"按钮（二次确认后调 DELETE） +- SWR 轮询（30s）+ 随错误上报即时刷新（`subscribeErrorLogged`） + +## 主要取舍 + +- 服务端 sqlite 按用户存储（跨设备可见、与现有 auth 一致），代价是新增一个 store 模块 +- 未读角标用 localStorage 游标，简单但换浏览器会重置 + +## 实施状态（2026-07-31） + +- 第 1–3 部分已完成并提交：`61c2aba`（store）、`8d455a0`（API）、`dd4b63a`（前端上报接入）、`09d9f49`（routeErrors 写入） +- 第 4 部分（铃铛 UI）见实施计划：`docs/superpowers/plans/2026-07-31-error-log-bell.md`