agentworkshop 0.7.70 → 0.8.0

package/server/api/workshop/daq/[id]/ingest.post.ts

@@ -1,166 +1,192 @@
-/**
- * POST /api/workshop/daq/:id/ingest —— 外部 API 推送多源异构数采样本。
- *
- * 适用:第三方/边缘系统每次调用返回一张图片或一个数组(如膜厚模头点位数组),
- * 由调用方主动推入本平台,走与网关采样完全相同的队列/入库/打标/告警链路。
- *
- * body:
- *   { at?: ISO, value?: number, points?: number[], metrics?: {k:number},
- *     state?: 'ok'|'warn'|'alarm'|'offline',
- *     image?: { base64|data: string, mime?: string, width?: number, height?: number } | string }
- *
- * 鉴权:
- *   - 配置了 AW_DAQ_INGEST_TOKEN 时,要求 x-aw-daq-token 头匹配(外部系统接入);
- *   - 未配置时退回仪表盘用户会话(resolveUser)。
- * 约束:
- *   - 节点必须存在且启用;载荷形态必须与模板 signalKind 一致(scalar/vector/image);
- *   - 向量 1..4096 个有限数;图像 ≤10MB 且 MIME image/*;
- *   - at 缺省=当前时间,允许范围为 ±7 天。
- */
-import { createHash } from 'node:crypto'
-import { getHeader, getRouterParam, readBody } from 'h3'
-import { resolveUser } from '@/server/api/workshop/caller'
-import { defineApiHandler } from '@/server/utils/response'
-import { getDaqController } from '@/server/services/workshop/daq/daq-controller'
-import { findDaqTemplate } from '@/server/services/workshop/daq/daq-templates'
-import { getDaqQueue } from '@/server/services/workshop/daq/bus'
-import { getObjectStore } from '@/server/services/workshop/daq/objectstore'
-import { daqObjectKey } from '@/server/services/workshop/daq/objectstore/objectstore-port'
-import type { DaqSampleEnvelope } from '@/server/services/workshop/daq/bus/queue-port'
-import { AppError } from '@/server/utils/errors'
-
-const IMAGE_MAX_BYTES = 10 * 1024 * 1024
-const VECTOR_MAX_POINTS = 4096
-const AT_RANGE_MS = 7 * 24 * 3600_000
-
-interface IngestBody {
-  at?: string
-  value?: number | string
-  points?: unknown
-  values?: unknown
-  metrics?: Record<string, unknown>
-  state?: string
-  image?: { base64?: string, data?: string, mime?: string, width?: number, height?: number } | string
-}
-
-function finiteList(raw: unknown): number[] | null {
-  if (!Array.isArray(raw)) return null
-  const out: number[] = []
-  for (const x of raw) {
-    const n = Number(x)
-    if (!Number.isFinite(n)) return null
-    out.push(n)
-  }
-  return out
-}
-
-function metricsOf(raw: unknown): Record<string, number> {
-  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) return {}
-  const out: Record<string, number> = {}
-  for (const [k, v] of Object.entries(raw as Record<string, unknown>).slice(0, 64)) {
-    const n = Number(v)
-    if (Number.isFinite(n) && k.trim()) out[k.trim().slice(0, 80)] = n
-  }
-  return out
-}
-
-export default defineApiHandler(async (event) => {
-  const id = getRouterParam(event, 'id') ?? ''
-  const expected = process.env.AW_DAQ_INGEST_TOKEN
-  if (expected) {
-    if (String(getHeader(event, 'x-aw-daq-token') ?? '') !== expected) {
-      throw new AppError(401, 'UNAUTHORIZED', '数采推送鉴权失败:请提供正确的 x-aw-daq-token(AW_DAQ_INGEST_TOKEN)。')
-    }
-  }
-  else {
-    resolveUser(event)
-  }
-
-  const node = getDaqController().byId(id)
-  if (!node) throw new AppError(404, 'NOT_FOUND', `数采节点不存在: ${id}`)
-  if (!node.enabled) throw new AppError(409, 'CONFLICT', `数采节点「${node.name}」已停用,不接受推送。`)
-  const tpl = findDaqTemplate(node.templateKey)
-  const kind = tpl?.signalKind ?? 'scalar'
-  const body = await readBody<IngestBody>(event) ?? {}
-
-  const now = Date.now()
-  const atRaw = String(body.at ?? '').trim()
-  const atMs = atRaw ? Date.parse(atRaw) : now
-  if (!Number.isFinite(atMs)) throw new AppError(400, 'VALIDATION_ERROR', `at 不是合法时间: ${atRaw}(示例 2026-10-19T12:00:00+08:00)`)
-  if (Math.abs(atMs - now) > AT_RANGE_MS) throw new AppError(400, 'VALIDATION_ERROR', 'at 超出允许范围(±7 天),请检查时区/时钟。')
-  const at = new Date(atMs).toISOString()
-  const state = ['ok', 'warn', 'alarm', 'offline'].includes(String(body.state ?? '')) ? String(body.state) : 'ok'
-  const metrics = metricsOf(body.metrics)
-  let env: DaqSampleEnvelope
-
-  if (kind === 'image') {
-    const img = body.image
-    const base64 = typeof img === 'string'
-      ? img
-      : String(img?.base64 ?? img?.data ?? '').trim()
-    if (!base64) throw new AppError(400, 'VALIDATION_ERROR', '图像节点的载荷必须提供 image.base64(或 image.data)。')
-    const mime = typeof img === 'object' && img?.mime ? String(img.mime) : 'image/png'
-    if (!/^image\//i.test(mime)) throw new AppError(400, 'VALIDATION_ERROR', `image.mime 必须是 image/*(收到 ${mime})`)
-    let buf: Buffer
-    try {
-      buf = Buffer.from(base64.replace(/^data:[^,]+,/, ''), 'base64')
-    }
-    catch {
-      throw new AppError(400, 'VALIDATION_ERROR', 'image.base64 解码失败。')
-    }
-    if (buf.length === 0) throw new AppError(400, 'VALIDATION_ERROR', '图像内容为空。')
-    if (buf.length > IMAGE_MAX_BYTES) throw new AppError(413, 'PAYLOAD_TOO_LARGE', `图像超过 ${IMAGE_MAX_BYTES / 1024 / 1024}MB 上限。`)
-    const objectKey = daqObjectKey(node.id, atMs, mime.includes('jpeg') ? '.jpg' : mime.includes('webp') ? '.webp' : '.png')
-    await getObjectStore().put(objectKey, buf, mime)
-    const sha256 = createHash('sha256').update(buf).digest('hex')
-    const width = Number(body.image && typeof body.image === 'object' ? body.image.width : NaN)
-    const height = Number(body.image && typeof body.image === 'object' ? body.image.height : NaN)
-    env = {
-      nodeId: node.id,
-      templateRef: node.templateRef,
-      value: Number((metrics.avg ?? 0).toFixed(node.decimals)),
-      state,
-      at,
-      frame: {
-        kind: 'image',
-        objectKey,
-        mime,
-        width: Number.isFinite(width) ? width : undefined,
-        height: Number.isFinite(height) ? height : undefined,
-        sha256,
-        size: buf.length,
-        metrics,
-      },
-    }
-  }
-  else if (kind === 'vector') {
-    const points = finiteList(body.points ?? body.values)
-    if (!points || points.length === 0) throw new AppError(400, 'VALIDATION_ERROR', '向量节点的载荷必须提供 points 数组。')
-    if (points.length > VECTOR_MAX_POINTS) throw new AppError(413, 'PAYLOAD_TOO_LARGE', `向量点数 ${points.length} 超过 ${VECTOR_MAX_POINTS} 上限。`)
-    const avg = points.reduce((a, b) => a + b, 0) / points.length
-    env = {
-      nodeId: node.id,
-      templateRef: node.templateRef,
-      value: Number((metrics.avg ?? avg).toFixed(node.decimals)),
-      state,
-      at,
-      frame: { kind: 'vector', points, metrics },
-    }
-  }
-  else {
-    const value = Number(body.value)
-    if (!Number.isFinite(value)) throw new AppError(400, 'VALIDATION_ERROR', '标量节点的载荷必须提供数值 value。')
-    env = { nodeId: node.id, templateRef: node.templateRef, value, state, at }
-  }
-
-  await getDaqQueue().then(q => q.publish(env))
-  return {
-    accepted: true,
-    nodeId: node.id,
-    kind,
-    at,
-    lineId: node.lineId ?? null,
-    ...(env.frame?.kind === 'image' ? { objectKey: env.frame.objectKey, bytes: env.frame.size } : {}),
-    ...(env.frame?.kind === 'vector' ? { points: env.frame.points?.length } : {}),
-  }
-})
+/**
+ * POST /api/workshop/daq/:id/ingest —— 外部 API 推送多源异构数采样本。
+ *
+ * 适用:第三方/边缘系统每次调用返回一张图片或一个数组(如膜厚模头点位数组),
+ * 由调用方主动推入本平台,走与网关采样完全相同的队列/入库/打标/告警链路。
+ *
+ * body:
+ *   { at?: ISO, value?: number, points?: number[], metrics?: {k:number},
+ *     state?: 'ok'|'warn'|'alarm'|'offline',
+ *     image?: { base64|data: string, mime?: string, width?: number, height?: number } | string }
+ *
+ * 鉴权:
+ *   - 配置了 AW_DAQ_INGEST_TOKEN 时,要求 x-aw-daq-token 头匹配(外部系统接入);
+ *   - 未配置时退回仪表盘用户会话(resolveUser),且**必须对该节点所属产线有 operate 权限**(WP2)。
+ * 约束:
+ *   - 节点必须存在且启用;载荷形态必须与模板 signalKind 一致(scalar/vector/image);
+ *   - 向量 1..4096 个有限数;图像 ≤10MB 且 MIME image/*;
+ *   - at 缺省=当前时间,回填窗默认 ±1h(env AW_DAQ_INGEST_BACKFILL_MS 可调,上限 7 天)。
+ */
+import { createHash } from 'node:crypto'
+import { getHeader, getRouterParam, readBody } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDaqController } from '@/server/services/workshop/daq/daq-controller'
+import { findDaqTemplate } from '@/server/services/workshop/daq/daq-templates'
+import { getDaqQueue } from '@/server/services/workshop/daq/bus'
+import { getObjectStore } from '@/server/services/workshop/daq/objectstore'
+import { daqObjectKey } from '@/server/services/workshop/daq/objectstore/objectstore-port'
+import type { DaqSampleEnvelope } from '@/server/services/workshop/daq/bus/queue-port'
+import { ingestAuthMode, ingestBackfillWindowMs, isWideBackfillWindow, withinBackfillWindow } from '@/server/services/workshop/daq/ingest-policy'
+import { recordOps } from '@/server/services/workshop/ops/ops'
+import { AppError } from '@/server/utils/errors'
+
+const IMAGE_MAX_BYTES = 10 * 1024 * 1024
+const VECTOR_MAX_POINTS = 4096
+/** 超宽回填窗告警只发一次(模块级;启动/首请求可见) */
+let wideWindowWarned = false
+
+interface IngestBody {
+  at?: string
+  value?: number | string
+  points?: unknown
+  values?: unknown
+  metrics?: Record<string, unknown>
+  state?: string
+  image?: { base64?: string, data?: string, mime?: string, width?: number, height?: number } | string
+}
+
+function finiteList(raw: unknown): number[] | null {
+  if (!Array.isArray(raw)) return null
+  const out: number[] = []
+  for (const x of raw) {
+    const n = Number(x)
+    if (!Number.isFinite(n)) return null
+    out.push(n)
+  }
+  return out
+}
+
+function metricsOf(raw: unknown): Record<string, number> {
+  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) return {}
+  const out: Record<string, number> = {}
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>).slice(0, 64)) {
+    const n = Number(v)
+    if (Number.isFinite(n) && k.trim()) out[k.trim().slice(0, 80)] = n
+  }
+  return out
+}
+
+export default defineApiHandler(async (event) => {
+  const id = getRouterParam(event, 'id') ?? ''
+  const node = getDaqController().byId(id)
+  if (!node) throw new AppError(404, 'NOT_FOUND', `数采节点不存在: ${id}`)
+
+  // ── 鉴权(WP2)────────────────────────────────────────────────────────────
+  // token 路径:边缘系统全局凭据(AW_DAQ_INGEST_TOKEN),语义不变;
+  // 兜底会话路径:必须对该节点所属产线有 operate 权限 —— 此前仅 resolveUser,
+  // 任意注册用户可向任意节点注入(含回填)伪造样本污染训练链。
+  {
+    const mode = ingestAuthMode({
+      configuredToken: process.env.AW_DAQ_INGEST_TOKEN,
+      providedToken: String(getHeader(event, 'x-aw-daq-token') ?? ''),
+    })
+    if (mode === 'token-mismatch') {
+      throw new AppError(401, 'UNAUTHORIZED', '数采推送鉴权失败:请提供正确的 x-aw-daq-token(AW_DAQ_INGEST_TOKEN)。')
+    }
+    if (mode === 'session') {
+      const user = resolveUser(event)
+      const { requireLineMode } = await import('@/server/services/workshop/permissions')
+      requireLineMode(user, node.lineId, 'operate')
+    }
+    if (isWideBackfillWindow() && !wideWindowWarned) {
+      wideWindowWarned = true
+      console.warn(`[daq.ingest] AW_DAQ_INGEST_BACKFILL_MS=${ingestBackfillWindowMs()} 超过默认 1h 安全窗(回填投毒面扩大)`)
+      recordOps({
+        actor: 'system', actorName: 'daq.ingest', actorKind: 'system',
+        action: 'policy.degrade.warn', kind: 'system', level: 'warn',
+        targetKind: 'system', targetId: 'daq.ingest.backfill',
+        summary: `数采推送回填窗被配置为 ${Math.round(ingestBackfillWindowMs() / 3600_000)}h(默认 1h,上限 7d)`,
+      })
+    }
+  }
+
+  if (!node.enabled) throw new AppError(409, 'CONFLICT', `数采节点「${node.name}」已停用,不接受推送。`)
+  const tpl = findDaqTemplate(node.templateKey)
+  const kind = tpl?.signalKind ?? 'scalar'
+  const body = await readBody<IngestBody>(event) ?? {}
+
+  const now = Date.now()
+  const atRaw = String(body.at ?? '').trim()
+  const atMs = atRaw ? Date.parse(atRaw) : now
+  if (!Number.isFinite(atMs)) throw new AppError(400, 'VALIDATION_ERROR', `at 不是合法时间: ${atRaw}(示例 2026-10-19T12:00:00+08:00)`)
+  const windowMs = ingestBackfillWindowMs()
+  if (!withinBackfillWindow(atMs, now, windowMs)) {
+    throw new AppError(400, 'VALIDATION_ERROR', `at 超出允许范围(±${Math.round(windowMs / 60_000)} 分钟),请检查时区/时钟。`)
+  }
+  const at = new Date(atMs).toISOString()
+  const state = ['ok', 'warn', 'alarm', 'offline'].includes(String(body.state ?? '')) ? String(body.state) : 'ok'
+  const metrics = metricsOf(body.metrics)
+  let env: DaqSampleEnvelope
+
+  if (kind === 'image') {
+    const img = body.image
+    const base64 = typeof img === 'string'
+      ? img
+      : String(img?.base64 ?? img?.data ?? '').trim()
+    if (!base64) throw new AppError(400, 'VALIDATION_ERROR', '图像节点的载荷必须提供 image.base64(或 image.data)。')
+    const mime = typeof img === 'object' && img?.mime ? String(img.mime) : 'image/png'
+    if (!/^image\//i.test(mime)) throw new AppError(400, 'VALIDATION_ERROR', `image.mime 必须是 image/*(收到 ${mime})`)
+    let buf: Buffer
+    try {
+      buf = Buffer.from(base64.replace(/^data:[^,]+,/, ''), 'base64')
+    }
+    catch {
+      throw new AppError(400, 'VALIDATION_ERROR', 'image.base64 解码失败。')
+    }
+    if (buf.length === 0) throw new AppError(400, 'VALIDATION_ERROR', '图像内容为空。')
+    if (buf.length > IMAGE_MAX_BYTES) throw new AppError(413, 'PAYLOAD_TOO_LARGE', `图像超过 ${IMAGE_MAX_BYTES / 1024 / 1024}MB 上限。`)
+    const objectKey = daqObjectKey(node.id, atMs, mime.includes('jpeg') ? '.jpg' : mime.includes('webp') ? '.webp' : '.png')
+    await getObjectStore().put(objectKey, buf, mime)
+    const sha256 = createHash('sha256').update(buf).digest('hex')
+    const width = Number(body.image && typeof body.image === 'object' ? body.image.width : NaN)
+    const height = Number(body.image && typeof body.image === 'object' ? body.image.height : NaN)
+    env = {
+      nodeId: node.id,
+      templateRef: node.templateRef,
+      value: Number((metrics.avg ?? 0).toFixed(node.decimals)),
+      state,
+      at,
+      frame: {
+        kind: 'image',
+        objectKey,
+        mime,
+        width: Number.isFinite(width) ? width : undefined,
+        height: Number.isFinite(height) ? height : undefined,
+        sha256,
+        size: buf.length,
+        metrics,
+      },
+    }
+  }
+  else if (kind === 'vector') {
+    const points = finiteList(body.points ?? body.values)
+    if (!points || points.length === 0) throw new AppError(400, 'VALIDATION_ERROR', '向量节点的载荷必须提供 points 数组。')
+    if (points.length > VECTOR_MAX_POINTS) throw new AppError(413, 'PAYLOAD_TOO_LARGE', `向量点数 ${points.length} 超过 ${VECTOR_MAX_POINTS} 上限。`)
+    const avg = points.reduce((a, b) => a + b, 0) / points.length
+    env = {
+      nodeId: node.id,
+      templateRef: node.templateRef,
+      value: Number((metrics.avg ?? avg).toFixed(node.decimals)),
+      state,
+      at,
+      frame: { kind: 'vector', points, metrics },
+    }
+  }
+  else {
+    const value = Number(body.value)
+    if (!Number.isFinite(value)) throw new AppError(400, 'VALIDATION_ERROR', '标量节点的载荷必须提供数值 value。')
+    env = { nodeId: node.id, templateRef: node.templateRef, value, state, at }
+  }
+
+  await getDaqQueue().then(q => q.publish(env))
+  return {
+    accepted: true,
+    nodeId: node.id,
+    kind,
+    at,
+    lineId: node.lineId ?? null,
+    ...(env.frame?.kind === 'image' ? { objectKey: env.frame.objectKey, bytes: env.frame.size } : {}),
+    ...(env.frame?.kind === 'vector' ? { points: env.frame.points?.length } : {}),
+  }
+})

package/server/api/workshop/ontology/drafts/[draftId]/compile.ts

@@ -0,0 +1,39 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/compile — 编译预览(四类产物 + Rule Trace;不落库)
+ *
+ * body.currentBounds 可选(现行权威界):提供时强制「只收紧」。
+ * body.approvedOnly 可选:true 时模拟发布路径(未获批硬约束将被拒)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, compileDraft } from '@/server/services/workshop/ontology/ontology.service'
+import type { CompileOptions } from '@/server/services/workshop/ontology/contracts'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const currentBounds = body.currentBounds as CompileOptions['currentBounds'] | undefined
+  const preview = compileDraft(draftId, actorFromUser(user), {
+    approvedOnly: body.approvedOnly === true,
+    currentBounds,
+  })
+  return {
+    status: preview.result.status,
+    contentHash: preview.contentHash,
+    packHash: preview.packHash,
+    rulePackHash: preview.result.rulePackHash,
+    counts: {
+      compiled: preview.result.compiledCount,
+      guard: preview.result.guardCount,
+      explained: preview.result.explainedCount,
+      rejected: preview.result.rejectedCount,
+    },
+    artifacts: preview.result.artifacts,
+    traces: preview.result.traces,
+    issues: preview.result.issues,
+  }
+})

