agentworkshop 0.7.49 → 0.7.50

package/server/services/workshop/dcw/dcw-controller/crud.ts

@@ -1,152 +1,162 @@
-/**
- * DcwControllerCrud —— 节点 CRUD
- * (拆分层,承 DcwControllerControl;方法体与原文件逐行一致)
- */
-import { DcwControllerControl } from './control'
-import type { DcwCreateInput, DcwPatchInput } from './types'
-import { AppError, ErrorCodes } from '../../../../utils/errors'
-import { DcwNode } from '../dcw-node'
-import { dcwKeyFromRef, normalizeDataTransform } from '../../../../../shared/dcw-protocol'
-import { findDcwTemplate } from '../dcw-templates'
-import { getDcwLineRepo } from '../dcw-line.repo'
-import { getDcwParamRepo } from '../param-map.repo'
-import { normalizeDcwDriverKind } from '../drivers'
-import { randomUUID } from 'node:crypto'
-
-export abstract class DcwControllerCrud extends DcwControllerControl {
-  create(input: DcwCreateInput): DcwNode {
-    this.ensureLoop()
-    if (!input.templateRef) {
-      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'templateRef 必填:控制节点必须绑定工艺参数模板')
-    }
-    const tpl = findDcwTemplate(dcwKeyFromRef(input.templateRef))
-    if (!tpl) {
-      throw new AppError(404, ErrorCodes.NOT_FOUND, `未知控制模板: ${input.templateRef}`)
-    }
-    const seq = this.repo.all().filter(n => n.templateKey === dcwKeyFromRef(input.templateRef!)).length + 1
-    const node = new DcwNode({
-      id: `dw-${randomUUID().slice(0, 8)}`,
-      templateRef: input.templateRef,
-      name: input.name ?? `${tpl.name} ${String(seq).padStart(2, '0')}`,
-      driver: input.driver ? normalizeDcwDriverKind(input.driver) : undefined,
-      driverConfig: input.driverConfig ?? {},
-      transform: normalizeDataTransform(input.transform),
-      enabled: input.enabled,
-      holdIntervalMs: input.holdIntervalMs ?? null,
-      readIntervalMs: input.readIntervalMs ?? null,
-      unit: input.unit,
-      decimals: input.decimals,
-      min: input.min,
-      max: input.max,
-      deviceBindingId: input.deviceBindingId ?? null,
-      deviceIds: input.deviceIds ?? (input.deviceBindingId ? [input.deviceBindingId] : []),
-      posX: input.posX,
-      posZ: input.posZ,
-      lineId: input.lineId,
-      semantics: input.semantics,
-      writeLockSeconds: input.writeLockSeconds,
-    })
-    this.repo.insert(node)
-    // 工艺参数映射面:节点创建即自动生成同名映射(用户/Agent 的参数语义面;
-    // PLC 寻址细节仍封装在节点驱动配置内)。失败不阻断节点创建(可事后手工补建)。
-    getDcwParamRepo().ensureForNode(node)
-    this.syncRuntimes()
-    this.emitNodeChanged('added', node)
-    return node
-  }
-
-  patch(id: string, patch: DcwPatchInput): DcwNode {
-    const node = this.repo.byId(id)
-    if (!node) throw new AppError(404, ErrorCodes.NOT_FOUND, `控制节点不存在: ${id}`)
-    let rearm = false
-    if (patch.name !== undefined) node.name = patch.name
-    if (patch.driver !== undefined) node.driver = normalizeDcwDriverKind(patch.driver)
-    if (patch.driverConfig !== undefined) node.driverConfig = { ...node.driverConfig, ...patch.driverConfig }
-    if (patch.transform !== undefined) {
-      if (patch.transform.kind === 'linear' && (!Number.isFinite(Number(patch.transform.scale)) || Number(patch.transform.scale) === 0)) {
-        throw new AppError(400, ErrorCodes.VALIDATION_ERROR, '标定系数 scale 必须为非零数字(物理值 = scale × PLC值 + offset)')
-      }
-      node.transform = normalizeDataTransform(patch.transform)
-    }
-    if (patch.unit !== undefined) node.unit = patch.unit
-    // decimals 必须 0..6 整数:它同时喂给 toFixed() —— 越界值会在**驱动已经写进 PLC 之后**
-    // 由 applyWriteResult/applyReadResult 抛 RangeError,造成「硬件已改、账本无记录、
-    // 调用方吃 500」(审计实测:decimals=101 → PLC 写入成功、无锚点、无写历史)。
-    // 在校验入口一次性拒掉,别让脏值走到写路径。
-    if (patch.decimals !== undefined) {
-      const d = Number(patch.decimals)
-      if (!Number.isInteger(d) || d < 0 || d > 6) {
-        throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `decimals 必须为 0..6 的整数(当前: ${String(patch.decimals)})`)
-      }
-      node.decimals = d
-    }
-    if (patch.min !== undefined) {
-      const v = Number(patch.min)
-      if (!Number.isFinite(v)) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `min 必须为有限数字(当前: ${String(patch.min)})`)
-      node.min = v
-    }
-    if (patch.max !== undefined) {
-      const v = Number(patch.max)
-      if (!Number.isFinite(v)) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `max 必须为有限数字(当前: ${String(patch.max)})`)
-      node.max = v
-    }
-    // 量程交叉校验放在两者都应用之后:min>max 会让 writeTolerance 变负、越界判定恒真
-    if (node.max < node.min) {
-      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `量程无效:max(${node.max}) 不得小于 min(${node.min})`)
-    }
-    if (patch.holdIntervalMs !== undefined) {
-      node.holdIntervalMs = patch.holdIntervalMs == null ? null : Math.max(0, Math.min(3_600_000, Math.round(patch.holdIntervalMs)))
-      rearm = true
-    }
-    if (patch.readIntervalMs !== undefined) {
-      node.readIntervalMs = patch.readIntervalMs == null ? null : Math.max(0, Math.min(3_600_000, Math.round(patch.readIntervalMs)))
-      rearm = true
-    }
-    if (patch.enabled !== undefined) {
-      node.enabled = patch.enabled
-      // 暂停/恢复的状态同步:暂停 → offline(暂停控制);恢复 → 回到待机(等下次写 ACK 转 ok)
-      if (!patch.enabled) node.state = 'offline'
-      else if (node.state === 'offline') node.state = 'idle'
-      rearm = true
-    }
-    if (patch.posX !== undefined) node.posX = patch.posX
-    if (patch.posZ !== undefined) node.posZ = patch.posZ
-    if (patch.lineId !== undefined) {
-      const lid = String(patch.lineId)
-      if (lid && !getDcwLineRepo().byId(lid)) throw new AppError(404, ErrorCodes.NOT_FOUND, `产线不存在: ${lid}`)
-      node.lineId = lid
-    }
-    if (patch.semantics !== undefined) node.semantics = String(patch.semantics)
-    if (patch.writeLockSeconds !== undefined) {
-      const v = Number(patch.writeLockSeconds)
-      if (!Number.isFinite(v) || v < 0 || v > 3600) {
-        throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `writeLockSeconds 必须为 0..3600 的整数秒(当前: ${String(patch.writeLockSeconds)})`)
-      }
-      node.writeLockSeconds = Math.round(v)
-    }
-    if (rearm) this.runtimes.get(id)?.rearm()
-    this.repo.flushNow()
-    this.emitNodeChanged('updated', node)
-    return node
-  }
-
-  remove(id: string): void {
-    const node = this.repo.byId(id)
-    if (!node) throw new AppError(404, ErrorCodes.NOT_FOUND, `控制节点不存在: ${id}`)
-    this.repo.remove(id)
-    this.runtimes.delete(id)
-    // 级联清理:工艺参数映射面随执行节点删除(参数不存在悬空引用)
-    getDcwParamRepo().removeForNode(id)
-    // 级联清理:该节点的 Agent 绑定移除,挂起中的手动审批按失效收敛
-    void import('../../agents/node-bindings.repo').then(({ getAgentNodeBindingRepo }) => {
-      const repo = getAgentNodeBindingRepo()
-      for (const b of repo.byNode(id)) {
-        void import('../../agents/tool-approvals').then(({ getToolApprovals }) => {
-          getToolApprovals().cancelPendingFor(b.agentId, id)
-        }).catch(() => {})
-        repo.removeAgentNode(b.agentId, id, 'dcw')
-      }
-    }).catch(() => {})
-    this.emitNodeChanged('removed', node)
-  }
-}
+/**
+ * DcwControllerCrud —— 节点 CRUD
+ * (拆分层,承 DcwControllerControl;方法体与原文件逐行一致)
+ */
+import { DcwControllerControl } from './control'
+import type { DcwCreateInput, DcwPatchInput } from './types'
+import { AppError, ErrorCodes } from '../../../../utils/errors'
+import { DcwNode } from '../dcw-node'
+import { dcwKeyFromRef, normalizeDataTransform } from '../../../../../shared/dcw-protocol'
+import { findDcwTemplate } from '../dcw-templates'
+import { getDcwLineRepo } from '../dcw-line.repo'
+import { getDcwParamRepo } from '../param-map.repo'
+import { normalizeDcwDriverKind } from '../drivers'
+import { randomUUID } from 'node:crypto'
+
+function normalizeStepLimitInput(value: unknown): number | null | undefined {
+  if (value === undefined) return undefined
+  if (value === null || value === '') return null
+  const n = Number(value)
+  if (!Number.isFinite(n) || n <= 0) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `stepLimit 必须为正数或 null(当前: ${String(value)})`)
+  return n
+}
+
+export abstract class DcwControllerCrud extends DcwControllerControl {
+  create(input: DcwCreateInput): DcwNode {
+    this.ensureLoop()
+    if (!input.templateRef) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'templateRef 必填:控制节点必须绑定工艺参数模板')
+    }
+    const tpl = findDcwTemplate(dcwKeyFromRef(input.templateRef))
+    if (!tpl) {
+      throw new AppError(404, ErrorCodes.NOT_FOUND, `未知控制模板: ${input.templateRef}`)
+    }
+    const seq = this.repo.all().filter(n => n.templateKey === dcwKeyFromRef(input.templateRef!)).length + 1
+    const node = new DcwNode({
+      id: `dw-${randomUUID().slice(0, 8)}`,
+      templateRef: input.templateRef,
+      name: input.name ?? `${tpl.name} ${String(seq).padStart(2, '0')}`,
+      driver: input.driver ? normalizeDcwDriverKind(input.driver) : undefined,
+      driverConfig: input.driverConfig ?? {},
+      transform: normalizeDataTransform(input.transform),
+      enabled: input.enabled,
+      holdIntervalMs: input.holdIntervalMs ?? null,
+      readIntervalMs: input.readIntervalMs ?? null,
+      unit: input.unit,
+      decimals: input.decimals,
+      min: input.min,
+      max: input.max,
+      deviceBindingId: input.deviceBindingId ?? null,
+      deviceIds: input.deviceIds ?? (input.deviceBindingId ? [input.deviceBindingId] : []),
+      posX: input.posX,
+      posZ: input.posZ,
+      lineId: input.lineId,
+      semantics: input.semantics,
+      writeLockSeconds: input.writeLockSeconds,
+      stepLimit: normalizeStepLimitInput(input.stepLimit),
+    })
+    this.repo.insert(node)
+    // 工艺参数映射面:节点创建即自动生成同名映射(用户/Agent 的参数语义面;
+    // PLC 寻址细节仍封装在节点驱动配置内)。失败不阻断节点创建(可事后手工补建)。
+    getDcwParamRepo().ensureForNode(node)
+    this.syncRuntimes()
+    this.emitNodeChanged('added', node)
+    return node
+  }
+
+  patch(id: string, patch: DcwPatchInput): DcwNode {
+    const node = this.repo.byId(id)
+    if (!node) throw new AppError(404, ErrorCodes.NOT_FOUND, `控制节点不存在: ${id}`)
+    let rearm = false
+    if (patch.name !== undefined) node.name = patch.name
+    if (patch.driver !== undefined) node.driver = normalizeDcwDriverKind(patch.driver)
+    if (patch.driverConfig !== undefined) node.driverConfig = { ...node.driverConfig, ...patch.driverConfig }
+    if (patch.transform !== undefined) {
+      if (patch.transform.kind === 'linear' && (!Number.isFinite(Number(patch.transform.scale)) || Number(patch.transform.scale) === 0)) {
+        throw new AppError(400, ErrorCodes.VALIDATION_ERROR, '标定系数 scale 必须为非零数字(物理值 = scale × PLC值 + offset)')
+      }
+      node.transform = normalizeDataTransform(patch.transform)
+    }
+    if (patch.unit !== undefined) node.unit = patch.unit
+    // decimals 必须 0..6 整数:它同时喂给 toFixed() —— 越界值会在**驱动已经写进 PLC 之后**
+    // 由 applyWriteResult/applyReadResult 抛 RangeError,造成「硬件已改、账本无记录、
+    // 调用方吃 500」(审计实测:decimals=101 → PLC 写入成功、无锚点、无写历史)。
+    // 在校验入口一次性拒掉,别让脏值走到写路径。
+    if (patch.decimals !== undefined) {
+      const d = Number(patch.decimals)
+      if (!Number.isInteger(d) || d < 0 || d > 6) {
+        throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `decimals 必须为 0..6 的整数(当前: ${String(patch.decimals)})`)
+      }
+      node.decimals = d
+    }
+    if (patch.min !== undefined) {
+      const v = Number(patch.min)
+      if (!Number.isFinite(v)) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `min 必须为有限数字(当前: ${String(patch.min)})`)
+      node.min = v
+    }
+    if (patch.max !== undefined) {
+      const v = Number(patch.max)
+      if (!Number.isFinite(v)) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `max 必须为有限数字(当前: ${String(patch.max)})`)
+      node.max = v
+    }
+    // 量程交叉校验放在两者都应用之后:min>max 会让 writeTolerance 变负、越界判定恒真
+    if (node.max < node.min) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `量程无效:max(${node.max}) 不得小于 min(${node.min})`)
+    }
+    if (patch.holdIntervalMs !== undefined) {
+      node.holdIntervalMs = patch.holdIntervalMs == null ? null : Math.max(0, Math.min(3_600_000, Math.round(patch.holdIntervalMs)))
+      rearm = true
+    }
+    if (patch.readIntervalMs !== undefined) {
+      node.readIntervalMs = patch.readIntervalMs == null ? null : Math.max(0, Math.min(3_600_000, Math.round(patch.readIntervalMs)))
+      rearm = true
+    }
+    if (patch.enabled !== undefined) {
+      node.enabled = patch.enabled
+      // 暂停/恢复的状态同步:暂停 → offline(暂停控制);恢复 → 回到待机(等下次写 ACK 转 ok)
+      if (!patch.enabled) node.state = 'offline'
+      else if (node.state === 'offline') node.state = 'idle'
+      rearm = true
+    }
+    if (patch.posX !== undefined) node.posX = patch.posX
+    if (patch.posZ !== undefined) node.posZ = patch.posZ
+    if (patch.lineId !== undefined) {
+      const lid = String(patch.lineId)
+      if (lid && !getDcwLineRepo().byId(lid)) throw new AppError(404, ErrorCodes.NOT_FOUND, `产线不存在: ${lid}`)
+      node.lineId = lid
+    }
+    if (patch.semantics !== undefined) node.semantics = String(patch.semantics)
+    if (patch.writeLockSeconds !== undefined) {
+      const v = Number(patch.writeLockSeconds)
+      if (!Number.isFinite(v) || v < 0 || v > 3600) {
+        throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `writeLockSeconds 必须为 0..3600 的整数秒(当前: ${String(patch.writeLockSeconds)})`)
+      }
+      node.writeLockSeconds = Math.round(v)
+    }
+    if (patch.stepLimit !== undefined) node.stepLimit = normalizeStepLimitInput(patch.stepLimit) ?? null
+    if (rearm) this.runtimes.get(id)?.rearm()
+    this.repo.flushNow()
+    this.emitNodeChanged('updated', node)
+    return node
+  }
+
+  remove(id: string): void {
+    const node = this.repo.byId(id)
+    if (!node) throw new AppError(404, ErrorCodes.NOT_FOUND, `控制节点不存在: ${id}`)
+    this.repo.remove(id)
+    this.runtimes.delete(id)
+    // 级联清理:工艺参数映射面随执行节点删除(参数不存在悬空引用)
+    getDcwParamRepo().removeForNode(id)
+    // 级联清理:该节点的 Agent 绑定移除,挂起中的手动审批按失效收敛
+    void import('../../agents/node-bindings.repo').then(({ getAgentNodeBindingRepo }) => {
+      const repo = getAgentNodeBindingRepo()
+      for (const b of repo.byNode(id)) {
+        void import('../../agents/tool-approvals').then(({ getToolApprovals }) => {
+          getToolApprovals().cancelPendingFor(b.agentId, id)
+        }).catch(() => {})
+        repo.removeAgentNode(b.agentId, id, 'dcw')
+      }
+    }).catch(() => {})
+    this.emitNodeChanged('removed', node)
+  }
+}

