zikai
a49a725950
- 全局重置（* / body）抽到 src/styles/global.css，仅独立 app 的 main.js 加载
- App.vue <style> 改 scoped，根及内部类名加 ttf- 前缀，避免与宿主冲突
- 根 class app -> ttf-app，min-height 改为填满容器以适配嵌入
- 加 defineOptions({ name: 'timetable' }) 供宿主 KeepAlive 匹配
- README 嵌入说明改为构建期组件集成 + git submodule
- 不影响独立运行：npm test 42 项通过，npm run build 通过
185 lines
6.5 KiB
Markdown
185 lines
6.5 KiB
Markdown
# timeTableFix - 纯前端 ICS 日历整理器
|
||
|
||
浏览器内解析、去重、编辑 ICS 日历文件，全程无需后端服务。拖入 `.ics` -> 整理去重 -> 编辑 -> 下载。
|
||
|
||
## 功能
|
||
|
||
- 拖入即用：拖拽或选择 `.ics` 文件，浏览器内直接解析
|
||
- 智能去重：检测事件间隔（每周 / 每两周 / 每 N 天），将扁平事件合并为 RRULE 重复事件 + EXDATE；交错的多班次自动拆分为多个系列
|
||
- 自动保存：所有编辑即时生效，下载时兜底序列化最新状态，无需手动保存
|
||
- 可视化编辑：编辑标题/地点/时间/重复规则，点击网格切换排除日期
|
||
- 拆分事件：把一个重复事件按日期拆成前后两段
|
||
- 增删事件：新增单次/重复事件，删除任意事件
|
||
- 导出 ICS：下载整理后的 `.ics`，可直接导入日历应用
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
timeTableFix/
|
||
├── index.html Vite 入口
|
||
├── package.json
|
||
├── vite.config.js 构建配置（含 preview.allowedHosts）
|
||
├── vitest.config.js
|
||
├── .npmrc npmmirror 镜像加速
|
||
├── src/
|
||
│ ├── main.js 应用挂载
|
||
│ ├── App.vue 布局装配
|
||
│ ├── composables/
|
||
│ │ └── useCalendar.js 中心 store（自动保存，无 undo）
|
||
│ ├── lib/
|
||
│ │ ├── weekday.js 星期常量与工具
|
||
│ │ ├── date.js 日期工具
|
||
│ │ ├── colors.js 事件配色
|
||
│ │ ├── uuid.js UUID 生成（含非安全上下文回退）
|
||
│ │ ├── ical-io.js ICS 文本 <-> plain model
|
||
│ │ ├── recur.js RRULE 网格展开
|
||
│ │ ├── organize.js 间隔去重 + 链拆分算法
|
||
│ │ ├── event-factory.js 事件构造工厂
|
||
│ │ └── split.js 事件拆分逻辑
|
||
│ └── components/
|
||
│ ├── HeaderBar.vue 顶栏：整理/导入/下载
|
||
│ ├── DropZone.vue 拖拽/选择文件
|
||
│ ├── EventList.vue 侧栏事件列表
|
||
│ ├── EventDetail.vue 编辑表单 + 拆分
|
||
│ ├── OccurrenceGrid.vue 排除日期网格
|
||
│ ├── MonthPreview.vue 月预览
|
||
│ └── WeekPreview.vue 周预览
|
||
├── test/ Vitest 单元测试
|
||
│ ├── golden-org.ics 测试用例（61 事件的真实课表）
|
||
│ ├── weekday.test.js
|
||
│ ├── ical-io.test.js
|
||
│ ├── recur.test.js
|
||
│ └── organize.test.js
|
||
└── docs/ 设计文档
|
||
├── organize-algorithm.md 间隔合并与链拆分算法详解
|
||
└── auto-save-design.md 自动保存设计
|
||
```
|
||
|
||
## Ubuntu 从零安装
|
||
|
||
### 1. 安装 Node.js 18+
|
||
|
||
```bash
|
||
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
node --version # 确认 v18.x
|
||
```
|
||
|
||
### 2. 克隆并安装依赖
|
||
|
||
```bash
|
||
git clone https://git.zikai.wang/zikai/timeTableFix.git
|
||
cd timeTableFix
|
||
npm install # 已配 npmmirror 镜像加速
|
||
```
|
||
|
||
### 3. 构建生产版本
|
||
|
||
```bash
|
||
npm run build # 产物输出到 dist/
|
||
npm test # （可选）运行单元测试
|
||
```
|
||
|
||
### 4. 部署为系统服务（systemd）
|
||
|
||
创建服务文件 `/etc/systemd/system/timetable-fix.service`：
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=timeTableFix ICS Calendar Organizer
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
WorkingDirectory=/path/to/timeTableFix
|
||
ExecStart=/path/to/timeTableFix/node_modules/.bin/vite preview --host 0.0.0.0 --port 8888
|
||
Restart=on-failure
|
||
RestartSec=3
|
||
Environment=NODE_ENV=production
|
||
StandardOutput=append:/var/log/timetable-preview.log
|
||
StandardError=append:/var/log/timetable-preview.log
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
> 将上述 `WorkingDirectory` 和 `ExecStart` 中的路径替换为实际的 `timeTableFix` 绝对路径。
|
||
|
||
加载并启动：
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now timetable-fix
|
||
```
|
||
|
||
### 5. 放行防火墙端口
|
||
|
||
```bash
|
||
sudo ufw allow 8888/tcp
|
||
```
|
||
|
||
浏览器访问 `http://<服务器IP>:8888` 即可。若通过域名访问（如 `f.zikai.wang`），需在 `vite.config.js` 的 `preview.allowedHosts` 中添加该域名。
|
||
|
||
### 6. 嵌入主页（可选）
|
||
|
||
本项目可作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的一个页签集成展示。采用**构建期组件集成 + git submodule**：
|
||
|
||
- mainPage 通过 git submodule 把本项目作为子目录（`third_party/timeTableFix`）引入，并直接 `import` 本项目的 `src/App.vue` 作为懒加载路由组件。
|
||
- 集成时共享 mainPage 的构建、依赖（`ical.js`）与 KeepAlive 缓存，不再是 iframe，无运行期割裂。
|
||
- 本项目 `App.vue` 已做样式隔离（scoped + `ttf-` 前缀类名），全局重置仅在独立 app（`main.js`）加载，作为组件嵌入时不污染宿主。
|
||
|
||
**升级流程**（mainPage 侧更新本项目到新版本）：
|
||
|
||
```bash
|
||
cd mainPage
|
||
git submodule update --remote third_party/timeTableFix # 拉取最新
|
||
cd third_party/timeTableFix && git checkout master # 固定到目标分支
|
||
cd ../..
|
||
git add third_party/timeTableFix # 更新 gitlink
|
||
git commit -m "chore: 升级 timeTableFix 子模块"
|
||
npm run build # 重新构建 mainPage
|
||
```
|
||
|
||
本项目本身完全独立：脱离 mainPage 仍可独立 `npm run build` / `npm test` / systemd 部署。移除 mainPage 中的页签仅需删其 `src/modules/timetable/` 并 `git submodule deinit`，不影响本项目。
|
||
|
||
> 旧的 iframe 嵌入方式（Apache `/ttf/` 反代到 8888）仍可保留，用于经 `https://zikai.wang/ttf/` 单独访问独立 app，与组件集成互不冲突。
|
||
|
||
## 使用（启动 / 关闭）
|
||
|
||
服务由 systemd 管理，开机自启、崩溃自动恢复。
|
||
|
||
```bash
|
||
# 启动
|
||
sudo systemctl start timetable-fix
|
||
|
||
# 关闭
|
||
sudo systemctl stop timetable-fix
|
||
|
||
# 重启
|
||
sudo systemctl restart timetable-fix
|
||
|
||
# 查看状态
|
||
sudo systemctl status timetable-fix
|
||
|
||
# 查看日志
|
||
tail -f /var/log/timetable-preview.log
|
||
```
|
||
|
||
开发模式（无需 systemd，前台运行）：
|
||
|
||
```bash
|
||
cd timeTableFix
|
||
npm run dev # http://localhost:5173
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 项 | 选择 |
|
||
|----|------|
|
||
| 框架 | Vue 3.5（SFC，`<script setup>`） |
|
||
| 构建 | Vite 6 |
|
||
| ICS 库 | ical.js 2.x |
|
||
| 状态管理 | composable 单例 store |
|
||
| 测试 | Vitest |
|
||
| 包源 | npmmirror.com（中国镜像加速） |
|