docs: fix factual errors, fill coverage gaps and align zh mirror

docs-plan.md

@@ -0,0 +1,174 @@
+# WebHooker 文档评估与优化计划
+
+> 生成日期：2026-08-13
+> 范围：`docs/`（VitePress，en+zh）、`README.md` / `README.zh.md`、`AGENTS.md`、`config.example.yaml`、`.env.example`
+
+---
+
+## 一、现状总览
+
+| 文档 | 规模 | 状态 |
+|---|---|---|
+| `docs/`（VitePress，en+zh 镜像） | 11 页 ×2，约 75KB | 结构完整但存在事实错误、覆盖缺失、信息架构混乱 |
+| `README.md` / `README.zh.md` | 363 行 | 与 docs 大量重复（secrets、GitHub App 设置、部署），已出现漂移 |
+| `AGENTS.md` | 222 行 | 基本同步，个别过时 |
+| `config.example.yaml` / `.env.example` | — | 良好，但 README/AGENTS 中 `DOCS_URL` 等变量名与代码不符（`.env.example` 正确） |
+
+---
+
+## 二、事实错误（需修复）
+
+1. **`GITHUB_APP_ID` / `GITHUB_PRIVATE_KEY` "未被代码使用"说法过时**
+   - `server/lib/github/oauth.ts:27-69` 已用它们生成 App JWT 查询安装账号（install 绑定流程）
+   - 过时位置：configuration.md:18-21、README.md:60-61/198、deployment.md:40-44、getting-started.md:40-42（en/zh 共 8 处）
+   - **deployment.md 内部自相矛盾**：40-44 行说"无需设置"，125-127 行又要求生成私钥保存到 `GITHUB_PRIVATE_KEY`
+
+2. **`DOCS_URL` / `GITHUB_REPO_URL` / `LEGAL_CONTACT` 变量名错误**
+   - README.md:74-76 与 AGENTS.md:218 使用旧名
+   - 代码实际读取 `NUXT_PUBLIC_DOCS_URL` / `NUXT_PUBLIC_REPO_URL` / `NUXT_PUBLIC_LEGAL_CONTACT`（nuxt.config.ts + runtimeConfig，`.env.example` 正确）
+
+3. **`DELETE /auth/token/:userId` 鉴权标注 "None"**（api/overview.md:23）
+   - 实际要求 admin session（oauth.ts:371-377），无 session 返回 401
+
+4. **Generic fallback 描述过时**（events/supported.md:60，en/zh）
+   - 声称"原始 payload 代码块（截断 1000 字符）"
+   - 实际 `server/lib/formatters/generic.ts` 只输出 title + color + author，无 payload 代码块
+
+5. **事件数量口径不一**
+   - "28"（docs/index、configuration、deployment、README）vs "29"（contributing.md、AGENTS.md:126）
+   - 实际 `server/lib/formatters/index.ts` switch 有 29 个 case（含 `custom`）
+   - 建议统一为："28 种 GitHub/Gitea 事件 + `custom`"
+
+6. **events/supported.md 事件表缺 `custom` 行**（en/zh 都缺）
+
+7. **`src/formatters/colors.ts` 旧路径残留**（events/supported.md:40，en/zh；应为 `server/lib/formatters/colors.ts`）
+
+8. **api/overview.md 端点表缺 9 个端点**
+   - `POST/GET /admin/api/groups/:id/invites`、`DELETE /admin/api/invites/:token`
+   - `GET /admin/api/audit`、`GET /admin/api/groups/:id/webhook`、`POST .../webhook/regenerate`、`DELETE .../webhook`
+   - `GET /admin/logout`、`GET /admin/invite?token=`
+   - configuration.md 里反而齐全——两处清单已漂移
+
+9. **providers 校验接受不存在的 `gitlab` 值**（admin.ts:288）
+   - 错误信息为 `"github" | "gitea" | "gitlab"`，但无 gitlab provider 实现
+   - 需决定：删掉（与文档 github/gitea 对齐）或保留（为未来扩展）
+
+---
+
+## 三、覆盖缺失
+
+1. **KV 布局表缺 `tenant:{groupId}`**（configuration.md:326-343，en/zh 都缺）
+   - 租户态 dedup key `delivery:{groupId}:{id}` 只散见正文
+
+2. **`NUXT_PUBLIC_DOCS_URL` / `NUXT_PUBLIC_REPO_URL` / `NUXT_PUBLIC_LEGAL_CONTACT` 未收录**
+   - configuration.md Secrets 表（en/zh）都未记录这三个变量
+
+3. **bot 命令文档碎片化**
+   - Discord `/gh` 命令只在 README（Bot Commands 段落）
+   - Telegram `/gh` 命令只在 deployment.md
+   - 无独立页面，sidebar 无入口
+
+4. **无独立页面/章节**：
+   - 调度任务（cron `*/5`：discord-sync / telegram-sync / audit-prune）
+   - i18n 消息语言与 `i18n:*` KV 覆盖机制
+   - 消息格式规范（只在 AGENTS.md，属开发内部文档）
+   - 发送日志（send_logs）字段与错误码说明
+   - FAQ / 故障排查
+
+5. **次要缺失**：
+   - 路由上限 200 / 分组上限 100（admin.ts:76,257）
+   - `X-Gitea-Delivery` 头参与去重（providers/gitea/parse.ts:60）
+   - install 选择页需要登录 session（oauth.ts:153-158）
+   - logTarget 摘要消息只列前 10 条 route×target + "+N"（dispatch.ts:88-100）
+
+---
+
+## 四、结构问题（"杂乱"的主因）
+
+1. **configuration.md 是 356 行巨型文档**
+   - 密钥、提供方、Web UI、端点、自定义 webhook、租户隔离、路由、分组、角色、过滤器、KV/D1 布局全挤一页
+
+2. **API 参考混乱**
+   - admin API 同时在 configuration.md（Web UI→端点表）、api/overview.md、README 出现三份，已开始漂移
+
+3. **sidebar 信息架构**
+   - 只有 Guide / API / Events 三类
+   - `docs/contributing.md` 不在 sidebar（孤儿页）
+   - 无 Bot 命令、无 FAQ、无故障排查入口
+
+4. **README 与 docs 严重重复**
+   - secrets 表、GitHub App 设置、Discord/Telegram bot 设置、部署步骤在 README 和 docs/deployment.md 各写一遍
+
+5. **docs 配置引用不存在的 `logo.svg`**
+   - `docs/.vitepress/config.ts` 引用 `/logo.svg`（favicon + 主题 logo），文件不存在（404）
+
+6. **footer copyright 仍写 2025**（当前 2026）
+
+---
+
+## 五、中英一致性（zh 滞后）
+
+| 严重度 | 文件 | 差异 |
+|---|---|---|
+| 高 | guide/introduction.md | zh 技术栈仍是"Nux3 静态 SPA"，en 已为"Nuxt 4 (Vue 3 + Tailwind CSS v3)" |
+| 高 | guide/getting-started.md | zh 脚本表缺 `bun run build`、`bun test` 两行；`bun run dev` 描述不一致（wrangler vs Nuxt HMR） |
+| 中 | api/overview.md | zh 漏"or manage a group"准入条件；漏"空过滤器仅 fallback 路由允许" |
+| 低 | guide/configuration.md | 可选密钥表行序不同；keyword 示例 zh 多 `*release-*`；"manage everything" 译作"管理路由" |
+| 低 | guide/filters.md | zh 一处"`/` 包裹"应为"`//` 包裹"（同文件其他处正确） |
+| 低 | index.md | 2 处 feature 描述中文略精简（未列签名头部、未列 slash commands and buttons） |
+
+完全一致的文件对：guide/deployment.md、api/actions.md、api/oauth.md、events/supported.md、contributing.md。
+
+---
+
+## 六、建议的重构方案
+
+### A 阶段：事实修正（低风险，必做）
+
+- 修复"二"中全部 9 项 + "三"的 KV/变量 2 项
+- 修复中英"高/中"级差异
+- logo.svg（补文件或从 config 移除引用）、footer 年份
+- 统一事件数量口径（28 + custom）
+
+### B 阶段：信息架构重构
+
+建议新结构：
+
+```text
+指南 Guide
+  Introduction / Getting Started / Deployment（保留现状）
+  核心概念（从 configuration.md 拆出）：
+    Routes & Targets
+    Groups & Access Control（角色/邀请/自助注册）
+    Webhook Ingress & Tenancy（全局/分组端点、custom、App 隔离）
+  消息与命令（新）：
+    Discord /gh Commands（合并 README 的 Bot Commands 段落）
+    Telegram /gh Commands
+    Message Format & i18n（新页：标题规范、emoji 开关、语言覆盖）
+  运维（新）：
+    Scheduled Tasks
+    Storage Layout（KV / D1 布局）
+    Send Logs & Audit Logs
+    FAQ & 故障排查
+
+参考 Reference
+  API（拆分 Public API 与 Admin API，与 configuration 去重）
+  Supported Events（补 custom 行、修 generic 描述）
+
+配置（单一权威来源）→ configuration.md 瘦身为"完整参考"
+README → 精简为 features + quick start + 命令摘要 + 指向 docs 的链接
+```
+
+### C 阶段：README 瘦身
+
+- README 保留：简介、features、quick start、/gh 命令摘要、部署速览、License
+- 移除与 docs 重复的完整表格（secrets、GitHub App 设置、bot 设置细节），改为链接指向 docs
+
+---
+
+## 七、待用户确认的决策点
+
+1. **范围**：只做 A？还是 A+B（重构结构）？或 A+B+C（含 README 瘦身）？
+2. **configuration.md**：按上述拆分成多个页面（改动大、导航清晰），还是保留单页只做内容修正？
+3. **`gitlab` 校验值**：代码放行但无实现——删掉（与文档对齐）还是保留（为未来扩展）？
+4. **新页面**：Bot 命令页、i18n/消息格式页、FAQ 页是否都需要？