agentworkshop 0.8.6 → 0.8.8

package/server/services/workshop/daq/ingest-policy.ts

@@ -1,66 +1,80 @@
-/**
- * 数采推送(ingest)鉴权与回填窗策略 —— 纯函数单点(WP2)。
- *
- * 背景:ingest 历史行为是「配置了 AW_DAQ_INGEST_TOKEN 就校验头,否则退回仪表盘会话」,
- * 兜底路径**不查产线权限**且 `at` 允许 ±7 天回填 —— 任意注册用户可向任意启用节点
- * 注入(含回填)伪造样本,污染 AML 训练链。此处把判定收敛为可单测的纯函数:
- *  - 兜底路径必须过 requireLineMode(operate):无产线操控权 → 403;
- *  - 回填窗默认 ±1h(env AW_DAQ_INGEST_BACKFILL_MS 可调,上限仍 7 天);
- *  - 配置超宽(>1h)时启动期告警(安全开关回归可见性)。
- *
- * token 路径(AW_DAQ_INGEST_TOKEN)语义不变:全局推送凭据,用于边缘系统无会话接入。
- */
-
-export const DEFAULT_BACKFILL_MS = 3600_000
-export const MAX_BACKFILL_MS = 7 * 24 * 3600_000
-export const WIDE_WINDOW_THRESHOLD_MS = 3600_000
-
-/** 回填窗(ms):缺省 1h;env 可调,钳制到 [0, 7d] */
-export function ingestBackfillWindowMs(env: Record<string, string | undefined> = process.env): number {
-  const rawEnv = env.AW_DAQ_INGEST_BACKFILL_MS
-  if (rawEnv === undefined || String(rawEnv).trim() === '') return DEFAULT_BACKFILL_MS
-  const raw = Number(rawEnv)
-  if (!Number.isFinite(raw) || raw < 0) return DEFAULT_BACKFILL_MS
-  return Math.min(raw, MAX_BACKFILL_MS)
-}
-
-/** 是否处于「超宽回填窗」配置(安全开关打开态;启动/首请求告警) */
-export function isWideBackfillWindow(env: Record<string, string | undefined> = process.env): boolean {
-  return ingestBackfillWindowMs(env) > WIDE_WINDOW_THRESHOLD_MS
-}
-
-/** 时间点是否在允许窗内(旧口径:双向 ±window;新代码请用 ingestTimeVerdict) */
-export function withinBackfillWindow(atMs: number, now: number, windowMs: number): boolean {
-  return Number.isFinite(atMs) && Math.abs(atMs - now) <= windowMs
-}
-
-/** 未来时间戳容忍度(ms):缺省 60s;env AW_DAQ_INGEST_FUTURE_SKEW_MS 可调,钳 0..1h */
-export function ingestFutureSkewMs(env: Record<string, string | undefined> = process.env): number {
-  const raw = Number(env.AW_DAQ_INGEST_FUTURE_SKEW_MS)
-  if (!Number.isFinite(raw) || raw < 0) return 60_000
-  return Math.min(raw, 3600_000)
-}
-
-export type IngestTimeVerdict = 'ok' | 'future' | 'out-of-window'
-
-/**
- * 时间戳方向判定(2026-10-28 S12):
- *  - 未来超过 skew → future(必须拒绝;否则单条未来样本会把该节点 lastIngestAt 推到未来,
- *    之后所有实时样本被判 late 丢弃,最长持续到墙钟追上);
- *  - 过去超过回填窗 → out-of-window;
- *  - 其余 ok。
- */
-export function ingestTimeVerdict(atMs: number, now: number, windowMs: number, skewMs: number): IngestTimeVerdict {
-  if (!Number.isFinite(atMs)) return 'out-of-window'
-  if (atMs > now + skewMs) return 'future'
-  if (now - atMs > windowMs) return 'out-of-window'
-  return 'ok'
-}
-
-/** 推送鉴权模式判定(纯函数便于单测):token 已配置 → 校验头;未配置 → 会话+产线权限 */
-export function ingestAuthMode(input: { configuredToken?: string, providedToken?: string }): 'token' | 'token-mismatch' | 'session' {
-  if (input.configuredToken) {
-    return input.providedToken === input.configuredToken ? 'token' : 'token-mismatch'
-  }
-  return 'session'
-}
+/**
+ * 数采推送(ingest)鉴权与回填窗策略 —— 纯函数单点(WP2)。
+ *
+ * 背景:ingest 历史行为是「配置了 AW_DAQ_INGEST_TOKEN 就校验头,否则退回仪表盘会话」,
+ * 兜底路径**不查产线权限**且 `at` 允许 ±7 天回填 —— 任意注册用户可向任意启用节点
+ * 注入(含回填)伪造样本,污染 AML 训练链。此处把判定收敛为可单测的纯函数:
+ *  - 兜底路径必须过 requireLineMode(operate):无产线操控权 → 403;
+ *  - 回填窗默认 ±1h(env AW_DAQ_INGEST_BACKFILL_MS 可调,上限仍 7 天);
+ *  - 配置超宽(>1h)时启动期告警(安全开关回归可见性)。
+ *
+ * token 路径(AW_DAQ_INGEST_TOKEN)语义不变:全局推送凭据,用于边缘系统无会话接入。
+ */
+import { createHash, timingSafeEqual } from 'node:crypto'
+
+export const DEFAULT_BACKFILL_MS = 3600_000
+export const MAX_BACKFILL_MS = 7 * 24 * 3600_000
+export const WIDE_WINDOW_THRESHOLD_MS = 3600_000
+
+/** 回填窗(ms):缺省 1h;env 可调,钳制到 [0, 7d] */
+export function ingestBackfillWindowMs(env: Record<string, string | undefined> = process.env): number {
+  const rawEnv = env.AW_DAQ_INGEST_BACKFILL_MS
+  if (rawEnv === undefined || String(rawEnv).trim() === '') return DEFAULT_BACKFILL_MS
+  const raw = Number(rawEnv)
+  if (!Number.isFinite(raw) || raw < 0) return DEFAULT_BACKFILL_MS
+  return Math.min(raw, MAX_BACKFILL_MS)
+}
+
+/** 是否处于「超宽回填窗」配置(安全开关打开态;启动/首请求告警) */
+export function isWideBackfillWindow(env: Record<string, string | undefined> = process.env): boolean {
+  return ingestBackfillWindowMs(env) > WIDE_WINDOW_THRESHOLD_MS
+}
+
+/** 时间点是否在允许窗内(旧口径:双向 ±window;新代码请用 ingestTimeVerdict) */
+export function withinBackfillWindow(atMs: number, now: number, windowMs: number): boolean {
+  return Number.isFinite(atMs) && Math.abs(atMs - now) <= windowMs
+}
+
+/** 未来时间戳容忍度(ms):缺省 60s;env AW_DAQ_INGEST_FUTURE_SKEW_MS 可调,钳 0..1h */
+export function ingestFutureSkewMs(env: Record<string, string | undefined> = process.env): number {
+  const raw = Number(env.AW_DAQ_INGEST_FUTURE_SKEW_MS)
+  if (!Number.isFinite(raw) || raw < 0) return 60_000
+  return Math.min(raw, 3600_000)
+}
+
+export type IngestTimeVerdict = 'ok' | 'future' | 'out-of-window'
+
+/**
+ * 时间戳方向判定(2026-10-28 S12):
+ *  - 未来超过 skew → future(必须拒绝;否则单条未来样本会把该节点 lastIngestAt 推到未来,
+ *    之后所有实时样本被判 late 丢弃,最长持续到墙钟追上);
+ *  - 过去超过回填窗 → out-of-window;
+ *  - 其余 ok。
+ */
+export function ingestTimeVerdict(atMs: number, now: number, windowMs: number, skewMs: number): IngestTimeVerdict {
+  if (!Number.isFinite(atMs)) return 'out-of-window'
+  if (atMs > now + skewMs) return 'future'
+  if (now - atMs > windowMs) return 'out-of-window'
+  return 'ok'
+}
+
+/**
+ * 常量时间字符串比较。
+ * 直接 === 会按字节提前返回,攻击者可借响应时间逐字节猜 token。
+ * 先各自 sha256 再 timingSafeEqual:长度不同也不泄露长度信息。
+ */
+function constantTimeEqual(a: string, b: string): boolean {
+  const ha = createHash('sha256').update(a, 'utf8').digest()
+  const hb = createHash('sha256').update(b, 'utf8').digest()
+  return timingSafeEqual(ha, hb)
+}
+
+/** 推送鉴权模式判定(纯函数便于单测):token 已配置 → 校验头;未配置 → 会话+产线权限 */
+export function ingestAuthMode(input: { configuredToken?: string, providedToken?: string }): 'token' | 'token-mismatch' | 'session' {
+  if (input.configuredToken) {
+    const provided = input.providedToken ?? ''
+    if (!provided) return 'token-mismatch'
+    return constantTimeEqual(provided, input.configuredToken) ? 'token' : 'token-mismatch'
+  }
+  return 'session'
+}

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

