FamilyBook

Files

T

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

Storage

v47：地址联想三处接入 / 读书页慢的真根因（会话锁）/ 笔记两处 / 日程状态下线

2026-10-14 01:20:40 +08:00

.htaccess

阶段 0 完整版：名册 + 账号 + 安装向导 + 设置（宣纸主题）

2026-09-30 00:49:53 +08:00

Account.php

名册每人一份 · 分组两层 · 拖动排序 · 表单合一 · 裁剪可缩放

2026-09-30 13:24:26 +08:00

Anniversary.php

v62：纪念日列表修正 / 分类图标与设置菜单 / 首页卡片体系