package/server/api/workshop/ontology/drafts/[draftId]/evidence.ts

@@ -0,0 +1,33 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/evidence — 登记证据(追加账本 + 写回草稿)
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, appendEvidence } from '@/server/services/workshop/ontology/ontology.service'
+
+const TARGET_KINDS = new Set(['entity', 'relation', 'rule', 'binding'])
+const LEVELS = new Set(['candidate_influence', 'observed_correlation', 'validated_control'])
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const targetKind = String(body.targetKind ?? '')
+  const level = String(body.level ?? '')
+  if (!TARGET_KINDS.has(targetKind)) throw new AppError(422, 'EVIDENCE_TARGET_INVALID', `targetKind 必须是 entity|relation|rule|binding(收到 ${targetKind})`)
+  if (!LEVELS.has(level)) throw new AppError(422, 'EVIDENCE_LEVEL_INVALID', `level 必须是 candidate_influence|observed_correlation|validated_control(收到 ${level})`)
+  const source = body.source
+  if (!source || typeof source !== 'object') throw new AppError(422, 'EVIDENCE_SOURCE_REQUIRED', 'source 必填(如 {type:"dataset_stats",datasetId,sha256})')
+  const detail = appendEvidence(draftId, actorFromUser(user), {
+    targetKind: targetKind as 'entity' | 'relation' | 'rule' | 'binding',
+    targetKey: String(body.targetKey ?? ''),
+    level: level as 'candidate_influence' | 'observed_correlation' | 'validated_control',
+    source: source as Parameters<typeof appendEvidence>[2]['source'],
+    sourceRef: typeof body.sourceRef === 'string' ? body.sourceRef : undefined,
+    note: typeof body.note === 'string' ? body.note : undefined,
+  })
+  return { draft: { id: detail.draft.id, rev: detail.draft.rev }, validation: detail.validation }
+})

