agentworkshop 0.2.1

package/server/services/workshop/daq/host-bindings.ts

@@ -0,0 +1,71 @@
+/**
+ * 宿主端口进程内默认装配(R5 可拆性准备)。
+ *
+ * 这里是 daq 网关与中心平台服务(device-twin.repo / dcw line-run、recipe、line repo)
+ * 唯一的耦合点:daq-controller 只依赖 host-ports.ts 的接口,具体实现集中在本文件。
+ * 未来 edge-agent 独立进程不 import 本文件,改为注入 MQTT 上行实现即可。
+ *
+ * bindDaqHost(fn) = bindDaqBroadcast(fn) + bindDaqHostPorts(进程内实现),
+ * daq REST 路由装配点统一改为调用它(端口先于控制器任何使用就位)。
+ */
+import { deviceScenePayload, getDeviceTwinRepo } from '../assets/device-twin.repo'
+import { bumpTaggedSamples, getActiveLineRun, getAllActiveLineRuns } from '../dcw/line-run'
+import { getDcwLineRepo } from '../dcw/dcw-line.repo'
+import { getDcwRecipeRepo } from '../dcw/dcw-recipe.repo'
+import { bindDaqBroadcast } from './daq-controller'
+import { bindDaqHostPorts, type ActiveRunSnapshot, type DaqHostPorts } from './host-ports'
+
+const telemetryImpl: DaqHostPorts['telemetry'] = {
+  applyTelemetry(deviceId, telemetry, state) {
+    try {
+      const twin = getDeviceTwinRepo().applyTelemetry(deviceId, telemetry, state)
+      return { ok: true, twinId: twin?.id ?? null }
+    }
+    catch {
+      // 与原实现同语义:目标设备不存在等异常 → 调用方解绑自愈
+      return { ok: false, twinId: null }
+    }
+  },
+  scenePayload(twinId) {
+    const twin = getDeviceTwinRepo().findById(twinId)
+    return twin ? deviceScenePayload(twin) : null
+  },
+  deviceExists(deviceId) {
+    return getDeviceTwinRepo().findById(deviceId) != null
+  },
+  listDaqTwins() {
+    return getDeviceTwinRepo()
+      .listAll()
+      .filter(t => t.kind === 'daq' || (t.modelRef ?? '').startsWith('daq-'))
+      .map(t => ({ id: t.id, kind: t.kind, modelRef: t.modelRef, name: t.name, posX: t.posX, posZ: t.posZ }))
+  },
+}
+
+const lineRunImpl: DaqHostPorts['lineRun'] = {
+  activeRun(lineId): ActiveRunSnapshot | null {
+    const run = getActiveLineRun(lineId ?? undefined)
+    return run ? { lineId: run.lineId, runId: run.runId, recipeId: run.recipeId, productId: run.productId } : null
+  },
+  hasAnyActiveRun() {
+    return getAllActiveLineRuns().length > 0
+  },
+  recipeWindow(recipeId, nodeId) {
+    const w = getDcwRecipeRepo().byId(recipeId)?.daqWindows?.find(x => x.nodeId === nodeId)
+    return w ? { min: w.min ?? null, max: w.max ?? null } : null
+  },
+  lineExists(lineId) {
+    return getDcwLineRepo().byId(lineId) != null
+  },
+  bumpTaggedSamples(lineId) {
+    bumpTaggedSamples(lineId)
+  },
+}
+
+/**
+ * daq REST 路由装配点统一入口:广播出口 + 宿主端口一次装配(幂等)。
+ * fn 传 null 仅刷新端口绑定(广播出口清空)。
+ */
+export function bindDaqHost(fn: ((type: string, payload: unknown) => void) | null): void {
+  bindDaqHostPorts({ telemetry: telemetryImpl, lineRun: lineRunImpl })
+  bindDaqBroadcast(fn)
+}

package/server/services/workshop/daq/host-ports.ts

