v7：家谱树与名册三处口径统一（树上的人自动互相可见）

用户反馈：我把一个人设成配偶、又设了我们的孩子，配偶登录后首页能看到
孩子、家谱也能看到，名册里却看不到——没分享的人却在家谱上看得到，
口径打架。

口径由用户拍板：**以每个人为中心上下三代那棵家谱树（= 首页「我的家人」
同一棵）里的人，自动进他名册（source=kin，默认归公共「家人」组）；
树外的人三处都不可见。**

- PersonRoster::syncKinForFamily()：整树同步（补缺、撤多余；已存在的
  self/shared/seeded 行绝不碰，用户改过的分组/顺序保留）。幂等。
- 同步挂在事件上：建边 / 解边 / 开通账号 / 结构升级回填。
- Relations::addParent/addSpouse 建边后同步；remove/detach 解边后同步。
- 名册不许单独移走 kin 来源的人（服务端拦截 + 人话提示 + 卡片隐藏
  移走按钮改提示语）：他在首页/家谱照样看得见，单藏名册只会回到口径
  打架；想不再看到他，解除关系即自动移出。
- 名册卡片给 kin 来源标「家谱」徽标（来历可辨）。
- Schema v7：widenRosterSourceEnum（⚠️ CREATE TABLE IF NOT EXISTS 不会
  更新已存在表的枚举，v6 老库不扩宽则 strict 模式下插 kin 整条被拒、
  且被容错吞掉——e2e 的 v6 旧库当场抓出）+ 按已有关系回填 kin 条目。

验证：e2e 309/0、升级专测 82/0、部署静态空跑 78/0、桌面几何 0 失败、
交互 97/0、移动几何 180/0；线上探针 ver=7、enum 含 kin、无升级告警。

app/PersonRoster.php

@@ -15,12 +15,18 @@
  *   · 我自己加的人（source=self）
  *   · 别人分享给我的名片（source=shared）
  *   · 升级时按当时"人人在自己名册里都能看到全家"的现状补的（source=seeded）
+ *   · **家谱树上的人**（source=kin，2026-09-30 v7 起）——
+ *     以我为中心上下三代那棵树（和首页「我的家人」同一棵）里的人，自动进我名册。
+ *     否则会撞出这种拧巴：家谱上看得见孩子、首页也有他，名册里却找不到
+ *     （2026-09-30 用户反馈：「我还没有分享给另外一个人，他应该都看不到才对吧」——
+ *      反过来说，只要关系建了，三处口径就必须一致：要都看得见）。
  * 除此之外一概看不见。所以「添加成员」时若这个人系统里已经有了，
  * 要引导用户走「从家里已有的人里挑」（见 pickable()），而不是又录一遍。
  *
  * ⚠️ 与 `persons.kind` 的关系：roster 只管"看不看得见"，
  *    家谱（Kinship）仍然按全家庭的 persons + relations 推导 ——
  *    名册是通讯录，家谱是血缘图，两者故意的不是一回事。
+ *    v7 之后两者的口径在「直接相邻的人」这一点上对齐了：有边 = 名册里也有。
  */
 
 declare(strict_types=1);
