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 记录本次勘误
feat: 白板页签从 iframe 改为构建期组件挂载
2026-07-28 11:57:32 +08:00 · 2026-07-28 10:39:24 +08:00 · 2026-07-27 17:38:16 +08:00 · 2026-07-27 17:35:40 +08:00 · 2026-07-27 17:14:07 +08:00 · 2026-07-27 15:44:49 +08:00
51 changed files with 1093 additions and 1507 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,8 @@
 # 依赖
 node_modules/
-# 子模块 timeTableFix 的依赖（node_modules 已被上一条覆盖，此条仅作显式说明）
+# 子模块的依赖（node_modules 已被上一条覆盖，以下仅作显式说明）
 third_party/timeTableFix/node_modules/
+third_party/z449/node_modules/

 # 构建产物（输出到 /root/html，不入库）
 dist/
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,3 +1,12 @@
 [submodule "third_party/timeTableFix"]
 	path = third_party/timeTableFix
 	url = https://git.zikai.wang/zikai/timeTableFix.git
+[submodule "third_party/z449"]
+	path = third_party/z449
+	url = https://git.zikai.wang/zikai/z449.git
+[submodule "third_party/zPDF_package"]
+	path = third_party/zPDF_package
+	url = https://git.zikai.wang/zikai/zPDF_package.git
+[submodule "third_party/zWhiteBoard"]
+	path = third_party/zWhiteBoard
+	url = https://git.zikai.wang/zikai/zWhiteBoard.git
--- a/README.md
+++ b/README.md
@@ -1,73 +1,79 @@
 # mainPage · 作品集主页

-Zikai 的作品集主页 -- Vue 3 模块化多项目展示站。浅色极简、中英双语（英文按需懒加载）。
-每个项目页签是一个独立「模块」，由注册表自动生成页签与路由 -- 新增/删除页签只增删一个文件夹，互不影响。
+Zikai 的作品集主页 -- Vue 3 模块化多项目展示站。浅色极简、中英双语（英文按需懒加载）。每个项目页签是一个独立「模块」，由注册表自动生成页签与路由 -- 新增/删除页签只增删一个文件夹，互不影响。

 > 架构细节、新增页签指南、子项目管理见 [`docs/`](./docs/)。

---
-
 ## 项目结构

 ```
 mainPage/
 ├── index.html
-├── package.json                  # 含 ical.js（timeTableFix 依赖）
-├── vite.config.js                # 构建输出到 /root/html（emptyOutDir=false，不清空既有文件）
-├── .gitmodules                   # git submodule：third_party/timeTableFix
+├── 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 日程整理器，独立仓库
+├── 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/          #   移动游戏项目页签
-    │   ├── whiteboard/           #   共享记事本页签（iframe 嵌入 + 存活校验）
-    │   ├── timetable/            #   日程整理页签（构建期 import 子模块 App.vue）
+    │   ├── mobile-game/          #   移动游戏页签（包装 z449 子模块）
+    │   ├── whiteboard/           #   共享记事本页签（包装 zWhiteBoard 子模块 + 存活校验）
+    │   ├── timetable/            #   日程整理页签（包装 timeTableFix 子模块）
+    │   ├── pdf/                  #   PDF 转换页签（包装 zPDF_package 子模块 + 存活校验）
    │   └── calendar/             #   隐藏页（仅手动访问 /cqy）
    ├── components/               # 共享组件（TabNav / LanguageSwitcher / ui 基元含 PageShell）
    ├── composables/              # useProjects / useLiveness / useI18nLazy / useLocale
    └── styles/                   # variables.css（主题令牌）+ base.css
 ```

-## 依赖的基础设施
+## 外部依赖

 | 项 | 要求 |
 |---|---|
-| Node.js | ≥ 18（开发于 18.19 + npm 9.2） |
-| Web 服务器 | Apache 2.4（启用 `mod_rewrite`），对外静态服务 `/root/html` |
-| SPA 回退 | history 模式需站点根 `.htaccess` 回退到 `index.html`（见下） |
+| Node.js | ≥ 18 |
+| Web 服务器 | Apache 2.4（启用 `mod_rewrite` / `mod_proxy` / `mod_proxy_wstunnel`），对外静态服务构建产物 |
+| SPA 回退 | history 模式需站点根 `.htaccess` 回退到 `index.html` |
+| 后端 | zTools2（127.0.0.1:6867），由 Apache 反代 `/api/`；PDF/白板页签依赖其 REST API 与 WebSocket |

-> 共享记事本页签 iframe 嵌入外部服务（`https://f.zikai.wang/wb/share`），URL 在 `src/config/app.config.js` 配置。
-> 日程整理页签（timeTableFix）经 git submodule 构建期集成（非 iframe），详见 [`docs/submodule-timeTableFix.md`](./docs/submodule-timeTableFix.md)。
+> 四个子模块均为**构建期组件集成（非 iframe）**，共享 mainPage 的构建与 KeepAlive 缓存。各子模块依赖在其自身 `node_modules`，由各自 `package.json` 管理。

-## Ubuntu 从 0 安装
+## 如何使用

 ```bash
 # 1. 安装 Node.js 18
 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo bash -
 sudo apt-get install -y nodejs

-# 2. 取代码（含子模块 timeTableFix）
+# 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/timeTableFix && npm install)
+(cd third_party/z449 && npm install)
+(cd third_party/zPDF_package && npm install)
+(cd third_party/zWhiteBoard && npm install)

-# 3. 构建（产物输出到 /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 回退：
@@ -80,14 +86,33 @@ 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 头。

 ## 开发命令

 ```bash
 npm install      # 首次安装依赖
 npm run dev      # 开发服务器 http://localhost:5173
-npm run build    # 构建到 /root/html
+npm run build    # 构建到 dist/
+npm run deploy   # 构建并 rsync 同步到 /var/www/html
 npm run preview  # 本地预览构建产物
 ```

@@ -96,3 +121,8 @@ npm run preview  # 本地预览构建产物
 - [架构（模块注册 / PageShell / KeepAlive / 存活校验）](./docs/architecture.md)
 - [如何新增一个项目页签](./docs/add-module.md)
 - [子项目 timeTableFix 管理（submodule 升级 / 移除）](./docs/submodule-timeTableFix.md)
+- [子项目 z449 管理（submodule + i18n prop 桥接）](./docs/submodule-z449.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)
--- a/deploy.sh
+++ b/deploy.sh
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# 整体部署：构建并部署 zMainPage（含子模块）+ zTools2（后端）到生产环境。
+#
+# 生产拓扑：
+#   Apache(:80) -> 静态文件 /var/www/html（zMainPage 构建产物）
+#              -> 反代 /api/ 到 zTools2(127.0.0.1:6867)（页面/静态/探针/WS/API 全在 /api/ 下）
+#   zTools2(127.0.0.1:6867) -> MySQL(3306) + uploads/ 磁盘
+#
+# 前提：zMainPage 与 zTools2 在同一主机（zMainPage 父项目，zTools2 同级目录）。
+# 用法：./deploy.sh [--no-restart]  （--no-restart 仅更新文件不重启 zTools2）
+set -euo pipefail
+
+cd "$(dirname "$0")"
+ROOT="$(pwd)"
+RESTART=1
+[[ "${1:-}" == "--no-restart" ]] && RESTART=0
+
+# 兄弟项目路径：zTools2 与 zMainPage 同级
+ZTOOLS2="../zTools2"
+ZTOOLS2_DIR="$(cd "$ZTOOLS2" 2>/dev/null && pwd)" || {
+  echo "未找到 zTools2（期望在 $ZTOOLS2）；请确保与 zMainPage 同级目录" >&2
+  exit 1
+}
+
+WEB_ROOT="${WEB_ROOT:-/var/www/html}"
+
+echo "==> [1/4] 构建 zMainPage（含子模块）"
+# 子模块依赖需各自安装（构建期编译其 .vue）
+[[ -d third_party/timeTableFix/node_modules ]] || (cd third_party/timeTableFix && npm install)
+[[ -d third_party/z449/node_modules ]] || (cd third_party/z449 && npm install)
+[[ -d third_party/zPDF_package/node_modules ]] || (cd third_party/zPDF_package && npm install)
+[[ -d third_party/zWhiteBoard/node_modules ]] || (cd third_party/zWhiteBoard && npm install)
+# 确保子模块源码存在（全新检出时）
+[[ -d third_party/zPDF_package/src ]] || git submodule update --init third_party/zPDF_package
+[[ -d third_party/zWhiteBoard/src ]] || git submodule update --init third_party/zWhiteBoard
+npm run build
+
+echo "==> [2/4] 部署 zMainPage 构建产物到 $WEB_ROOT"
+sudo mkdir -p "$WEB_ROOT/js/mainPage" "$WEB_ROOT/css/mainPage"
+sudo rsync -a --delete dist/js/mainPage/ "$WEB_ROOT/js/mainPage/"
+sudo rsync -a --delete dist/css/mainPage/ "$WEB_ROOT/css/mainPage/"
+sudo rsync -a dist/index.html "$WEB_ROOT/index.html"
+[[ -f dist/favicon.svg ]] && sudo rsync -a dist/favicon.svg "$WEB_ROOT/favicon.svg"
+# SPA 回退 .htaccess（history 模式）
+cat > /tmp/zmainpage_htaccess <<'HT'
+RewriteEngine On
+RewriteCond %{REQUEST_FILENAME} -f [OR]
+RewriteCond %{REQUEST_FILENAME} -d
+RewriteRule ^ - [L]
+RewriteRule ^ index.html [L]
+HT
+sudo cp /tmp/zmainpage_htaccess "$WEB_ROOT/.htaccess"
+
+echo "==> [3/4] 配置 Apache 反代（zMainPage -> zTools2）"
+# 确保 proxy / rewrite / headers / proxy_wstunnel（WebSocket）模块启用
+sudo a2enmod proxy proxy_http proxy_wstunnel rewrite headers >/dev/null 2>&1 || true
+# 写入 vhost 配置（仅当不存在时，避免覆盖已有 HTTPS 配置）
+VHOST="/etc/apache2/sites-available/zmainpage.conf"
+if [[ ! -f "$VHOST" ]]; then
+  sudo tee "$VHOST" >/dev/null <<'VH'
+<VirtualHost *:80>
+    DocumentRoot /var/www/html
+    # zTools2 反代：所有入口（页面/静态/探针/WS/API）统一在 /api/ 下，一条规则即可；
+    # WebSocket 走 /api/ws/wb/{id}，由 proxy_wstunnel 透传 Upgrade 头
+    ProxyPreserveHost On
+    ProxyPass        /api/   http://127.0.0.1:6867/api/
+    ProxyPassReverse /api/   http://127.0.0.1:6867/api/
+    # SPA 回退：非文件非目录的请求回退到 index.html
+    <Directory /var/www/html>
+        AllowOverride All
+        Require all granted
+    </Directory>
+</VirtualHost>
+VH
+  sudo a2dissite 000-default >/dev/null 2>&1 || true
+  sudo a2ensite zmainpage >/dev/null
+  echo "    已写入 $VHOST 并启用"
+else
+  echo "    $VHOST 已存在，跳过（如需更新请手动编辑）"
+fi
+sudo systemctl reload apache2
+
+echo "==> [4/4] 重启 zTools2 后端"
+if [[ $RESTART -eq 1 ]]; then
+  (cd "$ZTOOLS2_DIR" && ./stop.sh >/dev/null 2>&1 || true)
+  (cd "$ZTOOLS2_DIR" && ./start.sh)
+else
+  echo "    --no-restart：跳过 zTools2 重启"
+fi
+
+echo
+echo "部署完成。"
+echo "  - zMainPage: http://localhost（Apache :80，静态文件 + SPA）"
+echo "  - zTools2:   http://127.0.0.1:6867（经 Apache 反代 /api/）"
+echo "  - PDF 页签:  http://localhost -> 构建期组件嵌入，同源调用 zTools2 /api/pdf/*"
--- a/docs/add-module.md
+++ b/docs/add-module.md
@@ -41,7 +41,6 @@ const { t } = useLocale()
 PageShell props：
 - `titleKey`：i18n 键，渲染页面标题；不传则无标题
 - `fluid`：true 突破 1080px 全宽（如日历页）
- `padded`：false 去掉默认上下间距（页面自管布局时用）
 - `#actions` 具名插槽：标题旁的操作区（如白板切换表单）

 ### 3. 加 i18n 文案
