文件

T

zhou yang和Claude Opus 5 2bfe308b30 初始导入：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

2026-09-06 18:18:14 +08:00

4.9 KiB

原始文件 Blame 文件历史

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

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

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：

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

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

站点结构上的两个决定

需求文档就是首页，没有另做 landing page —— 这个站只有一篇正文，多一层入口只会多一次点击。
侧边栏是从 需求文档.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 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 之后要单独推一次：

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'

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

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

其它

搜索：本地搜索（不联网）。默认分词器会把整段中文当成一个 token，已在 config 里换成 Intl.Segmenter 分词，中文能搜出来。
矢量框图：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 下会被压成一堆折行。

4.9 KiB 原始文件 Blame 文件历史 Unescape Escape