@@ -30,7 +36,7 @@ namespace App;
 final class PersonRoster
 {
     /** 名册里一条记录的来源 */
-    public const SOURCES = ['self', 'shared', 'seeded'];
+    public const SOURCES = ['self', 'shared', 'seeded', 'kin'];
 
     /**
      * 把某人加进某人的名册（幂等：已经在里面就什么都不做）。
@@ -195,6 +201,83 @@ final class PersonRoster
         return $n;
     }
 
+    /**
+     * 按家谱把全家的 kin 名册条目对齐一遍（v7）。
+     *
+     * 语义与首页「我的家人」**完全同一棵树**：以每个有账号的人为中心、上下各三代，
+     * 树里有的人 = 他名册里自动有（source=kin，默认归公共「家人」组）；
+     * 树里没有但名册里还挂着 kin 条目的 = 撤掉。这样三处口径（首页/家谱/名册）
+     * 永远是同一个集合 —— 2026-09-30 用户反馈的问题（配偶在家谱看得到孩子、
+     * 名册里却没有；没分享的人却能在家谱看到）就是这么来的。
+     *
+     * 为什么是「整棵树」而不是「直接相邻的人」：只记了「我是父亲」的孩子，
+     * 跟配偶之间没有直接边，但配偶在家谱/首页照样看得到他 —— 只同步直接相邻
+     * 治不了这个不一致。树的展开规则（含配偶同代等）只写一遍，在这里复用。
+     *
+     * 幂等：已存在的行不动（用户改过的分组/顺序保留），只补缺、撤多余的。
+     * 调用点：建边 / 解边 / 开通账号 / 结构升级回填 —— 名册口径可能变的所有时刻。
+     *
+     * @return array ['added' => int, 'dropped' => int]
+     */
+    public static function syncKinForFamily(int $familyId): array
+    {
+        // 有账号的人才是「owner」——没账号的永远登不进来，给他同步是死数据
+        $st = Database::get()->prepare(
+            'SELECT a.person_id FROM accounts a JOIN persons p ON p.id = a.person_id
+             WHERE p.family_id = ?'
+        );
+        $st->execute([$familyId]);
+        $owners = array_map('intval', $st->fetchAll(\PDO::FETCH_COLUMN));
+        if (!$owners) {
+            return ['added' => 0, 'dropped' => 0];
+        }
+        $people = Person::map($familyId);
+        if (!$people) {
+            return ['added' => 0, 'dropped' => 0];
+        }
+        $graph = Kinship::graph($familyId);
+        $gid   = PersonGroup::idByName($familyId, '家人');
+        $use   = $gid > 0 ? $gid : null;   // 公共「家人」被删了就落未分类，不为它再造分组
+
+        $db = Database::get();
+        $added = 0;
+        $dropped = 0;
+        foreach ($owners as $oid) {
+            $tree = Kinship::tree($graph, $oid, $people, 3, 3);
+            $want = [];
+            foreach (array_keys($tree['nodes']) as $nid) {
+                $nid = (int)$nid;
+                if ($nid !== $oid && isset($people[$nid])) {
+                    $want[] = $nid;
+                }
+            }
+            foreach ($want as $pid) {
+                if (self::ensure($familyId, $oid, $pid, $use, 'kin')) {
+                    $added++;
+                }
+            }
+            // 撤掉「树里已经没有、名册还挂着」的 kin 条目
+            //（只动 source='kin'：self/shared/seeded 是用户自己的名册，绝不碰）
+            if ($want) {
+                $in = implode(',', $want);
+                $del = $db->prepare(
+                    "DELETE FROM person_roster
+                     WHERE family_id = ? AND owner_id = ? AND source = 'kin'
+                       AND person_id NOT IN ({$in})"
+                );
+                $del->execute([$familyId, $oid]);
+            } else {
+                $del = $db->prepare(
+                    "DELETE FROM person_roster
+                     WHERE family_id = ? AND owner_id = ? AND source = 'kin'"
+                );
+                $del->execute([$familyId, $oid]);
+            }
+            $dropped += $del->rowCount();
+        }
+        return ['added' => $added, 'dropped' => $dropped];
+    }
+
     /** 从我的名册里移掉一个人（只是我不再看到他，人还在名册里、还在家谱上） */
     public static function remove(int $familyId, int $ownerId, int $personId): bool
     {

app/Relations.php

@@ -37,6 +37,8 @@ final class Relations
             'INSERT INTO relations (family_id, from_id, to_id, kind, from_role) VALUES (?,?,?,"parent",?)'
         );
         $st->execute([$familyId, $parentId, $childId, $role]);
+        // 家谱变了 ⇒ 全家每个账号的 kin 名册条目按新树对齐（v7，三处口径一致）
+        PersonRoster::syncKinForFamily($familyId);
         return ['ok' => true, 'error' => ''];
     }
 
@@ -54,27 +56,42 @@ final class Relations
         );
         $st->execute([$familyId, $a, $b, $b, $a]);
         if ($st->fetchColumn()) {
+            // 已存在 ≠ 什么都不做：名册那边可能还没跟上（老数据/升级前建的边），补一次
+            PersonRoster::syncKinForFamily($familyId);
             return ['ok' => true, 'error' => ''];
         }
         $st = $db->prepare(
             'INSERT INTO relations (family_id, from_id, to_id, kind) VALUES (?,?,?,"spouse")'
         );
         $st->execute([$familyId, $a, $b]);
+        PersonRoster::syncKinForFamily($familyId);
         return ['ok' => true, 'error' => ''];
     }
 
