FamilyBook/app/PersonJob.php

<?php
/**
 * 工作经历：单位 / 职务 / 职称，**可以有多段**（v24 用户 2026-10-03 第 4 条）。
 *
 * 用户原话：「工作单位、职称、职务，都是可以填写多个的，因为一个人的工作可能会变，
 *            我们需要记住他工作和职务的变化。」
 *
 * 所以这里存的是**一条条经历**而不是三个字段：
 *   - 每段有 单位 / 职务 / 职称 / 起止年月 / 备注；
 *   - 没有结束年月的就是"当前"那一段（列表里排最前、标「现在」）；
 *   - 有起止的按时间倒序排（最近的在上面）。
 *
 * ⚠️ `persons.org` / `persons.title` **保留**，但语义变成"当前单位/当前职称的快照"：
 *    名册列表、家谱、观影人标签这些地方只需要"现在在哪儿"，不该为了一行文字去 JOIN
 *    一张历史表；而且已有数据不会因为这次改动而消失。
 *    → 保存时由 syncCurrent() 自动把"最新那段"回写到那两个字段。
 */

declare(strict_types=1);

namespace App;

final class PersonJob
{
    /** 一段经历：单位/职务/职称/起止/备注；timeline 里 sort 越小越靠前 */
    public const MAX = 20;      // 一个人最多留 20 段（再多也不会是真的工作史）

    /** 某个人的工作经历（当前那段在前，其余按开始时间倒序） */
    public static function list(int $personId): array
    {
        if ($personId <= 0) {
            return [];
        }
        $st = Database::get()->prepare(
            'SELECT * FROM person_jobs WHERE person_id = ?
              ORDER BY (end_ym IS NULL) DESC, COALESCE(start_ym, "") DESC, id DESC'
        );
        $st->execute([$personId]);
        return $st->fetchAll();
    }

