laoyang/FamilyBook
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity
139 Commits 1 Branch 0 Tags
610d524e683f484b37354b8925a90a94a370d1b7
Commit Graph
16 Commits
Author SHA1 Message Date
laoyang 0b8012f5dd 品牌改名：家书 → 岁月家（网页端标题/logo/文案；首页标题改「某某某的家庭岁月」） 2026-11-01 19:55:40 +08:00
laoyang 2f7dc6ca23 v63：卡片配色 / 日历本靠右 / 地图题图 / 设置页清理 / 公共标签颜色 / 令牌下线 
- 卡片右上角按钮改用「来自哪个模块」的主题色：HomeCards 登记表新增 mod 字段
  与 module()，首页从登记表取色（原来是模板里硬编码 in_array(['agenda','tasks'])
  白名单，新加带按钮的卡片会默默变灰）
- 首页日程把日历本放到色块右侧：.ag-ev 改弹性行，「时间+标题」包进
  .ag-ev-main（flex:1 1 auto; min-width:0），日历本作右侧兄弟。
  原来 display:block 会把日历本顶到第二行，色块一矮就完全看不见
- 旅程地图显示题图：服务端把 media_url(cover_key) 塞进地图数据，
  地图卡片左侧 40x40 题图（object-fit:cover），没有题图不留灰框
- 系统设置第一块改叫「系统标语」；删掉「首页上那一行小字」提示、
  「不是全家的统一口号」说明、「上次结构升级有步骤失败了」整框；
  运行环境删「排错时看这一块」与「亲属连线」那一行（功能与数据未动）
- 公共标签：说明文字全删；列表与编辑合并成一行（色块+名字+N人+箭头+编辑）；
  person_groups 加 color 列（Schema addColumn，老库可升）；点「编辑」弹框
  改名字与颜色、点「完成」提交；下面那个独立编辑列表撤掉。删除挪进弹框
- 个人设置删掉「手动签发接口令牌」整块；settings/api_token 路由保留但挡下提交
  （只删界面会留下知道地址就能用的后门）；令牌只由登录后自动签发，
  设备管理卡保留。apiTokens/apiPlain/apiLabel/apiBase 四个变量一并撤掉
 2026-10-19 17:27:37 +08:00
laoyang 9a66068c33 v62：纪念日列表修正 / 分类图标与设置菜单 / 首页卡片体系 
- 纪念日列表：display:flex 从 td 移到内层 div（写在 td 上会破坏表格列算法，
  表现为关联人列与其它列高度不一致）；行内列序按表头对齐；
  改完再点「新建」不再带出上次修改的数据；文案改为「与我相关」「来自名册」；
  别人记的、把我挂成关联人的条目一并显示（split() 返回 hiddenIds，
  路由层据此过滤「接下来的日子」，与两张表同一套可见性）
- 分类图标：新增 app/AnnivIcon.php（17 个行内 SVG 图标 + 同 key 的 emoji
  供日历纯文本处使用，内网无 CDN 不用 FontAwesome）；去掉「看日历」按钮；
  设置按钮改为菜单，第一项进 days/settings 独立页；分类可自选图标，
  列表徽标与日历条目都按分类显示
- 首页卡片：新增 app/HomeCards.php 与 templates/home_cards.php；
  8 格宽 × 高 2/4/6/8；首页拆成 templates/home/_card_*.php 共 8 个片段；
  home/cards 可改尺寸、调顺序、开关
 2026-10-19 12:51:17 +08:00
laoyang ebaed21920 v57：令牌升级为「设备会话」（24h 滑动续期 / 每账号 10 台 / 网页端远程退出） 
用户 2026-10-17 定的模型：
  · 一次登录 = 一台设备一条会话；同一台设备重登，旧令牌立即作废
  · 24 小时滑动续期（一直联网就不用每天输密码）；离线超 24h 只锁界面、不删数据
  · 网页端「个人设置 → 设备管理」能看见都有谁在登录，并能把丢了的那台踢掉
  · 每账号最多 10 台，超了让用户先踢旧的

服务端配套：
  · api_tokens 加 device_id / device_name / platform / app_version / last_ip
    + idx_api_device；历史令牌回填 legacy-<id>（不回填 = 踢不掉的幽灵会话）
  · ApiToken：issueDevice / listDevices / revokeDevice / revokeOthers / revokeCurrent
    + 滑动续期（剩余不足 4h 才写库）；verify 同时返回数字键与关联键（三处调用方在用）
  · 新增 /api/v1/logout、/api/v1/devices；ping 报 features.device_session
  · 登录不再读 days（0 = 永不过期会绕过 24h 这条线）；超限回 409 且**不动任何一行**
  · 老客户端兜底固定槽位 auto-unknown（随机设备号会撞满 10 台把账号锁死）
  · Schema 34 → 35

顺带：首页近期任务/往年的今天（Home::memories）、名册派生字段口径统一。

验证：设备会话探针 56/0、设备管理渲染 22/0、登录全链路 30/0、反向验证 12/0、
      e2e 1519/0、静态断言本地空跑 357/0、线上 /api/v1/{ping,devices,logout} 复核通过。
 2026-10-18 03:34:47 +08:00
laoyang 8d79857f1a v54：首页任务标题截断（真根因=两列网格被撑破）/ 名册分组→标签且候选读词表 / 旅程地图视图 / 旅程设置按钮 / 显示方式默认列表或地图 
用户 2026-10-16 傍晚五条。

① 首页「近期任务」标题太长会挤成两行
   用户原话：「首页**近期任务**那个地方要注意截断：如果任务标题太长，
   会把这个任务**挤成两行**。」
   🔴🔴 **真根因是两层，第一版只修了表面**：
     · 表面：`.dash-what` 只有 `flex:1 1 auto; min-width:0`，**缺** nowrap/hidden/ellipsis
       ⇒ 收缩后文字在框内换行；
     · 真身：`.home-duo` 是**两列 grid**，grid 子项默认 `min-width: auto`
       （"我最小也得装下我的内容"）⇒ 一条长标题把那一列顶到 **1763px**
       （父 `home-duo` 才 1032px）⇒ **整个两列布局被撑破**、页面横向溢出到 **2089px**
       （视口 1440）。⇒ 行宽 1721px、`scrollWidth === clientWidth`，
       **`text-overflow: ellipsis` 看起来"没生效"** —— 其实容器自己先爆了。
   修法：`.home-duo > * { min-width: 0; }`，且 **整条 flex 链**都补
     （`.hd-pane` → `.hd-pane-head` → `.hd-pane-body` → `.dash-list/.tk-list` → `.tk-row`）
     —— 链上任何一层漏了，收缩就断在那一层、下面的 nowrap 全白写。
   配套：任务标题加 `title=` 悬停看全。
   ⚠️ 这是本项目**第二次**踩 flex/grid 的 `min-width:auto`（v53 的 `.mv-grid` 是同类）。
      **以后"文字截断不生效"先量容器有没有被撑破**。