@@ -80,7 +79,7 @@ export default { id: 'secret', tabKey: 'tabs.secret', order: 99, hidden: true, c
 import { healthUrl } from '../../config/app.config.js'
 export default {
  id: 'my-service', tabKey: 'tabs.myService', order: 5,
-  requiresAlive: 'https://example.com/health',  // 存活探针 URL
+  requiresAlive: healthUrl('myService'),  // 同源探针 URL（/api/health）
  component: () => import('./MyService.vue')
 }
 ```
@@ -97,7 +96,10 @@ export default { id: 'my-project', tabKey: 'tabs.myProject', order: 4, param: 'i

 ### 集成独立子项目（git submodule）

-参照 `timetable` 模块：建 mainPage 侧包装器组件 import 子项目 `App.vue`，套 `PageShell`，包装器持有 `defineOptions({ name })`。子项目保持纯净。详见 [submodule-timeTableFix.md](./submodule-timeTableFix.md)。
+参照 `timetable` 模块（无 i18n 子项目）或 `mobile-game` 模块（带独立 i18n 的子项目）：建 mainPage 侧包装器组件 import 子项目 `App.vue`，包装器持有 `defineOptions({ name })`。子项目保持纯净。
+
+- **无 i18n 的子项目**（如 timeTableFix）：包装器直接 import App.vue 即可。
+- **带独立 i18n 的子项目**（如 z449）：子项目 App.vue 接 `:locale` prop，包装器把 mainPage 当前语言透传（`<Z449App :locale="locale" />`），子项目 `watch` 同步到自己的 i18n 实例。详见 [submodule-z449.md](./submodule-z449.md)。

 ## 元数据字段速查

--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -13,7 +13,7 @@ export default {
  component: () => import('./Whiteboard.vue'),   // 必填：懒加载组件（函数形式，独立 chunk）
  order: 2,                                      // 可选：页签排序，缺省 999（排在显式页签之后）
  hidden: true,                                  // 可选：不在导航显示，但 URL 访问后保持可见（如 cqy）
-  requiresAlive: 'https://f.zikai.wang/health',  // 可选：存活探针 URL，服务失活则隐藏页签并卸载组件
+  requiresAlive: healthUrl('whiteboard'),        // 可选：存活探针 URL（同源 /api/health），服务失活则隐藏页签并卸载组件
  param: 'boardId',                              // 可选：路由参数名，生成 /<id>/:<param>? 子路径
 }
 ```
@@ -39,7 +39,7 @@ export default {
 `src/components/ui/PageShell.vue` 是可复用的页面外壳组件，统一所有页面的：

 - **容器宽度**：默认复用全局 `.container`（`max-width: 1080px`，居中，左右 `padding`）；`fluid` 变体突破限制全宽（如日历页）
- **垂直节奏**：`padding: var(--space-xl) 0 var(--space-2xl)`；`padded: false` 可关
+- **垂直节奏**：`padding: var(--space-xl) 0 var(--space-2xl)`
 - **标题**：`titleKey` prop -> i18n 文案，渲染为 `<h1>`
 - **操作区**：`#actions` 具名插槽，放在标题旁（如白板的切换白板表单）

@@ -52,8 +52,19 @@ export default {
 - `keepInclude` 是模块 id 列表，默认包含所有模块。
 - 声明了 `requiresAlive` 的模块，当存活探测为 `down` 时移出名单 -> 组件卸载；恢复 `up` 后重新纳入。
 - **匹配约定**：KeepAlive 按组件 `name` 匹配，因此每个模块组件需 `defineOptions({ name: <模块 id> })`。
-  - 内置模块（mobile-game/whiteboard/calendar）直接在组件内声明。
-  - 子模块集成（timetable）由 mainPage 侧包装器 `Timetable.vue` 持有 name，子项目自身不持 name（保持纯净）。
+  - 内置模块（whiteboard/calendar）直接在组件内声明。
+  - 子模块集成（timetable/mobile-game）由 mainPage 侧包装器持有 name，子项目自身不持 name（保持纯净）。
+
+## 子模块集成（git submodule + 构建期组件）
+
+部分页签由独立仓库的子项目经 git submodule 集成，mainPage 侧用包装器 import 子项目 `App.vue` 作为路由组件（非 iframe），共享构建与 KeepAlive 缓存：
+
+- **timeTableFix**（`third_party/timeTableFix`，日程整理页签）：自带独立 `vue-i18n` 实例与中英 locale 文案。经 `:locale` prop 桥接父项目语言。详见 [submodule-timeTableFix.md](./submodule-timeTableFix.md)。
+- **z449**（`third_party/z449`，移动游戏页签）：自带独立 `vue-i18n` 实例与 locale 文案。mainPage 包装器把当前语言经 `:locale` prop 透传，子项目 `App.vue` `watch` 该 prop 同步到自己的 i18n 实例，从而跟随父项目语言开关响应式切换（不共享 messages，仅同步 locale 值）。详见 [submodule-z449.md](./submodule-z449.md)。
+- **zPDF_package**（`third_party/zPDF_package`，PDF 转换页签）：经同源 fetch 调用 zTools2 的 `/api/pdf/*` REST API。详见 [submodule-zPDF_package.md](./submodule-zPDF_package.md)。
+- **zWhiteBoard**（`third_party/zWhiteBoard`，共享记事本页签）：经同源 fetch/WS 调用 zTools2 的 `/api/wb/*` 与 `/api/ws/wb/*`。详见 [submodule-zWhiteBoard.md](./submodule-zWhiteBoard.md)。
+
+> **i18n 桥接关键点**：子项目组件用各自 `useLocale` composable **直接读自身模块级 i18n 实例**（`i18n.global`），而非 `useI18n({ useScope: 'global' })`。后者在嵌入时会解析到宿主已安装的 i18n 实例（不含子项目文案），导致文案回退成 i18n key（显示 ID 而非文字）。

 ## 存活校验（requiresAlive）

@@ -63,8 +74,9 @@ export default {
 - 时机：应用加载即探测一次，之后每 30s 周期重探（`startPolling`）。
 - 结果在全应用共享（模块级 `cache` Map），`useProjects`（页签可见性）与 `App.vue`（KeepAlive 卸载）共用同一 ref。
 - **乐观显示**：探测中（pending）/存活（up）都显示页签，仅明确不可达（down）才隐藏并卸载；恢复后自动重新加载。
+- 探针 URL 由 `healthUrl(service)` 拼出同源相对路径（`/api/health`），经 vite dev proxy / Apache 反代转发到 zTools2，与环境无关。

-目前仅白板页签使用（`requiresAlive: 'https://f.zikai.wang/health'`）。
+目前白板与 PDF 页签使用（`requiresAlive: healthUrl('whiteboard'|'pdf')`），二者探针均指向 zTools2 的 `/api/health`。

 ## 路由

@@ -76,4 +88,4 @@ export default {

 ## 集中配置

-`src/config/app.config.js` -- 外部服务 URL（白板地址、存活探针路径等）集中管理，模块按需 import。改 URL 只改这里（需重新 build）。
+`src/config/app.config.js` -- 各服务的同源探针路径（`/api/health`）与默认参数集中管理，模块按需 import。改路径只改这里（需重新 build）。
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -0,0 +1,151 @@
+# 部署指南
+
+zPDF_package 功能涉及三个项目协同：**zMainPage**（父站，Vue3 静态站）、**zTools2**（后端 API + PDF 页面）、**zPDF_package**（PDF 转换前端源码，zMainPage 子模块）。提供三种部署模式，按需选用。
+
+## 拓扑
+
+```
+浏览器 -> Apache(:80)
+            ├── 静态文件 /var/www/html  （zMainPage 构建产物：主页 + 页签）
+            └── 反代 /api/ -> zTools2(127.0.0.1:6867)
+                        ├── /api/pdf/*            PDF 转换 API（cookie 用户）
+                        ├── /api/pdf-admin        PDF 管理页（Basic Auth）
+                        ├── /api/static/pdf*      前端静态资源
+                        └── MySQL(3306) + uploads/
+```
+
+PDF 页签 = zMainPage 构建期 import zPDF_package 的 `App.vue` 作为组件（非 iframe），经同源 fetch 调用 zTools2 的 `/api/pdf/*` REST API（**同源相对路径**，cookie 第一方生效，与环境无关）。
+
+> **路由约定**：zTools2 所有入口（页面 / 静态 / 探针 / WS / API）统一挂在 `/api/` 下，反代与 vite proxy 只需一条 `/api/` 规则。前端组件经同源相对路径（`/api/pdf/jobs`、`/api/health` 等）调用，自动指向**当前环境**的 zTools2，无需区分 dev/prod，也不会误打到其它环境域名。详见 zTools2 README「路由约定」。
+
+---
+
+## 模式一：组件独立部署（开发/调试）
+
+各组件独立运行，互不依赖部署，适合开发调试。
+
+### 1. zTools2 后端独立运行
+
+```bash
+cd zTools2
+./setup.sh                 # 首次：venv + 依赖 + 建库 + SFTP 密钥
+./start.sh                 # 启动 HTTP(127.0.0.1:6867) + SFTP(2022)
+# 或：python -m uvicorn app.main:app --host 127.0.0.1 --port 6867
+```
+
+访问：http://127.0.0.1:6867/api/pdf-admin（PDF 管理页）、http://127.0.0.1:6867/docs（API 文档）。
+
+> 用户侧 PDF 页面由 zMainPage 的 zPDF_package 组件提供（构建期 import），zTools2 仅提供 `/api/pdf/*` REST API 与 `/api/pdf-admin` 管理页。
+
+### 2. zPDF_package 前端独立运行
+
+```bash
+cd zPDF_package
+npm install
+npm run dev                # http://localhost:5175
+```
+
+`vite.config.js` 已配代理：`/api` 转发到 `127.0.0.1:6867`（需 zTools2 在跑），覆盖 `/api/pdf/*` 与 `/api/admin/pdf/*`。
+
+### 3. zMainPage 独立运行
+
+```bash
+cd zMainPage
+git submodule update --init --recursive   # 含 timeTableFix / z449 / zPDF_package
+npm install
+(cd third_party/timeTableFix && npm install)
+(cd third_party/z449 && npm install)
+npm run dev                # http://localhost:5173
+```
+
+> 独立模式下 PDF 页签的 zPDF_package 组件经同源相对路径 `/api/pdf/*` 调用 zTools2，经 vite proxy 转发到本地 zTools2（127.0.0.1:6867）。如需指向其它环境的 zTools2，改 `src/config/app.config.js` 的 `pdf.baseUrl` 为该环境地址（含协议与域名）后重新 `npm run dev`，或设 `VITE_API_BASE` 环境变量。
+
+---
+
+## 模式二：整体部署（生产，一次性）
+
+一条命令构建并部署全部组件到生产。**前提**：zMainPage 与 zTools2 在同一主机的同级目录。
+
+```bash
+cd zMainPage
+./deploy.sh                 # 构建 + 部署 + 配置 Apache 反代 + 重启 zTools2
+./deploy.sh --no-restart    # 仅更新文件，不重启 zTools2（如 zTools2 由 systemd 管理）
+```
+
+`deploy.sh` 做的事：
+1. 构建 zMainPage（含子模块），rsync 到 `/var/www/html`
+2. 写入 `.htaccess`（SPA history 回退）
+3. 配置 Apache vhost（`/etc/apache2/sites-available/zmainpage.conf`）反代 `/api/` 到 `127.0.0.1:6867`（含 WebSocket，靠 proxy_wstunnel 透传 `/api/ws`）
+4. 重启 zTools2（除非 `--no-restart`）
+
+部署后访问 http://localhost/ 即主页，PDF 页签渲染 zPDF_package 组件并经同源 fetch 调用 `/api/pdf/*`。
+
+> 已有 HTTPS vhost 时：`deploy.sh` 不会覆盖（仅首次写入）。手动在现有 vhost 加 `ProxyPass /api/ http://127.0.0.1:6867/api/` 一条规则即可（需 `a2enmod proxy_wstunnel` 以支持 WebSocket）。
+
+---
+
+## 模式三：持久化部署（systemd，开机自启 + 崩溃重启）
+
+zTools2 后端需长期运行（PDF 转换是异步后台任务）。用 systemd 管理实现开机自启与崩溃自动重启。
+
+### 安装 systemd 服务
+
+```bash
+cd zTools2
+./deploy/install-systemd.sh
+```
+
+脚本自动：
+- 用实际路径填充 `deploy/ztools2.service` 模板（自动检测 `.venv/bin/uvicorn` 或系统 `uvicorn`）
+- 写入 `/etc/systemd/system/ztools2.service`
+- `systemctl enable --now ztools2`（开机自启 + 立即启动）
+
+### 运维命令
+
+```bash
+systemctl status ztools2          # 状态
+systemctl restart ztools2         # 重启（更新代码后）
+systemctl stop ztools2            # 停止
+journalctl -u ztools2 -f          # 实时日志
+```
+
+### 卸载
+
+```bash
+sudo systemctl disable --now ztools2
+sudo rm /etc/systemd/system/ztools2.service
+sudo systemctl daemon-reload
+```
+
+### 与整体部署配合
+
+生产推荐：**systemd 管理 zTools2 + deploy.sh 部署前端**。
+
+```bash
+# 首次
+cd zTools2 && ./setup.sh && ./deploy/install-systemd.sh   # 后端持久化
+cd ../zMainPage && ./deploy.sh --no-restart                # 前端部署（不重启后端，systemd 管）
+# 后续更新前端
+cd zMainPage && ./deploy.sh --no-restart
+# 后续更新后端代码
+cd zTools2 && sudo systemctl restart ztools2
+```
+
+---
+
+## 环境要求
+
+| 项 | 要求 |
+|----|------|
+| OS | Ubuntu 22.04+（systemd + apache2） |
+| Python | ≥ 3.10（本仓开发用 3.14，需 SQLAlchemy ≥ 2.0.37） |
+| Node.js | ≥ 18 |
+| MySQL | 8.x |
+| Apache | 2.4（启用 proxy / proxy_http / proxy_wstunnel / rewrite / headers） |
+| weasyprint 系统库 | libpango-1.0-0 / libpangoft2-1.0-0 / libcairo2 / libgdk-pixbuf-2.0-0 |
+
+## 防火墙
+
+- 80（HTTP）/ 443（HTTPS）：对外
+- 6867：仅 loopback（经 Apache 反代，不对外）
+- 2022（SFTP）：按需对外
--- a/docs/readme-fixes.md
+++ b/docs/readme-fixes.md
@@ -0,0 +1,53 @@
+# README 勘误记录
+
+本文件记录 mainPage README 中发现并修正的错误，便于追溯。
+
+## 2026-07-27：构建输出路径描述错误
+
+**原描述（错误）**：
+
+- 项目结构注释：`vite.config.js # 构建输出到 /root/html（emptyOutDir=false，不清空既有文件）`
+- 如何使用：`# 3. 构建（产物输出到 /root/html，不清空既有文件）`
+- 开发命令：`npm run build # 构建到 /root/html`
+
+**实际行为**（见 `vite.config.js`）：
+
+- `npm run build` 输出到项目本地 `dist/`（`emptyOutDir: true`，每次清空）。
+- `npm run deploy` 才用 rsync 把 `dist/` 同步到 Apache 站点根 `/root/html`（脚本：`vite build && rsync ... dist/... /root/html/...`）。
+
+**修正**：三处均改为说明构建输出到 `dist/`，由 `npm run deploy` rsync 到 `/root/html`，并在「开发命令」补 `npm run deploy` 一行。
+
+> 背景：本次升级 timeTableFix 子模块（新增时区选择）时，按 README 从 0 构建复现发现该不一致。
+
+## 2026-07-28：部署路径统一为 /var/www/html
+
+**原描述（不一致）**：
+
+- `package.json` 的 `npm run deploy` 脚本 rsync 到 `/root/html`（依赖 `/root/html` 软链到 `/var/www/html`）。
+- `deploy.sh` 与 README 用 `/var/www/html`（Apache 标准 DocumentRoot，不依赖软链）。
+- `vite.config.js` 顶部注释写 `/root/html(软链到 /var/www/html)`。
+
+**问题**：全新 Ubuntu 安装时 `/root/html` 软链不存在，`npm run deploy` 会失败或写到错误位置；三处路径不统一。
+
+**修正**：`package.json` deploy 脚本与 `vite.config.js` 注释统一为 `/var/www/html`，与 `deploy.sh`、README、Apache DocumentRoot 一致。
+
+## 2026-07-28：iframe / ical.js / 子模块数量描述过时
+
+**原描述（错误）**：
+
+- README「外部依赖」称白板页「iframe 嵌入外部服务 `https://f.zikai.wang`」。
+- README「项目结构」注释称 zPDF_package「iframe 嵌入 zTools2」、白板「iframe 嵌入」。
+- README「package.json」注释含 `ical.js`（子模块依赖被误列在父项目）。
+- README 子模块只列 timeTableFix / z449，漏 zPDF_package / zWhiteBoard；克隆后安装依赖步骤也漏后两者。
+- architecture.md 的 `requiresAlive` 示例为 `https://f.zikai.wang/health`，且称「仅白板页签使用」（PDF 也用）。
+- architecture.md / add-module.md 提及 PageShell 的 `padded` prop（已被移除）。
+- submodule-timeTableFix.md 称「共享 mainPage 的依赖 `ical.js`」（实际子模块自带）。
+
+**实际行为**：
+
+- 四个子模块（timeTableFix / z449 / zPDF_package / zWhiteBoard）均为**构建期组件 import**（非 iframe）。
+- 白板与 PDF 页签的探针均为同源相对路径 `/api/health`（经反代/vite proxy 指向 zTools2），非外部域名。
+- `ical.js` 仅 timeTableFix 使用，由其自身 `package.json` 管理；mainPage 的 `package.json` 不再列。
+- PageShell 已无 `padded` prop（默认即上下间距）。
+
+**修正**：README 改写为简洁版，结构/外部依赖/克隆步骤均对齐现状；docs 各文件同步修正。
--- a/docs/submodule-timeTableFix.md
+++ b/docs/submodule-timeTableFix.md
@@ -7,7 +7,7 @@ timeTableFix（ICS 日程整理器）作为 **git submodule** 被 mainPage 引
 mainPage 侧的 `src/modules/timetable/Timetable.vue` 包装器 import 子模块的 `src/App.vue` 作为组件，套 `PageShell` 统一容器与标题，并持有 KeepAlive 匹配名 `defineOptions({ name: 'timetable' })`。

 - 子模块 `App.vue` 保持纯净（不持 name、不依赖宿主），可独立 `npm run build` / `npm test` / 部署。
- 构建期集成（非 iframe），共享 mainPage 的构建、依赖（`ical.js`）与 KeepAlive 缓存。
+- 构建期集成（非 iframe），共享 mainPage 的构建与 KeepAlive 缓存。子模块自身依赖（如 `ical.js`）在 `third_party/timeTableFix/node_modules`，由其自身 `package.json` 管理。
 - 子模块样式已隔离（scoped + `ttf-` 前缀类名），全局重置仅在独立 app 的 `main.js` 加载，不污染宿主。

 ## 克隆（含子模块）
@@ -23,6 +23,12 @@ cd mainPage
 git submodule update --init --recursive
 ```

+> 构建前需在子模块目录内 `npm install`（mainPage 的 Vite 编译子模块 `.vue`，但子模块依赖如 `ical.js` 须各自安装）：
+
+```bash
+cd third_party/timeTableFix && npm install
+```
+
 ## 升级子模块到最新版本

 ```bash
@@ -47,13 +53,6 @@ git rm third_party/timeTableFix
 git commit -m "chore: 移除 timeTableFix 子模块集成"
 ```

-同时删 `src/modules/timetable/` 文件夹即移除页签。timeTableFix 独立仓库与部署不受影响。
+同时删 `src/modules/timetable/` 文件夹即移除页签。timeTableFix 独立仓库不受影响。

-## 独立访问
-
-timeTableFix 独立 app 可经 Apache `/ttf/` 反代单独访问（`https://zikai.wang/ttf/`），与 mainPage 组件集成互不冲突。反代配置：
-
-```apache
-ProxyPass        /ttf/ http://127.0.0.1:8888/
-ProxyPassReverse /ttf/ http://127.0.0.1:8888/
-```
+> timeTableFix 仅作为 submodule 被 mainPage 构建期集成，无独立线上入口。独立开发/测试用其自身的 `npm run dev` / `npm test`。
--- a/docs/submodule-z449.md
+++ b/docs/submodule-z449.md
@@ -0,0 +1,70 @@
+# 子项目 z449（git submodule + i18n 桥接）
+
+z449（移动游戏项目展示页）作为 **git submodule** 被 mainPage 引入，位于 `third_party/z449`，独立仓库为 https://git.zikai.wang/zikai/z449.git 。
+
+## 集成方式
+
+mainPage 侧的 `src/modules/mobile-game/MobileGameWrapper.vue` 包装器 import 子模块的 `src/App.vue` 作为组件，并持有 KeepAlive 匹配名 `defineOptions({ name: 'mobile-game' })`。
+
+- 子模块 `App.vue` 是**便携式组件**：嵌入与独立运行两用。它自带独立 `vue-i18n` 实例与自己的 locale 文案（`mobileGame.*`），不共享 mainPage 的 messages。
+- **i18n 桥接**：mainPage 把当前语言经 `:locale` prop 透传给子模块的 `App.vue`；后者 `watch` 该 prop，同步到自己的 i18n 实例 `locale`。这样切换语言时，移动游戏页内容跟随父项目响应式切换，文案来自 z449 自有 locale。
+- 子模块独立运行时不接收 prop，默认中文。
+- 构建期集成（非 iframe），共享 mainPage 的构建与 KeepAlive 缓存。
+- 子模块样式已隔离（scoped），全局重置/令牌仅在独立 app 的 `main.js` 加载，嵌入时不加载，复用宿主 `:root` 令牌级联。
+
+## 克隆（含子模块）
+
+```bash
+git clone --recursive https://git.zikai.wang/zikai/zMainPage.git mainPage
+```
+
+若已 clone 但未带子模块：
+
+```bash
+cd mainPage
+git submodule update --init --recursive
+```
+
+> 构建前需在子模块目录内 `npm install`（mainPage 的 Vite 编译子模块 `.vue`，但子模块依赖如 `vue-i18n` 须各自安装）：
+
+```bash
+cd third_party/z449 && npm install
+```
+
+## 升级子模块到最新版本
+
+```bash
+cd mainPage
+git submodule update --remote third_party/z449       # 拉取最新
+cd third_party/z449 && git checkout master            # 固定到目标分支/commit
+cd ../..
+git add third_party/z449                              # 更新 gitlink 指针
+git commit -m "chore: 升级 z449 子模块"
+npm run build                                         # 重新构建 mainPage
+git push                                              # 推送 mainPage（gitlink）
+```
+
+> 推送顺序：先确保子模块的 commit 已推到 z449.git，再推 mainPage 的 gitlink，否则别人 clone mainPage 时拉不到子模块对应 commit。
+
+## 移除子模块集成（仅移除 mainPage 页签，不影响 z449 本身）
+
+```bash
+cd mainPage
+git submodule deinit -f third_party/z449
+git rm third_party/z449
+git commit -m "chore: 移除 z449 子模块集成"
+```
+
+同时删 `src/modules/mobile-game/` 文件夹即移除页签。z449 独立仓库不受影响。
+
+> z449 仅作为 submodule 被 mainPage 构建期集成，无独立线上入口。独立开发/测试用其自身的 `npm run dev` / `npm run build`。
+
+## 与 timeTableFix 子模块的差异
+
+| 维度 | 早期 timeTableFix | timeTableFix（现已 i18n） | z449 |
+|------|-------------------|---------------------------|------|
+| i18n | 无（硬编码中文） | 自带独立 vue-i18n，中英双语 | 自带独立 vue-i18n，中英双语 |
+| 语言同步 | 无需 | 经 `:locale` prop 桥接 | 经 `:locale` prop 桥接 |
+| 文案来源 | 组件内硬编码 | ttf 自有 locale 文件（单一来源） | z449 自有 locale 文件（单一来源） |
+
+两个子项目均采用相同的 i18n 桥接模式：各自维护独立 `vue-i18n` 实例与 locale 文案，组件内用 `useLocale` composable **直接读自身实例**（而非 `useI18n()` 注入，否则嵌入时会解析到宿主实例导致文案回退成 key），mainPage 侧包装器经 `:locale` prop 透传当前语言。
--- a/docs/submodule-zPDF_package.md
+++ b/docs/submodule-zPDF_package.md
@@ -0,0 +1,64 @@
+# 子项目 zPDF_package（git submodule）
+
+zPDF_package（PDF 转换前端）作为 **git submodule** 被 mainPage 引入，位于 `third_party/zPDF_package`，独立仓库为 https://git.zikai.wang/zikai/zPDF_package.git 。
+
+## 集成方式
+
+mainPage 侧的 `src/modules/pdf/Pdf.vue` 包装器 import 子模块的 `src/App.vue` 作为组件，套 `PageShell` 统一容器与标题，并持有 KeepAlive 匹配名 `defineOptions({ name: 'pdf' })`。
+
+- 子模块 `App.vue` 保持纯净（不持 name、不依赖宿主），可独立 `npm run build` / `npm test` / 部署。
+- **构建期集成（非 iframe）**，共享 mainPage 的构建与 KeepAlive 缓存。前后端分离：UI/交互在 zPDF_package，能力由 zTools2 的 `/api/pdf/*` REST API 提供。
+- 子模块样式已隔离（scoped + `zpdf-` 前缀类名），全局重置仅在独立 app 的 `main.js` 加载，不污染宿主。
+- 页签带 `requiresAlive: healthUrl('pdf')`，zTools2 不可达时隐藏页签并卸载组件。
+- **认证**：用户身份凭 httpOnly cookie（`zk_pdf`，samesite=lax）标识。该 cookie 在首次 `POST /api/pdf/jobs`（上传）的响应里种下，与页面路由无关。组件经同源 fetch 调用 `/api/pdf/*`，反代使 `/api/` 与主页同源，cookie 自动携带，无需 CORS。
+
+## 克隆（含子模块）
+
+```bash
+git clone --recursive https://git.zikai.wang/zikai/zMainPage.git mainPage
+```
+
+若已 clone 但未带子模块：
+
+```bash
+cd mainPage
+git submodule update --init --recursive
+```
+
+## 升级子模块到最新版本
+
+```bash
+cd mainPage
+git submodule update --remote third_party/zPDF_package      # 拉取最新
+cd third_party/zPDF_package && git checkout master           # 固定到目标分支/commit
+cd ../..
+git add third_party/zPDF_package                             # 更新 gitlink 指针
+git commit -m "chore: 升级 zPDF_package 子模块"
+npm run build                                                # 重新构建 mainPage
+git push                                                     # 推送 mainPage（gitlink）
+```
+
+> 推送顺序：先确保子模块的 commit 已推到 zPDF_package.git，再推 mainPage 的 gitlink，否则别人 clone mainPage 时拉不到子模块对应 commit。
+
+## 移除子模块集成（仅移除 mainPage 页签，不影响 zPDF_package 本身）
+
+```bash
+cd mainPage
+git submodule deinit -f third_party/zPDF_package
+git rm third_party/zPDF_package
+git commit -m "chore: 移除 zPDF_package 子模块集成"
+```
+
+同时删 `src/modules/pdf/` 文件夹即移除页签。zPDF_package 独立仓库不受影响。
+
+## 与其他子模块的差异
+
+| 维度 | timeTableFix / z449 | zPDF_package |
+|------|---------------------|--------------|
+| 集成方式 | 构建期组件 import（共享构建/KeepAlive） | 构建期组件 import（共享构建/KeepAlive） |
+| 后端依赖 | 无（纯前端） | 有（zTools2 `/api/pdf/*`） |
+| 同源/CORS | 不涉及 | 同源经反代，无需 CORS |
+| cookie | 不涉及 | httpOnly `zk_pdf`，同源自动携带（首次上传种下） |
+| mainPage 是否编译子模块 | 是（import .vue） | 是（import .vue） |
+
+> 四个子项目（timeTableFix / z449 / zPDF_package / zWhiteBoard）均采用构建期组件 import 集成，无 iframe。zPDF_package 与 zWhiteBoard 额外依赖 zTools2 后端 API，页签带存活探针。
--- a/docs/submodule-zWhiteBoard.md
+++ b/docs/submodule-zWhiteBoard.md
@@ -0,0 +1,72 @@
+# 子项目 zWhiteBoard（git submodule）
+
+zWhiteBoard（共享记事本前端）作为 **git submodule** 被 mainPage 引入，位于 `third_party/zWhiteBoard`，独立仓库为 https://git.zikai.wang/zikai/zWhiteBoard.git 。
+
+## 集成方式
+
+mainPage 侧的 `src/modules/whiteboard/Whiteboard.vue` 包装器 import 子模块的 `src/App.vue` 作为组件，套 `PageShell` 统一容器与标题，并持有 KeepAlive 匹配名 `defineOptions({ name: 'whiteboard' })`。
+
+- 子模块 `App.vue` 保持纯净（不持 name、不依赖宿主），可独立 `npm run build` / `npm test` / 部署。
+- **构建期集成（非 iframe）**，共享 mainPage 的构建与 KeepAlive 缓存。前后端分离：UI/交互在 zWhiteBoard，能力由 zTools2 的 `/api/wb/*` REST API 与 `/api/ws/wb/*` WebSocket 提供。
+- 子模块样式已隔离（scoped），全局重置仅在独立 app 的 `main.js` 加载，不污染宿主。
+- 页签带 `requiresAlive: healthUrl('whiteboard')`（同源 `/api/health`），zTools2 不可达时隐藏页签并卸载组件。
+- **身份标识**：白板不依赖 cookie。客户端 id 由 WebSocket 首帧 `hello` 携带或服务端生成（`client_id`），用于区分广播来源。组件经同源 fetch/WS 调用，反代使 `/api/` 与主页同源，无需 CORS。
+- 包装器解析路由参数 `/whiteboard/:boardId` 并经 `:board-id` prop 透传给子模块，支持直链预填白板 id。
+
+## 克隆（含子模块）
+
+```bash
+git clone --recursive https://git.zikai.wang/zikai/zMainPage.git mainPage
+```
+
+若已 clone 但未带子模块：
+
+```bash
+cd mainPage
+git submodule update --init --recursive
+```
+
+> 构建前需在子模块目录内 `npm install`（mainPage 的 Vite 编译子模块 `.vue`，但子模块依赖如 `vue-i18n` 须各自安装）：
+
+```bash
+cd third_party/zWhiteBoard && npm install
+```
+
+## 升级子模块到最新版本
+
+```bash
+cd mainPage
+git submodule update --remote third_party/zWhiteBoard      # 拉取最新
+cd third_party/zWhiteBoard && git checkout master           # 固定到目标分支/commit
+cd ../..
+git add third_party/zWhiteBoard                             # 更新 gitlink 指针
+git commit -m "chore: 升级 zWhiteBoard 子模块"
+npm run build                                                # 重新构建 mainPage
+git push                                                     # 推送 mainPage（gitlink）
+```
+
+> 推送顺序：先确保子模块的 commit 已推到 zWhiteBoard.git，再推 mainPage 的 gitlink，否则别人 clone mainPage 时拉不到子模块对应 commit。
+
+## 移除子模块集成（仅移除 mainPage 页签，不影响 zWhiteBoard 本身）
+
+```bash
+cd mainPage
+git submodule deinit -f third_party/zWhiteBoard
+git rm third_party/zWhiteBoard
+git commit -m "chore: 移除 zWhiteBoard 子模块集成"
+```
+
+同时删 `src/modules/whiteboard/` 文件夹即移除页签。zWhiteBoard 独立仓库不受影响。
+
+## 与其他子模块的差异
+
+| 维度 | timeTableFix / z449 | zPDF_package | zWhiteBoard |
+|------|---------------------|--------------|-------------|
+| 集成方式 | 构建期组件 import（共享构建/KeepAlive） | 构建期组件 import（共享构建/KeepAlive） | 构建期组件 import（共享构建/KeepAlive） |
+| 后端依赖 | 无（纯前端） | 有（zTools2 `/api/pdf/*`） | 有（zTools2 `/api/wb/*` + `/api/ws/wb/*`） |
+| 同源/CORS | 不涉及 | 同源经反代，无需 CORS | 同源经反代，无需 CORS |
+| 身份标识 | 不涉及 | httpOnly `zk_pdf` cookie，同源自动携带 | WS 首帧 `client_id`（无 cookie） |
+| 路由参数 | 无 | 无 | `:boardId`（直链预填白板 id） |
+| mainPage 是否编译子模块 | 是（import .vue） | 是（import .vue） | 是（import .vue） |
+
+> 四个子项目均采用构建期组件 import 集成，无 iframe。zWhiteBoard 与 zPDF_package 额外依赖 zTools2 后端 API，页签带存活探针；zWhiteBoard 是唯一带 WebSocket 与路由参数的子模块。
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,13 +8,13 @@
      "name": "mainpage",
      "version": "0.1.0",
      "dependencies": {
-        "ical.js": "^2.1.0",
        "vue": "^3.4.21",
        "vue-i18n": "^9.13.1",
        "vue-router": "^4.3.0"
      },
      "devDependencies": {
        "@vitejs/plugin-vue": "^5.0.4",
+        "html-minifier-terser": "^7.2.0",
        "vite": "^5.2.0"
      }
    },
@@ -469,11 +469,50 @@
        "url": "https://github.com/sponsors/kazupon"
      }
    },
+    "node_modules/@jridgewell/gen-mapping": {
+      "version": "0.3.13",
+      "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
+      "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==",
+      "dev": true,
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.0",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/source-map": {
+      "version": "0.3.11",
+      "resolved": "https://registry.npmjs.org/@jridgewell/source-map/-/source-map-0.3.11.tgz",
+      "integrity": "sha512-ZMp1V8ZFcPG5dIWnQLr3NSI1MiCU7UETdS/A0G8V/XWHvJv3ZsFqutJn1Y5RPmAPX6F3BiE397OqveU/9NCuIA==",
+      "dev": true,
+      "dependencies": {
+        "@jridgewell/gen-mapping": "^0.3.5",
+        "@jridgewell/trace-mapping": "^0.3.25"
+      }
+    },
    "node_modules/@jridgewell/sourcemap-codec": {
      "version": "1.5.5",
      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og=="
    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "dev": true,
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
    "node_modules/@rollup/rollup-android-arm-eabi": {
      "version": "4.62.2",
      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.2.tgz",
@@ -914,11 +953,70 @@
      "resolved": "https://registry.npmjs.org/@vue/shared/-/shared-3.5.39.tgz",
      "integrity": "sha512-l1rrBtBfTnmxvtsvdQDXltUUy8S1Y+ZaqdfUzmAnJkTd8Z8rv5v/ytW+TKiqEOWyHPoqtPlNFSs0lhRmYVSHVA=="
    },
+    "node_modules/acorn": {
+      "version": "8.17.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.17.0.tgz",
+      "integrity": "sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==",
+      "dev": true,
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/buffer-from": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz",
+      "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==",
+      "dev": true
+    },
+    "node_modules/camel-case": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/camel-case/-/camel-case-4.1.2.tgz",
+      "integrity": "sha512-gxGWBrTT1JuMx6R+o5PTXMmUnhnVzLQ9SNutD4YqKtI6ap897t3tKECYla6gCWEkplXnlNybEkZg9GEGxKFCgw==",
+      "dev": true,
+      "dependencies": {
+        "pascal-case": "^3.1.2",
+        "tslib": "^2.0.3"
+      }
+    },
+    "node_modules/clean-css": {
+      "version": "5.3.3",
+      "resolved": "https://registry.npmjs.org/clean-css/-/clean-css-5.3.3.tgz",
+      "integrity": "sha512-D5J+kHaVb/wKSFcyyV75uCn8fiY4sV38XJoe4CUyGQ+mOU/fMVYUdH1hJC+CJQ5uY3EnW27SbJYS4X8BiLrAFg==",
+      "dev": true,
+      "dependencies": {
+        "source-map": "~0.6.0"
+      },
+      "engines": {
+        "node": ">= 10.0"
+      }
+    },
+    "node_modules/commander": {
+      "version": "10.0.1",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-10.0.1.tgz",
+      "integrity": "sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==",
+      "dev": true,
+      "engines": {
+        "node": ">=14"
+      }
+    },
    "node_modules/csstype": {
      "version": "3.2.3",
      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="
    },
+    "node_modules/dot-case": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/dot-case/-/dot-case-3.0.4.tgz",
+      "integrity": "sha512-Kv5nKlh6yRrdrGvxeJ2e5y2eRUpkUosIW4A2AS38zwSz27zu7ufDwQPi5Jhs3XAlGNetl3bmnGhQsMtkKJnj3w==",
+      "dev": true,
+      "dependencies": {
+        "no-case": "^3.0.4",
+        "tslib": "^2.0.3"
+      }
+    },
    "node_modules/entities": {
      "version": "7.0.1",
      "resolved": "https://registry.npmjs.org/entities/-/entities-7.0.1.tgz",
@@ -987,10 +1085,47 @@
        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
      }
    },
-    "node_modules/ical.js": {
-      "version": "2.2.1",
-      "resolved": "https://registry.npmjs.org/ical.js/-/ical.js-2.2.1.tgz",
-      "integrity": "sha512-yK/UlPbEs316igb/tjRgbFA8ZV75rCsBJp/hWOatpyaPNlgw0dGDmU+FoicOcwX4xXkeXOkYiOmCqNPFpNPkQg=="
+    "node_modules/html-minifier-terser": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/html-minifier-terser/-/html-minifier-terser-7.2.0.tgz",
+      "integrity": "sha512-tXgn3QfqPIpGl9o+K5tpcj3/MN4SfLtsx2GWwBC3SSd0tXQGyF3gsSqad8loJgKZGM3ZxbYDd5yhiBIdWpmvLA==",
+      "dev": true,
+      "dependencies": {
+        "camel-case": "^4.1.2",
+        "clean-css": "~5.3.2",
+        "commander": "^10.0.0",
+        "entities": "^4.4.0",
+        "param-case": "^3.0.4",
+        "relateurl": "^0.2.7",
+        "terser": "^5.15.1"
+      },
+      "bin": {
+        "html-minifier-terser": "cli.js"
+      },
+      "engines": {
+        "node": "^14.13.1 || >=16.0.0"
+      }
+    },
+    "node_modules/html-minifier-terser/node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "dev": true,
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/lower-case": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/lower-case/-/lower-case-2.0.2.tgz",
+      "integrity": "sha512-7fm3l3NAF9WfN6W3JOmf5drwpVqX78JtoGJ3A6W0a6ZnldM41w2fV5D490psKFTpMds8TJse/eHLFFsNHHjHgg==",
+      "dev": true,
+      "dependencies": {
+        "tslib": "^2.0.3"
+      }
    },
    "node_modules/magic-string": {
      "version": "0.30.21",
@@ -1017,6 +1152,36 @@
        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
      }
    },
