modelstage 0.0.0-stage → 0.5.24

package/src/server/http/background-solids.mjs

@@ -0,0 +1,270 @@
+// http/background-solids.mjs —— 纯色背景预设的数据层（读/写/校验/自愈）
+//
+// 为什么校验放这里而不是路由层：
+//   ① 前端会**原样显示**这些错误文案 ⇒ 文案与规则必须在同一处定义，不能两套；
+//   ② 校验放数据层后，11 条测试可以全部直接打数据层，**不用起 HTTP、不抢端口**；
+//   ③ 路由层保持"读 body → 转发 → 回包"的薄形态（与 http/backgrounds.mjs 的既有做法一致）。
+//
+// 落盘：`data/backgrounds/solids.json`（运行时数据；.gitignore 已忽略 /data/backgrounds/）。
+//   原子写 + fsync + 串行队列全部来自 http/atomic-json.mjs。
+//
+// 并发约定：**单实例内串行一致；多实例共享同一 dataDir 不保证**（无文件锁）。
+//   见 docs/契约/数据与接口.md §四。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createLogger } from '../core/log.mjs';
+import { backupFile, createSerialQueue, ensureDir, writeJsonAtomic } from './atomic-json.mjs';
+
+const log = createLogger('solid-bg');
+
+/** 数据文件名（在 data/backgrounds/ 下） */
+const FILE_NAME = 'solids.json';
+
+/** reset 前的存档前缀 */
+const BAK_PREFIX = `solids.bak-`;
+
+/** 损坏文件留证前缀 */
+const CORRUPT_PREFIX = `solids.corrupt-`;
+
+/** 备份保留份数（bak 与 corrupt 各自轮转，互不挤占） */
+const KEEP_BACKUPS = 5;
+
+/** 数量上限：防止被脚本刷爆数据文件 */
+const MAX_ITEMS = 50;
+
+/** 名称长度上限（按字符数算，中文一个字算一个） */
+const MAX_NAME_LEN = 30;
+
+/** 颜色格式：只接受 6 位十六进制；3 位缩写不接受（避免前端要处理两种形态） */
+const COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+
+/**
+ * 默认 5 个（原色板；绿幕/蓝幕是常用项）。
+ * id 用**确定性 slug**：reset 是幂等操作，产出变化的 id 反直觉；确定性 id 也让测试能直接断言。
+ */
+export const DEFAULT_SOLIDS = [
+  { id: 'solid-default-carbon', name: '炭黑', color: '#1a1a1c' },
+  { id: 'solid-default-warm-dark', name: '暖暗', color: '#2a2520' },
+  { id: 'solid-default-bone-white', name: '骨白', color: '#d6d0c4' },
+  { id: 'solid-default-green-screen', name: '绿幕', color: '#3d8f5c' },
+  { id: 'solid-default-blue-screen', name: '蓝幕', color: '#2f6aa3' },
+];
+
+/** 错误文案（前端原样展示，不要写成 "invalid color" 这种给程序看的话） */
+export const MESSAGES = {
+  badColor: '颜色格式不对，应为 #RRGGBB 形式（如 #3d8f5c）',
+  emptyName: '名称不能为空',
+  longName: (n) => `名称太长（最多 ${MAX_NAME_LEN} 个字，当前 ${n} 个）`,
+  dupName: (n) => `已经有同名颜色了（"${n}"），换个名字`,
+  tooMany: `颜色数量已达上限（最多 ${MAX_ITEMS} 个），先删几个再加`,
+  notFound: (id) => `找不到这个颜色（id=${id}），可能已被删除`,
+  ioFail: '读取颜色数据失败，本次操作已取消（不会覆盖你的数据）',
+};
+
+/** 生成一个新 id（时间 + 随机后缀，够用且无依赖） */
+function newId() {
+  const t = Date.now().toString(36);
+  const r = Math.random().toString(36).slice(2, 8);
+  return `solid-${t}-${r}`;
+}
+
+/** 归一化颜色：统一小写输出 */
+function normColor(c) {
+  return String(c || '').trim().toLowerCase();
+}
+
+/** 归一化名称：去首尾空格（中文里 "炭黑" 与 "炭黑 " 才算重复） */
+function normName(n) {
+  return String(n == null ? '' : n).trim();
+}
+
+/** 校验颜色（返回 null 表示通过，否则返回错误文案） */
+export function checkColor(color) {
+  return COLOR_RE.test(String(color || '')) ? null : MESSAGES.badColor;
+}
+
+/** 校验名称（返回 null 表示通过，否则返回错误文案） */
+export function checkName(name) {
+  const n = normName(name);
+  if (!n) return MESSAGES.emptyName;
+  if ([...n].length > MAX_NAME_LEN) return MESSAGES.longName([...n].length);
+  return null;
+}
+
+/** 名称是否已被占用（大小写敏感；excludeId 用于改名时排除自身） */
+function nameTaken(items, name, excludeId) {
+  return items.some((it) => it.id !== excludeId && it.name === name);
+}
+
+/** 单条记录的合法形态（缺字段/形态不对 ⇒ 丢弃该条） */
+function sanitizeItem(it) {
+  if (!it || typeof it !== 'object') return null;
+  if (typeof it.id !== 'string' || !it.id) return null;
+  if (typeof it.name !== 'string' || !normName(it.name)) return null;
+  if (typeof it.color !== 'string' || !COLOR_RE.test(it.color)) return null;
+  return {
+    id: it.id,
+    name: normName(it.name),
+    color: normColor(it.color),
+    createdAt: Number.isFinite(Number(it.createdAt)) ? Number(it.createdAt) : Date.now(),
+  };
+}
+
+/** 造一份默认列表（每次初始化/reset 都重新盖 createdAt） */
+function makeDefaults(at = Date.now()) {
+  return DEFAULT_SOLIDS.map((d) => ({ id: d.id, name: d.name, color: d.color, createdAt: at }));
+}
+
+/** 组装内部上下文（目录、文件、串行队列） */
+function makeCtx(paths) {
+  const dir = path.join(paths.dataDir, 'backgrounds');
+  return { dir, file: path.join(dir, FILE_NAME), enqueue: createSerialQueue() };
+}
+
+/** reset 存档：把当前文件复制成 solids.bak-<ts>.json（文件不存在返回 null） */
+function backupCurrent(ctx, at) {
+  if (!fs.existsSync(ctx.file)) return null;
+  return backupFile(ctx.file, ctx.dir, BAK_PREFIX, at, KEEP_BACKUPS);
+}
+
+/** 原子写盘（tmp → fsync → rename） */
+function saveItems(ctx, items) {
+  ensureDir(ctx.dir);
+  writeJsonAtomic(ctx.file, { version: 1, items });
+}
+
+/**
+ * 读磁盘并返回条目。**"读失败"与"没有数据"必须分开**（契约 §7.1.1 写入凭证）：
+ *   ENOENT ⇒ 首次初始化写默认；其它 IO 错误 ⇒ 返回 error，调用方绝不能拿默认值覆盖；
+ *   内容坏了 ⇒ 先留证再重建。
+ * @returns {{items:object[]}|{error:{status:number, body:object}}}
+ */
+function loadItems(ctx) {
+  let raw = null;
+  try {
+    raw = fs.readFileSync(ctx.file, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      const items = makeDefaults();
+      saveItems(ctx, items);
+      log.info('初始化默认纯色预设', { file: ctx.file, count: items.length });
+      return { items };
+    }
+    log.error('读取纯色预设失败（不覆盖原数据）', { file: ctx.file, code: e && e.code, error: String((e && e.message) || e) });
+    return { error: { status: 500, body: { error: MESSAGES.ioFail } } };
+  }
+
+  let parsed = null;
+  try { parsed = JSON.parse(raw); } catch { parsed = null; }
+  const arr = Array.isArray(parsed) ? parsed : (parsed && Array.isArray(parsed.items) ? parsed.items : null);
+  if (!arr) {
+    const bak = backupFile(ctx.file, ctx.dir, CORRUPT_PREFIX, Date.now(), KEEP_BACKUPS);
+    const items = makeDefaults();
+    saveItems(ctx, items);
+    log.warn('纯色预设内容损坏，已备份并重建默认', { file: ctx.file, backup: bak, bytes: raw.length });
+    return { items };
+  }
+  return { items: pickValid(arr, ctx.file) };
+}
+
+/** 过滤非法条目（只丢该条，其余保留） */
+function pickValid(arr, file) {
+  const items = [];
+  let dropped = 0;
+  for (const it of arr) {
+    const ok = sanitizeItem(it);
+    if (ok) items.push(ok);
+    else dropped += 1;
+  }
+  if (dropped) log.warn('纯色预设里有非法条目，已丢弃', { file, dropped, kept: items.length });
+  return items;
+}
+
+/** 串行队列内的"读 → 改 → 写"；fn 返回 {items, extra} 或 {error} */
+function mutate(ctx, fn) {
+  return ctx.enqueue(() => {
+    const loaded = loadItems(ctx);
+    if (loaded.error) return loaded.error;
+    const out = fn(loaded.items);
+    if (out.error) return out.error;
+    saveItems(ctx, out.items);
+    return { items: out.items, extra: out.extra };
+  });
+}
+
+/** GET 列表 */
+function apiList(ctx) {
+  const loaded = loadItems(ctx);
+  if (loaded.error) return loaded.error;
+  return { status: 200, body: { items: loaded.items } };
+}
+
+/** 新增：校验 → 查重 → 追加 */
+function apiAdd(ctx, input) {
+  return mutate(ctx, (items) => {
+    const name = normName(input.name);
+    const nameErr = checkName(name);
+    if (nameErr) return { error: { status: 400, body: { error: nameErr } } };
+    const colorErr = checkColor(input.color);
+    if (colorErr) return { error: { status: 400, body: { error: colorErr } } };
+    if (items.length >= MAX_ITEMS) return { error: { status: 400, body: { error: MESSAGES.tooMany } } };
+    if (nameTaken(items, name, null)) return { error: { status: 400, body: { error: MESSAGES.dupName(name) } } };
+    const item = { id: newId(), name, color: normColor(input.color), createdAt: Date.now() };
+    return { items: [...items, item], extra: { item } };
+  }).then((r) => (r.items ? { status: 200, body: { item: r.extra.item } } : r));
+}
+
+/** 改名：id/color/createdAt 不变；同名查重（排除自身） */
+function apiRename(ctx, input) {
+  return mutate(ctx, (items) => {
+    const id = String(input.id || '');
+    const idx = items.findIndex((it) => it.id === id);
+    if (idx < 0) return { error: { status: 404, body: { error: MESSAGES.notFound(id) } } };
+    const name = normName(input.name);
+    const nameErr = checkName(name);
+    if (nameErr) return { error: { status: 400, body: { error: nameErr } } };
+    if (nameTaken(items, name, id)) return { error: { status: 400, body: { error: MESSAGES.dupName(name) } } };
+    const next = items.slice();
+    next[idx] = { ...next[idx], name };
+    return { items: next, extra: { item: next[idx] } };
+  }).then((r) => (r.items ? { status: 200, body: { item: r.extra.item } } : r));
+}
+
+/** 删除 */
+function apiRemove(ctx, input) {
+  return mutate(ctx, (items) => {
+    const id = String(input.id || '');
+    if (!items.some((it) => it.id === id)) return { error: { status: 404, body: { error: MESSAGES.notFound(id) } } };
+    return { items: items.filter((it) => it.id !== id), extra: { id } };
+  }).then((r) => (r.items ? { status: 200, body: { removed: true, id: r.extra.id } } : r));
+}
+
+/** 重置：先备份当前，再重建默认 5 个 */
+function apiReset(ctx) {
+  return ctx.enqueue(() => {
+    const at = Date.now();
+    const bak = backupCurrent(ctx, at);   // 备份失败不阻断重置（最多丢一次历史，不丢当前数据）
+    const items = makeDefaults(at);
+    saveItems(ctx, items);
+    log.info('纯色预设已重置为默认', { file: ctx.file, backup: bak, count: items.length });
+    return { status: 200, body: { items } };
+  });
+}
+
+/**
+ * 建立纯色预设存储句柄（路由层只跟这个对象打交道）。
+ * @param {{dataDir:string}} paths core/paths.mjs 产出的路径集合
+ */
+export function createBackgroundSolids(paths) {
+  const ctx = makeCtx(paths);
+  return {
+    dir: ctx.dir,
+    file: ctx.file,
+    list: () => apiList(ctx),
+    add: (input = {}) => apiAdd(ctx, input),
+    rename: (input = {}) => apiRename(ctx, input),
+    remove: (input = {}) => apiRemove(ctx, input),
+    reset: () => apiReset(ctx),
+  };
+}

