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、无升级告警。
2026-09-30 16:12:28 +08:00
parent f7609a3ed9
commit 809443d429
5 changed files with 177 additions and 15 deletions
@@ -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
    {
@@ -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);
    }

    /** 某人身上挂着的全部关系（详情页编辑用） */
@@ -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(