agentworkshop 0.2.1

package/server/services/workshop/daq/daq-node.repo.ts

@@ -0,0 +1,96 @@
+/**
+ * DaqNode 持久化仓库 —— 对象快照落盘(server/data/daqs.json),与 DeviceTwinRepo 同风格。
+ * 进程内缓存 + 防抖写盘(采样只改 value/state,若逐帧同步落盘会 fs 抖动;
+ * 配置类变更立即刷盘,读数变更走 5s 防抖)。
+ */
+
+import { createLogger } from '../logger'
+import fs from 'node:fs'
+import path from 'node:path'
+import { DaqNode } from './daq-node'
+
+const log = createLogger('daq.node-repo')
+
+const DB_PATH = process.cwd().endsWith('server')
+  ? 'data/daqs.json'
+  : path.join(process.cwd(), 'server', 'data', 'daqs.json')
+
+function load(): DaqNode[] {
+  try {
+    const raw = fs.readFileSync(DB_PATH, 'utf-8')
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed.map(r => DaqNode.fromRow(r as Record<string, unknown>)) : []
+  }
+  catch {
+    return []
+  }
+}
+
+class DaqNodeRepo {
+  private list: DaqNode[]
+  private flushTimer: NodeJS.Timeout | null = null
+
+  constructor() {
+    this.list = load()
+  }
+
+  /** 磁盘 ↔ 内存同构:全量对象快照(启动恢复 / 诊断导出) */
+  snapshot(): DaqNode[] {
+    return [...this.list]
+  }
+
+  all(): DaqNode[] {
+    return this.list
+  }
+
+  byId(id: string): DaqNode | undefined {
+    return this.list.find(n => n.id === id)
+  }
+
+  insert(node: DaqNode): void {
+    this.list.push(node)
+    this.flushNow()
+  }
+
+  remove(id: string): boolean {
+    const before = this.list.length
+    this.list = this.list.filter(n => n.id !== id)
+    if (this.list.length !== before) {
+      this.flushNow()
+      return true
+    }
+    return false
+  }
+
+  /** 立即落盘(配置类 CRUD;同步写,量小无碍) */
+  flushNow(): void {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer)
+      this.flushTimer = null
+    }
+    try {
+      fs.mkdirSync(path.dirname(DB_PATH), { recursive: true })
+      fs.writeFileSync(DB_PATH, JSON.stringify(this.list.map(n => n.toRow()), null, 2), 'utf-8')
+    }
+    catch (err) {
+      log.error('[daq] 快照落盘失败:', err)
+    }
+  }
+
+  /** 读数落盘防抖(采样循环每帧调用;5s 合并一次磁盘写) */
+  flushDebounced(ms = 5000): void {
+    if (this.flushTimer) return
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null
+      this.flushNow()
+    }, ms)
+    this.flushTimer.unref?.()
+  }
+}
+
+let singleton: DaqNodeRepo | null = null
+
+export function getDaqNodeRepo(): DaqNodeRepo {
+  singleton ??= new DaqNodeRepo()
+  return singleton
+}

package/server/services/workshop/daq/daq-node.ts

