FamilyBook/app/Schema.php

<?php
/**
 * 建表语句与结构升级（安装向导与运行时共用同一份）。
 *
 * 五条约定：
 *   1. 全部 IF NOT EXISTS —— 重复执行不破坏已有数据
 *   2. 字符集一律 utf8mb4_unicode_ci，emoji 与人名生僻字都不会乱码
 *   3. 一切业务数据挂在 family_id 下，将来要支持多个家庭也不必改模型
 *   4. 手机号存两份：phone_hash 用于登录查找（确定性哈希），phone_encrypted 用于展示
 *   5. 结构升级走 ensure()，不靠人手动改库 —— 已上线的库也能自己长出新列
 */

declare(strict_types=1);

namespace App;

final class Schema
{
    /**
     * 当前结构版本。**唯一来源** —— index.php 的 FB_SCHEMA_VERSION 与
     * install.php 的盖章都取自这里，别在两处各写一个字符串（迟早会漂移）。
     *
     * 版本史：
     *   1 → 初始（families/persons/accounts/settings/relations）
     *   2 → birth_rank、is_placeholder、accounts.role 加 guest
     *   3 → 三个生日（birthday 升 DATETIME + id_card/lunar/leap）、slogan、nicknames 表
     *   4 → person_groups（关系分组，全家统一但可自定义）、persons.group_id、
     *       user_settings（「我的」维度设置：分组顺序等）
     */
    public const VERSION = '4';

