refactor: 清理死代码/提前失败/高内聚低耦合，重写文档

死代码清理： - 删除未使用的 UI 组件 Card.vue / Tag.vue - 移除 app.config.js 死字段 healthTimeoutMs（×2）与 isDev() - 移除 PageShell.vue 死 prop padded（恒为默认值） - 移除 useLocale.js 死导出 isZh/pick/locale - 移除 router/index.js 不可达 try/catch，简化为直接 .map() - 移除 package.json 重复依赖 ical.js（子模块自带） - 移除 i18n 死键 common.notAvailable / common.serviceUnavailable - 移除 vite.config.js 陈旧的 /448 /449 dev proxy（z449 为构建期组件，不走该 URL）提前失败/日志： - useI18nLazy.js switchLocale 加载语言包失败时 console.error 记录（原静默吞错） - modules/index.js 字段不全的模块跳过时 console.warn 告警（原与文档承诺不符、静默跳过） - deploy.sh 补齐 zWhiteBoard / zPDF_package 的 npm install 与子模块初始化（均为构建期组件 import，全新检出时缺少依赖会构建失败）文档对齐现状（无 iframe、无外部域名）： - README 改写为简洁版，修正 iframe/ical.js/子模块数量过时描述 - architecture.md 修正 requiresAlive 示例（同源 /api/health，非外部域名）与「仅白板使用」断言（PDF 也用）；移除已删 padded prop - add-module.md 同步移除 padded、修正 requiresAlive 示例 - submodule-timeTableFix.md 修正 ical.js 归属（子模块自带，非父项目共享） - submodule-zPDF_package.md 子项目数量 3 -> 4 - 新增 submodule-zWhiteBoard.md - readme-fixes.md 记录本次勘误
2026-07-28 11:47:25 +08:00
parent 5b1acbdeb7
commit 25dbceee2d
22 changed files with 216 additions and 168 deletions
--- a/README.md
+++ b/README.md
@@ -9,28 +9,30 @@ Zikai 的作品集主页 -- Vue 3 模块化多项目展示站。浅色极简、
 ```
 mainPage/
 ├── index.html
-├── package.json                  # 含 ical.js / vue-i18n（子模块嵌入时共享）
-├── vite.config.js                # 构建输出到 dist/，再由 npm run deploy rsync 到 /root/html
-├── .gitmodules                   # git submodule：timeTableFix / z449
+├── package.json                  # vue / vue-i18n / vue-router
+├── vite.config.js                # 构建输出到 dist/，再由 npm run deploy rsync 到 /var/www/html
+├── deploy.sh                     # 整体部署：构建 + rsync + Apache 反代 + 重启 zTools2
+├── .gitmodules                   # git submodule：timeTableFix / z449 / zPDF_package / zWhiteBoard
 ├── README.md
-├── docs/                         # 架构 / 新增页签 / 子模块管理文档
+├── docs/                         # 架构 / 新增页签 / 子模块管理 / 部署文档
 ├── public/favicon.svg
-├── third_party/
-│   ├── timeTableFix/             # ★ git submodule：ICS 日程整理器
-│   ├── z449/                     # ★ git submodule：移动游戏项目展示页
-│   └── zPDF_package/             # ★ git submodule：PDF 转换前端（iframe 嵌入 zTools2）
+├── third_party/                  # ★ git submodule 子项目
+│   ├── timeTableFix/             #   ICS 日程整理器（纯前端）
+│   ├── z449/                     #   移动游戏项目展示页（纯前端）
+│   ├── zPDF_package/             #   PDF 转换前端（同源调用 zTools2 /api/pdf/*）
+│   └── zWhiteBoard/              #   共享记事本前端（同源调用 zTools2 /api/wb/* + /api/ws/wb/*）
 └── src/
    ├── main.js                   # 应用入口（挂载 i18n / router / 全局样式）
    ├── App.vue                   # 根布局：顶栏 + 标签导航 + <KeepAlive router-view> + 页脚
-    ├── config/app.config.js      # 集中配置：外部服务 URL（白板地址 / 存活探针等）
+    ├── config/app.config.js      # 集中配置：各服务的同源探针路径（/api/health）与默认参数
    ├── i18n/                     # 国际化（中文同步注入；英文动态 import() 懒加载）
    ├── router/index.js           # 路由表由模块注册表自动生成
    ├── modules/                  # ★ 扩展点：每个页签一个文件夹
    │   ├── index.js              #   注册表（import.meta.glob 约定式收集，带容错）
-    │   ├── mobile-game/          #   移动游戏项目页签（包装 z449 子模块）
-    │   ├── whiteboard/           #   共享记事本页签（iframe 嵌入 + 存活校验）
+    │   ├── mobile-game/          #   移动游戏页签（包装 z449 子模块）
+    │   ├── whiteboard/           #   共享记事本页签（包装 zWhiteBoard 子模块 + 存活校验）
    │   ├── timetable/            #   日程整理页签（包装 timeTableFix 子模块）
-    │   ├── pdf/                  #   PDF 转换页签（iframe 嵌入 zTools2 /pdf + 存活校验）
+    │   ├── pdf/                  #   PDF 转换页签（包装 zPDF_package 子模块 + 存活校验）
    │   └── calendar/             #   隐藏页（仅手动访问 /cqy）
    ├── components/               # 共享组件（TabNav / LanguageSwitcher / ui 基元含 PageShell）
    ├── composables/              # useProjects / useLiveness / useI18nLazy / useLocale
@@ -42,11 +44,11 @@ mainPage/
 | 项 | 要求 |
 |---|---|
 | Node.js | ≥ 18 |
-| Web 服务器 | Apache 2.4（启用 `mod_rewrite`），对外静态服务构建产物 |
+| Web 服务器 | Apache 2.4（启用 `mod_rewrite` / `mod_proxy` / `mod_proxy_wstunnel`），对外静态服务构建产物 |
 | SPA 回退 | history 模式需站点根 `.htaccess` 回退到 `index.html` |
-| 共享记事本 | iframe 嵌入外部服务 `https://f.zikai.wang`（URL 在 `src/config/app.config.js` 配置） |
+| 后端 | zTools2（127.0.0.1:6867），由 Apache 反代 `/api/`；PDF/白板页签依赖其 REST API 与 WebSocket |