+    "node_modules/no-case": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/no-case/-/no-case-3.0.4.tgz",
+      "integrity": "sha512-fgAN3jGAh+RoxUGZHTSOLJIqUc2wmoBwGR4tbpNAKmmovFoWq0OdRkb0VkldReO2a2iBT/OEulG9XSUc10r3zg==",
+      "dev": true,
+      "dependencies": {
+        "lower-case": "^2.0.2",
+        "tslib": "^2.0.3"
+      }
+    },
+    "node_modules/param-case": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/param-case/-/param-case-3.0.4.tgz",
+      "integrity": "sha512-RXlj7zCYokReqWpOPH9oYivUzLYZ5vAPIfEmCTNViosC78F8F0H9y7T7gG2M39ymgutxF5gcFEsyZQSph9Bp3A==",
+      "dev": true,
+      "dependencies": {
+        "dot-case": "^3.0.4",
+        "tslib": "^2.0.3"
+      }
+    },
+    "node_modules/pascal-case": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/pascal-case/-/pascal-case-3.1.2.tgz",
+      "integrity": "sha512-uWlGT3YSnK9x3BQJaOdcZwrnV6hPpd8jFH1/ucpiLRPh/2zCVJKS19E4GvYHvaCcACn3foXZ0cLB9Wrx1KGe5g==",
+      "dev": true,
+      "dependencies": {
+        "no-case": "^3.0.4",
+        "tslib": "^2.0.3"
+      }
+    },
    "node_modules/picocolors": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -1049,6 +1214,15 @@
        "node": "^10 || ^12 || >=14"
      }
    },