@@ -0,0 +1,64 @@
+/**
+ * R5 可拆性准备:daq 网关对中心平台宿主服务的反向依赖收敛为端口接口。
+ *
+ * 网关(daq-controller)此前直接 import device-twin.repo(遥测回写/失败自愈解绑)
+ * 与 dcw/line-run + dcw-recipe.repo/dcw-line.repo(配方窗口门控),无法脱离中心平台
+ * 独立部署。现把这两类依赖收敛为 telemetry / lineRun 两个端口:
+ *  - 中心平台在路由装配点注入进程内默认实现(host-bindings.ts → bindDaqHost);
+ *  - 未来 edge-agent 独立进程提供自己的实现(或经 MQTT 上行)即可,网关代码零改动。
+ * 端口存 globalThis(HMR 存活,与 daq-controller 单例同一生命周期约定)。
+ */
+
+/** 时序库打标所需的批次快照(只暴露网关需要的字段,不泄漏 dcw 内部类型) */
+export interface ActiveRunSnapshot {
+  lineId: string
+  runId: string
+  recipeId: string
+  productId: string
+}
+
+/** 遥测上报端口:绑定设备的值回写 + 孪生场景推送 + 绑定校验(中心实现 = device-twin.repo) */
+export interface DaqTelemetryPort {
+  /**
+   * 遥测回写:telemetry 键值写入绑定设备的孪生,state 为同设备多节点汇聚的最严重态。
+   * 目标设备不存在 → { ok:false }(调用方解绑自身,链路自愈);成功 → { ok:true, twinId }。
+   */
+  applyTelemetry(deviceId: string, telemetry: Record<string, number | string | boolean>, state: string): { ok: boolean, twinId: string | null }
+  /** 孪生场景载荷(WS device.updated 帧;设备已删 → null) */
+  scenePayload(twinId: string): unknown | null
+  /** 绑定目标存在性校验 */
+  deviceExists(deviceId: string): boolean
+  /** 存量 kind='daq' 孪生清单(首访升格为 DaqNode;边缘模式返回 []) */
+  listDaqTwins(): Array<{ id: string, kind: string, modelRef: string, name: string, posX?: number, posZ?: number }>
+}
+
+/** 产线批次端口:活动 LineRun 门控 + 配方 daq 窗口 + 打标计数(中心实现 = dcw/line-run + recipe/line repo) */
+export interface DaqLineRunPort {
+  /** 产线当前活动批次(严格语义:lineId 空 → null,不受其他产线运行影响) */
+  activeRun(lineId: string | null): ActiveRunSnapshot | null
+  /** 是否存在任意活动批次(sweep 总门控) */
+  hasAnyActiveRun(): boolean
+  /** 配方对指定节点的数采监控窗口(min/max,未设 → null) */
+  recipeWindow(recipeId: string, nodeId: string): { min: number | null, max: number | null } | null
+  /** 产线存在性校验(节点绑定 lineId 时) */
+  lineExists(lineId: string): boolean
+  /** 活动窗口内样本打标计数(产线进度;非活动产线 no-op) */
+  bumpTaggedSamples(lineId: string): void
+}
+
+export interface DaqHostPorts {
+  telemetry: DaqTelemetryPort
+  lineRun: DaqLineRunPort
+}
+
+const g = globalThis as typeof globalThis & { __daqHostPorts?: DaqHostPorts }
+
+/** 装配宿主端口(中心平台路由装配点调用;幂等覆盖) */
+export function bindDaqHostPorts(ports: DaqHostPorts): void {
+  g.__daqHostPorts = ports
+}
+
+/** 读取宿主端口(未装配 = 中心装配前/边缘独立运行 → null,调用方走降级语义) */
+export function getDaqHostPorts(): DaqHostPorts | null {
+  return g.__daqHostPorts ?? null
+}

package/server/services/workshop/daq/infra.ts