-> 子模块（timeTableFix / z449）为构建期组件集成（非 iframe），共享 mainPage 的构建与 KeepAlive 缓存。
+> 四个子模块均为**构建期组件集成（非 iframe）**，共享 mainPage 的构建与 KeepAlive 缓存。各子模块依赖在其自身 `node_modules`，由各自 `package.json` 管理。

 ## 如何使用

@@ -55,21 +57,23 @@ mainPage/
 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo bash -
 sudo apt-get install -y nodejs

-# 2. 取代码（含子模块 timeTableFix / z449）
+# 2. 取代码（含四个子模块）
 git clone --recursive https://git.zikai.wang/zikai/zMainPage.git mainPage
 cd mainPage
 # 若已 clone 但未带子模块：git submodule update --init --recursive
 npm install
 # 子模块需各自安装依赖（构建期编译其 .vue）
-(cd third_party/z449 && npm install)
 (cd third_party/timeTableFix && npm install)
+(cd third_party/z449 && npm install)
+(cd third_party/zPDF_package && npm install)
+(cd third_party/zWhiteBoard && npm install)

-# 3. 构建到 dist/（再由 npm run deploy rsync 同步到 /root/html）
+# 3. 构建到 dist/（再由 npm run deploy rsync 同步到 /var/www/html）
 npm run build

 # 4. 安装并启用 Apache
 sudo apt-get install -y apache2
-sudo a2enmod rewrite
+sudo a2enmod rewrite proxy proxy_http proxy_wstunnel headers
 ```

 站点根放 `.htaccess`（Apache 需 `AllowOverride All`）做 SPA 回退：
@@ -82,7 +86,25 @@ RewriteRule ^ - [L]
 RewriteRule ^ index.html [L]
 ```

-把 `/root/html`（或 `/var/www/html`）设为 `DocumentRoot`，访问站点即可。
+并把 `/var/www/html` 设为 `DocumentRoot`。后端 zTools2 需监听 `127.0.0.1:6867`，并在 vhost 加反代规则（见下方 Apache 配置）。整体部署可用 `./deploy.sh` 一键完成（详见 [`docs/deployment.md`](./docs/deployment.md)）。
+
+### Apache 反代 zTools2（/api/ -> 127.0.0.1:6867）
+
+```apache
+<VirtualHost *:80>
+    DocumentRoot /var/www/html
+    ProxyPreserveHost On
+    # 所有 zTools2 入口（API/静态/探针/WS）统一在 /api/ 下，一条规则即可
+    ProxyPass        /api/   http://127.0.0.1:6867/api/
+    ProxyPassReverse /api/   http://127.0.0.1:6867/api/
+    <Directory /var/www/html>
+        AllowOverride All
+        Require all granted
+    </Directory>
+</VirtualHost>
+```
+
+> WebSocket 走 `/api/ws/wb/{id}`，需 `a2enmod proxy_wstunnel` 以透传 Upgrade 头。

 ## 开发命令

@@ -90,7 +112,7 @@ RewriteRule ^ index.html [L]
 npm install      # 首次安装依赖
 npm run dev      # 开发服务器 http://localhost:5173
 npm run build    # 构建到 dist/
-npm run deploy   # 构建并 rsync 同步到 /root/html
+npm run deploy   # 构建并 rsync 同步到 /var/www/html
 npm run preview  # 本地预览构建产物
 ```

@@ -100,6 +122,7 @@ npm run preview  # 本地预览构建产物
 - [如何新增一个项目页签](./docs/add-module.md)
 - [子项目 timeTableFix 管理（submodule 升级 / 移除）](./docs/submodule-timeTableFix.md)
 - [子项目 z449 管理（submodule + i18n prop 桥接）](./docs/submodule-z449.md)
- [子项目 zPDF_package 管理（submodule + iframe 同源集成）](./docs/submodule-zPDF_package.md)
+- [子项目 zPDF_package 管理（submodule + 同源 API 集成）](./docs/submodule-zPDF_package.md)
+- [子项目 zWhiteBoard 管理（submodule + 同源 API/WS 集成）](./docs/submodule-zWhiteBoard.md)
 - [部署指南（组件独立 / 整体 / 持久化 systemd）](./docs/deployment.md)
 - [README 勘误记录](./docs/readme-fixes.md)