Files
FamilyBook/templates/calendar/_settings_menu.php
T
laoyang 6ceae11293 v24 第 22 批:名册加 CardDAV 同步 + 一把通用 DAV 口令(日历与通讯录共用)
用户 2 条原话:
  ①「名册,增加cardav同步功能。」
  ②「caldav和cardav,都增加一个创建口令的功能,这样,就使用用户名和口令来同步,
     避免在第三方客户端进行同步时自己的密码泄露。」

用户拍板的两个岔路(AskUserQuestion):
  · 口令范围 = **一把通用 DAV 口令**(日历 + 通讯录共用),不是两个 ——
    手机上填一次就都通;两把会让用户要在两个页面各配一遍、还容易只配一半。
  · 同步范围 = 与**名册页完全一致**(Person::roster(kind='member')),不另发明判据。

════ 一、 口令统一:caldav_credentials → dav_credentials(Schema v23)════
表**改名**(不是新建一张 carddav_credentials):
  · 老站 RENAME → 已配好的口令一字不动,**所有设备不用重配**;
  · 新装时两表都不在 → 跳过(直接 RENAME 一张不存在的表会抛异常、把升级打断);
  · 两表并存(上次升级跑一半 / 有人手工建过)→ 搬行(INSERT IGNORE)+ DROP 旧表。
⚠️ 迁移**必须**是 RENAME + 存在性守卫(新增 Schema::hasTable),
   只改建表语句里的名字的话,老库会**再建一张空表**、旧表留在原地没人读 →
   用户所有已配好的同步设备立刻全部 401(而且改密码也修不好:新口令写进了新表)。

Auth:caldavIssue/Revoke/Auth/hasCalDav → davIssue/davRevoke/davAuth/hasDav,
新增 davLastUsed()(UI 上显示"最近使用")。

口令管理入口搬到**个人设置 → DAV 同步**(它管的是"我的凭据",同时服务日历与通讯录;
放在日历页会让只想同步通讯录的人在日程里找半天)。
  · 旧路由 calendar/caldav_token|caldav_revoke 保留为 302 → 老书签不 404;
  · 日历本页只留地址 + 一个指路按钮(密码类的东西只该有一个管理入口,
    两处各放一套按钮迟早对不上:这页重置了、那页还显示"已配置")。

════ 二、 CardDAV(全新)════
· app/Vcard.php —— 名册 → vCard **3.0**(iOS/DAVx⁵ 推荐;4.0 在 iOS 上会被降级丢字段)。
  FN 必须有(缺了 iOS 会**整张卡丢掉**)、UID 用 person id(稳定,不随改名变)、
  标签能对上固定词就走 TYPE(手机上显示成"手机/工作"),对不上就原样放进
  X-ABLabel(**不猜**成 HOME —— 猜错了用户看到"家"其实是"奶奶家")。
· app/CardDav.php —— books/rows/one/cardOf/etag/parsePath;ROOT='/carddav/'。
· carddav.php —— OPTIONS / PROPFIND(0,1) / GET / REPORT;**写方法一律 403**。
  只读是与 CalDAV 同样的取舍:与其"半支持"(客户端以为改成功了、服务端却没落库),
  不如明确拒绝,用户至少知道"手机上加的联系人不会同步回来"。
· **地址空间分离、鉴权同一套**:/carddav/ 与 /dav/ 各自独立(资源类型与命名空间
  完全不同,混在一棵树里要靠猜客户端意图,猜错的表现是"连上了但一本都看不到");
  但两者调**同一个** Auth::davAuth、读**同一张** dav_credentials 表 ——
  这正是"一把口令管两种同步"的落点,也保证不会出现"日历能连、通讯录连不上"。
· 路由三处:router.php(本地 php -S)+ .htaccess(书面来源)+ 部署脚本 5c 段。
  ⚠️ 线上用**独立标记块** `# >>> FamilyBook CardDAV`:老站已经有
  `# >>> FamilyBook CalDAV`,把新规则并进那一段会被"标记在不在"的幂等判断
  **整段跳过** → /carddav/ 永远 404,而本地(走 router.php)完全正常。
· 打包白名单加 carddav.php(站点根下的独立入口最容易漏 —— dav.php / upload_stage.php
  都漏过一次,症状都是"线上那个功能 404、本地一切正常")。

