初始导入：PhoneRail 五路手机直供电源板
原理图/PCB 已在 EasyEDA 里做到 12 页跨页 0 漏接，固件刚完成骨架包 A1。 这次是把已有的一切一次性纳入版本控制，没有改动任何设计内容。 纳入： - 设计与需求文档、PROGRESS.md、小米8 参考原理图 PDF 与追脚脚本 - .claude/ 下的 EasyEDA 桥接工具链与几何/网表缓存（eda-parts.json、 pcb-parts.json、pcb-pads.json、p2-ch1.json 等，是重画各页的唯一事实来源） - 117 张验证截图（本项目所有方向问题都是靠人眼看截图发现的，属于证据不是垃圾） - firmware/ 的 A1 骨架与 site/ 文档站源码 .gitignore 排除：构建产物（firmware/build、host/build、sdkconfig）、 site/node_modules、__pycache__、桥接日志 _bridge.log、脚本自标的 *.stale。 .gitattributes 默认 `* -text`：现有 .py/.json 大多是 CRLF，原样存， 不让 git 重写行尾。唯一例外是 *.sh 强制 LF —— 带 \r 的 shell 脚本 bash 跑不了。 Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01QYuExfgyYa6DzRRcUso8M8
这个提交包含在：
zhou yang
+113
@@ -0,0 +1,113 @@
|
||||
# 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 下会被压成一堆折行。
|
||||
在新工单中引用
屏蔽一个用户