② 名册「分组」→「标签」；打标签的候选要**从设置里读**
   用户原话：「现在名册里面给人打标签的时候，**这个标签数据是从哪读出来的**呀？
   在这个名册的设置页面，有很多分组，现在还叫分组。但是打标签的时候，
   **却不是从这些分组里读出来的**。……应该叫「名册标签」，是不是？
   **应该从这里面把所有标签都读出来**吧？……以后就没有分组的概念了，
   **全部都是标签的概念**。」
   🔴 **用户观察得完全正确，这是两套数据源**：
     · 设置页显示的词表来自 `person_groups`（**分组表**）；
     · 打标签的候选来自 `PersonTag::cloud()`（**你已经打过的词**，现算的）；
     ⇒ 两边根本不是一个数据源 ⇒ "设置里列着一堆、打标签时却只有几个"。
   修法：**`PersonTag::choices()` = 设置页词表 ∪ 我用过的词**（并集，词表在前）。
     · 词表里的词**还没用过**也能一点就打上（这正是词表的意义）；
     · 用过的词补在后面（历史不丢）；
     · 名册列表 / 新增 / 编辑 / 挑人 / 导入 **五处同一个函数**。
   界面口径全面改"标签"（**表名仍是 `person_groups`**：改名要背着 `PersonGroup` 类、
   `person_roster.group_id`、以及**另一个会话正在写的 `app/ApiHandler.php`**
   （它引用了 `PersonGroup::orderFor`）一起动，风险远大于收益）：
     · `_person_groups.php` 标题「名册标签」、按钮「加一个我自己的标签」；
     · 删除文案改成"只是从候选里去掉这个词，已打在别人身上的不受影响"
       （**语义真的变了**：标签是各自身上的字符串，不是引用）；
     · `people/_settings_menu.php`、`people/settings.php`、`settings/me.php`、
       `settings.php`（「公共分组」→「公共标签」）全部同步。
   顺带按"全部都是标签"改另两条入口：
     · `people/pick.php`「加进哪一组」下拉 → **打标签**；
     · `people/import.php` 同上；`ContactImporter::run()` 加 `$tags` 参数。
   🔴 新增 `PersonTag::addOne()`（**追加**一个标签）—— 这两处**绝不能用 `setFor()`**
      （它是"先 DELETE 再 INSERT"的整组替换）⇒ 会把人**原有**的标签清光
      （症状是"用一次导入，别人原有的标签全没了"，极难联想）。
   ⚠️ `group_id` 在 pick/import 的**服务端仍收着**（老书签/脚本兼容），只是界面不再展示。

③ 旅程模块加**地图视图**（读 TripLog 移植）
   用户原话：「你去读一下 TripLog 的代码，在旅程这个模块，**可以在地图上显示旅程数据**。
   1. 先读一下它之前那个代码是怎么实现的，**在我们的旅程模块也实现一下**。」
   读 TripLog（`templates/activities/index.php`）得到的要点：
     · 用**高德 AMap**（合规白名单内，绝不是境外瓦片）；
     · `position` 必须是 **[lng,lat] 数组**（传 `{lng,lat}` 裸对象会让 AMap 抛错、
       整个绘制循环当场中断 —— 它注释里写着"批 11 的光秃秃地图就是它"）；
     · `setFitView()` 后**上限 11 级**（只有一趟时会被放大到街道级，那是导航视角）；
     · `.amap-marker` 整层 `pointer-events:none`（否则包装层挡住别家卡片的点击）；
     · **容器必须有固定高度**（0 高度 → 空白地图）。
     它那套"同城环形扇开"是**几百行几何**，本仓数据量没压出这个问题 ⇒ **有意不做**。
   本仓数据更规整：`trip_nodes` 早有 `from_lng/from_lat/to_lng/to_lat`（v17 批）
   + `from_city/to_city` ⇒ 新增 `Trip::attachSpots()`：
     ① 有坐标取**重心**（不是端点 —— 端点会让"青岛→伊春"偏到某一头）；
     ② 没坐标退到**城市重心**（`Geo::lookup` 离线城市表，**不发网络请求**：
        列表页几十趟若逐条打高德逆地理，一次开页就是几十个外部请求）；
     ③ 都没有就不上图（列表里照常有，模板会说清"有几趟没上图"）。
     🔴 城市那里**必须也取重心**：`cities()` 的顺序是**按时间**（出发地在最前），
        取"第一个城市"会让**所有旅程都叠在家上**、地图毫无信息量。
   布局：两个视图用**标签页**（`?view=map` 是**链接**不是纯 JS 按钮 ——
     书签/前进后退/无 JS 都正确；也**有意不**把地图藏在 `display:none` 里，
     高德在 0 尺寸容器里会渲染空白）。
   高德 SDK 加载器重构：原来 `fbLoadAddr()` 顺带拉 `addr_suggest.js`，
   而地图只用 SDK 自带的 `AMap.Map/Marker` ⇒ 抽出 `window.fbAmapSdk()`（只拉 SDK）、
   新增 `fb-amap` meta（不带 plugin），`fb-addr` 那份共用同一加载器。

④ 旅程列表页「新建旅程」**后面**加「设置」按钮
   用户原话：「2. 在旅程的「新建旅程」后面也加一个「设置」按钮。」
   ⇒ 补 `_settings_menu.php`（设置恒排最右），菜单**第一条**加「显示方式」。

⑤ 显示方式：默认列表还是地图（用户自配）
   用户原话：「3. 里面的设置让用户自己配置：**到底默认显示旅程列表，还是用地图显示**。」
   ⇒ 新增 `trips/display`（设置页 + `?set=` 快速设置）与 `trips/display_save`，
     存 **`user_settings.trip_default_view`**（每人一份，**不是**全家设置）。
   ⚠️ 访客也能改（只影响自己看到的默认，不是数据变更）。

验证（新增 2 套件 + 更新 e2e/deploy 断言）：
 · _fb_v54_ui.py（**33 条**真机断言）
 · _b54_falsify.py（**11 注入 / 11 全抓**，基线 33/0）
 · e2e **1518/0**；familybook_deploy.sh 加「第54批形态」段（**24 条**）
 · 部署 **0 FAIL**；线上 **20 个文件 md5 逐字节一致**；
   线上实测：词表 24 条、`choices()` 24 条、**`cloud` 15 条全部 ⊆ `choices`**、
   4 趟旅程全部可上图（样例落在济南·青岛重心）；诊断页已删复验 404

⚠️ 本轮踩坑（已写进 pitfalls.md）：
 · 🔴🔴 **"文字截断不生效"要先量容器有没有被撑破**（第一嫌疑是 flex/grid 子项
   `min-width:auto`，不是 `text-overflow` 写错）；
 · **反向断言（"不该再出现 X"）必须用 `_code_has`（剥注释）** ——
   需求原话正当留在注释里，裸 `grep -F` 会命中自己的说明（本轮部署假红一次）；
 · **冗余防线会让反向验证打不红**（两处 `min-width:0` 只去掉一条 ⇒ 探针照旧全绿，
   注入必须一起去掉）；
 · **界面多加一个字符就可能打歪既有断言**（我在词表管理页给标签名加了 `#`，
   把 e2e 的 `my_group_order()` 读成 `#家人`）。
 2026-10-17 00:15:06 +08:00