════ 三、 🔴 三个真 bug(全是"本地校验全绿"型,靠 vCard 往返测试抓出来)════
把 App\Vcard(导出)与 App\ContactImport(导入)各自单测都是绿的,
但**导出→导入跑一遍**立刻翻出三个:

 ① Vcard::fold **漏了"续行补前导空格"**(照抄 Ics::fold 时抄漏了最后一步)。
    后果:折出来的那几段变成**独立的属性行** → 客户端把半个名字/半个地址当垃圾丢掉。
    而"每行 ≤75 字节""确实折行了"全是绿的 —— 只有「**折行可无损还原**」这条断言能抓。

 ② ContactImport 用 `explode(';')` 给 ADR / N 分段 —— PHP 的 explode **不认识转义**,
    值里写了 `\;`(字面分号)照样在那里拆开 → 地址「青岛市,市南区;某某路1号」被
    从中间切断,后半截(含省名)跑到别的段上;导进来的人地址只剩前半句、
    而且看着像"省没填"。手机通讯录里带分号的地址("XX路1号;3单元")不算罕见。
    → 新增 `splitVcardSegments()`:**按未转义的分号**切,切完再逐段 unescape。
    ⚠️ "先 unescape 再分段"是同一个错的另一种写法(本轮第一版就这么改,往返照样红)。

 ③ Vcard::adrField 的**分号数量对、但位置错一位**(省落到了"邮编"格)。
    第一版 `;;` + 街道 + `;;;` + 省 + `;` —— 总数也是 6,可多出来的那个挤在前面 →
    解析器读段 4 拿到空串。**段数对、总数对、只有位置错一位**,
    所以"数分号个数"的检查发现不了它。

════ 四、 顺带修的一个 ETag 一致性 bug ════
同一张卡在 PROPFIND(清单)与 REPORT(取正文)里原本算出**两个不同的 ETag**
(一个用不带结尾 CRLF 的正文、一个用带 CRLF 的)→ 客户端认为这张卡一直在变、
**反复重拉**(同步永远不收敛),而服务端看不出任何异常(两边都合法)。
→ 新增 `CardDav::cardOf()`,把**正文与 ETag 成对返回**,结尾 CRLF 只加在正文上、
不参与 ETag。修法不是"两处改成一样",而是**让它们没有机会不一样**。

════ 五、 UI ════
· 个人设置页「DAV 同步」卡:两个地址(/dav/ 与 /carddav/)+ 用户名预填 + 一次性明文
  (只显示这一次,走一次性会话槽位)+ 生成/重置/撤销 + "最近使用"。
· 名册页 CardDAV 卡:地址 + "这 N 个人"(人数与名册页一致,用户当场能对上)+
  指路口令的按钮。**不放**生成表单。
· 日历本页改口径:只留 /dav/ 地址 + 指路链接。

════ 六、 验证 ════
- e2e **1106/0**(本批新增约 45 条:CardDAV 全协议、越权 404、只读 403、
  一把口令开两把锁、撤销后两处**同时**失效、口令一次性/不落库、ETag 一致性)
- **vCard 规格体检 36/36**(新工具 `_fb_b22_vcf_spec.php`:转义/折行/多值/标签/
  空名兜底 + **导出→导入往返一致**)
- **真机探针 28/0**(新工具 `_fb_b22_ui.py`:两块 UI 渲染、**在浏览器里点按钮**生成
  口令、刷新后明文消失但状态留下、名册页人数对得上、日历本页改口径、
  撤销后两处 401、全程零 JS 报错)
- 桌面几何 428/0 · 移动端几何(360/375/390/414)684/0 · 结构升级 149/0
- 部署静态断言空跑 **307/0** · 线上部署 134 项自检 0 失败
- **反向验证 14/14**(`_fb_b22_falsify.py`):迁移不干活 / 读旧表 / 断入口 /
  去掉 addressbook 声明 / 只读守卫失效 / 不校验口令 / 越权不再查名册 /
  折行不补空格 / 分段改回 explode / ADR 错位 / UI 卡拿掉 / 明文不再一次性 /
  撤销不删凭据 —— 逐条改回旧行为,对应断言都变红,还原后复绿。

