FamilyBook/app/PersonTag.php

<?php
/**
 * 名册标签（v28 用户 2026-10-07 第 5 条）。
 *
 * 用户原话：「名册的分组，用下来不太好，我感觉应该改成打标签，就是说，一个人，
 *            他可能并不是只在一个分组，例如，他既是我的小学同学，又是我的初中同学，
 *            就没法分组，改成标签，似乎更合理。」
 *
 * 于是把「一人一组」换成「一人多标签」。三条关键设计：
 *
 *   ① **每个人一份**（`owner_id`）—— 与 person_roster 同口径。
 *      我给他打「小学同学」，不该让全家的名册都多出这个标签；
 *      而且同一个人在我这儿是「球友」、在我妈那儿是「外甥」，本来就该各说各的。
 *
 *   ② **标签词直接存字符串，不建标签表** —— 与笔记模块同一条轻量取舍。
 *      建一张标签表就要处理"改名后历史怎么办""两个标签合并"，那是重型知识库才值
 *      的复杂度；这里标签就是"随手打的词"，靠 GROUP BY 现算完事。
 *
 *   ③ **不动 person_roster.group_id** —— 那一列是 vCard CATEGORIES 与老代码的读点，
 *      删掉会让"没跟上升级"的地方静默少一个字段。旧分组值已在 Schema 里
 *      一次性迁成同名标签（幂等），之后两边各走各的：新界面只认标签。
 */

declare(strict_types=1);

namespace App;

final class PersonTag
{
    /** 标签长度与数量上限（挡住"把一句话当标签"） */
    public const MAX_LEN   = 24;
    public const MAX_EACH  = 12;

    /**
     * 我的名册里每个人的标签：person_id => [tag, tag, ...]
     *
     * 一次取完（列表页要整页渲染），不做 N+1 —— 名册上千人时那是致命的。
     */
    public static function mapFor(int $familyId, int $ownerId): array
    {
        if ($familyId <= 0 || $ownerId <= 0) {
            return [];
        }
        $st = Database::get()->prepare(
            'SELECT person_id, tag FROM person_tags
              WHERE family_id = ? AND owner_id = ?
              ORDER BY person_id, position, id'
        );
        $st->execute([$familyId, $ownerId]);
        $out = [];
        foreach ($st->fetchAll() as $r) {
            $out[(int)$r['person_id']][] = (string)$r['tag'];
        }
        return $out;
    }

    /** 单个（详情/编辑页用） */
    public static function of(int $ownerId, int $personId): array
    {
        if ($ownerId <= 0 || $personId <= 0) {
            return [];
        }
        $st = Database::get()->prepare(
            'SELECT tag FROM person_tags WHERE owner_id = ? AND person_id = ?
              ORDER BY position, id'
        );
        $st->execute([$ownerId, $personId]);
        $out = [];
        foreach ($st->fetchAll() as $r) {
            $out[] = (string)$r['tag'];
        }
        return $out;
    }

    /**
     * 我用过的全部标签 + 各挂了几个（顶部筛选条用）。
     *
     * ⚠️ 只统计**我的名册里还在的人** —— 否则会出现"标签上写着 5 个，
     *    点进去只有 3 个"（另外 2 个已经被移出名册，标签行还在）。
     */
    public static function cloud(int $familyId, int $ownerId): array
    {
        if ($familyId <= 0 || $ownerId <= 0) {
            return [];
        }
        $st = Database::get()->prepare(
            'SELECT t.tag, COUNT(*) AS n
               FROM person_tags t
               JOIN person_roster r ON r.owner_id = t.owner_id AND r.person_id = t.person_id
              WHERE t.family_id = ? AND t.owner_id = ?
              GROUP BY t.tag
              ORDER BY n DESC, t.tag ASC'
        );
        $st->execute([$familyId, $ownerId]);
        return $st->fetchAll();
    }

    /**
     * 打标签时的**候选词**（名册卡片浮层 / 编辑页 / 新增页都用它）。
     *
     * 🔴 v54（用户 2026-10-16 第 2 条）—— 这条是本次改动的核心。
     *   用户原话：「现在名册里面给人打标签的时候，**这个标签数据是从哪读出来的**呀？
     *   在这个名册的设置页面，有很多分组，现在还叫分组。但是打标签的时候，
     *   **却不是从这些分组里读出来的**。所以现在应该在这个设置页面，不应该再叫
     *   「名册分组」了吧？应该叫「名册标签」，是不是？**应该从这里面把所有标签都读出来**吧？
     *   但是现在标签里面却只有几个，也不知道是从哪儿读出来的。」
     *
     * **真根因（用户观察得完全正确）**：
     *   · 设置页显示的词表来自 `person_groups`（**分组表**，管理员/我维护的词）；
     *   · 打标签的候选来自 `cloud()`（**你已经打过的词**，现算的）；
     *   ⇒ 两边**根本不是一个数据源** —— 所以"设置里列着一堆、打标签时却只有几个"。
     *
     * ⇒ 合并两者，**并集**：
     *   · 词表（`PersonGroup::orderFor` = 公共同我的）在前 —— 这是用户说的
     *     "应该从这里面把所有标签都读出来"；**还没用过**的词也要能一点就打上，
     *     这正是"词表"相对于"用过的词"的价值（否则新标签永远得手打）。
     *   · 用过的词补在后面（词表里没收录、但历史打过的，不能凭空消失）。
     *
     * ⚠️ 只返回**词**（`array_column(...,'tag')` 那种扁平字符串列表），
     *    与既有 `tagChoices` 的消费方（模板 `foreach` 出 checkbox）契约一致 ——
     *    不返回 cloud 那种 `[['tag'=>..,'n'=>..]]`，否则调用点全要改。
     * ⚠️ 那个 `suggest()` 已被它取代（原名容易让人以为是"按人气排序的联想词"，
     *    而实际需求是"设置里配的 + 用过的"并集）—— 保留一个没用处的旧口径
     *    只会让下一个人继续从 `cloud()` 读、把用户这条需求又绕过一遍。
     *
     * @return array<int,string>
     */
    public static function choices(int $familyId, int $ownerId, int $limit = 60): array
    {
        if ($familyId <= 0 || $ownerId <= 0) {
            return [];
        }
        $out = [];
        // ① 词表（设置页「名册标签」里配的那些：公共同我的，带顺序）
        foreach (PersonGroup::orderFor($familyId, $ownerId) as $g) {
            $nm = trim((string)($g['name'] ?? ''));
            if ($nm !== '' && !in_array($nm, $out, true)) {
                $out[] = $nm;
            }
        }
        // ② 我已经打过的词（词表里没收录的补上；按人气降序）
        foreach (self::cloud($familyId, $ownerId) as $r) {
            $t = (string)($r['tag'] ?? '');
            if ($t !== '' && !in_array($t, $out, true)) {
                $out[] = $t;
            }
        }
        return array_slice($out, 0, max(1, $limit));
    }

