zipcalm 0.0.0-stage → 1.0.1

package/server/core/task/recovery.js

@@ -0,0 +1,116 @@
+// 启动对账（M5-F09 / 数据模型 §六.4、P-08/P-10）
+//
+// 职责：进程启动、任务状态加载后，对「删除链路」留下的中间状态做一次对账扫描：
+//
+// 1. **trash 孤儿批次**（P-08）：rename 进回收站与写 JSONL 日志是两步、非原子——
+//    进程在两步之间死掉会出现「文件已在 trash/ 但日志无该 batchId」。本扫描发现
+//    孤儿批次后补写 `action: 'reconciled-crash'` 日志行，消除不可对账状态。
+//    文件本身是安全的（在回收站里），不移动、不删除、不还原。
+//
+// 2. **deleting 中断恢复**（P-10）：deleting 是执行相位，中途 kill 后任务被 M3 恢复
+//    逻辑标为 interrupted，但 delete.status 可能停在 'deleting'、部分文件已进 trash、
+//    部分还在原位。对账后置 `delete.status='failed'`（契约枚举内，语义=删除未完成），
+//    details 记 batchId 指引与 trash 现状；不做自动续删（半删状态下继续删需要重新过
+//    全部删除前防线，重试才是安全路径——重试会创建新任务重新走完整删除链）。
+//
+// 设计约束：**只读 trash 与 tasks 快照 + 追加日志 + 修改内存任务字段**，绝不移动/删除
+// 任何文件（对账不是清理）；所有结论落日志，人工可复核。
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { toUserPath } from '../fs/safePath.js';
+
+/** 列出 trash 下的批次目录（排除 .cross-device 暂存位等非批次条目） */
+async function listTrashBatches(trashDir) {
+  try {
+    const entries = await fsp.readdir(trashDir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')).map((entry) => entry.name);
+  } catch {
+    return []; // trash 目录不存在 = 无批次
+  }
+}
+
+/** 读取全部删除日志里出现过的 batchId 集合（日志按天分文件，全量扫） */
+async function collectLoggedBatchIds(logDir) {
+  const ids = new Set();
+  let files;
+  try {
+    files = await fsp.readdir(logDir);
+  } catch {
+    return ids;
+  }
+  for (const file of files) {
+    if (!file.startsWith('delete-') || !file.endsWith('.jsonl')) continue;
+    const text = await fsp.readFile(path.join(logDir, file), 'utf8').catch(() => '');
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const entry = JSON.parse(line);
+        if (entry.batchId) ids.add(entry.batchId);
+      } catch {
+        // 单行损坏不阻断整体对账（append-only 日志的常态容忍）
+      }
+    }
+  }
+  return ids;
+}
+
+/**
+ * 对账入口：返回 { orphanBatches: string[], reconciledDeletes: number }。
+ * @param {{trashDir: string, logDir: string, rootAbs: string, logger: object}} deps
+ * @param {Array<{info: {id, status, delete?}}> } tasks 当前任务快照（recoverTasks 落盘前的内存态）
+ */
+export async function reconcileAfterBoot(deps, tasks) {
+  const { trashDir, logDir, rootAbs, logger } = deps;
+  const reconcileReport = { orphanBatches: [], reconciledDeletes: 0 };
+
+  // 1) trash 孤儿批次：有目录、无日志 → 补记
+  const loggedIds = await collectLoggedBatchIds(logDir);
+  for (const batchId of await listTrashBatches(trashDir)) {
+    if (loggedIds.has(batchId)) continue;
+    reconcileReport.orphanBatches.push(batchId);
+    try {
+      // 把批次内的文件清单写进补记日志（人工复核用，只列相对路径不复制内容）
+      const files = [];
+      const walk = async (dirAbs) => {
+        for (const entry of await fsp.readdir(dirAbs, { withFileTypes: true })) {
+          const abs = path.join(dirAbs, entry.name);
+          if (entry.isDirectory()) await walk(abs);
+          else files.push(toUserPath(rootAbs, abs));
+        }
+      };
+      await walk(path.join(trashDir, batchId));
+      const file = path.join(logDir, `delete-${new Date().toISOString().slice(0, 10).replaceAll('-', '')}.jsonl`);
+      await fsp.mkdir(logDir, { recursive: true });
+      await fsp.appendFile(file, `${JSON.stringify({
+        action: 'reconciled-crash',
+        batchId,
+        at: Date.now(),
+        files: files.slice(0, 50),
+        fileCount: files.length,
+        note: '进程在 rename 进回收站与写日志之间中断，启动对账补记（文件安全在回收站）',
+      })}\n`, 'utf8');
+      logger.warn('发现 trash 孤儿批次（日志缺失），已补记 reconciled-crash', { batchId, fileCount: files.length });
+    } catch (error) {
+      logger.error('trash 孤儿批次补记失败（不阻断启动）', { batchId, error: error.message });
+    }
+  }
+
+  // 2) deleting 中断的 delete.status 对账（任务此刻已被标 interrupted）
+  for (const record of tasks) {
+    const { info } = record;
+    if (!info.delete || info.delete.status !== 'deleting') continue;
+    info.delete.status = 'failed';
+    info.delete.error = {
+      code: 'INTERNAL_ERROR',
+      message: '删除阶段被服务重启中断，启动对账后标记为失败；原文件要么已进回收站（可从 trash 恢复）要么仍在原位，重试任务将重新走完整删除链',
+      at: Date.now(),
+      details: { trashBatch: info.delete.batchId || info.delete.trashBatch || null },
+    };
+    reconcileReport.reconciledDeletes += 1;
+    logger.warn('deleting 中断任务已对账为 delete.status=failed', { taskId: info.id, trashBatch: info.delete.batchId || null });
+  }
+
+  return reconcileReport;
+}

