# 文档受众分层重构计划

**状态**：待实施
**创建日期**：2026-05-12
**核心目标**：把 `docs/technical/{zh,en}/manual.md` 拆成"纯客户视角"的使用手册，把 `planet.sh`、日志、LAN、故障排查这类运维内容迁到独立 `ops-runbook.md`，并把分层规则写进 `documentation-coverage-rules.md` 和 `.claude/commands/docs.md`，让以后写文档时自动按受众归档。

## 背景

当前 `manual.md` 把客户实际使用和开发/运维操作混在一份文档里：开头 200 多行讲的是 `planet.sh start/stop/restart/log/health/createuser/--allow-lan`、AI Provider 镜像构建、`netsh portproxy` 和故障排查顺序，后面才进入 Earth、控制台、AI、Docs 这些客户真正会用到的功能。

客户读到一半会被 shell 命令吓住，开发者想找运维细节又要在大段 UI 操作里翻。`documentation-coverage-rules.md` 现在也没有受众分层规则，未来文档继续混着写。

本计划假定客户已经能拿到账号登录使用 — 注册/验证流程本身见 [用户公开注册与邮箱验证计划](/home/ray/dev/linkong/planet/docs/plans/user-registration-email-verification-plan.md)。

## 新的文档地形

| 文档 | 受众 | Gatekeeper 组 | 范围 |
| --- | --- | --- | --- |
| `manual.md` (zh+en) | 纯客户/最终用户 | `public` | 注册、登录、账户、设置 UI、collector 配置、AI 配置、Console 页面、Earth、Docs 浏览 |
| `quickstart.md` (zh+en) | 纯客户 | `public` | "我刚拿到 Planet 怎么开始用" — 打开 URL → 注册 → 验证 → 登录 → 第一次配置 |
| `ops-runbook.md` (zh+en, **新增**) | 运维/部署人员 | `docs_admin` | `planet.sh` 完整命令、健康检查、日志位置、LAN/portproxy、故障排查顺序、createuser CLI、Bun 构建约定 |
| `ops-planet-sh-startup.md` (已存在) | 运维 | `docs_admin` | 启动性能、AI Provider 镜像、`PLANET_LOAD_ZSHRC_ENV` 深度调优 — 保持不动 |
| 现有 `*-context.md` / `backend-*.md` | 二次开发者 | `docs_developer` | 保持现状 |

`backend-system-service-control.md` 偏后端服务控制原理，**不**和 `ops-runbook.md` 重复 — runbook 讲"运维要敲什么命令"，service-control 讲"后端怎么实现服务管控"。

## manual.md 重写后的章节顺序（客户旅程）

1. **欢迎与入口** — Planet 是什么、几个入口（Earth 公开 / Console 需登录 / Docs / API）
2. **注册账户** — 打开 `/login` → 点"注册" → 填用户名/邮箱/密码 → 收邮件 → 输入 6 位验证码 → 登录
3. **登录与找回密码** — 登录页、忘记密码流程
4. **账户设置** — 修改密码、修改邮箱（需重新验证）、查看权限组、登出
5. **Console 总览** — 左侧菜单结构、各路由用途
6. **配置数据采集器** — `/collection-management?tab=collector_credentials`：选择 collector、连接测试、保存凭证；BarentsWatch / AISStream 两个典型例子
7. **配置 AI 凭证** — `/ai?tab=providers`：默认 provider、模型、Base URL、API Key、本地代理；工具 tab（WebSearch、OCR）
8. **系统设置** — `/settings` 其他子 tab（系统设置、电视直播源、SMTP 邮件）
9. **用户管理（管理员）** — `/users`：创建、删除、改角色、Gatekeeper 权限组
10. **数据探索** — `/datasources`、`/data`、`/bgp`、`/alerts/*`
11. **AI 测试台** — `/ai?tab=playground`
12. **Earth 公开页面** — 现 manual.md 的 Earth 章节原样保留（图层、图例、搜索、位置候选、设置、视角、动捕、巡航、移动端）
13. **Docs 文档站** — 当前 Docs 章节保留（权限组说明）

不再出现：`planet.sh`、`./planet.sh log`、`netsh portproxy`、`source ~/.zshrc && bun run build`、"故障排查顺序"、"开发命令约定"。

## quickstart.md 重写

当前 quickstart 假设读者会自己 `git clone` 然后 `./planet.sh start`，这是给开发者看的。改为：

- 打开管理员给你的 URL
- 注册账号 + 邮箱验证
- 登录后第一次做什么（建议先到 `/collection-management?tab=collector_credentials` 配一个 collector，再到 `/ai` 配模型）
- 看 Earth