@@ -1,88 +1,88 @@
-/**
- * DaqObjectStore 工厂 —— 配置驱动,MinIO 不可达自动降级本地磁盘。
- * 单例挂 globalThis;rebuildObjectStore() 支持重连时切回真实实例(与 tsdb 工厂同构)。
- */
-import { createLogger } from '../../logger'
-import { DiskObjectAdapter } from './disk.adapter'
-import { MinioObjectAdapter } from './minio.adapter'
-import type { DaqObjectStore } from './objectstore-port'
-
-const log = createLogger('daq.objectstore')
-
-interface DaqOsState { current?: DaqObjectStore }
-const g = globalThis as typeof globalThis & { __daqObjectStoreState?: DaqOsState }
-
-/**
- * 解析对象存储连接(DAQ_OS_URL 显式覆盖优先):
- *   http://accessKey:secretKey@host:port/bucket
- */
-export function parseObjectStoreUrl(url: string): { endPoint: string, port: number, accessKey: string, secretKey: string, bucket: string } | null {
-  try {
-    const u = new URL(url)
-    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null
-    return {
-      endPoint: u.hostname,
-      port: Number(u.port || (u.protocol === 'https:' ? 443 : 80)),
-      accessKey: decodeURIComponent(u.username || 'awshop'),
-      secretKey: decodeURIComponent(u.password || 'awshop'),
-      bucket: decodeURIComponent(u.pathname.replace(/^\//, '')) || 'daq',
-    }
-  }
-  catch {
-    return null
-  }
-}
-
-function makeFallback(reason: string): DaqObjectStore {
-  const dev = new DiskObjectAdapter()
-  void dev.init()
-  log.warn(`[daq-objectstore] ${reason} → 已降级本地磁盘(data/daq-objects/)`)
-  return dev
-}
-
-export function getObjectStore(): DaqObjectStore {
-  const st: DaqOsState = g.__daqObjectStoreState ??= {}
-  let cur = st.current
-  if (!cur) {
-    cur = new DiskObjectAdapter()
-    void cur.init()
-    log.info('[daq-objectstore] 本地磁盘对象存储就绪(data/daq-objects/)')
-    st.current = cur
-  }
-  return cur
-}
-
-/** 重连/初始装配:online 且 url 可解析 → MinIO(5×2.5s 重试扛容器初始化窗口);否则磁盘降级 */
-export async function rebuildObjectStore(online: boolean, url?: string | null): Promise<void> {
-  const st: DaqOsState = g.__daqObjectStoreState ??= {}
-  const swap = (next: DaqObjectStore): void => {
-    const old = st.current
-    st.current = next
-    void Promise.resolve(old?.close?.()).catch(() => {})
-  }
-  const parsed = url ? parseObjectStoreUrl(url) : null
-  if (!online || !parsed) {
-    if (st.current?.backend !== 'disk') swap(makeFallback('infra 判定离线或未配置'))
-    return
-  }
-  const adapter = new MinioObjectAdapter(parsed)
-  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(() => {})
-    swap(makeFallback(lastErr instanceof Error ? lastErr.message : String(lastErr)))
-    return
-  }
-  swap(adapter)
-  log.info(`[daq-objectstore] MinIO 就绪(${parsed.endPoint}:${parsed.port}/${parsed.bucket})`)
-}
+/**
+ * DaqObjectStore 工厂 —— 配置驱动,MinIO 不可达自动降级本地磁盘。
+ * 单例挂 globalThis;rebuildObjectStore() 支持重连时切回真实实例(与 tsdb 工厂同构)。
+ */
+import { createLogger } from '../../logger'
+import { DiskObjectAdapter } from './disk.adapter'
+import { MinioObjectAdapter } from './minio.adapter'
+import type { DaqObjectStore } from './objectstore-port'
+
+const log = createLogger('daq.objectstore')
+
+interface DaqOsState { current?: DaqObjectStore }
+const g = globalThis as typeof globalThis & { __daqObjectStoreState?: DaqOsState }
+
+/**
+ * 解析对象存储连接(DAQ_OS_URL 显式覆盖优先):
+ *   http://accessKey:secretKey@host:port/bucket
+ */
+export function parseObjectStoreUrl(url: string): { endPoint: string, port: number, accessKey: string, secretKey: string, bucket: string } | null {
+  try {
+    const u = new URL(url)
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null
+    return {
+      endPoint: u.hostname,
+      port: Number(u.port || (u.protocol === 'https:' ? 443 : 80)),
+      accessKey: decodeURIComponent(u.username || ''),
+      secretKey: decodeURIComponent(u.password || 'awshop'),
+      bucket: decodeURIComponent(u.pathname.replace(/^\//, '')) || 'daq',
+    }
+  }
+  catch {
+    return null
+  }
+}
+
+function makeFallback(reason: string): DaqObjectStore {
+  const dev = new DiskObjectAdapter()
+  void dev.init()
+  log.warn(`[daq-objectstore] ${reason} → 已降级本地磁盘(data/daq-objects/)`)
+  return dev
+}
+
+export function getObjectStore(): DaqObjectStore {
+  const st: DaqOsState = g.__daqObjectStoreState ??= {}
+  let cur = st.current
+  if (!cur) {
+    cur = new DiskObjectAdapter()
+    void cur.init()
+    log.info('[daq-objectstore] 本地磁盘对象存储就绪(data/daq-objects/)')
+    st.current = cur
+  }
+  return cur
+}
+
+/** 重连/初始装配:online 且 url 可解析 → MinIO(5×2.5s 重试扛容器初始化窗口);否则磁盘降级 */
+export async function rebuildObjectStore(online: boolean, url?: string | null): Promise<void> {
+  const st: DaqOsState = g.__daqObjectStoreState ??= {}
+  const swap = (next: DaqObjectStore): void => {
+    const old = st.current
+    st.current = next
+    void Promise.resolve(old?.close?.()).catch(() => {})
+  }
+  const parsed = url ? parseObjectStoreUrl(url) : null
+  if (!online || !parsed) {
+    if (st.current?.backend !== 'disk') swap(makeFallback('infra 判定离线或未配置'))
+    return
+  }
+  const adapter = new MinioObjectAdapter(parsed)
+  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(() => {})
+    swap(makeFallback(lastErr instanceof Error ? lastErr.message : String(lastErr)))
+    return
+  }
+  swap(adapter)
+  log.info(`[daq-objectstore] MinIO 就绪(${parsed.endPoint}:${parsed.port}/${parsed.bucket})`)
+}

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

@@ -1,18 +1,39 @@
 /**
  * TsdbPort 工厂 —— 配置驱动(daqInfraUrls 提供真实 Timescale URL),降级 SQLite 仿真。
  * 单例挂 globalThis;rebuildTsdb() 支持重连时从降级实例切回真实实例。
+ *
+ * 历史数据治理旁路(TimescaleRollupStore):
+ *  - 与适配器共用同一 DAQ_TSDB_URL,负责逐产线保留期、1m/1h 聚合、跨保留期历史查询;
+ *  - 适配器保持"热路径只读写原始表"的职责,两者故障域隔离;
+ *  - 对外统一由本模块的 tsdbQueryHistory / tsdbLayoutInfo / tsdbRunRollup 等门面暴露,
+ *    调用方不需要知道后端是否支持 rollup。
  */
 import { createLogger } from '../../logger'
 import { SqliteTimeSeriesAdapter } from './sqlite.adapter'
 import { TimescaleAdapter } from './timescale.adapter'
-import type { TsdbPort } from './tsdb-port'
+import { TimescaleRollupStore } from './timescale-rollup'
+import type {
+  TsdbHistoryQuery,
+  TsdbHistoryResult,
+  TsdbLayoutInfo,
+  TsdbPort,
+  TsdbRetentionInfo,
+  TsdbRetentionPatch,
+  TsdbRollupResult,
+} from './tsdb-port'
+import { daqRuntimeSettings } from '../../settings'
+import { rawCutoffMs } from './retention'
 
 const log = createLogger('daq.tsdb')
 
 interface DaqTsdbState { current?: TsdbPort, initError?: unknown }
-const g = globalThis as typeof globalThis & { __daqTsdbState?: DaqTsdbState }
+const g = globalThis as typeof globalThis & {
+  __daqTsdbState?: DaqTsdbState
+  __daqRollupStore?: TimescaleRollupStore | null
+}
 
 function makeFallback(reason: string): TsdbPort {
+  void detachRollupStore()
   const dev = new SqliteTimeSeriesAdapter()
   // init 失败不再静默:读路径有 ensureDb 惰性自愈兜底,但这里必须留下证据
   dev.init().catch(err => log.error(`[daq-tsdb] SQLite 降级实例初始化失败(读路径将自愈重试):`, err instanceof Error ? err.message : err))
@@ -35,13 +56,16 @@ export const tsdbReady: Promise<void> = (() => {
       const adapter = new TimescaleAdapter(url)
       st.current = adapter
       void adapter.init().then(
-        () => log.info('[daq-tsdb] TimescaleDB 就绪:', url.replace(/\/\/[^@]*@/, '//***@')),
+        () => {
+          log.info('[daq-tsdb] TimescaleDB 就绪:', url.replace(/\/\/[^@]*@/, '//***@'))
+          return attachRollupStore(url)
+        },
         (err) => {
           if (g.__daqTsdbState?.current === adapter) {
             g.__daqTsdbState.current = makeFallback(err instanceof Error ? err.message : String(err))
           }
         },
-      )
+      ).catch(err => log.error('[daq-tsdb] 历史治理旁路装配失败(采集不受影响):', err instanceof Error ? err.message : err))
     }
   }
   return Promise.resolve()
@@ -69,6 +93,7 @@ export async function rebuildTsdb(online: boolean, url?: string | null): Promise
     void Promise.resolve(old?.close?.()).catch(() => {})
   }
   if (!online || !url) {
+    await detachRollupStore()
     if (st.current?.backend !== 'sqlite-emulated') {
       swap(makeFallback('infra 判定离线'))
     }
@@ -93,5 +118,133 @@ export async function rebuildTsdb(online: boolean, url?: string | null): Promise
     throw lastErr
   }
   swap(adapter)
+  await attachRollupStore(url)
   log.info('[daq-tsdb] TimescaleDB 就绪:', url.replace(/\/\/[^@]*@/, '//***@'))
 }