    /**
     * 整组替换某人的标签（名册卡片上改标签就用它）。
     *
     * 为什么是"整组替换"而不是逐个增删：界面是一次提交一整套标签的，
     * 逐个 diff 反而要处理"哪些是新增/哪些是删除"，代码多且容易漏。
     * 标签没有历史价值，全量重写最简单可靠。
     *
     * @param array|string $raw 数组，或一段用空格/逗号分隔的标签
     * @return array<int,string> 归一后真正写进去的标签（调用方可以回显）
     */
    public static function setFor(int $familyId, int $ownerId, int $personId, $raw): array
    {
        if ($familyId <= 0 || $ownerId <= 0 || $personId <= 0) {
            return [];
        }
        $tags = self::clean($raw);
        $db = Database::get();
        $db->prepare('DELETE FROM person_tags WHERE owner_id = ? AND person_id = ?')
           ->execute([$ownerId, $personId]);
        if (!$tags) {
            return [];
        }
        $st = $db->prepare(
            'INSERT INTO person_tags (family_id, owner_id, person_id, tag, position)
             VALUES (?,?,?,?,?)'
        );
        $pos = 10;
        foreach ($tags as $t) {
            $st->execute([$familyId, $ownerId, $personId, $t, $pos]);
            $pos += 10;
        }
        return $tags;
    }

    /** 删某人时把他的标签一起删（persons 外键也会级联，这里显式一次更稳）。 */
    public static function forgetPerson(int $personId): void
    {
        if ($personId <= 0) {
            return;
        }
        Database::get()->prepare('DELETE FROM person_tags WHERE person_id = ?')->execute([$personId]);
    }

    /**
     * 给某人**追加**一个标签（已存在则不重复）。
     *
     * 🔴 v54（用户 2026-10-16 第 2 条）：挑人 / 导入联系人时要用它。
     * 为什么必须是"追加"而不是 `setFor()`（整组替换）：
     *   `setFor` 会**先 DELETE 再 INSERT** —— 用在这里会把那些人
     *   **原有**的标签一起清掉。而这两个入口的语义是"顺手给新人打一个标签"，
     *   不是"把他们的标签改成这一个"。这种"用整组替换去做追加"的错，
     *   症状是"用一次导入，别人身上原有的标签全没了"，而且很难联想到原因。
     *
     * ⚠️ 靠 `uk_pt`（owner_id, person_id, tag 三列唯一）保证幂等：
     *    重复打同一个词会 `duplicate`，这里用 INSERT IGNORE 吞掉，不报错。
     * @return bool 这次真的插进去了吗（已存在 = false）
     */
    public static function addOne(int $familyId, int $ownerId, int $personId, string $tag): bool
    {
        $one = self::clean($tag);
        if ($familyId <= 0 || $ownerId <= 0 || $personId <= 0 || !$one) {
            return false;
        }
        $st = Database::get()->prepare(
            'INSERT IGNORE INTO person_tags (family_id, owner_id, person_id, tag, position)
             VALUES (?,?,?,?,?)'
        );
        $st->execute([$familyId, $ownerId, $personId, $one[0], 100]);
        return $st->rowCount() > 0;
    }

    /**
     * 标签归一：`#小学同学` / `小学同学 ` / `小学,同学` 都要变成干净的词。
     *
     * 与 Note::cleanTags 同一套规则（去 `#`、去空白、去重、限长限数）——
     * 两处各写一份迟早不一致（用户在笔记里能打 `#`，在名册里却打不了，最恼人）。
     */
    public static function clean($raw): array
    {
        $list = [];
        if (is_array($raw)) {
            $list = $raw;
        } elseif (is_string($raw)) {
            $list = preg_split('/[\s,，]+/u', $raw) ?: [];
        }
        $out = [];
        foreach ($list as $t) {
            $t = trim((string)$t);
            $t = ltrim($t, '#');
            // 空白与 `#` 都不能出现在标签内部（它们是分隔符）
            $t = (string)preg_replace('/[\s#]+/u', '', $t);
            if ($t === '') {
                continue;
            }
            $t = mb_substr($t, 0, self::MAX_LEN, 'UTF-8');
            if (!in_array($t, $out, true)) {
                $out[] = $t;
            }
            if (count($out) >= self::MAX_EACH) {
                break;
            }
        }
        return $out;
    }
}