agentworkshop 0.7.66 → 0.7.71

package/server/services/workshop/eda/dashboard-repo.ts

@@ -0,0 +1,166 @@
+/**
+ * EDA 看板仓储(plan1 M3)—— eda_dashboards + eda_dashboard_charts。
+ * 可见性同 chart(B4):private→owner/admin;line→产线可读。
+ * 布局 = 12 栅格 gridPos(Grafana 模式);详情对内嵌 chart 逐个走 canReadChart,
+ * 不可见图在响应中标 inaccessible: true(不静默丢弃 —— 旁路防护的可见化)。
+ */
+import { randomUUID } from 'node:crypto'
+import type { ResolvedUser } from '@/server/api/workshop/caller'
+import { lineMode } from '../permissions'
+import { recordOps } from '../ops/ops'
+import { edaDb } from './eda-db'
+import { chartById, canReadChart, type EdaChartRow } from './chart-repo'
+
+export interface BoardGridPos { chartId: string, x: number, y: number, w: number, h: number }
+
+export interface EdaDashboardRow {
+  id: string
+  title: string
+  filters: { window?: string, agg?: string }
+  layout: BoardGridPos[]
+  ownerUserId: string
+  lineId: string | null
+  visibility: 'private' | 'line'
+  version: number
+  createdAt: string
+  updatedAt: string
+}
+
+function rowOf(r: Record<string, unknown>): EdaDashboardRow {
+  return {
+    id: String(r.id),
+    title: String(r.title ?? ''),
+    filters: safeObj(r.filters_json) as EdaDashboardRow['filters'],
+    layout: safeArr(r.layout_json) as BoardGridPos[],
+    ownerUserId: String(r.owner_user_id ?? ''),
+    lineId: r.line_id == null ? null : String(r.line_id),
+    visibility: String(r.visibility ?? 'private') as EdaDashboardRow['visibility'],
+    version: Number(r.version ?? 1),
+    createdAt: String(r.created_at ?? ''),
+    updatedAt: String(r.updated_at ?? ''),
+  }
+}
+function safeObj(text: unknown): Record<string, unknown> {
+  try {
+    return JSON.parse(String(text ?? '{}')) as Record<string, unknown>
+  }
+  catch {
+    return {}
+  }
+}
+function safeArr(text: unknown): unknown[] {
+  try {
+    return JSON.parse(String(text ?? '[]')) as unknown[]
+  }
+  catch {
+    return []
+  }
+}
+
+function canReadBoard(user: ResolvedUser, row: EdaDashboardRow): boolean {
+  if (row.ownerUserId === user.id || user.role === 'admin') return true
+  if (row.visibility === 'line' && row.lineId) return lineMode(user, row.lineId) !== 'none'
+  return false
+}
+
+function writeOk(user: ResolvedUser, row: EdaDashboardRow): boolean {
+  return row.ownerUserId === user.id || user.role === 'admin'
+}
+
+export function listDashboards(user: ResolvedUser, opts: { mine?: boolean } = {}): EdaDashboardRow[] {
+  const rows = edaDb().prepare('SELECT * FROM eda_dashboards ORDER BY updated_at DESC LIMIT 200').all() as Array<Record<string, unknown>>
+  return rows.map(rowOf)
+    .filter(b => canReadBoard(user, b))
+    .filter(b => (opts.mine ? b.ownerUserId === user.id : true))
+}
+
+function boardByIdRaw(id: string): EdaDashboardRow | null {
+  const r = edaDb().prepare('SELECT * FROM eda_dashboards WHERE id = ?').get(id) as Record<string, unknown> | undefined
+  return r ? rowOf(r) : null
+}
+
+export function dashboardById(user: ResolvedUser, id: string): {
+  dashboard: EdaDashboardRow
+  charts: Array<{ chart: EdaChartRow | null, gridPos: BoardGridPos | null, inaccessible: boolean }>
+} | null {
+  const row = boardByIdRaw(id)
+  if (!row || !canReadBoard(user, row)) return null
+  const charts = row.layout.map((pos) => {
+    const chart = chartById(user, pos.chartId)
+    return { chart, gridPos: pos, inaccessible: !chart || !canReadChart(user, chart) }
+  })
+  return { dashboard: row, charts }
+}
+
+function sanitizeLayout(layout: unknown): BoardGridPos[] {
+  if (!Array.isArray(layout)) return []
+  return layout
+    .filter((p): p is BoardGridPos => {
+      const x = p as BoardGridPos
+      return typeof x?.chartId === 'string' && Number.isInteger(x.x) && Number.isInteger(x.y)
+    })
+    .map(p => ({
+      chartId: p.chartId,
+      x: Math.min(Math.max(Math.round(p.x), 0), 11),
+      y: Math.max(Math.round(p.y), 0),
+      w: Math.min(Math.max(Math.round(p.w) || 4, 1), 12),
+      h: Math.min(Math.max(Math.round(p.h) || 3, 1), 12),
+    }))
+}
+
+export function createDashboard(user: ResolvedUser, input: {
+  title: string
+  filters?: Record<string, unknown>
+  layout?: unknown
+  lineId?: string | null
+  visibility?: string
+}): EdaDashboardRow {
+  const vis = input.visibility ?? 'private'
+  if (!['private', 'line'].includes(vis)) throw new Error('visibility 只支持 private/line。')
+  if (vis === 'line' && !input.lineId) throw new Error('visibility=line 必须携带 line_id。')
+  const id = `edb-${randomUUID().slice(0, 8)}`
+  const now = new Date().toISOString()
+  edaDb().prepare(`INSERT INTO eda_dashboards (id, title, filters_json, layout_json, owner_user_id, line_id, visibility, version, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?, ?)`)
+    .run(id, input.title.slice(0, 200), JSON.stringify(input.filters ?? {}), JSON.stringify(sanitizeLayout(input.layout)), user.id, input.lineId ?? null, vis, now, now)
+  recordOps({
+    actor: user.id, actorName: user.name, actorKind: 'user',
+    action: 'dashboard.save', kind: 'system', targetKind: 'eda-dashboard', targetId: id,
+    summary: `创建看板「${input.title}」(${vis})`,
+  })
+  return boardByIdRaw(id)!
+}
+
+export function updateDashboard(user: ResolvedUser, id: string, patch: {
+  title?: string
+  filters?: Record<string, unknown>
+  layout?: unknown
+  visibility?: string
+  lineId?: string | null
+}): EdaDashboardRow {
+  const row = boardByIdRaw(id)
+  if (!row) throw new Error(`看板不存在: ${id}`)
+  if (!writeOk(user, row)) throw new Error('仅 owner 或 admin 可修改看板。')
+  const vis = patch.visibility ?? row.visibility
+  const lineId = patch.lineId !== undefined ? patch.lineId : row.lineId
+  if (!['private', 'line'].includes(vis)) throw new Error('visibility 只支持 private/line。')
+  if (vis === 'line' && !lineId) throw new Error('visibility=line 必须携带 line_id。')
+  edaDb().prepare(`UPDATE eda_dashboards SET title = ?, filters_json = ?, layout_json = ?, line_id = ?, visibility = ?, version = version + 1, updated_at = ? WHERE id = ?`)
+    .run(patch.title ?? row.title, JSON.stringify(patch.filters ?? row.filters), JSON.stringify(sanitizeLayout(patch.layout ?? row.layout)), lineId ?? null, vis, new Date().toISOString(), id)
+  recordOps({
+    actor: user.id, actorName: user.name, actorKind: 'user',
+    action: 'dashboard.save', kind: 'system', targetKind: 'eda-dashboard', targetId: id,
+    summary: `更新看板「${patch.title ?? row.title}」(v${row.version + 1})`,
+    detail: { keys: Object.keys(patch) },
+  })
+  return boardByIdRaw(id)!
+}
+
+export function deleteDashboard(user: ResolvedUser, id: string): boolean {
+  const row = boardByIdRaw(id)
+  if (!row) return false
+  if (!writeOk(user, row)) throw new Error('仅 owner 或 admin 可删除看板。')
+  edaDb().prepare('DELETE FROM eda_dashboard_charts WHERE dashboard_id = ?').run(id)
+  edaDb().prepare('DELETE FROM eda_dashboards WHERE id = ?').run(id)
+  return true
+}

