557 lines
24 KiB
Markdown
557 lines
24 KiB
Markdown
# timeTable2 - 纯前端 ICS 日历整理与编辑器
|
||
|
||
**日期**: 2026-07-13
|
||
**状态**: 设计已定稿，待用户复核
|
||
**位置**: `D:\zcode\timeTable2`（与 `D:\zcode\timeTable` 平级，独立 git 仓库）
|
||
|
||
---
|
||
|
||
## 1. 目标与范围
|
||
|
||
### 1.1 目标
|
||
|
||
构建一个**纯前端**（HTML + JS + CSS，无 Python、无后端服务）的 ICS 日历应用，实现：
|
||
|
||
1. **解析**：浏览器内读取任意 `.ics` 文件（支持 VTIMEZONE、RRULE、EXDATE）
|
||
2. **去重整理**：将"每周相同却被导出为 N 个独立事件"的扁平列表，自动合并为带 `RRULE` + `EXDATE` 的重复事件
|
||
3. **编辑**：可视化编辑每个事件（标题/地点/描述/时间/重复规则/排除日期）
|
||
4. **增删拆**：手动新增事件、删除事件、把一个已合并的重复事件按日期拆成两段
|
||
5. **导出**：编辑完成后下载整理好的 `.ics`
|
||
|
||
用户全程通过拖拽/选择文件进入，编辑完成后下载，**无需任何命令行或服务器**。
|
||
|
||
### 1.2 范围边界
|
||
|
||
**包含**：
|
||
- Vite + Vue3（SFC，`<script setup>`）工程化项目
|
||
- ical.js 仅用于 ICS 文本解析与序列化
|
||
- 移植 `timeTable/ical_organizer.py` 的 GCD 去重算法到纯 JS
|
||
- 移植 `timeTable/ical_editor.py` 的 RRULE 网格展开逻辑到纯 JS
|
||
- 单一中心 store + 快照式 undo/redo
|
||
- 与 `timeTable/editor.html` 一致的深色顶栏 + 白色侧栏 + 绿/红网格视觉风格
|
||
|
||
**不包含**：
|
||
- Python 任何依赖（纯前端）
|
||
- `recurring-ical-events` 等服务端展开库（用自写网格生成器替代）
|
||
- 多用户/多文件会话（单文件、单会话工具）
|
||
- 移动端原生适配（桌面优先，但布局响应式不崩）
|
||
|
||
### 1.3 与 timeTable 的关系
|
||
|
||
`timeTable`（Python 版）保持不动。`timeTable2` 是平级的全新项目，目标是"零安装、双击即用"的等价能力。算法逻辑从 Python 1:1 移植，确保行为一致（同一 `org.ics` 输入应产出与 `ical_organizer.py` 等价的合并结果）。
|
||
|
||
---
|
||
|
||
## 2. 技术栈与依赖
|
||
|
||
| 项 | 选择 | 说明 |
|
||
|----|------|------|
|
||
| 框架 | Vue 3.5+ | SFC，`<script setup>` 语法 |
|
||
| 构建 | Vite 6+ | `npm create vite@latest` |
|
||
| ICS 库 | ical.js | 唯一外部依赖，仅用 `ICAL.parse` / `ICAL.Component` / `ICAL.Time` 做文本↔对象转换 |
|
||
| UI 库 | 无 | 组件自带 scoped CSS，复用 `editor.html` 视觉风格 |
|
||
| 状态管理 | composable（无 Pinia） | `useCalendar.js` 单例 reactive store |
|
||
| 包源 | npmmirror.com | 中国镜像加速，配 `.npmrc` |
|
||
| Node | v24.14.0（本机） | 要求 Node 20+ |
|
||
| 版本控制 | git | `D:\zcode\timeTable2` 独立 `git init` |
|
||
|
||
`.npmrc` 内容：
|
||
```
|
||
registry=https://registry.npmmirror.com
|
||
```
|
||
|
||
`package.json` 依赖：
|
||
- `vue`: ^3.5
|
||
- `ical.js`: ^2.1
|
||
|
||
devDependencies：
|
||
- `vite`: ^6
|
||
- `@vitejs/plugin-vue`: ^5
|
||
|
||
无其他依赖。
|
||
|
||
---
|
||
|
||
## 3. 项目结构
|
||
|
||
```
|
||
timeTable2/
|
||
├── .gitignore
|
||
├── .npmrc # npmmirror 镜像
|
||
├── index.html # Vite 入口
|
||
├── package.json
|
||
├── vite.config.js
|
||
├── README.md
|
||
├── public/ # （可空，留作 favicon 等）
|
||
├── docs/
|
||
│ └── superpowers/specs/
|
||
│ └── 2026-07-13-timetable2-design.md # 本文件
|
||
└── src/
|
||
├── main.js # createApp 挂载
|
||
├── App.vue # 布局与装配
|
||
├── composables/
|
||
│ └── useCalendar.js # 中心 store + 快照 undo/redo
|
||
├── lib/
|
||
│ ├── ical-io.js # ICS 文本 <-> plain model（ical.js 封装）
|
||
│ ├── organize.js # GCD 去重算法（移植 ical_organizer.py）
|
||
│ ├── recur.js # RRULE 网格展开 / EXDATE 重算
|
||
│ └── weekday.js # DOW 数组、BYDAY 映射、weekday 工具
|
||
└── components/
|
||
├── HeaderBar.vue # 顶栏：整理/撤销/重做/导入/下载/dirty 标记
|
||
├── DropZone.vue # 拖拽/选择文件落地区
|
||
├── EventList.vue # 侧栏事件列表 + 新增按钮
|
||
├── EventDetail.vue # 右侧编辑表单 + 工具栏
|
||
└── OccurrenceGrid.vue # 排除日期网格（绿/红切换）
|
||
```
|
||
|
||
### 分层依赖（自下而上，单向）
|
||
|
||
```
|
||
lib/weekday.js 纯常量与工具，无依赖
|
||
lib/ical-io.js 依赖 ical.js + weekday.js
|
||
lib/recur.js 依赖 weekday.js
|
||
lib/organize.js 依赖 recur.js + weekday.js
|
||
composables/useCalendar.js 依赖 lib/* 全部
|
||
components/* 仅依赖 useCalendar，纯展示 + 调 store action
|
||
App.vue 组装 components
|
||
```
|
||
|
||
`lib/` 全部是**纯函数**：入参为 plain object，返回 plain object，无副作用，可独立单元测试。
|
||
|
||
---
|
||
|
||
## 4. 数据模型
|
||
|
||
### 4.1 CalendarMeta
|
||
|
||
```js
|
||
{
|
||
prodid: '-//Allocate//iCal4j 1.0//EN',
|
||
version: '2.0',
|
||
calscale: 'GREGORIAN',
|
||
method: 'PUBLISH' | null,
|
||
xWrCalname: string | null,
|
||
xWrTimezone: string | null,
|
||
vtimezones: [ /* 原始 VTIMEZONE 组件的 jCal 数组，原样透传 */ ],
|
||
}
|
||
```
|
||
|
||
### 4.2 EventModel（plain，Vue 响应式友好）
|
||
|
||
```js
|
||
{
|
||
uid: 'uid0' | crypto.randomUUID(),
|
||
summary: 'ACC INFO SYS, Tutorial',
|
||
location: 'CA_B_B471',
|
||
description: 'ACF2400_CA_S2_ON-CAMPUS...',
|
||
dtstartDate: '2026-07-27', // YYYY-MM-DD
|
||
dtstartTime: '18:00', // HH:MM
|
||
dtendTime: '20:00', // HH:MM
|
||
tzid: 'Australia/Melbourne', // 时区标识，UTC 或 TZID
|
||
rrule: { // null 表示单次事件
|
||
freq: 'WEEKLY' | 'DAILY',
|
||
interval: 1,
|
||
byday: 'MO' | 'TU' | ... | 'SU', // 仅 WEEKLY 有意义
|
||
untilDate: '2026-10-19', // YYYY-MM-DD（墙钟语义）
|
||
} | null,
|
||
exdates: ['2026-09-21', ...], // YYYY-MM-DD 数组
|
||
_raw: { // 未建模属性原样透传，零数据丢失
|
||
dtstamp: '20260711T085008Z',
|
||
// 其他 X- 属性、ATTENDEE 等
|
||
},
|
||
}
|
||
```
|
||
|
||
设计要点：
|
||
- **墙钟语义**：`dtstartDate/Time`、`untilDate`、`exdates` 全部是用户看到的本地墙钟值，不带时区计算。时区信息保存在 `tzid` 中，序列化时由 ical.js 处理。
|
||
- **UNTIL 存储为墙钟日期**，序列化到 ICS 时转 UTC（RFC 5545 要求 UNTIL 用 UTC，如 `20261019T070000Z`）。转换：用 `tzid` 把 `untilDate 23:59` 当作该时区时刻 -> UTC。
|
||
- **EXDATE 存储为墙钟日期**，序列化时用 `dtstartTime` + `tzid` 还原为带 TZID 的 `EXDATE;TZID=...:20260921T180000`。
|
||
- **`_raw` 透传**：除已建模字段外的所有属性（DTSTAMP、X-* 等）原样保留并回写，确保编辑后导出的 ICS 不丢字段。
|
||
|
||
### 4.3 StoreState
|
||
|
||
```js
|
||
{
|
||
meta: CalendarMeta,
|
||
events: EventModel[],
|
||
selectedUid: string | null,
|
||
history: [ deepClone(state) ], // 快照栈，上限 50
|
||
redoStack: [ deepClone(state) ],
|
||
fileName: 'org.ics' | null,
|
||
dirty: boolean, // 有未保存变更
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 模块设计
|
||
|
||
### 5.1 `lib/weekday.js`
|
||
|
||
```js
|
||
export const DOW = ['周日','周一','周二','周三','周四','周五','周六'];
|
||
// JS getDay() 索引：0=周日 .. 6=周六
|
||
export const DOW_EN = ['SU','MO','TU','WE','TH','FR','SA'];
|
||
// 索引与 DOW 一致：BYDAY_MAP[getDay()] => 'SU'..'SA'
|
||
export const BYDAY_TO_INDEX = { SU:0, MO:1, TU:2, WE:3, TH:4, FR:5, SA:6 };
|
||
export function bydayFromDate(date) { return DOW_EN[date.getDay()]; }
|
||
export function dowLabel(date) { return DOW[date.getDay()]; }
|
||
```
|
||
|
||
**关键决定**：全项目统一使用 JS `getDay()`（0=周日），避免 Python `weekday()`（0=周一）的映射问题。BYDAY 数组直接按 `getDay` 索引，无需转换。这是与 `timeTable/editor.html` 里 `pyWeekdayToJs` hack 的根本区别——新项目从一开始就用对齐的索引。
|
||
|
||
### 5.2 `lib/ical-io.js`
|
||
|
||
```js
|
||
export function parseICS(text) -> { meta: CalendarMeta, events: EventModel[] }
|
||
export function serializeICS({ meta, events }) -> string
|
||
```
|
||
|
||
**parseICS 流程**：
|
||
1. `ICAL.parse(text)` -> jCal 根数组
|
||
2. `new ICAL.Component(root)` -> 遍历子组件
|
||
3. VTIMEZONE 组件：把 jCal 子数组原样 push 到 `meta.vtimezones`（不解析内部）
|
||
4. VEVENT 组件：`new ICAL.Event(component)` 提取字段
|
||
- `summary/location/description`：字符串
|
||
- `dtstart`：`ICAL.Time` -> `dtstartDate/Time`（取 `year/month/day/hour/minute`）；`tzid` 从 `component.getFirstProperty('dtstart').getParameter('tzid')` 取，无则 `'UTC'`
|
||
- `dtend`：同上取时间
|
||
- `rrule`：`event.component.getFirstPropertyValue('rrule')` -> `ICAL.Recur` -> 转 `{freq, interval, byday, untilDate}`。`until` 是 `ICAL.Time`，按其 `zone` 转 `untilDate` 墙钟。
|
||
- `exdates`：遍历所有 `EXDATE` 属性，每个 `ICAL.Time` -> `YYYY-MM-DD`
|
||
- `_raw`：DTSTAMP 及其他未建模属性，存为 `{ propName: rawValue }`
|
||
5. meta：`prodid/version/calscale/method` 从 `component.getFirstPropertyValue(name)` 取；`x-wr-calname/x-wr-timezone` 用全小写属性名取
|
||
6. 返回 `{meta, events}`
|
||
|
||
**serializeICS 流程**：
|
||
1. `new ICAL.Component(['vcalendar', [], []])`
|
||
2. 添加 meta 标量属性（prodid/version/calscale/method/x-wr-calname/x-wr-timezone）
|
||
3. 把 `meta.vtimezones` 每个 jCal 数组 `addComponent` 回去
|
||
4. 每个 EventModel -> 构造 VEVENT 子组件：
|
||
- SUMMARY/LOCATION/DESCRIPTION：`addPropertyWithValue`
|
||
- DTSTART：`new ICAL.Time({...dtstartDate/Time}, ICAL.TimezoneService.get(tzid))`，set TZID 参数
|
||
- DTEND：同上
|
||
- RRULE（若 rrule 非空）：`new ICAL.Recur({freq, interval, byday, until})`。`until` 用 `new ICAL.Time(untilDate 23:59, tz).convertToZone(ICAL.Timezone.utcTimezone)`
|
||
- EXDATE：每个 `exdates[i]` -> `new ICAL.Time({date + dtstartTime}, tz)`，`addPropertyWithValue('exdate', time)` 并 set TZID
|
||
- DTSTAMP：从 `_raw` 取或用 `now UTC`
|
||
- 其他 `_raw` 属性：原样回写
|
||
5. `component.toString()` -> ICS 文本
|
||
|
||
### 5.3 `lib/recur.js`
|
||
|
||
```js
|
||
export function expandOccurrences(ev) -> [{ date:'YYYY-MM-DD', skipped:boolean }]
|
||
export function intervalDays(ev) -> number // DAILY->interval, WEEKLY->7*interval
|
||
```
|
||
|
||
**expandOccurrences**（移植 `ical_editor.py` 的网格生成）：
|
||
- 单次事件（`rrule === null`）：返回 `[{date: ev.dtstartDate, skipped:false}]`
|
||
- 重复事件：
|
||
- `step = intervalDays(ev)`
|
||
- `cur = new Date(ev.dtstartDate)`，`until = new Date(ev.untilDate)`
|
||
- `exdateSet = new Set(ev.exdates)`
|
||
- 循环 `while cur <= until && count < 500`：`push {date: toISO(cur), skipped: exdateSet.has(date)}`，`cur += step 天`
|
||
- 返回数组
|
||
|
||
> 注：原 Python 版有 `regenerateOccurrences`（UNTIL 变化时保留 skip 状态）。新设计里 occurrences 完全按需从 `exdates` 推导，UNTIL 变化只需重新渲染网格，exdates 本身不变（超出新 UNTIL 的 exdate 仍在数组里但不被网格显示，序列化时无副作用）。因此无需 `regenerateOccurrences`。
|
||
|
||
### 5.4 `lib/organize.js`（移植 `ical_organizer.py`）
|
||
|
||
```js
|
||
export function seriesKey(ev) -> string
|
||
export function detectInterval(startDates) -> number | null
|
||
export function fitSeries(evs) -> { base, rrule, exdates } | null
|
||
export function organize(events) -> { events: EventModel[], stats: {series, flat} }
|
||
```
|
||
|
||
**seriesKey(ev)**：`[summary, location, dtstartTime, durationMin, weekday(getDay)]` join。与 Python 版一致（除 weekday 用 getDay 而非 Python weekday，但分组效果相同——同一天的事件归一组）。
|
||
|
||
**detectInterval(startDates)**：
|
||
- `<2` 个 -> `null`
|
||
- 算连续日期间隔（天）的 GCD；GCD=0 -> `null`
|
||
- 返回 GCD
|
||
|
||
**fitSeries(evs)**（移植 `ical_organizer.fit_series`）：
|
||
1. `starts = evs.sort(by dtstartDate)`
|
||
2. `interval = detectInterval(starts)`，null -> 拒绝
|
||
3. `first=starts[0], last=starts[-1]`
|
||
4. 构建期望网格 `first..last step interval`：`expected[]`
|
||
5. `missing = expected 中不在 present 的`；`offGrid = present 中不在 expected 的`
|
||
6. 有 offGrid -> 拒绝（事件不在规律网格上）
|
||
7. "大多数规律"：`evs.length < 2` 或 `missing.length >= evs.length` -> 拒绝
|
||
8. 构造 rrule：
|
||
- `interval % 7 == 0` -> `freq='WEEKLY', interval=interval/7, byday=bydayFromDate(first)`
|
||
- 否则 -> `freq='DAILY', interval=interval, byday=null`
|
||
- `untilDate = last.dtstartDate`
|
||
9. `exdates = missing` 的日期
|
||
10. 返回 `{base: evs[0], rrule, exdates}`
|
||
|
||
**organize(events)**（移植 `ical_organizer.organize`）：
|
||
1. 按 `seriesKey` 分组
|
||
2. 每组排序后调 `fitSeries`：
|
||
- 成功 -> 输出 1 个合并事件（**保留 base 的原始 UID**，而非 Python 的重新分配——避免重新导入时 UID 冲突）
|
||
- 失败 -> 原样输出每个事件
|
||
3. 返回 `{events, stats:{series:N, flat:M}}`
|
||
|
||
**与 Python 版的差异**：
|
||
- UID 策略：保留原始 UID（Python 版重新分配 `uid0..uidN`）。原因：合并后的事件沿用其首次出现的 UID，日历客户端更稳定，且重新整理同一文件结果幂等。
|
||
- weekday 索引：用 `getDay`（0=周日），但仅用于分组键，不影响合并正确性。
|
||
- 其余算法 1:1 一致。
|
||
|
||
### 5.5 `composables/useCalendar.js`
|
||
|
||
单例 store（模块级 `reactive` + `export function useCalendar()` 返回同一实例）。
|
||
|
||
**状态**：见 4.3。
|
||
|
||
**Actions**（每个 mutation 前先 `_pushHistory()` 快照）：
|
||
|
||
| Action | 行为 |
|
||
|--------|------|
|
||
| `loadFile(file: File)` | 读 text -> `parseICS` -> 设 meta/events/fileName，清 history/dirty，selectedUid=null |
|
||
| `organize()` | `events = organize(events).events`，设 dirty |
|
||
| `updateEvent(uid, patch)` | 找到 event，浅合并 patch，设 dirty |
|
||
| `deleteEvent(uid)` | 过滤掉，selectedUid 清空，设 dirty |
|
||
| `addEvent()` | 新建单次事件（dtstart=今天，UID=`crypto.randomUUID()`，DTSTAMP=now UTC），push 并选中，设 dirty |
|
||
| `splitEvent(uid, splitDate)` | 见下，设 dirty |
|
||
| `toggleOccurrence(uid, date)` | 切换某 occurrence 的 skipped：若 date 在 exdates 中则移除，否则加入。设 dirty |
|
||
| `undo()` | redoStack.push(当前)，state = history.pop() |
|
||
| `redo()` | history.push(当前)，state = redoStack.pop() |
|
||
| `serialize()` | `serializeICS({meta, events})` -> 字符串 |
|
||
| `markSaved()` | dirty=false |
|
||
|
||
**occurrences 不是持久字段**：EventModel（§4.2）不存 occurrences。`OccurrenceGrid` 渲染时实时调 `expandOccurrences(ev)` 计算，切换 skipped 走 `toggleOccurrence` 直接改 `exdates`。这样无需在 updateEvent 里维护缓存，避免缓存与 exdates 不同步。`updateEvent` 只做浅合并 patch，不碰 occurrences。
|
||
|
||
**快照机制**：`_pushHistory()` = `history.push(structuredClone({meta, events, selectedUid}))`，超 50 截断尾部；清空 redoStack。`structuredClone` 在 Node/浏览器均可用，能深拷贝纯数据 plain object（store 里只有 plain object + 字符串，无函数/循环引用）。
|
||
|
||
**splitEvent(uid, splitDate)** 逻辑：
|
||
1. 取原事件 `ev`，要求 `ev.rrule` 非空（单次事件不可拆）
|
||
2. `splitDate` 必须在 `dtstartDate < splitDate <= untilDate` 内
|
||
3. 若 `splitDate` 不在网格上，`snap` 到 ≥ splitDate 的下一个网格点
|
||
4. **Part A**（前半段）：
|
||
- 复制 ev
|
||
- `rrule.untilDate = (splitDate - intervalDays)` 的前一个网格点日期
|
||
- `exdates = exdates.filter(d => d < splitDate)`
|
||
5. **Part B**（后半段）：
|
||
- 复制 ev
|
||
- `dtstartDate = snapPoint`（网格对齐后的 split 日期）
|
||
- `rrule` 保持 freq/interval/byday，`untilDate` = 原 untilDate
|
||
- `exdates = exdates.filter(d => d >= splitDate)`
|
||
- `uid = crypto.randomUUID()`（新 UID）
|
||
6. 替换原事件为 `[A, B]`，选中 B
|
||
7. 用户随后可分别编辑两段（如后半段换教室）
|
||
|
||
---
|
||
|
||
## 6. UI 组件设计
|
||
|
||
视觉风格移植 `timeTable/editor.html`：深色顶栏 `#2c3e50`、白色侧栏、绿/红网格、圆角按钮。所有 CSS 用 SFC `<style scoped>`。
|
||
|
||
### 6.1 `App.vue`
|
||
|
||
布局：
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ HeaderBar │
|
||
├──────────┬──────────────────────────────────┤
|
||
│ │ │
|
||
│ EventList│ EventDetail / DropZone / Empty │
|
||
│ │ │
|
||
└──────────┴──────────────────────────────────┘
|
||
```
|
||
- 未加载文件：主区显示 `DropZone`
|
||
- 已加载、未选中：主区显示"从左侧选择"空状态
|
||
- 已选中：主区显示 `EventDetail`
|
||
|
||
### 6.2 `HeaderBar.vue`
|
||
|
||
- 左：标题「📅 ICS 日程整理器」
|
||
- 右按钮组：
|
||
- 「整理去重」（调用 `organize()`，按钮 disabled 当无事件或已全部为重复事件——简单判断：所有事件 rrule 非空时禁用，提示"已无可合并的重复"）
|
||
- 「↶ 撤销」「↷ 重做」（disabled 据 history/redoStack 长度）
|
||
- 「📥 导入文件」（触发隐藏 `<input type=file>`）
|
||
- 「⬇ 下载 ICS」（dirty 时弹确认"有未保存更改，仍要下载？"）
|
||
- dirty 红点标记
|
||
|
||
### 6.3 `DropZone.vue`
|
||
|
||
- 大虚线框，文字"拖入 .ics 文件 或 点击选择"
|
||
- `dragover` 高亮，`drop` 读 `e.dataTransfer.files[0]`
|
||
- 点击触发隐藏 `<input type=file accept=".ics">`
|
||
- 解析失败：红字提示错误 + 保留 drop 区
|
||
|
||
### 6.4 `EventList.vue`
|
||
|
||
- 顶栏统计：「共 N 个日程（X 重复 / Y 单次）」
|
||
- 「➕ 新增日程」按钮（调用 `addEvent()`）
|
||
- 列表项：标题 + 徽章（重复=绿/单次=橙）+ `DOW[weekday] 时间–时间 · 地点`
|
||
- 点击选中（`selectedUid`），高亮左边框
|
||
- weekday 显示：`DOW[new Date(ev.dtstartDate).getDay()]`（直接用 getDay 索引 DOW，无转换）
|
||
|
||
### 6.5 `EventDetail.vue`
|
||
|
||
表单分三区：
|
||
|
||
**基本信息**：SUMMARY（text）、开始时间（time）、结束时间（time）、LOCATION（text）、DESCRIPTION（textarea）
|
||
|
||
**重复规则（RRULE）**：
|
||
- 「启用重复」复选框
|
||
- 启用后显示：频率（WEEKLY/DAILY select）、间隔（number）、重复到 UNTIL（date）、星期 BYDAY（仅 WEEKLY，select DOW_EN）
|
||
- 改 UNTIL/BYDAY/INTERVAL 后，「应用更改」时 patch 进 store，网格因 exdates/rrule 响应式自动重算
|
||
|
||
**工具栏**：
|
||
- 「应用更改」（把表单值 patch 到 store）
|
||
- 「拆分此日程」（仅重复事件显示；点击展开日期选择器 + 确认）
|
||
- 「删除此日程」（确认对话框）
|
||
|
||
### 6.6 `OccurrenceGrid.vue`
|
||
|
||
- props: `occurrences: [{date, skipped}]`
|
||
- 网格 `grid-template-columns: repeat(auto-fill, minmax(140px, 1fr))`
|
||
- 每格：日期 + 小字星期（`DOW[new Date(date).getDay()]`）
|
||
- 绿色=active，红色删除线=skipped
|
||
- 点击切换 skipped（emit 事件让父组件调 `store.toggleOccurrence(uid, date)`，该 action 直接增删 `exdates` 数组中的该日期）
|
||
- 上限 500 格，超出截断 + 提示
|
||
|
||
---
|
||
|
||
## 7. 数据流
|
||
|
||
### 7.1 加载
|
||
|
||
```
|
||
用户拖入 file
|
||
-> DropZone.drop / input.change
|
||
-> file.text()
|
||
-> ical-io.parseICS(text)
|
||
-> store.loadFile({meta, events})
|
||
-> 渲染 EventList
|
||
```
|
||
|
||
### 7.2 整理去重
|
||
|
||
```
|
||
点击「整理去重」
|
||
-> store.organize()
|
||
-> lib/organize.organize(events)
|
||
-> 替换 events，push history
|
||
-> 渲染刷新
|
||
```
|
||
|
||
### 7.3 编辑
|
||
|
||
```
|
||
表单修改 -> 点击「应用更改」
|
||
-> store.updateEvent(uid, patch)
|
||
-> push history，dirty=true
|
||
-> EventDetail 刷新（网格实时调 expandOccurrences 重算）
|
||
```
|
||
|
||
### 7.4 拆分
|
||
|
||
```
|
||
点击「拆分」-> 选 splitDate -> 确认
|
||
-> store.splitEvent(uid, splitDate)
|
||
-> 原事件替换为 [A, B]
|
||
-> 选中 B
|
||
```
|
||
|
||
### 7.5 导出
|
||
|
||
```
|
||
点击「下载 ICS」
|
||
-> 若 dirty 弹确认
|
||
-> store.serialize()
|
||
-> Blob -> <a download> 触发下载
|
||
-> 文件名：原 fileName 去扩展 + '.edited.ics'（如 org.edited.ics）
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 错误处理
|
||
|
||
| 场景 | 处理 |
|
||
|------|------|
|
||
| 拖入非 .ics / 解析失败 | DropZone 红字提示，保留落地区，不清空已有状态 |
|
||
| DTSTART 缺失的 VEVENT | parseICS 跳过该事件，控制台 warn，不阻断其余 |
|
||
| ical.js 不识别的属性 | 收进 `_raw` 原样回写，不丢 |
|
||
| 无时区信息的事件 | tzid 默认 `'UTC'` |
|
||
| organize 后无变化 | toast「未发现可合并的重复模式」 |
|
||
| split 日期不在范围内 | 表单校验红字，不执行 |
|
||
| undo 栈空 | 按钮已 disabled，理论不可触发 |
|
||
| 文件超大（>5MB） | 解析前提示「文件较大，解析可能较慢」，不阻断 |
|
||
|
||
错误展示统一用 toast（右下角，3 秒淡出），复用 `editor.html` 的 `.toast` 样式。
|
||
|
||
---
|
||
|
||
## 9. 测试策略
|
||
|
||
`lib/` 是纯函数，重点单测：
|
||
|
||
- **organize.js**：用 `timeTable/org.ics` 的期望结果作黄金用例（61 事件 -> 5 重复 + 3 单次，与 Python `--verify` 一致）。但因 UID 策略不同，比对时忽略 UID，比对 (summary, dtstart, rrule, exdates)。
|
||
- **recur.js**：给定 rrule+exdates，展开网格与 Python 版 `event_to_dict` 的 `occurrences` 字段逐项比对。
|
||
- **ical-io.js round-trip**：parse(serialize(parse(text))) == parse(text)（结构等价）。
|
||
|
||
测试框架：Vitest（devDependency）。若用户不想加测试依赖，至少写一个 `npm run check` 脚本跑黄金比对。
|
||
|
||
> 决定：加入 Vitest 作为 devDependency，确保移植正确性可自动验证。
|
||
|
||
---
|
||
|
||
## 10. Git 工作流
|
||
|
||
1. `cd D:\zcode\timeTable2 && git init`
|
||
2. `.gitignore`：`node_modules/`、`dist/`、`.vite/`、`*.log`
|
||
3. 首个 commit：脚手架（package.json / vite.config / index.html / main.js / 空 App.vue）
|
||
4. 后续按模块 commit：lib/weekday -> lib/ical-io -> lib/recur -> lib/organize -> useCalendar -> 各组件 -> README
|
||
5. 每个 commit 信息：`feat: ...` / `fix: ...` / `docs: ...`
|
||
6. spec 文档（本文件）单独 commit：`docs: add design spec`
|
||
|
||
---
|
||
|
||
## 11. 开放决定（已自决）
|
||
|
||
| 问题 | 决定 | 理由 |
|
||
|------|------|------|
|
||
| UID 策略 | 合并后保留 base 的原始 UID | 避免重新导入冲突；幂等 |
|
||
| weekday 索引 | 全项目统一 getDay（0=周日） | 从根上消除 Python 版的映射 hack |
|
||
| undo 实现 | structuredClone 快照，上限 50 | 简单可靠，纯数据无循环引用 |
|
||
| 测试框架 | Vitest | 与 Vite 生态一致，纯函数易测 |
|
||
| 是否加 Pinia | 不加 | 单 store composable 足够，减依赖 |
|
||
| 时区处理 | 墙钟语义 + tzid 标签，序列化时由 ical.js 处理 | 避免手动时区计算错误 |
|
||
| 拆分粒度 | 按日期拆成两段 | 最常见需求（后半学期换教室） |
|
||
| CSS 方案 | SFC scoped，移植 editor.html 风格 | 视觉一致，无额外依赖 |
|
||
|
||
---
|
||
|
||
## 12. 验收标准
|
||
|
||
1. `npm install` 用 npmmirror 成功，无错误
|
||
2. `npm run dev` 启动，浏览器打开无报错
|
||
3. 拖入 `timeTable/org.ics`，左侧显示 61 个事件
|
||
4. 点击「整理去重」，变为 8 个事件（5 重复 + 3 单次），与 Python `ical_organizer.py` 输出结构等价（忽略 UID）
|
||
5. 选中一个重复事件，网格正确显示所有 occurrence，绿/红切换正常
|
||
6. 编辑字段 -> 应用 -> 网格/列表刷新
|
||
7. 拆分一个重复事件，得到两段，各自网格正确
|
||
8. 新增一个事件，可编辑
|
||
9. 撤销/重做正常
|
||
10. 下载 ICS，用 `timeTable/.venv` 的 Python 验证：parse + expand 后 occurrence 列表与编辑前等价
|
||
11. `npm run build` 产出 `dist/`，可直接用静态服务器或 `file://` 打开 `dist/index.html` 运行（注：ical.js 需确保无 CDN 依赖，全打包）
|
||
|
||
---
|
||
|
||
## 13. 实现顺序（供 writing-plans 细化）
|
||
|
||
1. 脚手架：git init + Vite 创建 + .npmrc + .gitignore + 装依赖 + 首次 commit
|
||
2. `lib/weekday.js`（最简，先跑通）
|
||
3. `lib/ical-io.js` + 用 org.ics 手动验证 parse/serialize round-trip
|
||
4. `lib/recur.js` + 单测
|
||
5. `lib/organize.js` + 黄金用例单测（对齐 Python 输出）
|
||
6. `composables/useCalendar.js`（含 undo）
|
||
7. `DropZone.vue` + `App.vue` 骨架，跑通"拖入 -> 显示列表"
|
||
8. `EventList.vue` + `HeaderBar.vue`（含整理按钮），跑通"整理去重"
|
||
9. `EventDetail.vue` + `OccurrenceGrid.vue`，跑通编辑
|
||
10. splitEvent + addEvent + deleteEvent
|
||
11. 下载导出 + dirty 提示
|
||
12. README.md
|
||
13. `npm run build` 验证 + 收尾 commit
|