From bcaa578ebee7f63a33fd4d41f0ac6197364bda54 Mon Sep 17 00:00:00 2001
From: laoyang <i@yangyq.net>
Date: Tue, 3 Nov 2026 09:06:02 +0800
Subject: [PATCH] =?UTF-8?q?docs(=E9=AA=8C=E8=AF=81):=20=E8=A1=A5=E8=AE=B0?=
 =?UTF-8?q?=209a67fce=20=E7=9A=84=E7=9C=9F=E6=9C=BA=E9=AA=8C=E8=AF=81?=
 =?UTF-8?q?=E7=BB=93=E6=9E=9C=EF=BC=883=20=E6=9D=A1=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E5=85=A8=E9=83=A8=E9=80=9A=E8=BF=87=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

9a67fce 的提交说明里写着「真机未验证」，现已完成验证并全部通过。
本提交仅补充文档，不改代码。

## 设备与环境
- 设备: 5NC0225B27004718 (HarmonyOS)
- 服务器: DAViCal 1.1.9 @ nas.yangyq.net/caldav.php/synccalendartest

## 关键发现：该服务器天然测不出此 bug

DAViCal 的命名规则是「uid 做 URL 编码后直接当文件名」：

  uid    : 20261102T153543-10c5d3cb@169.254.186.221
  文件名 : 20261102T153543-10c5d3cb%40169.254.186.221.ics

猜的名字 == 真名，同步 746 条后 remotePath 全部等于 uid 猜测值，
无论修复是否生效都看不出差异。必须造「文件名 ≠ UID」的资源才能验出。

## 陷阱资源

直接 PUT 一个刻意不匹配的资源：
  文件名 : trap-file.ics
  UID    : trap-uid-with-special-chars@example.com

服务器实测：
  tfxnz/trap-file.ics                                    → 200 存在
  tfxnz/trap-uid-with-special-chars%40example.com.ics    → 404 不存在

⇒ 旧代码删除时必然打到 404。

## 验证结果

### 1. remotePath 存真名 ✅
  实际存储: trap-file.ics
  旧代码会: trap-uid-with-special-chars%40example.com.ics

### 2. 删除打到正确地址并成功 ✅
  DELETE .../tfxnz/trap-file.ics → 204
  日志: 推送删除 uid=trap-uid-with-special-chars@example.com → .../trap-file.ics

### 3. 服务器端确实删掉 ✅
  trap-file.ics → 404
  REPORT tfxnz 资源数 → 0

### 4. 本地物理清库 ✅
  本地库 trap 行数 → 0

### 5. 防复活白名单未误伤 ✅
  日志: 新增0 更新0 删除0 不变1
  同 uid 始终 1 行，未插重复

## 完整同步结果（746 行）
  home      716    lvirlu      9    ycbco       7    cojiujq     7
  tfxnz       3    zlqlzm      2    tdotbsnl    2

## 踩坑记录：拉库必须连 WAL

首次拉库读到 735 行、remotePath 全等于 uid 猜测值，差点误判修复失效。
真实原因是 WAL 未合并：

  sync_calendar.db      344 KB
  sync_calendar.db-wal  428 KB   ← 最新数据全在这里

只拉主库会看到过期快照，必须连 -wal / -shm 一起拉。

## 清理
陷阱数据已彻底清除（服务器 404、本地 0 行），测试日历无残留。

详见工单 #8。