package/server/services/workshop/dcw/dcw-controller/helpers.ts

@@ -1,57 +1,61 @@
-/**
- * DcwController 的模块级纯工具/常量(原 server/services/workshop/dcw/dcw-controller.ts 类外声明,含类体之后与类无关的部分)。
- */
-import type { ProductInput } from '../../../../../shared/dcw-protocol'
-import { AppError, ErrorCodes } from '../../../../utils/errors'
-import { attachDcwPluginBridge } from '../plugin-bridge'
-import { getDcwParamRepo } from '../param-map.repo'
-
-export const opsWriteMemo = new Map<string, { eng: number, at: number }>()
-
-// 写驱动插件桥(模块装载即挂;插件宿主先到则注册项排队、此处接管回放)
-attachDcwPluginBridge()
-
-/** 周期读网关默认间隔(节点 readIntervalMs=null 时生效;真实 PLC 建议按链路承载调整) */
-export const DEFAULT_READ_INTERVAL_MS = 5000
-
-/** write() 来源 → 日志来源(user 人工下发 / agent 智能体 / system 配方·回退等系统路径) */
-export function opsActorKindOf(source: string): 'user' | 'agent' | 'system' {
-  if (source === 'agent') return 'agent'
-  if (source === 'manual') return 'user'
-  return 'system'
-}
-
-export const SWEEP_MS = 500
-
-/**
- * 产品级工艺参数限界校验:键必须命中该产品所属产线上的工艺参数映射
- * (防静默失效的拼错键);区间须 min<=max 且为有限数字。产品未挂产线时限界无
- * 寻址语境,拒绝非空限界。
- */
-export function assertProductParamLimits(lineId: string, paramLimits: ProductInput['paramLimits'] | undefined): void {
-  if (paramLimits == null) return
-  if (typeof paramLimits !== 'object' || Array.isArray(paramLimits)) {
-    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'paramLimits 需为对象(键=工艺参数 key,值={min?,max?})')
-  }
-  const entries = Object.entries(paramLimits)
-  if (entries.length === 0) return
-  if (!lineId) {
-    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, '产品未挂载产线,不可设定工艺参数限界(限界按产线内的工艺参数寻址)')
-  }
-  const lineKeys = new Set(
-    getDcwParamRepo().listViews().filter(p => p.lineId === lineId).map(p => p.key),
-  )
-  for (const [key, range] of entries) {
-    if (!lineKeys.has(key)) {
-      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `产品限界的工艺参数键「${key}」在产线上不存在(可用的工艺参数:${[...lineKeys].join(', ') || '无 —— 先创建写控节点生成参数面'})`)
-    }
-    const min = range?.min == null ? null : Number(range.min)
-    const max = range?.max == null ? null : Number(range.max)
-    if ((range?.min != null && !Number.isFinite(min)) || (range?.max != null && !Number.isFinite(max))) {
-      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `产品限界「${key}」的上下限需为数字`)
-    }
-    if (min != null && max != null && min > max) {
-      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `产品限界「${key}」非法:min ${min} > max ${max}`)
-    }
-  }
-}
+/**
+ * DcwController 的模块级纯工具/常量(原 server/services/workshop/dcw/dcw-controller.ts 类外声明,含类体之后与类无关的部分)。
+ */
+import type { ProductInput } from '../../../../../shared/dcw-protocol'
+import { AppError, ErrorCodes } from '../../../../utils/errors'
+import { attachDcwPluginBridge } from '../plugin-bridge'
+import { getDcwParamRepo } from '../param-map.repo'
+
+// 写驱动插件桥(模块装载即挂;插件宿主先到则注册项排队、此处接管回放)
+attachDcwPluginBridge()
+
+/** 周期读网关默认间隔(节点 readIntervalMs=null 时生效;真实 PLC 建议按链路承载调整) */
+export const DEFAULT_READ_INTERVAL_MS = 5000
+
+/** write() 来源 → 日志来源(user 人工下发 / agent 智能体 / system 配方·回退等系统路径) */
+export function opsActorKindOf(source: string): 'user' | 'agent' | 'system' {
+  if (source === 'agent') return 'agent'
+  if (source === 'manual') return 'user'
+  return 'system'
+}
+
+export const SWEEP_MS = 500
+
+// 基准模式显式留痕:AW_BENCH_MODE=1 豁免在线探索限频(单步上限/60s 间隔/写入保持窗),
+// 四层限界联锁不受影响(软层旁路还需每次写携带 meta.benchArm)。生产实例误配此 env 时启动即告警。
+if (process.env.AW_BENCH_MODE === '1') {
+  console.warn('[dcw] AW_BENCH_MODE=1:在线探索限频(单步上限/60s 间隔/写入保持窗)已整体豁免 —— 仅限基准/审计环境使用!')
+}
+
+/**
+ * 产品级工艺参数限界校验:键必须命中该产品所属产线上的工艺参数映射
+ * (防静默失效的拼错键);区间须 min<=max 且为有限数字。产品未挂产线时限界无
+ * 寻址语境,拒绝非空限界。
+ */
+export function assertProductParamLimits(lineId: string, paramLimits: ProductInput['paramLimits'] | undefined): void {
+  if (paramLimits == null) return
+  if (typeof paramLimits !== 'object' || Array.isArray(paramLimits)) {
+    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'paramLimits 需为对象(键=工艺参数 key,值={min?,max?})')
+  }
+  const entries = Object.entries(paramLimits)
+  if (entries.length === 0) return
+  if (!lineId) {
+    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, '产品未挂载产线,不可设定工艺参数限界(限界按产线内的工艺参数寻址)')
+  }
+  const lineKeys = new Set(
+    getDcwParamRepo().listViews().filter(p => p.lineId === lineId).map(p => p.key),
+  )
+  for (const [key, range] of entries) {
+    if (!lineKeys.has(key)) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `产品限界的工艺参数键「${key}」在产线上不存在(可用的工艺参数:${[...lineKeys].join(', ') || '无 —— 先创建写控节点生成参数面'})`)
+    }
+    const min = range?.min == null ? null : Number(range.min)
+    const max = range?.max == null ? null : Number(range.max)
+    if ((range?.min != null && !Number.isFinite(min)) || (range?.max != null && !Number.isFinite(max))) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `产品限界「${key}」的上下限需为数字`)
+    }
+    if (min != null && max != null && min > max) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `产品限界「${key}」非法:min ${min} > max ${max}`)
+    }
+  }
+}