════ 七、 🔴🔴 线上实测挖出的**最重要**的一条:DAV 鉴权在 Apache 上一直是坏的 ════
部署后在线上以 **Web 用户(www)** 身份做端到端验收时,DAV 全部 401 ——
而本地 e2e 全绿。追下去发现两层原因:

 ① **测试假象**:我把 DAV 请求放进了一个**临时探针文件**里,用 `curl` 打它。
    但 Apache 请求 `.php` 文件时**不套用站点根 .htaccess 的 URL 重写** ——
    所以探针里的请求根本没被转给 dav.php/carddav.php,拿到的是**探针自己的 401**,
    不是 DAV 的。第一轮"全 401"有一半是探针自己造的假象。

 ② **真问题**:Apache 默认**不把 `Authorization` 头交给 PHP-FPM** ——
    `$_SERVER['PHP_AUTH_USER']` 与 `HTTP_AUTHORIZATION` **全是 null**。
    实测(这台服务器 Apache 2.4.53,直接监听 80/443,**没有 nginx**):
        基线            : {"PHP_AUTH_USER":null,"HTTP_AUTHORIZATION":null}
        `CGIPassAuth On`: {"PHP_AUTH_USER":"abc","HTTP_AUTHORIZATION":"(有)"}
    ⇒ **线上 CalDAV 从来没被真实客户端连上过**(服务端代码是对的、环境少了这一行)。
      本轮 e2e 用 `php -S`,那里 `PHP_AUTH_USER` 是**自己填好的**,所以一路全绿 ——
      又一个"本地好好的、线上不行"。

  修法:部署脚本 5c 段追加**独立标记块** `# >>> FamilyBook DAV auth`,内容
  `CGIPassAuth On`(Apache **2.4.13+ 的核心指令**,不需要额外模块、**不用动宝塔面板**)。
  仓库 `.htaccess` 同步写上(它是那段规则唯一的书面来源)。

  修完后线上端到端**全部通过**(以 www 身份、真实 HTTP 服务、真实数据):
    · CalDAV:`PROPFIND → 207`、**8 本日历本**、`PUT → 403`
    · CardDAV:根 `207` + `<card:addressbook/>`;清单 `207`、**1089 张卡**、1089 个 ETag;
      整本 vcf `200`、1089 张、全是 3.0、`text/vcard`;**最长行 75 字节**(真实数据上
      折行真的发生了);`REPORT → 207` 带 `address-data`;`PUT → 403`;
      `OPTIONS → 200 DAV: 1, 2, 3, addressbook`
    · 导出的卡数 **1089 == 名册人数 1089**(口径一致)
    · 口令错 → `401`
  临时探针用完即删并复验 404;临时插入的口令用完即清(不动用户已配的凭据)。

════ 八、 关于 CalDAV「本来是好的」这件事 ════
严格说:**服务端实现一直是对的**,缺的是 Apache 那一行 `CGIPassAuth`。
也就是说这个仓库里的 CalDAV 之前**上线即不可用**(只是没人用真实客户端试过)。
本批顺手把它一起修好了 —— 现在 /dav/ 与 /carddav/ 都能被 iOS / DAVx⁵ 正常连上。
2026-10-06 17:33:48 +08:00