package/server/api/workshop/ontology/drafts/[draftId]/publish.ts

@@ -0,0 +1,44 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/publish — 冻结为不可变版本(仅 admin)
+ *
+ * body.currentBounds 可选(提供时编译期强制「只收紧」)。
+ * 失败语义:422 VALIDATION_BLOCKED / ONTOLOGY_BINDING_INVALID / ONTOLOGY_NOT_APPROVED;
+ *           409 ONTOLOGY_VERSION_CONFLICT(并发发布)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireAdmin } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, getDraft, publishDraft } from '@/server/services/workshop/ontology/ontology.service'
+import type { CompileOptions } from '@/server/services/workshop/ontology/contracts'
+import { recordConfigAction } from '@/server/services/workshop/optimization/access'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireAdmin(event)
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const result = publishDraft(draftId, actorFromUser(user), {
+    currentBounds: body.currentBounds as CompileOptions['currentBounds'] | undefined,
+  })
+  const draft = getDraft(draftId)
+  recordConfigAction(user, 'ontology.publish', { kind: 'ontology_version', id: `${result.version.id}@${result.version.version}` },
+    `发布本体 ${result.version.id}@${result.version.version}(编译 ${result.compile.compiledCount} / 守卫 ${result.compile.guardCount})`,
+    { ontologyId: result.version.id, version: result.version.version, packHash: result.packHash, revision: draft.rev })
+  return {
+    version: {
+      id: result.version.id, version: result.version.version, status: result.version.status,
+      contentHash: result.version.contentHash, parentVersion: result.version.parentVersion,
+      lineId: result.version.lineId, createdAt: result.version.createdAt,
+    },
+    packHash: result.packHash,
+    counts: {
+      compiled: result.compile.compiledCount,
+      guard: result.compile.guardCount,
+      explained: result.compile.explainedCount,
+      rejected: result.compile.rejectedCount,
+    },
+    issues: result.compile.issues,
+    draftRev: result.draft.rev,
+  }
+})