-    /** 解除某条关系（按 id） */
-    public static function remove(int $familyId, int $id): void
+    /**
+     * 解除某条关系（按 id）。
+     *
+     * ⚠️ v7 起「家谱树 ⇒ 名册自动同步」：边没了，树上够不着的人的 kin 名册条目
+     * 也跟着撤（可能不止这一对——比如解开「父子」，孩子就从配偶的名册里一起消失，
+     * 因为树是从配偶那边绕过我来展开的）。self/shared/seeded 的条目绝不碰。
+     *
+     * @return int 撤掉的 kin 名册条目数（路由层用它把话说全）
+     */
+    public static function remove(int $familyId, int $id): int
     {
-        Database::get()->prepare('DELETE FROM relations WHERE id = ? AND family_id = ?')
+        $db = Database::get();
+        $db->prepare('DELETE FROM relations WHERE id = ? AND family_id = ?')
             ->execute([$id, $familyId]);
+        $st = PersonRoster::syncKinForFamily($familyId);
+        return (int)$st['dropped'];
     }
 
-    /** 解除两人之间的某种关系 */
+    /** 解除两人之间的某种关系（与 remove() 同样的名册同步语义；当前无其他调用方） */
     public static function detach(int $familyId, int $personId, string $kind, string $role = ''): void
     {
         $sql = 'DELETE FROM relations WHERE family_id = ? AND to_id = ? AND kind = ? AND from_role = ?';
         Database::get()->prepare($sql)->execute([$familyId, $personId, $kind, $role]);
+        PersonRoster::syncKinForFamily($familyId);
     }
 
     /** 某人身上挂着的全部关系（详情页编辑用） */

app/Schema.php

@@ -32,8 +32,13 @@ final class Schema
      *   6 → **成员信息对齐 vCard**：person_contacts（多个电话 / 邮箱 / 地址 / 网址，
      *       对应 vCard 的 TEL / EMAIL / ADR / URL）+ persons.org / persons.title
      *       （工作单位 ORG / 职务职称 TITLE）。主手机号仍留在 persons（登录凭据）。
+     *   7 → **家谱树 ⇒ 名册自动同步**：以每个账号为中心上下三代的树里的人
+     *       自动进他名册（source=kin，归公共「家人」组），树外自动撤；
+     *       升级时按已有关系回填。起因：家谱/首页按关系推导可见，名册按分享推导
+     *       —— 同一个人三处口径打架（配偶能在家谱看到孩子、名册里却没有）。
+     *       用户拍板：树上的人三处都可见，没上树的都不可见。
      */
-    public const VERSION = '6';
+    public const VERSION = '7';
 
     /** @return string[] */
     public static function statements(): array
@@ -325,6 +330,22 @@ SQL,
         //    搬进 contacts 反而把「登录凭据」和「联系信息」搅在一起。
         //    contacts 里的 phone 是**额外的**电话，一样加密存。
 
+        // ---- 家谱树 ⇒ 名册自动同步（版本 7）----
+        // ⚠️ 先扩宽 source 枚举再回填：v6 老库的枚举只有 self/shared/seeded，
+        //    建表语句里的 IF NOT EXISTS **不会**更新已存在表的枚举 ——
+        //    不扩宽的话，回填插 source='kin' 会被严格模式整条拒掉，
+        //    而且 ensure() 的容错会把这条失败悄悄吞掉（线上表现＝功能像没生效）。
+        self::widenRosterSourceEnum($db);
+        // 已有的关系也要补出 kin 名册条目：升级完的当下口径就对齐，
+        // 而不是等用户哪天再点一次「保存关系」才生效。
+        // syncKinForFamily 幂等（只补缺、撤多余，用户改过的分组/顺序不动），
+        // 重复跑不插重；某条脏数据只影响它自己，容错跑，别挡住后面的步骤。
+        self::tryStep('按家谱回填名册（kin 与首页同一棵树）', static function () use ($db) {
+            foreach ($db->query('SELECT id FROM families')->fetchAll() as $fam) {
+                \App\PersonRoster::syncKinForFamily((int)$fam['id']);
+            }
+        });
+
         // 被容错跳过的数据步骤记进设置，系统设置页会把它显出来 ——
         // 不然「升级没跑完」这件事只活在日志里，跟没发生一样。
         if (self::$stepErrors) {
@@ -430,6 +451,24 @@ SQL,
         }
     }
 