部署/开发的 quickstart 内容并入 `ops-runbook.md` 的"首次部署"小节，**不**再单独出 `ops-quickstart.md`，避免新增维护点。

## ops-runbook.md 内容大纲

抽自现 manual.md，重新组织：

1. 首次启动 — `./planet.sh start`、默认账号（`admin/admin123`、`linkong/12345678`，引用 `b15d097b` 引入的 `DEFAULT_LOGIN_USERS`）
2. 启停与按模块重启 — `start/stop/restart` 及 `-b -f -a -d`
3. 健康检查 — `./planet.sh health`
4. 日志 — `./planet.sh log` 及 `-f -b -a`，日志文件路径
5. 创建用户（CLI 兜底）— `./planet.sh createuser`；说明这是公开注册不可用（SMTP 未配置）时的兜底
6. 局域网/WSL 访问 — `--allow-lan`、`netsh portproxy`、防火墙
7. AI Provider 环境变量与构建 — `aiprovider/.env`、`~/.zshrc`、`PLANET_LOAD_ZSHRC_ENV`
8. 故障排查顺序 — 现 manual 末尾那段，原样搬来
9. 开发命令约定 — Bun、`bun run build`、为什么不用 npm

## documentation-coverage-rules.md 增量

在现有"覆盖清单"末尾新增一段：

> **受众分层（强制）**
>
> - 客户/最终用户能在浏览器里完成的操作 → 只写到 `manual.md` / `quickstart.md`
> - 需要 SSH/shell/Docker/`planet.sh`/日志文件路径/端口转发 → 只写到 `ops-runbook.md`（或现有 `ops-*.md`），**禁止**出现在 manual/quickstart
> - 同一动作两种入口（如"创建用户"既能 UI 也能 CLI）→ UI 路径写 manual.md，CLI 路径写 ops-runbook.md，互相用一句话相互引用
> - 新增客户可见 UI 流 → 同时更新 `manual.md` zh+en 与 `docs-content.ts`
> - 新增 ops 命令或脚本 → 只更新 `ops-runbook.md` zh+en

## .claude/commands/docs.md 增量

在 "Step 2 — Decide Scope" 后插一段：

> **Document Audience Routing (Planet)**
>
> 在 Planet 仓库内，写文档前先判断动作的执行者：
>
> - 浏览器 UI 用户 → `docs/technical/{zh,en}/manual.md` / `quickstart.md`
> - shell/容器/运维 → `docs/technical/{zh,en}/ops-runbook.md` 或现有 `ops-*.md`
> - 二次开发者 → 现有 `*-context.md` / `backend-*.md`
>
> 永远不要把 shell 命令、日志路径、Docker 操作写进 manual/quickstart；永远不要把 UI 截图/按钮路径写进 ops-*。

## 关键文件清单

- `docs/technical/zh/manual.md` & `en/manual.md` — 重写
- `docs/technical/zh/quickstart.md` & `en/quickstart.md` — 重写
- `docs/technical/zh/ops-runbook.md` & `en/ops-runbook.md` *(新)*
- `docs/documentation-coverage-rules.md` — 加受众分层段
- `.claude/commands/docs.md` — 加 Document Audience Routing 段
- `frontend/src/pages/Docs/docs-content.ts` — 注册 `ops-runbook` 到 `DOCS_METADATA`（`docs_admin` 组）

## 依赖

manual.md 的"注册账户"和"登录与找回密码"两章需要前后端注册/验证流程已经落地，否则文档会描述不存在的功能。注册功能本身见 [用户公开注册与邮箱验证计划](/home/ray/dev/linkong/planet/docs/plans/user-registration-email-verification-plan.md)。建议先实现注册再重写 manual，避免文档与代码错位。

## 验证

- `rg -n 'planet\.sh' docs/technical/zh/manual.md docs/technical/en/manual.md docs/technical/zh/quickstart.md docs/technical/en/quickstart.md` 应该为空
- `rg -n '注册账户|register|邮箱验证' docs/technical/zh/manual.md docs/technical/en/manual.md` 应该有命中
- `rg -n 'planet\.sh' docs/technical/zh/ops-runbook.md docs/technical/en/ops-runbook.md` 应该有命中
- `frontend/src/pages/Docs/docs-content.ts` 中 `ops-runbook` 出现且分组为 `docs_admin`
- zh/en manual 章节标题对齐（按 `documentation-coverage-rules.md` 现有要求）
- Docs 站点访问：未登录看 manual/quickstart 正常；非 `docs_admin` 用户看不到 `ops-runbook`；`admin` 能看到