# site —— 需求文档的网页版（VitePress）

把项目根的 **`需求文档.md`** 渲染成一个可搜索、带目录的静态站。

```bash
cd site
npm install          # 首次
npm run dev          # 本地预览  http://localhost:5173/
npm run build        # 产出静态站到 site/.vitepress/dist/
npm run preview      # 预览构建产物
```

## 内容从哪来

**唯一事实来源是 `D:\DCDC\需求文档.md`。**
`npm run dev` / `npm run build` 之前会自动跑 `scripts/sync-docs.mjs`，
把它拷成 `site/docs/index.md`。

> ⚠️ **`site/docs/` 下的文件是生成物，不要在里面改内容** —— 改了会在下次同步时被覆盖。
> 要改内容就改项目根的 `需求文档.md`。

为什么要拷而不是让 VitePress 直接指向项目根：`srcDir` 指到 `D:\DCDC` 之后，
那里的 `.md` 编译出的虚拟模块要 `import 'vue/server-renderer'`，而 `node_modules`
在 `site/` 下（是子目录不是父目录），Rollup 解析不到，构建会直接失败。

## 想再加一篇（比如设计文档 / PROGRESS）

改 `scripts/sync-docs.mjs` 里的 `PAGES`：

```js
const PAGES = [
  ['需求文档.md', 'index.md'],
  ['五路直供电源板设计.md', 'design.md']   // 新增
]
```

再在 `.vitepress/config.mts` 的 `themeConfig.nav` / `sidebar` 里加一项即可。
（设计文档有 432 KB / 6900 行，会是一个很长的单页，建议单独放一条 nav。）

## 站点结构上的两个决定

1. **需求文档就是首页**，没有另做 landing page —— 这个站只有一篇正文，
   多一层入口只会多一次点击。
2. **侧边栏是从 `需求文档.md` 的 `##` 标题现算的**，不是手写的常量。
   正文加一章，侧边栏自动就有，不会漏。

代价是 `config.mts` 里得自己实现一份和 VitePress 一致的 `slugify()`
（`@mdit-vue/shared` 打包在 vitepress 内部，外面 import 不到）。
两边只要差一个字符，侧边栏链接就会**静默跳空**——页面照样打开，只是不滚动，肉眼很难发现。
所以 `npm run build` 之后会自动跑 `scripts/check-anchors.mjs`，
拿构建产物里真实的标题 `id` 对一遍生成的锚点，对不上就让构建失败。

## 部署（home 服务器）

线上地址：**<http://phonerail.home.example:7755/>** —— 挂在统一门户后面，要先登录。

更新内容只要一条命令（在 Git Bash 里，从 `site/` 跑）：

```bash
bash deploy/deploy.sh
```

它做三件事：`npm run build` → `tar over ssh` 同步到 `/root/phonerail-docs` → 回读验证。

| 项 | 值 |
|---|---|
| 静态文件 | `10.5.5.13:/root/phonerail-docs` |
| nginx | `/etc/nginx/conf.d/phonerail-docs.conf`（源在 `deploy/nginx-phonerail-docs.conf`） |
| 监听 | **`127.0.0.1:7757`** —— 只给门户反代用 |
| 门户注册 | 应用表 `key=phonerail` / `port=7757`，授权 admin + staff + viewer |

> ⚠️ **7757 故意只绑 loopback。** 这台机器实测是大范围 / DMZ 转发，绑 `0.0.0.0` 的端口
> 默认公网可达，而应用端口那一路是**不带门禁**的 —— 现有 12 个应用就是这个状态。
> 绑 loopback 之后，唯一入口只剩门户，代价是**内网直连 `10.5.5.13:7757` 也进不来**。

改了 `deploy/nginx-phonerail-docs.conf` 之后要单独推一次：

```bash
scp deploy/nginx-phonerail-docs.conf 10.5.5.13:/etc/nginx/conf.d/phonerail-docs.conf
ssh 10.5.5.13 'nginx -t && systemctl reload nginx'
```

改了应用注册信息（改名 / 换端口 / 增删应用）走门户 → 应用管理，然后：

```bash
ssh 10.5.5.13 'python3 /root/portal/deploy/gen-vhosts.py --write'
```

## 其它

- **搜索**：本地搜索（不联网）。默认分词器会把整段中文当成一个 token，
  已在 config 里换成 `Intl.Segmenter` 分词，中文能搜出来。
- **矢量框图**：markdown 里写成

  ````markdown
  ```diagram=system
  （这里仍然是 ASCII 框图）
  ```
  ````

  的代码块，站点上会被替换成 `site/diagrams/<名字>.svg` 的**内联 SVG**（当前三张：
  `system` / `layers` / `links`）。内联而不是 `<img>`，是为了让 SVG 用页面的 CSS 变量
  跟着明暗主题走。找不到对应 svg 时**退回渲染成普通代码块**，站点不会崩。

  > ⚠️ **ASCII 与 SVG 是两份，改框图内容要改两处。**
  > 保留 ASCII 是有意的：它既是 GitHub / 编辑器里的可读降级，也是 SVG 的 alt 内容。
  > 颜色一律用 `custom.css` 里的 `--dg-*` 变量与 `.dg-box` / `.dg-key` 这类 class，
  > **SVG 文件里不要写死颜色**，否则深色主题下会瞎。

- **告警块**：正文里以 `⚠️` / `❌` 开头的引用块会渲染成橙色警告卡片，
  `✅` 开头的渲染成绿色。这个转换在 `config.mts` 的 markdown 插件里做，
  **不改 markdown 源文件** —— 所以原稿在 GitHub / 编辑器里看仍然正常。
- **版心加宽到 1080px**：文档里 5~6 列的需求表在默认的 688px 下会被压成一堆折行。