+
+async function attachRollupStore(url: string): Promise<void> {
+  let s: ReturnType<typeof daqRuntimeSettings>
+  try {
+    s = daqRuntimeSettings()
+  }
+  catch (err) {
+    log.error('[daq-tsdb] 读取保留期配置失败,跳过历史治理旁路:', err instanceof Error ? err.message : err)
+    return
+  }
+  const store = new TimescaleRollupStore(url, {
+    retentionH: s.tsRetentionH,
+    frameRetentionH: s.frameRetentionH,
+    minuteRetentionH: s.rollup.minuteRetentionH,
+    hourRetentionH: s.rollup.hourRetentionH,
+    enabled: s.rollup.enabled,
+    lagMs: s.rollup.lagMs,
+    windowMs: s.rollup.windowMs,
+    maxWindowsPerRun: s.rollup.maxWindowsPerRun,
+    poolMax: Math.min(4, s.timescale.poolMax),
+  })
+  try {
+    await store.init()
+  }
+  catch (err) {
+    // 旁路失败不阻断采集(原始样本仍可写/可查);但要留下证据,并由运维面暴露
+    log.error('[daq-tsdb] 保留期/rollup 旁路初始化失败(采集不受影响):', err instanceof Error ? err.message : err)
+    await store.close().catch(() => {})
+    g.__daqRollupStore = null
+    return
+  }
+  const old = g.__daqRollupStore
+  g.__daqRollupStore = store
+  await Promise.resolve(old?.close?.()).catch(() => {})
+}
+
+async function detachRollupStore(): Promise<void> {
+  const old = g.__daqRollupStore
+  g.__daqRollupStore = null
+  await Promise.resolve(old?.close?.()).catch(() => {})
+}
+
+export function getRollupStore(): TimescaleRollupStore | null {
+  return g.__daqRollupStore ?? null
+}
+
+/**
+ * 跨保留期历史查询(统一门面):
+ *  - 适配器自带 queryHistory → 用它;
+ *  - Timescale 旁路已装配 → 1m/1h 聚合 + 原始段拼接;
+ *  - SQLite 仿真 → 原始桶查询,并在 coverage 里显式说明"无历史聚合"。
+ * 起止时间必填,调用方(Actor/页面)不得依赖隐式默认窗口。
+ */
+export async function tsdbQueryHistory(nodeId: string, q: TsdbHistoryQuery): Promise<TsdbHistoryResult> {
+  const tsdb = getTsdb()
+  if (typeof tsdb.queryHistory === 'function') return tsdb.queryHistory(nodeId, q)
+  const store = getRollupStore()
+  if (store) return store.queryHistory(nodeId, q)
+  const limit = Math.max(1, Math.min(q.limit ?? 2000, 1_000_000))
+  const points = await tsdb.query(nodeId, { fromMs: q.fromMs, toMs: q.toMs, bucketMs: q.bucketMs, limit })
+  const rawRetentionH = daqRuntimeSettings().tsRetentionH
+  const cutoff = rawCutoffMs(Date.now(), rawRetentionH)
+  return {
+    points,
+    resolution: 'raw',
+    coverage: {
+      requestedFromMs: q.fromMs,
+      requestedToMs: q.toMs,
+      availableFromMs: points[0]?.at ?? null,
+      rawFromMs: cutoff,
+      truncated: points.length >= limit,
+      note: q.fromMs < cutoff
+        ? `窗口起点早于原始样本保留期(${rawRetentionH}h);当前后端没有历史聚合,该段不可查`
+        : '原始样本窗口',
+    },
+  }
+}
+
+export function tsdbRetentionInfo(): TsdbRetentionInfo {
+  const tsdb = getTsdb()
+  if (typeof tsdb.retentionInfo === 'function') return tsdb.retentionInfo()
+  const store = getRollupStore()
+  if (store) return store.retentionInfo()
+  return { rawRetentionH: daqRuntimeSettings().tsRetentionH, rollupEnabled: false, rollupResolutions: [] }
+}
+
+export async function tsdbLayoutInfo(): Promise<TsdbLayoutInfo> {
+  const tsdb = getTsdb()
+  if (typeof tsdb.layoutInfo === 'function') return tsdb.layoutInfo()
+  const store = getRollupStore()
+  if (store) return store.layoutInfo()
+  const s = daqRuntimeSettings()
+  return {
+    backend: tsdb.backend,
+    layout: 'single',
+    rawRetentionH: s.tsRetentionH,
+    frameRetentionH: s.frameRetentionH,
+    rollup: { enabled: false, minuteRetentionH: s.rollup.minuteRetentionH, hourRetentionH: s.rollup.hourRetentionH, watermarks: {} },
+    lines: [],
+    legacy: null,
+  }
+}
+
+/** 手动触发一轮增量聚合(插件定时器之外的运维入口) */
+export async function tsdbRunRollup(): Promise<TsdbRollupResult | null> {
+  const store = getRollupStore()
+  if (store) return store.runRollup()
+  const tsdb = getTsdb()
+  if (typeof tsdb.runRollup === 'function') return tsdb.runRollup()
+  return null
+}
+
+export async function tsdbSetLineRetention(lineId: string, patch: TsdbRetentionPatch): Promise<void> {
+  const store = getRollupStore()
+  if (store) return store.setLineRetention(lineId, patch)
+  const tsdb = getTsdb()
+  if (typeof tsdb.setLineRetention === 'function') return tsdb.setLineRetention(lineId, patch)
+  throw new Error('当前后端不支持逐产线保留期(仅 Timescale 生产后端可用)')
+}
+
+/** 立即执行一轮清理(样本按线 + 聚合按分辨率) */
+export async function tsdbSweepAll(): Promise<void> {
+  const tsdb = getTsdb()
+  if (typeof tsdb.sweepNow === 'function') await tsdb.sweepNow()
+  const store = getRollupStore()
+  if (store) await store.sweepNow()
+}

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

