 laoyang
|
c86658966c
|
CalDAV 增加待办（VTODO）双向同步
用户原话：「网页端的 caldav 功能，除了能够同步日程外，增加可以同步任务（待办）的功能」
## 三个设计选择（用户已定）
1. 存放位置：作为 /dav/ 内的一个日历本，不另开 /taskdav/ 入口
2. 同步方向：直接双向读写
3. 字段映射：标准映射
## 字段映射
| VTODO | tasks 列 | 说明 |
|---|---|---|
| UID | 派生 task-<id> | 与日历 UID 空间隔离 |
| SUMMARY | title | 子任务加「└ 」前缀（纯展示） |
| DESCRIPTION | note | |
| DUE | due_at | 零点视为整天，用 VALUE=DATE |
| STATUS | status | todo→NEEDS-ACTION，doing→IN-PROCESS，done→COMPLETED |
| COMPLETED | done_at | 仅 done 时输出 |
| PERCENT-COMPLETE | status | doing=50，done=100 |
| CATEGORIES | 看板名 | 让客户端能归类 |
| RELATED-TO | parent_id | 标准父子表达 |
## 改动
### app/Ics.php：并列增加 VTODO 能力
不改 parse()/export() 的任何行为（VEVENT 路径注释里记着多轮踩坑史），
新增 exportTodos() / vtodo() / parseTodos() / normalizeTodo()，复用底层工具。
### app/TaskDav.php（新建，约 380 行）
虚拟日历本：href 固定 /dav/tasks.ics/，BOOK_ID = -1
（calendar_events.calendar_id 是 INT UNSIGNED 恒 ≥1，负数永不撞）。
权限口径与网页端完全一致，复用 Task::visibleTo / Task::canWrite /
Task::create / Task::update / Task::destroy，不另写一套。
### dav.php：前置拦截，原有日历逻辑零改动
PROPFIND / REPORT / GET / PUT / DELETE 各分支开头判断是否待办本，
是则走 TaskDav 并 exit。另外在 /dav/ 的本清单里追加待办本
（否则客户端根本不知道有这一本）。
## 过程中修掉的 4 个真 bug
1. **Class "TaskDav" not found** → 缺 use App\TaskDav;
autoload 要求带上命名空间前缀，漏了会让整个 dav.php 全线 500。
2. **PUT/GET单条/DELETE 全 404** → 原来全用 isTaskHref()，
它只比「整条路径 == /dav/tasks.ics/」，带子资源时必然 false。
新增 isTaskPath() 做前缀匹配（且要求前缀后必须是 / 或结束，
避免 /dav/tasks.icsXXX 被误判）。
3. **PUT 到不存在的资源名返回 403** → 原实现直接抛「任务不存在」。
按 RFC 4918 §9.7，PUT 到不存在的 URI 就是创建资源。
改为：只有确实存在且有权访问时才走更新分支，否则新建。
4. **注释里的 markdown 加粗导致 PHP 语法错**
`作为 **/dav/ 内的一个日历本**` 里 `**/` 形成 `*/`，提前闭合块注释。
PHP 注释里不要写 markdown 加粗。
## 验证
### Ics 层（34 项全过）
生成 → 解析 → 归一往返，含三种客户端完成态表达
（STATUS:COMPLETED / 只有 COMPLETED 时间戳 / PERCENT-COMPLETE:100）。
### TaskDav 层（45 项全过，真实 32 条任务）
读写、ETag 稳定性、权限、事务回滚。
写操作全在事务里做并回滚，不污染真实数据。
### HTTP 端到端（37 项全过）
OPTIONS → PROPFIND 发现 → REPORT → GET 整本 → PUT 新建
→ GET 读回 → PUT 更新 → DELETE，另含回归与越权检查：
- 原有日历本 PROPFIND/GET 仍正常，组件类型仍是 VEVENT
- 无口令 401、错口令 401、不存在的任务 404
测试按 RFC 跟随 Location（新建时服务端分配 id 并告知真实 href），
这也是真实客户端的行为。
### 数据完整性
测试前后 tasks 均为 32 条，测试数据已清理。
测试用 DAV 口令已 revoke（不影响用户原有口令）。
## 部署
app/Ics.php、app/TaskDav.php、dav.php 三个文件已上传并验证。
⚠️ 服务端文件不在客户端仓库，以后改这些要先比对服务器 md5 再验
（本次踩过：改了没上传，拿旧代码验出假结果）。
|
2026-11-02 15:29:36 +08:00 |
|