package/server/api/workshop/ontology/drafts/[draftId]/rules/[ruleId]/approval-decision.ts

@@ -0,0 +1,28 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/rules/:ruleId/approval-decision — 裁决批准申请
+ * body: { approvalId, approved, comment? }
+ *
+ * 自审禁止:起草人不能裁决自己的申请(单管理员实例由服务层打 solo_operator 豁免)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, decideRuleApproval } from '@/server/services/workshop/ontology/ontology.service'
+import { recordConfigAction } from '@/server/services/workshop/optimization/access'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const approvalId = String(body.approvalId ?? '')
+  if (!approvalId) throw new AppError(422, 'APPROVAL_ID_REQUIRED', 'approvalId 必填')
+  const result = decideRuleApproval(draftId, approvalId, actorFromUser(user), {
+    approved: body.approved === true,
+    comment: typeof body.comment === 'string' ? body.comment : undefined,
+  })
+  recordConfigAction(user, 'ontology.rule.decide', { kind: 'ontology_approval', id: approvalId },
+    `裁决本体规则批准 ${approvalId}:${result.decision}`)
+  return result
+})

package/server/api/workshop/ontology/drafts/[draftId]/rules/[ruleId]/approval.ts

@@ -0,0 +1,17 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/rules/:ruleId/approval — 申请控制级批准(第二人裁决)
+ * 返回 { approvalId };后续 POST /api/workshop/ontology/approvals/:approvalId/decide。
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, requestRuleApproval } from '@/server/services/workshop/ontology/ontology.service'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  const ruleId = getRouterParam(event, 'ruleId') ?? ''
+  if (!draftId || !ruleId) throw new AppError(422, 'RULE_ID_REQUIRED', 'draftId/ruleId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  return requestRuleApproval(draftId, ruleId, actorFromUser(user))
+})

