@yixinshuke/node-dashboard 0.0.0-stage → 0.1.0

package/src/panel-token-inject.ts

@@ -0,0 +1,53 @@
+/**
+ * 给 apirouter 调试面板注入「令牌自动保存」。
+ *
+ * 背景：运行时安装的 @yixinshuke/node-apirouter 较旧，其面板 renderResp 只在
+ * `cmd` 以 "/login" 结尾时才把 accessToken/refreshToken 写进面板 Access/Refresh 输入框；
+ * 本项目登录 cmd 是中文 "auth/登录"，故初次登录后令牌不会自动落进调试面板（需手动粘贴）。
+ * 新版 apirouter 已改成「成功 + 响应含令牌字段即保存」，这里在服务端补上等价行为，
+ * 让 GET /api 调试面板返回的 HTML 自动具备该能力，与框架新版本对齐。
+ *
+ * 实现：注册一个 app 级 onSend 钩子，仅对调试面板的 text/html 响应注入一段脚本，
+ * 覆写 renderResp —— 任意「成功 + data 含令牌字段」的响应都自动填入输入框。
+ * 仅针对面板 HTML，不影响 JSON/业务接口（那些 content-type 不是 text/html）。
+ *
+ * ⚠️ 必须为 async 并返回 payload：Fastify 的 onSend 钩子若用 3 参形式，
+ *    会被当作「返回 Promise 的钩子」，返回值即新 payload；若写成同步函数直接
+ *    return，Fastify 会一直等 done 回调 → 所有响应挂死直到超时。
+ */
+export function registerPanelTokenInject(app: any): void {
+  if (!app || typeof app.addHook !== "function") return;
+
+  app.addHook(
+    "onSend",
+    async (_request: any, reply: any, payload: any): Promise<any> => {
+      const ct: string = (reply.getHeader && reply.getHeader("content-type")) || "";
+      if (!ct.includes("text/html") || typeof payload !== "string") return payload;
+      const url: string = String(_request?.url ?? "").split("?")[0];
+      // 仅匹配面板渲染端点：/api 与 /api/:module（带 / 不带尾斜杠）
+      if (!/^\/api(\/[^/]+)?\/?$/.test(url)) return payload;
+
+      const inject = `<script>
+(function(){
+  if(typeof renderResp !== "function") return;
+  var _orig = renderResp;
+  renderResp = function(data, t0){
+    _orig(data, t0);
+    try{
+      if(data && data.result === "成功" && data.data){
+        if(data.data.accessToken) setAccessToken(String(data.data.accessToken));
+        if(data.data.refreshToken) setRefreshToken(String(data.data.refreshToken));
+        syncTokenInputs();
+      }
+    }catch(e){ /* 面板脚本未定义相关函数时静默忽略 */ }
+  };
+})();
+</script>`;
+
+      if (payload.includes("</body>")) {
+        return payload.replace("</body>", inject + "\n</body>");
+      }
+      return payload + inject;
+    },
+  );
+}

package/src/qpm-hist.ts