@@ -0,0 +1,202 @@
+/**
+ * DAQ 基础设施编排 —— 配置驱动的真实 MQTT/Timescale 生命周期。
+ *
+ * 启动策略(config.yml daq.startInfrastructure):
+ *   auto   = 探测配置地址;端口不通且宿主有 Docker → docker compose 自动拉起,
+ *            拉起后等待就绪;无 Docker → 直连失败即降级;
+ *   always = 仅经 Docker 拉起(不探测直连);
+ *   never  = 只按配置直连。
+ *
+ * 降级语义:任一后端不可达 → 该后端回退 mock 对应物(进程内队列 / SQLite 时序仿真),
+ * 控制器停采(在线数采停用),meta 携带 warning,前端横幅 + 一键重连;
+ * 后台每 30s 自动重试,恢复后自动重启采集并切回真实后端。
+ */
+import { createLogger } from '../logger'
+import { execFile } from 'node:child_process'
+import { createConnection } from 'node:net'
+import { promisify } from 'node:util'
+import { join } from 'node:path'
+
+const log = createLogger('daq.infra')
+
+const execFileAsync = promisify(execFile)
+
+export interface DaqInfraConfig {
+  startInfrastructure: 'auto' | 'always' | 'never'
+  mqtt: { host: string, port: number, username?: string, password?: string, secure?: boolean, caFile?: string }
+  timescale: { host: string, port: number, user: string, password: string, database: string }
+}
+
+export interface DaqInfraStatus {
+  /** 真实 MQTT 是否在线(离线 → 进程内队列降级) */
+  mqttOnline: boolean
+  /** Timescale 是否在线(离线 → SQLite 时序仿真降级) */
+  tsdbOnline: boolean
+  /** 任一降级 → 在线采集停用,前端横幅警告 */
+  degraded: boolean
+  warning: string
+  /** 基础设施拉起方式:docker / direct / none */
+  startedBy: 'docker' | 'direct' | 'none'
+  lastCheckAt: string
+  lastError?: string
+}
+
+const g = globalThis as typeof globalThis & {
+  __daqInfra?: { cfg: DaqInfraConfig, status: DaqInfraStatus, retryTimer?: NodeJS.Timeout, projectRoot?: string }
+}
+
+function state() {
+  return g.__daqInfra ??= {
+    cfg: { startInfrastructure: 'auto', mqtt: { host: '127.0.0.1', port: 1883 }, timescale: { host: '127.0.0.1', port: 5432, user: 'postgres', password: 'awshop', database: 'awshop' } },
+    status: { mqttOnline: false, tsdbOnline: false, degraded: true, warning: '', startedBy: 'none', lastCheckAt: new Date().toISOString() },
+  }
+}
+
+/** TCP 端口探测(2s 超时;Docker 端口映射即代表服务可连) */
+function probePort(host: string, port: number, timeoutMs = 2000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = createConnection({ host, port })
+    const done = (ok: boolean): void => {
+      sock.destroy()
+      resolve(ok)
+    }
+    sock.setTimeout(timeoutMs, () => done(false))
+    sock.once('connect', () => done(true))
+    sock.once('error', () => done(false))
+  })
+}
+
+async function dockerAvailable(): Promise<boolean> {
+  try {
+    await execFileAsync('docker', ['--version'], { timeout: 5000 })
+    return true
+  }
+  catch {
+    return false
+  }
+}
+
+async function dockerComposeUp(projectRoot: string): Promise<{ ok: boolean, error?: string }> {
+  try {
+    await execFileAsync('docker', ['compose', '-f', join(projectRoot, 'docker-compose.yml'), 'up', '-d', 'daq-mosquitto', 'daq-timescale'], { timeout: 120_000, cwd: projectRoot })
+    return { ok: true }
+  }
+  catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+/** 等待两个端口就绪(拉起后服务初始化需要数秒;最长 waitMs) */
+async function waitPorts(cfg: DaqInfraConfig, waitMs: number): Promise<{ mqtt: boolean, tsdb: boolean }> {
+  const deadline = Date.now() + waitMs
+  let mqtt = false
+  let tsdb = false
+  while (Date.now() < deadline && !(mqtt && tsdb)) {
+    mqtt = mqtt || await probePort(cfg.mqtt.host, cfg.mqtt.port, 1200)
+    tsdb = tsdb || await probePort(cfg.timescale.host, cfg.timescale.port, 1200)
+    if (!(mqtt && tsdb)) await new Promise(r => setTimeout(r, 1500))
+  }
+  return { mqtt, tsdb }
+}
+
+export function daqInfraStatus(): DaqInfraStatus {
+  return { ...state().status }
+}
+
+/** 运行配置快照(启动插件装配时写入;重连端点复用) */
+export function daqInfraConfig(): DaqInfraConfig {
+  return state().cfg
+}
+
+/** 配置 → 连接 URL(env 显式覆盖优先,便于外部托管 broker/db;S1:支持凭据/TLS) */
+export function daqUrls(cfg = state().cfg): { mqttUrl: string | null, tsdbUrl: string | null } {
+  // S1:凭据/TLS 优先 env(DAQ_MQTT_URL 整串覆盖),否则由 config.mqtt 拼(含 user:pass@ 与 mqtts://)
+  let mqttUrl: string
+  if (process.env.DAQ_MQTT_URL) {
+    mqttUrl = process.env.DAQ_MQTT_URL
+  }
+  else {
+    const scheme = cfg.mqtt.secure ? 'mqtts' : 'mqtt'
+    const cred = cfg.mqtt.username
+      ? `${encodeURIComponent(cfg.mqtt.username)}:${encodeURIComponent(cfg.mqtt.password ?? '')}@`
+      : ''
+    mqttUrl = `${scheme}://${cred}${cfg.mqtt.host}:${cfg.mqtt.port}`
+  }
+  const { user, password, database, host, port } = cfg.timescale
+  const tsdbUrl = process.env.DAQ_TSDB_URL ?? `postgres://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}/${database}`
+  return { mqttUrl, tsdbUrl }
+}
+
+/**
+ * 探测/拉起/降级判定主流程(幂等;启动插件与重连端点共用)。
+ * 返回最终状态;真实后端在线时由调用方(插件)重建 queue/tsdb 单例并恢复采集。
+ */
+export async function ensureDaqInfrastructure(cfg: DaqInfraConfig, projectRoot: string): Promise<DaqInfraStatus> {
+  const st = state()
+  st.cfg = cfg
+  const s = st.status
+  s.lastCheckAt = new Date().toISOString()
+  s.lastError = undefined
+
+  // 1) 直接探测配置地址
+  let probe = await waitPorts(cfg, 3000)
+  s.startedBy = 'none'
+
+  // 2) 不通 → 按策略 Docker 拉起
+  if (!(probe.mqtt && probe.tsdb) && cfg.startInfrastructure !== 'never') {
+    const canDocker = await dockerAvailable()
+    if (canDocker) {
+      log.info('[daq-infra] 配置地址未就绪,经 Docker Compose 拉起(daq-mosquitto + daq-timescale)…')
+      const up = await dockerComposeUp(projectRoot)
+      if (up.ok) {
+        probe = await waitPorts(cfg, 60_000)
+        if (probe.mqtt || probe.tsdb) s.startedBy = 'docker'
+      }
+      else {
+        s.lastError = `docker compose 拉起失败: ${up.error?.slice(0, 200)}`
+        log.error('[daq-infra]', s.lastError)
+      }
+    }
+    else if (cfg.startInfrastructure === 'auto') {
+      s.lastError = '宿主机无 Docker,直接连接配置地址'
+    }
+  }
+
+  if (probe.mqtt && probe.tsdb) {
+    if (s.startedBy === 'none') s.startedBy = 'direct'
+  }
+
+  s.mqttOnline = probe.mqtt
+  s.tsdbOnline = probe.tsdb
+  s.degraded = !(probe.mqtt && probe.tsdb)
+
+  if (s.degraded) {
+    const missing: string[] = []
+    if (!probe.mqtt) missing.push(`MQTT ${cfg.mqtt.host}:${cfg.mqtt.port}`)
+    if (!probe.tsdb) missing.push(`Timescale ${cfg.timescale.host}:${cfg.timescale.port}`)
+    s.warning = `数采基础设施不可达:${missing.join('、')}${s.lastError ? `(${s.lastError})` : ''}。已降级:队列→进程内 / 时序库→SQLite 仿真,在线采集已停用;修复后可重连。`
+    log.warn(`[daq-infra] 降级运行 — ${s.warning}`)
+  }
+  else {
+    s.warning = ''
+    log.info(`[daq-infra] 真实链路就绪(mqtt=${cfg.mqtt.host}:${cfg.mqtt.port}, timescale=${cfg.timescale.host}:${cfg.timescale.port}, 来源=${s.startedBy})`)
+  }
+  return daqInfraStatus()
+}
+
+/** 后台自动重连(降级期间每 30s 重试;恢复后 rebuild + 恢复采集) */
+export function scheduleAutoReconnect(onRestored: () => void): void {
+  const st = state()
+  if (st.retryTimer) return
+  st.retryTimer = setInterval(() => {
+    const s = st.status
+    if (!s.degraded) return
+    void ensureDaqInfrastructure(st.cfg, st.projectRoot ?? process.cwd()).then((fresh) => {
+      if (!fresh.degraded) {
+        log.info('[daq-infra] 自动重连成功,恢复真实链路')
+        onRestored()
+      }
+    }).catch(() => { /* 下个周期再试 */ })
+  }, 30_000)
+  st.retryTimer.unref?.()
+}

package/server/services/workshop/daq/storage/index.ts

@@ -0,0 +1,96 @@
+/**
+ * TsdbPort 工厂 —— 配置驱动(daqInfraUrls 提供真实 Timescale URL),降级 SQLite 仿真。
+ * 单例挂 globalThis;rebuildTsdb() 支持重连时从降级实例切回真实实例。
+ */
+import { createLogger } from '../../logger'
+import { SqliteTimeSeriesAdapter } from './sqlite.adapter'
+import { TimescaleAdapter } from './timescale.adapter'
+import type { TsdbPort } from './tsdb-port'
+
+const log = createLogger('daq.tsdb')
+
+interface DaqTsdbState { current?: TsdbPort, initError?: unknown }
+const g = globalThis as typeof globalThis & { __daqTsdbState?: DaqTsdbState }
+
+function makeFallback(reason: string): TsdbPort {
+  const dev = new SqliteTimeSeriesAdapter()
+  dev.init()
+  log.warn(`[daq-tsdb] ${reason} → 已降级 SQLite 时序仿真`)
+  return dev
+}
+
+/** 就绪门:消费者可 await 后再批量写(真实 Timescale 异步建表完成前由门挡住) */
+export const tsdbReady: Promise<void> = (() => {
+  const st: DaqTsdbState = g.__daqTsdbState ??= {}
+  if (!st.current) {
+    const url = process.env.DAQ_TSDB_URL
+    if (!url) {
+      // 无配置(启动插件尚未装配):先占位仿真库;插件随后按 infra 状态 rebuild
+      const dev = new SqliteTimeSeriesAdapter()
+      dev.init()
+      st.current = dev
+    }
+    else {
+      const adapter = new TimescaleAdapter(url)
+      st.current = adapter
+      void adapter.init().then(
+        () => log.info('[daq-tsdb] TimescaleDB 就绪:', url.replace(/\/\/[^@]*@/, '//***@')),
+        (err) => {
+          if (g.__daqTsdbState?.current === adapter) {
+            g.__daqTsdbState.current = makeFallback(err instanceof Error ? err.message : String(err))
+          }
+        },
+      )
+    }
+  }
+  return Promise.resolve()
+})()
+
+export function getTsdb(): TsdbPort {
+  const st: DaqTsdbState = g.__daqTsdbState ??= {}
+  let cur = st.current
+  if (!cur) {
+    cur = new SqliteTimeSeriesAdapter()
+    void cur.init()
+    log.info('[daq-tsdb] SQLite 时序仿真就绪(data/daq-timeseries.sqlite)')
+    st.current = cur
+  }
+  return cur
+}
+
+/** 重连/初始装配:按 infra 判定结果(重新)构建真实或降级实例;旧实例显式释放连接 */
+export async function rebuildTsdb(online: boolean, url?: string | null): Promise<void> {
+  const st: DaqTsdbState = g.__daqTsdbState ??= {}
+  const swap = (next: TsdbPort): void => {
+    const old = st.current
+    st.current = next
+    // 旧池延后释放(在飞写自然失败一次即被消费侧重试收口)
+    void Promise.resolve(old?.close?.()).catch(() => {})
+  }
+  if (!online || !url) {
+    if (st.current?.backend !== 'sqlite-emulated') {
+      swap(makeFallback('infra 判定离线'))
+    }
+    return
+  }
+  const adapter = new TimescaleAdapter(url)
+  // PG/Timescale 初始化窗口:接受 TCP 但建连即断(Connection terminated)→ 有限重试
+  let lastErr: unknown
+  for (let i = 0; i < 5; i++) {
+    try {
+      await adapter.init()
+      lastErr = null
+      break
+    }
+    catch (err) {
+      lastErr = err
+      await new Promise(r => setTimeout(r, 2500))
+    }
+  }
+  if (lastErr) {
+    await adapter.close?.().catch(() => {})
+    throw lastErr
+  }
+  swap(adapter)
+  log.info('[daq-tsdb] TimescaleDB 就绪:', url.replace(/\/\/[^@]*@/, '//***@'))
+}

package/server/services/workshop/daq/storage/sqlite.adapter.ts

@@ -0,0 +1,205 @@
+/**
+ * SqliteTimeSeriesAdapter —— TsdbPort 的开发仿真实现。
+ *
+ * 无 Timescale 实例时的缺省后端:同一契约落在本地 SQLite(data/daq-timeseries.sqlite),
+ * 结构与时序语义对齐(ts_ms 主键 + 节点索引、bucketMs 降采样用整除分桶聚合)。
+ * 生产环境配置 DAQ_TSDB_URL 即切换 Timescale,业务代码零改动。
+ */
+import { createLogger } from '../../logger'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+import type { DaqQueryOpts, DaqSampleRow, TsdbPoint, TsdbPort } from './tsdb-port'
+
+const log = createLogger('daq.tsdb.sqlite')
+
+const DB_PATH = join(ensureDataDir(), 'daq-timeseries.sqlite')
+
+export class SqliteTimeSeriesAdapter implements TsdbPort {
+  readonly backend = 'sqlite-emulated'
+  private db: DatabaseSync | null = null
+  /** 启动清理水位(默认保留 7 天,环境变量 DAQ_TS_RETENTION_H 可调) */
+  private readonly retentionH = Number(process.env.DAQ_TS_RETENTION_H ?? 168)
+  private retentionTimer: NodeJS.Timeout | null = null
+
+  async init(): Promise<void> {
+    this.db = new DatabaseSync(DB_PATH)
+    this.db.exec('PRAGMA journal_mode = WAL')
+    // WAL + NORMAL:批写单事务一次 fsync,兼顾持久性与事件循环停顿
+    this.db.exec('PRAGMA synchronous = NORMAL')
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS daq_samples (
+        node_id TEXT    NOT NULL,
+        ts_ms   INTEGER NOT NULL,
+        value   REAL    NOT NULL,
+        state   TEXT    NOT NULL DEFAULT 'ok',
+        line_id    TEXT,
+        product_id TEXT,
+        recipe_id  TEXT,
+        run_id     TEXT,
+        PRIMARY KEY (node_id, ts_ms)
+      );
+      CREATE INDEX IF NOT EXISTS idx_daq_node_ts ON daq_samples (node_id, ts_ms DESC);
+    `)
+    // 存量库迁移:先补打标列(幂等),再建依赖列的索引
+    const cols = new Set((this.db.prepare('PRAGMA table_info(daq_samples)').all() as Array<{ name: string }>).map(c => c.name))
+    for (const [col, ddl] of [['line_id', 'ALTER TABLE daq_samples ADD COLUMN line_id TEXT'], ['product_id', 'ALTER TABLE daq_samples ADD COLUMN product_id TEXT'], ['recipe_id', 'ALTER TABLE daq_samples ADD COLUMN recipe_id TEXT'], ['run_id', 'ALTER TABLE daq_samples ADD COLUMN run_id TEXT']] as const) {
+      if (!cols.has(col)) this.db.exec(ddl)
+    }
+    this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_daq_tag ON daq_samples (product_id, recipe_id, ts_ms DESC);
+      CREATE INDEX IF NOT EXISTS idx_daq_run ON daq_samples (run_id, ts_ms DESC);
+    `)
+    // 保留窗口:启动清一次 + 后台周期任务(30min,防长会话磁盘无限涨)
+    this.sweepRetention()
+    if (!this.retentionTimer) {
+      this.retentionTimer = setInterval(() => this.sweepRetention(), 30 * 60_000)
+      this.retentionTimer.unref?.()
+    }
+  }
+
+  /** 保留期清理:分批 DELETE(单批 5000 行,避免长事务锁库) */
+  private sweepRetention(): void {
+    if (!this.db) return
+    const cutoff = Date.now() - this.retentionH * 3600_000
+    try {
+      let removed = 0
+      for (;;) {
+        const r = this.db.prepare(
+          'DELETE FROM daq_samples WHERE rowid IN (SELECT rowid FROM daq_samples WHERE ts_ms < ? LIMIT 5000)',
+        ).run(cutoff)
+        removed += Number(r.changes)
+        if (Number(r.changes) < 5000) break
+      }
+      if (removed > 0) log.info(`[daq-tsdb] 保留期清理 ${removed} 行(>${this.retentionH}h)`)
+    }
+    catch (err) {
+      log.error('[daq-tsdb] 保留期清理失败:', err instanceof Error ? err.message : err)
+    }
+  }
+
+  async writeSamples(rows: DaqSampleRow[]): Promise<void> {
+    if (!this.db || rows.length === 0) return
+    // 批内单事务:一次 fsync 落整批(逐行 run 会每行一次 WAL fsync,写放大)
+    const ins = this.db.prepare(
+      'INSERT OR IGNORE INTO daq_samples (node_id, ts_ms, value, state, line_id, product_id, recipe_id, run_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+    )
+    this.db.exec('BEGIN')
+    try {
+      for (const r of rows) ins.run(r.nodeId, r.tsMs, r.value, r.state, r.lineId ?? null, r.productId ?? null, r.recipeId ?? null, r.runId ?? null)
+      this.db.exec('COMMIT')
+    }
+    catch (err) {
+      try {
+        this.db.exec('ROLLBACK')
+      }
+      catch { /* 事务已终结 */ }
+      throw err
+    }
+  }
+
+  async query(nodeId: string, opts: DaqQueryOpts): Promise<TsdbPoint[]> {
+    if (!this.db) return []
+    const limit = Math.min(opts.limit ?? 500, 5000)
+    const from = opts.fromMs ?? 0
+    const to = opts.toMs ?? Date.now()
+    if (opts.bucketMs && opts.bucketMs >= 100) {
+      const bucket = opts.bucketMs
+      const rows = this.db.prepare(`
+        SELECT (ts_ms / :b) * :b AS b_at,
+               AVG(value) AS avg, MIN(value) AS min, MAX(value) AS max, COUNT(*) AS cnt
+        FROM daq_samples
+        WHERE node_id = :id AND ts_ms >= :from AND ts_ms <= :to
+        GROUP BY b_at ORDER BY b_at DESC LIMIT :lim
+      `).all({ ':id': nodeId, ':from': from, ':to': to, ':b': bucket, ':lim': limit }) as Array<{ b_at: number, avg: number, min: number, max: number, cnt: number }>
+      return rows.map(r => ({ at: Number(r.b_at), avg: r.avg, min: r.min, max: r.max, cnt: Number(r.cnt) }))
+    }
+    const rows = this.db.prepare(`
+      SELECT ts_ms, value, state FROM daq_samples
+      WHERE node_id = :id AND ts_ms >= :from AND ts_ms <= :to
+      ORDER BY ts_ms DESC LIMIT :lim
+    `).all({ ':id': nodeId, ':from': from, ':to': to, ':lim': limit }) as Array<{ ts_ms: number, value: number, state: string }>
+    return rows.map(r => ({ at: Number(r.ts_ms), value: Number(r.value), state: String(r.state) }))
+  }
+
+  async queryTagged(q: import('./tsdb-port').TsdbTagQuery): Promise<Map<string, import('./tsdb-port').TsdbPoint[]>> {
+    const out = new Map<string, import('./tsdb-port').TsdbPoint[]>()
+    if (!this.db) return out
+    const where: string[] = []
+    const params: Array<string | number> = []
+    if (q.lineId) {
+      where.push('line_id = ?')
+      params.push(q.lineId)
+    }
+    if (q.productId) {
+      where.push('product_id = ?')
+      params.push(q.productId)
+    }
+    if (q.recipeId) {
+      where.push('recipe_id = ?')
+      params.push(q.recipeId)
+    }
+    if (q.runId) {
+      where.push('run_id = ?')
+      params.push(q.runId)
+    }
+    if (q.nodeIds?.length) {
+      where.push(`node_id IN (${q.nodeIds.map(() => '?').join(',')})`)
+      params.push(...q.nodeIds)
+    }
+    where.push('ts_ms >= ?')
+    params.push(q.fromMs ?? 0)
+    where.push('ts_ms <= ?')
+    params.push(q.toMs ?? Date.now())
+    const limit = Math.min(q.limit ?? 2000, 10_000)
+    if (q.bucketMs && q.bucketMs >= 100) {
+      const rows2 = (this.db.prepare(`
+        SELECT node_id, (ts_ms / ?) * ? AS b_at, AVG(value) AS avg, MIN(value) AS min, MAX(value) AS max, COUNT(*) AS cnt
+        FROM daq_samples WHERE ${where.join(' AND ')}
+        GROUP BY node_id, b_at ORDER BY b_at ASC LIMIT ?
+      `).all(q.bucketMs, q.bucketMs, ...params, limit)) as Array<{ node_id: string, b_at: number, avg: number, min: number, max: number, cnt: number }>
+      for (const r of rows2) {
+        const list = out.get(r.node_id) ?? []
+        list.push({ at: Number(r.b_at), avg: r.avg, min: r.min, max: r.max, cnt: Number(r.cnt) })
+        out.set(r.node_id, list)
+      }
+      return out
+    }
+    const rows = (this.db.prepare(`
+      SELECT node_id, ts_ms, value FROM daq_samples WHERE ${where.join(' AND ')}
+      ORDER BY ts_ms ASC LIMIT ?
+    `).all(...params, limit)) as Array<{ node_id: string, ts_ms: number, value: number }>
+    for (const r of rows) {
+      const list = out.get(r.node_id) ?? []
+      list.push({ at: Number(r.ts_ms), value: r.value })
+      out.set(r.node_id, list)
+    }
+    return out
+  }
+
+  async latest(): Promise<Map<string, DaqSampleRow>> {
+    const out = new Map<string, DaqSampleRow>()
+    if (!this.db) return out
+    // SQLite 裸列保证:GROUP BY + MAX() 时裸列取自 max 所在行(命中 idx_daq_node_ts,免相关子查询)
+    const rows = this.db.prepare(`
+      SELECT node_id, MAX(ts_ms) AS ts_ms, value, state FROM daq_samples GROUP BY node_id
+    `).all() as Array<{ node_id: string, ts_ms: number, value: number, state: string }>
+    for (const r of rows) {
+      out.set(r.node_id, { nodeId: r.node_id, tsMs: Number(r.ts_ms), value: Number(r.value), state: String(r.state) })
+    }
+    return out
+  }
+
+  close(): Promise<void> | void {
+    this.sweepRetentionTimerStop()
+    this.db?.close()
+    this.db = null
+  }
+
+  private sweepRetentionTimerStop(): void {
+    if (this.retentionTimer) {
+      clearInterval(this.retentionTimer)
+      this.retentionTimer = null
+    }
+  }
+}