package/server/api/workshop/ontology/drafts/[draftId]/rules/[ruleId]/transition.ts

@@ -0,0 +1,32 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/rules/:ruleId/transition — 规则状态迁移
+ * body: { to, approvalId?, comment? }
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { ONTOLOGY_STATES, type OntologyState } from '@/server/services/workshop/ontology/contracts'
+import { actorFromUser, transitionRule } from '@/server/services/workshop/ontology/ontology.service'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  const ruleId = getRouterParam(event, 'ruleId') ?? ''
+  if (!draftId || !ruleId) throw new AppError(422, 'RULE_ID_REQUIRED', 'draftId/ruleId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const to = String(body.to ?? '') as OntologyState
+  if (!(ONTOLOGY_STATES as readonly string[]).includes(to)) {
+    throw new AppError(422, 'RULE_STATE_INVALID', `to 必须是 ${ONTOLOGY_STATES.join('|')}(收到 ${to})`)
+  }
+  const detail = transitionRule(draftId, ruleId, actorFromUser(user), {
+    to,
+    approvalId: typeof body.approvalId === 'string' ? body.approvalId : undefined,
+    comment: typeof body.comment === 'string' ? body.comment : undefined,
+  })
+  return {
+    draft: { id: detail.draft.id, rev: detail.draft.rev },
+    rule: detail.doc.rules.find(r => r.id === ruleId || r.key === ruleId),
+    validation: detail.validation,
+  }
+})

package/server/api/workshop/ontology/drafts/[draftId]/validate.ts

@@ -0,0 +1,16 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/validate — 全量校验(结构+活体绑定)
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, validateDraft } from '@/server/services/workshop/ontology/ontology.service'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const report = validateDraft(draftId, actorFromUser(user))
+  return report
+})