FamilyBook/app/HomeMods.php

<?php
/**
 * 首页上显示哪些模块、什么顺序（用户 2026-10-03 第 3 条）。
 *
 * 原话：「在个人设置那里，要增加一个设置，用户可以选择，在首页上显示哪些模块，
 *        并且调整它们显示的顺序。」
 *
 * 与导航条那套（Module::navFor + nav_known）是**同一套思路**，所以这里刻意
 * 复用同样的三条纪律（踩过的坑不再踩第二遍）：
 *
 *   ① 存 user_settings（**每人一份**）—— 首页放什么是很个人的事；
 *   ② 只保留"还存在的模块"（删模块/改 key 之后，老配置里那条认不出来，
 *      直接渲染就是一张空卡）；
 *   ③ 另存一份 `home_known` =「用户做这次决定时，世上已知的全部模块」——
 *      只有 `现在的模块 - known` 才是**真的新装**、才该补进来。
 *      ⚠️ 不能写成"不在已选里就补"：那样用户**主动关掉**的模块下次请求就被补回来，
 *         「可配置显示哪些」直接失效（导航条那边就是这么踩过的）。
 */

declare(strict_types=1);

namespace App;

final class HomeMods
{
    /**
     * 首页**默认**显示哪些模块、什么顺序。
     *
     * 比默认导航条短一些：首页是"概览"，把九个模块都铺上去就成了一面墙。
     * 选的是"每天想看的那几个"。
     */
    public const DEFAULT_HOME = ['tasks', 'calendar', 'days', 'movies', 'trips', 'ledger', 'books'];

    /** 这个人首页上要显示哪些模块（按顺序） */
    public static function forPerson(int $personId): array
    {
        $raw = (string)UserSetting::get($personId, 'home_modules', '');
        $dec = $raw !== '' ? json_decode($raw, true) : null;
        if (!is_array($dec)) {
            return self::DEFAULT_HOME;      // 没配过（新装的人 / 重置过的）
        }

        // ① 只留还存在的模块（去重、保序）
        $saved = [];
        foreach ($dec as $k) {
            $k = (string)$k;
            if (Module::exists($k) && !in_array($k, $saved, true)) {
                $saved[] = $k;
            }
        }

        // ③ 新装的模块补到末尾（见类注释里的 ③）
        $known = [];
        $kraw  = (string)UserSetting::get($personId, 'home_known', '');
        $kdec  = $kraw !== '' ? json_decode($kraw, true) : null;
        if (is_array($kdec)) {
            foreach ($kdec as $k) {
                $k = (string)$k;
                if (Module::exists($k)) {
                    $known[$k] = true;
                }
            }
        }
        foreach (Module::keys() as $k) {
            if (!isset($known[$k]) && !in_array($k, $saved, true)) {
                $saved[] = $k;              // 真的新装 → 补进来
            }
        }
        return $saved;
    }

    /** 保存首页模块（顺序即数组顺序；不在数组里的就是关掉的） */
    public static function save(int $personId, array $keys): void
    {
        $out = [];
        foreach ($keys as $k) {
            $k = (string)$k;
            if (Module::exists($k) && !in_array($k, $out, true)) {
                $out[] = $k;
            }
        }
        UserSetting::set($personId, 'home_modules', json_encode($out, JSON_UNESCAPED_UNICODE));
        // 【关键】同时记下"此刻已知的全部模块"，这样才能区分
        // 「用户关掉的」与「后来新装的」（见 ③）
        UserSetting::set($personId, 'home_known',
            json_encode(Module::keys(), JSON_UNESCAPED_UNICODE));
    }

    /**
     * 设置页要用的展示顺序：已选的按现有顺序在前，未选的按模块表顺序在后。
     * 这样"关掉再打开"位置不会跳。
     */
    public static function orderedForPicker(int $personId): array
    {
        $on = self::forPerson($personId);
        $out = $on;
        foreach (Module::keys() as $k) {
            if (!in_array($k, $out, true)) {
                $out[] = $k;
            }
        }
        return $out;
    }
}