package/server/core/task/store.js

@@ -0,0 +1,240 @@
+// 任务落盘（docs/M0/数据模型.md §六 落盘模型）
+//
+// 两个文件、两种写法的分野（这是本模块存在的全部理由）：
+// - `tasks.json`：**非终态 + failed/interrupted** 任务，原子写（写 .tmp → rename）+ **500ms 节流**；
+//   终态 done/aborted 写进历史后从这里移除。
+// - `task-history.jsonl`：每次进终态**追加一行**；内存缓存最近 `limits.taskHistoryMax`（默认 200）条，
+//   文件增长过大时按缓存重写压缩（避免无限增长）。
+//
+// 为什么必须原子写：任务状态是"服务重启后唯一能还原真相的来源"，
+// 原地截断写被中断 → 半个 JSON → 重启后任务全丢（INV-11）。
+//
+// 结构：状态全部放在 `ctx` 里，具体动作都是**模块级小函数**（每个只做一件事），
+// 工厂函数只负责建 ctx 并把动作绑上去（便于单测与审读）。
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { readJson, writeJsonAtomic } from '../../lib/atomic-json.js';
+
+/** 历史条目净化：历史文件可能由旧版本写入（含 absPath 等内部字段），读取/追加时一律剥掉，防止经 API 泄漏 */
+function sanitizeHistoryEntry(entry) {
+  if (!entry || typeof entry !== 'object') return entry;
+  const clean = { ...entry };
+  if (Array.isArray(clean.sources)) {
+    clean.sources = clean.sources.map(({ absPath, userPath, ...rest }) => rest);
+  }
+  if (clean.result && Array.isArray(clean.result.packages)) {
+    clean.result = { ...clean.result, packages: clean.result.packages.map(({ absPath, ...rest }) => rest) };
+  }
+  return clean;
+}
+
+function buildContext(options) {
+  const { dataDir } = options;
+  return {
+    logger: options.logger,
+    historyMax: Number.isInteger(options.historyMax) ? options.historyMax : 200,
+    saveThrottleMs: Number.isInteger(options.saveThrottleMs) ? options.saveThrottleMs : 500,
+    // 契约里的路径是 `storage/tasks.json`；本项目 dataDir 就是 ./storage（见 config/defaults.js）
+    tasksFile: path.join(dataDir, 'tasks.json'),
+    historyFile: path.join(dataDir, 'task-history.jsonl'),
+    /** 最近 historyMax 条历史（旧 → 新，与文件顺序一致） */
+    historyCache: [],
+    saveTimer: null,
+    savePending: null,
+    saveInFlight: null,
+    /** 写入串行链（并发写会互相截断 .tmp，见 saveTasksNow 注释） */
+    writeChain: Promise.resolve(),
+  };
+}
+
+/** 读 tasks.json；坏文件按空处理并告警（原文件保留，人工可查；不拖垮启动） */
+async function loadTasks(ctx) {
+  const { data, ok, reason } = await readJson(ctx.tasksFile, []);
+  if (!ok && reason !== 'not-found') {
+    ctx.logger.warn('tasks.json 不可读，按空列表处理', { reason });
+    return [];
+  }
+  return Array.isArray(data) ? data : [];
+}
+
+/**
+ * 读取历史文件（逐行解析 + 净化；坏行跳过）。
+ *
+ * **关键：启动加载时就收敛文件本身**，不只裁内存。
+ * 为什么必须这样：`appendHistoryEntry` 是"先 appendFile、后 trimHistoryFile"两步，
+ * 进程若在这两步之间被 kill（crash 套件就是用 kill -9 复现的），文件就会停在上限 +1 行；
+ * 而旧实现只在内存里 slice(-max)，文件要等"下一次 append"才顺带收敛 ——
+ * 若启动后一直空闲，文件会**永久停在 201 行**（实测：验收独立跑就抓到了这条）。
+ */
+async function loadHistoryFromFile(ctx) {
+  let rawLines;
+  try {
+    rawLines = (await fs.readFile(ctx.historyFile, 'utf8')).split('\n').filter((line) => line.trim().length > 0);
+  } catch {
+    return []; // 文件不存在/不可读：按空历史启动（不拖垮启动）
+  }
+
+  const entries = rawLines.slice(-ctx.historyMax).map(parseHistoryLine).filter(Boolean);
+
+  if (rawLines.length > ctx.historyMax) {
+    await rewriteHistoryFile(ctx, entries, { was: rawLines.length, trigger: '启动加载' });
+  }
+  return entries;
+}
+
+/** 单行 → 净化后的历史条目；坏行返回 null（调用方过滤掉） */
+function parseHistoryLine(line) {
+  try {
+    return sanitizeHistoryEntry(JSON.parse(line));
+  } catch {
+    return null;
+  }
+}
+
+/** 启动加载：读 tasks.json + 预热历史缓存 */
+async function initStore(ctx) {
+  const tasks = await loadTasks(ctx);
+  ctx.historyCache = await loadHistoryFromFile(ctx);
+  return { tasks, historyCount: ctx.historyCache.length };
+}
+
+/** 单次写入（原子：写 <file>.tmp → rename） */
+async function writeTasksFile(ctx, tasks) {
+  try {
+    await writeJsonAtomic(ctx.tasksFile, tasks);
+  } catch (error) {
+    ctx.logger.error('tasks.json 写盘失败', { error: error.message });
+  }
+}
+
+/**
+ * 立即原子落盘。
+ * **必须串行**：`writeJsonAtomic` 用的是固定的 `<file>.tmp`，两个写并发会互相截断同一个临时文件，
+ * rename 之后 tasks.json 里就会出现"两份 JSON 粘在一起"的残骸（实测踩过：JSON.parse 报
+ * "Unexpected non-whitespace character after JSON"）。串行化后任一时刻只有一个写在跑，
+ * 也与"单进程单写者"（INV-09）的模型一致。
+ */
+async function saveTasksNow(ctx, tasks) {
+  ctx.savePending = null;
+  if (ctx.saveTimer) {
+    clearTimeout(ctx.saveTimer);
+    ctx.saveTimer = null;
+  }
+  const previous = ctx.writeChain || Promise.resolve();
+  const chained = previous.then(() => writeTasksFile(ctx, tasks)).catch(() => {});
+  ctx.writeChain = chained;
+  ctx.saveInFlight = chained;
+  await chained;
+  if (ctx.saveInFlight === chained) ctx.saveInFlight = null;
+}
+
+/**
+ * 节流落盘：进度类高频变更走这里（契约：tasks.json ≤2 次/秒）。
+ * 状态/phase 变化与终态必须用 saveTasksNow() 立即落盘，**不能等节流**（INV-10「创建即落盘」同理）。
+ */
+function scheduleTasksSave(ctx, tasks) {
+  ctx.savePending = tasks;
+  if (ctx.saveTimer) return;
+  ctx.saveTimer = setTimeout(() => {
+    ctx.saveTimer = null;
+    const payload = ctx.savePending;
+    ctx.savePending = null;
+    if (payload) void saveTasksNow(ctx, payload);
+  }, ctx.saveThrottleMs);
+  if (typeof ctx.saveTimer.unref === 'function') ctx.saveTimer.unref();
+}
+
+/** 收尾：等写入链跑完，并把未决的节流内容立刻写出（优雅关闭时调用） */
+async function flushStore(ctx) {
+  if (ctx.writeChain) await ctx.writeChain;
+  if (ctx.savePending) await saveTasksNow(ctx, ctx.savePending);
+}
+
+/**
+ * 用给定条目**原子重写**历史文件（写 .tmp → rename）。
+ * 空数组写成空文件（合法：0 行历史）；失败只告警，不影响运行。
+ * @param {object} ctx store 上下文
+ * @param {Array} entries 要保留的条目（旧 → 新）
+ * @param {{was?: number, trigger?: string}} [meta] 仅用于日志（哪次触发的、原来多少行）
+ */
+async function rewriteHistoryFile(ctx, entries, meta = {}) {
+  try {
+    const tmpPath = `${ctx.historyFile}.tmp`;
+    const body = entries.length > 0 ? `${entries.map((item) => JSON.stringify(item)).join('\n')}\n` : '';
+    await fs.writeFile(tmpPath, body, 'utf8');
+    await fs.rename(tmpPath, ctx.historyFile);
+    ctx.logger.info('task-history.jsonl 已按条数收敛', {
+      kept: entries.length,
+      was: Number.isInteger(meta.was) ? meta.was : null,
+      max: ctx.historyMax,
+      trigger: meta.trigger || '追加后',
+    });
+  } catch (error) {
+    ctx.logger.warn('task-history.jsonl 压缩失败（不影响运行）', { error: error.message });
+  }
+}
+
+/**
+ * 历史文件按条数收敛（契约：`task-history.jsonl` 保留最近 `limits.taskHistoryMax` 条）。
+ * 触发条件只看行数（不再设"文件多大才整理"的门槛，否则行数会长期超过上限 —— 实测踩过）；
+ * 超过就按内存缓存重写一次（200 行 ≈ 400KB，代价可控），原子性由 rewriteHistoryFile 保证。
+ */
+async function trimHistoryFile(ctx) {
+  try {
+    const lines = (await fs.readFile(ctx.historyFile, 'utf8')).split('\n').filter((line) => line.trim().length > 0);
+    if (lines.length <= ctx.historyMax) return;
+    await rewriteHistoryFile(ctx, ctx.historyCache, { was: lines.length, trigger: '追加后' });
+  } catch (error) {
+    ctx.logger.warn('task-history.jsonl 压缩失败（不影响运行）', { error: error.message });
+  }
+}
+
+/** 终态追加一行，并同步内存缓存（超限裁剪） */
+async function appendHistoryEntry(ctx, entry) {
+  const clean = sanitizeHistoryEntry(entry);
+  ctx.historyCache.push(clean);
+  if (ctx.historyCache.length > ctx.historyMax) ctx.historyCache = ctx.historyCache.slice(-ctx.historyMax);
+  try {
+    await fs.mkdir(path.dirname(ctx.historyFile), { recursive: true });
+    await fs.appendFile(ctx.historyFile, `${JSON.stringify(clean)}\n`, 'utf8');
+    await trimHistoryFile(ctx);
+  } catch (error) {
+    ctx.logger.error('task-history.jsonl 写入失败', { error: error.message });
+  }
+}
+
+/** 历史查询（新 → 旧）；内存缓存优先（契约 §六.5） */
+function listHistory(ctx, filter = {}) {
+  const limit = Number.isInteger(filter.limit) ? filter.limit : 50;
+  let items = [...ctx.historyCache].reverse();
+  if (filter.status) items = items.filter((item) => filter.status.includes(item.status));
+  return items.slice(0, limit);
+}
+
+function getHistoryEntry(ctx, id) {
+  for (let index = ctx.historyCache.length - 1; index >= 0; index -= 1) {
+    if (ctx.historyCache[index].id === id) return ctx.historyCache[index];
+  }
+  return null;
+}
+
+/**
+ * @param {{dataDir: string, historyMax?: number, saveThrottleMs?: number, logger: object}} options
+ */
+export function createTaskStore(options) {
+  const ctx = buildContext(options);
+  return {
+    init: () => initStore(ctx),
+    loadTasks: () => loadTasks(ctx),
+    scheduleSave: (tasks) => scheduleTasksSave(ctx, tasks),
+    saveNow: (tasks) => saveTasksNow(ctx, tasks),
+    flush: () => flushStore(ctx),
+    appendHistory: (entry) => appendHistoryEntry(ctx, entry),
+    listHistory: (filter) => listHistory(ctx, filter),
+    getHistoryEntry: (id) => getHistoryEntry(ctx, id),
+    files: { tasksFile: ctx.tasksFile, historyFile: ctx.historyFile },
+    historyMax: ctx.historyMax,
+  };
+}

