FamilyBook/upload_stage.php

<?php
/**
 * 暂存上传（v24 第 20 批 用户第 4 条）。
 *
 * 用户原话：「所有上传图片视频和附件的模块，都允许多次拖动添加文件上传，
 *            拖动一个进去，就开始上传，还可以继续拖动，继续上传，
 *            最后统一保存即可。」
 *
 * ────────────────────────────────────────────────────────────────
 * 为什么需要"暂存"这一步（而不是直接往目标上挂）：
 *   用户要的是「**拖一个就立刻上传**，最后统一保存」。等最后一个"保存"才落库，
 *   就要求"拖进来的文件先别落库、但又要能显示缩略图" —— 那就得有个
 *   **暂存区**。所以：
 *     ① 拖进来的文件立刻 POST 到 upload_stage.php → 服务端落进**暂存目录**
 *        （`uploads/_staging/<随机>/<文件名>`），回一个 `stoken`（随机令牌）与
 *        预览地址；
 *     ② 前端把 stoken 塞进隐藏字段 `stage[]`，并立刻画一张缩略图（看得见）；
 *     ③ 用户点"保存"时，业务路由读 `stage[]`，把它**认领**到目标条目上
 *        （App\StagedUpload::claim —— 移文件 + 建附件行），暂存目录随之清空。
 *   ⚠️ 这样"立刻上传"与"最后统一保存"两件事都成立：上传是真的（文件已到服务器），
 *      但**不会被挂到任何条目上**，直到用户按下保存。
 *
 * ⚠️ 安全边界（这个端点**不要求**登录之外的任何业务权限）：
 *   · 必须登录（Auth::requireLogin）；
 *   · 必须带 CSRF（与其他写接口同一套）；
 *   · 图片走 Upload::image 的既定槽位规则（比例/尺寸/内存守卫都在那儿）；
 *   · 非图片（PDF/Word/视频原件…）只做 MIME 嗅探与扩展名整理，不动内容；
 *   · 令牌是 24 字节随机串，且**只在本账号的暂存目录里**找 —— 拿到别人的令牌
 *     也认领不了（claim 时会比对 owner）。
 *   · 暂存目录由 App\StagedUpload::sweep() 定期清（超过 TTL 的丢掉），
 *     避免"拖了没保存"的文件永远堆着。
 *
 * 请求：POST multipart，字段 `file`（一个文件）+ `slot`（可选，图片槽位键）
 * 返回：JSON {ok:true, stoken, name, is_image, kind, size, url, size_word}
 *        或 {ok:false, error:"..."}
 */

declare(strict_types=1);

// ⚠️ 这个文件有**两种进入方式**，所以 bootstrap 要按需加载：
//   ① 直接访问 `upload_stage.php`（老式入口）；
//   ② 经 `?r=upload/stage` 转发（index.php 里 `require` 进来）——
//      那时 bootstrap **已经加载过**，再 require 一次会重复 `define()` 常量 → Warning
//      （而 Warning 会被打成 HTML 混进 JSON 里 → 前端 JSON.parse 直接炸，实测踩到）。
//    判据就是 bootstrap 一定会先定义的那个常量。
if (!defined('FB_APP')) {
    require __DIR__ . '/app/bootstrap.php';
}

use App\Auth;
use App\StagedUpload;

header('Content-Type: application/json; charset=utf-8');
// ⚠️ 这个接口只回 JSON，任何 PHP 警告/错误如果被 display_errors 打成 HTML，
//    前端 JSON.parse 会直接炸（"接口返回的不是 JSON"那一课）。
//    所以这里显式把错误转成异常、且不要往输出里打。
ini_set('display_errors', '0');

/**
 * 回一个 JSON 并结束。
 * ⚠️ 前端**只看 ok 字段**，错误一律给"人话"，不吐堆栈（避免泄漏路径）。
 */
function stage_json(array $d): void
{
    echo json_encode($d, JSON_UNESCAPED_UNICODE | JSON_HEX_TAG | JSON_HEX_AMP);
    exit;
}

// ---- 1. 登录 + CSRF ----
if (!Auth::check()) {
    http_response_code(401);
    stage_json(['ok' => false, 'error' => '登录已过期，刷新页面再试。']);
}
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
    http_response_code(405);
    stage_json(['ok' => false, 'error' => '只接受 POST。']);
}
// csrf_check() 失败会直接结束请求并打 HTML —— 这里自己校验，保证回的是 JSON
$tok = (string)($_POST['_csrf'] ?? '');
if ($tok === '' || !hash_equals((string)csrf_token(), $tok)) {
    http_response_code(419);
    stage_json(['ok' => false, 'error' => '会话已过期，刷新页面再试。']);
}

// ---- 2. 收文件 ----
$file = $_FILES['file'] ?? null;
if (!is_array($file) || !array_key_exists('error', $file)) {
    stage_json(['ok' => false, 'error' => '没有收到文件。']);
}
// 上传本身失败时 PHP 给的错误码要翻成人话（"什么都没发生"最难排查）
$err = (int)$file['error'];
if ($err !== UPLOAD_ERR_OK) {
    $map = [
        UPLOAD_ERR_INI_SIZE   => '文件超过了服务器允许的大小（upload_max_filesize）。',
        UPLOAD_ERR_FORM_SIZE  => '文件超过了表单允许的大小。',
        UPLOAD_ERR_PARTIAL    => '文件只传了一半，请重试。',
        UPLOAD_ERR_NO_FILE    => '没有选择文件。',
        UPLOAD_ERR_NO_TMP_DIR => '服务器没有临时目录。',
        UPLOAD_ERR_CANT_WRITE => '服务器写不了磁盘。',
        UPLOAD_ERR_EXTENSION  => '上传被某个扩展拦下了。',
    ];
    stage_json(['ok' => false, 'error' => $map[$err] ?? ('上传失败（错误码 ' . $err . '）。')]);
}

$familyId = (int)Auth::familyId();
$personId = (int)Auth::personId();
$slot     = trim((string)($_POST['slot'] ?? ''));

$res = StagedUpload::stage($familyId, $personId, $file, $slot);
if (empty($res['ok'])) {
    stage_json(['ok' => false, 'error' => (string)($res['error'] ?? '没存上')]);
}
stage_json([
    'ok'        => true,
    'stoken'    => (string)$res['stoken'],
    'name'      => (string)$res['name'],
    'is_image'  => !empty($res['is_image']),
    'kind'      => (string)$res['kind'],
    'size'      => (int)$res['size'],
    'size_word' => (string)$res['size_word'],
    'url'       => (string)$res['url'],
]);