agentworkshop 0.7.65 → 0.7.70

package/server/services/workshop/dcw/drivers/mes-rest.ts

@@ -14,7 +14,7 @@ import { lookup } from 'node:dns/promises'
 import { isIP } from 'node:net'
 import { AppError } from '../../../../utils/errors'
 import { mesWriteCheckHookCode, mesWriteHookCode, runMesWriteCheckHook, runMesWriteHook } from '../../mes/mes-hook'
-import type { DcwFetchHistoryInput, DcwFetchHistoryResult, DcwHistoryFormat, DcwHistoryRow, DcwReadInput, DcwReadResult, DcwWriteDriver, DcwWriteInput, DcwWriteResult } from './shared'
+import type { DcwFetchHistoryInput, DcwFetchHistoryResult, DcwFieldDef, DcwHistoryFormat, DcwHistoryRow, DcwReadInput, DcwReadResult, DcwWriteDriver, DcwWriteInput, DcwWriteResult } from './shared'
 import { num, readbackAck } from './shared'
 
 // ============================================================
@@ -26,7 +26,9 @@ interface MesReadMap {
   path: string
   query: Record<string, string>
   headers: Record<string, string>
-  response: { valuePath: string, tsPath?: string, tsFormat?: 'epoch_s' | 'epoch_ms' | 'iso' }
+  /** 响应内字段字典路径(可选;数组/对象/含 fields 数组的对象均可) */
+  dictionaryPath?: string
+  response: { valuePath: string, tsPath?: string, tsFormat?: 'epoch_s' | 'epoch_ms' | 'iso', dictionaryPath?: string }
 }
 
 interface MesWriteMap {
@@ -46,6 +48,8 @@ interface MesHistoryMap {
   path: string
   query: Record<string, string>
   headers: Record<string, string>
+  /** 响应内字段字典路径(可选;MES 随历史响应返回字段含义/单位) */
+  dictionaryPath?: string
   response: {
     rowsPath: string
     /** scalar 行数值路径(format=scalar 时必填;其余格式可省) */
@@ -59,6 +63,8 @@ interface MesHistoryMap {
     dataPath?: string
     mimePath?: string
     nextCursorPath?: string
+    /** 字段字典路径(与 historyMap.dictionaryPath 等价;response 内优先) */
+    dictionaryPath?: string
   }
   pageSize?: number
   maxPages: number
@@ -114,7 +120,13 @@ function parseReadMap(cfg: Record<string, unknown>): MesReadMap | null {
     path: reqString(rec, 'path', 'readMap'),
     query: stringRecord(rec.query, 'readMap.query'),
     headers: stringRecord(rec.headers, 'readMap.headers'),
-    response: { valuePath: reqString(resp, 'valuePath', 'readMap.response'), tsPath: optString(resp.tsPath), tsFormat: fmt },
+    dictionaryPath: optString(rec.dictionaryPath),
+    response: {
+      valuePath: reqString(resp, 'valuePath', 'readMap.response'),
+      tsPath: optString(resp.tsPath),
+      tsFormat: fmt,
+      dictionaryPath: optString(resp.dictionaryPath),
+    },
   }
 }
 
@@ -169,6 +181,7 @@ function parseHistoryMap(cfg: Record<string, unknown>): MesHistoryMap | null {
     path: reqString(rec, 'path', 'historyMap'),
     query: stringRecord(rec.query, 'historyMap.query'),
     headers: stringRecord(rec.headers, 'historyMap.headers'),
+    dictionaryPath: optString(rec.dictionaryPath),
     response: {
       rowsPath: reqString(resp, 'rowsPath', 'historyMap.response'),
       valuePath,
@@ -178,6 +191,7 @@ function parseHistoryMap(cfg: Record<string, unknown>): MesHistoryMap | null {
       dataPath,
       mimePath: optString(resp.mimePath),
       nextCursorPath: optString(resp.nextCursorPath),
+      dictionaryPath: optString(resp.dictionaryPath),
     },
     pageSize: pageSize !== undefined && Number.isFinite(pageSize) && pageSize > 0 ? pageSize : undefined,
     maxPages: Number.isFinite(maxPages) && maxPages > 0 ? maxPages : 40,
@@ -458,6 +472,124 @@ function extract(root: unknown, dotted: string): unknown {
   return expanded ? level : level[0]
 }
 
+// ============================================================
+// 字段字典归一(MES 响应 → Agent 可读的物理含义)
+// ============================================================
+
+const DICT_ENTRY_CAP = 256
+const DICT_POINT_CAP = 4096
+
+const strOf = (v: unknown, max = 300): string | undefined => {
+  if (v === null || v === undefined) return undefined
+  const s = String(v).trim()
+  return s === '' ? undefined : s.slice(0, max)
+}
+
+const numOf = (v: unknown): number | undefined => {
+  if (v === null || v === undefined || v === '') return undefined
+  const n = Number(v)
+  return Number.isFinite(n) ? n : undefined
+}
+
+function normalizeDictEntry(raw: unknown, fallbackField?: string, fallbackIndex?: number): DcwFieldDef | null {
+  if (raw === null || raw === undefined) return null
+  if (typeof raw === 'string') {
+    const field = fallbackField ?? strOf(raw, 80)
+    return field ? { field, label: strOf(raw) } : null
+  }
+  if (typeof raw !== 'object' || Array.isArray(raw)) return null
+  const rec = raw as Record<string, unknown>
+  const field = strOf(rec.field ?? rec.key ?? rec.name ?? rec.tag, 80) ?? fallbackField
+    ?? (fallbackIndex !== undefined ? `v${fallbackIndex}` : undefined)
+  if (!field) return null
+  const kindRaw = strOf(rec.kind ?? rec.type, 16)
+  const kind = kindRaw === 'scalar' || kindRaw === 'vector' || kindRaw === 'point' ? kindRaw : undefined
+  const out: DcwFieldDef = { field }
+  const label = strOf(rec.label ?? rec.title ?? rec.ch ?? rec.description ?? rec.desc ?? rec.meaning ?? rec.semantics)
+  if (label) out.label = label
+  const unit = strOf(rec.unit ?? rec.uom ?? rec.unit_of_measure, 40)
+  if (unit) out.unit = unit
+  const description = strOf(rec.description ?? rec.desc ?? rec.meaning ?? rec.semantics ?? rec.note)
+  if (description) out.description = description
+  const min = numOf(rec.min ?? rec.lsl ?? rec.lower)
+  const max = numOf(rec.max ?? rec.usl ?? rec.upper)
+  if (min !== undefined) out.min = min
+  if (max !== undefined) out.max = max
+  if (kind) out.kind = kind
+  const index = numOf(rec.index ?? rec.idx ?? rec.position ?? fallbackIndex)
+  if (index !== undefined && Number.isInteger(index) && index >= 0) out.index = index
+  const points = Array.isArray(rec.points) ? rec.points.slice(0, DICT_POINT_CAP) : null
+  if (points) {
+    out.points = points
+      .map((p, i) => normalizeDictEntry(p, undefined, i))
+      .filter((p): p is DcwFieldDef => p !== null)
+  }
+  return out
+}
+
+/**
+ * 把 MES 返回的数据字典归一成 DcwFieldDef[]。
+ * 支持三种常见形态:
+ *   1) [{field,label,unit,...}, ...]
+ *   2) { fields:[...], units:{field:unit}, labels:{field:label}, descriptions:{field:text} }
+ *   3) { fieldName:{label,unit,...}, other:{...} }
+ * 解析失败/空对象 → [] (不抛:字典是增强信息,不能击穿取数)。
+ */
+export function normalizeMesDictionary(raw: unknown): DcwFieldDef[] {
+  if (raw === null || raw === undefined) return []
+  let body: unknown = raw
+  if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
+    const rec = body as Record<string, unknown>
+    // 常见包裹:data / dictionary / meta
+    for (const k of ['dictionary', 'fields', 'schema', 'meta', 'data']) {
+      const v = rec[k]
+      if (v !== undefined && v !== null && typeof v === 'object') {
+        body = v
+        break
+      }
+    }
+  }
+  if (Array.isArray(body)) {
+    return body.slice(0, DICT_ENTRY_CAP)
+      .map((x, i) => normalizeDictEntry(x, undefined, i))
+      .filter((x): x is DcwFieldDef => x !== null)
+  }
+  if (body === null || typeof body !== 'object') return []
+  const rec = body as Record<string, unknown>
+  if (Array.isArray(rec.fields)) {
+    const units = rec.units !== null && typeof rec.units === 'object' && !Array.isArray(rec.units)
+      ? rec.units as Record<string, unknown>
+      : {}
+    const labels = rec.labels !== null && typeof rec.labels === 'object' && !Array.isArray(rec.labels)
+      ? rec.labels as Record<string, unknown>
+      : {}
+    const descriptions = rec.descriptions !== null && typeof rec.descriptions === 'object' && !Array.isArray(rec.descriptions)
+      ? rec.descriptions as Record<string, unknown>
+      : {}
+    return rec.fields.slice(0, DICT_ENTRY_CAP)
+      .map((x, i) => {
+        const one = normalizeDictEntry(x, undefined, i)
+        if (!one) return null
+        if (one.unit === undefined && units[one.field] !== undefined) one.unit = strOf(units[one.field], 40)
+        if (one.label === undefined && labels[one.field] !== undefined) one.label = strOf(labels[one.field])
+        if (one.description === undefined && descriptions[one.field] !== undefined) one.description = strOf(descriptions[one.field])
+        return one
+      })
+      .filter((x): x is DcwFieldDef => x !== null)
+  }
+  // 对象映射:key = 字段名
+  return Object.entries(rec).slice(0, DICT_ENTRY_CAP)
+    .map(([k, v]) => normalizeDictEntry(v, k))
+    .filter((x): x is DcwFieldDef => x !== null)
+}
+
+/** 字典路径取值:优先 response 内路径,回落 historyMap/readMap 顶层路径;无路径 → [] */
+function dictionaryOf(json: unknown, map: { dictionaryPath?: string, response: { dictionaryPath?: string } }): DcwFieldDef[] {
+  const path = map.response.dictionaryPath ?? map.dictionaryPath
+  if (!path) return []
+  return normalizeMesDictionary(extract(json, path))
+}
+
 /** 数值归一(数值/数值字符串 → 有限数,其余 undefined) */
 function toFinite(v: unknown): number | undefined {
   if (v === null || v === undefined || v === '') return undefined
@@ -484,14 +616,14 @@ function tsToIso(raw: unknown, fmt?: 'epoch_s' | 'epoch_ms' | 'iso'): string | n
   return String(raw)
 }
 
-/** readMap 一次取数:valuePath 数值 + tsPath 归一 ISO(HTTP 非 2xx 抛分类错误) */
-async function readOnce(cfg: Record<string, unknown>, map: MesReadMap): Promise<{ value: number | null, tsIso: string | null }> {
+/** readMap 一次取数:valuePath 数值 + tsPath 归一 ISO + 可选字段字典(HTTP 非 2xx 抛分类错误) */
+async function readOnce(cfg: Record<string, unknown>, map: MesReadMap): Promise<{ value: number | null, tsIso: string | null, dictionary: DcwFieldDef[] }> {
   const { path, query } = applyPathTemplate(map.path, map.query)
   const { status, json } = await mesRequest(cfg, { method: map.method, path, query, headers: map.headers })
   if (status < 200 || status >= 300) throw new AppError(502, 'MES_HTTP_ERROR', classifyHttpFail(status))
   const value = toFinite(extract(json, map.response.valuePath))
   const tsIso = map.response.tsPath ? tsToIso(extract(json, map.response.tsPath), map.response.tsFormat) : null
-  return { value: value === undefined ? null : value, tsIso }
+  return { value: value === undefined ? null : value, tsIso, dictionary: dictionaryOf(json, map) }
 }
 
 // ============================================================
@@ -599,9 +731,11 @@ export const mesRestDcwDriver: DcwWriteDriver = {
       const cfg = input.driverConfig
       const map = parseReadMap(cfg)
       if (!map) return { ok: false, message: '未配置 readMap(当前值映射),无法读取', eng: null, raw: null }
-      const { value, tsIso } = await readOnce(cfg, map)
-      if (value === null) return { ok: false, message: `MES 响应中 valuePath(${map.response.valuePath})未提取到数值`, eng: null, raw: null }
-      return { ok: true, message: `MES 读数 ${Number(value.toFixed(4))},ts=${tsIso ?? '未提供'}`, eng: value, raw: value }
+      const { value, tsIso, dictionary } = await readOnce(cfg, map)
+      if (value === null) {
+        return { ok: false, message: `MES 响应中 valuePath(${map.response.valuePath})未提取到数值`, eng: null, raw: null, ...(dictionary.length > 0 ? { dictionary } : {}) }
+      }
+      return { ok: true, message: `MES 读数 ${Number(value.toFixed(4))},ts=${tsIso ?? '未提供'}`, eng: value, raw: value, ...(dictionary.length > 0 ? { dictionary } : {}) }
     }
     catch (err) {
       // 读是调度周期原语:一切失败(含配置错)收敛为 ok=false,不打断网关节拍
@@ -617,6 +751,7 @@ export const mesRestDcwDriver: DcwWriteDriver = {
     let rows = 0
     let pages = 0
     let complete = false
+    let dictionary: DcwFieldDef[] = []
     // 声明式分页:终止 = nextCursor 缺失/空(取完)或 rows>=maxRows 或 pages>maxPages
     while (rows < input.maxRows && pages < map.maxPages) {
       const query: Record<string, string> = { ...map.query, from: input.fromIso, to: input.toIso }
@@ -627,6 +762,7 @@ export const mesRestDcwDriver: DcwWriteDriver = {
       if (status < 200 || status >= 300) throw new AppError(502, 'MES_HTTP_ERROR', classifyHttpFail(status))
       const rawRows = extract(json, map.response.rowsPath)
       if (!Array.isArray(rawRows)) throw new AppError(502, 'MES_HTTP_ERROR', `historyMap.response.rowsPath(${map.response.rowsPath})未提取到数组`)
+      if (dictionary.length === 0) dictionary = dictionaryOf(json, map)
       const fmt = map.response.format
       const batch: DcwHistoryRow[] = []
       for (const row of rawRows) {
@@ -639,7 +775,18 @@ export const mesRestDcwDriver: DcwWriteDriver = {
           if (!Array.isArray(arr) || arr.length === 0) continue
           const values = arr.map(v => toFinite(v)).filter((x): x is number => x !== undefined)
           if (values.length === 0) continue
-          batch.push({ ts, values })
+          // 行级伴随字段(mean/lane_unit/peak_nm 等)单独保留:向量本体的语义/诊断信息
+          // 常在这些字段里,不能丢(不进 values 以免污染维度)
+          const meta: Record<string, unknown> = {}
+          if (row !== null && typeof row === 'object') {
+            const valuesKey = (map.response.valuesPath ?? '').split('.').pop() ?? ''
+            for (const [k, v] of Object.entries(row as Record<string, unknown>)) {
+              if (k === valuesKey) continue
+              if (typeof v === 'string' && v.length > 256) continue
+              meta[k] = v
+            }
+          }
+          batch.push({ ts, values, ...(Object.keys(meta).length > 0 ? { record: meta } : {}) })
         }
         else if (fmt === 'image') {
           // 图像帧:base64 提取(空串跳过);MIME 缺省 image/png。
@@ -680,7 +827,7 @@ export const mesRestDcwDriver: DcwWriteDriver = {
       }
       cursor = nextStr
     }
-    return { rows, complete }
+    return { rows, complete, ...(dictionary.length > 0 ? { dictionary } : {}) }
   },
 
   async test(driverConfig: Record<string, unknown>): Promise<{ ok: boolean, message: string }> {

package/server/services/workshop/dcw/drivers/shared.ts

@@ -72,6 +72,38 @@ export interface DcwReadResult {
   eng: number | null
   /** 原始值(寄存器解码;非寄存器驱动与 eng 同源) */
   raw: number | null
+  /** 数据字典(可选;MES 响应可携带字段级语义,供目录/取数/导出透传) */
+  dictionary?: DcwFieldDef[]
+}
+
+// ============================================================
+// 字段级数据字典(MES 多源异构数据的物理含义)
+// ============================================================
+
+/**
+ * 字段/点位语义。一个字段既可以是一个标量列,也可以是一个向量字段
+ * (points 描述向量每个下标/模头点位的含义)。
+ *
+ * 来源:优先由 MES API 随响应返回(dictionaryPath),其次由节点配置静态声明
+ * (driverConfig.dictionary);两者都缺省时 Agent 只能看到原始字段名。
+ */
+export interface DcwFieldDef {
+  /** 字段名(响应里的 key;向量点位用 field=profile 等) */
+  field: string
+  /** 人话标签(如 膜厚断面) */
+  label?: string
+  /** 物理单位(如 µm) */
+  unit?: string
+  /** 物理意义/判读说明 */
+  description?: string
+  min?: number
+  max?: number
+  /** 字段形态:scalar 标量列 / vector 向量列 / point 向量内点位 */
+  kind?: 'scalar' | 'vector' | 'point'
+  /** 向量点位下标(0-based;point 条目使用) */
+  index?: number
+  /** 向量字段的逐点语义(index 0..N-1) */
+  points?: DcwFieldDef[]
 }
 
 // ============================================================
@@ -94,7 +126,7 @@ export interface DcwHistoryRow {
   data?: string
   /** image:MIME(缺省 image/png) */
   mime?: string
-  /** table/event:原始记录(JSON 值) */
+  /** table/event:原始记录(JSON 值);vector:行级伴随字段(mean/lane_unit 等,不含向量本体) */
   record?: unknown
 }
 
@@ -117,6 +149,8 @@ export interface DcwFetchHistoryResult {
   rows: number
   /** true=nextCursor 自然耗尽取完;false=因 maxRows/maxPages 提前截断 */
   complete: boolean
+  /** 数据字典(可选;从响应首个非空页解析,随数据集 manifest/工具回包透传) */
+  dictionary?: DcwFieldDef[]
 }
 
 export const num = (v: unknown): number | undefined => {

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

@@ -0,0 +1,177 @@
+/**
+ * eda_charts 仓储(plan1 M2,含 BLOCKER B4 修正):
+ *
+ * 读路径(B4 铁律):
+ *  - private → 仅 owner / admin;
+ *  - line    → owner / admin / 该产线 readonly 及以上(按 chart.lineId 判,不看请求参数);
+ *  - public  → 首期不做;
+ *  - 列表谓词 = owner==user OR 可见性判定(不能用裸 filterByLine——它会把 lineId=NULL
+ *    的条目整条丢弃,owner 自己的私有无产线图表会从自己的列表里消失);
+ *  - 看板包含 chart 时的读判定也必须走 canReadChart(防看板旁路,见 dashboard 侧)。
+ * 写路径:owner / admin;visibility='line' 强制 line_id 非空。
+ * 数据访问永不代理:图表只存查询参数快照,取数永远在客户端调 /daq/query 时按请求鉴权。
+ */
+import { randomUUID } from 'node:crypto'
+import type { ResolvedUser } from '@/server/api/workshop/caller'
+import { lineMode } from '../permissions'
+import { recordOps } from '../ops/ops'
+import { edaDb } from './eda-db'
+
+export const CHART_VIZ_TYPES = ['trend', 'bar', 'scatter', 'table', 'kpi', 'histogram'] as const
+export type ChartVizType = typeof CHART_VIZ_TYPES[number]
+const VISIBILITIES = ['private', 'line'] as const
+
+export interface EdaChartRow {
+  id: string
+  title: string
+  vizType: ChartVizType
+  datasource: Record<string, unknown>
+  encoding: Record<string, unknown>
+  transform: Record<string, unknown>
+  options: Record<string, unknown>
+  annotations: unknown[]
+  ownerUserId: string
+  lineId: string | null
+  visibility: 'private' | 'line'
+  version: number
+  createdAt: string
+  updatedAt: string
+}
+
+function rowOf(r: Record<string, unknown>): EdaChartRow {
+  return {
+    id: String(r.id),
+    title: String(r.title ?? ''),
+    vizType: String(r.viz_type ?? 'trend') as ChartVizType,
+    datasource: safeObj(r.datasource_json),
+    encoding: safeObj(r.encoding_json),
+    transform: safeObj(r.transform_json),
+    options: safeObj(r.options_json),
+    annotations: safeArr(r.annotations_json),
+    ownerUserId: String(r.owner_user_id ?? ''),
+    lineId: r.line_id == null ? null : String(r.line_id),
+    visibility: String(r.visibility ?? 'private') as EdaChartRow['visibility'],
+    version: Number(r.version ?? 1),
+    createdAt: String(r.created_at ?? ''),
+    updatedAt: String(r.updated_at ?? ''),
+  }
+}
+function safeObj(text: unknown): Record<string, unknown> {
+  try {
+    return JSON.parse(String(text ?? '{}')) as Record<string, unknown>
+  }
+  catch {
+    return {}
+  }
+}
+function safeArr(text: unknown): unknown[] {
+  try {
+    return JSON.parse(String(text ?? '[]')) as unknown[]
+  }
+  catch {
+    return []
+  }
+}
+
+/** B4 读判定(单图;看板侧逐图复用) */
+export function canReadChart(user: ResolvedUser, row: EdaChartRow): boolean {
+  if (row.ownerUserId === user.id || user.role === 'admin') return true
+  if (row.visibility === 'line' && row.lineId) return lineMode(user, row.lineId) !== 'none'
+  return false
+}
+
+function canWriteChart(user: ResolvedUser, row: EdaChartRow): boolean {
+  return row.ownerUserId === user.id || user.role === 'admin'
+}
+
+export function chartById(user: ResolvedUser, id: string): EdaChartRow | null {
+  const r = edaDb().prepare('SELECT * FROM eda_charts WHERE id = ?').get(id) as Record<string, unknown> | undefined
+  if (!r) return null
+  const row = rowOf(r)
+  return canReadChart(user, row) ? row : null
+}
+
+export function listChartsFor(user: ResolvedUser, opts: { lineId?: string, mine?: boolean, limit?: number } = {}): EdaChartRow[] {
+  const limit = Math.min(Math.max(Math.round(Number(opts.limit)) || 100, 1), 500)
+  const rows = edaDb().prepare('SELECT * FROM eda_charts ORDER BY updated_at DESC LIMIT ?').all(limit) as Array<Record<string, unknown>>
+  return rows
+    .map(rowOf)
+    .filter(row => canReadChart(user, row))
+    .filter(row => (opts.mine ? row.ownerUserId === user.id : true))
+    .filter(row => (opts.lineId ? row.lineId === opts.lineId : true))
+}
+
+export interface ChartInput {
+  title: string
+  vizType: string
+  datasource?: Record<string, unknown>
+  encoding?: Record<string, unknown>
+  transform?: Record<string, unknown>
+  options?: Record<string, unknown>
+  lineId?: string | null
+  visibility?: string
+}
+
+function validateInput(input: ChartInput): void {
+  if (!CHART_VIZ_TYPES.includes(input.vizType as ChartVizType)) {
+    throw new Error(`viz_type 只支持 ${CHART_VIZ_TYPES.join('/')}(收到 ${input.vizType})`)
+  }
+  const vis = input.visibility ?? 'private'
+  if (!VISIBILITIES.includes(vis as 'private' | 'line')) {
+    throw new Error(`visibility 只支持 ${VISIBILITIES.join('/')}(public 首期不开放)`)
+  }
+  if (vis === 'line' && !input.lineId) {
+    throw new Error('visibility=line 必须携带 line_id(B4:产线可见图必须钉在产线上)')
+  }
+}
+
+export function createChart(user: ResolvedUser, input: ChartInput): EdaChartRow {
+  validateInput(input)
+  const id = `ec-${randomUUID().slice(0, 8)}`
+  const now = new Date().toISOString()
+  edaDb().prepare(`INSERT INTO eda_charts (id, title, viz_type, datasource_json, encoding_json, transform_json, options_json, annotations_json, owner_user_id, line_id, visibility, version, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, '[]', ?, ?, ?, 1, ?, ?)`)
+    .run(id, input.title, input.vizType,
+      JSON.stringify(input.datasource ?? {}), JSON.stringify(input.encoding ?? {}), JSON.stringify(input.transform ?? {}), JSON.stringify(input.options ?? {}),
+      user.id, input.lineId ?? null, input.visibility ?? 'private', now, now)
+  recordOps({
+    actor: user.id, actorName: user.name, actorKind: 'user',
+    action: 'chart.save', kind: 'system', targetKind: 'eda-chart', targetId: id,
+    summary: `保存图表「${input.title}」(${input.vizType},${input.visibility ?? 'private'})`,
+    detail: { vizType: input.vizType, visibility: input.visibility ?? 'private' },
+  })
+  return chartById(user, id)!
+}
+
+export function updateChart(user: ResolvedUser, id: string, patch: Partial<ChartInput> & { annotations?: unknown[] }): EdaChartRow {
+  const existing = edaDb().prepare('SELECT * FROM eda_charts WHERE id = ?').get(id) as Record<string, unknown> | undefined
+  if (!existing) throw new Error(`图表不存在: ${id}`)
+  const row = rowOf(existing)
+  if (!canWriteChart(user, row)) throw new Error('仅 owner 或 admin 可修改该图表。')
+  const merged: ChartInput = {
+    title: patch.title ?? row.title,
+    vizType: patch.vizType ?? row.vizType,
+    datasource: patch.datasource ?? row.datasource,
+    encoding: patch.encoding ?? row.encoding,
+    transform: patch.transform ?? row.transform,
+    options: patch.options ?? row.options,
+    lineId: patch.lineId !== undefined ? patch.lineId : row.lineId,
+    visibility: patch.visibility ?? row.visibility,
+  }
+  validateInput(merged)
+  edaDb().prepare(`UPDATE eda_charts SET title = ?, viz_type = ?, datasource_json = ?, encoding_json = ?, transform_json = ?, options_json = ?, annotations_json = ?, line_id = ?, visibility = ?, version = version + 1, updated_at = ? WHERE id = ?`)
+    .run(merged.title, merged.vizType,
+      JSON.stringify(merged.datasource ?? {}), JSON.stringify(merged.encoding ?? {}), JSON.stringify(merged.transform ?? {}), JSON.stringify(merged.options ?? {}),
+      JSON.stringify(patch.annotations ?? row.annotations),
+      merged.lineId ?? null, merged.visibility ?? 'private', new Date().toISOString(), id)
+  return chartById(user, id)!
+}
+
+export function deleteChart(user: ResolvedUser, id: string): boolean {
+  const existing = edaDb().prepare('SELECT * FROM eda_charts WHERE id = ?').get(id) as Record<string, unknown> | undefined
+  if (!existing) return false
+  if (!canWriteChart(user, rowOf(existing))) throw new Error('仅 owner 或 admin 可删除该图表。')
+  edaDb().prepare('DELETE FROM eda_dashboard_charts WHERE chart_id = ?').run(id)
+  edaDb().prepare('DELETE FROM eda_charts WHERE id = ?').run(id)
+  return true
+}

package/server/services/workshop/eda/commonality.ts

@@ -0,0 +1,106 @@
+/**
+ * E5 Commonality —— 坏批次共性分析(bad run 集合 × 因子的交叉统计 + lift)。
+ *
+ * bad 集 = 特征违例行涉及的全部 run(FDC violated=1;SPC 判异走 ops 审计不入本表,
+ * 后续项);因子 = node / chamber(E8 节点可选字段)/ recipe / hour(批次开始小时桶)。
+ * lift = P(bad|factor) / P(bad):>1 表示该因子取值下坏批占比高于基线。
+ * 查询形状:全部 GROUP BY 聚合,TS 只算占比(评审判定:纯封装)。
+ */
+import type { ResolvedUser } from '@/server/api/workshop/caller'
+import { lineMode } from '../permissions'
+import { edaDb } from './eda-db'
+import { getDaqNodeRepo } from '../daq/daq-node.repo'
+
+export type CommonalityFactor = 'node' | 'chamber' | 'recipe' | 'hour'
+
+export interface CommonalityRow {
+  factor: string
+  factorValue: string
+  runsTotal: number
+  runsBad: number
+  badRate: number
+  lift: number
+}
+
+export class CommonalityError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message)
+  }
+}
+
+export function commonality(user: ResolvedUser, args: {
+  lineId: string
+  factor: CommonalityFactor
+}): { factor: CommonalityFactor, baselineBadRate: number, runsTotal: number, rows: CommonalityRow[] } {
+  if (lineMode(user, args.lineId) === 'none') {
+    throw new CommonalityError(403, `产线 ${args.lineId} 不在你的可读范围内。`)
+  }
+  const db = edaDb()
+  const runsTotal = Number((db.prepare('SELECT COUNT(*) AS c FROM eda_runs WHERE line_id = ?').get(args.lineId) as { c: number }).c)
+  if (runsTotal === 0) return { factor: args.factor, baselineBadRate: 0, runsTotal: 0, rows: [] }
+  // 坏批集:该线特征违例行涉及的 run(去重)
+  const badSet = new Set(
+    (db.prepare(`SELECT DISTINCT f.run_id FROM eda_run_features f JOIN eda_runs r ON r.id = f.run_id
+      WHERE r.line_id = ? AND f.violated = 1`).all(args.lineId) as Array<{ run_id: string }>).map(x => x.run_id),
+  )
+  const baselineBadRate = badSet.size / runsTotal
+  const rows: CommonalityRow[] = []
+  if (args.factor === 'node' || args.factor === 'chamber') {
+    const nodes = getDaqNodeRepo().all().filter(n => n.lineId === args.lineId)
+    const valueOf = (nodeId: string): string | null => {
+      const n = nodes.find(x => x.id === nodeId)
+      if (!n) return null
+      if (args.factor === 'node') return n.id
+      return (n as unknown as { chamber?: string }).chamber || null
+    }
+    // 特征行面聚合:每个因子的涉及 run 数与违例 run 数
+    const feats = db.prepare(`SELECT f.node_id, f.run_id, f.violated FROM eda_run_features f JOIN eda_runs r ON r.id = f.run_id
+      WHERE r.line_id = ?`).all(args.lineId) as Array<{ node_id: string, run_id: string, violated: number }>
+    const byFactor = new Map<string, { runs: Set<string>, bad: Set<string> }>()
+    for (const f of feats) {
+      const v = valueOf(f.node_id)
+      if (!v) continue
+      const a = byFactor.get(v) ?? { runs: new Set<string>(), bad: new Set<string>() }
+      a.runs.add(f.run_id)
+      if (f.violated === 1 && badSet.has(f.run_id)) a.bad.add(f.run_id)
+      byFactor.set(v, a)
+    }
+    for (const [v, a] of byFactor) {
+      const badRate = a.runs.size ? a.bad.size / a.runs.size : 0
+      rows.push({ factor: args.factor, factorValue: v, runsTotal: a.runs.size, runsBad: a.bad.size, badRate: Number(badRate.toFixed(4)), lift: Number((badRate / baselineBadRate || 0).toFixed(4)) })
+    }
+  }
+  else if (args.factor === 'recipe') {
+    const feats = db.prepare(`SELECT r.recipe_id, f.run_id, f.violated FROM eda_run_features f JOIN eda_runs r ON r.id = f.run_id
+      WHERE r.line_id = ?`).all(args.lineId) as Array<{ recipe_id: string, run_id: string, violated: number }>
+    const byRecipe = new Map<string, { runs: Set<string>, bad: Set<string> }>()
+    for (const f of feats) {
+      const a = byRecipe.get(f.recipe_id) ?? { runs: new Set<string>(), bad: new Set<string>() }
+      a.runs.add(f.run_id)
+      if (f.violated === 1 && badSet.has(f.run_id)) a.bad.add(f.run_id)
+      byRecipe.set(f.recipe_id, a)
+    }
+    for (const [v, a] of byRecipe) {
+      const badRate = a.runs.size ? a.bad.size / a.runs.size : 0
+      rows.push({ factor: 'recipe', factorValue: v, runsTotal: a.runs.size, runsBad: a.bad.size, badRate: Number(badRate.toFixed(4)), lift: Number((badRate / baselineBadRate || 0).toFixed(4)) })
+    }
+  }
+  else {
+    // hour:批次开始小时桶(全 run 面,不依赖特征行)
+    const runs = db.prepare('SELECT id, started_at FROM eda_runs WHERE line_id = ?').all(args.lineId) as Array<{ id: string, started_at: string }>
+    const byHour = new Map<string, { runs: Set<string>, bad: Set<string> }>()
+    for (const r of runs) {
+      const h = String(r.started_at).slice(11, 13)
+      const a = byHour.get(h) ?? { runs: new Set<string>(), bad: new Set<string>() }
+      a.runs.add(r.id)
+      if (badSet.has(r.id)) a.bad.add(r.id)
+      byHour.set(h, a)
+    }
+    for (const [v, a] of byHour) {
+      const badRate = a.runs.size ? a.bad.size / a.runs.size : 0
+      rows.push({ factor: 'hour', factorValue: v, runsTotal: a.runs.size, runsBad: a.bad.size, badRate: Number(badRate.toFixed(4)), lift: Number((badRate / baselineBadRate || 0).toFixed(4)) })
+    }
+  }
+  rows.sort((a, b) => b.lift - a.lift)
+  return { factor: args.factor, baselineBadRate: Number(baselineBadRate.toFixed(4)), runsTotal, rows }
+}