package/server/http/middleware/auth.js

@@ -0,0 +1,130 @@
+// 认证中间件：Session（Cookie）+ Bearer Token 双通道（docs/M0/API规范.md §二）
+//
+// 行为：
+// - onRequest 阶段"尽力认证"：有凭据就校验，通过则挂 request.auth，不通过则记下失败原因（不在这里抛错，
+//   让公开端点（登录/健康检查）照常工作；受保护端点由 requireAuth 抛错）。
+// - Bearer 优先于 Cookie（契约）。
+// - Session 命中滑动续期阈值时重发 Cookie（对齐"7 天滑动续期"）。
+// - 失败原因区分：完全没带 → AUTH_REQUIRED；带了但无效/过期 → AUTH_INVALID / AUTH_EXPIRED。
+
+import { ERROR_CODES, apiError } from '../../lib/errors.js';
+
+/** 从 Authorization 头里取 Bearer token */
+function readBearer(request) {
+  const header = request.headers.authorization;
+  if (typeof header !== 'string') return null;
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : null;
+}
+
+export function registerAuth(app, { store, config }) {
+  app.decorateRequest('auth', null);
+  app.decorateRequest('authFailure', null);
+  app.decorateRequest('sessionId', null);
+  app.decorateRequest('sessionRenewed', null);
+  /** 是否需要在响应里补发会话 Cookie（见 onRequest 里 Bearer 分支的说明） */
+  app.decorateRequest('needsSessionMint', false);
+
+  app.addHook('onRequest', async (request) => {
+    const bearer = readBearer(request);
+    if (bearer) {
+      applyBearerAuth(request, store, config, bearer); // ① Bearer 优先
+      return;
+    }
+    applySessionCookie(request, store, config); // ② Cookie 兜底
+  });
+
+  /**
+   * 受保护路由的 preHandler。
+   * 注意：Session 续期需要"写 Cookie"，所以放在这里（只有真正访问受保护端点时才续期）。
+   */
+  app.decorate('requireAuth', async function requireAuth(request, reply) {
+    assertAuthenticated(request);
+    renewSessionCookie(request, reply, config, store);
+  });
+
+  // ===== Cookie 助手（统一 HttpOnly / SameSite=Lax，契约 §二）=====
+
+  app.decorate('setSessionCookie', (reply, sid, ttlMs) => setSessionCookie(reply, config, sid, ttlMs));
+  app.decorate('clearSessionCookie', (reply) => reply.clearCookie(config.cookieName, { path: '/' }));
+}
+
+/** 取会话 Cookie 的值（没装 cookie 插件或没带该 Cookie 时返回 null） */
+function readSessionCookie(request, config) {
+  return request.cookies ? request.cookies[config.cookieName] : null;
+}
+
+/**
+ * ① Bearer 分支（优先）。
+ * Bearer 通过时仍看一眼 Cookie：能验证就复用（并给滑动续期机会）；
+ * 带了却验证不过（典型：服务重启后内存 session 失效）→ 标记补发新会话 Cookie。
+ * 为什么必须补：EventSource 无法携带 Authorization 头，浏览器里 SSE 只能靠 Cookie ——
+ * 不补的话重启后 SSE 会一直 401，而其余 axios 请求因为有 Bearer 照常工作（表象极具迷惑性）。
+ */
+function applyBearerAuth(request, store, config, bearer) {
+  const record = store.verifyToken(bearer);
+  if (!record) {
+    request.authFailure = ERROR_CODES.AUTH_INVALID;
+    return;
+  }
+  request.auth = { type: 'bearer', user: record.user, expiresAt: record.expiresAt };
+
+  const cookieValue = readSessionCookie(request, config);
+  if (!cookieValue) return;
+  const session = store.verifySession(cookieValue);
+  if (session) {
+    request.sessionId = cookieValue;
+    request.sessionRenewed = session.renewed;
+    return;
+  }
+  request.needsSessionMint = true;
+}
+
+/** ② Cookie 兜底：验证不过时区分"已过期"与"未带凭据"（前端据此决定是提示重登还是跳登录页） */
+function applySessionCookie(request, store, config) {
+  const cookieValue = readSessionCookie(request, config);
+  if (!cookieValue) {
+    request.authFailure = ERROR_CODES.AUTH_REQUIRED;
+    return;
+  }
+  const session = store.verifySession(cookieValue);
+  if (!session) {
+    request.authFailure = ERROR_CODES.AUTH_EXPIRED;
+    return;
+  }
+  request.auth = { type: 'session', user: session.user, expiresAt: session.expiresAt };
+  request.sessionId = cookieValue;
+  request.sessionRenewed = session.renewed;
+}
+
+/** 未认证就抛契约错误（早返回：把后续的续期/补发逻辑从 if 里解放出来） */
+function assertAuthenticated(request) {
+  if (request.auth) return;
+  const code = request.authFailure || ERROR_CODES.AUTH_REQUIRED;
+  throw apiError(code, code === ERROR_CODES.AUTH_REQUIRED ? '需要登录后才能访问' : '登录凭据无效或已过期');
+}
+
+/** 需要续期/补发时才写 Cookie（Session 续期与 Bearer 补发共用同一个出口） */
+function renewSessionCookie(request, reply, config, store) {
+  if (request.auth.type === 'session' && request.sessionRenewed && request.sessionId) {
+    setSessionCookie(reply, config, request.sessionId, store.sessionTtlMs);
+    return;
+  }
+  // Bearer 通过但客户端带着失效的会话 Cookie → 补发一次（只补一次：新 Cookie 下次即可验证通过）
+  if (request.auth.type === 'bearer' && request.needsSessionMint) {
+    const session = store.createSession(request.auth.user);
+    setSessionCookie(reply, config, session.sid, store.sessionTtlMs);
+  }
+}
+
+/** 写会话 Cookie（统一属性；放模块级，避免在注册函数里再嵌一层函数） */
+function setSessionCookie(reply, cfg, sid, ttlMs) {
+  reply.setCookie(cfg.cookieName, sid, {
+    path: '/',
+    httpOnly: true,
+    sameSite: 'lax',
+    // 生产环境走 HTTPS 时应置 true；本机/局域网 HTTP 场景保持 false，否则浏览器不回传
+    secure: false,
+    maxAge: Math.floor(ttlMs / 1000),
+  });
+}