+    "node_modules/relateurl": {
+      "version": "0.2.7",
+      "resolved": "https://registry.npmjs.org/relateurl/-/relateurl-0.2.7.tgz",
+      "integrity": "sha512-G08Dxvm4iDN3MLM0EsP62EDV9IuhXPR6blNz6Utcp7zyV3tr4HVNINt6MpaRWbxoOHT3Q7YN2P+jaHX8vUbgog==",
+      "dev": true,
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
    "node_modules/rollup": {
      "version": "4.62.2",
      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.62.2.tgz",
@@ -1093,6 +1267,15 @@
        "fsevents": "~2.3.2"
      }
    },
+    "node_modules/source-map": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
+      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+      "dev": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
    "node_modules/source-map-js": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -1101,6 +1284,46 @@
        "node": ">=0.10.0"
      }
    },
+    "node_modules/source-map-support": {
+      "version": "0.5.21",
+      "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.21.tgz",
+      "integrity": "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==",
+      "dev": true,
+      "dependencies": {
+        "buffer-from": "^1.0.0",
+        "source-map": "^0.6.0"
+      }
+    },
+    "node_modules/terser": {
+      "version": "5.49.0",
+      "resolved": "https://registry.npmjs.org/terser/-/terser-5.49.0.tgz",
+      "integrity": "sha512-SNiDnXyHSrxVcIOtVbULzcTmniUiwcV7Nwdyj1twVubeTmbjoa8p69KKDpfkdoOavuM4/GRm1+ykI8qqnavHoA==",
+      "dev": true,
+      "dependencies": {
+        "@jridgewell/source-map": "^0.3.3",
+        "acorn": "^8.15.0",
+        "commander": "^2.20.0",
+        "source-map-support": "~0.5.20"
+      },
+      "bin": {
+        "terser": "bin/terser"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/terser/node_modules/commander": {
+      "version": "2.20.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
+      "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
+      "dev": true
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true
+    },
    "node_modules/vite": {
      "version": "5.4.21",
      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
--- a/package.json
+++ b/package.json
@@ -7,16 +7,17 @@
  "scripts": {
    "dev": "vite",
    "build": "vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "deploy": "vite build && rsync -a --delete dist/js/mainPage/ /var/www/html/js/mainPage/ && rsync -a --delete dist/css/mainPage/ /var/www/html/css/mainPage/ && rsync -a dist/index.html /var/www/html/index.html && rsync -a dist/favicon.svg /var/www/html/favicon.svg"
  },
  "dependencies": {
-    "ical.js": "^2.1.0",
    "vue": "^3.4.21",
    "vue-i18n": "^9.13.1",
    "vue-router": "^4.3.0"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.0.4",
+    "html-minifier-terser": "^7.2.0",
    "vite": "^5.2.0"
  }
 }
--- a/src/App.vue
+++ b/src/App.vue
@@ -62,8 +62,6 @@ const keepInclude = computed(() =>
    <footer class="footer">
      <div class="container footer__inner">
        <span>© {{ new Date().getFullYear() }} Zikai Wang</span>
-        <span class="footer__dot">·</span>
-        <span>Built with Vue 3</span>
      </div>
    </footer>
  </div>
@@ -122,9 +120,6 @@ const keepInclude = computed(() =>
  color: var(--text-tertiary);
  font-size: 0.85rem;
 }
-.footer__dot {
-  opacity: 0.5;
-}

 .fade-enter-active,
 .fade-leave-active {
--- a/src/components/ui/Card.vue
+++ b/src/components/ui/Card.vue
@@ -1,28 +0,0 @@
-<script setup>
-defineProps({
-  hoverable: { type: Boolean, default: false }
-})
-</script>
-
-<template>
-  <div class="card" :class="{ 'card--hover': hoverable }">
-    <slot />
-  </div>
-</template>
-
-<style scoped>
-.card {
-  background: var(--bg);
-  border: 1px solid var(--border);
-  border-radius: var(--radius);
-  box-shadow: var(--shadow-sm);
-  padding: var(--space-lg);
-}
-.card--hover {
-  transition: transform var(--transition), box-shadow var(--transition);
-}
-.card--hover:hover {
-  transform: translateY(-2px);
-  box-shadow: var(--shadow-hover);
-}
-</style>
--- a/src/components/ui/PageShell.vue
+++ b/src/components/ui/PageShell.vue
@@ -3,17 +3,15 @@ import { computed } from 'vue'
 import { useLocale } from '../../composables/useLocale.js'

 // ★ 可复用页面外壳 -- 统一页面的容器宽度、垂直节奏与标题，消除各模块重复包裹。
-// 高内聚：所有页面布局令牌集中于此；低耦合：模块只声明 titleKey/fluid/padded，
+// 高内聚：所有页面布局令牌集中于此；低耦合：模块只声明 titleKey/fluid，
 // 不关心 .container 实现。新增页签照此复用，无需各写一套 wrapper。
 //
 // Props:
 //   titleKey: i18n 键（如 'tabs.whiteboard'），渲染为页面主标题；不传则无标题
 //   fluid:    true 时突破 1080px 限制（全宽 + 左右 padding），如日历页
-//   padded:   false 时去掉默认上下间距（页面完全自管布局时用）
 const props = defineProps({
  titleKey: { type: String, default: '' },
-  fluid: { type: Boolean, default: false },
-  padded: { type: Boolean, default: true }
+  fluid: { type: Boolean, default: false }
 })

 const { t } = useLocale()
@@ -21,7 +19,7 @@ const title = computed(() => (props.titleKey ? t(props.titleKey) : ''))
 </script>

 <template>
-  <div class="page-shell" :class="{ 'page-shell--padded': padded }">
+  <div class="page-shell">
    <div :class="fluid ? 'page-shell__fluid' : 'container page-shell__inner'">
      <div v-if="title || $slots.actions" class="page-shell__head">
        <h1 v-if="title" class="page-shell__title">{{ title }}</h1>
@@ -35,7 +33,7 @@ const title = computed(() => (props.titleKey ? t(props.titleKey) : ''))
 </template>

 <style scoped>
-.page-shell--padded {
+.page-shell {
  padding: var(--space-xl) 0 var(--space-2xl);
 }
 /* 标准容器宽度复用全局 .container（max-width 1080px，居中，左右 padding） */
--- a/src/components/ui/Tag.vue
+++ b/src/components/ui/Tag.vue
@@ -1,25 +0,0 @@
-<script setup>
-defineProps({
-  tag: { type: String, default: 'span' }
-})
-</script>
-
-<template>
-  <component :is="tag" class="tag">
-    <slot />
-  </component>
-</template>
-
-<style scoped>
-.tag {
-  display: inline-flex;
-  align-items: center;
-  padding: 2px 10px;
-  font-size: 0.78rem;
-  font-weight: 500;
-  color: var(--accent);
-  background: var(--accent-weak);
-  border-radius: 999px;
-  line-height: 1.6;
-}
-</style>
--- a/src/composables/useI18nLazy.js
+++ b/src/composables/useI18nLazy.js
@@ -14,6 +14,9 @@ export function useI18nLazy() {
    switching.value = true
    try {
      await loadLocaleAsync(locale)
+    } catch (e) {
+      // 语言包加载失败不能静默：记录到控制台，便于排查（如 chunk 404）
+      console.error('[mainPage] 加载语言包失败', locale, e)
    } finally {
      switching.value = false
    }
--- a/src/composables/useLocale.js
+++ b/src/composables/useLocale.js
@@ -1,15 +1,11 @@
-import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'

-// 共享的语言辅助 composable，消除各组件重复定义 L()
+// 共享的语言辅助 composable，消除各组件重复定义。
 // 用法：
-//   const { t, locale, isZh, pick } = useLocale()
-//   t('some.key')        // 走 i18n（推荐，文案在 locale 文件）
-//   isZh.value           // 判断当前是否中文
-//   pick({ zh, en })     // 从 {zh,en} 对象取当前语言值（用于数据文件）
+//   const { t } = useLocale()
+//   t('some.key')        // 走 i18n（文案在 locale 文件）
+// 页签包装器透传 locale 给子模块时直接读 i18n.global.locale（见各 wrapper）。
 export function useLocale() {
-  const { t, locale } = useI18n({ useScope: 'global' })
-  const isZh = computed(() => locale.value === 'zh-CN')
-  const pick = (obj) => (isZh.value ? obj.zh : obj.en)
-  return { t, locale, isZh, pick }
+  const { t } = useI18n({ useScope: 'global' })
+  return { t }
 }
--- a/src/config/app.config.js
+++ b/src/config/app.config.js
@@ -1,27 +1,40 @@
 // ★ 集中配置 -- 外部服务 URL、默认参数等统一在此维护
 // 模块按需 import { appConfig } 使用，改 URL 只改这里即可（需重新 build）。
 // 每个服务项都带默认值，避免缺失字段导致渲染崩溃。
+//
+// 路由约定：zTools2 所有入口（API/静态/探针/WS）统一挂在 /api/ 下，
+// fetch 与探针一律用**同源相对路径**（/api/pdf/jobs、/api/health 等）。
+// 无论是 vite dev（server.proxy 转发 /api 到本地 zTools2）、还是任意部署环境
+// （Apache/Nginx 反代 /api 到当前环境的 zTools2），同源相对路径都自动指向
+// **当前环境**的服务，无需区分 dev/prod，也不会误打到其它环境域名。
+// 罕见需要时可设 VITE_API_BASE（含协议与域名）显式覆盖为绝对地址。
+
+// 默认空串 = 同源相对路径；VITE_API_BASE 可覆盖为绝对地址（如指向独立测试环境域名）
+const BASE_URL = import.meta.env.VITE_API_BASE || ''

 export const appConfig = {
  // 共享记事本（白板）服务
  whiteboard: {
-    // 服务根地址（含协议与域名）
-    baseUrl: 'https://f.zikai.wang',
+    // 服务根地址（含协议与域名）；默认空串 = 同源相对路径
+    baseUrl: BASE_URL,
    // 存活探针路径；周期探测，挂掉则隐藏页签并卸载组件
-    healthPath: '/health',
-    // 记事本页面路径生成器
-    pagePath: (boardId) => `/wb/${encodeURIComponent(boardId)}`,
-    // 默认打开的记事本 id
-    defaultBoardId: 'share',
-    // 探测超时（毫秒）
-    healthTimeoutMs: 4000
+    healthPath: '/api/health',
+    // 默认打开的记事本 id（Whiteboard.vue 的 resolveBoardId 回退用）
+    defaultBoardId: 'share'
+  },
+  // PDF 转换服务（zTools2 提供 /api/pdf/* REST API；zPDF_package 组件同源 fetch 调用）
+  pdf: {
+    // 服务根地址（含协议与域名）；默认空串 = 同源相对路径
+    baseUrl: BASE_URL,
+    // 存活探针路径；周期探测，挂掉则隐藏页签并卸载组件
+    healthPath: '/api/health'
  }
 }

 /**
 * 取某服务的存活探针 URL。
 * @param {keyof typeof appConfig} service 配置中的服务名
- * @returns {string} 完整探针 URL，如 https://f.zikai.wang/health
+ * @returns {string} 完整探针 URL，如同源相对 /api/health 或绝对地址
 */
 export function healthUrl(service) {
  const cfg = appConfig[service]
--- a/src/i18n/locales/en.js
+++ b/src/i18n/locales/en.js
@@ -5,102 +5,20 @@ export default {
    title: 'Zikai'
  },
  common: {
-    loading: 'Loading…',
-    notAvailable: 'Not available',
-    serviceUnavailable: 'Service is temporarily unavailable. Please try again later.'
+    loading: 'Loading…'
  },
  tabs: {
    mobileGame: 'Mobile Game Project',
    calendar: 'CQY Timetable',
    whiteboard: 'Shared Notepad',
-    timetable: 'Schedule Organizer'
+    timetable: 'Schedule Organizer',
+    pdf: 'PDF Converter'
  },
  whiteboard: {
-    openExternal: 'Open in new tab',
    boardId: 'Board ID',
    switch: 'Switch'
-  },
-  mobileGame: {
-    hero: {
-      title: 'Mobile Game Project',
-      desc: 'A cross-semester Unity mobile-game capstone: 448 built the game (WebGL + Android APK), 449 built the showcase site and player leaderboard. Iterated across versions, from a character controller to a gyroscope-controlled 3D rolling-ball game, with ML-Agents reinforcement-learning experiments.'
-    },
-    meta: {
-      course: 'Miami University · Capstone 448 / 449',
-      stack: 'Stack',
-      stackValue: 'Unity · C# · WebGL · Android · PHP',
-      period: 'Period',
-      periodValue: '2022'
-    },
-    overview: {
-      label: 'Overview',
-      title: 'From character controller to gyro ball',
-      p1: 'The project spans courses 448 and 449. 448 built the game with Unity, producing browser-playable WebGL builds and installable Android APKs; 449 built the showcase site and a PHP+MySQL player leaderboard. The game evolved along several parallel lines, from 2D character controllers and platformers, ultimately shifting to a gyroscope-controlled 3D rolling ball, with ML-Agents reinforcement-learning experiments.',
-      p2: 'Gameplay iterated across versions: early builds were keyboard-controlled 2D character controllers with health/power stats; the final version became a gyroscope-tilt 3D rolling-ball game with falling snowflake bricks and bouncing yellow bricks.'
-    },
-    subtabs: {
-      team: 'Team · Leaderboard',
-      iterations: 'Iterations',
-      experiment: 'Experiment'
-    },
-    team: {
-      label: 'Team',
-      title: 'Members'
-    },
-    leaderboard: {
-      label: 'Leaderboard',
-      title: 'Top 30 Scores',
-      colRank: '#',
-      colName: 'Name',
-      colScore: 'Score',
-      noScores: 'No scores yet',
-      error: 'Leaderboard service unavailable'
-    },
-    iterations: {
-      label: 'Version History',
-      title: 'Iteration Record',
-      colControls: 'Controls',
-      colNote: 'Note',
-      colUnity: 'Unity',
-      playWebgl: 'Play WebGL',
-      downloadApk: 'Download APK',
-      pivotText: 'Earlier parallel lines: 2D'
-    },
-    experiment: {
-      label: 'Experiment',
-      title: 'ML-Agents Reinforcement Learning Demo',
-      caption: 'Capsules trained via ML-Agents to keep the ball from falling and to navigate obstacles.'
-    },
-    tracks: {
-      'roll-a-ball': {
-        name: '3D Rolling Ball (Final Form)',
-        desc: 'The final form as the project shifted from 2D to 3D. Tilt the phone to roll the ball; snowflake bricks fall, yellow bricks bounce.'
-      },
-      'zikai-ui': {
-        name: 'zikai-ui Character Controller',
-        desc: 'The most iterated line. A 2D character with health/power stats; controls evolved from mouse, QWER/ASDF keys, finally to WASD.'
-      },
-      'main': {
-        name: 'main Character Controller',
-        desc: '2D character controller; upgraded Unity 2020 -> 2021, added on-screen buttons and jump.'
-      },
-      'doby': {
-        name: 'DobyAdventure',
-        desc: '2D side-scrolling platformer: collect coins, score, health, touch joystick.'
-      }
-    },
-    versions: {
-      'zikai-0.0.0': { control: 'Left mouse: operate, Right mouse: track', note: 'Early mouse-controlled prototype' },
-      'zikai-0.0.1': { control: 'Health Q/W/E/R, Power A/S/D/F', note: 'Introduced health/power stat system' },
-      'zikai-0.0.2': { control: 'Same as 0.0.1', note: 'Build artifact renaming' },
-      'zikai-0.0.3': { control: 'WASD move, J jump, K fly (testing)', note: 'Switched to WASD, latest of this line' },
-      'main-0.0.0': { control: 'Character controller', note: 'Baseline' },
-      'main-0.0.1': { control: 'WASD move, K jump', note: 'Upgraded Unity, added on-screen buttons' },
-      'hongXiang-0.0.0': { control: 'A/D move, jump, collect coins', note: '2D platformer' },
-      'ball': { control: 'Tilt phone to move, tilt up/tap to jump', note: 'Final version, project shifted to 3D rolling ball' }
-    },
-    screenshots: {
-      caption: 'Screenshot {n}'
-    }
  }
+  // Mobile-game copy is provided by the z449 submodule's own i18n;
+  // mainPage keeps only tabs.mobileGame. Locale syncs to z449 via :locale prop.
+  // PDF tab copy is provided by the zPDF_package submodule's own i18n; mainPage keeps only tabs.pdf.
 }
--- a/src/i18n/locales/zh-CN.js
+++ b/src/i18n/locales/zh-CN.js
@@ -4,104 +4,20 @@ export default {
    title: 'Zikai'
  },
  common: {
-    loading: '加载中…',
-    notAvailable: '暂不可用',
-    serviceUnavailable: '服务暂不可用，请稍后再试。'
+    loading: '加载中…'
  },
  tabs: {
    mobileGame: '移动游戏项目',
    calendar: 'cqy课程表',
    whiteboard: '共享记事本',
-    timetable: '日程整理'
+    timetable: '日程整理',
+    pdf: 'PDF 转换'
  },
  whiteboard: {
-    openExternal: '在新标签页打开',
    boardId: '白板 ID',
    switch: '切换'
-  },
-  mobileGame: {
-    hero: {
-      title: '移动游戏项目',
-      desc: '一个跨学期的 Unity 移动游戏毕设项目：448 开发游戏本体（WebGL + Android APK），449 搭建展示网站与玩家排行榜。经历多版本迭代，从角色控制器演进到陀螺仪操控的 3D 滚球游戏，并尝试用 ML-Agents 做强化学习实验。'
-    },
-    meta: {
-      course: '迈阿密大学 · 毕设 448 / 449',
-      stack: '技术栈',
-      stackValue: 'Unity · C# · WebGL · Android · PHP',
-      period: '时间',
-      periodValue: '2022'
-    },
-    overview: {
-      label: '项目概览',
-      title: '从角色控制器到陀螺仪滚球',
-      p1: '项目跨越 448 与 449 两门课程。448 用 Unity 开发游戏本体，产出可浏览器试玩的 WebGL 构建与可安装的 Android APK；449 搭建展示网站与基于 PHP+MySQL 的玩家分数排行榜。游戏经历多条并行演进线，从 2D 角色控制器与平台跳跃，最终转向手机陀螺仪操控的 3D 滚球，并尝试用 ML-Agents 做强化学习实验。',
-      p2: '玩法经过多版本迭代：早期是键盘控制生命/能量的 2D 角色控制器，最终版改为手机陀螺仪倾斜操控的 3D 滚球，含雪花砖掉落、黄色砖弹跳等机制。'
-    },
-    subtabs: {
-      team: '团队 · 排行榜',
-      iterations: '迭代记录',
-      experiment: '实验'
-    },
-    team: {
-      label: '团队',
-      title: '成员'
-    },
-    leaderboard: {
-      label: '排行榜',
-      title: '玩家分数 Top 30',
-      colRank: '#',
-      colName: '玩家',
-      colScore: '分数',
-      noScores: '暂无分数记录',
-      error: '排行榜服务暂不可用'
-    },
-    iterations: {
-      label: '版本演进',
-      title: '迭代记录',
-      colControls: '操作',
-      colNote: '说明',
-      colUnity: 'Unity',
-      playWebgl: 'WebGL 试玩',
-      downloadApk: '下载 APK',
-      pivotText: '早期并行演进：2D 线'
-    },
-    experiment: {
-      label: '实验',
-      title: 'ML-Agents 强化学习演示',
-      caption: '胶囊体经 ML-Agents 训练，学习保球不掉与越障。'
-    },
-    // 版本演进线与版本数据中的可翻译文案
-    tracks: {
-      'roll-a-ball': {
-        name: '3D 滚球（最终形态）',
-        desc: '项目从 2D 转向 3D 的最终形态。手机陀螺仪倾斜操控滚球，含雪花砖掉落、黄色砖弹跳等机制。'
-      },
-      'zikai-ui': {
-        name: 'zikai-ui 角色控制器',
-        desc: '迭代次数最多的线。2D 角色带生命/能量属性，操作方式从鼠标、QWER/ASDF 键盘最终改为 WASD。'
-      },
-      'main': {
-        name: 'main 角色控制器',
-        desc: '2D 角色控制器，从 Unity 2020 升级到 2021，新增屏幕按键与跳跃。'
-      },
-      'doby': {
-        name: 'DobyAdventure',
-        desc: '2D 横版平台跳跃，吃金币、计分、血量、触屏摇杆。'
-      }
-    },
-    // 各版本的操作与说明文案（key = 版本 id）
-    versions: {
-      'zikai-0.0.0': { control: '鼠标左键操作、右键追踪', note: '早期鼠标控制原型' },
-      'zikai-0.0.1': { control: '生命 Q/W/E/R、能量 A/S/D/F', note: '引入生命/能量属性系统' },
-      'zikai-0.0.2': { control: '同 0.0.1', note: '构建产物重命名整理' },
-      'zikai-0.0.3': { control: 'WASD 移动、J 跳跃、K 飞行(测试)', note: '改为 WASD 操作，本线最新版' },
-      'main-0.0.0': { control: '角色控制器', note: '基线版本' },
-      'main-0.0.1': { control: 'WASD 移动、K 跳跃', note: '升级 Unity，新增屏幕按键' },
-      'hongXiang-0.0.0': { control: 'A/D 移动、跳跃、吃金币', note: '2D 平台跳跃' },
-      'ball': { control: '手机陀螺仪倾斜移动、上倾/点击跳跃', note: '最终版本，项目转向 3D 滚球' }
-    },
-    screenshots: {
-      caption: '项目截图 {n}'
-    }
  }
+  // 注：移动游戏项目（mobile-game）的文案由子模块 z449 自有 i18n 提供，
+  // mainPage 仅保留 tabs.mobileGame 页签标题。切换语言时经 :locale prop 同步给 z449。
+  // PDF 转换页签的文案由子模块 zPDF_package 自有 i18n 提供，mainPage 仅保留 tabs.pdf。
 }
--- a/src/modules/index.js
+++ b/src/modules/index.js
@@ -19,11 +19,16 @@

 const moduleFiles = import.meta.glob('./*/index.js', { eager: true })

-const modules = Object.values(moduleFiles)
-  .map((mod) => mod?.default)
-  .filter(Boolean)
-  // 字段完整性兜底：缺 id/tabKey/component 的模块无法生成页签与路由，跳过
-  .filter((m) => m && m.id && m.tabKey && typeof m.component === 'function')
+const modules = Object.entries(moduleFiles)
+  .map(([path, mod]) => ({ path, mod: mod?.default }))
+  .filter(({ mod }) => mod != null)
+  // 字段完整性兜底：缺 id/tabKey/component 的模块无法生成页签与路由，跳过并告警
+  .filter(({ path, mod }) => {
+    if (mod.id && mod.tabKey && typeof mod.component === 'function') return true
+    console.warn('[mainPage] 模块缺少必填字段，已跳过', path)
+    return false
+  })
+  .map(({ mod }) => mod)
  // order 缺省 999：排在所有显式 order 页签之后（hidden 页常用 99 之类显式值）
  .sort((a, b) => (a.order ?? 999) - (b.order ?? 999))

--- a/src/modules/mobile-game/MobileGame.vue
+++ b/src/modules/mobile-game/MobileGame.vue
@@ -1,106 +0,0 @@
-<script setup>
-import { ref, defineAsyncComponent } from 'vue'
-// 组件名与模块 id 一致，供 <KeepAlive :include> 按 id 精确匹配
-defineOptions({ name: 'mobile-game' })
-import HeroSection from './components/HeroSection.vue'
-import ScreenshotCarousel from './components/ScreenshotCarousel.vue'
-import SubTabs from './components/SubTabs.vue'
-import PageShell from '../../components/ui/PageShell.vue'
-import { useLocale } from '../../composables/useLocale.js'
-import { subTabs, defaultSubTab } from './config.js'
-
-const { t } = useLocale()
-
-// 子标签页配置转为 SubTabs 需要的 { id, labelKey } 形式
-const tabs = subTabs
-const activeTab = ref(defaultSubTab)
-
-// ★ 按需加载：三个子标签页用 defineAsyncComponent 动态 import，
-// 被 Vite/Rollup 拆成独立 chunk，只有切到对应标签页时才下载与渲染。
-// 配合 v-if，未激活的标签页组件根本不挂载（不执行 setup、不发 AJAX）。
-const TeamLeaderboardTab = defineAsyncComponent(() => import('./components/TeamLeaderboardTab.vue'))
-const IterationsTab = defineAsyncComponent(() => import('./components/IterationsTab.vue'))
-const ExperimentTab = defineAsyncComponent(() => import('./components/ExperimentTab.vue'))
-</script>
-
-<template>
-  <div class="mobile-game">
-    <HeroSection />
-
-    <!-- 内容区复用 PageShell 统一容器宽度（无标题，Hero 即页头） -->
-    <PageShell :padded="false">
-      <div class="mg-blocks">
-        <!-- 概览 + 截图轮播（始终显示） -->
-        <section class="block">
-          <div class="block__grid">
-            <div class="block__text">
-              <h2 class="section-title">
-                <small>{{ t('mobileGame.overview.label') }}</small>
-                {{ t('mobileGame.overview.title') }}
-              </h2>
-              <p>{{ t('mobileGame.overview.p1') }}</p>
-              <p>{{ t('mobileGame.overview.p2') }}</p>
-            </div>
-            <div class="block__media">
-              <ScreenshotCarousel />
-            </div>
-          </div>
-        </section>
-
-        <!-- 子标签页区域：按需加载，v-if 确保未激活的不渲染 -->
-        <section class="block">
-          <SubTabs v-model="activeTab" :tabs="tabs" />
-
-          <Suspense>
-            <TeamLeaderboardTab v-if="activeTab === 'team'" />
-            <IterationsTab v-else-if="activeTab === 'iterations'" />
-            <ExperimentTab v-else-if="activeTab === 'experiment'" />
-            <template #fallback>
-              <div class="tab-loading">{{ t('common.loading') }}</div>
-            </template>
-          </Suspense>
-        </section>
-      </div>
-    </PageShell>
-  </div>
-</template>
-
-<style scoped>
-.mobile-game {
-  padding-bottom: var(--space-2xl);
-}
-.mg-blocks {
-  padding: var(--space-xl) 0;
-}
-.block {
-  padding: var(--space-xl) 0;
-  border-bottom: 1px solid var(--border);
-}
-.block:last-child {
-  border-bottom: none;
-}
-.block__grid {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: var(--space-xl);
-  align-items: start;
-}
-.block__text p {
-  margin-bottom: var(--space-md);
-}
-.block__text p:last-child {
-  margin-bottom: 0;
-}
-.tab-loading {
-  padding: var(--space-xl);
-  text-align: center;
-  color: var(--text-tertiary);
-  font-size: 0.9rem;
-}
-
-@media (max-width: 768px) {
-  .block__grid {
-    grid-template-columns: 1fr;
-  }
-}
-</style>
--- a/src/modules/mobile-game/MobileGameWrapper.vue
+++ b/src/modules/mobile-game/MobileGameWrapper.vue
@@ -0,0 +1,20 @@
+<script setup>
+// ★ mobile-game 页签的 mainPage 侧包装器。
+// 子模块 z449 的 App.vue 作为便携式组件被 import，本包装器负责：
+//   1. 持有 KeepAlive 匹配用的组件名（与模块 id 一致），子模块自身不持 name
+//   2. 把 mainPage 当前语言经 :locale prop 透传给子模块的独立 i18n 实例，
+//      使其跟随父项目语言开关响应式切换（不共享 messages，仅同步 locale 值）
+// 子模块独立运行时不经过本包装器，保持纯净。
+defineOptions({ name: 'mobile-game' })
+
+import { computed } from 'vue'
+import i18n from '../../i18n/index.js'
+import Z449App from '../../../third_party/z449/src/App.vue'
+
+// 透传父项目当前语言给子应用（响应式：切语言时子应用内容跟随）
+const locale = computed(() => i18n.global.locale.value)
+</script>
+
+<template>
+  <Z449App :locale="locale" />
+</template>
--- a/src/modules/mobile-game/components/ExperimentTab.vue
+++ b/src/modules/mobile-game/components/ExperimentTab.vue
@@ -1,43 +0,0 @@
-<script setup>
-import { useLocale } from '../../../composables/useLocale.js'
-import { assets } from '../config.js'
-
-const { t } = useLocale()
-</script>
-
-<template>
-  <div class="tab-experiment">
-    <h2 class="section-title">
-      <small>{{ t('mobileGame.experiment.label') }}</small>
-      {{ t('mobileGame.experiment.title') }}
-    </h2>
-    <div class="video-wrap">
-      <video controls preload="none" :poster="assets.video.poster">
-        <source :src="assets.video.src" type="video/mp4" />
-      </video>
-      <p class="video-caption">{{ t('mobileGame.experiment.caption') }}</p>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.video-wrap {
-  border: 1px solid var(--border);
-  border-radius: var(--radius);
-  overflow: hidden;
-  background: var(--surface);
-  box-shadow: var(--shadow-sm);
-}
-.video-wrap video {
-  width: 100%;
-  display: block;
-  aspect-ratio: 16 / 9;
-  background: #000;
-}
-.video-caption {
-  padding: var(--space-md) var(--space-lg);
-  font-size: 0.88rem;
-  color: var(--text-secondary);
-  margin: 0;
-}
-</style>
--- a/src/modules/mobile-game/components/HeroSection.vue
+++ b/src/modules/mobile-game/components/HeroSection.vue
@@ -1,64 +0,0 @@
-<script setup>
-import Tag from '../../../components/ui/Tag.vue'
-import { useLocale } from '../../../composables/useLocale.js'
-import { heroMeta } from '../config.js'
-
-const { t } = useLocale()
-</script>
-
-<template>
-  <section class="hero">
-    <div class="container">
-      <div class="hero__eyebrow">
-        <Tag>{{ t(heroMeta.courseKey) }}</Tag>
-      </div>
-      <h1 class="hero__title">{{ t('mobileGame.hero.title') }}</h1>
-      <p class="hero__desc">{{ t('mobileGame.hero.desc') }}</p>
-      <div class="hero__meta">
-        <div v-for="item in heroMeta.items" :key="item.labelKey" class="hero__meta-item">
-          <span class="hero__meta-label">{{ t(item.labelKey) }}</span>
-          <span>{{ t(item.valueKey) }}</span>
-        </div>
-      </div>
-    </div>
-  </section>
-</template>
-
-<style scoped>
-.hero {
-  padding: var(--space-2xl) 0 var(--space-xl);
-  background: linear-gradient(180deg, var(--surface) 0%, var(--bg) 100%);
-  border-bottom: 1px solid var(--border);
-}
-.hero__eyebrow {
-  margin-bottom: var(--space-md);
-}
-.hero__title {
-  font-size: 2.3rem;
-  margin-bottom: var(--space-md);
-}
-.hero__desc {
-  max-width: 720px;
-  font-size: 1.02rem;
-  color: var(--text-secondary);
-  margin-bottom: var(--space-lg);
-}
-.hero__meta {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--space-xl);
-}
-.hero__meta-item {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  font-size: 0.92rem;
-  color: var(--text-primary);
-}
-.hero__meta-label {
-  font-size: 0.75rem;
-  text-transform: uppercase;
-  letter-spacing: 0.06em;
-  color: var(--text-tertiary);
-}
-</style>
--- a/src/modules/mobile-game/components/IterationsTab.vue
+++ b/src/modules/mobile-game/components/IterationsTab.vue
@@ -1,16 +0,0 @@
-<script setup>
-import { useLocale } from '../../../composables/useLocale.js'
-import VersionTimeline from './VersionTimeline.vue'
-
-const { t } = useLocale()
-</script>
-
-<template>
-  <div class="tab-iterations">
-    <h2 class="section-title">
-      <small>{{ t('mobileGame.iterations.label') }}</small>
-      {{ t('mobileGame.iterations.title') }}
-    </h2>
-    <VersionTimeline />
-  </div>
-</template>
--- a/src/modules/mobile-game/components/Leaderboard.vue
+++ b/src/modules/mobile-game/components/Leaderboard.vue
@@ -1,128 +0,0 @@
-<script setup>
-import { ref, onMounted } from 'vue'
-import { useLocale } from '../../../composables/useLocale.js'
-import { leaderboard } from '../config.js'
-
-const { t } = useLocale()
-
-const rows = ref([])
-const state = ref('loading') // loading | ok | error
-const errorMsg = ref('')
-
-// 复用 449 现有后端：POST endpoint {num} 取分页 JSON
-async function load() {
-  state.value = 'loading'
-  try {
-    const all = []
-    for (let page = 0; page < leaderboard.pages; page++) {
-      const res = await fetch(leaderboard.endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: `num=${page * leaderboard.perPage}`
-      })
-      if (!res.ok) throw new Error(`HTTP ${res.status}`)
-      const data = await res.json()
-      // data 形如 { "1": ["name", score], ... }
-      Object.keys(data).forEach((k) => {
-        const entry = data[k]
-        all.push({ rank: all.length + 1, name: entry[0], score: entry[1] })
-      })
-    }
-    rows.value = all
-    state.value = all.length ? 'ok' : 'error'
-    if (!all.length) errorMsg.value = t('mobileGame.leaderboard.noScores')
-  } catch (e) {
-    state.value = 'error'
-    errorMsg.value = t('mobileGame.leaderboard.error')
-  }
-}
-
-onMounted(load)
-</script>
-
-<template>
-  <div class="leaderboard">
-    <div v-if="state === 'loading'" class="leaderboard__state">
-      {{ t('common.loading') }}
-    </div>
-
-    <div v-else-if="state === 'error'" class="leaderboard__state leaderboard__state--error">
-      {{ errorMsg }}
-    </div>
-
-    <table v-else class="leaderboard__table">
-      <thead>
-        <tr>
-          <th>{{ t('mobileGame.leaderboard.colRank') }}</th>
-          <th>{{ t('mobileGame.leaderboard.colName') }}</th>
-          <th>{{ t('mobileGame.leaderboard.colScore') }}</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr v-for="r in rows" :key="r.rank" :class="{ 'is-top': r.rank <= 3 }">
-          <td class="leaderboard__rank">{{ r.rank }}</td>
-          <td class="leaderboard__name">{{ r.name }}</td>
-          <td class="leaderboard__score">{{ r.score }}</td>
-        </tr>
-      </tbody>
-    </table>
-  </div>
-</template>
-
-<style scoped>
-.leaderboard {
-  border: 1px solid var(--border);
-  border-radius: var(--radius);
-  overflow: hidden;
-  background: var(--bg);
-}
-.leaderboard__state {
-  padding: var(--space-xl);
-  text-align: center;
-  color: var(--text-secondary);
-}
-.leaderboard__state--error {
-  color: var(--text-tertiary);
-  font-size: 0.9rem;
-}
-.leaderboard__table {
-  width: 100%;
-  border-collapse: collapse;
-  font-size: 0.92rem;
-}
-.leaderboard__table th {
-  text-align: left;
-  padding: var(--space-sm) var(--space-md);
-  background: var(--surface);
-  border-bottom: 1px solid var(--border);
-  font-weight: 600;
-  color: var(--text-secondary);
-  font-size: 0.82rem;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
-}
-.leaderboard__table td {
-  padding: var(--space-sm) var(--space-md);
-  border-bottom: 1px solid var(--border);
-  color: var(--text-primary);
-}
-.leaderboard__table tbody tr:last-child td {
-  border-bottom: none;
-}
-.leaderboard__table tbody tr:hover {
-  background: var(--surface);
-}
-.leaderboard__rank {
-  width: 50px;
-  font-family: var(--font-mono);
-  color: var(--text-tertiary);
-}
-tr.is-top .leaderboard__rank {
-  color: var(--accent);
-  font-weight: 600;
-}
-.leaderboard__score {
-  font-family: var(--font-mono);
-  text-align: right;
-}
-</style>
--- a/src/modules/mobile-game/components/ScreenshotCarousel.vue
+++ b/src/modules/mobile-game/components/ScreenshotCarousel.vue
@@ -1,131 +0,0 @@
-<script setup>
-import { ref, onMounted, onUnmounted } from 'vue'
-import { useLocale } from '../../../composables/useLocale.js'
-import { assets } from '../config.js'
-
-const { t } = useLocale()
-const images = assets.screenshots
-const current = ref(0)
-let timer = null
-
-function go(i) {
-  current.value = (i + images.length) % images.length
-}
-function next() {
-  go(current.value + 1)
-}
-function pause() {
-  if (timer) {
-    clearInterval(timer)
-    timer = null
-  }
-}
-function resume() {
-  if (!timer) timer = setInterval(next, 5000)
-}
-
-onMounted(resume)
-onUnmounted(pause)
-</script>
-
-<template>
-  <div class="carousel" @mouseenter="pause" @mouseleave="resume">
-    <div class="carousel__viewport">
-      <div class="carousel__track" :style="{ transform: `translateX(-${current * 100}%)` }">
-        <figure v-for="(src, i) in images" :key="i" class="carousel__slide">
-          <img :src="src" :alt="t('mobileGame.screenshots.caption', { n: i + 1 })" loading="lazy" />
-        </figure>
-      </div>
-    </div>
-
-    <button class="carousel__btn carousel__btn--prev" @click="go(current - 1)" aria-label="prev">‹</button>
-    <button class="carousel__btn carousel__btn--next" @click="go(current + 1)" aria-label="next">›</button>
-
-    <div class="carousel__dots">
-      <button
-        v-for="(src, i) in images"
-        :key="i"
-        class="carousel__dot"
-        :class="{ 'is-active': i === current }"
-        @click="go(i)"
-        :aria-label="`slide ${i + 1}`"
-      />
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.carousel {
-  position: relative;
-  border: 1px solid var(--border);
-  border-radius: var(--radius);
-  overflow: hidden;
-  background: var(--surface);
-  box-shadow: var(--shadow);
-}
-.carousel__viewport {
-  overflow: hidden;
-  aspect-ratio: 4 / 3;
-}
-.carousel__track {
-  display: flex;
-  height: 100%;
-  transition: transform 0.5s ease;
-}
-.carousel__slide {
-  flex: 0 0 100%;
-  height: 100%;
-  margin: 0;
-}
-.carousel__slide img {
-  width: 100%;
-  height: 100%;
-  object-fit: cover;
-}
-.carousel__btn {
-  position: absolute;
-  top: 50%;
-  transform: translateY(-50%);
-  width: 36px;
-  height: 36px;
-  border-radius: 50%;
-  background: rgba(255, 255, 255, 0.9);
-  border: 1px solid var(--border);
-  color: var(--text-primary);
-  font-size: 1.3rem;
-  line-height: 1;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  box-shadow: var(--shadow);
-  transition: all var(--transition);
-}
-.carousel__btn:hover {
-  background: #fff;
-}
-.carousel__btn--prev { left: 12px; }
-.carousel__btn--next { right: 12px; }
-
-.carousel__dots {
-  position: absolute;
-  bottom: 12px;
-  left: 50%;
-  transform: translateX(-50%);
-  display: flex;
-  gap: 6px;
-}
-.carousel__dot {
-  width: 8px;
-  height: 8px;
-  border-radius: 50%;
-  background: rgba(255, 255, 255, 0.6);
-  border: 1px solid var(--border);
-  transition: all var(--transition);
-}
-.carousel__dot.is-active {
-  background: var(--accent);
-  border-color: var(--accent);
-  width: 22px;
-  border-radius: 4px;
-}
-</style>
--- a/src/modules/mobile-game/components/SubTabs.vue
+++ b/src/modules/mobile-game/components/SubTabs.vue
@@ -1,65 +0,0 @@
-<script setup>
-import { useLocale } from '../../../composables/useLocale.js'
-
-const props = defineProps({
-  tabs: { type: Array, required: true }, // [{ id, labelKey }]
-  modelValue: { type: String, required: true }
-})
-const emit = defineEmits(['update:modelValue'])
-
-const { t } = useLocale()
-</script>
-
-<template>
-  <div class="subtabs">
-    <button
-      v-for="tab in tabs"
-      :key="tab.id"
-      type="button"
-      class="subtabs__btn"
-      :class="{ 'is-active': modelValue === tab.id }"
-      @click="emit('update:modelValue', tab.id)"
-    >
-      {{ t(tab.labelKey) }}
-    </button>
-  </div>
-</template>
-
-<style scoped>
-.subtabs {
-  display: flex;
-  gap: var(--space-xs);
-  border-bottom: 1px solid var(--border);
-  margin-bottom: var(--space-lg);
-  overflow-x: auto;
-  scrollbar-width: none;
-}
-.subtabs::-webkit-scrollbar {
-  display: none;
-}
-.subtabs__btn {
-  position: relative;
-  padding: var(--space-sm) var(--space-md);
-  font-size: 0.92rem;
-  font-weight: 500;
-  color: var(--text-secondary);
-  white-space: nowrap;
-  transition: color var(--transition);
-}
-.subtabs__btn:hover {
-  color: var(--text-primary);
-}
-.subtabs__btn.is-active {
-  color: var(--accent);
-}
-.subtabs__btn.is-active::after {
-  content: '';
-  position: absolute;
-  left: var(--space-md);
-  right: var(--space-md);
-  bottom: -1px;
-  height: 2px;
-  background: var(--accent);
-  border-radius: 2px;
-}
-</style>
--- a/src/modules/mobile-game/components/TeamCard.vue
+++ b/src/modules/mobile-game/components/TeamCard.vue
@@ -1,55 +0,0 @@
-<script setup>
-import { team } from '../data/team.js'
-</script>
-
-<template>
-  <div class="team">
-    <div v-for="m in team" :key="m.name" class="team__card">
-      <div class="team__avatar">{{ m.name.charAt(0) }}</div>
-      <div class="team__info">
-        <div class="team__name">{{ m.name }}</div>
-      </div>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.team {
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
-  gap: var(--space-md);
-}
-.team__card {
-  display: flex;
-  align-items: center;
-  gap: var(--space-md);
-  padding: var(--space-md) var(--space-lg);
-  background: var(--bg);
-  border: 1px solid var(--border);
-  border-radius: var(--radius);
-  box-shadow: var(--shadow-sm);
-  transition: transform var(--transition), box-shadow var(--transition);
-}
-.team__card:hover {
-  transform: translateY(-2px);
-  box-shadow: var(--shadow-hover);
-}
-.team__avatar {
-  flex: 0 0 40px;
-  width: 40px;
-  height: 40px;
-  border-radius: 50%;
-  background: var(--accent-weak);
-  color: var(--accent);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  font-weight: 600;
-  font-size: 1.05rem;
-}
-.team__name {
-  font-weight: 600;
-  font-size: 0.95rem;
-  color: var(--text-primary);
-}
-</style>
--- a/src/modules/mobile-game/components/TeamLeaderboardTab.vue
+++ b/src/modules/mobile-game/components/TeamLeaderboardTab.vue
@@ -1,40 +0,0 @@
-<script setup>
-import { useLocale } from '../../../composables/useLocale.js'
-import TeamCard from './TeamCard.vue'
-import Leaderboard from './Leaderboard.vue'
-
-const { t } = useLocale()
-</script>
-
-<template>
-  <div class="tab-team block--two">
-    <div>
-      <h2 class="section-title">
-        <small>{{ t('mobileGame.team.label') }}</small>
-        {{ t('mobileGame.team.title') }}
-      </h2>
-      <TeamCard />
-    </div>
-    <div>
-      <h2 class="section-title">
-        <small>{{ t('mobileGame.leaderboard.label') }}</small>
-        {{ t('mobileGame.leaderboard.title') }}
-      </h2>
-      <Leaderboard />
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.block--two {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: var(--space-xl);
-  align-items: start;
-}
-@media (max-width: 768px) {
-  .block--two {
-    grid-template-columns: 1fr;
-  }
-}
-</style>
--- a/src/modules/mobile-game/components/VersionTimeline.vue
+++ b/src/modules/mobile-game/components/VersionTimeline.vue
@@ -1,266 +0,0 @@
-<script setup>
-import { computed } from 'vue'
-import { useLocale } from '../../../composables/useLocale.js'
-import { versions, tracks } from '../data/versions.js'
-
-const { t } = useLocale()
-
-// 按 tracks 数组顺序分组（3D 最终形态在前）；同一线内按 order 排序
-const grouped = computed(() => {
-  return tracks
-    .map((tr) => {
-      const items = versions
-        .filter((v) => v.track === tr.id)
-        .sort((a, b) => a.order - b.order)
-      return { track: tr, items }
-    })
-    .filter((g) => g.items.length > 0)
-})
-
-const is3D = (track) => track.form === '3D'
-const isFeatured = (track) => track.featured
-
-// 形态转变标记：出现在 3D 线（首位）之后、2D 线之前
-const showPivotAfter = (gi) => gi === 0 && grouped.value.length > 1 && is3D(grouped.value[0].track)
-
-// i18n 取值辅助：track/version 的文案在 locale 的 mobileGame.tracks / mobileGame.versions 下
-const trackName = (trackId) => t(`mobileGame.tracks.${trackId}.name`)
-const trackDesc = (trackId) => t(`mobileGame.tracks.${trackId}.desc`)
-const vControl = (versionId) => t(`mobileGame.versions.${versionId}.control`)
-const vNote = (versionId) => t(`mobileGame.versions.${versionId}.note`)
-</script>
-
-<template>
-  <div class="timeline">
-    <div
-      v-for="(g, gi) in grouped"
-      :key="g.track.id"
-      class="timeline__track"
-      :class="{
-        'timeline__track--3d': is3D(g.track),
-        'timeline__track--featured': isFeatured(g.track)
-      }"
-    >
-      <!-- 线标题 -->
-      <div class="timeline__track-head">
-        <span class="timeline__form" :class="{ 'is-3d': is3D(g.track) }">{{ g.track.form }}</span>
-        <span class="timeline__track-name">{{ trackName(g.track.id) }}</span>
-        <span v-if="isFeatured(g.track)" class="timeline__star">★</span>
-      </div>
-      <p class="timeline__track-desc">{{ trackDesc(g.track.id) }}</p>
-
-      <!-- 该线下的版本 -->
-      <div class="timeline__items">
-        <div
-          v-for="(v, i) in g.items"
-          :key="v.id"
-          class="timeline__item"
-        >
-          <div class="timeline__marker">
-            <span class="timeline__dot"></span>
-            <span v-if="i < g.items.length - 1" class="timeline__line"></span>
-          </div>
-          <div class="timeline__body">
-            <div class="timeline__head">
-              <span class="timeline__version">v{{ v.version }}</span>
-              <span class="timeline__product">{{ v.product }}</span>
-            </div>
-            <div class="timeline__row">
-              <span class="timeline__label">{{ t('mobileGame.iterations.colControls') }}</span>
-              <span>{{ vControl(v.id) }}</span>
-            </div>
-            <div class="timeline__row">
-              <span class="timeline__label">{{ t('mobileGame.iterations.colNote') }}</span>
-              <span>{{ vNote(v.id) }}</span>
-            </div>
-            <div class="timeline__row">
-              <span class="timeline__label">{{ t('mobileGame.iterations.colUnity') }}</span>
-              <span class="timeline__mono">{{ v.unity }}</span>
-            </div>
-            <div class="timeline__links">
-              <a v-if="v.webgl" :href="v.webgl" target="_blank" rel="noopener">
-                {{ t('mobileGame.iterations.playWebgl') }} ↗
-              </a>
-              <a v-if="v.apk" :href="v.apk" target="_blank" rel="noopener">
-                {{ t('mobileGame.iterations.downloadApk') }} ↗
-              </a>
-            </div>
-          </div>
-        </div>
-      </div>
-
-      <!-- 形态转变标记：3D 线之后、2D 线之前 -->
-      <div v-if="showPivotAfter(gi)" class="timeline__pivot">
-        <span class="timeline__pivot-line"></span>
-        <span class="timeline__pivot-text">{{ t('mobileGame.iterations.pivotText') }}</span>
-        <span class="timeline__pivot-line"></span>
-      </div>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-.timeline {
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-xl);
-}
-
-/* 最终形态强调 */
-.timeline__track--featured {
-  padding: var(--space-lg);
-  background: linear-gradient(180deg, var(--accent-weak) 0%, transparent 100%);
-  border: 1px solid var(--accent-weak);
-  border-radius: var(--radius);
-}
-.timeline__track--featured .timeline__track-name {
-  font-size: 1.2rem;
-}
-.timeline__track--featured .timeline__track-desc {
-  color: var(--text-primary);
-}
-
-.timeline__track-head {
-  display: flex;
-  align-items: center;
-  gap: var(--space-sm);
-  margin-bottom: var(--space-xs);
-}
-.timeline__form {
-  display: inline-flex;
-  align-items: center;
-  padding: 2px 10px;
-  font-size: 0.74rem;
-  font-weight: 600;
-  border-radius: 999px;
-  background: var(--surface-2);
-  color: var(--text-secondary);
-  letter-spacing: 0.04em;
-}
-.timeline__form.is-3d {
-  background: var(--accent);
-  color: #fff;
-}
-.timeline__track-name {
-  font-weight: 600;
-  font-size: 1.05rem;
-  color: var(--text-primary);
-}
-.timeline__star {
-  color: var(--accent);
-  font-size: 0.9rem;
-}
-.timeline__track-desc {
-  font-size: 0.9rem;
-  color: var(--text-secondary);
-  margin: 0 0 var(--space-md);
-  max-width: 640px;
-}
-
-.timeline__items {
-  padding-left: 4px;
-}
-.timeline__item {
-  display: flex;
-  gap: var(--space-md);
-  padding-bottom: var(--space-md);
-}
-.timeline__marker {
-  position: relative;
-  flex: 0 0 14px;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  padding-top: 6px;
-}
-.timeline__dot {
-  width: 10px;
-  height: 10px;
-  border-radius: 50%;
-  background: var(--bg);
-  border: 2px solid var(--accent);
-  flex: 0 0 10px;
-}
-.timeline__track--3d .timeline__dot {
-  background: var(--accent);
-}
-.timeline__line {
-  flex: 1;
-  width: 2px;
-  background: var(--border);
-  margin-top: 4px;
-  min-height: 20px;
-}
-.timeline__body {
-  flex: 1;
-  padding: var(--space-sm) var(--space-md);
-  background: var(--bg);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-sm);
-  box-shadow: var(--shadow-sm);
-  transition: box-shadow var(--transition);
-}
-.timeline__body:hover {
-  box-shadow: var(--shadow);
-}
-.timeline__head {
-  display: flex;
-  align-items: baseline;
-  gap: var(--space-sm);
-  margin-bottom: var(--space-xs);
-}
-.timeline__version {
-  font-family: var(--font-mono);
-  font-size: 0.82rem;
-  color: var(--accent);
-  background: var(--accent-weak);
-  padding: 1px 8px;
-  border-radius: 6px;
-  font-weight: 600;
-}
-.timeline__product {
-  font-size: 0.82rem;
-  color: var(--text-tertiary);
-}
-.timeline__row {
-  display: flex;
-  gap: var(--space-sm);
-  font-size: 0.88rem;
-  color: var(--text-secondary);
-  padding: 1px 0;
-}
-.timeline__label {
-  flex: 0 0 52px;
-  color: var(--text-tertiary);
-  font-size: 0.8rem;
-}
-.timeline__mono {
-  font-family: var(--font-mono);
-}
-.timeline__links {
-  display: flex;
-  gap: var(--space-md);
-  margin-top: var(--space-xs);
-  font-size: 0.85rem;
-}
-
-/* 形态转变标记 */
-.timeline__pivot {
-  display: flex;
-  align-items: center;
-  gap: var(--space-md);
-  margin: var(--space-md) 0 0;
-}
-.timeline__pivot-line {
-  flex: 1;
-  height: 1px;
-  background: linear-gradient(90deg, transparent, var(--border-strong), transparent);
-}
-.timeline__pivot-text {
-  font-size: 0.8rem;
-  font-weight: 600;
-  color: var(--text-tertiary);
-  white-space: nowrap;
-  letter-spacing: 0.02em;
-}
-</style>
--- a/src/modules/mobile-game/config.js
+++ b/src/modules/mobile-game/config.js
@@ -1,46 +0,0 @@
-// mobile-game 模块的静态配置（集中管理，避免散落在各组件）
-// 文案走 i18n（见 locales 的 mobileGame 命名空间），此处只放纯配置与资源路径。
-
-// 站点根绝对路径的资源引用
-export const assets = {
-  // 截图轮播图源
-  screenshots: [
-    '/448/1.jpg',
-    '/448/2.jpg',
-    '/448/3.jpg'
-  ],
-  // ML-Agents 演示视频
-  video: {
-    src: '/448/ml/449ml.mp4',
-    poster: '/448/2.jpg'
-  }
-}
-
-// 排行榜后端（复用 449 现有 PHP 接口）
-export const leaderboard = {
-  endpoint: '/449/449rest.php',
-  // 拉取页数 x 每页条数 = 总条数
-  pages: 3,
-  perPage: 10
-}
-
-// Hero 区元数据（i18n 键，文案在 locales/mobileGame.meta 下）
-export const heroMeta = {
-  // meta 项顺序：labelKey -> valueKey
-  items: [
-    { labelKey: 'mobileGame.meta.stack', valueKey: 'mobileGame.meta.stackValue' },
-    { labelKey: 'mobileGame.meta.period', valueKey: 'mobileGame.meta.periodValue' }
-  ],
-  // 顶部 eyebrow tag
-  courseKey: 'mobileGame.meta.course'
-}
-
-// 子标签页定义（id 与 i18n 键）
-export const subTabs = [
-  { id: 'team', labelKey: 'mobileGame.subtabs.team' },
-  { id: 'iterations', labelKey: 'mobileGame.subtabs.iterations' },
-  { id: 'experiment', labelKey: 'mobileGame.subtabs.experiment' }
-]
-
-// 默认激活的子标签页
-export const defaultSubTab = 'team'
--- a/src/modules/mobile-game/data/team.js
+++ b/src/modules/mobile-game/data/team.js
@@ -1,8 +0,0 @@
-// 团队成员（来自 449 展示页）
-export const team = [
-  { name: 'Zikai Wang' },
-  { name: 'Hongxiang He' },
-  { name: 'Zhuoyue Sun' },
-  { name: 'Xingchen Zhou' },
-  { name: 'Yidong Yao' }
-]
--- a/src/modules/mobile-game/data/versions.js
+++ b/src/modules/mobile-game/data/versions.js
@@ -1,48 +0,0 @@
-// 448 版本演进数据（纯结构化数据，文案走 i18n：mobileGame.tracks / mobileGame.versions）
-//
-// 项目是多条线并行演进的，且经历了「2D -> 3D 滚球」的形态转变：
-//   - roll-a-ball（3D，featured）：项目转向 3D 的最终形态，置顶强调
-//   - zikai-ui（2D）：角色控制器，0.0.0 -> 0.0.3
-//   - main（2D）：角色控制器，0.0.0 -> 0.0.1
-//   - doby（2D）：2D 平台跳跃
-//
-// track 字段标识所属演进线；form 标识 2D/3D；order 用于线内排序。
-// name/note/control 等文案通过 i18n 键 tracks[trackId] / versions[versionId] 取。
-
-export const tracks = [
-  {
-    id: 'roll-a-ball',
-    form: '3D',
-    featured: true
-  },
-  {
-    id: 'zikai-ui',
-    form: '2D'
-  },
-  {
-    id: 'main',
-    form: '2D'
-  },
-  {
-    id: 'doby',
-    form: '2D'
-  }
-]
-
-export const versions = [
-  // zikai-ui 线
-  { id: 'zikai-0.0.0', track: 'zikai-ui', version: '0.0.0', unity: '-', product: 'My project / 1.0.2', webgl: '/448/zikai-0.0.0/', apk: null, order: 1 },
-  { id: 'zikai-0.0.1', track: 'zikai-ui', version: '0.0.1', unity: '2020.3.30f1', product: 'zikai-ui / 1.0.2', webgl: '/448/zikai-0.0.1/', apk: '/448/zikai-0.0.1/zikai.apk', order: 2 },
-  { id: 'zikai-0.0.2', track: 'zikai-ui', version: '0.0.2', unity: '2020.3.30f1', product: 'zikai-ui / 1.0.2', webgl: '/448/zikai-0.0.2/', apk: '/448/zikai-0.0.2/zikai.apk', order: 3 },
-  { id: 'zikai-0.0.3', track: 'zikai-ui', version: '0.0.3', unity: '2020.3.30f1', product: 'zikai-ui / 1.0.2.5', webgl: '/448/zikai-0.0.3/', apk: '/448/zikai-0.0.3/zikai.apk', order: 4 },
-
-  // main 线
-  { id: 'main-0.0.0', track: 'main', version: '0.0.0', unity: '2020.3.30f1', product: 'zikai-main / 1.0.2.6', webgl: '/448/main-0.0.0/', apk: '/448/main-0.0.0.apk', order: 2 },
-  { id: 'main-0.0.1', track: 'main', version: '0.0.1', unity: '2021.3.12f1', product: 'beta / 1.0.2', webgl: '/448/main-0.0.1/', apk: '/448/main-0.0.1/zikai.apk', order: 5 },
-
-  // doby 线
-  { id: 'hongXiang-0.0.0', track: 'doby', version: '0.0.0', unity: '2021.2.10f1', product: 'DobyAdventure', webgl: null, apk: '/448/hongXiang-0.0.0/2D game.apk', order: 3 },
-
-  // roll-a-ball 线（3D，项目形态转变）
-  { id: 'ball', track: 'roll-a-ball', version: '0.0.2', unity: '2021.3.12f1', product: '3dRoingBallt2 / 0.0.2', webgl: '/448/ball/', apk: '/448/203wangz199.apk', order: 6 }
-]
--- a/src/modules/mobile-game/index.js
+++ b/src/modules/mobile-game/index.js
@@ -3,6 +3,6 @@ export default {
  id: 'mobile-game',
  tabKey: 'tabs.mobileGame',
  order: 1,
-  // 懒加载组件 -> 独立 chunk
-  component: () => import('./MobileGame.vue')
+  // 懒加载组件 -> 独立 chunk（包装器 import 子模块 z449 的 App.vue）
+  component: () => import('./MobileGameWrapper.vue')
 }
