laoyang
be582569dd
用户原话：「carddav 和 caldav 好像都不好用，没有任何数据被同步出来。
同步的客户端，在 D:/Yongquan/code/SyncCalendar 中有，你可以用这个里面的代码试试同步一下。」
三处真根因**全部靠实测**拿到（不是"看代码猜"）：写了 _fb_dav_diag.py，
逐字复刻 SyncCalendar 的 DavClient 请求序列（PROPFIND/REPORT/GET + 它那几个 XML 体），
打线上一次就复现出用户症状（15 条失败），修完线上 28/0。
1. 发现链（discovery）**整段缺失** ← 这就是"没有任何数据"的根因
标准客户端（DAVx⁵ / iOS / SyncCalendar）建账号按 RFC 6764 走：
GET /.well-known/caldav → 302 到 /dav/ ← 原来 404（落到 index.php 去登录页）
PROPFIND <上下文路径> → current-user-principal ← 原来回的是"日历本清单"，没有 principal
PROPFIND <principal> → calendar-home-set ← 原来没这个属性
PROPFIND <home> Depth:1 / <book> / REPORT ← 这两步一直是通的
① 就断 ⇒ 客户端**在填完账号点保存那一刻**就失败，一条数据都拉不到。
为什么历次验收全绿：上批只验了 PROPFIND /dav/ 与 /carddav/ —— 恰好是**一直通**的那两步，
断点在其**前面**，从来没被测过。
改：两个入口补 PRINCIPAL_PATH/HOME_PATH + /.well-known/* 301（**在鉴权之前**）+
根/principal/列表三处都给 current-user-principal。.htaccess 用**独立标记块**追加
well-known 重写规则（本仓库第 4 次"独立入口必须独立块"）。
2. DTSTAMP 取 time() → ETag 潮汐（增量同步**永远不收敛**）
App\Ics::stampOf() 原为"没给时间就 time()"，而**派生条目**（观影/行程/生日/农历/
节假日/节气）没有 updated_at/created_at ⇒ 每生成一次 ICS 就写一个新"现在" ⇒ 正文变
⇒ ETag 变。线上实测：同一本连续两次 REPORT **每一条 ETag 都不同**，整本 GET 的 ETag
也在变 ⇒ 客户端把"增量同步"退化成"每轮全量重拉"，且拉回来的对不上、永远不收敛。
改：缺时间写固定值 19700101T000000Z（确定优先于"诚实的当前时间"）。
3. 派生本把"日历视图条目"当"CalDAV 资源"
Calendar::exportRows() 对派生本按**日历视图**取数（重复日程展开 N 次、跨天逐日、
生日/农历逐日派生）。线上 /dav/1.ics/ 实测 **2981 个 response / 只有 196 个不同 href**
（anniv-0_familybook.ics 自己重复 **2399** 次）。CalDAV 的资源是**一个 .ics 文件** ⇒
客户端要么把同一条反复入库，要么判定服务器异常而中止本轮同步。
改：CalDav::resources() 按 **UID 去重**（资源名本就是 UID）。
4. 连带两个真 bug（同一段代码顺出来的）
· exportRows() 派生分支**没按本过滤**：month() 里"任务""纪念日"两段不带 kind 判断
（它们 cal=0）⇒ 取"观影本"会把全家所有生日一起带出来（2981 条里绝大多数是 anniv）。
· CalDav::parsePath() 的 $event=(int)$evSeg：派生资源名（movie-100_familybook）
(int) 后全是 0 ⇒ 单条资源请求被当"整本"，GET /dav/4.ics/lunar-...ics 实测回 **400 条**。
5. 顺带补全：系统日历本（农历/节假日/传统节日/节气）原来**导出是空的**
它们只走派生、没有 calendar_events 行，而 exportRows 只认 custom/movie/trip ⇒
手机上订阅这几个本一条都没有。改：按 [今年-1, 今年+5] 派生（**封顶**，农历每天一条，
130 年会有 4.7 万条）。实测耗时 lunarRange 31ms / traditional 51ms / Anniversary 30ms。
改：.htaccess、router.php、dav.php、carddav.php、app/CalDav.php、app/CardDav.php、
app/Calendar.php、app/Ics.php、templates/settings/me.php（补"或只填服务器地址"的提示）。
验证（全部 0 失败）：DAV 探针 28/0（**线上修前 15 失败 → 修后 28/0**，同一套探针两处都跑）、
DAV 反向验证 8/0（7 处修复各自改回旧行为，断言全变红）、e2e 1478/0、升级 153/0、
城市 32/0、几何 428/0 + 移动 680/0 + 交互 92/0、b24 41/0、b27 34/0、b28 39/0、b29 38/0、
b30_import 26/0、b30_ui2 16/0、b30_notify 23/0；部署静态断言新增 12 条守卫并逐条证伪通过。
线上 7 个文件 SHA256 与本地一致；/.well-known/caldav→301 到 /dav/ 实测生效。
⚠️ 本轮在部署脚本上真踩到并修掉两个坑（已写进 pitfalls.md）：
· router.php **不发到线上**，把它写进部署断言 → grep "No such file" → 部署中止在
"改了一半"的状态（迁到 push.sh 第 1 段）。
· `set -euo pipefail` 下 `X=$(... | grep -c ...)` 在 **0 匹配**时退出码 1 ⇒
**整个脚本静默退出**（不打 FAIL，日志停在上一行）。已给全部 7 处补 `|| true`。
FamilyBook
家书，记录家庭的全部生活，一本用岁月写成的家谱。
把一个家的「人」「日子」「去过的地方、看过的电影」收进同一本书里。
它是什么
一个自托管的家庭生活系统。它不是又一个待办清单，而是这个家的长期档案 —— 十年之后还能翻出孩子第一次观影的票根、那年暑假走过的路线。
围绕三个圈展开：
- 人：家庭成员、亲友通讯录，以及他们之间的共享关系
- 时间：日历、日程、提醒，以及任务的期限
- 事件：观影、旅行、其他活动 —— 一切都落在同一条时间轴上
它在做什么
| 阶段 | 主题 | 内容 |
|---|---|---|
| 0 | 地基 | 名册、账号、登录、权限模型、安装向导 |
| 1 | 通信 | 通讯录、共享给某个成员、CardDAV 服务端 |
| 2 | 时间 | 日历本、重复日程、提醒、CalDAV 服务端 |
| 3 | 归一 | 观影与旅行迁入统一事件模型 |
| 4 | 任务 | 任务管理，期限自动映射成日历事件 |
| 5 | 回看 | 统计、年度家书、时间轴 |
当前进度：阶段 0 起步，仓库里只有图标与脚手架。
技术选型
- PHP 7.4+（无框架、无 Composer，上传到站点目录即可运行）
- MySQL 5.7+ / 8.0（
utf8mb4） - 前端为原生 HTML / CSS / JavaScript，无构建步骤
⚠️ 注意 CalDAV / CardDAV 是双向协议，和单纯的 .ics 文件导出不是一个量级的东西。
部署
- 把代码放到站点根目录；
- 复制
config.example.php为config.php，填写数据库与app_key； - 访问站点根，按引导页确认 PHP 版本、扩展、配置、数据库连接四项都通过。
config.php 不入库（已在 .gitignore 中忽略），其中包含数据库口令与加密密钥。
⚠️ app_key 一旦开始记录数据就不能再改（换掉即解不开已有数据），
并且它必须单独备份 —— 密钥丢失等同于数据永久丢失。
隐私
身份证号、手机号属于敏感个人信息，一律加密存储。 （就家庭自用而言，身份证号其实没有多少必须存的场景，启用前请三思。）
图标
见 assets/icons/。概念是「这本书就是家」：屋顶即一本摊开的书，
屋顶下纸做的墙上，三行横线是这个家写下的日子。