+    /** person_roster.source 原本只有 self/shared/seeded，v7 起要加 kin（见 ensure 里的说明） */
+    private static function widenRosterSourceEnum(\PDO $db): void
+    {
+        $st = $db->prepare(
+            "SELECT COLUMN_TYPE FROM information_schema.COLUMNS
+             WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'person_roster' AND COLUMN_NAME = 'source'"
+        );
+        $st->execute();
+        $type = (string)$st->fetchColumn();
+        if ($type !== '' && strpos($type, 'kin') === false) {
+            $db->exec(
+                "ALTER TABLE `person_roster` MODIFY COLUMN `source`
+                 ENUM('self','shared','seeded','kin') NOT NULL DEFAULT 'self'
+                 COMMENT 'self=我自己加的 / shared=别人分享给我的 / seeded=升级时按当时可见范围补的 / kin=家谱树自动同步（v7）'"
+            );
+        }
+    }
+
     private static function hasIndex(\PDO $db, string $table, string $index): bool
     {
         $st = $db->prepare(

index.php

@@ -522,9 +522,17 @@ switch ($r) {
         $pid = (int)($_POST['person_id'] ?? 0);
         $p   = Person::find($pid);
         if ($p && (int)$p['family_id'] === (int)Auth::familyId()) {
+            // v7：家谱关系带来的人不许「移走」——他在首页/家谱上照样看得见，
+            // 单独从名册藏掉只会把三处口径又搅回打架的状态。
+            // 想不再看到他，解除那条关系（名册条目会跟着自动收回）。
+            $src = (string)(PersonRoster::mine((int)Auth::familyId(), (int)Auth::personId())[$pid]['source'] ?? '');
+            if ($src === 'kin') {
+                flash('err', '「' . $p['name'] . '」是因为家谱关系自动进你名册的，不能单独移走；解除关系后他会自动移出。');
+            } else {
                 PersonRoster::remove((int)Auth::familyId(), (int)Auth::personId(), $pid);
                 flash('ok', '已把「' . $p['name'] . '」从你的名册里移走（他还在家里）。');
             }
+        }
         redirect('people');
         break;
 
@@ -1015,6 +1023,8 @@ switch ($r) {
         }
         $r0 = (string)($_POST['role'] ?? '');
         Account::create($personId, $pass, in_array($r0, Account::ROLES, true) ? $r0 : 'member');
+        // v7：多了一个「看家谱的人」——他的名册也要按树播种，一登录三处口径就是对的
+        PersonRoster::syncKinForFamily((int)Auth::familyId());
         flash('ok', '账号已开通，用手机号就能登录。');
         redirect('people/show', ['id' => $personId]);
         break;
@@ -1104,8 +1114,12 @@ switch ($r) {
         $familyId = (int)Auth::familyId();
         $id  = (int)($_POST['id'] ?? 0);
         $who = (int)($_POST['person_id'] ?? 0);
-        Relations::remove($familyId, $id);
-        flash('ok', '这条关系已解除。');
+        $kinRemoved = Relations::remove($familyId, $id);
+        // v7：关系没了，因这条关系自动进两端名册的条目也收回 —— 把这件事说破，
+        // 不然用户会以为名册里的人凭空消失了
+        flash('ok', $kinRemoved
+            ? '这条关系已解除，两人名册里因此自动加入的对方也一并移出了。'
+            : '这条关系已解除。');
         redirect('people/show', ['id' => $who]);
         break;
 

templates/people/index.php

@@ -77,6 +77,11 @@ $renderGrid = function (array $list) use ($meId, $canMove, $groups): void {
                 if ($pNick !== '' && $pNick !== (string)$p['name']) {
                     echo ' · <span class="muted">' . e((string)$p['name']) . '</span>';
                 }
+                // v7：因家谱关系自动进名册的人，标出来历 ——
+                // 不然"我没加过他，他怎么在我名册里"会让人怀疑数据坏了
+                if (($p['roster_source'] ?? '') === 'kin') {
+                    echo ' <span class="badge" title="他在你的家谱树上（配偶/父母/子女/祖孙…），自动加入你的名册">家谱</span>';
+                }
                 ?>
               </div>
             </div>
@@ -99,11 +104,15 @@ $renderGrid = function (array $list) use ($meId, $canMove, $groups): void {
                 </select>
                 <button class="btn btn-ghost btn-sm" type="submit" data-no-drag>移动</button>
               </form>
+              <?php if (($p['roster_source'] ?? '') === 'kin'): ?>
+                <p class="small muted person-move" style="margin:4px 0 0">因家谱关系自动加入；解除关系后自动移出。</p>
+              <?php else: ?>
                 <form method="post" action="<?= e(url('people/forget')) ?>" class="person-move">
                   <?= csrf_field() ?>
                   <input type="hidden" name="person_id" value="<?= $pid ?>">
                   <button class="btn btn-ghost btn-sm" type="submit" data-no-drag>从我的名册移走</button>
                 </form>
+              <?php endif; ?>
             </details>
           <?php endif; ?>
         </div>