@@ -0,0 +1,208 @@
+import os from "node:os";
+import { dashboardConfig } from "./config.js";
+
+/**
+ * QPM 分钟历史持久化（宿主层）。
+ *
+ * 背景：apirouter（QosStats）与 http-client（Metrics）的统计都在进程内存，重启即丢；
+ * 只有 shardorm 走库内 RedisMetricsBackend 已持久化。这里在宿主层把 apirouter / http-client
+ * 的逐分钟计数与窗口累计（total/ok/fail/avgMs/maxMs/minMs）落到 Redis。
+ *
+ * 设计要点：
+ * - 实例标识用 ip:port（稳定）：重启后 pid 会变，但端口不变，历史键才能接上。
+ * - 键：qpmhist:{env}:{ip}:{port}:{svc}，hash field = `{分钟序号}:{c|ok|f|ls|lmx|lmn}`，TTL 25h。
+ *   （c=请求数 ok=成功 f=失败 ls=耗时和 lmx=耗时峰值 lmn=耗时最低；avgMs=ls/c）
+ * - 通道维度：svc = `apirouter-api` / `apirouter-open` / `apirouter-callback`（按 apirouter 命名空间拆分）。
+ * - cmd 维度：qpmhist:{env}:{ip}:{port}:{svc}:cmd:{cmd}，同样 6 个 field；供「cmd 钻取」时序。
+ * - apirouter：QosStats.onFlush 窗口增量 HINCRBY（事件驱动，空闲零回调）。
+ * - http-client：无钩子，宿主每 2s 观测当前分钟桶，跨分钟时把上一分钟终值 HSET 覆盖。
+ * - 读时聚合：histGetAgg / histGetCmd 返回最近 24h 窗口累计 + 逐分钟序列（供折线）。
+ * - 【铁律】监控非关键路径：所有 Redis 异常一律吞掉，绝不影响业务。
+ */
+
+const TTL_MS = 25 * 60 * 60 * 1000; // 保留 24h 数据 + 1h 余量；写入持续续期
+
+/** 直方图桶上界(ms)，须与 node-apirouter 的 LAT_BOUNDS 逐字节一致；否则百分位估算错位。 */
+const DEFAULT_LAT_BOUNDS = [1, 2, 3, 5, 8, 12, 20, 30, 50, 80, 120, 200, 300, 500, 1000, 2000, 5000, 10000];
+
+let redis: any = null;
+let inst = "unknown";
+
+/** 启动时调用一次：注入 Redis 客户端与稳定实例标识。无 Redis 则全部降级为 no-op。 */
+export function initQpmHist(client: any, port: number): void {
+  redis = client ?? null;
+  const ip = Object.values(os.networkInterfaces())
+    .flat()
+    .find((i: any) => i && i.family === "IPv4" && !i.internal)?.address ?? "127.0.0.1";
+  inst = `${ip}:${port}`;
+}
+
+const keyOf = (svc: string) => `qpmhist:${dashboardConfig.env}:${inst}:${svc}`;
+const cmdKeyOf = (svc: string, cmd: string) => `qpmhist:${dashboardConfig.env}:${inst}:${svc}:cmd:${cmd}`;
+const minuteOf = (t = Date.now()) => Math.floor(t / 60000);
+
+export interface MinuteStat {
+  total: number;
+  ok: number;
+  fail: number;
+  durMs: number;
+  maxMs: number;
+  minMs: number;
+}
+
+/** 单条调用增量写入（apirouter onFlush 用）：窗口增量 HINCRBY 到其所在分钟；同时落 cmd 维度。 */
+export function histIncrDelta(svc: string, d: { total?: number; ok?: number; fail?: number; costMs?: number; maxMs?: number; minMs?: number; hist?: number[]; byCmd?: Array<{ cmd: string; total?: number; ok?: number; fail?: number; costMs?: number; maxMs?: number; minMs?: number; hist?: number[] }> }): void {
+  if (!redis) return;
+  const c = Number(d.total ?? 0);
+  if (!c) return;
+  const p = String(minuteOf());
+  const svcKey = keyOf(svc);
+
+  const svcOps: Promise<any>[] = [
+    redis.hincrby(svcKey, `${p}:c`, c),
+    redis.hincrby(svcKey, `${p}:ok`, Number(d.ok ?? 0)),
+    redis.hincrby(svcKey, `${p}:f`, Number(d.fail ?? 0)),
+    redis.hincrby(svcKey, `${p}:ls`, Math.round(Number(d.costMs ?? 0))),
+    redis.hincrby(svcKey, `${p}:lmx`, Number(d.maxMs ?? 0)),
+    redis.hincrby(svcKey, `${p}:lmn`, Number(d.minMs ?? 0)),
+    redis.pexpire(svcKey, TTL_MS),
+  ];
+  // 耗时直方图（桶定义见 DEFAULT_LAT_BOUNDS）：HINCRBY 累加窗口增量，多实例/多次 flush 合并
+  const bn = Math.min((d.hist?.length) ?? 0, DEFAULT_LAT_BOUNDS.length + 1);
+  for (let k = 0; k < bn; k++) svcOps.push(redis.hincrby(svcKey, `${p}:b${k}`, d.hist?.[k] ?? 0));
+  svcOps.push(redis.hsetnx(svcKey, "bounds", JSON.stringify(DEFAULT_LAT_BOUNDS)));
+  void Promise.all(svcOps).catch(() => {});
+
+  // cmd 维度
+  for (const cmd of d.byCmd ?? []) {
+    const cc = Number(cmd.total ?? 0);
+    if (!cc) continue;
+    const ck = cmdKeyOf(svc, cmd.cmd);
+    const ops: Promise<any>[] = [
+      redis.hincrby(ck, `${p}:c`, cc),
+      redis.hincrby(ck, `${p}:ok`, Number(cmd.ok ?? 0)),
+      redis.hincrby(ck, `${p}:f`, Number(cmd.fail ?? 0)),
+      redis.hincrby(ck, `${p}:ls`, Math.round(Number(cmd.costMs ?? 0))),
+      redis.hincrby(ck, `${p}:lmx`, Number(cmd.maxMs ?? 0)),
+      redis.hincrby(ck, `${p}:lmn`, Number(cmd.minMs ?? 0)),
+      redis.pexpire(ck, TTL_MS),
+    ];
+    const cbn = Math.min((cmd.hist?.length) ?? 0, DEFAULT_LAT_BOUNDS.length + 1);
+    for (let k = 0; k < cbn; k++) ops.push(redis.hincrby(ck, `${p}:b${k}`, cmd.hist?.[k] ?? 0));
+    ops.push(redis.hsetnx(ck, "bounds", JSON.stringify(DEFAULT_LAT_BOUNDS)));
+    void Promise.all(ops).catch(() => {});
+  }
+}
+
+/** 兼容旧调用：仅写 svc 级（不落 cmd 维度） */
+export function histIncrQos(svc: string, d: any): void {
+  histIncrDelta(svc, d ?? {});
+}
+
+/** 分钟终值覆盖写（http tick 结算用）。 */
+export function histSetMinute(svc: string, minute: number, b: MinuteStat): void {
+  if (!redis) return;
+  try {
+    const k = keyOf(svc);
+    const p = String(minute);
+    void Promise.all([
+      redis.hset(
+        k,
+        `${p}:c`, String(b.total),
+        `${p}:ok`, String(b.ok),
+        `${p}:f`, String(b.fail),
+        `${p}:ls`, String(Math.round(b.durMs)),
+        `${p}:lmx`, String(b.maxMs),
+        `${p}:lmn`, String(b.minMs),
+      ),
+      redis.pexpire(k, TTL_MS),
+    ]).catch(() => {});
+  } catch {
+    /* ignore */
+  }
+}
+
+export interface HistAgg {
+  total: number;
+  ok: number;
+  fail: number;
+  avgMs: number;
+  maxMs: number;
+  minMs: number;
+  perMinute: Array<{ t: number; count: number; fail: number; avgMs: number; maxMs: number; minMs: number; hist: number[] }>;
+  /** 直方图桶上界(ms)，与 perMinute[].hist 配套 */
+  bounds: number[];
+}
+
+/** 把 Redis hash（含直方图桶 b0..bN 与 bounds）解析为聚合结果 */
+function parseHistAgg(raw: any): HistAgg | null {
+  if (!raw || !Object.keys(raw).length) return null;
+  const boundsRaw = raw["bounds"] ? safeParseBounds(raw["bounds"]) : null;
+  const bounds = Array.isArray(boundsRaw) && boundsRaw.length ? boundsRaw : DEFAULT_LAT_BOUNDS;
+  const bn = bounds.length + 1;
+  const byMinute = new Map<number, { c: number; ok: number; f: number; ls: number; lmx: number; lmn: number; hist: number[] }>();
+  for (const [field, v] of Object.entries(raw)) {
+    if (field === "bounds") continue;
+    const i = field.indexOf(":");
+    if (i <= 0) continue;
+    const m = Number(field.slice(0, i));
+    if (!Number.isFinite(m)) continue;
+    const b = byMinute.get(m) ?? { c: 0, ok: 0, f: 0, ls: 0, lmx: 0, lmn: 0, hist: new Array(bn).fill(0) };
+    const n = Number(v) || 0;
+    const sub = field.slice(i + 1);
+    if (sub === "c") b.c += n;
+    else if (sub === "ok") b.ok += n;
+    else if (sub === "f") b.f += n;
+    else if (sub === "ls") b.ls += n;
+    else if (sub === "lmx") b.lmx += n;
+    else if (sub === "lmn") b.lmn += n;
+    else if (sub[0] === "b") { const k = Number(sub.slice(1)); if (Number.isFinite(k) && k < bn) b.hist[k] += n; }
+    byMinute.set(m, b);
+  }
+  let total = 0, ok = 0, fail = 0, ls = 0, lmx = 0, lmn = 0;
+  const perMinute: Array<{ t: number; count: number; fail: number; avgMs: number; maxMs: number; minMs: number; hist: number[] }> = [];
+  for (const [m, b] of [...byMinute.entries()].sort((a, z) => a[0] - z[0])) {
+    total += b.c; ok += b.ok; fail += b.f; ls += b.ls; if (b.lmx > lmx) lmx = b.lmx; if (b.lmn && (!lmn || b.lmn < lmn)) lmn = b.lmn;
+    perMinute.push({ t: m * 60000, count: b.c, fail: b.f, avgMs: b.c ? Math.round(b.ls / b.c) : 0, maxMs: b.lmx, minMs: b.c ? b.lmn : 0, hist: b.hist });
+  }
+  return { total, ok, fail, avgMs: total ? Math.round(ls / total) : 0, maxMs: lmx, minMs: total ? lmn : 0, perMinute, bounds };
+}
+
+function safeParseBounds(s: any): number[] | null {
+  try { const a = JSON.parse(s); return Array.isArray(a) ? a.map(Number) : null; } catch { return null; }
+}
+
+/** 读本实例历史并聚合为最近 24 小时窗口累计（无 Redis 返回 null，调用方回退内存值）。 */
+export async function histGetAgg(svc: string): Promise<HistAgg | null> {
+  if (!redis) return null;
+  try {
+    const raw = await redis.hgetall(keyOf(svc));
+    return parseHistAgg(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** 读某 cmd 的逐分钟时序（钻取用）。 */
+export async function histGetCmd(svc: string, cmd: string): Promise<HistAgg | null> {
+  if (!redis) return null;
+  try {
+    const raw = await redis.hgetall(cmdKeyOf(svc, cmd));
+    return parseHistAgg(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** 内存实时桶 + Redis 历史合并（折线用）：内存优先（实时权威），Redis 只补内存缺失的分钟，不双计。 */
+export function mergeMemHist(
+  mem: Array<{ t: number; count: number }>,
+  hist: Array<{ t: number; count: number }>,
+): Array<{ t: number; count: number }> {
+  const out = new Map<number, number>();
+  for (const b of hist) out.set(b.t, b.count);
+  for (const b of mem) out.set(b.t, b.count);
+  return [...out.entries()]
+    .map(([t, count]) => ({ t, count }))
+    .sort((a, b) => a.t - b.t);
+}

package/src/shardorm-logger.ts

@@ -0,0 +1,107 @@
+import { GlobalLogger } from "@yixinshuke/node-log";
+import type { Logger, LogCategory, LogLevel } from "@yixinshuke/node-shardorm";
+
+/**
+ * shardorm → node-log 日志桥接。
+ *
+ * 把 shardorm 的 `Logger` 端口（debug/info/warn/error(category, msg, meta?)）转投到 node-log，
+ * 按 docs/日志路径说明.md §2.2 的类别约定落到 `shardorm/` 之下的对应子目录：
+ *
+ *   dml                                  → www/logs/{yyyy}/{yyyyMM}/{yyyyMMdd}/shardorm/sql/<bizKey>.log
+ *   slow                                 → www/logs/{yyyy}/{yyyyMM}/{yyyyMMdd}/shardorm/msql/<bizKey>.log
+ *   ddl / sync                           → www/logs/{yyyy}/{yyyyMM}/{yyyyMMdd}/shardorm/sync/<bizKey>.log
+ *   startup                              → www/logs/{yyyy}/{yyyyMM}/{yyyyMMdd}/shardorm/startup/<bizKey>.log
+ *   routing/connection/cache/tx/         → www/logs/{yyyy}/{yyyyMM}/{yyyyMMdd}/shardorm/{cat}/<bizKey>.log
+ *     saga/tcc/guard
+ *   monitor/encrypto/system              → www/logs/{yyyy}/{yyyyMM}/{yyyyMMdd}/shardorm/system/<bizKey>.log
+ *
+ * 设计要点（端口原则，shardorm 自身零开关）：
+ * - shardorm 只管「产生语义化日志事件」；是否落盘/落哪/落多少由本桥接控制（见 CATEGORY_DIR / CATEGORY_ENABLED / DROP_DEBUG）；
+ * - 每条日志以 `category` 末段（sql/msql/sync/startup/routing/…）作 bizKey，故同一类别当天写进同一文件；
+ * - meta（如 sql / db / shard / durationMs / error）经 `extra` 透传进 JSONL；
+ * - 观测是非关键路径：桥接本身抛错一律吞掉，**绝不阻断 shardorm 主链路**（与 node-log 铁律一致）。
+ */
+
+/** 消费端类别开关：置 false 的类别（key 用 LogCategory 值）桥接直接丢弃，不写盘。
+ * shardorm 仍照常 emit，开关完全在消费端（符合「依赖注入 / 端口」原则，shardorm 零开关）。
+ * 默认全开；取消注释即可临时关闭某类别（如热路径的 cache）。 */
+const CATEGORY_ENABLED: Partial<Record<LogCategory, boolean>> = {
+  // cache: false,
+};
+
+/** 这些类别的 debug 级日志量极大（tcc 步骤流、cache 命中明细），桥接层丢弃 debug 以控体积 */
+const DROP_DEBUG: ReadonlySet<LogCategory> = new Set<LogCategory>(["tcc", "cache"]);
+
+/** shardorm LogCategory → node-log 类别路径（见 docs/日志路径说明.md §2.2）。
+ *  全部落在 `shardorm/` 之下；monitor/encrypto 合并进 system 兜底。 */
+const CATEGORY_DIR: Record<LogCategory, string> = {
+  dml: "shardorm/sql",
+  slow: "shardorm/msql",
+  ddl: "shardorm/sync",
+  sync: "shardorm/sync",
+  startup: "shardorm/startup",
+  routing: "shardorm/routing",
+  connection: "shardorm/connection",
+  cache: "shardorm/cache",
+  tx: "shardorm/tx",
+  saga: "shardorm/saga",
+  tcc: "shardorm/tcc",
+  monitor: "shardorm/system",
+  encrypto: "shardorm/system",
+  guard: "shardorm/guard",
+  system: "shardorm/system",
+};
+
+function dirOf(category: LogCategory): string {
+  return CATEGORY_DIR[category] ?? "shardorm/system";
+}
+
+/** 构造一个实现 shardorm `Logger` 接口的桥接器（注入 ShardingDBOptions.logger 即可） */
+export function createShardormLogger(): Logger {
+  const logger = GlobalLogger.getInstance();
+
+  const emit = (
+    level: LogLevel,
+    category: LogCategory,
+    msg: string,
+    meta?: Record<string, unknown>,
+  ): void => {
+    // 消费端开关：关闭的类别直接丢弃（shardorm 已照常 emit，仅桥接不写盘）
+    if (CATEGORY_ENABLED[category] === false) return;
+    // 控体积：tcc/cache 丢弃 debug 级（量大）
+    if (level === "debug" && DROP_DEBUG.has(category)) return;
+    try {
+      const dir = dirOf(category);
+      const fileBase = dir.split("/").pop()!; // sql / msql / shardorm
+      const fn = (
+        {
+          debug: logger.debug.bind(logger),
+          info: logger.info.bind(logger),
+          warn: logger.warn.bind(logger),
+          error: logger.error.bind(logger),
+        } as const
+      )[level];
+      fn(
+        {
+          // 走 node-log 的 category 路径模式：{年}/{月}/{日}/{category}/{bizKey}.log
+          category: dir,
+          merchantId: 0,
+          storeId: 0,
+          system: "shardorm",
+          bizKey: fileBase,
+          extra: meta,
+        },
+        msg,
+      );
+    } catch {
+      /* 观测非关键路径：吞错，绝不阻断 shardorm 主链路 */
+    }
+  };
+
+  return {
+    debug: (c, m, meta) => emit("debug", c, m, meta),
+    info: (c, m, meta) => emit("info", c, m, meta),
+    warn: (c, m, meta) => emit("warn", c, m, meta),
+    error: (c, m, meta) => emit("error", c, m, meta),
+  };
+}

package/src/sql-trace.ts

@@ -0,0 +1,291 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * 请求级「shardorm 执行记录」桶 —— 响应体 `data.sql` 的唯一数据来源。
+ *
+ * 三条写入路径，形状统一、互不重叠：
+ *  1. **成功**：service 调完 shardorm 后，把返回对象的 **SQL 元信息**放进桶（用 `traceExec` 包装一行即可）。
+ *     shardorm 的既有约定：读返回 rows/row、写返回 affected，且都带 `sql:{logicalSql,statements}`；
+ *     其中 rows/row 是业务数据（响应 data 里已有一份），**不进桶**，否则响应体翻倍。
+ *  2. **失败**：SQL 执行抛错时 shardorm 不返回对象（异常里也没有 sql），故由构造项 `onError`
+ *     钩子补录一条 `ok:false` 记录（含**真实下发**的物理 SQL、物理库/表、根因）。
+ *  3. 【兜底·推荐】**shardorm 构造项 `onSql`**：每条物理 SQL 执行后即时入桶（`src:"hook"`），
+ *     覆盖全部执行（读/写/DDL），无需业务侧逐处包 traceExec —— 只因历史上有模块漏包，
+ *     那些接口的 data.sql 会莫名为空。与 1 重叠时由 pushSql 合并（保留钩子那条，见 pushSql 注释）。
+ *
+ * 出口：Fastify `preSerialization` 把桶挂到 `body.data.sql`（恒定数组；无 SQL 时 `[]`）。
+ * 红线：观测是非关键路径 —— 任何异常一律吞掉，绝不阻断业务。
+ */
+
+/** 桶元素：一次 shardorm 调用的执行记录 */
+export interface SqlExecRecord {
+  /** 本次请求内的执行序号（从 1 开始，按实际调用顺序） */
+  seq: number;
+  /** 操作类型：select / selectOne / insert / update / delete / upsert / exec（失败记录为 query/write/error） */
+  op: string;
+  /** 逻辑表名 */
+  table?: string;
+  /** service 侧测得的耗时（毫秒，含 MySQL 往返） */
+  ms?: number;
+  /** 失败记录固定 false；成功记录不带该字段 */
+  ok?: boolean;
+  /** 失败原因（ok:false 时）= shardorm 的 `err.message`：面向业务，**不含分片细节** */
+  error?: string;
+  /**
+   * 排障信息（ok:false 时）= shardorm 的 `err.shardMsg`：失败/成功分片清单 + 物理 SQL。
+   * 由 traceExec 的 catch 从抛出的 ShardormError 回填（onError 钩子按分片回调，那时还没有整体 shardMsg）。
+   */
+  shardMsg?: string;
+  /** 其余字段 = shardorm 返回对象的 SQL 元信息（sql / affected / routes …；rows 等行数据已剔除） */
+  [k: string]: unknown;
+}
+
+/** 单请求最多保留的记录数（超出丢弃，防止响应体被刷爆） */
+const MAX_ITEMS = 200;
+
+const als = new AsyncLocalStorage<SqlExecRecord[]>();
+
+/** 请求入口调用：为当前异步上下文绑定一个全新的收集桶 */
+export function beginSqlTrace(): SqlExecRecord[] {
+  const bucket: SqlExecRecord[] = [];
+  als.enterWith(bucket);
+  return bucket;
+}
+
+/** 读取当前请求的桶（不在请求上下文中时返回 undefined） */
+export function currentSqlTrace(): SqlExecRecord[] | undefined {
+  return als.getStore();
+}
+
+/** 出口格式化：恒定返回数组（无执行 → `[]`） */
+export function toSqlTrace(bucket?: SqlExecRecord[] | null): SqlExecRecord[] {
+  return bucket ?? [];
+}
+
+/**
+ * 成功路径：把一次 shardorm 调用的返回对象记入桶（**剔除行数据**）。
+ *
+ * shardorm 的返回对象里，`rows`/`row`/`result` 就是查询结果本身（业务 `data` 里已经有一份），
+ * 若原样展开进桶，同一份数据会在响应里出现两次、列表接口的响应体直接翻倍。
+ * 故这里只保留 SQL 元信息（sql / affected / routes / value …），数据只存在业务侧那一份。
+ */
+/**
+ * 取一条记录所代表的**物理语句指纹**集合：`物理库 | 物理表 | SQL 文本` 三元组。
+ * 必须带库与表，只看 SQL 文本会误杀——月汇总这类「按年分库不分表」的表，
+ * 2025/2026/2027 三个库执行的是**同一条 SQL 文本**（表名不带年后缀），只有 db 不同。
+ * 两种记录形状都要认：
+ *  - onSql 钩子记录：`sql` 是物理 SQL 字符串，库/表在 `db` / `shard`；
+ *  - 执行结果记录：`sql` 是 `{ logicalSql, statements:[{db, physicalTable, sql}] }`。
+ */
+function sqlKeysOf(rec: Record<string, unknown>): string[] {
+  const r = rec ?? {};
+  const s = r.sql;
+  if (typeof s === "string") return [`${r.db ?? ""}|${r.shard ?? ""}|${s}`];
+  const st = (s as { statements?: unknown } | undefined)?.statements;
+  if (Array.isArray(st)) {
+    return st.map((x) => {
+      const o = (x ?? {}) as { db?: unknown; physicalTable?: unknown; sql?: unknown };
+      return `${o.db ?? ""}|${o.physicalTable ?? ""}|${o.sql ?? ""}`;
+    });
+  }
+  return [];
+}
+
+export function pushSql(res: unknown, meta: { op: string; table?: string; ms?: number }): void {
+  try {
+    const bucket = als.getStore();
+    if (!bucket || bucket.length >= MAX_ITEMS) return;
+    // 三种「数据本体」形状都要摘，否则各自重复一份：
+    //   rows   → 列表查询 select（SelectResult.rows）
+    //   row    → 单条查询 first/selectOne（SelectOneResult.row）
+    //   result → 原生 exec（ExecResult.result，可能是整页数据）
+    // 保留：sql（logicalSql + 各分片 statements）/ routes / affected / value（聚合标量）等元信息
+    const { rows: _rows, row: _row, result: _result, ...rest } = (res ?? {}) as Record<string, unknown>;
+    // 【去重】挂了 shardorm `onSql` 钩子的服务：钩子在每条物理 SQL 执行后即时入桶（src:"hook"），
+    // 业务侧 traceExec 随后还会推一条同语句的执行结果记录 —— 同一条语句会出现两条。
+    // 这里命中「同一条物理语句的钩子记录」就**只做合并**不再新增：把业务侧更精确的 op（insert/update…）
+    // 与逻辑表名补过去，耗时保留钩子那条（它是 SQL 真实往返耗时）。
+    // 两个护栏：① 钩子记录本身（src:"hook"）永不参与去重，否则跨分片执行的同文本语句会被互相吞掉；
+    //          ② 指纹含物理库 + 物理表 + SQL 文本，跨年库的同文本语句互不干扰。
+    // 未挂钩子的服务桶里没有 hook 记录，本分支永不命中，行为与既往完全一致。
+    const keys = sqlKeysOf(rest);
+    if (keys.length > 0 && (rest as { src?: unknown }).src !== "hook") {
+      const hit = bucket.find(
+        (r) =>
+          (r as { src?: unknown } | undefined)?.src === "hook" &&
+          sqlKeysOf(r as Record<string, unknown>).some((k) => keys.includes(k)),
+      ) as SqlExecRecord | undefined;
+      if (hit) {
+        if (hit.op === "query" || hit.op === "write") hit.op = meta.op;
+        if (hit.table === undefined && meta.table !== undefined) hit.table = meta.table;
+        return;
+      }
+    }
+    bucket.push({ seq: bucket.length + 1, op: meta.op, table: meta.table, ms: meta.ms, ...rest });
+  } catch {
+    /* 观测非关键路径：吞错 */
+  }
+}
+
+/**
+ * 包装一次 shardorm 调用（service 层统一入口）：
+ *
+ * ```ts
+ * const res = await traceExec(q.insert(), { op: "insert", table: "b_商品" });
+ * ```
+ *
+ * 成功 → 返回对象记入桶并原样返回；抛错 → 原错照抛（SQL 由 onError 钩子补录、shardMsg 由 catch 回填），
+ * 业务语义不变。
+ */
+export async function traceExec<P extends Promise<any>>(
+  exec: P,
+  meta: { op: string; table?: string },
+): Promise<Awaited<P>> {
+  const t0 = Date.now();
+  // 本次调用开始前的桶长度：失败时只在 [before, end) 区间回填，绝不误伤上一次调用的记录
+  const before = als.getStore()?.length ?? 0;
+  try {
+    const res = await exec;
+    pushSql(res, { op: meta.op, table: meta.table, ms: Date.now() - t0 });
+    return res as Awaited<P>;
+  } catch (err) {
+    attachShardMsg(err, before);
+    throw err;
+  }
+}
+
+/**
+ * 失败路径（traceExec 的 catch）：把抛出的 ShardormError 自带的 `shardMsg` 补进本次调用的失败记录。
+ *
+ * 为什么必须在这里补：shardorm 的 `onError` 钩子是**按失败分片**回调的，那一刻只有分片级原始错误
+ * （如 `Duplicate entry ...`），还没有「失败分片清单 + 成功分片清单 + 物理 SQL」这个整体 shardMsg
+ * —— 它是在失败分片聚合完成后随异常抛出的。所以只读异常，不依赖钩子。
+ *
+ * @param before 本次调用开始前的桶长度，只在该区间内回填
+ */
+function attachShardMsg(err: unknown, before: number): void {
+  try {
+    const bucket = als.getStore();
+    if (!bucket) return;
+    const msg = (err as { shardMsg?: unknown } | null)?.shardMsg;
+    if (typeof msg !== "string" || !msg) return;
+    // 优先回填本次调用新产生的失败记录（不新增条目，避免同一错误出现两条）
+    for (let i = bucket.length - 1; i >= before; i--) {
+      const rec = bucket[i];
+      if (rec?.ok === false) {
+        if (rec.shardMsg === undefined) rec.shardMsg = msg;
+        return;
+      }
+    }
+    // 本次调用没有产出失败语句（如护栏类错误不触发 onError）→ 补一条最小记录，保证 shardMsg 不丢
+    if (bucket.length >= MAX_ITEMS) return;
+    bucket.push({
+      seq: bucket.length + 1,
+      op: "error",
+      ok: false,
+      error: (err as Error)?.message,
+      shardMsg: msg,
+    });
+  } catch {
+    /* 观测非关键路径：吞错 */
+  }
+}
+
+/** 链式 builder 的「执行型」方法：调用即打库（中间方法只改条件、返回 this） */
+const TERMINAL_METHODS = new Set(["select", "selectOne", "first", "agg", "insert", "update", "delete", "upsert", "exec"]);
+/** 不执行的纯计算方法（离线生成 SQL），直接透传 */
+const PASSTHROUGH_METHODS = new Set(["toSql"]);
+
+/** 包一个链式 builder：终结方法执行后把返回对象记入桶；中间方法保持代理链 */
+function tracedBuilder(builder: any, table: string): any {
+  return new Proxy(builder, {
+    get(t: any, prop: string | symbol, recv) {
+      const v = Reflect.get(t, prop, recv);
+      if (typeof v !== "function") return v;
+      if (typeof prop !== "string" || PASSTHROUGH_METHODS.has(prop)) return v.bind(t);
+      if (TERMINAL_METHODS.has(prop)) {
+        // first 归一为 selectOne，与 service 里手写的 op 命名保持一致
+        const op = prop === "first" ? "selectOne" : prop;
+        return (...args: any[]) => traceExec(v.apply(t, args), { op, table });
+      }
+      return (...args: any[]) => {
+        const out = v.apply(t, args);
+        if (out === t) return recv; // 链式方法返回 this → 复用当前代理
+        return out !== null && typeof out === "object" ? tracedBuilder(out, table) : out;
+      };
+    },
+  });
+}
+
+/**
+ * 给 shardorm 门面套一层代理：该入口下**所有**链式执行（读/写/exec，含 `tx()` 回调内、
+ * 以及复用同一 db 对象的内部函数）执行成功后自动把返回对象记入本次请求的桶。
+ *
+ * 用法（service 层一处即可）：
+ * ```ts
+ * const { base, order } = dbReady();   // 内部即 tracedDb(getBaseDb())
+ * await order.tx("sys_审批单", shard, async (db) => { await db.from(...).insert(); }); // 回调内同样被记录
+ * ```
+ *
+ * 是非关键路径：仅在一次调用**成功返回**后补记录；抛错不拦截（由 onError 钩子补录失败语句）。
+ */
+export function tracedDb<T extends object>(db: T): T {
+  return new Proxy(db, {
+    get(t: any, prop: string | symbol, recv) {
+      const v = Reflect.get(t, prop, recv);
+      if (typeof v !== "function") return v;
+      if (typeof prop !== "string") return v.bind(t);
+      if (prop === "from") return (name: string) => tracedBuilder(v.call(t, name), String(name));
+      if (prop === "tx") {
+        // tx(table, shard, fn)：把回调收到的 db 也包一层，保证事务内语句同样进桶
+        return (...args: any[]) => {
+          const i = args.findIndex((a: unknown) => typeof a === "function");
+          if (i >= 0) {
+            const fn = args[i] as (inner: any, ...rest: any[]) => unknown;
+            args[i] = (inner: any, ...rest: any[]) => fn(tracedDb(inner), ...rest);
+          }
+          return v.apply(t, args);
+        };
+      }
+      if (TERMINAL_METHODS.has(prop)) {
+        // 门面级终结方法（如 db.exec(sql, params)）
+        return (...args: any[]) => traceExec(v.apply(t, args), { op: prop });
+      }
+      return v.bind(t);
+    },
+  }) as T;
+}
+
+/**
+ * 失败路径（shardorm 构造项 `onError` 的钩子实现）：补录一条失败记录。
+ *
+ * 事件里的 `sql` 是**真实下发**的物理 SQL（已改写为物理表名），并带物理库/表与失败根因；
+ * 不是离线预生成结果，故外键第二段、对齐式深分页等「执行期组装」的语句也不会缺。
+ */
+export function pushFailedSql(info: unknown): void {
+  try {
+    const bucket = als.getStore();
+    if (!bucket || bucket.length >= MAX_ITEMS) return;
+    const e = info as Record<string, any>;
+    if (!e?.sql) return; // 无 SQL 的错误事件（如结果行数护栏）不产出语句记录
+    const context = e?.context === undefined || e?.context === null ? "" : String(e.context);
+    const sql = String(e.sql);
+    // 事件里的 error 是「分片级原始错误」，正常不带 shardMsg（整体 shardMsg 在抛出的异常上，
+    // 由 traceExec 的 catch 回填）；这里只做防御性透传，shardorm 若给事件补上就原样带出。
+    const evMsg = (e?.error as { shardMsg?: unknown } | undefined)?.shardMsg;
+    bucket.push({
+      seq: bucket.length + 1,
+      op: context.includes("write") ? "write" : context.includes("query") ? "query" : "error",
+      table: e?.shard,
+      ok: false,
+      error: e?.error?.message ?? (e?.error === undefined || e?.error === null ? undefined : String(e.error)),
+      ...(typeof evMsg === "string" && evMsg ? { shardMsg: evMsg } : {}),
+      db: e?.db,
+      context: context || undefined,
+      // 失败路径没有逻辑 SQL 预览，logicalSql 置空以保持与成功记录同构
+      sql: { logicalSql: "", statements: [{ db: e?.db, physicalTable: e?.shard, sql }] },
+    });
+  } catch {
+    /* 观测非关键路径：吞错 */
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.