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 记录本次勘误
This commit is contained in:
@@ -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')
|
||||
}
|
||||
```
|
||||
|
||||
@@ -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` 具名插槽，放在标题旁（如白板的切换白板表单）
|
||||
|
||||
@@ -59,8 +59,10 @@ export default {
|
||||
|
||||
部分页签由独立仓库的子项目经 git submodule 集成，mainPage 侧用包装器 import 子项目 `App.vue` 作为路由组件（非 iframe），共享构建与 KeepAlive 缓存：
|
||||
|
||||
- **timeTableFix**（`third_party/timeTableFix`，日程整理页签）：自带独立 `vue-i18n` 实例与中英 locale 文案。与 z449 同样经 `:locale` prop 桥接父项目语言。详见 [submodule-timeTableFix.md](./submodule-timeTableFix.md)。
|
||||
- **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 而非文字）。
|
||||
|
||||
@@ -72,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`。
|
||||
|
||||
## 路由
|
||||
|
||||
@@ -85,4 +88,4 @@ export default {
|
||||
|
||||
## 集中配置
|
||||
|
||||
`src/config/app.config.js` -- 外部服务 URL（白板地址、存活探针路径等）集中管理，模块按需 import。改 URL 只改这里（需重新 build）。
|
||||
`src/config/app.config.js` -- 各服务的同源探针路径（`/api/health`）与默认参数集中管理，模块按需 import。改路径只改这里（需重新 build）。
|
||||
|
||||
@@ -16,7 +16,7 @@ zPDF_package 功能涉及三个项目协同：**zMainPage**（父站，Vue3 静
|
||||
|
||||
PDF 页签 = zMainPage 构建期 import zPDF_package 的 `App.vue` 作为组件（非 iframe），经同源 fetch 调用 zTools2 的 `/api/pdf/*` REST API（**同源相对路径**，cookie 第一方生效，与环境无关）。
|
||||
|
||||
> **路由约定**：zTools2 所有入口（页面 / 静态 / 探针 / WS / API）统一挂在 `/api/` 下，反代与 vite proxy 只需一条 `/api/` 规则。前端（无论是 iframe 嵌入页还是组件 fetch API）一律用同源相对路径（`/api/pdf/jobs`、`/api/health` 等），自动指向**当前环境**的 zTools2，无需区分 dev/prod，也不会误打到其它环境域名。详见 zTools2 README「路由约定」。
|
||||
> **路由约定**：zTools2 所有入口（页面 / 静态 / 探针 / WS / API）统一挂在 `/api/` 下，反代与 vite proxy 只需一条 `/api/` 规则。前端组件经同源相对路径（`/api/pdf/jobs`、`/api/health` 等）调用，自动指向**当前环境**的 zTools2，无需区分 dev/prod，也不会误打到其它环境域名。详见 zTools2 README「路由约定」。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -18,3 +18,36 @@
|
||||
**修正**：三处均改为说明构建输出到 `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 各文件同步修正。
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -61,4 +61,4 @@ git commit -m "chore: 移除 zPDF_package 子模块集成"
|
||||
| cookie | 不涉及 | httpOnly `zk_pdf`，同源自动携带（首次上传种下） |
|
||||
| mainPage 是否编译子模块 | 是（import .vue） | 是（import .vue） |
|
||||
|
||||
> 三个子项目（timeTableFix / z449 / zPDF_package）均采用构建期组件 import 集成，无 iframe。zPDF_package 额外依赖 zTools2 后端 API，页签带存活探针。
|
||||
> 四个子项目（timeTableFix / z449 / zPDF_package / zWhiteBoard）均采用构建期组件 import 集成，无 iframe。zPDF_package 与 zWhiteBoard 额外依赖 zTools2 后端 API，页签带存活探针。
|
||||
|
||||
72
docs/submodule-zWhiteBoard.md
Normal file
72
docs/submodule-zWhiteBoard.md
Normal file
@@ -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 与路由参数的子模块。
|
||||
Reference in New Issue
Block a user