laoyang ed122c034b v52：旅程 CalDAV 结束时间 / 笔记（标题·段落下加段加图·逐段就地编辑）/ 名册自动匹配与设置页 / 模块设置整合表 
用户 2026-10-15 七条。

① 旅程行程经 CalDAV 同步后「结束时间 = 开始时间」
   **真根因**（app/Calendar.php 的 exportRows()）：对**派生条目**（观影/旅程）写死
     'ends_at' => null，而 Ics::vevent() 遇到空结束会退化成「DTEND = DTSTART」
     ⇒ 手机上每条行程的结束时间都等于开始。
   **附带第二个 bug**：分组键含日期（kind-ref_id-date），而 month() 把**跨天条目逐天**
     铺出来 ⇒ 跨天节点被拆成 N 条（UID 相同），resources() 按 UID 去重后**只留第一天**，
     而第一天那条没有结束时刻 ⇒ 又回到 DTEND=DTSTART。
   修法：键改成 `kind-ref_id`，先收集同节点的各天，再用**首末天**拼一条真实跨度
     （末天那条才带 end_time）。实测单日 DTEND=12:30、跨天 DTEND=第3天11:00，
     每节点恰好 1 条 VEVENT。
   ⚠️ 副作用（已处理）：v31 DAV 去重的反向验证原来靠「跨天节点逐天出、UID 全同」造重复，
     本修把那条素材**修没了** ⇒ 给夹具换成「同一份 .ics 导两次」（两条 UID 相同的
     自定义日程），守卫仍能被证伪（见 _fb_dav_diag.py 与 pitfalls 的同族条目）。

② 笔记详情页标题是"看笔记"而不是笔记名
   阅读态 h1 改用笔记自己的 $noteTitle；**编辑态仍用「改笔记/写笔记」**
   （编辑时标题就在下面第一个输入框，两处重名看着像重复）。浏览器 <title> 同步。

③ 加段落/加图片要在**输入框下面**
   note_editor.js 的 makeBlock() 里每块下方加一排 .note-block-add（＋段落/＋图片），
   点了插在**这一块后面**；顶部那组**保留**（用户明确"上面和下面都保留"）。
   ⚠️ 挂在 body 里而不是 wrap 上 —— .note-block 是 display:flex 横排，
      挂 wrap 会变成"输入框右边的第三列"，不是"下面"。
   ⚠️ 用 data-add-below（不是 data-add）：顶部是"追加到末尾"、块内是"插在本块后"。

④ 笔记详情页「逐段就地编辑」（分块多时不用跳编辑页找那一块）
   模板给每块包 .note-read-item[data-block][data-kind][data-raw] + 右上角「编辑」按钮；
   新增 assets/js/note_inline.js（按需加载）：划过出现 → 点编辑就地变 textarea →
   保存 POST notes/block → 只换这一块。
   服务端 Note::updateBlock()：**按块主键改一行**（不是整组替换）——
   ⚠️ 整组替换会换掉每个块的 id（前端手里的 data-block 当场失效）+ 并发互相覆盖；
   ⚠️ SQL 必须带 `AND note_id = ?`（块 id 全局自增，少了它就能改别人笔记里的块）。
   权限与整条编辑同一把尺（find() + canWrite()）。

⑤ 删掉「从已有家里人中挑选」，改成「新增/导入时自动匹配」
   新增 Person::matchExisting()：手机号（有 phone_hash，一条 SQL 精确命中）→
   身份证（无哈希，整表解密比）→ 姓名（**先记下不立刻返回**，等精确命中看完再退到它）。
   people/create：校验通过后先 matchExisting，命中就在**同一张表单里**出确认条
   （#personConfirm）。⚠️ **不做成单独确认页**：单独页要把整张表（含工作经历/补充联系
   方式这些**数组字段**）原样回传，漏一类就静默丢数据；同表单里字段天然全在。
   ⚠️ 判"是不是第一次提交"用 array_key_exists('confirm_existing')（0=不是、1=是、无=首次）。
   导入那条路的缺口（本轮补）：ContactImporter 命中已有的人时只补字段、**不挂进导入者的
   名册** ⇒ "文件里有他、系统里也有他，但导完我的名册里看不到他"。已在命中分支加
   PersonRoster::ensure(..., $meId, ...)。
   顺手加 PersonRoster::has()（避免调用方又踩"visibleIds 是值列表不是集合"那个坑）。