@@ -0,0 +1,247 @@
+/**
+ * DaqNode —— 数据采集节点领域对象(class 封装)。
+ *
+ * 一个实例 = 一条物理采集通道:模板域(量程/单位/精度)+ 运行配置(驱动/周期/启停)
+ * + 绑定关系(deviceBindingId → DeviceTwin)+ 实时状态(value/state/lastAt)。
+ * 序列化经 toRow/fromRow 与持久化仓库对接(daqs.json,对象快照落盘);
+ * 采样历史仅驻内存(环形缓冲),不进磁盘快照 —— 磁盘只存"配置 + 最近一次读数"。
+ */
+
+import { daqKeyFromRef, type DaqDriverKind, type DaqNodeState, type DaqNodeView, type DataTransform } from '../../../../shared/daq-protocol'
+import { findDaqTemplate } from './daq-templates'
+
+/** 采样历史环形缓冲长度(前端趋势图/火花线消费;1s 周期 ≈ 5 分钟窗口) */
+export const DAQ_HIST_CAP = 60
+
+interface DaqNodeOptions {
+  id: string
+  templateRef: string
+  name?: string
+  driver?: DaqDriverKind
+  enabled?: boolean
+  intervalMs?: number | null
+  /** WS 实时下发间隔(null=跟随全局;0=每帧) */
+  publishIntervalMs?: number | null
+  unit?: string
+  decimals?: number
+  min?: number
+  max?: number
+  warnLow?: number | null
+  warnHigh?: number | null
+  deviceBindingId?: string | null
+  /** 数据语义标定钩子(decoder:采集值 → 物理值) */
+  transform?: DataTransform
+  posX?: number
+  posZ?: number
+  /** 所属产线('' = 未分配;采集门控/场景光晕按产线隔离) */
+  lineId?: string
+  /** 节点级采集语义备注(覆盖模板 semantics;注入 Agent 上下文) */
+  semantics?: string
+  /** 驱动连接参数(modbus-tcp/opcua 协议参数;mock 空) */
+  driverConfig?: Record<string, string | number | boolean>
+  createdAt?: string
+}
+
+export class DaqNode {
+  readonly id: string
+  /** 模板引用(daq-<key> 形态;域缺省来源) */
+  templateRef: string
+  name: string
+  driver: DaqDriverKind
+  enabled: boolean
+  /** null = 跟随 controller 全局周期 */
+  intervalMs: number | null
+  /** WS 实时下发(消费)间隔;null = 跟随全局,0 = 每帧(随采样节拍) */
+  publishIntervalMs: number | null
+  unit: string
+  decimals: number
+  min: number
+  max: number
+  warnLow: number | null
+  warnHigh: number | null
+  deviceBindingId: string | null
+  driverConfig: Record<string, string | number | boolean>
+  transform?: DataTransform
+  posX?: number
+  posZ?: number
+  /** 所属产线('' = 未分配;采集门控/场景光晕按产线隔离) */
+  lineId = ''
+  /** 节点级采集语义备注(覆盖模板 semantics) */
+  semantics?: string
+  value: number | null
+  state: DaqNodeState = 'offline'
+  lastAt: string | null = null
+  /** 去抖候选态(连续 3 帧一致才切换;alarm/offline 立即生效,安全优先) */
+  private stateCand: DaqNodeState | null = null
+  private stateCandN = 0
+  readonly createdAt: string
+
+  constructor(o: DaqNodeOptions) {
+    const tpl = findDaqTemplate(daqKeyFromRef(o.templateRef))
+    this.id = o.id
+    this.templateRef = o.templateRef
+    this.name = o.name ?? (tpl ? `${tpl.name}` : '数采节点')
+    this.driver = o.driver ?? 'mock'
+    this.enabled = o.enabled ?? true
+    this.intervalMs = o.intervalMs ?? null
+    this.publishIntervalMs = o.publishIntervalMs ?? null
+    this.unit = o.unit ?? tpl?.unit ?? ''
+    this.decimals = o.decimals ?? tpl?.decimals ?? 2
+    this.min = o.min ?? tpl?.min ?? 0
+    this.max = o.max ?? tpl?.max ?? 100
+    // 预警带缺省 = 量程两端各收 8%(越带即 warn,越硬限即 alarm)
+    this.warnLow = o.warnLow !== undefined ? o.warnLow : this.min !== undefined && tpl ? +(this.min + (this.max - this.min) * 0.08).toFixed(this.decimals) : null
+    this.warnHigh = o.warnHigh !== undefined ? o.warnHigh : tpl ? +(this.max - (this.max - this.min) * 0.08).toFixed(this.decimals) : null
+    this.deviceBindingId = o.deviceBindingId ?? null
+    this.driverConfig = o.driverConfig ?? {}
+    if (o.transform) this.transform = o.transform
+    if (o.posX !== undefined) this.posX = o.posX
+    if (o.posZ !== undefined) this.posZ = o.posZ
+    this.lineId = o.lineId ?? ''
+    this.semantics = o.semantics
+    this.value = null
+    this.createdAt = o.createdAt ?? new Date().toISOString()
+  }
+
+  /** 模板 key(`daq-<key>` 中提取;未知模板返回原 ref) */
+  get templateKey(): string {
+    return daqKeyFromRef(this.templateRef)
+  }
+
+  /** 有效采样周期(ms):节点覆盖 > 全局缺省 */
+  effectiveInterval(defaultIntervalMs: number): number {
+    return Math.max(120, this.intervalMs ?? defaultIntervalMs)
+  }
+
+  /** 越限派生:硬限外 = alarm;预警带 2% 滞回(退出需越过内缩边界,防临界抖动)。
+   *  注意:滞回依赖当前 state,故仅在 applyReading 的稳态链路中语义正确。 */
+  deriveState(v: number): DaqNodeState {
+    if (!this.enabled) return 'offline'
+    if (v < this.min || v > this.max) return 'alarm'
+    const margin = (this.max - this.min) * 0.02
+    if (this.state === 'warn') {
+      // 已在预警:回到"内缩边界内"才算恢复
+      if (this.warnLow != null && v < this.warnLow + margin) return 'warn'
+      if (this.warnHigh != null && v > this.warnHigh - margin) return 'warn'
+      return 'ok'
+    }
+    if ((this.warnLow != null && v < this.warnLow) || (this.warnHigh != null && v > this.warnHigh)) return 'warn'
+    return 'ok'
+  }
+
+  /** 记录一次采样(controller 采样循环调用):去抖 + 滞回后落状态 */
+  applyReading(v: number, at: string): void {
+    this.value = v
+    const raw = this.deriveState(v)
+    // alarm/offline 立即切换(安全事件不等去抖);ok↔warn 需连续 3 帧一致
+    if (raw === 'alarm' || raw === 'offline' || raw === this.state) {
+      this.state = raw
+      this.stateCand = null
+      this.stateCandN = 0
+    }
+    else if (raw === this.stateCand) {
+      if (++this.stateCandN >= 3) {
+        this.state = raw
+        this.stateCand = null
+        this.stateCandN = 0
+      }
+    }
+    else {
+      this.stateCand = raw
+      this.stateCandN = 1
+    }
+    this.lastAt = at
+  }
+
+  /** 对象快照(磁盘形态:配置 + 最近读数;无运行时缓冲) */
+  toRow(): Record<string, unknown> {
+    return {
+      id: this.id,
+      templateRef: this.templateRef,
+      name: this.name,
+      driver: this.driver,
+      enabled: this.enabled,
+      intervalMs: this.intervalMs,
+      publishIntervalMs: this.publishIntervalMs,
+      unit: this.unit,
+      decimals: this.decimals,
+      min: this.min,
+      max: this.max,
+      warnLow: this.warnLow,
+      warnHigh: this.warnHigh,
+      deviceBindingId: this.deviceBindingId,
+      driverConfig: this.driverConfig,
+      transform: this.transform,
+      posX: this.posX,
+      posZ: this.posZ,
+      lineId: this.lineId,
+      semantics: this.semantics,
+      value: this.value,
+      state: this.state,
+      lastAt: this.lastAt,
+      createdAt: this.createdAt,
+    }
+  }
+
+  static fromRow(row: Record<string, unknown>): DaqNode {
+    const node = new DaqNode({
+      id: String(row.id),
+      templateRef: String(row.templateRef ?? ''),
+      name: row.name != null ? String(row.name) : undefined,
+      driver: (row.driver as DaqDriverKind) ?? undefined,
+      enabled: row.enabled === undefined ? undefined : Boolean(row.enabled),
+      intervalMs: row.intervalMs == null ? null : Number(row.intervalMs),
+      publishIntervalMs: row.publishIntervalMs == null ? null : Number(row.publishIntervalMs),
+      unit: row.unit != null ? String(row.unit) : undefined,
+      decimals: row.decimals != null ? Number(row.decimals) : undefined,
+      min: row.min != null ? Number(row.min) : undefined,
+      max: row.max != null ? Number(row.max) : undefined,
+      warnLow: row.warnLow === undefined ? undefined : (row.warnLow == null ? null : Number(row.warnLow)),
+      warnHigh: row.warnHigh === undefined ? undefined : (row.warnHigh == null ? null : Number(row.warnHigh)),
+      deviceBindingId: row.deviceBindingId === undefined ? undefined : (row.deviceBindingId == null ? null : String(row.deviceBindingId)),
+      driverConfig: (row.driverConfig as Record<string, string | number | boolean>) ?? {},
+      transform: (row.transform as DataTransform | undefined) ?? undefined,
+      posX: row.posX == null ? undefined : Number(row.posX),
+      posZ: row.posZ == null ? undefined : Number(row.posZ),
+      lineId: row.lineId == null ? '' : String(row.lineId),
+      semantics: row.semantics == null ? undefined : String(row.semantics),
+      createdAt: row.createdAt != null ? String(row.createdAt) : undefined,
+    })
+    if (row.value != null && !Number.isNaN(Number(row.value))) {
+      node.value = Number(row.value)
+      node.state = node.deriveState(node.value)
+    }
+    if (row.lastAt != null) node.lastAt = String(row.lastAt)
+    return node
+  }
+
+  /** AEP/REST 投影(view 同构载荷) */
+  toView(): DaqNodeView {
+    return {
+      id: this.id,
+      templateRef: this.templateRef,
+      name: this.name,
+      driver: this.driver,
+      enabled: this.enabled,
+      intervalMs: this.intervalMs,
+      publishIntervalMs: this.publishIntervalMs,
+      unit: this.unit,
+      decimals: this.decimals,
+      min: this.min,
+      max: this.max,
+      warnLow: this.warnLow,
+      warnHigh: this.warnHigh,
+      deviceBindingId: this.deviceBindingId,
+      driverConfig: this.driverConfig,
+      transform: this.transform,
+      posX: this.posX,
+      posZ: this.posZ,
+      lineId: this.lineId,
+      semantics: this.semantics,
+      value: this.value,
+      state: this.state,
+      lastAt: this.lastAt,
+      createdAt: this.createdAt,
+    }
+  }
+}