package/src/server/http/backgrounds.mjs

@@ -0,0 +1,388 @@
+// http/backgrounds.mjs —— 舞台「自定义背景图」的存储与五个接口
+//
+// 为什么要服务端存：背景图要跟"换机/备份"一起走、要在刷新后仍在、要能被重命名与删除。
+//   只写 localStorage 的 dataURL 是假上传（换浏览器就没了、无法列表管理、单张 4MB 写爆存储），
+//   所以这里落盘到 data/backgrounds/（运行时数据目录，与 data/export/ 同类，不入库）。
+//
+// 五个接口（路由在 serve.mjs 里挂，这里只做数据与校验）：
+//   GET  /api/backgrounds              列表
+//   POST /api/backgrounds              上传（原始二进制 + x-filename 头）
+//   POST /api/backgrounds/rename       重命名（只改显示名，id/file 不变）
+//   POST /api/backgrounds/delete       删除（文件进 .trash/，索引同步移除）
+//   GET  /api/backgrounds/file/<id>    出图（id 只查索引，绝不拼路径）
+//
+// 三条硬约束（本机无 GPU、内存小，且 URL 里的 id 是用户可控输入）：
+//   1. 上传边读边计数，超限立刻中断——不允许"先全读进内存再判断"
+//   2. 出图只认索引里的 id，索引没有就 404；文件路径永远由索引里的 file 字段拼出并校验前缀
+//   3. index.json 走 .tmp + rename 原子写，且用串行队列避免并发写互相覆盖
+
+import fs from 'node:fs';
+import { createSerialQueue, writeFileAtomic, writeJsonAtomic } from './atomic-json.mjs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/** 单张背景图上限：5MB（够一张 4K 静图；再大让用户自己压，避免软渲染下贴图上传/解码过慢） */
+export const MAX_BG_BYTES = 5 * 1024 * 1024;
+
+/** 允许的图片类型 → 落盘扩展名。刻意不收 gif：动画背景会持续重绘，与"暂停不空转"目标冲突 */
+const ALLOWED_TYPES = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' };
+
+/** 显示名上限（超出截断，不报错——用户改个名不该被卡住） */
+const MAX_NAME_LEN = 60;
+
+/** 索引文件名与回收目录名 */
+const INDEX_FILE = 'index.json';
+const TRASH_DIR = '.trash';
+
+// ------------------------------------------------------------------ 纯工具
+
+/**
+ * 净化显示名：去掉控制字符与首尾空白，压缩连续空白，截断到上限。
+ * 只影响"展示"，永远不参与文件路径（落盘名由服务端生成）。
+ * @param {unknown} raw 原始输入
+ * @returns {string} 净化后的名字（可能为空串，由调用方兜底）
+ */
+function sanitizeName(raw) {
+  const s = String(raw == null ? '' : raw)
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return s.length > MAX_NAME_LEN ? s.slice(0, MAX_NAME_LEN) : s;
+}
+
+/**
+ * 还原请求头里的非 ASCII 文本（中文文件名）。
+ *
+ * 为什么需要两步：HTTP 头按规范是 latin-1，浏览器若不百分号编码就会把 UTF-8 字节
+ *   直接塞进去，Node 读出来是乱码（"我的背景" → "æçèæ¯"）；
+ *   前端约定用 encodeURIComponent 传，所以先试百分号解码，失败再按 latin-1→utf-8 还原。
+ * @param {unknown} raw 请求头原值
+ * @returns {string} 可读文本
+ */
+function decodeHeaderText(raw) {
+  const s = String(raw == null ? '' : raw);
+  if (!s) return '';
+  if (/%[0-9A-Fa-f]{2}/.test(s)) {
+    try { return decodeURIComponent(s); } catch { /* 落到下面的字节还原 */ }
+  }
+  try {
+    const restored = Buffer.from(s, 'latin1').toString('utf8');
+    // 还原后若出现替换符说明本来就不是 UTF-8 字节（真 latin-1 名字），保持原样
+    return restored.includes('\ufffd') ? s : restored;
+  } catch {
+    return s;
+  }
+}
+
+/**
+ * 从 x-filename 里取一个"基名"当显示名（仅展示用；绝不进落盘路径）。
+ * @param {string|undefined} raw 请求头原值
+ * @returns {string} 去掉扩展名与目录部分的基名
+ */
+function displayNameFromHeader(raw) {
+  const text = decodeHeaderText(raw);
+  const base = text.replace(/\\/g, '/').split('/').pop() || '';
+  return sanitizeName(base.replace(/\.[A-Za-z0-9]{1,8}$/, ''));
+}
+
+/**
+ * 按文件头判定真实图片类型（不信任 Content-Type 与扩展名）。
+ * @param {Buffer} buf 文件开头若干字节
+ * @returns {string|null} 命中的 MIME，未识别返回 null
+ */
+function sniffImageType(buf) {
+  if (!buf || buf.length < 12) return null;
+  // PNG: 89 50 4E 47 0D 0A 1A 0A
+  if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return 'image/png';
+  // JPEG: FF D8 FF
+  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg';
+  // WebP: "RIFF" .... "WEBP"
+  if (buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WEBP') return 'image/webp';
+  return null;
+}
+
+/**
+ * 统一失败响应（前端按 reason 给不同提示，不用笼统"上传失败"）。
+ * @param {string} reason 机器可读原因
+ * @param {string} message 人类可读说明
+ * @param {number} [status] HTTP 状态码
+ */
+function fail(reason, message, status = 400) {
+  return { ok: false, status, body: { ok: false, reason, error: message } };
+}
+
+// ------------------------------------------------------------------ 索引读写
+
+/**
+ * 索引存储：原子写 + 串行队列。
+ * @param {{dir: string, indexFile: string, trashDir: string}} ctx 存储上下文
+ */
+function createIndexStore(ctx) {
+  /** 串行队列：索引读写不并发，避免两次上传把 index.json 互相覆盖（与全仓同一实现） */
+  const enqueue = createSerialQueue();
+
+  /** 确保目录存在（首次使用时创建） */
+  function ensureDirs() {
+    fs.mkdirSync(ctx.dir, { recursive: true });
+    fs.mkdirSync(ctx.trashDir, { recursive: true });
+  }
+
+  /** 读索引（文件不存在/损坏都当空索引，不让坏文件把整个列表打挂） */
+  function read() {
+    try {
+      const obj = JSON.parse(fs.readFileSync(ctx.indexFile, 'utf8'));
+      const items = Array.isArray(obj && obj.items) ? obj.items : [];
+      return items.filter((it) => it && typeof it.id === 'string' && typeof it.file === 'string');
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * 写索引：复用全仓统一的 writeJsonAtomic（写 tmp → **fsync** → rename）。
+   *
+   * 旧实现手写了 tmp+rename 但**漏了 fsync**：rename 只保证"看到旧或新文件"，
+   *   不保证新文件内容已落盘 —— 崩溃窗口里会出现 0 字节的 index.json，
+   *   图片还在但界面里全部消失（纯色预设那条路早就用 writeJsonAtomic 修过，这里是漏网的另一处）。
+   */
+  function write(items) {
+    ensureDirs();
+    writeJsonAtomic(ctx.indexFile, { version: 1, items });
+  }
+
+  return { ensureDirs, read, write, enqueue };
+}
+
+/** 索引项 → 对外视图（带上可直接用于 <img>/background 的 url） */
+function toItemView(it) {
+  return {
+    id: it.id,
+    name: it.name,
+    url: `/api/backgrounds/file/${it.id}`,
+    bytes: Number(it.bytes) || 0,
+    mime: it.mime || '',
+    addedAt: it.addedAt || '',
+  };
+}
+
+/**
+ * 把索引项解析成绝对路径，并校验它确实落在 backgrounds 目录内。
+ * 双保险：file 字段由服务端生成（不含用户输入），这里再做一次前缀校验，
+ *   防止索引文件被外部改坏后变成路径穿越。
+ * @param {{dir: string}} ctx 存储上下文
+ * @param {{file: string}} it 索引项
+ * @returns {string|null} 绝对路径（越界或不存在返回 null）
+ */
+function resolveFile(ctx, it) {
+  const base = path.resolve(ctx.dir);
+  const abs = path.resolve(base, String(it.file || ''));
+  if (abs !== base && !abs.startsWith(`${base}${path.sep}`)) return null;
+  try {
+    if (!fs.statSync(abs).isFile()) return null;
+  } catch {
+    return null;
+  }
+  return abs;
+}
+
+// ------------------------------------------------------------------ 五个动作
+
+/**
+ * 列表：新加的排前面（用户刚上传的最想先看到）。
+ * @param {object} store 索引存储
+ */
+function listItems(store) {
+  const items = store.read().slice().reverse();
+  return { ok: true, limit: MAX_BG_BYTES, types: Object.keys(ALLOWED_TYPES), items: items.map(toItemView) };
+}
+
+/**
+ * 校验并落盘一次上传（此时内容已在内存里，且必定 ≤ 上限）。
+ * @param {{store: object, ctx: object}} env 存储与上下文
+ * @param {Buffer} buf 文件内容
+ * @param {object} headers 请求头
+ */
+function saveUpload(env, buf, headers) {
+  const mime = sniffImageType(buf);
+  if (!mime || !ALLOWED_TYPES[mime]) {
+    const declared = String(headers['content-type'] || '(未声明)');
+    return fail('bad-type', `只接受 png / jpeg / webp 且文件内容要与类型相符（收到：${declared}）`, 415);
+  }
+  const ext = ALLOWED_TYPES[mime];
+  const id = crypto.randomBytes(8).toString('hex');
+  const file = `bg-${Date.now()}-${id}.${ext}`;
+  const abs = path.join(env.ctx.dir, file);
+  try {
+    env.store.ensureDirs();
+    // 与索引同一套原子写（tmp → fsync → rename）：否则崩溃后可能"索引有这条、图片 0 字节"，
+    //   而取文件路径只校验 isFile()（0 字节也算存在）⇒ 不会被剔除，用户长期破图。
+    writeFileAtomic(abs, buf);
+  } catch (e) {
+    return fail('disk-error', `写入磁盘失败：${(e && e.message) || e}`, 500);
+  }
+  return env.store.enqueue(() => {
+    const items = env.store.read();
+    const name = displayNameFromHeader(headers['x-filename']) || `未命名 ${items.length + 1}`;
+    const item = { id, name, file, mime, bytes: buf.length, addedAt: new Date().toISOString() };
+    items.push(item);
+    try {
+      env.store.write(items);
+    } catch (e) {
+      // 索引写失败：把刚落盘的文件清掉，避免产生"看不见的孤儿文件"
+      try { fs.unlinkSync(abs); } catch { /* 忽略 */ }
+      return fail('disk-error', `索引写入失败：${(e && e.message) || e}`, 500);
+    }
+    return { ok: true, status: 201, body: { ok: true, item: toItemView(item) } };
+  });
+}
+
+/**
+ * 边读边计数地上传一张图：超限立即中止。
+ * @param {{store: object, ctx: object}} env 存储与上下文
+ * @param {import('node:http').IncomingMessage} req 原始请求
+ * @returns {Promise<{ok:boolean, status:number, body:object, destroy?:boolean}>} 统一响应
+ */
+function readUpload(env, req) {
+  // ① Content-Length 预检：声明就超限的，连读都不读（一个字节都不占内存）
+  const declared = Number(req.headers['content-length']);
+  if (Number.isFinite(declared) && declared > MAX_BG_BYTES) {
+    const r = fail('too-large',
+      `图片 ${(declared / 1048576).toFixed(2)}MB 超过上限 ${MAX_BG_BYTES / 1048576}MB，请先压缩`, 413);
+    r.destroy = true;
+    req.resume();          // 丢弃后续数据，避免占着连接不放
+    return Promise.resolve(r);
+  }
+  return new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let aborted = false;
+    /**
+     * 中止这次上传并给出原因。
+     * 注意顺序：**先把响应交出去、再由路由层断开**——直接 destroy 会让客户端只看到
+     *   "连接被重置"，拿不到 413 与具体原因（实测 curl 只收到 100 Continue）。
+     */
+    const abortWith = (reason, message, status) => {
+      if (aborted) return;
+      aborted = true;
+      req.resume();   // 继续把剩余字节读出来丢弃：不占内存，也能让连接安静下来
+      const r = fail(reason, message, status);
+      r.destroy = true;
+      resolve(r);
+    };
+    req.on('data', (chunk) => {
+      if (aborted) return;
+      total += chunk.length;
+      // ② 流式累加：没有 Content-Length（chunked）时靠这里兜住上限
+      if (total > MAX_BG_BYTES) {
+        abortWith('too-large', `图片超过上限 ${MAX_BG_BYTES / 1048576}MB，请先压缩`, 413);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('error', () => abortWith('aborted', '上传中断（连接已断开）', 400));
+    req.on('end', () => {
+      if (aborted) return;
+      if (!total) { resolve(fail('empty', '没有收到文件内容', 400)); return; }
+      resolve(saveUpload(env, Buffer.concat(chunks), req.headers));
+    });
+  });
+}
+
+/**
+ * 重命名：只改显示名，id 与 file 保持不变（URL 因此永远稳定）。
+ * 重名不拒绝而是自动加 `(2)`/`(3)` 后缀——用户想保留两份同名图是合理需求，
+ *   但列表里出现两个一模一样的名字会分不清谁是谁。
+ * @param {object} store 索引存储
+ * @param {string} id 目标 id
+ * @param {unknown} rawName 新显示名
+ */
+function renameItem(store, id, rawName) {
+  const name = sanitizeName(rawName);
+  if (!name) return Promise.resolve(fail('bad-name', '名称不能为空'));
+  return store.enqueue(() => {
+    const items = store.read();
+    const hit = items.find((it) => it.id === id);
+    if (!hit) return fail('not-found', `没有这条背景图：${id}`, 404);
+    const taken = new Set(items.filter((it) => it.id !== id).map((it) => it.name));
+    let final = name;
+    let n = 2;
+    while (taken.has(final)) { final = `${name} (${n})`; n += 1; }
+    hit.name = final;
+    try {
+      store.write(items);
+    } catch (e) {
+      return fail('disk-error', `索引写入失败：${(e && e.message) || e}`, 500);
+    }
+    return { ok: true, status: 200, body: { ok: true, item: toItemView(hit), adjusted: final !== name } };
+  });
+}
+
+/**
+ * 删除：文件移进 .trash/（可恢复），索引同步移除（否则列表会出现点不开的幽灵项）。
+ * @param {{store: object, ctx: object}} env 存储与上下文
+ * @param {string} id 目标 id
+ */
+function removeItem(env, id) {
+  return env.store.enqueue(() => {
+    const items = env.store.read();
+    const hit = items.find((it) => it.id === id);
+    if (!hit) return fail('not-found', `没有这条背景图：${id}`, 404);
+    const abs = resolveFile(env.ctx, hit);
+    let trashed = false;
+    if (abs) {
+      try {
+        env.store.ensureDirs();
+        fs.renameSync(abs, path.join(env.ctx.trashDir, `${Date.now()}-${path.basename(abs)}`));
+        trashed = true;
+      } catch {
+        // 移动失败不阻断索引移除：留在盘上的文件比"列表里删不掉"危害小
+        trashed = false;
+      }
+    }
+    const next = items.filter((it) => it.id !== id);
+    try {
+      env.store.write(next);
+    } catch (e) {
+      return fail('disk-error', `索引写入失败：${(e && e.message) || e}`, 500);
+    }
+    return { ok: true, status: 200, body: { ok: true, removed: id, trashed } };
+  });
+}
+
+/**
+ * 取一张图的落盘信息（出图接口用）：**只按索引查 id**，URL 里的字符串永不参与拼路径。
+ * @param {{store: object, ctx: object}} env 存储与上下文
+ * @param {string} id 索引 id
+ * @returns {{abs: string, mime: string, name: string}|null} 命中返回路径与类型
+ */
+function findFile(env, id) {
+  const hit = env.store.read().find((it) => it.id === id);
+  if (!hit) return null;
+  const abs = resolveFile(env.ctx, hit);
+  if (!abs) return null;
+  return { abs, mime: hit.mime || 'application/octet-stream', name: hit.name };
+}
+
+// ------------------------------------------------------------------ 对外句柄
+
+/**
+ * 建立背景图存储句柄（路由层只跟这个对象打交道）。
+ * @param {{dataDir: string}} paths 项目路径集合（core/paths.mjs 产出）
+ */
+export function createBackgrounds(paths) {
+  const ctx = {
+    dir: path.join(paths.dataDir, 'backgrounds'),
+    indexFile: path.join(paths.dataDir, 'backgrounds', INDEX_FILE),
+    trashDir: path.join(paths.dataDir, 'backgrounds', TRASH_DIR),
+  };
+  const env = { ctx, store: createIndexStore(ctx) };
+  return {
+    dir: ctx.dir,
+    list: () => listItems(env.store),
+    uploadStream: (req) => readUpload(env, req),
+    rename: (id, name) => renameItem(env.store, id, name),
+    remove: (id) => removeItem(env, id),
+    fileOf: (id) => findFile(env, id),
+  };
+}