package/server/services/workshop/dcw/dcw-controller/types.ts

@@ -1,57 +1,61 @@
-/**
- * DcwController 的依赖类型与对外 DTO(原 server/services/workshop/dcw/dcw-controller.ts 顶部模块级类型声明)。纯类型。
- */
-import type { DataTransform, DcwDriverKind } from '../../../../../shared/dcw-protocol'
-
-export type BroadcastFn = (type: string, payload: unknown) => void
-
-export interface DcwCreateInput {
-  templateRef?: string
-  name?: string
-  driver?: DcwDriverKind
-  driverConfig?: Record<string, string | number | boolean>
-  /** 数据语义标定钩子(encode:物理值 → PLC 设定值) */
-  transform?: DataTransform
-  holdIntervalMs?: number | null
-  /** 周期读间隔 ms(null = 网关默认;0 = 仅手动读取) */
-  readIntervalMs?: number | null
-  unit?: string
-  decimals?: number
-  min?: number
-  max?: number
-  enabled?: boolean
-  posX?: number
-  posZ?: number
-  deviceBindingId?: string | null
-  deviceIds?: string[]
-  /** 所属产线('' = 未分配) */
-  lineId?: string
-  /** 节点级工艺语义备注(覆盖模板) */
-  semantics?: string
-  /** 写入保持窗秒数(写成功后锁定节点防震荡;0 = 不锁;默认 30) */
-  writeLockSeconds?: number
-}
-
-export interface DcwPatchInput {
-  name?: string
-  driver?: DcwDriverKind
-  driverConfig?: Record<string, string | number | boolean>
-  /** 数据语义标定钩子(encode) */
-  transform?: DataTransform
-  holdIntervalMs?: number | null
-  /** 周期读间隔 ms(null = 网关默认;0 = 仅手动读取) */
-  readIntervalMs?: number | null
-  unit?: string
-  decimals?: number
-  min?: number
-  max?: number
-  enabled?: boolean
-  posX?: number
-  posZ?: number
-  lineId?: string
-  semantics?: string
-  /** 写入保持窗秒数(0 = 不锁) */
-  writeLockSeconds?: number
-}
-
-/** 网关扫描周期(ms;保写心跳分辨率) */
+/**
+ * DcwController 的依赖类型与对外 DTO(原 server/services/workshop/dcw/dcw-controller.ts 顶部模块级类型声明)。纯类型。
+ */
+import type { DataTransform, DcwDriverKind } from '../../../../../shared/dcw-protocol'
+
+export type BroadcastFn = (type: string, payload: unknown) => void
+
+export interface DcwCreateInput {
+  templateRef?: string
+  name?: string
+  driver?: DcwDriverKind
+  driverConfig?: Record<string, string | number | boolean>
+  /** 数据语义标定钩子(encode:物理值 → PLC 设定值) */
+  transform?: DataTransform
+  holdIntervalMs?: number | null
+  /** 周期读间隔 ms(null = 网关默认;0 = 仅手动读取) */
+  readIntervalMs?: number | null
+  unit?: string
+  decimals?: number
+  min?: number
+  max?: number
+  enabled?: boolean
+  posX?: number
+  posZ?: number
+  deviceBindingId?: string | null
+  deviceIds?: string[]
+  /** 所属产线('' = 未分配) */
+  lineId?: string
+  /** 节点级工艺语义备注(覆盖模板) */
+  semantics?: string
+  /** 写入保持窗秒数(写成功后锁定节点防震荡;0 = 不锁;默认 60) */
+  writeLockSeconds?: number
+  /** 单次控制步长上限(工程量;探索阶段的安全护栏) */
+  stepLimit?: number | null
+}
+
+export interface DcwPatchInput {
+  name?: string
+  driver?: DcwDriverKind
+  driverConfig?: Record<string, string | number | boolean>
+  /** 数据语义标定钩子(encode) */
+  transform?: DataTransform
+  holdIntervalMs?: number | null
+  /** 周期读间隔 ms(null = 网关默认;0 = 仅手动读取) */
+  readIntervalMs?: number | null
+  unit?: string
+  decimals?: number
+  min?: number
+  max?: number
+  enabled?: boolean
+  posX?: number
+  posZ?: number
+  lineId?: string
+  semantics?: string
+  /** 写入保持窗秒数(0 = 不锁) */
+  writeLockSeconds?: number
+  /** 单次控制步长上限(工程量;null = 显式清除参数,回到安全默认) */
+  stepLimit?: number | null
+}
+
+/** 网关扫描周期(ms;保写心跳分辨率) */

