laoyang
89b956205d
用户原话：「旅程这个模块，我准备大改…如果按照计划行程和实际行程来分别管理，
会变的很复杂…根据我的想法，重构这个模块。」
—— 这不是加需求，是把「双轨」架构换成「一条记录 + 状态机」。
## 用户确认的三个决定
1. 两层：**活动**（顶层容器）→ **行程**（挂其下，字段沿用原节点）
2. **修正不立即转实际**：修正只是记录，行程仍标"计划（已修正 N 次）"，
要再点一次「标记为实际」才转实际
3. 老数据**按现有轨道自动迁移**（category=reality → stage=actual）
## 状态机（本次重构的心脏）
trip_nodes.stage：
· plan 计划行程 —— 唯一以「计划时间」上日程的状态，三个动作都能用
· actual 实际行程 —— 上日程（实际时间）+ 进「往年今日」
· skipped 未成行 —— **不上日程、不进往年今日**，但旅程里仍显示并标注
（用户："还是要显示，只不过要标记上"）
旧的 category(plan/reality) 保留作兼容，业务一律看 stage（saveNode 同步维护两者）。
## 三个动作（Trip.php）
· reviseNode —— 记一次修正。🔴 **第一次修正前先把原计划存成 seq=1 快照**，
否则用户要的"之前的计划行程数据要保留，为了以后做对比"就落空。**不动 stage**。
可无限次（seq 递增）。
· completeNode —— 实际＝计划，直接转 actual，**不产生修正历史**（没有变化就没有历史）。
· markActual —— 把（已修正过的）计划正式转 actual。
· skipNode —— **不是真删**，只置 stage='skipped'（用户明确"不要真的删除，只是做一个标记"）。
· restoreNode —— 撤销未成行（点错了能改回来）。
界面上的「彻底删除」与「标记未成行」是两个并列动作，弹窗文案里写明区别。
## 修正历史（Schema v19，新表 trip_node_revisions）
每次修正一行：实际起止 / 实际地点 / 说明 / 参与人快照。
第 1 条 = 原计划快照，第 2..n 条 = 各次修正 —— 详情页用表格展示，可直接对比。
## 日历与往年今日（用户点名的联动）
· 日历：`n.stage IN ('plan','actual')` —— 去掉旧的 `status<>'cancelled'`
（那是双轨口径；现在"未成行"是 stage）。实际行程标题加 ✓ 前缀便于区分。
· **活动本身绝不上日程**（用户："活动因为可能跨越的时间比较长"）。
· 往年今日：旅程部分从「整趟 events」改成**实际行程**（stage='actual'），
标题带活动名前缀；未成行的不出现。
## 验证
新增 _trip_e2e12.py **30/0**：建活动 → 加行程（可选计划/实际）→ 修正（仍计划 /
历史保留原计划 09:00 / 可无限次）→ 标记为实际 → 完成（无历史）→ 标记未成行（未真删）
→ 日历四种情形（已转实际✓ 新建实际✓ 完成✓ 未成行✗ 活动✗）→ 往年今日只看实际。
回归：e2e 787/0、升级 129/0（含 v19 路径）、batch_e 91/0、batch10 46/0、batch9 38/0、
picker 28/0 + 11/0、crop 17/0、formbloat 9/0、semi 27/0、geom 5/5、mobile 688/0、
interact 92/0、drag 5/0。
e2e 两条旧断言（"双轨两块/两轨各一条"）按重构语义更新为"三组渲染 / stage 各一条
+ category 与 stage 同步"。
部署断言新增 1 大组，含**反退化防线**：skipNode 若被改成 DELETE 立即变红。
线上自检 19/19；线上真实账号验收 16/0。
线上老数据迁移实测：#222 计划3+实际1、#221 实际4、#220 实际13 —— 一条没丢。
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/。概念是「这本书就是家」：屋顶即一本摊开的书，
屋顶下纸做的墙上，三行横线是这个家写下的日子。