package/server/services/workshop/eda/data-export.ts

@@ -0,0 +1,274 @@
+/**
+ * 用户面 DAQ 批量导出服务(plan1 M1)。
+ *
+ * 与 Agent 面差异:授权 = 可读产线(readonly+)的节点集合(toolDaqExport 是 agent
+ * 绑定口径);执行走同一 exportDaqDataset 核心(依赖注入,护栏沿用 7 天窗/200 万点
+ * 每节点/400 万总行/保留 50 目录)。任务经 eda_export_jobs 账本异步执行:
+ *  - 并发=1 队列(exportDaqDataset 全内存缓冲,并发多路会叠加内存尖峰 —— 评审 H4);
+ *  - bootedAt 判死:进程重启后遗留 running 按失败呈现(mes_fetch_jobs 同款);
+ *  - 产物目录仍落 <dataDir>/daq-exports/,台账存 id 引用(RETAIN_EXPORTS 清理旧目录
+ *    后文件可能不存在 —— 读时探测并如实呈现,评审 H4)。
+ */
+import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ResolvedUser } from '@/server/api/workshop/caller'
+import { lineMode } from '../permissions'
+import { getDaqNodeRepo } from '../daq/daq-node.repo'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+import { recordOps } from '../ops/ops'
+import { edaDb } from './eda-db'
+
+const WINDOW_MAX_MS = 7 * 24 * 3600_000
+const NODES_MAX = 50
+/** 进程启动时刻(跨进程判死基线) */
+const bootedAt = new Date().toISOString()
+
+export interface EdaExportJobView {
+  id: string
+  kind: string
+  status: 'running' | 'ready' | 'failed'
+  spec: { nodeIds: string[], fromMs: number, toMs: number, title: string, note: string, merge: boolean, runId?: string }
+  result: { exportId?: string, dir?: string, files?: Array<{ nodeId: string, rows: number }>, totalRows?: number, truncated?: string[], mergedFile?: string, missing?: boolean }
+  error?: string
+  createdBy: string
+  createdAt: string
+  updatedAt: string
+}
+
+function rowToView(r: Record<string, unknown>): EdaExportJobView {
+  return {
+    id: String(r.id),
+    kind: String(r.kind ?? 'daq-export'),
+    status: String(r.status) as EdaExportJobView['status'],
+    spec: safeJson(r.spec_json, { nodeIds: [], fromMs: 0, toMs: 0, title: '', note: '', merge: false }),
+    result: safeJson(r.result_json, {} as EdaExportJobView['result']),
+    error: r.error == null ? undefined : String(r.error),
+    createdBy: String(r.created_by ?? ''),
+    createdAt: String(r.created_at ?? ''),
+    updatedAt: String(r.updated_at ?? ''),
+  }
+}
+
+function safeJson<T>(text: unknown, fallback: T): T {
+  try {
+    return JSON.parse(String(text ?? '')) as T
+  }
+  catch {
+    return fallback
+  }
+}
+
+function jobById(id: string): EdaExportJobView | null {
+  const r = edaDb().prepare('SELECT * FROM eda_export_jobs WHERE id = ?').get(id) as Record<string, unknown> | undefined
+  return r ? rowToView(r) : null
+}
+
+function updateJob(id: string, patch: { status?: string, result?: unknown, error?: string }): void {
+  edaDb().prepare('UPDATE eda_export_jobs SET status = COALESCE(?, status), result_json = COALESCE(?, result_json), error = ?, updated_at = ? WHERE id = ?')
+    .run(patch.status ?? null, patch.result === undefined ? null : JSON.stringify(patch.result), patch.error ?? null, new Date().toISOString(), id)
+}
+
+/** 进程重启判死:遗留 running 一律按失败呈现(一次性,模块首用时收口) */
+let swept = false
+function sweepStaleOnce(): void {
+  if (swept) return
+  swept = true
+  try {
+    edaDb().prepare(`UPDATE eda_export_jobs SET status = 'failed', error = '进程重启,任务中断(bootedAt 判死)', updated_at = ?
+      WHERE status = 'running' AND created_at < ?`).run(bootedAt, bootedAt)
+  }
+  catch { /* 台账不可用不阻断导出 */ }
+}
+
+// ===== 并发=1 队列 =====
+let queue: Promise<void> = Promise.resolve()
+
+export function edaExportQueueResetForTest(): void {
+  queue = Promise.resolve()
+}
+
+function enqueue(jobId: string): void {
+  queue = queue.then(() => runExportJob(jobId)).catch(() => { /* 队列不因单任务失败断裂 */ })
+}
+
+async function runExportJob(jobId: string): Promise<void> {
+  const job = jobById(jobId)
+  if (!job || job.status !== 'running') return
+  try {
+    const { exportDaqDataset } = await import('../agents/industrial/daq-export')
+    const { getTsdb, tsdbReady } = await import('../daq/storage')
+    await tsdbReady
+    const { findDaqTemplate } = await import('../daq/daq-templates')
+    const { getDcwLineRepo } = await import('../dcw/dcw-line.repo')
+    const nodeOf = (id: string) => {
+      const n = getDaqNodeRepo().byId(id)
+      if (!n) return undefined
+      const tpl = findDaqTemplate(n.templateKey)
+      return {
+        id: n.id, name: n.name, unit: n.unit ?? '', lineId: n.lineId ?? '',
+        min: n.min, max: n.max, warnLow: n.warnLow, warnHigh: n.warnHigh,
+        intervalMs: n.intervalMs ?? null, decimals: n.decimals,
+        semantics: n.semantics || tpl?.semantics || tpl?.ch || '',
+        signalKind: (tpl?.signalKind === 'vector' || tpl?.signalKind === 'image' ? tpl.signalKind : 'scalar') as 'scalar' | 'vector' | 'image',
+        ...(tpl?.vector ? { vector: tpl.vector } : {}),
+      }
+    }
+    const lineIds = [...new Set(job.spec.nodeIds.map(id => nodeOf(id)?.lineId ?? '').filter(Boolean))]
+    const lines = lineIds.map((lid) => {
+      const line = getDcwLineRepo().byId(lid)
+      return { lineId: lid, lineName: line?.name ?? lid, description: '' }
+    })
+    const result = await exportDaqDataset({
+      targets: job.spec.nodeIds,
+      nodeOf,
+      // E1:runId 贯穿导出 —— 带 runId 时走打标查询(只取该批次样本),否则全量窗口
+      readPoints: job.spec.runId
+        ? async (nodeId, win) => {
+          const m = await getTsdb().queryTagged({ runId: job.spec.runId, nodeIds: [nodeId], fromMs: win.fromMs, toMs: win.toMs, limit: win.limit })
+          return (m.get(nodeId) ?? []).map(p => ({ at: p.at, value: p.value ?? p.avg, state: p.state }))
+        }
+        : (nodeId, win) => getTsdb().query(nodeId, win),
+      fromMs: job.spec.fromMs,
+      toMs: job.spec.toMs,
+      title: job.spec.title,
+      note: job.spec.note,
+      lines,
+      rootDir: join(ensureDataDir(), 'daq-exports'),
+      merge: job.spec.merge,
+      readFrames: (nodeId, win) => getTsdb().queryFrames(nodeId, win),
+      readFrameContent: async (nodeId, at) => {
+        const { getDaqController } = await import('../daq/daq-controller')
+        return getDaqController().frameContent(nodeId, at, false)
+      },
+    })
+    updateJob(jobId, {
+      status: 'ready',
+      result: {
+        exportId: result.exportId,
+        dir: result.dir,
+        files: result.files.map(f => ({ nodeId: f.nodeId, rows: f.rows })),
+        totalRows: result.totalRows,
+        truncated: result.truncated,
+        ...(result.mergedFile ? { mergedFile: result.mergedFile } : {}),
+      },
+    })
+  }
+  catch (err) {
+    updateJob(jobId, { status: 'failed', error: err instanceof Error ? err.message : String(err) })
+  }
+}
+
+/** 可读节点 allowlist(readonly+;与 /data 数据源树同口径) */
+function readableNodeIds(user: ResolvedUser): string[] {
+  return getDaqNodeRepo().all().filter(n => n.enabled && lineMode(user, n.lineId) !== 'none').map(n => n.id)
+}
+
+export function startDaqExport(user: ResolvedUser, args: {
+  lineId?: string
+  nodeIds?: string[]
+  fromMs?: number
+  toMs?: number
+  lastMinutes?: number
+  title?: string
+  note?: string
+  merge?: boolean
+  /** E1:批次切片导出(带 runId 时 readPoints 走打标查询,只含该批次样本) */
+  runId?: string
+}): EdaExportJobView {
+  sweepStaleOnce()
+  const allowed = new Set(readableNodeIds(user))
+  if (allowed.size === 0) {
+    throw Object.assign(new Error('你没有可读产线的数采节点,无权导出。'), { status: 403, code: 'SCOPE_VIOLATION' })
+  }
+  let targets = (args.nodeIds ?? []).map(s => String(s).trim()).filter(Boolean)
+  if (targets.length > NODES_MAX) {
+    throw Object.assign(new Error(`node_ids 一次最多 ${NODES_MAX} 个。`), { status: 400, code: 'VALIDATION_ERROR' })
+  }
+  if (targets.length > 0) {
+    const illegal = targets.filter(id => !allowed.has(id))
+    if (illegal.length > 0) {
+      throw Object.assign(new Error(`无权导出节点:${illegal.join(', ')}。`), { status: 403, code: 'SCOPE_VIOLATION' })
+    }
+  }
+  else {
+    targets = [...allowed]
+    if (args.lineId) targets = targets.filter((id) => {
+      const n = getDaqNodeRepo().byId(id)
+      return n?.lineId === args.lineId
+    })
+  }
+  targets = [...new Set(targets)].filter(id => getDaqNodeRepo().byId(id))
+  if (targets.length === 0) {
+    throw Object.assign(new Error('没有可导出的节点(指定节点均不存在或不在可读产线上)。'), { status: 400, code: 'VALIDATION_ERROR' })
+  }
+  const toMs = Number(args.toMs) || Date.now()
+  const fromMs = Number(args.fromMs) || toMs - (Number(args.lastMinutes) || 60) * 60_000
+  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || fromMs >= toMs) {
+    throw Object.assign(new Error('时间窗非法:from 必须小于 to。'), { status: 400, code: 'VALIDATION_ERROR' })
+  }
+  if (toMs - fromMs > WINDOW_MAX_MS) {
+    throw Object.assign(new Error('时间窗超限(最大 7 天),请缩小窗口。'), { status: 400, code: 'VALIDATION_ERROR' })
+  }
+  const id = `edajob-${randomUUID().slice(0, 8)}`
+  const now = new Date().toISOString()
+  const spec = { nodeIds: targets, fromMs, toMs, title: String(args.title ?? '').slice(0, 200), note: String(args.note ?? '').slice(0, 500), merge: args.merge === true, ...(args.runId ? { runId: args.runId } : {}) }
+  edaDb().prepare(`INSERT INTO eda_export_jobs (id, kind, spec_json, status, result_json, created_by, created_at, updated_at)
+    VALUES (?, 'daq-export', ?, 'running', '{}', ?, ?, ?)`).run(id, JSON.stringify(spec), user.id, now, now)
+  recordOps({
+    actor: user.id,
+    actorName: user.name,
+    actorKind: 'user',
+    action: 'data.export',
+    kind: 'daq',
+    targetKind: 'daq',
+    targetId: id,
+    lineId: args.lineId ?? '',
+    scope: 'line',
+    summary: `用户发起 DAQ 批量导出(${targets.length} 节点,窗口 ${new Date(fromMs).toISOString()} ~ ${new Date(toMs).toISOString()}${spec.merge ? ',merge 宽表' : ''})`,
+    detail: { jobId: id, nodes: targets.length },
+  })
+  enqueue(id)
+  return jobById(id)!
+}
+
+/** 可见 job = 创建者本人 ∪ 产线可读者 */
+export function visibleExportJobs(user: ResolvedUser, limit = 50): EdaExportJobView[] {
+  sweepStaleOnce()
+  const rows = edaDb().prepare('SELECT * FROM eda_export_jobs ORDER BY created_at DESC LIMIT ?').all(Math.min(Math.max(limit, 1), 200)) as Array<Record<string, unknown>>
+  return rows.map(rowToView).filter((j) => {
+    if (j.createdBy === user.id) return true
+    return j.spec.nodeIds.some((id) => {
+      const n = getDaqNodeRepo().byId(id)
+      return !!n && lineMode(user, n.lineId) !== 'none'
+    })
+  })
+}
+
+export function getExportJobFor(user: ResolvedUser, id: string): EdaExportJobView | null {
+  sweepStaleOnce()
+  const job = jobById(id)
+  if (!job) return null
+  if (job.createdBy !== user.id && !visibleExportJobs(user, 200).some(j => j.id === id)) return null
+  return { ...job, result: probeMissing(job) }
+}
+
+/** RETAIN_EXPORTS 清理后目录可能不存在:读时探测,missing 标记如实呈现(评审 H4) */
+function probeMissing(job: EdaExportJobView): EdaExportJobView['result'] {
+  if (job.status === 'ready' && job.result.dir && !existsSync(job.result.dir)) {
+    return { ...job.result, missing: true }
+  }
+  return job.result
+}
+
+/** 产物文件安全下载:manifest.json / README.md / merged.csv / nodes/<safe>.csv / data.csv(派生集;路径穿越防护) */
+export function resolveExportFile(user: ResolvedUser, jobId: string, rel: string): { abs: string, mime: string } | null {
+  const job = getExportJobFor(user, jobId)
+  if (!job || job.status !== 'ready' || !job.result.dir) return null
+  const clean = String(rel ?? '').trim()
+  if (!/^(manifest\.json|README\.md|merged\.csv|data\.csv|nodes\/[A-Za-z0-9_-]{1,80}\.csv)$/.test(clean)) return null
+  const dir = job.result.dir
+  const abs = join(dir, clean)
+  if (!abs.startsWith(dir) || !existsSync(abs)) return null
+  return { abs, mime: clean.endsWith('.json') ? 'application/json' : 'text/csv; charset=utf-8' }
+}