--- a/src/modules/pdf/Pdf.vue
+++ b/src/modules/pdf/Pdf.vue
@@ -0,0 +1,49 @@
+<script setup>
+// ★ pdf 页签的 mainPage 侧包装器。
+// 子模块 zPDF_package 的 App.vue 作为便携式组件被 import，本包装器负责：
+//   1. 套 PageShell 统一容器宽度与标题（与其他页签对齐）
+//   2. 持有 KeepAlive 匹配用的组件名（与模块 id 一致），子模块自身不持 name
+//   3. 把 mainPage 当前语言经 :locale prop 透传给子模块的独立 i18n 实例，
+//      使其跟随父项目语言开关响应式切换（不共享 messages，仅同步 locale 值）
+// 前后端分离：UI/交互在 zPDF_package，能力由 zTools2 的 /api/pdf/* REST API 提供，
+// 同源 fetch 自动携带 httpOnly cookie（zk_pdf），无需 CORS。与 timeTableFix 集成范式一致。
+// 子模块独立运行时不经过本包装器，保持纯净。
+defineOptions({ name: 'pdf' })
+
+import { computed } from 'vue'
+import PageShell from '../../components/ui/PageShell.vue'
+import i18n from '../../i18n/index.js'
+import ZPdfApp from '../../../third_party/zPDF_package/src/App.vue'
+
+// 透传父项目当前语言给子应用（响应式：切语言时子应用内容跟随）
+const locale = computed(() => i18n.global.locale.value)
+</script>
+
+<template>
+  <PageShell title-key="tabs.pdf">
+    <div class="pdf__frame">
+      <ZPdfApp :locale="locale" />
+    </div>
+  </PageShell>
+</template>
+
+<style scoped>
+/* 让子应用填满外壳容器，保留其内部布局自洽；转换页以上传与列表为主，给足高度 */
+.pdf__frame {
+  position: relative;
+  border-radius: var(--radius);
+  overflow: hidden;
+  box-shadow: var(--shadow);
+  border: 1px solid var(--border);
+  background: var(--surface);
+  /* 转换页以上传与列表为主，给足高度 */
+  height: 78vh;
+  min-height: 520px;
+}
+@media (max-width: 768px) {
+  .pdf__frame {
+    height: 72vh;
+    min-height: 400px;
+  }
+}
+</style>
--- a/src/modules/pdf/index.js
+++ b/src/modules/pdf/index.js
@@ -0,0 +1,17 @@
+// 模块元数据 -- PDF 转换页签
+// 构建期组件集成：mainPage 侧包装器 Pdf.vue import 子模块 zPDF_package 的 App.vue，
+// 套 PageShell 统一容器与标题。zPDF_package 作为 git submodule 独立维护，
+// 其 UI/交互经同源 fetch 调用 zTools2 的 /api/pdf/* REST API（前后端分离）。
+// requiresAlive 指向存活探针 URL：启动时探测，zTools2 不可达则隐藏该页签。
+// 升级：cd third_party/zPDF_package && git pull，回 mainPage 根 git add 该子模块并重新 build。
+import { healthUrl } from '../../config/app.config.js'
+
+export default {
+  id: 'pdf',
+  tabKey: 'tabs.pdf',
+  order: 4,
+  // 存活探针 URL；useProjects 启动时探测一次，挂掉则不显示页签
+  requiresAlive: healthUrl('pdf'),
+  // 懒加载组件 -> 独立 chunk
+  component: () => import('./Pdf.vue')
+}
--- a/src/modules/timetable/Timetable.vue
+++ b/src/modules/timetable/Timetable.vue
@@ -1,19 +1,26 @@
 <script setup>
 // ★ timetable 页签的 mainPage 侧包装器。