package/server/services/workshop/dcw/dcw-controller/write-audit.ts

@@ -0,0 +1,49 @@
+/**
+ * 写控运维入册(写成功后的单点记账,由 write() 内联块收敛而来):
+ *  - recordOps 运维日志(同节点同值 10s 去重节流,防重试风暴刷屏);
+ *  - 插件写控 ACK 钩子(与运维入册同点同去重节流)。
+ * 与调控闭环入册(afterWrite)分离;调用方保证吞掉本模块异常 —— 日志失败不影响写结果。
+ */
+import type { DcwWriteMeta, DcwWriteSource } from '../../../../../shared/dcw-protocol'
+import { emitDcwWrite } from '@/server/services/workshop/plugins/host.mjs'
+import { getActiveLineRun } from '../line-run'
+import { opsActorKindOf } from './helpers'
+import { recordOps } from '../../ops/ops'
+
+/** 同节点写入去重节流表(eng+10s 窗内视为同一次下发的重试回执) */
+export const opsWriteMemo = new Map<string, { eng: number, at: number }>()
+
+export function recordDcwWriteOps(args: {
+  id: string
+  node: { name: string, unit?: string, lineId: string }
+  eng: number
+  prevValue: number | null
+  outcome: { ok: boolean, message: string }
+  src: DcwWriteSource
+  meta?: DcwWriteMeta
+  recipeRunId: string | null
+}): void {
+  const memo = opsWriteMemo.get(args.id)
+  const now = Date.now()
+  if (memo && memo.eng === args.eng && now - memo.at <= 10_000) return
+  opsWriteMemo.set(args.id, { eng: args.eng, at: now })
+  if (opsWriteMemo.size > 500)
+    opsWriteMemo.clear()
+  const runNow = getActiveLineRun(args.node.lineId)
+  recordOps({
+    actor: args.meta?.actor ?? 'user',
+    actorName: args.meta?.actorName ?? args.meta?.actor ?? 'user',
+    actorKind: opsActorKindOf(args.src),
+    action: `dcw.write.${args.src}`,
+    kind: 'write',
+    targetKind: 'dcw-node',
+    targetId: args.id,
+    summary: `下发设定「${args.node.name}」→ ${args.eng}${args.node.unit ?? ''}(${args.src === 'manual' ? '手动' : args.src === 'agent' ? 'Agent' : args.src === 'rollback' ? '回退恢复' : '配方'})`,
+    lineId: args.node.lineId ?? '',
+    productId: runNow?.productId ?? '',
+    recipeId: runNow?.recipeId ?? args.recipeRunId ?? '',
+    detail: { eng: args.eng, prevValue: args.prevValue, ok: args.outcome.ok, message: args.outcome.message, taskId: args.meta?.taskId ?? null },
+  })
+  // 插件钩子:写控 ACK 观察(与运维入册同点同去重节流)
+  emitDcwWrite({ nodeId: args.id, name: args.node.name, eng: args.eng, prevValue: args.prevValue, ok: args.outcome.ok, source: args.src, lineId: args.node.lineId ?? '', at: new Date().toISOString() })
+}