package/server/services/workshop/eda/data-query.ts

@@ -0,0 +1,231 @@
+/**
+ * EDA 数据查询服务 —— 产线级多节点批量时序查询(plan1 /daq/query 的核心)。
+ *
+ * B1 收口方式:服务层**逐节点循环**调用 queryTagged(nodeIds:[单个]) —— 单节点查询时
+ * 全局 LIMIT 与每节点配额语义等价,无需改动 TsdbPort 双适配器契约(2026-10-21:适配器
+ * 侧 ROW_NUMBER 方案因安全扫描器对存量 $n 占位符体系的全文件基线拦截而放弃,逐节点
+ * 循环是评审给出的备选②,正确性由构造保证)。
+ *
+ * 交互式护栏(eda-enterprise 评审 H2):
+ *  - node_ids ≤ 8;省略时取产线全部节点,>8 即 400 要求显式指定;
+ *  - 每节点返回点 ≤2000;桶宽自动抬高使 桶数/节点 ≤2000(窗口/2000);
+ *  - 窗口 ≤7 天;单用户并发查询 ≤2(超出 429);
+ *  - LRU 缓存 key=全部影响结果的入参(节点集+窗+桶+agg+打标过滤),TTL 按桶宽分档。
+ */
+import type { ResolvedUser } from '@/server/api/workshop/caller'
+import { lineMode } from '../permissions'
+import { getDaqNodeRepo } from '../daq/daq-node.repo'
+import { getDcwController } from '../dcw/dcw-controller'
+import { getActiveLineRun } from '../dcw/line-run'
+
+export const QUERY_NODES_MAX = 8
+export const QUERY_POINTS_PER_NODE = 2000
+const WINDOW_MAX_MS = 7 * 24 * 3600_000
+
+export type QueryAgg = 'avg' | 'min' | 'max'
+
+export interface DataQueryInput {
+  lineId?: string
+  nodeIds?: string[]
+  fromMs?: number
+  toMs?: number
+  lastMinutes?: number
+  bucketMs?: number
+  agg?: QueryAgg
+  runId?: string
+  recipeId?: string
+  productId?: string
+  includeBand?: boolean
+}
+
+export interface DataQuerySeries {
+  nodeId: string
+  name: string
+  unit: string
+  lineId: string
+  min: number | null
+  max: number | null
+  points: Array<{ at: number, v: number }>
+  band?: Array<{ at: number, lo: number, hi: number }>
+  truncated: boolean
+}
+
+export interface DataQueryResult {
+  lineId: string
+  window: { fromMs: number, toMs: number, bucketMs: number, agg: QueryAgg }
+  series: DataQuerySeries[]
+  cached: boolean
+}
+
+// ===== 并发闸(单用户 ≤2 在飞) =====
+const inflight = new Map<string, number>()
+
+export function dataQueryConcurrencyReset(): void {
+  inflight.clear()
+}
+
+// ===== LRU 缓存(TTL 按桶宽分档) =====
+interface CacheEntry {
+  at: number
+  result: DataQueryResult
+}
+const cache = new Map<string, CacheEntry>()
+const CACHE_MAX = 100
+
+function cacheTtl(bucketMs: number): number {
+  return bucketMs >= 60_000 ? 60_000 : 5_000
+}
+
+export function dataQueryCacheClear(): void {
+  cache.clear()
+}
+
+function cacheKey(inp: DataQueryInput & { resolvedNodeIds: string[] }): string {
+  return JSON.stringify([
+    inp.resolvedNodeIds, inp.fromMs, inp.toMs, inp.bucketMs, inp.agg,
+    inp.lineId ?? '', inp.runId ?? '', inp.recipeId ?? '', inp.productId ?? '', inp.includeBand ?? false,
+  ])
+}
+
+export class DataQueryError extends Error {
+  constructor(readonly status: number, readonly code: string, message: string) {
+    super(message)
+  }
+}
+
+/** 用户可读产线集合内的节点解析(越权/不存在/停用一律剔除;全不可见报 403) */
+function resolveNodes(user: ResolvedUser, inp: DataQueryInput): { lineId: string, nodeIds: string[] } {
+  const repo = getDaqNodeRepo()
+  let lineId = String(inp.lineId ?? '').trim()
+  if (lineId && lineMode(user, lineId) === 'none') {
+    throw new DataQueryError(403, 'SCOPE_VIOLATION', `产线 ${lineId} 不在你的可读范围内。`)
+  }
+  const wanted = (inp.nodeIds ?? []).map(s => String(s).trim()).filter(Boolean)
+  if (wanted.length > QUERY_NODES_MAX) {
+    throw new DataQueryError(400, 'VALIDATION_ERROR', `node_ids 一次最多 ${QUERY_NODES_MAX} 个(收到 ${wanted.length});请分组查询或按产线过滤。`)
+  }
+  let nodes = wanted.map(id => repo.byId(id)).filter(n => n && n.enabled)
+  if (wanted.length > 0 && nodes.length === 0) {
+    throw new DataQueryError(403, 'SCOPE_VIOLATION', '指定的节点不存在、已停用或不在你的可读范围内。')
+  }
+  for (const n of nodes) {
+    if (lineMode(user, n!.lineId) === 'none') {
+      throw new DataQueryError(403, 'SCOPE_VIOLATION', `节点 ${n!.name}(${n!.id}) 不在你的可读产线上。`)
+    }
+    if (!lineId) lineId = n!.lineId ?? ''
+  }
+  if (wanted.length === 0) {
+    if (!lineId) throw new DataQueryError(400, 'VALIDATION_ERROR', 'line_id 与 node_ids 至少提供一个。')
+    nodes = repo.all().filter(n => n.lineId === lineId && n.enabled)
+    if (nodes.length > QUERY_NODES_MAX) {
+      throw new DataQueryError(400, 'VALIDATION_ERROR', `产线 ${lineId} 有 ${nodes.length} 个数采节点,一次最多查询 ${QUERY_NODES_MAX} 个:请传 node_ids 显式选择(≤${QUERY_NODES_MAX})。`)
+    }
+  }
+  if (nodes.length === 0) throw new DataQueryError(400, 'VALIDATION_ERROR', '没有可查询的节点。')
+  return { lineId, nodeIds: nodes.map(n => n!.id) }
+}
+
+/** 多节点批量查询(逐节点循环;护栏/缓存/并发闸在此收口) */
+export async function dataQuery(user: ResolvedUser, inp: DataQueryInput): Promise<DataQueryResult> {
+  const nInFlight = inflight.get(user.id) ?? 0
+  if (nInFlight >= 2) {
+    throw new DataQueryError(429, 'QUERY_CONCURRENCY', '你的查询并发已达上限(2),请等待在途查询完成。')
+  }
+  const toMs = Number(inp.toMs) || Date.now()
+  const fromMs = Number(inp.fromMs) || toMs - (Number(inp.lastMinutes) || 60) * 60_000
+  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || fromMs >= toMs) {
+    throw new DataQueryError(400, 'VALIDATION_ERROR', '时间窗非法:from 必须小于 to。')
+  }
+  if (toMs - fromMs > WINDOW_MAX_MS) {
+    throw new DataQueryError(400, 'VALIDATION_ERROR', '时间窗超限(最大 7 天),请缩小窗口。')
+  }
+  const agg: QueryAgg = inp.agg === 'min' || inp.agg === 'max' ? inp.agg : 'avg'
+  // 桶宽:显式请求与自动抬高中取大者,保证 桶数/节点 ≤2000(默认下限仍受 daq.query.minBucketMs 约束)
+  const { minBucketMs } = (await import('../settings')).daqRuntimeSettings().query
+  const autoBucket = Math.ceil((toMs - fromMs) / QUERY_POINTS_PER_NODE)
+  const bucketMs = Math.max(minBucketMs, Math.round(Number(inp.bucketMs)) || 0, autoBucket)
+
+  const { lineId, nodeIds } = resolveNodes(user, inp)
+  const key = cacheKey({ ...inp, resolvedNodeIds: nodeIds, fromMs, toMs, bucketMs, agg })
+  const hit = cache.get(key)
+  if (hit && Date.now() - hit.at < cacheTtl(bucketMs)) {
+    cache.delete(key)
+    cache.set(key, hit)
+    return { ...hit.result, cached: true }
+  }
+
+  inflight.set(user.id, nInFlight + 1)
+  try {
+    const { getTsdb, tsdbReady } = await import('../daq/storage')
+    await tsdbReady
+    const tsdb = getTsdb()
+    const repo = getDaqNodeRepo()
+    const series: DataQuerySeries[] = []
+    for (const nodeId of nodeIds) {
+      const node = repo.byId(nodeId)
+      if (!node) continue
+      const tagged = await tsdb.queryTagged({
+        lineId: node.lineId || lineId || undefined,
+        runId: inp.runId || undefined,
+        recipeId: inp.recipeId || undefined,
+        productId: inp.productId || undefined,
+        nodeIds: [nodeId],
+        fromMs,
+        toMs,
+        bucketMs,
+        limit: QUERY_POINTS_PER_NODE,
+      })
+      const pts = tagged.get(nodeId) ?? []
+      const points: DataQuerySeries['points'] = []
+      let band: DataQuerySeries['band']
+      for (const p of pts) {
+        const v = agg === 'min' ? p.min : agg === 'max' ? p.max : p.avg
+        if (!Number.isFinite(v)) continue
+        points.push({ at: p.at, v: Number((v ?? 0).toFixed(6)) })
+        if (inp.includeBand && p.min != null && p.max != null) {
+          band ??= []
+          band.push({ at: p.at, lo: Number(p.min.toFixed(6)), hi: Number(p.max.toFixed(6)) })
+        }
+      }
+      series.push({
+        nodeId,
+        name: node.name,
+        unit: node.unit ?? '',
+        lineId: node.lineId ?? lineId,
+        min: node.min ?? null,
+        max: node.max ?? null,
+        points,
+        ...(band ? { band } : {}),
+        truncated: pts.length >= QUERY_POINTS_PER_NODE,
+      })
+    }
+    // 默认作用域提示(与 daq_query 工具同口径):无显式打标过滤且产线有活动批次 → 结果只含活动批次样本
+    const result: DataQueryResult = {
+      lineId,
+      window: { fromMs, toMs, bucketMs, agg },
+      series,
+      cached: false,
+    }
+    cache.set(key, { at: Date.now(), result })
+    if (cache.size > CACHE_MAX) {
+      const oldest = cache.keys().next().value
+      if (oldest !== undefined) cache.delete(oldest)
+    }
+    void inp
+    return result
+  }
+  finally {
+    inflight.set(user.id, Math.max(0, (inflight.get(user.id) ?? 1) - 1))
+  }
+}
+
+/** 活动批次提示(前端时间选择器旁展示"当前查询默认限定活动批次") */
+export function activeRunHintOf(lineId: string): { runId?: string, recipeId?: string } {
+  const run = lineId ? getActiveLineRun(lineId) : null
+  return run ? { runId: run.runId, recipeId: run.recipeId } : {}
+}
+
+/** 缓存与配方名联查(前端图例需要配方上下文时用) */
+export function recipeNameOf(recipeId: string): string {
+  return getDcwController().listRecipes().find(r => r.id === recipeId)?.name ?? recipeId
+}