-// 子模块 timeTableFix 的 App.vue 作为纯功能组件被 import，本包装器负责：
+// 子模块 timeTableFix 的 App.vue 作为便携式组件被 import，本包装器负责：
 //   1. 套 PageShell 统一容器宽度与标题（与其他页签对齐）
 //   2. 持有 KeepAlive 匹配用的组件名（与模块 id 一致），子模块自身不持 name
+//   3. 把 mainPage 当前语言经 :locale prop 透传给子模块的独立 i18n 实例，
+//      使其跟随父项目语言开关响应式切换（不共享 messages，仅同步 locale 值）
 // 子模块独立运行时不经过本包装器，保持纯净。
 defineOptions({ name: 'timetable' })

+import { computed } from 'vue'
 import PageShell from '../../components/ui/PageShell.vue'
+import i18n from '../../i18n/index.js'
 import TimeTableFixApp from '../../../third_party/timeTableFix/src/App.vue'
+
+// 透传父项目当前语言给子应用（响应式：切语言时子应用内容跟随）
+const locale = computed(() => i18n.global.locale.value)
 </script>

 <template>
  <PageShell title-key="tabs.timetable">
    <div class="timetable__frame">
-      <TimeTableFixApp />
+      <TimeTableFixApp :locale="locale" />
    </div>
  </PageShell>
 </template>