package/server/services/workshop/daq/daq-runtime.ts

@@ -0,0 +1,168 @@
+/**
+ * DaqNodeRuntime —— 单节点边缘运行时(每个数采节点独立实例化,元数据驱动)。
+ *
+ * 概念模型:节点 = 边缘计算节点,控制器(DaqController)= 总体网关。
+ * 运行时持有该节点全部私有节拍状态(采样时点/下发时点/乱序游标/故障节流/在飞互斥),
+ * 由节点元数据驱动:
+ *   - intervalMs        采集入库节拍(null = 跟随网关缺省;每个采样必入库)
+ *   - publishIntervalMs WS 实时下发节拍(null = 跟随网关缺省;0 = 每帧随采样)
+ * 节拍状态独立 → 单节点慢驱动/停用/重配不波及邻居;网关只做统一调度与管线汇聚。
+ */
+
+import { applyTransform } from '../../../../shared/daq-protocol'
+import type { DaqNode } from './daq-node'
+import type { DaqSampleEnvelope } from './bus/queue-port'
+
+/** 驱动故障广播节流(ms;每运行时独立计时) */
+const ERR_THROTTLE_MS = 30_000
+
+/** WS 下发间隔上限(与采样周期同界,防误配) */
+export const PUBLISH_INTERVAL_MAX = 60_000
+
+/** 网关注入的服务面(运行时只依赖此接口;管线汇聚在网关侧) */
+export interface DaqRuntimeHost {
+  /** 网关全局缺省(节点元数据为 null 时回退) */
+  defaults(): { intervalMs: number, publishIntervalMs: number }
+  /** 生产面:驱动采样一次(网关实现协议解析与模板域) */
+  sample(node: DaqNode, now: number): Promise<number | null>
+  /** 生产面:样本帧入队 */
+  publishSample(env: DaqSampleEnvelope): void
+  /**
+   * 消费面:样本入网关管线(状态派生已完成)。
+   * allowPublish = 本帧通过该节点的 WS 下发节拍门控(入库/回写不受门控,每帧必达)。
+   */
+  ingest(node: DaqNode, env: DaqSampleEnvelope, allowPublish: boolean): void
+  /** 驱动故障告警(网关节流广播) */
+  broadcastError(node: DaqNode, message: string): void
+  /** S5:越限进入 alarm(带触发量与越限方向) */
+  onAlarm?(node: DaqNode, value: number, rule: 'lt-min' | 'gt-max', threshold: number): void
+  /** S5:alarm 恢复(回到限内;报警仍待人工 ack) */
+  onAlarmRecover?(node: DaqNode, value: number): void
+  /** 活动配方对该节点的数采监控窗口(null = 无活动批次/未设窗口;越窗视同 alarm) */
+  recipeWindowFor?(node: DaqNode): { min: number | null, max: number | null } | null
+}
+
+/** onSample 结果(网关据此计指标) */
+export type ConsumeVerdict = 'late' | 'ok' | 'unknown-node'
+
+export class DaqNodeRuntime {
+  /** 采样时点(epoch ms;-Inf = 立即到期) */
+  private lastSampleAt = Number.NEGATIVE_INFINITY
+  /** WS 下发时点(0 = 立即可发) */
+  private lastPublishAt = 0
+  /** 已消费样本时间轴(乱序防御游标) */
+  private lastIngestAt = 0
+  /** 上次故障广播时刻 */
+  private errAt = 0
+  /** 采样在飞互斥(本节点串行;慢驱动不叠采也不阻塞邻居) */
+  private sampling = false
+
+  constructor(
+    /** 绑定的领域节点(元数据权威:enabled/intervalMs/publishIntervalMs/decimals 等) */
+    public readonly node: DaqNode,
+    private readonly host: DaqRuntimeHost,
+  ) {}
+
+  /** 元数据变更/网关重配后重置节拍(变化即刻生效,不等旧周期到期) */
+  rearm(): void {
+    this.lastSampleAt = Number.NEGATIVE_INFINITY
+    this.lastPublishAt = 0
+    this.lastIngestAt = 0
+  }
+
+  /** 仅重置下发游标(全局下发间隔变更时,让新缺省立刻可观测) */
+  republish(): void {
+    this.lastPublishAt = 0
+  }
+
+  /**
+   * 生产面 tick(网关 250ms 扫描驱动):到期判定 → 驱动采样 → 样本入队。
+   * 到期/互斥/启停判定基于本运行时私有状态;lastSampleAt 取采样完成时刻(慢驱动周期顺延)。
+   */
+  async tick(now: number): Promise<void> {
+    const node = this.node
+    if (this.sampling || !node.enabled) return
+    if (now < this.lastSampleAt + node.effectiveInterval(this.host.defaults().intervalMs)) return
+    this.sampling = true
+    try {
+      let v: number | null = null
+      try {
+        v = await this.host.sample(node, now)
+      }
+      finally {
+        // 采样完成时刻入账:采样耗时计入周期,慢驱动自然降频
+        this.lastSampleAt = Date.now()
+      }
+      if (v == null || Number.isNaN(v)) return
+      // 数据语义标定钩子(decoder):PLC 采集值 → 真实物理参数。
+      // 状态派生/入库/WS 下发全部使用物理值(节点元数据 transform 驱动)。
+      const phys = applyTransform(v, node.transform)
+      this.host.publishSample({
+        nodeId: node.id,
+        templateRef: node.templateRef,
+        value: Number(phys.toFixed(node.decimals)),
+        state: 'ok', // 健康态由消费端按量程派生(生产者只负责读数)
+        at: new Date(now).toISOString(),
+      })
+    }
+    catch (err) {
+      // 驱动故障(mock 不应发生;PLC 未接入走这里):置 offline + 独立节流广播
+      node.state = 'offline'
+      if (now - this.errAt > ERR_THROTTLE_MS) {
+        this.errAt = now
+        this.host.broadcastError(node, err instanceof Error ? err.message : String(err))
+      }
+    }
+    finally {
+      this.sampling = false // 互斥复位(成功/失败都要,否则节点采样一次即停)
+    }
+  }
+
+  /**
+   * 消费面:队列样本 → 乱序防御 → 状态派生 → WS 下发节拍门控 → 交网关管线。
+   * 入库与遥测回写不受门控(每帧必达);仅实时展示按 publishIntervalMs 限频。
+   */
+  onSample(env: DaqSampleEnvelope): ConsumeVerdict {
+    const node = this.node
+    const tsMs = Date.parse(env.at)
+    // 乱序防御(broker 多投递者场景):迟到帧直接丢弃
+    if (tsMs && tsMs <= this.lastIngestAt) return 'late'
+    this.lastIngestAt = tsMs
+
+    // S5:alarm 进入/恢复沿(边沿触发,非每帧;恢复不自动 ack,仍待人工确认)
+    // 配方监控窗口(活动批次)在派生后叠加:越窗视同 alarm,沿语义与量程告警一致
+    const prevState = node.state
+    node.applyReading(env.value, env.at)
+    const rw = this.host.recipeWindowFor?.(node) ?? null
+    if (rw && node.state !== 'alarm') {
+      if ((rw.min != null && env.value < rw.min) || (rw.max != null && env.value > rw.max))
+        node.state = 'alarm'
+    }
+    if (node.state === 'alarm' && prevState !== 'alarm') {
+      let rule: 'lt-min' | 'gt-max' = 'gt-max'
+      let threshold = node.max
+      if (rw && rw.max != null && env.value > rw.max) {
+        rule = 'gt-max'
+        threshold = rw.max
+      }
+      else if (rw && rw.min != null && env.value < rw.min) {
+        rule = 'lt-min'
+        threshold = rw.min
+      }
+      else if (env.value < node.min) {
+        rule = 'lt-min'
+        threshold = node.min
+      }
+      this.host.onAlarm?.(node, env.value, rule, threshold)
+    }
+    else if (node.state !== 'alarm' && prevState === 'alarm') {
+      this.host.onAlarmRecover?.(node, env.value)
+    }
+    const pubMs = Math.max(0, Math.min(PUBLISH_INTERVAL_MAX, node.publishIntervalMs ?? this.host.defaults().publishIntervalMs))
+    const now = Date.now()
+    const allowPublish = pubMs <= 0 || now - this.lastPublishAt >= pubMs
+    if (allowPublish) this.lastPublishAt = now
+    this.host.ingest(node, env, allowPublish)
+    return 'ok'
+  }
+}