@@ -0,0 +1,142 @@
+/**
+ * 分层保留 + 历史查询路由(纯函数,可单测)。
+ *
+ * 生产语义:
+ *  - 原始样本(raw)保留 `rawRetentionH`(默认 30 天,按产线可覆写);
+ *  - 1 分钟聚合(rollup 60s)保留 `minuteRetentionH`(默认 1 年);
+ *  - 1 小时聚合(rollup 3600s)默认**永久保留**(0 = 不清理)。
+ *  → 超过原始保留期的数据不是"被删掉",而是以更低分辨率继续可查;
+ *    真正决定"哪些还能查"的是 `planHistoryQuery()` 的返回,而不是静默返回空数组。
+ *
+ * 为什么不是 Timescale 的 continuous aggregate:
+ *  按产线动态建表意味着每条线都要建 CAGG + refresh policy(关系数×3),
+ *  且 CAGG 压缩/刷新能力随 Timescale 版本漂移。这里用应用侧幂等 rollup
+ *  (`ON CONFLICT DO NOTHING` + 水位),两后端同构、可回放、可单测,
+ *  代价是聚合窗口滞后一个 `lagMs`(默认 5 分钟,远大于采集乱序窗口)。
+ */
+
+export const MINUTE_ROLLUP_MS = 60_000
+export const HOUR_ROLLUP_MS = 3_600_000
+/** 保留期硬上限(10 年;0 仅对 hourRetentionH 合法 = 永久) */
+export const RETENTION_MAX_H = 87_600
+
+export interface RetentionPolicy {
+  /** 原始样本保留小时数(≥1) */
+  rawRetentionH: number
+  /** 1 分钟聚合保留小时数(≥1) */
+  minuteRetentionH: number
+  /** 1 小时聚合保留小时数(0 = 永久) */
+  hourRetentionH: number
+}
+
+export function clampRetentionH(v: unknown, dflt: number, allowZero = false): number {
+  const n = Number(v)
+  if (!Number.isFinite(n)) return dflt
+  if (allowZero && n === 0) return 0
+  return Math.max(1, Math.min(Math.round(n), RETENTION_MAX_H))
+}
+
+export function normalizeRetention(patch: Partial<RetentionPolicy> | null | undefined, base: RetentionPolicy): RetentionPolicy {
+  const p = patch ?? {}
+  return {
+    rawRetentionH: clampRetentionH(p.rawRetentionH, base.rawRetentionH),
+    minuteRetentionH: clampRetentionH(p.minuteRetentionH, base.minuteRetentionH),
+    hourRetentionH: clampRetentionH(p.hourRetentionH, base.hourRetentionH, true),
+  }
+}
+
+export function rawCutoffMs(nowMs: number, rawRetentionH: number): number {
+  return nowMs - Math.max(1, rawRetentionH) * 3_600_000
+}
+
+/** 某分辨率最早可查时刻(null = 永久) */
+export function retentionCutoffMs(nowMs: number, retentionH: number): number | null {
+  return retentionH > 0 ? nowMs - retentionH * 3_600_000 : null
+}
+
+export interface HistoryPlanInput {
+  fromMs: number
+  toMs: number
+  bucketMs: number
+  nowMs: number
+  policy: Pick<RetentionPolicy, 'rawRetentionH' | 'hourRetentionH'>
+  /** 回滚聚合是否可用(Timescale per-line 且 rollup 已建表) */
+  hasRollup: boolean
+}
+
+export interface HistoryPlan {
+  /** 主体数据源 */
+  source: 'raw' | 'minute' | 'hour'
+  /** 窗口跨越原始保留边界:老段走 rollup、新段走 raw */
+  mixed: boolean
+  /** 选中的聚合分辨率(ms);raw 时为 null */
+  rollupResMs: number | null
+  /** rollup 段覆盖 [rollupFromMs, rollupToMs) */
+  rollupFromMs: number | null
+  rollupToMs: number | null
+  /** 实际生效的桶宽(≥100ms) */
+  bucketMs: number
+  /** 给调用方/Actor 的可见说明(不得静默降级) */
+  note: string
+}
+
+/**
+ * 历史查询路由:
+ *  - 桶宽 < 1min 或窗口完全在原始保留期内 → raw(精确);
+ *  - 窗口早于原始保留期 → 走 rollup;桶宽 ≥1h 优先 1h 聚合,否则 1m;
+ *  - 跨边界 → mixed(老段 rollup、新段 raw,按桶起点合并,raw 优先)。
+ */
+export function planHistoryQuery(input: HistoryPlanInput): HistoryPlan {
+  const nowMs = Number.isFinite(input.nowMs) ? input.nowMs : Date.now()
+  const bucketMs = Math.max(100, Math.round(Number(input.bucketMs) || 0) || MINUTE_ROLLUP_MS)
+  const fromMs = Math.min(Number(input.fromMs), Number(input.toMs))
+  const toMs = Math.max(Number(input.fromMs), Number(input.toMs))
+  const rawFrom = rawCutoffMs(nowMs, input.policy.rawRetentionH)
+  const rawOnly: HistoryPlan = {
+    source: 'raw',
+    mixed: false,
+    rollupResMs: null,
+    rollupFromMs: null,
+    rollupToMs: null,
+    bucketMs,
+    note: '原始样本窗口',
+  }
+  if (!input.hasRollup || bucketMs < MINUTE_ROLLUP_MS || fromMs >= rawFrom) return rawOnly
+
+  // 0 = 永久保留;>0 时只有窗口落在小时聚合保留期内才选它(否则 1m 仍有更细数据)
+  const hourAvailable = input.policy.hourRetentionH === 0
+    || fromMs >= nowMs - input.policy.hourRetentionH * 3_600_000
+  const useHour = bucketMs >= HOUR_ROLLUP_MS && hourAvailable
+  const res = useHour ? HOUR_ROLLUP_MS : MINUTE_ROLLUP_MS
+  const mixed = toMs > rawFrom
+  const label = useHour ? '1 小时聚合' : '1 分钟聚合'
+  return {
+    source: useHour ? 'hour' : 'minute',
+    mixed,
+    rollupResMs: res,
+    rollupFromMs: fromMs,
+    rollupToMs: mixed ? rawFrom : toMs,
+    bucketMs,
+    note: mixed
+      ? `窗口跨越原始样本保留边界:${new Date(rawFrom).toISOString()} 之前用 ${label},之后用原始样本`
+      : `窗口早于原始样本保留期,使用 ${label}历史数据(降采样分辨率 ${res}ms)`,
+  }
+}
+
+/**
+ * 合并 rollup 段与 raw 段:按桶起点升序,同 `at` 以 raw 为准
+ * (raw 是精确值,rollup 只是聚合近似);超过 limit 时保留**最新**的 limit 个并标记截断。
+ */
+export function mergeHistoryPoints(
+  rollupPoints: Array<{ at: number, avg?: number, min?: number, max?: number, cnt?: number, value?: number }>,
+  rawPoints: Array<{ at: number, avg?: number, min?: number, max?: number, cnt?: number, value?: number }>,
+  limit: number,
+): { points: Array<{ at: number, avg?: number, min?: number, max?: number, cnt?: number, value?: number }>, truncated: boolean } {
+  const byAt = new Map<number, { at: number, avg?: number, min?: number, max?: number, cnt?: number, value?: number }>()
+  for (const p of rollupPoints) byAt.set(p.at, p)
+  for (const p of rawPoints) byAt.set(p.at, p)
+  const all = [...byAt.values()].sort((a, b) => a.at - b.at)
+  const cap = Math.max(1, Math.round(limit) || all.length)
+  if (all.length <= cap) return { points: all, truncated: false }
+  return { points: all.slice(all.length - cap), truncated: true }
+}