--- a/src/modules/whiteboard/Whiteboard.vue
+++ b/src/modules/whiteboard/Whiteboard.vue
@@ -1,13 +1,22 @@
 <script setup>
-import { ref, computed, watch } from 'vue'
-// 组件名与模块 id 一致，供 <KeepAlive :include> 按 id 精确匹配；
-// 白板后端失活时把它从 include 移除即可卸载组件
+// ★ whiteboard 页签的 mainPage 侧包装器。
+// 子模块 zWhiteBoard 的 App.vue 作为便携式组件被 import，本包装器负责：
+//   1. 套 PageShell 统一容器宽度与标题（与其他页签对齐）
+//   2. 持有 KeepAlive 匹配用的组件名（与模块 id 一致），子模块自身不持 name
+//   3. 把 mainPage 当前语言经 :locale prop 透传给子模块的独立 i18n 实例
+//   4. 解析路由参数 /whiteboard/:boardId 并经 :boardId prop 透传给子模块（直链预填 + 切换表单）
+// 前后端分离：UI/交互在 zWhiteBoard，能力由 zTools2 的 /api/wb/* 与 /api/ws/wb/* 提供，
+// 同源 fetch/WS 自动携带 httpOnly cookie，无需 CORS。与 zPDF_package 集成范式一致。
+// 子模块独立运行时不经过本包装器，保持纯净。
 defineOptions({ name: 'whiteboard' })
