阶段 0 完整版：名册 + 账号 + 安装向导 + 设置（宣纸主题）

这一版把「家」的地基铺完：功能 - 安装向导 install.php：建四张表 → 建家庭 → 建第一人（兼管理员），装完自删；「是否已装」以数据库四张表为准，不以文件是否存在为准 - 家庭名册：成员增删改查、头像上传（居中裁方 512×512 转 JPEG、finfo 校验、随机文件名）、生日自动算年龄与倒数天数 - 敏感信息加密存储：手机号双写（SHA-256 哈希用于登录 + AES-256-CBC 密文用于显示）、身份证只存密文；页面上永远只显示脱敏后的 138****8000 / 前 6 后 4 - 账号体系：人与账号分离（孩子可入名册但无需密码）、开通/停用/角色、防爆破（5 次失败锁 60 秒）、修改密码、最后一个管理员不可移除 - 设置页：家庭名称与座右铭、加密密钥状态 - 宣纸主题 UI：砖红取自图标，扁平、留白充足；移动端顶栏收紧不换行安全 - 所有 POST 走 CSRF；输出全量 e() 转义；uploads/ 禁执行脚本 - app/ 与 templates/ 加 .htaccess 整体拒绝直连（直接请求模板会 Fatal 并把服务器绝对路径打在页面上 —— 这是线上真实抓到过的问题） - 已安装的 install.php 返回 404；display_errors 线上关闭工程 - 无框架无 Composer，query-string 路由（index.php?r=模块/动作），不依赖 rewrite - 静态资源带 mtime+size 版本号，改版后浏览器不会吃旧缓存 - 配套部署与冒烟（_tooling/，不入库）：部署脚本容忍 tar 对非属主目录的元数据回填失败；冒烟断言「状态码 + 正文无 PHP 错误 + </html> 收尾 + 无绝对路径泄露 + 断言总数下限」—— 只看状态码会把「200 但正文中间 Fatal」当成通过，这一版在线上真实抓到过一次
2026-09-30 00:49:53 +08:00
parent ecafa110f2
commit 8eb19267bc
30 changed files with 2462 additions and 123 deletions
@@ -0,0 +1,139 @@
+<?php
+/**
+ * 全局辅助函数（由 bootstrap.php 引入，页面无需重复 require）
+ */
+
+declare(strict_types=1);
+
+/** HTML 转义：所有输出到页面的动态值都必须过一道 */
+function e($value): string
+{
+    return htmlspecialchars((string)$value, ENT_QUOTES, 'UTF-8');
+}
+
+/** 静态资源地址，带版本号（mtime + size）——没版本号的话浏览器会一直用旧缓存 */
+function asset(string $rel): string
+{
+    $p = dirname(__DIR__) . $rel;
+    if (!is_file($p)) {
+        return $rel;
+    }
+    return $rel . '?v=' . substr(md5(filemtime($p) . filesize($p)), 0, 8);
+}
+
+/** 站内链接（统一走 query-string 路由，不依赖 Apache 重写） */
+function url(string $route = 'home', array $query = []): string
+{
+    $q = array_merge(['r' => $route], $query);
+    return 'index.php?' . http_build_query($q);
+}
+
+function redirect(string $route = 'home', array $query = []): void
+{
+    header('Location: ' . url($route, $query));
+    exit;
+}
+
+function is_post(): bool
+{
+    return ($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST';
+}
+
+function fb_config(string $key = null, $default = null)
+{
+    $c = $GLOBALS['config'];
+    if ($key === null) {
+        return $c;
+    }
+    return array_key_exists($key, $c) ? $c[$key] : $default;
+}
+
+// ---------------- CSRF ----------------
+function csrf_token(): string
+{
+    if (empty($_SESSION['_csrf'])) {
+        $_SESSION['_csrf'] = bin2hex(random_bytes(16));
+    }
+    return $_SESSION['_csrf'];
+}
+
+function csrf_field(): string
+{
+    return '<input type="hidden" name="_csrf" value="' . e(csrf_token()) . '">';
+}
+
+/**
+ * 校验 CSRF。失败直接结束请求 —— 不做这种假返回：
+ * 「返回 false 让调用层自己处理」的写法，迟早有人忘了判断。
+ */
+function csrf_check(): void
+{
+    $ok = isset($_POST['_csrf'], $_SESSION['_csrf'])
+        && hash_equals($_SESSION['_csrf'], (string)$_POST['_csrf']);
+    if (!$ok) {
+        http_response_code(419);
+        echo '页面已过期，请刷新后重试（CSRF 校验失败）';
+        exit;
+    }
+}
+
+// ---------------- 一次性提示 ----------------
+function flash(string $type, string $message): void
+{
+    $_SESSION['_flash'][] = ['type' => $type, 'message' => $message];
+}
+
+function take_flash(): array
+{
+    $f = $_SESSION['_flash'] ?? [];
+    unset($_SESSION['_flash']);
+    return $f;
+}
+
+/** 表单回填（校验失败时保留用户输入） */
+function old(string $key, $default = '')
+{
+    return $_SESSION['_old'][$key] ?? $default;
+}
+
+function set_old(array $data): void
+{
+    $_SESSION['_old'] = $data;
+}
+
+function clear_old(): void
+{
+    unset($_SESSION['_old']);
+}
+
+/** 生日相关：返回年龄与距下次生日天数 */
+function age_from(string $birthday): ?int
+{
+    if ($birthday === '' || $birthday === null) {
+        return null;
+    }
+    try {
+        $b = new DateTimeImmutable($birthday);
+    } catch (Exception $ex) {
+        return null;
+    }
+    return (int)$b->diff(new DateTimeImmutable('today'))->y;
+}
+
+function days_until_birthday(string $birthday): ?int
+{
+    if (!$birthday) {
+        return null;
+    }
+    try {
+        $b   = new DateTimeImmutable($birthday);
+        $now = new DateTimeImmutable('today');
+        $next = new DateTimeImmutable($now->format('Y') . '-' . $b->format('m-d'));
+        if ($next < $now) {
+            $next = $next->modify('+1 year');
+        }
+        return (int)$now->diff($next)->days;
+    } catch (Exception $ex) {
+        return null;
+    }
+}