zikai
04f11b5432
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：更新结构、子模块列表、文档链接
105 lines
4.8 KiB
Markdown
105 lines
4.8 KiB
Markdown
# mainPage · 作品集主页
|
||
|
||
Zikai 的作品集主页 -- Vue 3 模块化多项目展示站。浅色极简、中英双语（英文按需懒加载）。每个项目页签是一个独立「模块」，由注册表自动生成页签与路由 -- 新增/删除页签只增删一个文件夹，互不影响。
|
||
|
||
> 架构细节、新增页签指南、子项目管理见 [`docs/`](./docs/)。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
mainPage/
|
||
├── index.html
|
||
├── package.json # 含 ical.js / vue-i18n（子模块嵌入时共享）
|
||
├── vite.config.js # 构建输出到 dist/，再由 npm run deploy rsync 到 /root/html
|
||
├── .gitmodules # git submodule：timeTableFix / z449
|
||
├── README.md
|
||
├── docs/ # 架构 / 新增页签 / 子模块管理文档
|
||
├── public/favicon.svg
|
||
├── third_party/
|
||
│ ├── timeTableFix/ # ★ git submodule：ICS 日程整理器
|
||
│ ├── z449/ # ★ git submodule：移动游戏项目展示页
|
||
│ └── zPDF_package/ # ★ git submodule：PDF 转换前端（iframe 嵌入 zTools2）
|
||
└── src/
|
||
├── main.js # 应用入口（挂载 i18n / router / 全局样式）
|
||
├── App.vue # 根布局：顶栏 + 标签导航 + <KeepAlive router-view> + 页脚
|
||
├── config/app.config.js # 集中配置：外部服务 URL（白板地址 / 存活探针等）
|
||
├── i18n/ # 国际化（中文同步注入；英文动态 import() 懒加载）
|
||
├── router/index.js # 路由表由模块注册表自动生成
|
||
├── modules/ # ★ 扩展点：每个页签一个文件夹
|
||
│ ├── index.js # 注册表（import.meta.glob 约定式收集，带容错）
|
||
│ ├── mobile-game/ # 移动游戏项目页签（包装 z449 子模块）
|
||
│ ├── whiteboard/ # 共享记事本页签（iframe 嵌入 + 存活校验）
|
||
│ ├── timetable/ # 日程整理页签（包装 timeTableFix 子模块）
|
||
│ ├── pdf/ # PDF 转换页签（iframe 嵌入 zTools2 /pdf + 存活校验）
|
||
│ └── calendar/ # 隐藏页（仅手动访问 /cqy）
|
||
├── components/ # 共享组件（TabNav / LanguageSwitcher / ui 基元含 PageShell）
|
||
├── composables/ # useProjects / useLiveness / useI18nLazy / useLocale
|
||
└── styles/ # variables.css（主题令牌）+ base.css
|
||
```
|
||
|
||
## 外部依赖
|
||
|
||
| 项 | 要求 |
|
||
|---|---|
|
||
| Node.js | ≥ 18 |
|
||
| Web 服务器 | Apache 2.4（启用 `mod_rewrite`），对外静态服务构建产物 |
|
||
| SPA 回退 | history 模式需站点根 `.htaccess` 回退到 `index.html` |
|
||
| 共享记事本 | iframe 嵌入外部服务 `https://f.zikai.wang`（URL 在 `src/config/app.config.js` 配置） |
|
||
|
||
> 子模块（timeTableFix / z449）为构建期组件集成（非 iframe），共享 mainPage 的构建与 KeepAlive 缓存。
|
||
|
||
## 如何使用
|
||
|
||
```bash
|
||
# 1. 安装 Node.js 18
|
||
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo bash -
|
||
sudo apt-get install -y nodejs
|
||
|
||
# 2. 取代码（含子模块 timeTableFix / z449）
|
||
git clone --recursive https://git.zikai.wang/zikai/zMainPage.git mainPage
|
||
cd mainPage
|
||
# 若已 clone 但未带子模块：git submodule update --init --recursive
|
||
npm install
|
||
# 子模块需各自安装依赖（构建期编译其 .vue）
|
||
(cd third_party/z449 && npm install)
|
||
(cd third_party/timeTableFix && npm install)
|
||
|
||
# 3. 构建到 dist/（再由 npm run deploy rsync 同步到 /root/html）
|
||
npm run build
|
||
|
||
# 4. 安装并启用 Apache
|
||
sudo apt-get install -y apache2
|
||
sudo a2enmod rewrite
|
||
```
|
||
|
||
站点根放 `.htaccess`（Apache 需 `AllowOverride All`）做 SPA 回退：
|
||
|
||
```apache
|
||
RewriteEngine On
|
||
RewriteCond %{REQUEST_FILENAME} -f [OR]
|
||
RewriteCond %{REQUEST_FILENAME} -d
|
||
RewriteRule ^ - [L]
|
||
RewriteRule ^ index.html [L]
|
||
```
|
||
|
||
把 `/root/html`（或 `/var/www/html`）设为 `DocumentRoot`，访问站点即可。
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
npm install # 首次安装依赖
|
||
npm run dev # 开发服务器 http://localhost:5173
|
||
npm run build # 构建到 dist/
|
||
npm run deploy # 构建并 rsync 同步到 /root/html
|
||
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 + iframe 同源集成）](./docs/submodule-zPDF_package.md)
|
||
- [README 勘误记录](./docs/readme-fixes.md)
|