+
+import { ref, computed, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
-import { appConfig, healthUrl } from '../../config/app.config.js'
+import { appConfig } from '../../config/app.config.js'
 import { useLocale } from '../../composables/useLocale.js'
-import { getLiveness } from '../../composables/useLiveness.js'
+import i18n from '../../i18n/index.js'
 import PageShell from '../../components/ui/PageShell.vue'
+import ZWbApp from '../../../third_party/zWhiteBoard/src/App.vue'

 const { t } = useLocale()
 const route = useRoute()
@@ -15,6 +24,9 @@ const router = useRouter()

 const wbConfig = appConfig.whiteboard

+// 透传父项目当前语言给子应用（响应式：切语言时子应用内容跟随）
+const locale = computed(() => i18n.global.locale.value)
+
 // 当前白板 id：优先取路由参数 /whiteboard/:boardId，否则用配置默认值
 function resolveBoardId(val) {
  const id = String(val ?? '').trim()
@@ -46,39 +58,6 @@ function submitBoard() {
    router.replace(`/whiteboard/${encodeURIComponent(id)}`)
  }
 }
-
-// 完整白板页 URL（公开，可被 iframe 嵌入）；随 currentBoardId 响应式变化
-const boardSrc = computed(
-  () => `${wbConfig.baseUrl}${wbConfig.pagePath(currentBoardId.value)}`
-)
-
-// 存活态：服务挂掉时显示降级提示（页签本身也已隐藏，但用户若直链进入仍可见）
-const aliveState = getLiveness(healthUrl('whiteboard'))
-const isDown = computed(() => aliveState.value === 'down')
-
-const loaded = ref(false)
-const failed = ref(false)
-
-// 切换白板时重置加载态
-watch(boardSrc, () => {
-  loaded.value = false
-  failed.value = false
-  scheduleFailCheck()
-})
-
-function onLoad() {
-  loaded.value = true
-}
-function scheduleFailCheck() {
-  setTimeout(() => {
-    if (!loaded.value) failed.value = true
-  }, 6000)
-}
-scheduleFailCheck()
-
-function openExternal() {
-  window.open(boardSrc.value, '_blank', 'noopener')
-}
 </script>

 <template>
@@ -104,28 +83,8 @@ function openExternal() {
      </form>
    </template>

-    <!-- 服务不可达 / iframe 加载超时降级 -->
-    <div v-if="isDown || failed" class="wb-fallback">
-      <p class="wb-fallback__text">{{ t('common.serviceUnavailable') }}</p>
-      <button type="button" class="wb-fallback__open" @click="openExternal">
-        {{ t('whiteboard.openExternal') }}
-      </button>
-    </div>
-
-    <div v-else class="wb-frame">
-      <!-- 加载骨架（iframe 加载完成后淡出） -->
-      <Transition name="fade">
-        <div v-if="!loaded" class="wb-frame__skeleton">
-          <div class="wb-frame__skeleton-text">{{ t('common.loading') }}</div>
-        </div>
-      </Transition>
-      <iframe
-        :src="boardSrc"
-        class="wb-frame__iframe"
-        frameborder="0"
-        :title="t('tabs.whiteboard')"
-        @load="onLoad"
-      />
+    <div class="whiteboard__frame">
+      <ZWbApp :locale="locale" :board-id="currentBoardId" />
    </div>
  </PageShell>
 </template>
@@ -167,78 +126,24 @@ function openExternal() {
 .wb-switch__go:hover {
  background: var(--accent-hover);
 }
-.wb-frame {
+/* 让子应用填满外壳容器，保留其内部布局自洽；记事本以编辑为主，给足高度 */
+.whiteboard__frame {
  position: relative;
  border-radius: var(--radius);
  overflow: hidden;
  box-shadow: var(--shadow);
  border: 1px solid var(--border);
-  width: 100%;
-  /* 记事本以编辑为主，给足高度 */
-  height: 70vh;
-  min-height: 480px;
  background: var(--surface);
+  height: 78vh;
+  min-height: 520px;
 }
-.wb-frame__iframe {
-  width: 100%;
-  height: 100%;
-  display: block;
-  border: 0;
-}
-.wb-frame__skeleton {
-  position: absolute;
-  inset: 0;
-  z-index: 1;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  background: var(--surface);
-}
-.wb-frame__skeleton-text {
-  color: var(--text-tertiary);
-  font-size: 0.95rem;
-}
-.wb-fallback {
-  text-align: center;
-  padding: var(--space-2xl) var(--space-lg);
-  border: 1px dashed var(--border-strong);
-  border-radius: var(--radius);
-  background: var(--surface);
-}
-.wb-fallback__text {
-  color: var(--text-secondary);
-  margin-bottom: var(--space-md);
-}
-.wb-fallback__open {
-  display: inline-flex;
-  align-items: center;
-  padding: 8px 18px;
-  font-size: 0.9rem;
-  font-weight: 500;
-  color: #fff;
-  background: var(--accent);
-  border-radius: var(--radius-sm);
-  transition: background var(--transition);
-}
-.wb-fallback__open:hover {
-  background: var(--accent-hover);
-}
-.fade-enter-active,
-.fade-leave-active {
-  transition: opacity 0.4s ease;
-}
-.fade-enter-from,
-.fade-leave-to {
-  opacity: 0;
-}
-
@media (max-width: 768px) {
  .wb-switch__input {
    width: 120px;
  }
-  .wb-frame {
-    height: 65vh;
-    min-height: 360px;
+  .whiteboard__frame {
+    height: 72vh;
+    min-height: 400px;
  }
 }
 </style>
--- a/src/modules/whiteboard/index.js
+++ b/src/modules/whiteboard/index.js
@@ -1,6 +1,9 @@
 // 模块元数据 -- 共享记事本（白板）页签
-// requiresAlive 指向存活探针 URL：启动时探测，服务不可达则隐藏该页签。
-// 删除本目录即可移除此页签，其余模块不受影响。
+// 构建期组件集成：mainPage 侧包装器 Whiteboard.vue import 子模块 zWhiteBoard 的 App.vue，
+// 套 PageShell 统一容器与标题。zWhiteBoard 作为 git submodule 独立维护，
+// 其 UI/交互经同源 fetch/WS 调用 zTools2 的 /api/wb/* 与 /api/ws/wb/*（前后端分离）。
+// requiresAlive 指向存活探针 URL：启动时探测，zTools2 不可达则隐藏该页签。
+// 升级：cd third_party/zWhiteBoard && git pull，回 mainPage 根 git add 该子模块并重新 build。
 import { healthUrl } from '../../config/app.config.js'

 export default {
--- a/src/router/index.js
+++ b/src/router/index.js
@@ -2,24 +2,17 @@
 import { createRouter, createWebHistory } from 'vue-router'
 import modules from '../modules/index.js'

-const moduleRoutes = modules
-  .map((m) => {
-    try {
-      // 模块可声明 param（如 'boardId'）以接受 /<id>/<param> 形式的子路径，
-      // 形如 /whiteboard/share。可选参数 (? 后缀) 使 /whiteboard 仍可访问。
-      const paramPart = m.param ? `/:${m.param}?` : ''
-      return {
-        path: `/${m.id}${paramPart}`,
-        name: m.id,
-        component: m.component,
-        meta: { moduleId: m.id }
-      }
-    } catch (e) {
-      console.warn(`[router] 模块 ${m?.id} 路由生成失败，已跳过：`, e)
-      return null
-    }
-  })
-  .filter(Boolean)
+const moduleRoutes = modules.map((m) => {
+  // 模块可声明 param（如 'boardId'）以接受 /<id>/<param> 形式的子路径，
+  // 形如 /whiteboard/share。可选参数 (? 后缀) 使 /whiteboard 仍可访问。
+  const paramPart = m.param ? `/:${m.param}?` : ''
+  return {
+    path: `/${m.id}${paramPart}`,
+    name: m.id,
+    component: m.component,
+    meta: { moduleId: m.id }
+  }
+})

 const routes = [
  {
--- a/src/styles/variables.css
+++ b/src/styles/variables.css
@@ -15,6 +15,14 @@
  --accent-weak: #eef2ff;
  --accent-hover: #4338ca;

+  /* 语义色（供嵌入的子项目如 timeTableFix 复用，保证嵌入时按钮/徽章可见） */
+  --success: #2e7d32;
+  --success-weak: #e8f5e9;
+  --danger: #c62828;
+  --danger-weak: #fbe9e7;
+  --warn: #e65100;
+  --warn-weak: #fff3e0;
+
  /* 线/边 */
  --border: #eceef1;
  --border-strong: #e0e2e6;
--- a/third_party/timeTableFix
+++ b/third_party/timeTableFix
--- a/third_party/z449
+++ b/third_party/z449
--- a/third_party/zPDF_package
+++ b/third_party/zPDF_package
--- a/third_party/zWhiteBoard
+++ b/third_party/zWhiteBoard
--- a/vite.config.js
+++ b/vite.config.js
@@ -1,42 +1,66 @@
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
+import { minify } from 'html-minifier-terser'
+
+// 构建到项目本地 dist/（每次清空，避免旧产物残留），
+// 再由 `npm run deploy` 或 `deploy.sh` 用 rsync 同步到 Apache 站点根 /var/www/html。
+// 文件名去掉内容 hash，保持稳定；JS 由 esbuild 压缩，HTML 由下方插件压缩。
+// 用 mainPage/ 命名空间子目录避免与 /var/www/html/js、/var/www/html/css 既有旧文件冲突。
+function minifyHtml() {
+  return {
+    name: 'minify-html',
+    apply: 'build',
+    transformIndexHtml: {
+      order: 'post',
+      handler(html) {
+        return minify(html, {
+          collapseWhitespace: true,
+          removeComments: true,
+          removeRedundantAttributes: true,
+          removeScriptTypeAttributes: true,
+          removeStyleLinkTypeAttributes: true,
+          collapseBooleanAttributes: true,
+          minifyCSS: true,
+          minifyJS: true,
+        })
+      },
+    },
+  }
+}

-// 构建产物输出到站点根 /root/html，但绝不清空该目录
-// （里面已有 448/449/js/css 等既有内容）。
-// 用 mainPage/ 命名空间子目录避免与 /root/html/js、/root/html/css 旧文件冲突。
 export default defineConfig({
-  plugins: [vue()],
+  plugins: [vue(), minifyHtml()],
  base: '/',
  build: {
-    outDir: '/root/html',
-    // ★ 安全项：不清空 outDir，保护既有文件
-    emptyOutDir: false,
+    outDir: 'dist',
+    // ★ dist 在项目内，安全清空，杜绝旧 hash 文件堆积
+    emptyOutDir: true,
    rollupOptions: {
      output: {
-        entryFileNames: 'js/mainPage/[name].[hash].js',
-        chunkFileNames: 'js/mainPage/[name].[hash].js',
+        // 稳定文件名：去掉 [hash]，便于部署与长效缓存策略
+        entryFileNames: 'js/mainPage/[name].js',
+        chunkFileNames: 'js/mainPage/[name].js',
        assetFileNames: (assetInfo) => {
          const name = assetInfo.name || ''
          if (name.endsWith('.css')) {
-            return 'css/mainPage/[name].[hash][extname]'
+            return 'css/mainPage/[name][extname]'
          }
-          return 'assets/mainPage/[name].[hash][extname]'
-        }
-      }
-    }
+          return 'assets/mainPage/[name][extname]'
+        },
+      },
+    },
  },
  server: {
-    // 开发服务器把站点根的静态资源代理到 /root/html，方便引用 /448 /449 等
    port: 5173,
    proxy: {
-      '/448': {
-        target: 'http://localhost:8080',
-        changeOrigin: true
+      // zTools2 后端同源代理：所有入口（API/静态/探针/WS）统一在 /api/ 下，一条规则即可。
+      // ws:true 让 /api/ws/wb/{id} 的 WebSocket 也走此代理。
+      // 同源相对路径与环境无关：dev 命中本地 zTools2，生产由反代命中当前环境 zTools2。
+      '/api': {
+        target: 'http://127.0.0.1:6867',
+        changeOrigin: true,
+        ws: true,
      },
-      '/449': {
-        target: 'http://localhost:8080',
-        changeOrigin: true
-      }
-    }
-  }
+    },
+  },
 })
Author	SHA1	Message	Date
zikai	25dbceee2d	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:57:32 +08:00
zikai	5b1acbdeb7	feat: 白板页签从 iframe 改为构建期组件挂载新增 zWhiteBoard 子模块（textarea + WebSocket 实时同步、心跳、断线重连）， Whiteboard.vue 改为组件包装器，经 :locale/:boardId props 透传，与 zPDF_package 范式一致。复用 zTools2 的 /api/wb/* 与 /api/ws/wb/* 接口，后端无改动；旧版 /api/wb-page/* 保留不删。清理 iframe 专用配置（pagePath）与降级文案（whiteboard.openExternal）。	2026-07-28 10:39:24 +08:00
zikai	1cc2ec1c9f	feat: 升级 zPDF_package 子模块，PDF 页签移动端兼容子模块指针 a48e601 -> cfbf4ad： - JobList 表格窄屏（≤768px）转卡片式，避免横向滚动 - Uploader 拖拽区缩小、按钮触控目标加大 - 统一移动端断点为 768px（与宿主一致）	2026-07-27 17:38:16 +08:00
zikai	4c7245f919	feat: 升级 zPDF_package 子模块，PDF 页签删除任务去掉二次确认子模块指针 4d12b61 -> a48e601： - JobList.vue 删除任务的 confirm() 二次确认弹窗移除，点击即删（软删，管理员可恢复） - i18n 移除已无引用的 deleteConfirm/deleted/deleteFailed 文案	2026-07-27 17:35:40 +08:00
zikai	ae540a1a70	feat: PDF 页签从 iframe 改为构建期组件挂载，清理 iframe 配置与文档前后端分离：UI/交互在 zPDF_package，能力由 zTools2 的 /api/pdf/* REST API 提供。组件经同源 fetch 调用，httpOnly cookie（zk_pdf）经反代第一方自动携带，无需 CORS。与 timeTableFix 集成范式完全一致。 - src/modules/pdf/Pdf.vue：iframe 包装器重写为组件挂载包装器，套 PageShell + 透传 :locale；删除 pageSrc/getLiveness/scheduleFailCheck/openExternal 等 iframe 逻辑 - src/modules/pdf/index.js：注释从 iframe 改为构建期组件 import（requiresAlive 探针保留） - src/config/app.config.js：移除 pdf.pagePath（iframe src），保留探针配置 - src/i18n/{zh-CN,en}.js：移除 pdf.openExternal（iframe 降级按钮文案，已无用） - docs/submodule-zPDF_package.md：集成方式改为构建期组件 import，补 cookie 认证说明 - docs/deployment.md：拓扑去 /api/pdf 页面行，措辞改为组件 fetch - third_party/zPDF_package：子模块指针升级到 4d12b61（去 iframe 表述）	2026-07-27 17:14:07 +08:00
zikai	304ebc9448	feat: 配置简化为同源相对路径，统一 /api/ 路由约定配合 zTools2 路由统一到 /api/，简化环境感知配置： - app.config.js：去掉 BASE_URL 的 dev/prod 分支，iframe 与探针一律用同源相对路径（/api/pdf、/api/health、/api/wb-page/{id}），默认空 baseUrl；保留 VITE_API_BASE 覆盖。这样无论 dev（vite proxy）还是任意部署环境（反代），同源相对路径都自动指向当前环境 zTools2，不再误打到 f.zikai.wang 等其它环境域名。 - vite.config.js：dev proxy 从 /api /pdf /health /static /upload /files /wb /ws 多条简化为单条 /api（含 ws:true，覆盖 /api/ws WebSocket）。 - deploy.sh：Apache vhost 从多条 ProxyPass 简化为单条 /api/，a2enmod 增加 proxy_wstunnel。 - docs/deployment.md：更新拓扑/模式说明，新增路由约定（所有入口在 /api/ 下，反代只需一条规则）。 - 同步更新 zPDF_package 子模块指针（其 vite proxy 亦简化为单条 /api）。	2026-07-27 15:44:49 +08:00
zikai	39f3056099	feat: 环境感知配置（dev 经 vite proxy 指向本地 zTools2，prod 指向 f.zikai.wang）修复 PDF 页签在开发环境返回 {"detail":"Not Found"}：此前 baseUrl 始终指向线上 f.zikai.wang，开发环境跨域访问线上既无法命中本地 /pdf 路由又会暴露生产。 - app.config.js: BASE_URL 按 import.meta.env.PROD 切换 dev -> ''（同源，经 vite proxy 转发到本地 zTools2） prod -> https://f.zikai.wang（同源） VITE_API_BASE 可显式覆盖 - vite.config.js: dev server 新增 /api /pdf /health /static /upload /files /wb /ws 代理到 127.0.0.1:6867，使 iframe 与 fetch 同源命中本地服务测试环境指向测试环境，生产环境指向生产环境。	2026-07-27 13:59:50 +08:00
zikai	66f93c67f5	feat: 新增整体部署脚本与部署指南（组件独立/整体/持久化三模式） - deploy.sh：整体部署，构建 zMainPage + rsync 到 /var/www/html + 配置 Apache 反代（/api /pdf /pdf-admin /static 等到 zTools2）+ 重启后端 - docs/deployment.md：三种部署模式文档（组件独立开发 / 整体生产 / systemd 持久化） - README：补部署指南链接	2026-07-27 13:52:40 +08:00
zikai	04f11b5432	feat: 新增 PDF 转换页签（iframe 嵌入 zTools2 /pdf，zPDF_package 子模块） mainPage 用 iframe 嵌入 zTools2 同源托管的 /pdf 页面（PDF 转换：上传 epub、进度显示、下载、用户软删/管理员硬删）。同源使 cookie 第一方生效，无需 CORS。 - src/modules/pdf/：页签模块（requiresAlive 存活校验 + iframe + 降级提示） - src/config/app.config.js：新增 pdf 服务配置（baseUrl/healthPath/pagePath） - i18n：tabs.pdf 中英文案 + pdf.openExternal - third_party/zPDF_package：git submodule（源码管理，iframe 集成非构建期编译） - docs/submodule-zPDF_package.md：集成/升级/移除文档 - README：更新结构、子模块列表、文档链接	2026-07-27 11:35:28 +08:00
zikai	3e5c1d5494	feat: 升级 timeTableFix 子模块（时区选择）+ 修正 README 构建路径 - 子模块 timeTableFix 升级至时区选择版本：加载自动检测用户时区，取不到回退墨尔本；仅作新建事件默认 tzid 与下载 ICS 的 X-WR-TIMEZONE，不换算 - 修正 README：构建输出到 dist/（非 /root/html），由 npm run deploy rsync 到站点根；补 npm run deploy 命令；细节记于 docs/readme-fixes.md - 集成构建验证通过（npm run build）	2026-07-27 09:51:43 +08:00
Zikai	1379e1a607	build: 稳定文件名去hash + HTML压缩 + deploy脚本 - vite.config.js: 文件名去掉 [hash]，输出到项目本地 dist/(emptyOutDir=true 避免旧 hash 残留堆积)；新增 html-minifier-terser 插件压缩 index.html。 - package.json: 新增 deploy 脚本，build 后用 rsync 把 dist/ 的 mainPage 命名空间子目录同步到 Apache 站点根 /root/html，--delete 仅作用于 mainPage 子目录，不误伤既有旧文件(jquery/pdf.js 等)。 - 站点始终由 Apache 静态服务(DocumentRoot /var/www/html)，无 Node 实时渲染。	2026-07-24 09:34:22 +00:00
Zikai	cb50c23c84	chore: 页脚移除 'Built with Vue 3' 字样 - 页脚仅保留版权年份，去掉技术栈宣传文字 - 同步更新 timeTableFix 子模块 gitlink(导入按钮高亮) - 移除无用的 .footer__dot 样式	2026-07-24 09:25:37 +00:00
Zikai	05a594d0cb	docs: 更新 timeTableFix 子模块 gitlink	2026-07-24 09:16:24 +00:00
Zikai	08c1b457e4	docs: 精简 README（结构/依赖/使用），更新子模块 gitlink - mainPage README 精简为结构/外部依赖/如何使用/开发命令 - 子模块 z449 (9ed486c) / timeTableFix (78d7afe) README 同步精简，细节移至各自 docs/	2026-07-24 09:15:38 +00:00
Zikai	d9309756c7	fix: 子模块 i18n 桥接 -- 透传 :locale prop，修复嵌入页显示 i18n ID 根因：子项目组件用 useI18n({useScope:'global'}) 注入，嵌入时解析到宿主 mainPage 的 i18n 实例（不含子项目文案）-> 文案回退成 key（显示 ID）。修复： - z449 / timeTableFix 组件改用 useLocale composable 直读自身模块级 i18n 实例 - ttf 新增独立 i18n（中英 locale + useLocale），抽取所有硬编码中文 - mainPage 侧 Timetable/MobileGameWrapper 包装器透传 :locale prop - 两个子模块 gitlink 更新至各自修复 commit 验证：构建后两个子模块 chunk 含真实中文文案，无 useI18n 注入残留	2026-07-24 09:02:38 +00:00
Zikai	6ad6c15e9d	feat: 拆分移动游戏项目为独立 z449 子模块（git submodule + i18n prop 桥接） - mobile-game 模块源码迁出至独立仓库 z449（third_party/z449），独立可渲染/维护 - z449 App.vue 为便携式组件：自带独立 vue-i18n 实例与 locale 文案 - mainPage 侧 MobileGameWrapper 透传 :locale prop，子模块 watch 同步语言 - mainPage i18n 精简：仅保留 tabs.mobileGame，删除 mobileGame.* 大块文案 - 文档：新增 docs/submodule-z449.md，更新 README/architecture/add-module	2026-07-23 07:04:08 +00:00
zikai	61e65052d4	fix: 补语义令牌修复嵌入页下载按钮不可见 + 停用 /ttf/ 独立入口 - variables.css 补 --success/--danger/--warn 等语义令牌：timeTableFix 嵌入时其按钮(btn-success/danger)依赖这些令牌，缺失会导致背景/边框为空、按钮不可见 - docs/submodule-timeTableFix.md 移除 /ttf/ 独立访问说明（已停用） - 升级 timeTableFix 子模块至 2d7b8d0（README 移除 systemd 部署）	2026-07-23 04:46:40 +00:00
zikai	b3960f503a	docs: 移除 systemd 部署与 /ttf/ 独立入口说明本项目仅作为 mainPage submodule 集成，无独立线上入口。保留独立开发/测试说明（npm run dev/test/build）。	2026-07-23 04:45:49 +00:00