⑥ 名册页只剩「添加成员 + 设置」；分组搬到名册设置
   templates/people/_settings_menu.php（新）：☰ 下拉两行 = 导入联系人 / 名册分组。
   templates/people/settings.php（新，路由 people/settings）：require 从个人设置**整块搬出来**
   的 templates/_person_groups.php。
   ⚠️ 是**真搬**不是复制（两份一模一样的分组界面，改一处忘一处是必然的）；
   ⚠️ 片段变量一律加 pg 前缀 —— 模板片段与宿主 require 是**共享作用域**，
      用 $groups 这种通名会覆盖宿主同名变量（本轮真踩到，已改）。
   ⚠️ 表单 action 仍指 settings/groups/*（一个字段没改）。

⑦ 个人设置：模块设置整合成一张表
   原来是**三张卡三个表单**（首页模块 / 导航模块 / 主题色），同一串模块名出现两遍。
   现在一张表五列：顺序 | 模块 | 导航 | 首页 | 颜色，一次保存。
   新增 settings/modules_save 路由：**底层存储一个没改**（仍是 nav_modules /
   home_modules / module_colors），只是把三个 save 依次调一遍 ⇒ 老数据天然兼容。
   ⚠️ 权限**没有**因为"合并"被放宽：颜色仍是家庭一份、只有管理员能改
      （非管理员那列是只读色块；提交时服务端静默忽略 c[]）。
   窄屏：表格 min-width:560px + 外层 overflow-x:auto（375px 实测横向溢出 0）。

验证（新增 5 套件 + 更新若干旧断言）：
 · _fb_v52_ics.py（3）/ _fb_v52_note.py（19）/ _fb_v52_roster.py（12）/ _fb_v52_mods.py（13）
 · _b52_falsify.py（**12 注入 / 31 断言全抓**）
 · _fb_import_test.py 补 ⑯（命中的人也要回到导入者名册）；_fb_dav_diag.py 换去重素材
 · e2e 1516/0；_fb_batch_e.py / _fb_e2e.py / familybook_deploy.sh 里随 #6/#7 搬家或改形的
   旧断言（分组在个人设置、模块行 li→tr、show_present、RRULE 前缀）意图一字不改
 · 全流水线 **PUSH_RC=0**、部署 0 FAIL（含"第52批形态"）；线上 16 文件 md5 逐字节一致

⚠️ 工程纪律（已写进 pitfalls.md / 工作日志）：
 · 探针自起的 PHP 服务**一律随机空闲端口**（写死 + "连上就复用" 会静默测到别的目录/库）；
 · **同一工具链目录 + 同一库名不支持两个会话并发** —— 本轮最后一个多小时的"诡异全红"
   全是**另一个会话**在同时跑 _fb_e2e.py、共享 fb_test 与 _fb_site 造成的；
 · 并发下**连 git stash 都不能用**（会把别人的半成品一起藏起来），基线对照用 git worktree；
 · 修好业务可能让"守着它的反向验证"空转（素材被修没了）⇒ 换一处等价素材，别删守卫；
 · 断言盯**形态**而非具体数值（分栏那次写死 50% 在别的批次数据上假红）。
 2026-10-15 23:04:25 +08:00
laoyang 075ac6bbeb v44 第 44 批：界面 5 条 + 移动端 API v1 全量 
界面（用户 2026-10-12 第 1~5 条）
1. 新建日程「日历本」并入 .cs 自绘下拉，颜色画进候选项，三字与下拉同行。
2. 新建日程「开始/结束」改「日期范围：」，删旧日期控件；
   重复相关三行仅选重复时出现；删「（含第一次）」与「这段时间算忙碌」。
3. 条目浮层加「地点」、去掉「状态」行；首页红线按分钟定位（原只取整小时）；
   去掉左侧红点只留红线。
4. 任务页删掉状态说明提示（STATUS_HINT 三值清空）。
5. 新建任务：标题在前树框在后；截止时间改最新日历控件；负责人默认自己；
   删冗余提示；「上面要做什么」→「任务名称」；清理括号说明。

移动端 API（用户第 6 条：导航模块除外，其余全量）
- 新增 Bearer 令牌鉴权（api_tokens 表，Schema v32），与登录口令 / DAV 口令三套分立。
- Api.php 内核（鉴权/取参/信封/分页/分发 + _method 覆写）+
  ApiHandler.php 17 条资源 + ApiToken.php + api.php 入口。
- 路由：router.php / .htaccess / index.php 三处 /api/ 兜底（部署脚本自动追加线上规则）。
- 个人设置新增「App 接口令牌」卡；docs/API.md 接口文档；
  docs/API-QUESTION-LIST.md 自主决策与待确认缺口清单。

验证：本地 e2e 1510/0、v43 真机 33/0、v43 反向 9/0、
v44 真机 41/0、v44 API 63/0、v44 反向 19/0；全流水线 PUSH_RC=0。
 2026-10-12 15:31:03 +08:00
laoyang be582569dd v31 第 31 批：DAV（CalDAV/CardDAV）同步修复 —— 发现链缺失 + ETag 潮汐 + 资源重复 
用户原话：「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`。
 2026-10-08 20:05:01 +08:00
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
laoyang f0437e6c93 v24 第 21 批：无刷新删除与新建日程 / 实际行程不回退 / 行程按时间排 / 统一上传框 / 时间范围控件修复（用户 8 条） 
用户 8 条原话要点：
  ①「名册页面，删除一个联系人后，能否不刷新页面，删除成功后，直接把这个人，
     从当前页面的 dom 中删除，页面保持不动。」
  ②「观影模块，海报和票根以及照片都带进来了，但是没有缩放，把页面撑破了，
     应该缩放成缩略图。」
  ③「个人设置页面，天气设置那里，把：只影响你自己首页上的那一格 / 填个城市名就行
     （如「青岛」）… 这些提示，都删除。把城市单独放一行，精度维度放在一行。」
  ④「旅程模块，实际行程编辑后，点击保存，竟然又变成计划行程了，这个不合理，
     实际行程永远是实际行程，不会再变回计划行程了。」
  ⑤「旅程模块，旅程列表，行程列表，都是按照行程的开始时间排序的，最新的在最上面，
     而不是按照编辑修改时间。」
  ⑥「旅程的详情页面，右上角的按钮，设置在最右侧，和其他模块保持统一。」
  ⑦「所有上传图片等附件的地方，都不再放按钮，而是放一个框，点击这个框实现点击上传
     按钮的功能，拖动图片进这个框里，实现拖动多个上传功能。框里面写一句话：
     点击或拖动进行上传，其他的功能和现在保持一致。」
  ⑧「日历中新建日程，无论是点击按钮还是点击日历中间，都是采用弹框的形式进行添加，
     这样不影响当前日历的显示，添加完成后，动态修改当前视图，不要刷新。添加日历日程，
     开始时间和结束时间那里，用我们统一的时间范围选择器重做，现在功能无法使用。
     选择日历本，带上颜色。」

🔴 五个真根因（全都不像 bug）：

 ① 🔴 **④「实际行程变回计划」= 表单字段同名合并**（本批最要紧的一条）
    暂存上传的令牌字段原叫 `stage[]`，与行程表单里那个隐藏的 `stage`（plan/actual）
    **同名**。PHP 解析表单时同名会**合并进同一个键**：
        `stage=actual` + `stage[]=tok` → `$_POST['stage'] = ['actual','tok']`
    （`[]` 只是"往同一个键追加"的记号，**不构成另一个键名**。）
    于是路由里 `(string)($_POST['stage'] ?? 'plan')` 得到 `"Array"` →
    `in_array('Array', ['plan','actual'])` 为假 → **静默回落成 'plan'**。
    ⚠️ 只有"拖过图片的行程"会犯（没拖就没有 `stage[]`）→ 症状是"时好时坏"。
    修法：令牌字段改名成 `stage_token[]`（改的是**字段名本身**，不是"是数组就取第一个"
    绕过去 —— 同名合并是 PHP 的表单语义，绕过去只会把坑留给下一次加字段）。
    **另加一道语义保险**：编辑路径**一律沿用库里那条自己的 stage**，不读表单 ——
    编辑表单里根本没有改阶段的控件（改阶段走详情页那几个显式动作）。
    这样即便将来又冒出某个字段名冲突，也不可能把「实际」悄悄变回「计划」。

 ② 🔴 **⑧「时间范围选择器无法使用」= 三道门叠在一起**
    ① `_event_fields.php` 的**结束端默认带 `hidden`**（要点「+ 添加结束时间」才出现）；
    ② `app.js` 的 `upgradeRange()` 有「**两端都得可见**才升级」的判断 → 永远不成立
       （实测 `data-semi-range-done` 恒为 `null`）；
    ③ CSS `html.js .dt-range:not(.is-semi-range) .dt-input { visibility: hidden }` →
       未升级时原生控件**也是不可见的** ⇒ 屏幕上一片空白、点哪儿都没反应。
    修法：两端**始终可见**（"没有结束"由清空后半段表达，不再靠开关）；
    并把旧的「+ 添加结束时间 / 去掉结束时间」开关整套删掉。
    ⚠️ 顺带挖出：`upgradeRange()` 里 `group.insertBefore(host, a)` 在"两端各自被
    `.field` 包着"时 `a` 不是 `group` 的子节点 → 直接抛
    `Failed to execute 'insertBefore' on 'Node'`。这个异常**以前从没触发过**
    （被 ② 的提前 return 挡住了）—— 一旦放出来就炸。修成插在"端点最外层包装"之前。
    ⚠️ 观察器加了 `attributes: true, attributeFilter: ['hidden']`（并把 childList
    分支的 `return` 去掉）：弹框/折叠面板/tab 里"稍后才露出来"的日期控件从此都能自动升级。

 ③ 🔴 **⑧「新建日程默认建出观影记录」= 产品缺口，不只是显示问题**
    `Calendar::DEFAULT_KINDS` 原来只有 6 本**派生**本（观影/旅行/农历/节假日/传统节日/
    节气），**一本可写的普通本都没有**。于是"放在哪本"里全是派生本、默认选中排最前的
    **观影** → 用户直接打字点「加上」，建出来的是一条**观影记录**
    （日历里看着是多了条日程，观影列表里莫名多一条）。这是"建错东西"，事后极难发现。
    → ① 默认本补成「我的日程」(kind='custom')，模板里默认选中也改成**优先 custom 本**；
      ② 选择器里把**纯派生只读本**禁用并标「（自动生成）」
         （直接不列会让人以为本子丢了；列为可选又会白选一次再吃错误）。
    ⚠️ 顺带发现 `Calendar::READONLY_KINDS` 把 `movie`/`trip` 也算进去了，而
    `event_add` 里**紧跟着**就有两段专门处理它们的分支（「已加进观影」/「已加进旅程」）
    —— 那两段**永远走不到**（校验先一步把请求打回去了）。判据要按**能不能写**分，
    不是按"是不是派生"。

 ④ 🔴 **②「观影编辑页图片撑破」= `.mv-slot` 这个类在样式表里根本不存在**
    第 21 批加模板时只写了结构没写样式 → `<img>` 按**原始像素**渲染：600×900 的海报
    在 236px 宽的格子里撑出 942px 高，还把整页横向顶破（实测 docW 1297 > vw 1280）。
    → 补 `.mv-slot` 规格：固定 108×162 缩略图 + `object-fit: cover`。
    ⚠️ **高度必须写死** —— 不写死就又会由原图比例决定，等于没修。

 ⑤ **⑤行程列表排序 = `category, position` 主导**
    `position` 默认同一个数（旧迁移给的多是 0/100），于是顺序被 position 挤乱。
    实测线上 #222 渲染成「返回青岛(10-5) → 出发去菏泽(9-30) → 去姥姥家(10-2)」。
    → 改成 `ORDER BY (starts_at IS NULL), starts_at, id`。
    ⚠️ 方向是**正序**（早的在前，已跟用户确认）；旅程列表仍是 DESC（最新在最上）。
       两者方向不同是**刻意的**：一个是"挑哪趟旅行"，一个是"读这趟旅行的行程"。
    ⚠️ 详情页**按阶段分三组**渲染（计划/实际/未成行），排序只需在**组内**有序。

本批新增能力：
- **统一上传框**（⑦）：`templates/_stage_drop.php` 现在**同时**负责
  「sr-only 的真文件框 + 看得见的上传框 + 暂存清单」，调用方只 require 一行。
  框是 `role="button" tabindex="0"`，JS 转发 `input.click()`（键盘 Enter/Space 也通），
  拖文件进框走既有的暂存上传（拖一个立刻传、可续拖、失败标红、未传完拦住保存）。
  ⚠️ 框用 `<div>` 不是 `<button>`：里面要放暂存清单（含「撤掉这张」按钮），
     按钮里嵌按钮是非法 HTML（第 21 批刚在 `<form>` 嵌套上栽过同一个跟头）。
  ⚠️ 文件框用 `.sr-only` 不是 `display:none`：后者不可聚焦，带 `required` 时
     Chrome 会报 "An invalid form control is not focusable" —— 点了什么都不发生。
  落了 11 处：行程照片 / 观影海报·票根·合影 / 资源 / 任务 / 日程附件 / 书籍 /
  联系人导入 / ics 导入 / 观影补传 / 资源补传。
  ⚠️ 清单与提示行移到框**外面**（放框内会变成"一个大框套五张图"），
     所以 app.js 改从 `.upfield` 容器里找它们。
- **无刷新删除（①）与无刷新新建日程（⑧）**：路由按 `X-Requested-With`
  （或 `Accept: application/json`）区分调用者 —— 带它回 JSON、不带照旧 302
  （无 JS 的兜底**不变**，两边的反向都写了断言）。
  · 名册删除：成功 → 摘卡片 + 就地改「共 N 人」与分组人数 + 派发 `input` 让
    filter.js 自己重算（**不抄它的判据**）；失败 → 把原因说出来（不刷页）；
    拿不到 JSON → **退回原生提交**（绝不静默失败）。
  · 日历新建：JSON 带齐前端插入当前视图要用的字段（时间/颜色/链接/是否全天/cal）。
    月视图**按时间插入**（不能 append —— 服务端只渲染前 3 条、按时间序取，
    append 会让"新加的早间日程"掉进「+N 条」里看不见，刷新后又跑到第一位）；
    周/日视图按"24h = 100%"算 top/height 插块。
  · 观影 / 旅行本是**可写派生本**：AJAX 时不再跳详情页（跳走就离开了日历），
    改在提示行给一个「去看详情 →」链接。
- **⑧日历本带颜色**：原生 `<option>` 画不出色块（浏览器不允许在 option 里放元素），
  所以做成「色块 + 下拉」并排，色块跟着当前选中的本子变色。
- **③天气卡片**：三句提示全删；城市单独一行、纬度/经度同一行（`.loc-row`）。
  删的只是说明文字，三个输入框 + 保存 + 状态回显都保留。
- **⑥设置按钮贴最右**：原来顺序是「… → 设置 ☰ → 删除 🗑」，设置被删除键挤到**倒数第二**；
  改成删除在前、设置恒为最后一个（与观影/日程/任务/资源同一个手势）。

验证（本地全套）：
- e2e **1059/0**（本批新增约 40 条断言）· 结构升级 149/0 · 桌面几何 428/0
- **真机探针 75/0**（`_fb_b21_ui.py`）：AJAX 删除真的没导航 / 卡片真被摘掉 /
  滚动位置保持；缩略图几何（108×162，不再溢出）；上传框（框在、原生框不可见、
  点框真打开文件选择框、连拖两张都上去且清单可见）；日历弹框（打开时网格一动不动、
  范围控件真的挂上且可见、能弹面板、色块跟着换、无刷新提交后当前视图里立刻出现、
  周视图也能插时间块、全程无 JS 报错）。
- **反向验证 12 条**（`_fb_b21_falsify.py`）：逐条把修复改回旧行为看断言是否变红 ——
  令牌字段改回 stage[] / 编辑读表单 stage / 排序改回 position / 设置按钮挪走 /
  框不转发点击 / 文件框不再 sr-only / 删缩略图规格 / 删除不回 JSON /
  结束端改回 hidden / 日历本默认改回第一个 / 天气提示加回 / 弹框改回内联。
- 部署脚本静态断言段本地空跑 **307/0**。
 2026-10-06 12:08:40 +08:00
laoyang c3d00ad66a v24 第 20 批：拖动即时上传 / 观影图片带出 / 行程保存修复 / 日程红线与删除范围与多提醒 / 悬停统一（用户 9 条） 
用户 9 条原话要点：
  ①「观影模块，编辑观影，已经保存的海报和票根、合影，都没带进来。」
  ②「个人设置页面，"只影响你自己看到的样子"这个提示删除，不要了。我怎么称呼家人，
     这个卡片，不要了。我的资料这个卡片，不要了。」
  ③「旅程模块，编辑行程，点击保存没有反应。」
  ④「所有上传图片视频和附件的模块，都允许多次拖动添加文件上传，拖动一个进去，
     就开始上传，还可以继续拖动，继续上传，最后统一保存即可。」
  ⑤「添加行程，线路名、承运方，都不要了。车辆，只在出行方式选择自驾时才出现，
     其他情况下默认不出现。出发地和到达地，应该在同一行。」
  ⑥「日程模块，周视图和日视图，应该在视图中间显示一条红线，用来表示当前进行的时间…
     用一个不断从上到下的红线，来表示当前时间在视图上的刻度和位置。」
  ⑦「对于重复的日程，当点击删除的时候，应该提示是删除这一次，还是全部都删除，
     还是删除这一次及以后的。」
  ⑧「日程的提醒，是可以多选的，就是说，一个日程，我可以选择让它 5 分钟提醒，
     10 分钟提醒等等。」
  ⑨「很多按钮的悬停效果非常奇怪，感觉纯粹是换了一个背景色…应该调整所有按钮的悬停效果，
     保持统一，但是不要单纯的换一个不协调的背景色。」

🔴 三个真根因（都是"看着不像 bug"的地方）：
  1. **③ 点保存没反应 = `<form>` 嵌套**（HTML 非法）：`trips/node_form.php` 的照片缩略图上
     套了 `<form action=photo_del>`，而整块在**外层行程表单内部**。浏览器解析到内层
     `</form>` 时**把外层表单提前关掉** → 「保存」按钮**掉出表单**（真机实测
     `button.form === null`）。源码里完全看不出，**只有真浏览器量 `btn.form` 才现形**；
     且**只有这段行程已经有照片时才触发** —— 所以表现为"有时候好、有时候坏"。
     → 按钮留在原位（布局不动），用 HTML5 `form="id"` 关联到**表单外**的独立表单。
  2. **⑤ 车辆藏不住（第 17 批就写过、一直没生效）**：`.field` 自己声明 `display:flex`，
     作者样式压过浏览器默认的 `[hidden]{display:none}` → `hidden` 形同虚设。
     **本项目第 4 次栽同一个坑**（.att-item / .pv / .pp-item 各一次）→ 补 `.field[hidden]`。
  3. **④ 拖动即时上传的卡片"看不见"**：模板给 `.stage-list` 加了 `hidden`（没人上传时
     不留空边框），JS 建卡片时忘了 `list.hidden = false` → 卡片在 DOM 里但整条清单
     `display:none`、尺寸 0×0。**HTTP 层断言全绿**（HTML 里确实有卡片），
     **只有真机量尺寸才发现** —— 由新写的真机探针抓到。

本批新增能力：
- **拖动即时上传**（第 4 条）：新增 `upload_stage.php` + `app/StagedUpload.php` +
  `templates/_stage_drop.php`。拖进来 → **立刻** POST 到暂存目录 → 回 `stoken` →
  放进隐藏字段 `stage[]` → 保存时在 `attach_save_files()` 里**认领**（移文件 + 建附件行）。
  `media.php` 加 `?stage=` 预览（拖完立刻看得见缩略图）。
  ⚠️ 三个必须踩准：**串行队列**（并发会让缩略图顺序乱跳）、**提交守卫**
  （还有没传完就 preventDefault，否则"拖了但没保存上"必然发生）、**卡片清单要 un-hide**。
  ⚠️ 海报/票根走**独立字段名** `stage_poster`/`stage_ticket`（各自单槽位、要按比例重裁）。
  ⚠️ 落点**就近取**（`input.closest('.field')`）：一个表单里多个上传区不能串到第一个去。
- **观影编辑带出已存图片**（第 1 条）：编辑页显示海报 / 票根 / 合影 + 各自的删除入口；
  新增 `movies/media_del`（只删不换也能删，槽位走白名单）；`movies/update` 收编辑页
  新选的照片时**合并**而不是替换（否则一编辑就把已有合影冲掉）。
- **行程表单**（第 5 条）：去掉线路名 / 承运方（**库里的值保留**：UPDATE 时不参与，
  与 seat_info/gate 同一套）；出发地/到达地包进 `.loc-row` 真同一行；车辆按自驾显隐。
- **当前时间红线**（第 6 条）：位置在服务端算（与 `.tg-block` 同一套"24h = 100%"坐标），
  前端每分钟自己挪（对齐到下一分钟整再起定时器），跨午夜 reload；只画在**今天那一列**。
- **重复日程删除三档**（第 7 条）：与「编辑」那三档同名同序（全部 / 这一次及以后 /
  只这一次）。「只删这一次」→ `skipOnce`（**绝不删整条系列**）；「这一次及以后」→
  老系列截 UNTIL，**必须清掉 COUNT**（两者并存时 COUNT 优先，不清就截不断）。
- **提醒多选**（第 8 条）：同列存逗号串（`5,15,60`）；Schema 把它从 **INT 改 VARCHAR**
  （INT 存逗号串会被隐式转换，多档会静默只剩第一档）；ICS 导出吐**多个 VALARM**。
- **悬停统一**（第 9 条）：原来 14 种互不相干的 hover 底色 → 统一成**两套手法**：
  有底色 `filter: brightness(.92)` 同色系加深 + 轻抬升；描边白底 `--hov-veil` 中性薄雾
  + 边框微显。放在 CSS **最末**用一条兜底收口（新按钮自动继承），并把十几条旧规则
  清成"交给统一段"。`person_picker.js` 同时改为按需加载。

验证（本地全套）：
- e2e **1004/0**（+21 条本批断言）· 升级 149/0 · 桌面几何 428/0 ·
  **真机探针 25/0**（连续拖两次 / 红线位置与颜色与几何 / 车辆显隐 / 出发到达同行）。
- **反向验证 5/5**：①删除按钮改回嵌套 form ②卡片清单不 un-hide ③观影编辑不渲染海报
  ④车辆隐藏失效 ⑤「只删这一次」做成删全部 —— 五种坏法全部被抓住，还原后复绿 1004/0。
  过程中还**抓到两条弱断言**（只查 DOM 有无、不查可见性/是否真渲染），已一并加强。
- 部署脚本静态断言段本地空跑 **305 条全过**。
 2026-10-06 03:14:18 +08:00
laoyang e0562b8627 v24 第 5 轮：十条清单（天气填城市 / 输入即筛选 / 看板列＝看板 / 账本盘点折线图 / 纪念日分类） 
用户 2026-10-03 的十条，逐条落点：

1. 天气改为**个人设置里填城市**（每人一份）：新增 app/Geo.php，内置 197 个
   地级市坐标（离线、逐条核对，生成脚本 _tooling/_fb_geo_gen.py）。填坐标仍
   作为内置表没有时的出口；老的家庭级坐标保留为兜底，升级当天天气不会凭空消失。
2. 所有"找个人"的地方**输入即筛选**：新增 assets/js/filter.js（纯前端显隐，
   不发请求、回车不刷新）+ app/PersonQuery.php 把服务端判据收敛成一份
   （名册 / 挑人 / 高级搜索共用，避免三处实现漂移）。
3. 名册列表：有昵称就不重复显示本名、行变矮、补齐手机/阴历阳历生日(带年份)/
   邮箱/工作单位；「清除」与「搜索」同款同尺寸。
4/5. 日程：撤掉左侧日历本栏改满宽，功能（显隐/颜色/导入/默认视图）全收进
   右侧 ☰；**色块高度改为按起止时长**（旧实现一律 30 分钟，三小时的会跟
   十五分钟的同高）；点日历空白处即建日程，开始时间＝点的那一格。
6/10. 资源：搜索提到最上；按"最近改动/最新新增"排序，默认只显示最新 10 条并
   给「显示全部」出口。
7. 任务：看板的**列＝用户自定义的看板**（不再是写死的待办/进行中），
   拖动/左右键＝换看板（改 board_id，不动 status）。
8. 财务：概览在上账目在下、记一笔改右侧按钮、账本设置（共享/改名/新建/删除）
   收进 ☰、默认账本名「xxx的账本」、"挂在谁名下"默认自己且用标准选人框；
   **新增盘点**（新增 ledger_entry_snapshots 只增不改的历史表，旧值不被清空）
   + 上面画金额变化折线图（app/chart.php 服务端画 SVG，零依赖）。
9. 纪念日：手动添加的与名册生日派生的**分两块**、手动的在上；右侧设置可增删
   分类（家庭级，删分类不强改已用的历史）。

本轮另外修掉/加固的四类问题（都由新增的静态或运行时守卫兜住）：
- index.php 少写 2 个 use 导入（Pinyin / UserSetting）→ 名册与个人设置
  返回 200 但正文是 Fatal；顺带修了一处早已存在的 Attachment 未导入。
  → 新增 _fb_import_check.py（1f 段）。
- 一次不精确替换弄丢了 app/Calendar.php 开头的 `<?php`，整份源码被当 HTML
  吐给浏览器，而 `php -l` 报"无语法错误"（纯文本输出确实合法）。
  → 新增 _fb_php_open_check.py（1e 段）。
- 模板片段 unset 了宿主模板的变量（账本片段 unset($canWrite)）→ 正文里一片
  Undefined variable 而 HTTP 仍 200。同 _datetime.php 早年 $t 的坑。
  → 新增 _fb_fragment_scope_check.py（1g 段）+ _fb_batch_e.py 的 26 页无告警巡检。
- 窄屏下页头动作区不换行 → 周视图横向溢出且按钮被挤成三种高度（用户提过三次
  "按钮要同高"）→ .page-head .actions 加 flex-wrap。

验证战绩（全绿）：
  e2e 773/0 · 第 5 轮专项 91/0 · 结构升级 126/0 · 几何 428/0 · 移动端 684/0 ·
  交互 97/0 · 家谱 26/0 · 按钮 60/0；三轮反向验证各 3/3 抓到，还原后复绿。
线上：schema v14、指纹一致（9df6c9fccc6796db）、snapshots 表已建、197 城、
  8 个关键文件 md5 与本地逐字节一致、app/ 403 无源码泄漏、错误日志无新增。
 2026-10-03 15:01:38 +08:00
laoyang 02f5d072a4 家谱卡片重做 / 首页控制台 / 名册改列表 / 重复日程与旅程公开 
用户 2026-10-03 提的四条：

① 家谱卡片重做
   · 去掉「⇄ 姻亲」按钮，改成**每个人**卡片右下角都有「以 TA 为中心」
     （点了以他重画一张家谱，涵盖原来的姻亲场景）。
   · 头像外框改**长方形**（96×72，宽度贴合头像），object-fit: contain 不裁切，
     姓名/称呼在头像下方。
   · 修「点右下角按钮误进成员页」：卡片不再整张是 <a>，
     只有姓名是链接，右下角是独立的 <button>（物理上分开，不抢点击）。

② 家谱文案与按钮清理
   · 去掉副标题与下方图例说明；整块去掉「看全部 / 回到我 / 回到我的家谱」
     （顺带消掉"出现两个回到我的家谱"）。镜头由库自动 fit，拖拽/滚轮即可。

③ 首页控制台
   · 标题下显示个人 slogan；去掉右侧三个统计；「我的资料/我的家谱」换成图标按钮；
     去掉与导航条重复的「名册」按钮。
   · 去掉「接下来的日子」（生日归到"未来七天"里，不再重复）。
   · 新增统计信息块：按时段随机问候 + 今日天气（Open-Meteo，免 key，可留空不显示）
     + 近七天日程/待办/逾期数。
   · 新增各模块小结卡（任务/日程/纪念日/观影/旅程/财务/名册/家谱/资源）。
   · 个人设置新增「首页上的模块」：可勾选与拖动排序（每人一份，存 user_settings）。
   · 保留「往年的今天」。

④ 名册改列表
   · 卡片网格 → **竖向列表**：左头像、中间姓名+与我的关系+手机号+生日。
   · 修拖动「只能往后不能往前」：落点改为显式记录"插到谁前面/后面"，
     并排除被拖元素自身。
   · 去掉那句拖动提示（能力保留）。
   · 搜索新增**姓名首字母**检索（y / yy / yyq 都命中「杨永全」）：
     新 app/Pinyin.php，intl 优先 + 内置常用字表兜底（本地无 intl 也能测）；
     纯字母/数字查询词不走 SQL LIKE（拼音与加密手机号在库里都比不了）。

附带上两轮的收尾：
   · 菜单点外部自动关闭（全局事件委托，覆盖所有 details.menu）。
   · 旅程 is_public：列表与日历只显示公开的；详情页不拦（不丢数据）。
   · 重复日程：新 app/Repeat.php（RRULE 解析/生成/展开，含"工作日"），
     新表 calendar_event_skips（RFC 的 EXDATE）；日历按规则展开；
     编辑支持三档「全部 / 这一次及以后 / 仅此一次」。
   · 结束时间可添加/去掉，并随开始时间联动。

验证：端到端 772 项通过 / 0 失败；几何 368、交互 97、移动端 516、家谱 26、
升级 123 全绿；SQL 列名静态校验 0 处可疑；部署 11 条线上探针全过。
 2026-10-03 11:30:48 +08:00
laoyang 71a7ec35a0 v14: 观影/家谱/日程/旅程/资源/任务六模块统一，首页改 dashboard 
用户 14 条需求一次交付（1-13 功能 + 14 工作方式）。

观影（1-4）
- 返回文案全模块统一为「返回观影」（不再有「返回列表」「返回观影记录」三种叫法）
- 观影人一律用彩色人物标签 person_chip：底色由头像主色算出来（上传时存库），
  瀑布流卡片也按人显示；五处观影模板全部改用它
- 人员显示统一走 person_name()（shown → 我给他起的称呼 → 姓名）
- 影院管理页与年度报告页的上下两块用 .card + .card 统一给间距（原来紧贴成一整块）

家谱（5）
- 树根从「我」换成**辈分最高的祖先**：库画的是"树根的祖先链+后代+树根的兄弟姐妹"，
  根=我 时伯父/堂兄/嫂子/侄子一个都不画（12 人夹具只画出 8 人）
- focusMap 按**代数**圈定三代（不再按步数），normalizeLinks 把子女对称挂到父母双方
  —— 修掉"母亲登录看不到孩子"
- 新增「看全部 / 回到我」两个按钮，放在画布外（画布整块被库接管了手势）

统一事件原语（6-9）
- 旅程：TripLog 全量迁入（3 趟旅程 / 21 段行程 / 72 张照片 / 5 个人）。
  复用 events(kind='trip') + trip_details + trip_nodes（计划/执行双轨保留）
- 日程：每人可建日历本（自定义色）+ 共享只读/可写；观影与旅行是每人默认两本，
  内容是**从各模块实时派生**的（不复制，所以改了观影日期日历立刻跟着变）；
  没有具体时分 = 全天；月视图参照群晖 Calendar
- 资源：挂在某人名下的附属信息（标题+正文+多附件），可共享给多人并设只读/读写，
  默认折叠、可搜标题与正文
- 任务：看板三列 + 两级子任务 + 评论@人 + 共享 + 循环（完成时按原截止日推下一期）
- 统一附件表：四个模块的附件共用一张，下载地址不落库、一律由 media.php 现算

模块化（10-11）
- App\Module 是模块的唯一来源（加一行 = 导航条/主题色/个人设置三处自动出现）
- 个人设置里可勾选要显示哪些模块、拖动排序（关掉的模块**不会**被兜底补回来）
- 每个模块一套主题色（家庭级），只覆盖 --brand 三兄弟，不碰纸墨底色

其他（12-13）
- 新增成员表单可选所属分组（编辑表单没有：分组是"我和他的关系"，只归我自己）
- 首页改 dashboard：接下来的日子 / 未来七天 / 手头在做 / 往年今日。
  家人卡片从首页撤走（看人去名册）

验证（全部通过）
- e2e 542 条（新增 4 模块端到端 60+ 条）
- 桌面几何 368 / 移动端几何 520 / 家谱 12 / 交互 97 / 老库升级 123
- SQL 列名静态校验 0 处可疑（对着真实表结构）
- 反向验证 18 条新注入全部抓住

顺带修掉的既有问题
- 老库升级回填 SQL 按实际存在的列动态拼（缺列不再 1054 炸断升级）
- 全新安装时 Schema::ensure 跑在"人还没建"之前 → 补建日历本三处齐备
- 窄屏导航横向溢出（模块从 4 个加到 8 个后顶栏撑破视口）
 2026-10-02 09:28:07 +08:00
laoyang ed38a40c08 名册每人一份 · 分组两层 · 拖动排序 · 表单合一 · 裁剪可缩放 
按用户十点反馈逐条落地（v5，Schema::VERSION = 5）：

- 名册改成每人一份：新表 person_roster(owner_id, person_id, group_id,
  sort_order, source)。默认只看「我添加的 + 别人分享给我的」；
  source='seeded' 是升级时从老 persons.group_id 播进来的（先播数据再删列）。
- 排序不再手填：名册页直接拖动卡片（整版提交，一次 applyLayout 落库），
  无 JS 时卡片上的「调整分组」表单照旧可用。
- 分组分两层：管理员在「系统设置」维护公共分组（owner_id=0），
  用户在「个人设置」加自己的分组；显示顺序各人各定、互不影响。
- 名册可共享：把名片分享给别的用户（people/share）；添加成员时若系统里
  已有这个人，可直接复用（people/pick），不必重复录入。
- 「编辑成员」与「改我自己的资料」合并为同一张表（templates/people/form.php），
  两个入口 href 完全相同，h1 按改谁切换文案；个人设置页只留
  资料入口 + 称呼 + 我的分组三块，删除 templates/settings/_profile.php。
- 系统设置收进头像下拉，顶栏只剩 首页/家谱/名册。
- 裁剪器加缩放（滑块 1-4x、Ctrl+滚轮、还原）：缩放只改视图大小，
  落库的归一化矩形保持不变。
- 权限：管理员可以改任何人的权限（含自己），只拦「最后一位管理员」被降级。
- 去掉首页「我的一句话」后的链接、家谱说明段、以及「还没归到任何分组」提示。

迁移安全：数据回填（PersonRoster::seedFromPersons）先于删列执行、且不进
tryStep 容错；失败步骤记入 settings.schema_upgrade_warning 并在系统设置页提示。
线上已验证：schema_upgrade_warning 为空，person_roster/person_groups.owner_id
就位，persons.group_id / sort_order 已删。

验证：php -l 48 文件；本地 e2e 277/0、老库升级 81/0、桌面几何 108/0、
移动端几何 180/0、交互 96/0；反向验证 38 条注入 + 2 条缩放注入全部命中；
部署静态断言 53/0，站点自检 7/7（--resolve 锁本机走 443，探针真的进 PHP）。
 2026-09-30 13:24:26 +08:00
laoyang 1c460a0e83 图片可裁剪 · 名册按关系分组 · 个人设置独立 · 顶栏下拉菜单 
① 上传图片一律可裁剪，比例由图位决定
   新增 app/ImageSlot.php 统一配置（头像 1:1/512×512；题图 16:9 只留注释，
   将来启用只加一行）。前端只挑区域、写回归一化矩形 "x,y,w,h"，真正裁剪在服务端
   Upload::fitRegion()：夹回图内 → 在框内居中收缩到目标比例（不外扩）→ 钉住 sx+sw ≤ w。
   比例解析单独写 parseRatioAttr()：parseFloat('16:9') 得 16，会把题图裁成细长条且不报错。

② 名册按关系分组，顺序每人可自定
   分类全家共用（person_groups，另一个人可以自己加分类）；「自己的」只体现在顺序上
   （user_settings.group_order，每人一份）。persons.group_id 故意不加外键（老库只能
   ADD COLUMN），完整性由 PersonGroup 保证：删分类把人置回未分类，人不会从名册消失。

③ 设置分两级：系统设置 / 个人设置
   个人设置拆成 templates/settings/me.php + _profile.php + _nicknames.php，
   取代 templates/people/me.php（旧路由与旧表单仍兼容）。

④ 右上角「姓名/头像 + 下拉菜单」
   原来是两个裸链接，窄屏会被 CSS 藏掉导致改密码/退出不可达；改成 <details> 零 JS 菜单
   （app.js 只补「点外面 / Esc」）。菜单项：个人设置 / 系统设置（管理员）/ 修改密码 / 退出登录。

Schema 版本 3 → 4；安装与老库升级共用 PersonGroup::backfillMissing() 一条回填路径。

验证：php -l 全量；e2e 202/0（新增「关系分组」与「图片裁剪」两节）；老库升级 49/0；
桌面几何 108/0；移动端几何 192/0（360/375/390/414）；交互 76/0；
反向验证 31/31（逐条把修复改回旧写法，指定的目标断言必须变红）；
部署后本地↔线上 72 个文件 sha256 逐字节一致。
 2026-09-30 11:06:22 +08:00