release: bump version to 0.42.0

docs/plans/frontend-public-docs-site-plan.md

@@ -0,0 +1,486 @@
+# Frontend Public Docs Site Plan
+
+## 目标
+
+新增一个公开访问的 `/docs` 页面，作为 Planet 的开发设计文档与使用手册入口。
+
+这个页面应类似常见开源软件文档站：
+
+- 不需要登录即可访问
+- 与 `/earth` 和 admin 后台平级，但视觉和信息架构独立
+- 直接整理并展示仓库内 `docs/technical` 的 Markdown 文档
+- 支持搜索、分类导航、文档目录和内部跳转
+- 让 `docs/technical` 继续作为文档真源，避免页面内容和仓库文档漂移
+
+## 非目标
+
+本阶段不做：
+
+- 后端全文搜索服务
+- 数据库驱动的 CMS
+- 独立文档构建系统，例如 Docusaurus / VitePress
+- 每篇文档单独手写 React 页面
+- 用户权限、编辑器、在线保存或评论功能
+- 把 `docs/plans`、`docs/deprecated` 全量公开为正式手册
+
+后续可以再决定是否把 plans / deprecated 做成独立的“路线图 / 历史归档”分区。
+
+## 技术路线
+
+### 推荐方案：Markdown 直接渲染
+
+使用 Vite 在前端构建阶段直接加载 `docs/technical/**/*.md`：
+
+```ts
+const modules = import.meta.glob('../../../docs/technical/**/*.md', {
+  query: '?raw',
+  import: 'default',
+})
+```
+
+这样每篇 Markdown 文件仍然留在仓库文档目录中，`/docs` 页面只是读取、索引和渲染这些文档。
+
+当前项目已经满足主要前提：
+
+- 前端使用 Vite + React
+- `frontend/vite.config.ts` 已配置 `server.fs.allow: ['..']`
+- 已有 `MarkdownRenderer` 可作为基础
+- `docs/technical` 文档数量较少，前端本地搜索足够
+
+### 不推荐方案：每篇文档单独写 React
+
+不建议把每篇文档重写成 `.tsx` 页面，因为：
+
+- 文档会出现两份真源
+- 修改技术文档时还要同步 UI 页面
+- 计划文档、技术上下文、变量表这类内容天然适合 Markdown
+- 后续新增文档的成本会变高
+
+只有当某篇文档需要强交互演示、实时图表或复杂 UI 时，才考虑给该文档补充一个 React 组件扩展。
+
+## 信息架构
+
+### 公开路由
+
+新增：
+
+- `/docs`
+- `/docs/:slug`
+
+路由行为：
+
+- `/docs` 默认打开 `docs/technical/README.md`，或打开人工指定的首页文档
+- `/docs/:slug` 打开对应技术文档
+- 未找到文档时显示 docs 专属 404，而不是跳回 admin
+- `/docs` 加入 `App.tsx` 的公开路由白名单
+
+### 文档分类
+
+将 `docs/technical` 中的现有文档整理进以下分组：
+
+#### Overview
+
+- `README.md`
+
+#### Earth
+
+- `earth-frontend-context.md`
+- `earth-layer-style-reference.md`
+- `earth-render-layer-order.md`
+- `earth-satellite-footprint-policy.md`
+- `earth-bgp-context.md`
+- `earth-news-live-streams-collector-format.md`
+
+#### Frontend
+
+- `frontend-admin-frontend-context.md`
+- `frontend-layout-guidelines.md`
+
+#### Backend
+
+- `backend-collectors.md`
+- `backend-system-service-control.md`
+
+#### Agents
+
+- `agents-aiprovider.md`
+
+#### Ops
+
+- `ops-docker-compose-buildx-upgrade.md`
+
+### 页面布局
+
+桌面端：
+
+- 顶部：产品名、搜索框、当前文档标题
+- 左侧：文档分组导航
+- 中间：Markdown 正文
+- 右侧：当前文档目录，也就是 h2 / h3 anchors
+
+移动端：
+
+- 顶部固定搜索入口
+- 导航折叠为抽屉或下拉
+- 正文单列显示
+- 当前文档目录折叠为“本文目录”
+
+视觉风格：
+
+- 像开源软件 docs 页面，清晰、安静、可长时间阅读
+- 不复用 admin 后台的重操作感布局
+- 不做 Earth 的沉浸式深色 HUD 风格
+- 优先阅读性、扫描效率和代码/表格可读性
+
+## 前端实现设计
+
+### 文件结构
+
+建议新增：
+
+```text
+frontend/src/pages/Docs/
+  Docs.tsx
+  docs-content.ts
+  docs-search.ts
+  docs-slugs.ts
+  Docs.css
+```
+
+可选拆分：
+
+```text
+frontend/src/pages/Docs/components/
+  DocsSidebar.tsx
+  DocsSearch.tsx
+  DocsToc.tsx
+  DocsMarkdown.tsx
+```
+
+如果初版代码量不大，可以先保持在 `Docs.tsx` + 少量 helper 文件中，避免过度拆分。
+
+### 文档注册表
+
+创建一个 registry，负责将 Markdown 文件路径映射为文档元信息：
+
+```ts
+interface DocsEntry {
+  slug: string
+  path: string
+  title: string
+  group: string
+  order: number
+  loader: () => Promise<string>
+}
+```
+
+slug 规则：
+
+- `docs/technical/README.md` -> `overview`
+- `docs/technical/earth-layer-style-reference.md` -> `earth-layer-style-reference`
+- 只暴露稳定 slug，不暴露本机绝对路径
+
+标题规则：
+
+- 优先读取 Markdown 第一个 `# heading`
+- 没有 h1 时用人工 registry title
+- 再 fallback 到文件名转换标题
+
+### Markdown 渲染
+
+初版可以复用现有：
+
+- [frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx](/home/ray/dev/linkong/planet/frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx)
+
+但建议增强或包装为 docs 专用渲染：
+
+- heading 生成稳定 `id`
+- 右侧 TOC 使用同一套 heading 解析结果
+- 内部 Markdown 链接转换为 `/docs/:slug`
+- 外部链接保留 `target="_blank" rel="noreferrer"`
+- 表格横向滚动
+- 代码块保留等宽字体和语言标记
+- 支持 GitHub 风格的相对文档链接
+
+内部链接转换示例：
+
+- `earth-render-layer-order.md` -> `/docs/earth-render-layer-order`
+- `./earth-layer-style-reference.md` -> `/docs/earth-layer-style-reference`
+- `/home/ray/dev/linkong/planet/docs/technical/foo.md` -> `/docs/foo`
+
+对非 `docs/technical` 的链接：
+
+- 初版可保留原始链接文本
+- 或显示为不可跳转的 repo path
+- 后续再扩展为跨文档区导航
+
+### 搜索
+
+初版使用纯前端本地搜索。
+
+索引字段：
+
+- title
+- slug
+- group
+- headings
+- markdown 正文纯文本
+
+搜索策略：
+
+- 页面首次加载后异步加载所有 `docs/technical` Markdown
+- 生成内存索引
+- 用户输入时本地过滤
+- 简单打分即可：
+  - 标题命中权重最高
+  - heading 命中其次
+  - 文件名 / slug 命中其次
+  - 正文命中最低
+
+搜索结果展示：
+
+- 文档标题
+- 分组
+- 命中的 heading 或正文摘要
+- 点击跳转到文档
+
+当前只有 13 篇文档，不需要 Lunr、Fuse 或后端搜索。后续文档数量显著增长时，再考虑引入轻量搜索库。
+
+### 路由接入
+
+修改：
+
+- [frontend/src/App.tsx](/home/ray/dev/linkong/planet/frontend/src/App.tsx)
+
+新增 lazy import：
+
+```ts
+const Docs = lazy(() => import('./pages/Docs/Docs'))
+```
+
+公开路由：
+
+```ts
+const publicPaths = new Set(['/', '/earth', '/docs'])
+```
+
+注意：`/docs/:slug` 不能只用精确匹配 `Set`。
+
+建议改为：
+
+```ts
+const isPublicRoute =
+  window.location.pathname === '/' ||
+  window.location.pathname === '/earth' ||
+  window.location.pathname === '/docs' ||
+  window.location.pathname.startsWith('/docs/')
+```
+
+新增 routes：
+
+```tsx
+<Route path="/docs" element={<Docs />} />
+<Route path="/docs/:slug" element={<Docs />} />
+```
+
+### 样式
+
+建议独立 `Docs.css`，不依赖 admin 页面布局。
+
+核心样式要求：
+
+- 文档正文最大宽度控制在适合阅读的范围
+- 表格横向滚动，不撑破布局
+- 代码块横向滚动
+- 左侧导航固定或 sticky
+- 右侧 TOC sticky
+- 移动端隐藏右侧 TOC，导航折叠
+- 搜索结果浮层或独立面板不遮挡正文阅读
+
+注意：
+
+- 不做营销 hero
+- 不做卡片堆叠式首页
+- 首页第一屏应直接是文档入口和内容，而不是宣传页
+
+## 实施阶段
+
+### Phase 1：基础文档站
+
+目标：
+
+- `/docs` 可公开访问
+- 能看到 `docs/technical` 文档列表
+- 能打开每篇 Markdown
+- 能基本渲染标题、段落、列表、代码块、表格
+
+任务：
+
+- 新增 `Docs` 页面
+- 新增 docs registry
+- 接入 Vite raw Markdown loading
+- 接入 `/docs` 和 `/docs/:slug`
+- 加入公开路由白名单
+- 初版 CSS 布局
+
+验收：
+
+- 未登录访问 `/docs` 不跳转登录
+- `/docs/earth-layer-style-reference` 可打开样式参考文档
+- `/docs/backend-collectors` 可打开后端采集器文档
+- 构建通过：`source ~/.zshrc && bun run build`
+
+### Phase 2：搜索与 TOC
+
+目标：
+
+- 支持本地搜索所有 technical 文档
+- 当前文档右侧显示目录
+- 搜索结果可跳转
+
+任务：
+
+- 实现 heading parser
+- 实现 TOC 组件
+- 实现 search index
+- 搜索结果显示文档标题、分组和摘要
+- 当前文档标题与 active nav 高亮
+
+验收：
+
+- 搜索 `Fresnel` 能找到 Earth 图层样式文档
+- 搜索 `collector` 能找到 backend collectors
+- 点击搜索结果进入对应文档
+- 右侧 TOC 点击后滚动到对应 heading
+
+### Phase 3：链接清理与文档体验
+
+目标：
+
+- Markdown 内部链接在 docs 站内自然跳转
+- 长表格、代码块、绝对路径链接的显示更友好
+
+任务：
+
+- 转换 `docs/technical/*.md` 相对链接
+- 转换 repo 内 technical 文档绝对路径
+- 外链新窗口打开
+- 文件路径链接以代码样式显示
+- 增强空状态和 404
+
+验收：
+
+- 从 `docs/technical/README.md` 点击 technical 文档链接进入 `/docs/:slug`
+- 不支持的 repo 内路径不会导致前端崩溃
+- 外部链接行为正常
+
+### Phase 4：文档内容整理
+
+目标：
+
+- `docs/technical` 的首页适合作为公开手册入口
+- 每篇文档标题、摘要和分类清晰
+
+任务：
+
+- 检查每篇文档是否有唯一 h1
+- 给 README 补公开手册导览
+- 必要时补文档摘要
+- 保持文档内容仍然服务开发维护，不改成营销语气
+
+验收：
+
+- `/docs` 首页能说明各技术文档用途
+- 左侧分类和 README 内容一致
+- 没有明显重复、过期或找不到的主入口
+
+## 需要改动的文件
+
+预计新增：
+
+- `frontend/src/pages/Docs/Docs.tsx`
+- `frontend/src/pages/Docs/Docs.css`
+- `frontend/src/pages/Docs/docs-content.ts`
+- `frontend/src/pages/Docs/docs-search.ts`
+
+预计修改：
+
+- `frontend/src/App.tsx`
+- `frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx` 或新增 docs 专用 wrapper
+- `docs/technical/README.md`
+
+可选修改：
+
+- `frontend/src/index.css`，只放全局极少量 docs shell reset 时才需要
+- `docs/CHANGELOG.md`，实施完成后记录
+- `docs/version-history.md`，若进入版本发布流程再更新
+
+## 风险与注意事项
+
+### 构建路径风险
+
+Vite 从 `frontend/src` 读取 `../../../docs/technical/**/*.md` 时，需要确认开发和生产构建都可解析。
+
+缓解：
+
+- 使用相对路径 glob
+- 构建验证必须跑 `source ~/.zshrc && bun run build`
+- 不使用运行时 `fetch('/docs/...')` 读取仓库文件，避免生产环境缺文件
+
+### Markdown 能力不足
+
+现有 `MarkdownRenderer` 是轻量实现，可能不完整支持所有 GitHub Markdown。
+
+缓解：
+
+- 初版优先覆盖当前 `docs/technical` 实际用到的语法
+- 若后续需要脚注、嵌套列表、复杂代码高亮，再考虑引入 `react-markdown` 等依赖
+
+### Bundle 体积
+
+把所有 Markdown 打进前端 bundle 会增加体积。
+
+当前文档数量少，风险可接受。
+
+缓解：
+
+- 使用 lazy page chunk
+- Markdown loader 保持异步
+- 搜索索引在 `/docs` 页面内初始化，不影响 `/earth` 和 admin 首屏
+
+### 公开内容边界
+
+`docs/technical` 会被公开展示，需要避免包含密钥、内部机器地址、临时方案或不应公开的操作细节。
+
+缓解：
+
+- 实施前快速审阅 `docs/technical`
+- 暂不公开 `docs/plans` 和 `docs/deprecated`
+- 以后如需公开更多文档，先建立 allowlist
+
+## 验收清单
+
+- `/docs` 未登录可访问
+- `/docs/:slug` 未登录可访问
+- `/docs` 不影响 `/earth`
+- 未登录访问 admin 仍然跳登录
+- 左侧导航包含所有 `docs/technical` 文档
+- 文档按 Overview / Earth / Frontend / Backend / Agents / Ops 分类
+- Markdown 表格正常显示并可横向滚动
+- 代码块正常显示并可横向滚动
+- 搜索可搜索标题、heading 和正文
+- 搜索结果点击可跳转
+- 当前文档 TOC 可跳转
+- 不存在的 slug 显示 docs 404
+- `source ~/.zshrc && bun run build` 通过
+
+## 后续增强
+
+- 给文档页面增加复制 heading 链接按钮
+- 给代码块增加复制按钮
+- 增加“上一页 / 下一页”导航
+- 增加最近更新信息
+- 从 git metadata 读取文档更新时间
+- 引入轻量全文搜索库
+- 支持 plans / deprecated 独立分区
+- 增加页面内反馈入口