package/server/services/workshop/daq/daq-templates.ts

@@ -0,0 +1,157 @@
+/**
+ * DaqTemplate 注册表 —— 内置模板(shared 单一事实源)+ 用户自定义模板的统一查询口。
+ *
+ * 自定义模板落盘 server/data/daq-templates.json(仅存自定义;内置始终在代码里),
+ * 与 DaqNodeRepo 同风格:进程内缓存 + 同步落盘(量小无抖动)。节点创建校验、
+ * 缺省域、mock 采样一律经 findDaqTemplate 查找 —— 自定义模板与内置同权。
+ */
+
+import { createLogger } from '../logger'
+import fs from 'node:fs'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { DAQ_TEMPLATES, DAQ_TEMPLATE_ICONS, daqTemplateByKey, type DaqTemplateDef, type DaqTemplateIcon, type DaqTemplateInput } from '../../../../shared/daq-protocol'
+import { AppError, ErrorCodes } from '../../../utils/errors'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+
+const log = createLogger('daq.templates')
+
+/** 业务错误捷径(经 defineApiHandler 映射为对应 HTTP 状态与消息) */
+const bad = (msg: string): AppError => new AppError(400, ErrorCodes.VALIDATION_ERROR, msg)
+
+// 配置根 .AgentWorkShop/data（ensureDataDir 统一解析 + 旧位置迁移）
+const DB_PATH = join(ensureDataDir(), 'daq-templates.json')
+
+function load(): DaqTemplateDef[] {
+  try {
+    const raw = fs.readFileSync(DB_PATH, 'utf-8')
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed as DaqTemplateDef[] : []
+  }
+  catch {
+    return []
+  }
+}
+
+/** 输入校验 + 归一(base/amp/decimals 等缺省由量程推导;非法值直接抛业务错误) */
+function normalize(input: Partial<DaqTemplateInput>, prev?: DaqTemplateDef): DaqTemplateDef {
+  const name = String(input.name ?? prev?.name ?? '').trim()
+  if (!name) throw bad('模板名称必填')
+  const unit = String(input.unit ?? prev?.unit ?? '').trim()
+  if (!unit) throw bad('单位必填(如 ℃ / MPa)')
+
+  const min = Number(input.min ?? prev?.min)
+  const max = Number(input.max ?? prev?.max)
+  if (!Number.isFinite(min) || !Number.isFinite(max) || min >= max) {
+    throw bad('量程非法:需满足 min < max 的数字')
+  }
+
+  const base = input.base ?? prev?.base ?? (min + max) / 2
+  if (!Number.isFinite(Number(base))) throw bad('模拟基值需为数字')
+
+  const amp = Number(input.amp ?? prev?.amp ?? Math.max((max - min) * 0.04, 0.001))
+  if (!Number.isFinite(amp) || amp <= 0) throw bad('模拟波幅需为正数')
+
+  const decimals = Math.round(Number(input.decimals ?? prev?.decimals ?? 2))
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 4) {
+    throw bad('小数位需为 0~4 的整数')
+  }
+
+  const iconRaw = String(input.icon ?? prev?.icon ?? 'thermo')
+  const icon = (DAQ_TEMPLATE_ICONS as readonly string[]).includes(iconRaw)
+    ? iconRaw as DaqTemplateIcon
+    : 'thermo'
+
+  return {
+    key: prev?.key ?? `ct-${randomUUID().slice(0, 8)}`,
+    name,
+    code: String(input.code ?? prev?.code ?? name).trim().toUpperCase() || name.toUpperCase(),
+    ch: String(input.ch ?? prev?.ch ?? name).trim() || name,
+    unit,
+    base: Number(base),
+    amp,
+    min,
+    max,
+    decimals,
+    icon,
+    semantics: String(input.semantics ?? prev?.semantics ?? '').trim() || undefined,
+    telemetryKey: String(input.telemetryKey ?? prev?.telemetryKey ?? '').trim() || undefined,
+    builtin: false,
+  }
+}
+
+class DaqTemplateRegistry {
+  private customs: DaqTemplateDef[]
+
+  constructor() {
+    this.customs = load()
+  }
+
+  /** 全目录:内置在前(统一打 builtin 标记,前端据此分区),自定义在后 */
+  all(): DaqTemplateDef[] {
+    return [...DAQ_TEMPLATES.map(t => ({ ...t, builtin: true })), ...this.customs]
+  }
+
+  byKey(key: string): DaqTemplateDef | undefined {
+    return daqTemplateByKey(key) ?? this.customs.find(t => t.key === key)
+  }
+
+  create(input: DaqTemplateInput): DaqTemplateDef {
+    const tpl = normalize(input)
+    if (this.customs.some(t => t.name === tpl.name)) {
+      throw new AppError(409, ErrorCodes.CONFLICT, `同名自定义模板已存在: ${tpl.name}`)
+    }
+    this.customs.push(tpl)
+    this.flush()
+    return tpl
+  }
+
+  update(key: string, patch: Partial<DaqTemplateInput>): DaqTemplateDef {
+    const prev = this.customs.find(t => t.key === key)
+    if (!prev) {
+      throw new AppError(400, ErrorCodes.BAD_REQUEST, daqTemplateByKey(key) ? '内置模板不可修改(可复制为自定义)' : `自定义模板不存在: ${key}`)
+    }
+    const tpl = normalize(patch, prev)
+    this.customs = this.customs.map(t => (t.key === key ? tpl : t))
+    this.flush()
+    return tpl
+  }
+
+  remove(key: string): DaqTemplateDef {
+    const prev = this.customs.find(t => t.key === key)
+    if (!prev) {
+      throw new AppError(400, ErrorCodes.BAD_REQUEST, daqTemplateByKey(key) ? '内置模板不可删除' : `自定义模板不存在: ${key}`)
+    }
+    this.customs = this.customs.filter(t => t.key !== key)
+    this.flush()
+    return prev
+  }
+
+  private flush(): void {
+    try {
+      fs.mkdirSync(join(DB_PATH, '..'), { recursive: true })
+      fs.writeFileSync(DB_PATH, JSON.stringify(this.customs, null, 2), 'utf-8')
+    }
+    catch (err) {
+      log.error('[daq] 模板落盘失败:', err)
+    }
+  }
+}
+
+// 单例(HMR 存活,与 DaqNodeRepo 同风格)
+const g = globalThis as typeof globalThis & { __daqTemplateRegistry?: DaqTemplateRegistry }
+
+export function getDaqTemplateRegistry(): DaqTemplateRegistry {
+  g.__daqTemplateRegistry ??= new DaqTemplateRegistry()
+  return g.__daqTemplateRegistry
+}
+
+/** 目录快照(server 返回给前端时附带 builtin 标记) */
+export function listDaqTemplates(): DaqTemplateDef[] {
+  return getDaqTemplateRegistry().all()
+}
+
+/** 节点缺省域/mock 采样的统一查找口(内置 + 自定义) */
+export function findDaqTemplate(key: string): DaqTemplateDef | undefined {
+  return getDaqTemplateRegistry().byKey(key)
+}