    /** @return string[] */
    public static function statements(): array
    {
        return [
            <<<'SQL'
CREATE TABLE IF NOT EXISTS `families` (
  `id`         INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `name`       VARCHAR(100) NOT NULL COMMENT '家庭名称',
  `motto`      VARCHAR(200) DEFAULT NULL COMMENT '一句话，展示在首页',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='家庭空间（一切数据的根）'
SQL,
            <<<'SQL'
CREATE TABLE IF NOT EXISTS `persons` (
  `id`                INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `family_id`         INT UNSIGNED NOT NULL,
  `kind`              ENUM('member','contact') NOT NULL DEFAULT 'member' COMMENT '家庭成员 / 外部联系人',
  `name`              VARCHAR(50)  NOT NULL COMMENT '姓名',
  `nickname`          VARCHAR(50)  DEFAULT NULL COMMENT '【旧语义，已废弃】全家共用的小名；升级时搬进 nicknames 表，新代码不再读写它',
  `gender`            ENUM('m','f','x') DEFAULT NULL COMMENT '男 / 女 / 未填写',
  `birth_rank`        INT          DEFAULT NULL COMMENT '家中排行（同一对父母的子女里，1=老大），用来算长子/次女',
  `birthday`          DATE         DEFAULT NULL COMMENT '生日（自动生成日历上的生日日程用）',
  `avatar`            VARCHAR(255) DEFAULT NULL COMMENT '头像，相对于 uploads/avatars',
  `phone_hash`        CHAR(64)     DEFAULT NULL COMMENT '手机号 sha256，登录查找用；NULL 不参与唯一约束',
  `phone_encrypted`   VARCHAR(512) DEFAULT NULL COMMENT 'AES 加密的手机号',
  `id_card_encrypted` VARCHAR(512) DEFAULT NULL COMMENT 'AES 加密的身份证号',
  `email`             VARCHAR(120) DEFAULT NULL,
  `address`           VARCHAR(200) DEFAULT NULL,
  `note`              TEXT         DEFAULT NULL COMMENT '备注',
  `is_placeholder`    TINYINT(1) NOT NULL DEFAULT 0 COMMENT '虚拟人物：还没弄清真实身份的占位（如「我的父亲」）',
  `group_id`          INT UNSIGNED DEFAULT NULL COMMENT '关系分组（人属于哪一组：家人/同事/朋友…），全家人共用一套分类',
  `sort_order`        INT NOT NULL DEFAULT 1000 COMMENT '名册排序，小的在前',
  `created_at`        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at`        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_phone_hash` (`phone_hash`),
  KEY `idx_family_kind` (`family_id`, `kind`, `sort_order`),
  KEY `idx_person_group` (`group_id`),
  CONSTRAINT `fk_persons_family` FOREIGN KEY (`family_id`) REFERENCES `families` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='家庭名册'
SQL,
            <<<'SQL'
CREATE TABLE IF NOT EXISTS `accounts` (
  `id`            INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `person_id`     INT UNSIGNED NOT NULL COMMENT '一个人最多一个账号',
  `password_hash` VARCHAR(255) NOT NULL,
  `role`          ENUM('admin','member','guest') NOT NULL DEFAULT 'member' COMMENT '管理员 / 家庭成员 / 访客',
  `status`        ENUM('active','disabled') NOT NULL DEFAULT 'active',
  `last_login_at` DATETIME DEFAULT NULL,
  `created_at`    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_account_person` (`person_id`),
  CONSTRAINT `fk_accounts_person` FOREIGN KEY (`person_id`) REFERENCES `persons` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='登录账号'
SQL,
            <<<'SQL'
CREATE TABLE IF NOT EXISTS `relations` (
  `id`         INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `family_id`  INT UNSIGNED NOT NULL,
  `from_id`    INT UNSIGNED NOT NULL COMMENT '关系的一端',
  `to_id`      INT UNSIGNED NOT NULL COMMENT '关系的另一端',
  `kind`       ENUM('parent','spouse') NOT NULL COMMENT 'parent: from 是 to 的父/母；spouse: 配偶（对称）',
  `from_role`  ENUM('father','mother') DEFAULT NULL COMMENT 'kind=parent 时必填：from 相对 to 是父亲还是母亲',
  `note`       VARCHAR(200) DEFAULT NULL,
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_rel` (`from_id`,`to_id`,`kind`,`from_role`),
  KEY `idx_rel_from` (`from_id`,`kind`),
  KEY `idx_rel_to`   (`to_id`,`kind`),
  CONSTRAINT `fk_rel_family` FOREIGN KEY (`family_id`) REFERENCES `families` (`id`) ON DELETE CASCADE,
  CONSTRAINT `fk_rel_from`   FOREIGN KEY (`from_id`)   REFERENCES `persons` (`id`) ON DELETE CASCADE,
  CONSTRAINT `fk_rel_to`     FOREIGN KEY (`to_id`)     REFERENCES `persons` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='亲属关系：只存相邻两代之间的边，其余靠推导'
SQL,
            <<<'SQL'
CREATE TABLE IF NOT EXISTS `settings` (
  `family_id` INT UNSIGNED NOT NULL,
  `k`         VARCHAR(64)  NOT NULL,
  `v`         TEXT         DEFAULT NULL,
  PRIMARY KEY (`family_id`, `k`),
  CONSTRAINT `fk_settings_family` FOREIGN KEY (`family_id`) REFERENCES `families` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='家庭级键值对设置'
SQL,
            <<<'SQL'
CREATE TABLE IF NOT EXISTS `nicknames` (
  `family_id`  INT UNSIGNED NOT NULL,
  `viewer_id`  INT UNSIGNED NOT NULL COMMENT '谁在称呼别人（当前登录的人）',
  `target_id`  INT UNSIGNED NOT NULL COMMENT '被称呼的人',
  `nickname`   VARCHAR(50)  NOT NULL COMMENT '我叫他/她什么',
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`viewer_id`, `target_id`),
  KEY `idx_nick_family` (`family_id`),
  KEY `idx_nick_target` (`target_id`),
  CONSTRAINT `fk_nick_family` FOREIGN KEY (`family_id`) REFERENCES `families` (`id`) ON DELETE CASCADE,
  CONSTRAINT `fk_nick_viewer` FOREIGN KEY (`viewer_id`) REFERENCES `persons` (`id`) ON DELETE CASCADE,
  CONSTRAINT `fk_nick_target` FOREIGN KEY (`target_id`) REFERENCES `persons` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='称呼是视角属性：每个人各自决定怎么称呼别人，不挂在被称呼者身上'
SQL,
            <<<'SQL'
CREATE TABLE IF NOT EXISTS `person_groups` (
  `id`         INT UNSIGNED NOT NULL AUTO_INCREMENT,
  `family_id`  INT UNSIGNED NOT NULL,
  `name`       VARCHAR(20)  NOT NULL COMMENT '分组名，如「家人」「同事」',
  `position`   INT NOT NULL DEFAULT 100 COMMENT '默认顺序（用户没自定义顺序时按它排）',
  `is_builtin` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1=安装时预置的分组',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_group_name` (`family_id`, `name`),
  KEY `idx_group_family` (`family_id`, `position`),
  CONSTRAINT `fk_group_family` FOREIGN KEY (`family_id`) REFERENCES `families` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='关系分组：全家人共用一套（一个人只属于一个分组），但每个人可以各自决定分组的先后'
SQL,
            <<<'SQL'
CREATE TABLE IF NOT EXISTS `user_settings` (
  `person_id`  INT UNSIGNED NOT NULL COMMENT '这条设置属于谁（登录者本人）',
  `k`          VARCHAR(64)  NOT NULL,
  `v`          TEXT         DEFAULT NULL,
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`person_id`, `k`),
  CONSTRAINT `fk_uset_person` FOREIGN KEY (`person_id`) REFERENCES `persons` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='「我自己的」设置：只影响我自己看到的样子'
SQL,
        ];
    }

    /** 安装时预置的关系分组（用户可自行增删改名，这里只是初始值） */
    public const DEFAULT_GROUPS = [
        '家人'     => 10,
        '亲戚'     => 20,
        '同事'     => 30,
        '朋友'     => 40,
        '合作伙伴' => 50,
        '认识'     => 60,
        '不熟'     => 70,
    ];

    /**
     * 幂等结构升级：建表 + 补齐后加的列/枚举值。
     *
     * ⚠️ CREATE TABLE IF NOT EXISTS 对**已存在的表**什么都不做 ——
     *    所以给老库加列必须显式 ALTER，而且要先查 information_schema 再改，
     *    否则第二次执行会报 Duplicate column。这就是「部署即可升级」的全部秘密。
     */
    public static function ensure(): void
    {
        $db = Database::get();
        foreach (self::statements() as $sql) {
            $db->exec($sql);
        }
        self::addColumn($db, 'persons', 'birth_rank',
            "ADD COLUMN `birth_rank` INT DEFAULT NULL COMMENT '家中排行（同一对父母的子女里，1=老大），用来算长子/次女' AFTER `gender`");
        self::addColumn($db, 'persons', 'is_placeholder',
            "ADD COLUMN `is_placeholder` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '虚拟人物：还没弄清真实身份的占位（如「我的父亲」）' AFTER `note`");
        self::widenRoleEnum($db);

        // ---- 三个生日（版本 3）----
        // birthday 原本是 DATE，现在要精确到时分秒 → 升成 DATETIME。
        // MODIFY 是幂等的（已经是 DATETIME 时再 MODIFY 也不报错、不丢数据）。
        $db->exec("ALTER TABLE `persons` MODIFY COLUMN `birthday`
                   DATETIME DEFAULT NULL COMMENT '真实阳历生日（精确到时分秒）'");
        self::addColumn($db, 'persons', 'birthday_id_card',
            "ADD COLUMN `birthday_id_card` DATE DEFAULT NULL COMMENT '身份证上的生日：由身份证第 7-14 位推导，只读、永不变' AFTER `birthday`");
        self::addColumn($db, 'persons', 'birthday_lunar',
            "ADD COLUMN `birthday_lunar` DATETIME DEFAULT NULL COMMENT '农历生日：**日期部分是农历年月日**，时间部分与阳历一致' AFTER `birthday_id_card`");
        self::addColumn($db, 'persons', 'birthday_lunar_leap',
            "ADD COLUMN `birthday_lunar_leap` TINYINT(1) NOT NULL DEFAULT 0 COMMENT 'birthday_lunar 的月份是否为闰月' AFTER `birthday_lunar`");
        self::addColumn($db, 'persons', 'slogan',
            "ADD COLUMN `slogan` VARCHAR(200) DEFAULT NULL COMMENT '个人的一句话；没填就用家庭统一的那句' AFTER `note`");

        // 老数据里 birthday 若是 DATE，升成 DATETIME 后时间部分自动是 00:00:00，无需回填。
        // 把老数据补出农历生日：只在还没算过时算一次（幂等）。
        self::backfillLunarBirthday($db);
        self::backfillIdCardBirthday($db);

        // ---- 称呼从「人的属性」改成「视角属性」----
        // 老语义：persons.nickname 是全家共用的小名。
        // 新语义：nicknames 表，(viewer, target) → 我叫他什么。
        // ⚠️ 必须在这里搬：不然升级之后界面上再没有人读 persons.nickname，
        //    用户会觉得"以前填的小名一夜之间全没了"。搬的时候给每个账号都写一份，
        //    迁移前后大家看到的叫法完全一致（`Nickname::migrateLegacy` 里说明了原因）。
        //    放在结构升级里、而不是"某次请求里顺手做"，是为了升级完就已经搬好。
        foreach ($db->query('SELECT id FROM families')->fetchAll() as $fam) {
            \App\Nickname::migrateLegacy((int)$fam['id']);
        }

        // ---- 关系分组（版本 4）----
        // persons 新增 group_id。这里**不加外键**：老库只能 ADD COLUMN，加不上约束，
        // 新装的加了就会两边结构不一致；统一由 PersonGroup 保证不留悬空 id。
        self::addColumn($db, 'persons', 'group_id',
            "ADD COLUMN `group_id` INT UNSIGNED DEFAULT NULL COMMENT '关系分组（人属于哪一组：家人/同事/朋友…），全家人共用一套分类' AFTER `is_placeholder`");
        // 每个家庭都要有一套预置分组（新装的由 install.php 建，老的在这里补）
        foreach ($db->query('SELECT id FROM families')->fetchAll() as $fam) {
            \App\PersonGroup::seedDefaults((int)$fam['id']);
        }
        // 老库的人还没有分组 → 按名册类型补：家庭成员=家人、外部联系人=认识。
        // 只补空的，用户自己改过的一律不动。
        \App\PersonGroup::backfillMissing($db);
    }

    /** 老库已有阳历生日但没有农历生日 → 补算一次。用「为空」作条件，天然幂等。 */
    private static function backfillLunarBirthday(\PDO $db): void
    {
        $st = $db->query(
            "SELECT id, birthday FROM persons
             WHERE birthday IS NOT NULL AND (birthday_lunar IS NULL OR birthday_lunar = '')"
        );
        $rows = $st->fetchAll();
        if (!$rows) {
            return;
        }
        $up = $db->prepare('UPDATE persons SET birthday_lunar = ?, birthday_lunar_leap = ? WHERE id = ?');
        foreach ($rows as $r) {
            $bd = substr((string)$r['birthday'], 0, 10);
            [$y, $m, $d] = array_map('intval', explode('-', $bd));
            $lu = \App\Lunar::solarToLunar($y, $m, $d);
            if ($lu === null) {
                continue;
            }
            $up->execute([
                sprintf('%04d-%02d-%02d %s', $lu['year'], $lu['month'], $lu['day'], substr((string)$r['birthday'], 11, 8) ?: '00:00:00'),
                $lu['is_leap'] ? 1 : 0,
                (int)$r['id'],
            ]);
        }
    }

    /** 老库已有身份证号但没有「身份证生日」→ 推导一次。同样以「为空」为条件。 */
    private static function backfillIdCardBirthday(\PDO $db): void
    {
        $st = $db->query(
            "SELECT id, id_card_encrypted FROM persons
             WHERE id_card_encrypted IS NOT NULL AND id_card_encrypted <> ''
               AND (birthday_id_card IS NULL)"
        );
        $rows = $st->fetchAll();
        if (!$rows) {
            return;
        }
        $up = $db->prepare('UPDATE persons SET birthday_id_card = ? WHERE id = ?');
        foreach ($rows as $r) {
            try {
                $id = \App\Crypto::decrypt((string)$r['id_card_encrypted']);
            } catch (\Throwable $ex) {
                continue;   // 密钥换过 / 解不开就跳过，绝不能因此让整次升级失败
            }
            $bd = \App\Birthday::fromIdCard($id);
            if ($bd !== null) {
                $up->execute([$bd, (int)$r['id']]);
            }
        }
    }

    /** 列不存在才加 */
    private static function addColumn(\PDO $db, string $table, string $column, string $alter): void
    {
        $st = $db->prepare(
            'SELECT COUNT(*) FROM information_schema.COLUMNS
             WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?'
        );
        $st->execute([$table, $column]);
        if ((int)$st->fetchColumn() === 0) {
            $db->exec("ALTER TABLE `{$table}` {$alter}");
        }
    }

    /** accounts.role 原本只有 admin/member，升级时要把 guest 加进枚举 */
    private static function widenRoleEnum(\PDO $db): void
    {
        $st = $db->prepare(
            "SELECT COLUMN_TYPE FROM information_schema.COLUMNS
             WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'accounts' AND COLUMN_NAME = 'role'"
        );
        $st->execute();
        $type = (string)$st->fetchColumn();
        if ($type !== '' && strpos($type, 'guest') === false) {
            $db->exec(
                "ALTER TABLE `accounts` MODIFY COLUMN `role`
                 ENUM('admin','member','guest') NOT NULL DEFAULT 'member'
                 COMMENT '管理员 / 家庭成员 / 访客'"
            );
        }
    }
}