ReCloudStudio/WebHooker
1
0
Fork 0
mirror of https://github.com/ReCloudStudio/WebHooker.git synced 2026-09-22 16:11:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
WebHooker/docs-plan.md

7.9 KiB
Raw Blame History

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 阶段：信息架构重构

建议新结构：

指南 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 页是否都需要？