    /**
     * **批量**取一批人的工作经历（一个人的当前段在前，其余按开始时间倒序）。
     *
     * 🔴 v62（用户 2026-10-19）：「现在名册的列表太空了，应该显示更多内容，
     *    例如**工作单位、职务**。」
     *    ⇒ 名册列表（上千人）要显示单位/职务，**不能**对每个人各调一次
     *      `list()` —— 那是 N+1 查询（1000 人 = 1000 次 SQL）。
     *      这里一次 `IN (...)` 取回来，再按 person_id 分桶。
     *
     * ⚠️ 返回的是**每个 id 的完整经历数组**（不是只给第一段）：
     *    端上列表只显示第一段（当前/最近的那段），但详情页要全部 ——
     *    同一份数据一次给足，省得端上为详情再打一次接口。
     * ⚠️ 排序与 `list()` **逐字一致**（当前段在前 → 开始时间倒序 → id 倒序）：
     *    否则"列表显示的单位"和"详情里第一段"会是两个不同的单位。
     *
     * @param int[] $personIds
     * @return array<int,array> person_id => [经历, …]（没有经历的人**不出现**在结果里）
     */
    public static function mapFor(array $personIds): array
    {
        $ids = array_values(array_unique(array_filter(
            array_map('intval', $personIds), static fn(int $v): bool => $v > 0)));
        if (count($ids) === 0) {
            return [];
        }
        // ⚠️ `IN (?,?,…)` 的占位符按实际个数生成 —— 不能直接把数组塞进去
        $ph = implode(',', array_fill(0, count($ids), '?'));
        $st = Database::get()->prepare(
            "SELECT * FROM person_jobs WHERE person_id IN ({$ph})
              ORDER BY person_id, (end_ym IS NULL) DESC, COALESCE(start_ym, \"\") DESC, id DESC"
        );
        $st->execute($ids);
        $out = [];
        foreach ($st->fetchAll() as $r) {
            $out[(int)$r['person_id']][] = $r;
        }
        return $out;
    }

    /**
     * 整组替换（与 Person::replaceContacts 同一套做法：表单里就是一组行，
     * 删行/改行/加行一起提交，最省心 —— 逐行增删要额外的行 id 体系）。
     *
     * ⚠️ 空行（单位、职务、职称都空）会被丢掉，不留垃圾行。
     */
    public static function replace(int $personId, array $rows): void
    {
        if ($personId <= 0) {
            return;
        }
        $db = Database::get();
        $db->prepare('DELETE FROM person_jobs WHERE person_id = ?')->execute([$personId]);

        $ins = $db->prepare(
            'INSERT INTO person_jobs (person_id, org, title, rank_name, start_ym, end_ym, note)
             VALUES (?,?,?,?,?,?,?)'
        );
        $n = 0;
        foreach ($rows as $row) {
            $org   = mb_substr(trim((string)($row['org'] ?? '')), 0, 120, 'UTF-8');
            $title = mb_substr(trim((string)($row['title'] ?? '')), 0, 120, 'UTF-8');
            $rank  = mb_substr(trim((string)($row['rank_name'] ?? '')), 0, 120, 'UTF-8');
            $note  = mb_substr(trim((string)($row['note'] ?? '')), 0, 200, 'UTF-8');
            if ($org === '' && $title === '' && $rank === '') {
                continue;               // 整行空 → 丢掉
            }
            if ($n >= self::MAX) {
                break;
            }
            $ins->execute([
                $personId,
                $org   !== '' ? $org : null,
                $title !== '' ? $title : null,
                $rank  !== '' ? $rank : null,
                self::ym($row['start_ym'] ?? ''),
                self::ym($row['end_ym'] ?? ''),
                $note !== '' ? $note : null,
            ]);
            $n++;
        }
        self::syncCurrent($personId);
    }

    /**
     * 把"当前那一段"回写到 persons.org / persons.title（列表页等地方读的是那两个字段）。
     *
     * 取"当前"的规则：**没有结束年月的那一段**优先；都填了结束时间就取开始时间最晚的。
     *
     * 🔴🔴 **经历表为空时什么都不做**（绝不把 org/title 清空）。
     *    这一条是实测踩出来的：老库里 `persons.org` 有值、但 `person_jobs` 还没有行
     *    （升级回填之前、或某次操作删光了经历）。此时如果按"取不到就置空"来写，
     *    任何一次 `replace()` 都会把**用户填的单位抹掉** —— 而 replace 被调用在
     *    "编辑资料"“导入联系人”这类常规路径上，等于随手一保存就丢数据。
     *    正确的语义是：**经历表是"更详细的那一份"，不是"唯一的一份"** ——
     *    它没内容时，就去尊重 org/title 里已有的值。
     */
    public static function syncCurrent(int $personId): void
    {
        $list = self::list($personId);
        if (!$list) {
            return;       // 见上面的说明：没有经历 ≠ 没有单位，别动
        }
        $cur = null;
        foreach ($list as $r) {
            if ($r['end_ym'] === null || $r['end_ym'] === '') {
                $cur = $r;
                break;              // list() 已把"无结束"的排在最前
            }
        }
        if ($cur === null) {
            $cur = $list[0];        // 全是历史：取最近一段（list 已按开始时间倒序）
        }
        Database::get()->prepare('UPDATE persons SET org = ?, title = ? WHERE id = ?')
            ->execute([
                $cur['org'] ?: null,
                // ⚠️ title 列里放「职务」，rank_name 放「职称」——两个都要能显示，
                //    列表页只显示 title，所以把职称拼在后面（有职务时"教授 · 博导"这样）。
                self::joinTitle($cur['title'] ?? '', $cur['rank_name'] ?? ''),
                $personId,
            ]);
    }

    /** 职务 + 职称 合成一个显示串（哪个空就只用另一个；都空返回 null） */
    public static function joinTitle(?string $title, ?string $rank): ?string
    {
        $t = trim((string)$title);
        $r = trim((string)$rank);
        if ($t !== '' && $r !== '') {
            return $t . ' · ' . $r;
        }
        $v = $t !== '' ? $t : $r;
        return $v !== '' ? $v : null;
    }

    /**
     * 从**旧的两个字段**造一段经历（升级回填用）。
     * @return array 一行 ['org','title','rank_name','start_ym','end_ym','note']
     */
    public static function rowFromLegacy(?string $org, ?string $title): ?array
    {
        $o = trim((string)$org);
        $t = trim((string)$title);
        if ($o === '' && $t === '') {
            return null;
        }
        // 老数据的 title 是"职务 / 职称"随手填的，分不出哪个是哪个 →
        // 整串放进 title（职务），rank_name 留空。不猜。
        return ['org' => $o, 'title' => $t, 'rank_name' => '',
                'start_ym' => '', 'end_ym' => '', 'note' => ''];
    }

    /** 'YYYY-MM' 归一化；不合法返回 null */
    private static function ym($v): ?string
    {
        $v = trim((string)$v);
        return preg_match('/^\d{4}-\d{2}$/', $v) ? $v : null;
    }
}