package/server/http/middleware/error.js

@@ -0,0 +1,54 @@
+// 统一错误处理 + 统一响应信封（docs/M0/API规范.md §一 / §八）
+//
+// 三条硬规则：
+// 1. 所有响应都是 { ok, data, error }（成功 error=null，失败 data=null）；
+// 2. 错误码一律来自 shared/error-codes.js，HTTP 状态由契约元信息决定（不自造映射）；
+// 3. 5xx 记 error 级日志并带 traceId，4xx 记 warn 级（便于排查又不吵）。
+
+import crypto from 'node:crypto';
+
+import { ERROR_CODES, errorPayload, httpStatusOfError, toApiError } from '../../lib/errors.js';
+
+export function registerErrorHandling(app, { logger }) {
+  // 成功响应助手：reply.ok(data) —— 业务代码永远不手写 { ok:true, ... }
+  app.decorateReply('ok', function sendOk(data, statusCode = 200) {
+    this.code(statusCode).send({ ok: true, data: data === undefined ? null : data, error: null });
+  });
+
+  // 404（路由不存在）也必须是契约信封
+  app.setNotFoundHandler((request, reply) => {
+    reply.code(404).send({
+      ok: false,
+      data: null,
+      error: {
+        code: ERROR_CODES.PATH_NOT_FOUND,
+        message: `接口不存在：${request.method} ${request.url.split('?')[0]}`,
+      },
+    });
+  });
+
+  app.setErrorHandler((error, request, reply) => {
+    const apiError = toApiError(error);
+    const statusCode = httpStatusOfError(apiError);
+    const traceId = request.id || crypto.randomUUID();
+
+    const logContext = {
+      traceId,
+      method: request.method,
+      url: request.url.split('?')[0],
+      statusCode,
+      code: apiError.code,
+    };
+    if (statusCode >= 500) {
+      logger.error('request failed', { ...logContext, error: apiError.message, stack: apiError.cause ? String(apiError.cause.stack || '').split('\n').slice(0, 3).join(' | ') : undefined });
+    } else {
+      logger.warn('request rejected', { ...logContext, error: apiError.message });
+    }
+
+    const payload = errorPayload(apiError);
+    // 5xx 附带 traceId，方便对着日志查（不泄漏堆栈）
+    if (statusCode >= 500) payload.details = { ...(payload.details || {}), traceId };
+
+    reply.code(statusCode).send({ ok: false, data: null, error: payload });
+  });
+}

package/server/http/middleware/logger.js

@@ -0,0 +1,27 @@
+// 请求日志（结构化 + 脱敏）
+//
+// 只记录「定位问题需要的最小信息」：requestId / method / path / status / 耗时 / 认证通道。
+// **不记录**查询串原文（可能含 path 但更可能含将来出现的敏感参数）、不记录 Cookie/Authorization
+// （lib/logger.js 的 redact 也会兜一层）。
+
+import crypto from 'node:crypto';
+
+export function registerRequestLogger(app, { logger }) {
+  app.addHook('onRequest', async (request, reply) => {
+    request.requestId = crypto.randomUUID();
+    request.startAt = process.hrtime.bigint();
+    reply.header('X-Request-Id', request.requestId);
+  });
+
+  app.addHook('onResponse', async (request, reply) => {
+    const durationMs = request.startAt ? Number(process.hrtime.bigint() - request.startAt) / 1e6 : null;
+    logger.info('request', {
+      requestId: request.requestId,
+      method: request.method,
+      path: request.url.split('?')[0],
+      status: reply.statusCode,
+      durationMs: durationMs === null ? null : Number(durationMs.toFixed(1)),
+      authType: request.auth ? request.auth.type : null,
+    });
+  });
+}