118 lines
6.5 KiB
PHP
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<?php
/**
* 日程模块的「设置」下拉(v24 用户 2026-10-03 第 4、5 条)
*
* 用户原话:「日程模块,左侧的日历本显示与否,去掉,让日历充满整个宽度。
* 在右侧,也加一个设置按钮,设置中,可以设置哪些日历本显示,
* 调整日历的颜色,导入日历等功能,都放在这个设置下。」
* 「在日程的设置中,可以设置默认显示的视图模式,月视图还是周视图还是日视图。
* 把日历本这个按钮的功能,收到设置中。」
*
* 所以这个 ☰ 是**原来左边那一栏 + 「日历本」按钮**的合并去处。
* 外观与观影 / 任务的设置下拉完全一致(只留图标、排最右、条目带小图标),
* 三处同一个手势,用户不用记第二套。
*
* 两件**个人偏好**(默认视图 / 显示哪些本子)就地用表单提交;
* 其余的(颜色、共享、导入、CalDAV)是**页面级**的操作,
* 跳到「日历本」管理页 —— 那里本来就有全套,没必要在这儿再写一遍。
*
* 用法(require 前 set 好):
* $setCurrent 当前页 key('view'),用来高亮
* $cals 我可见的日历本(带 perm / color);可能为空
* $view 当前视图(回跳时保持)
* $anchor 当前锚定日(周/日视图回跳时保持)
*/
$setCurrent = (string)($setCurrent ?? '');
$setOn = static function (string $key) use ($setCurrent): string {
return $setCurrent === $key ? ' class="on"' : '';
};
$setIcon = static function (string $name): string {
$paths = [
'view' => '<rect x="2" y="3.2" width="12" height="10.4" rx="1.6"/><path d="M2 6.4h12M5.4 1.6v3.2M10.6 1.6v3.2"/>',
'books' => '<path d="M2.6 3.2h4v9.6h-4zM9.4 3.2h4v9.6h-4z"/>',
'import' => '<path d="M8 2.6v7.2M5 6.8l3 3 3-3M3.2 13.4h9.6"/>',
'dav' => '<circle cx="8" cy="8" r="5.6"/><path d="M2.4 8h11.2M8 2.4c1.8 2 2.6 3.7 2.6 5.6S9.8 12 8 13.6C6.2 11.6 5.4 9.9 5.4 8S6.2 4.4 8 2.4z"/>',
];
$d = $paths[$name] ?? '';
if ($d === '') {
return '';
}
return '<svg class="mi" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"'
. ' fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"'
. ' stroke-linejoin="round">' . $d . '</svg>';
};
$myCals = (array)($cals ?? []);
$hiddenIds = array_map('intval', (array)($hiddenCals ?? []));
$curView = (string)($view ?? 'month');
$backView = $curView;
?>
<details class="movie-set menu cal-set">
<summary class="btn btn-icon" title="日程设置" aria-label="日程设置"><svg viewBox="0 0 16 16" width="18" height="18" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11"/></svg></summary>
<div class="menu-list cal-set-list">
<?php /* ---- 默认视图 + 显示哪些本子(个人偏好,就地提交)---- */ ?>
<form method="post" action="<?= e(url('calendar/prefs')) ?>" class="cal-set-form">
<?= csrf_field() ?>
<input type="hidden" name="back_view" value="<?= e($backView) ?>">
<div class="cal-set-block">
<div class="cal-set-h">默认打开时看</div>
<div class="cal-set-views">
<?php foreach (\App\Calendar::VIEWS as $vk => $vw): ?>
<label class="cal-set-view">
<input type="radio" name="view" value="<?= e($vk) ?>"
<?= \App\Calendar::defaultView((int)\App\Auth::personId()) === $vk ? 'checked' : '' ?>>
<span><?= e($vw) ?>视图</span>
</label>
<?php endforeach; ?>
</div>
</div>
<div class="cal-set-block">
<div class="cal-set-h">显示哪些日历本</div>
<?php /* ⚠️ 这个隐藏标记是**必须**的:HTML 里"一个都没勾"会让浏览器
整个省掉 `show[]` 键,服务端就分不清「用户想全关掉」与
「这次请求没打算改显隐」—— 没有它的话,将来任何只改默认视图的
提交都会把所有日历本静默藏掉。 */ ?>
<input type="hidden" name="show_present" value="1">
<?php if (!$myCals): ?>
<p class="small muted" style="margin:0">还没有日历本。</p>
<?php else: ?>
<?php foreach ($myCals as $c): $cid = (int)$c['id']; ?>
<label class="cal-set-book">
<input type="checkbox" name="show[]" value="<?= $cid ?>"
<?= in_array($cid, $hiddenIds, true) ? '' : 'checked' ?>>
<span class="color-preview" style="background: <?= e((string)$c['color']) ?>;"></span>
<span class="cal-name"><?= e((string)$c['name']) ?></span>
<?php if ((string)$c['kind'] !== 'custom'): ?>
<span class="node-badge">系统</span>
<?php elseif ((int)$c['shared'] === 1): ?>
<span class="node-badge"><?= ($c['perm'] ?? '') === 'write' ? '共享·可写' : '共享·只读' ?></span>
<?php endif; ?>
</label>
<?php endforeach; ?>
<?php endif; ?>
<p class="small muted" style="margin:6px 0 0">
观影、旅行、有截止时间的任务会自动出现在这里,不用另建本子。
</p>
</div>
<div class="cal-set-foot">
<button class="btn btn-sm" type="submit">保存显示设置</button>
</div>
</form>
<?php /* ---- 页面级操作:颜色/新建/共享/导入/CalDAV 都在「日历本」管理页 ---- */ ?>
<div class="cal-set-links">
<a href="<?= e(url('calendar/calendars')) ?>"<?= $setOn('books') ?>><?= $setIcon('books') ?><span>日历本 · 颜色 / 共享 / 导入</span></a>
<a href="<?= e(url('calendar/calendars')) ?>#caldav"><?= $setIcon('dav') ?><span>CalDAV 订阅(在手机日历里看)</span></a>
<?php /* v24 第 22 批:口令改成通用 DAV 口令(日历 + 通讯录共用)。这条不再直接跳
日历本页那个卡片,而是跳到**口令管理**页 —— 用户从这里点进来十有八九
是"要配同步",那就该落到能生成口令的地方(日历本页现在只有地址)。 */ ?>
<a href="<?= e(url('settings/me', [], 'dav')) ?>"><?= $setIcon('dav') ?><span>DAV 口令(日历 + 通讯录)</span></a>
</div>
</div>
</details>
<?php
unset($setCurrent, $setOn, $setIcon, $myCals, $hiddenIds, $curView, $backView);