@xtalpi/agentic-lab-skills 0.0.9 → 0.0.11

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/use/useSuperTableBitableLifecycle.ts

@@ -1,555 +1,555 @@
-/* eslint-disable @typescript-eslint/typedef, prefer-destructuring, no-continue, quote-props, operator-linebreak */
-import { computed, ref, watch } from 'vue'
-import type { Ref } from 'vue'
-import { fetchAgenticlabTicketList, postAgenticlabExecutionComplete } from '@/api/agenticlabTickets'
-import type { XNBBitableChoreo, XnbSuperCellContext } from '@/types/xnb-context'
-import { extractTicketIdsFromPayload, extractValveIdFromPayload } from '@/utils/openerTicketIds'
-
-/** 与 Book 子表、updateSubBitable 最后一参 `name` 对齐（示例名） */
-export const DEMO_SUB_TABLE_NAME = '演示'
-
-/** index 须与子表编辑器一致；单主表且编辑器为空时可试 `''`（多子表勿用空串） */
-export const DEMO_LIST_SUB = { index: 'sheet-demo', name: DEMO_SUB_TABLE_NAME, row: 200 } as const
-
-const HEADER_GRAY = '#9e9e9e'
-
-/** 列定义：field 为表格中文列头，key 为接口/内存行字段 */
-export const DEMO_LIST_COLS = [
-  { field: '编码', key: 'code' },
-  { field: '名称', key: 'name' },
-  { field: '数量', key: 'qty' }
-] as const
-
-export interface DemoListRow {
-  id: string
-  code: string
-  name: string
-  qty: number
-}
-
-const bitableConfig = {
-  columnlen: { '0': 120, '1': 160, '2': 100 },
-  rowlen: { 0: 34 }
-}
-
-function buildDataColumns (): Array<Record<string, unknown>> {
-  const cols: Array<Record<string, unknown>> = [
-    {
-      w: 120,
-      dv: { type: 'text_length' },
-      field: '编码',
-      readonly: true,
-      visible: true,
-      dbRelated: false,
-      filters: null,
-      configurable: false,
-      headerColor: HEADER_GRAY
-    },
-    {
-      w: 160,
-      dv: { type: 'text_length' },
-      field: '名称',
-      readonly: true,
-      visible: true,
-      dbRelated: false,
-      filters: null,
-      configurable: false,
-      headerColor: HEADER_GRAY
-    },
-    {
-      w: 100,
-      dv: { type: 'number' },
-      ct: { fa: '0', t: 'n' },
-      field: '数量',
-      readonly: true,
-      visible: true,
-      dbRelated: false,
-      filters: null,
-      configurable: false,
-      headerColor: HEADER_GRAY
-    }
-  ]
-  cols.forEach((dc, i) => {
-    dc.c = i
-  })
-  return cols
-}
-
-const dataColumns = buildDataColumns()
-
-/** opener `payload` 中带 `demoRows` 时用于首屏/刷新数据源（类型宽松便于对接） */
-export function parseDemoRowsFromOpenerPayload (payload: unknown): DemoListRow[] | null {
-  if (payload == null || typeof payload !== 'object') return null
-  const rows = (payload as { demoRows?: unknown }).demoRows
-  if (!Array.isArray(rows) || rows.length === 0) return null
-  const out: DemoListRow[] = []
-  for (const r of rows) {
-    if (r == null || typeof r !== 'object') continue
-    const o = r as Record<string, unknown>
-    const id = o.id != null ? String(o.id) : ''
-    if (!id) continue
-    const code = o.code != null ? String(o.code) : ''
-    const name = o.name != null ? String(o.name) : ''
-    const qty = typeof o.qty === 'number' ? o.qty : Number(o.qty)
-    if (!Number.isFinite(qty)) continue
-    out.push({ id, code, name, qty })
-  }
-  return out.length ? out : null
-}
-
-/** opener 已预拉工单列表时（如父级合并的 `ticketList`），直接映射为表格行 */
-function parseTicketListFromOpenerPayload (payload: unknown): DemoListRow[] | null {
-  if (payload == null || typeof payload !== 'object') return null
-  const list = (payload as { ticketList?: unknown }).ticketList
-  if (!Array.isArray(list) || list.length === 0) return null
-  const rows = list.map((t) => mapAgenticlabTicketToDemoRow(t)).filter((r): r is DemoListRow => r != null)
-  return rows.length ? rows : null
-}
-
-function numOr0 (v: unknown): number {
-  const n = typeof v === 'number' ? v : Number(v)
-  return Number.isFinite(n) ? n : 0
-}
-
-/** 将 `/api/ticket/list` 单项映射为示例表列（编码/名称/数量） */
-function mapAgenticlabTicketToDemoRow (raw: unknown): DemoListRow | null {
-  if (raw == null || typeof raw !== 'object') return null
-  const t = raw as Record<string, unknown>
-  const id = t.id != null ? String(t.id) : ''
-  if (!id) return null
-  const detail = t.detail != null && typeof t.detail === 'object' ? (t.detail as Record<string, unknown>) : {}
-  const ticketId = detail.ticket_id != null ? String(detail.ticket_id) : id
-  const name =
-    detail.compound_id != null
-      ? String(detail.compound_id)
-      : detail.smiles != null
-        ? String(detail.smiles)
-        : String(t.uuid ?? ticketId)
-  const pp = detail.process_params != null && typeof detail.process_params === 'object'
-    ? (detail.process_params as Record<string, unknown>)
-    : {}
-  const qty =
-    numOr0(pp['@requested_amount_mg']) ||
-    numOr0(detail.target_amount_1_mg) ||
-    numOr0(detail.target_amount_2_mg) ||
-    0
-  return { id, code: ticketId, name, qty }
-}
-
-export interface ListSubShape {
-  index: string
-  name: string
-  row: number
-}
-
-function handleBitable (bitable: Record<string, unknown>, sub: ListSubShape | undefined): void {
-  bitable.name = sub?.name
-  if (sub && Object.prototype.hasOwnProperty.call(sub, 'index')) bitable.index = sub.index
-  bitable.row = sub?.row ?? 200
-  bitable.xnb_show_sheetbar = true
-  bitable.xnb_hide_statisticbar = true
-  bitable.xnb_hide_toolbar = false
-  bitable.xnb_hide_formulaBar = false
-  bitable.xnb_excel_with_bg = true
-  bitable.xnb_height = `${Math.floor((window.innerHeight - 100) * 0.72)}px`
-  bitable.config = bitable.config ?? bitableConfig
-}
-
-function dataColumnsMismatch (bitable: Record<string, unknown>, cols: Array<Record<string, unknown>>): boolean {
-  const dc = (bitable.data_columns as Array<{ field?: string }> | undefined) ?? []
-  if (dc.length !== cols.length) return true
-  return cols.some((c, i) => c.field !== dc[i]?.field)
-}
-
-export interface UseSuperTableBitableLifecycleResult {
-  choreo: Ref<XNBBitableChoreo | null>
-  lastRowCount: Ref<number>
-  /** 首屏：ensure 列结构 + 拉数 + 写 items */
-  bootstrap: () => Promise<void>
-  /** 与 bitable-list-lifecycle.js 中 refreshTable 一致：列不齐则补建，再拉数，整表替换 items 后 update */
-  refreshTable: (opts?: { silentNotify?: boolean; skipLoading?: boolean }) => Promise<number>
-  /** 校验当前子表行：数量列为正数；`skipLoading` 为 true 时不套 loading（供提交前复用）；`silentSuccess` 为 true 时通过不弹成功提示 */
-  checkRows: (opts?: { skipLoading?: boolean; silentSuccess?: boolean }) => Promise<boolean>
-  /** 先 `checkRows`，再 POST `/api/execution/complete`（不触发整书保存） */
-  submitRows: () => Promise<void>
-}
-
-/**
- * Vue 版「超级表格列表」生命周期。
- * 刷新使用全量 `items = mapped`（`applyRowsToBitable(..., { replaceAll: true })`）；全量 list 接口须同此写法（见 orbit skill §8.5.2）。
- */
-export function useSuperTableBitableLifecycle (
-  getContext: () => XnbSuperCellContext,
-  getOpenerPayload: () => unknown
-): UseSuperTableBitableLifecycleResult {
-  const choreo = ref<XNBBitableChoreo | null>(null)
-  const lastRowCount = ref(0)
-  /** 最近一次从 AgenticLab `GET /api/ticket/list` 拉到的完整工单，用于提交时与表格合并为 `tickets` */
-  const lastAgenticRawTickets = ref<Record<string, unknown>[]>([])
-  const cellUid = computed(() => getContext().cellUid || '')
-
-  let _prevBookPath = ''
-  let _prevCellUid = ''
-
-  watch(
-    () => [getContext().bookPath, getContext().cellUid, getContext().XNBBitable] as const,
-    () => {
-      const ctx = getContext()
-      const bp = ctx.bookPath
-      const cu = ctx.cellUid
-      if (bp === _prevBookPath && cu === _prevCellUid && choreo.value != null) return
-      _prevBookPath = bp
-      _prevCellUid = cu
-      const Ctor = ctx.XNBBitable
-      choreo.value = Ctor != null ? new Ctor({ bookPath: bp, cellUid: cu }) : null
-    },
-    { immediate: true }
-  )
-
-  function xnb (): XNBBitableChoreo {
-    const c = choreo.value
-    if (c == null) throw new Error('XNBBitable 未注入')
-    return c
-  }
-
-  const listSub: ListSubShape = {
-    index: DEMO_LIST_SUB.index,
-    name: DEMO_LIST_SUB.name,
-    row: DEMO_LIST_SUB.row
-  }
-
-  async function resolveBitableBySub (sub: ListSubShape): Promise<Record<string, unknown> | null> {
-    const x = xnb()
-    if (!(await x.getSubCell())) return null
-    const all = await x.getAllSubBitable(true)
-    if (sub.index) {
-      const hit = all.find((b) => b.index === sub.index)
-      if (hit) return hit
-    }
-    if (all.length === 1) return all[0] ?? null
-    const main = (await x.getSubBitable(true)) as Record<string, unknown> | null
-    if (main == null) return null
-    if (!sub.index || main.index === sub.index) return main
-    return null
-  }
-
-  async function rebuildSubBitableColumns (
-    bitable: Record<string, unknown>,
-    sub: ListSubShape,
-    cols: Array<Record<string, unknown>>
-  ): Promise<void> {
-    const x = xnb()
-    bitable.items = []
-    bitable.data_columns = []
-    await x.addColumns(bitable, cols, [])
-    handleBitable(bitable, sub)
-    await x.updateSubBitable([bitable], { isMerge: false, name: DEMO_SUB_TABLE_NAME })
-    if (typeof x.delay === 'function') await x.delay(300)
-  }
-
-  async function createEmptyBitable (isMerge = false): Promise<void> {
-    const x = xnb()
-    if (await x.getSubCell()) {
-      const bitable = (await x.getSubBitable(true)) as Record<string, unknown>
-      bitable.items = []
-      bitable.data_columns = []
-      await x.addColumns(bitable, dataColumns, [])
-      handleBitable(bitable, listSub)
-      await x.updateSubBitable([bitable], { isMerge, name: DEMO_SUB_TABLE_NAME })
-      if (typeof x.delay === 'function') await x.delay(300)
-      return
-    }
-    const bitable: Record<string, unknown> = { items: [], data_columns: [] }
-    handleBitable(bitable, listSub)
-    await x.addColumns(bitable, dataColumns, [])
-    try {
-      await x.createSubBitable([bitable], DEMO_SUB_TABLE_NAME)
-    } catch {
-      if (typeof x.delay === 'function') await x.delay(500)
-      await x.createSubBitable([bitable], DEMO_SUB_TABLE_NAME)
-    }
-  }
-
-  async function fetchDemoList (): Promise<DemoListRow[]> {
-    const payload = getOpenerPayload()
-    const baseUrl = import.meta.env.VITE_AGENTICLAB_API_URL || ''
-    const token = import.meta.env.VITE_DEV_TOKEN || ''
-    const ids = extractTicketIdsFromPayload(payload)
-    if (baseUrl !== '' && ids.length > 0) {
-      const list = await fetchAgenticlabTicketList({
-        baseUrl,
-        token,
-        ticketIds: ids
-      })
-      const fromApi = list.map((t) => mapAgenticlabTicketToDemoRow(t)).filter((r): r is DemoListRow => r != null)
-      if (fromApi.length > 0) {
-        lastAgenticRawTickets.value = list.map((t) => {
-          return t != null && typeof t === 'object' ? (t as Record<string, unknown>) : {}
-        })
-        return fromApi
-      }
-    }
-    lastAgenticRawTickets.value = []
-    const fromTicketList = parseTicketListFromOpenerPayload(payload)
-    if (fromTicketList != null) return fromTicketList
-    const fromOpener = parseDemoRowsFromOpenerPayload(payload)
-    if (fromOpener != null) return fromOpener
-    /* 无 Agentic 列表、无 opener ticketList/demoRows 时不注入占位行 */
-    return []
-  }
-
-  function mapRowToItem (row: DemoListRow, i: number): { id: string; fields: Record<string, string> } {
-    const fields: Record<string, string> = {}
-    for (const { field, key } of DEMO_LIST_COLS) {
-      const raw = row[key as keyof DemoListRow]
-      fields[field] = raw == null ? '' : typeof raw === 'object' ? JSON.stringify(raw) : String(raw)
-    }
-    return {
-      id: String(row.id ?? `${cellUid.value}-${i}`),
-      fields
-    }
-  }
-
-  /**
-   * `replaceAll: true`（刷新列表）：整表 `items = mapped`，与全量 list 接口写法一致，宿主表格易重绘。
-   * 默认 `replaceAll: false`：无可见行时整表替换，有行时按 id 合并 fields（询价式增量示例）。
-   */
-  async function applyRowsToBitable (
-    bitable: Record<string, unknown>,
-    rows: DemoListRow[],
-    opts?: { replaceAll?: boolean }
-  ): Promise<void> {
-    const x = xnb()
-    const mapped = rows.map((row, i) => mapRowToItem(row, i))
-    const items = (bitable.items as Array<{ id: string; fields: Record<string, string>; visible?: boolean }> | undefined) ?? []
-    const visible = items.filter((it) => it?.visible !== false)
-    if (opts?.replaceAll === true || !visible.length) {
-      bitable.items = mapped
-    } else {
-      const byId = new Map(mapped.map((m) => [m.id, m]))
-      for (const item of items) {
-        const hit = byId.get(item.id)
-        if (hit != null) item.fields = { ...item.fields, ...hit.fields }
-      }
-      const have = new Set(items.map((it) => it.id))
-      for (const m of mapped) {
-        if (!have.has(m.id)) items.push(m)
-      }
-      bitable.items = items
-    }
-
-    await x.updateSubBitable([bitable], { isMerge: true, name: DEMO_SUB_TABLE_NAME })
-    if (typeof x.delay === 'function') await x.delay(300)
-  }
-
-  async function ensureBitableStructure (): Promise<void> {
-    const x = xnb()
-    if (!(await x.getSubCell())) {
-      await createEmptyBitable()
-      return
-    }
-    const bitable = await resolveBitableBySub(listSub)
-    if (bitable == null) throw new Error('无法解析子表：请核对 listSub.index / name 与 Book')
-    if (dataColumnsMismatch(bitable, dataColumns) || !((bitable.data_columns as unknown[])?.length)) {
-      await rebuildSubBitableColumns(bitable, listSub, dataColumns)
-    }
-  }
-
-  async function refreshTable (opts: { silentNotify?: boolean; skipLoading?: boolean } = {}): Promise<number> {
-    const { silentNotify, skipLoading } = opts
-    const ctx = getContext()
-    const loadingShow = ctx.loadingShow
-    const loadingHide = ctx.loadingHide
-    const notifySuccess = ctx.notifySuccess
-    const notifyError = ctx.notifyError
-    const outer = !skipLoading
-    if (outer) loadingShow?.()
-    try {
-      const x = xnb()
-      let bitable = await resolveBitableBySub(listSub)
-      if (bitable == null && (await x.getSubCell())) {
-        bitable = (await x.getSubBitable(true)) as Record<string, unknown>
-      }
-      if (bitable == null) throw new Error('未解析到 bitable')
-
-      if (dataColumnsMismatch(bitable, dataColumns) || !((bitable.data_columns as unknown[])?.length)) {
-        await rebuildSubBitableColumns(bitable, listSub, dataColumns)
-        bitable = (await resolveBitableBySub(listSub)) ?? bitable
-      }
-
-      const rows = await fetchDemoList()
-      await applyRowsToBitable(bitable, rows, { replaceAll: true })
-      lastRowCount.value = rows.length
-      if (!silentNotify) notifySuccess?.(`已刷新，共 ${rows.length} 条`)
-      return rows.length
-    } catch (e) {
-      notifyError?.(e, '', '刷新失败')
-      throw e
-    } finally {
-      if (outer) loadingHide?.()
-    }
-  }
-
-  async function bootstrap (): Promise<void> {
-    const ctx = getContext()
-    const loadingShow = ctx.loadingShow
-    const loadingHide = ctx.loadingHide
-    const notifySuccess = ctx.notifySuccess
-    const notifyError = ctx.notifyError
-    loadingShow?.()
-    try {
-      await ensureBitableStructure()
-      await refreshTable({ silentNotify: true, skipLoading: true })
-      notifySuccess?.('演示表已加载')
-    } catch (e) {
-      notifyError?.(e, '', '首屏加载失败')
-      throw e
-    } finally {
-      loadingHide?.()
-    }
-  }
-
-  async function checkRows (opts: { skipLoading?: boolean; silentSuccess?: boolean } = {}): Promise<boolean> {
-    const { skipLoading = false, silentSuccess = false } = opts
-    const ctx = getContext()
-    const notifySuccess = ctx.notifySuccess
-    const notifyError = ctx.notifyError
-    const loadingShow = ctx.loadingShow
-    const loadingHide = ctx.loadingHide
-    const outer = !skipLoading
-    if (outer) loadingShow?.()
-    try {
-      const x = xnb()
-      const bitable = (await resolveBitableBySub(listSub)) ?? ((await x.getSubBitable(true)) as Record<string, unknown>)
-      const items = (bitable.items as Array<{ fields?: Record<string, string> }> | undefined) ?? []
-      const visible = items.filter((it) => (it as { visible?: boolean }).visible !== false)
-      const qtyField = DEMO_LIST_COLS.find((c) => c.key === 'qty')?.field ?? '数量'
-      const bad: string[] = []
-      for (const it of visible) {
-        const raw = it.fields?.[qtyField]
-        const n = Number(raw)
-        if (!Number.isFinite(n) || n <= 0) bad.push(String(it.fields?.['编码'] ?? it.fields?.['名称'] ?? '?'))
-      }
-      if (bad.length) {
-        notifyError?.(new Error(`数量须为正数，行：${bad.join(', ')}`), '', '数据检查未通过')
-        return false
-      }
-      if (!silentSuccess) {
-        notifySuccess?.(`数据检查通过，共 ${visible.length} 行`)
-      }
-      return true
-    } catch (e) {
-      notifyError?.(e, '', '数据检查失败')
-      throw e
-    } finally {
-      if (outer) loadingHide?.()
-    }
-  }
-
-  function resolveValveIdForSubmit (): number {
-    const fromPayload = extractValveIdFromPayload(getOpenerPayload())
-    if (fromPayload != null) return fromPayload
-    const env = import.meta.env.VITE_AGENTICLAB_VALVE_ID
-    if (env != null && env !== '') {
-      const n = Number(env)
-      if (Number.isFinite(n)) return n
-    }
-    return 0
-  }
-
-  /** 将表格行中的「数量」写回工单 `detail`（与 `mapAgenticlabTicketToDemoRow` 读取路径对齐） */
-  function mergeEditedRowIntoAgenticTicket (ticket: Record<string, unknown>, row: DemoListRow): Record<string, unknown> {
-    const out = JSON.parse(JSON.stringify(ticket)) as Record<string, unknown>
-    const detail = (out.detail != null && typeof out.detail === 'object' ? out.detail : {}) as Record<string, unknown>
-    const pp =
-      detail.process_params != null && typeof detail.process_params === 'object'
-        ? ({ ...(detail.process_params as Record<string, unknown>) } as Record<string, unknown>)
-        : ({} as Record<string, unknown>)
-    pp['@requested_amount_mg'] = row.qty
-    detail.process_params = pp
-    detail.target_amount_1_mg = row.qty
-    out.detail = detail
-    return out
-  }
-
-  function buildTicketsForComplete (bitable: Record<string, unknown>): Record<string, unknown>[] {
-    const rows = itemsToRows(bitable)
-    const byId = new Map(lastAgenticRawTickets.value.map((t) => [String(t.id), t]))
-    const tickets: Record<string, unknown>[] = []
-    for (const row of rows) {
-      const raw = byId.get(String(row.id))
-      if (raw == null) continue
-      tickets.push(mergeEditedRowIntoAgenticTicket(raw, row))
-    }
-    return tickets
-  }
-
-  function itemsToRows (bitable: Record<string, unknown>): DemoListRow[] {
-    const items = (bitable.items as Array<{ id: string; fields?: Record<string, string> }> | undefined) ?? []
-    const qtyField = DEMO_LIST_COLS.find((c) => c.key === 'qty')?.field ?? '数量'
-    return items
-      .filter((it) => (it as { visible?: boolean }).visible !== false)
-      .map((it) => {
-        const f = it.fields ?? {}
-        return {
-          id: String(it.id),
-          code: f['编码'] ?? '',
-          name: f['名称'] ?? '',
-          qty: Number(f[qtyField])
-        }
-      })
-  }
-
-  async function submitRows (): Promise<void> {
-    const ctx = getContext()
-    const notifySuccess = ctx.notifySuccess
-    const notifyError = ctx.notifyError
-    const loadingShow = ctx.loadingShow
-    const loadingHide = ctx.loadingHide
-    loadingShow?.()
-    try {
-      if (!(await checkRows({ skipLoading: true, silentSuccess: true }))) {
-        return
-      }
-      const baseUrl = import.meta.env.VITE_AGENTICLAB_API_URL || ''
-      const token = import.meta.env.VITE_DEV_TOKEN || ''
-      if (baseUrl === '') {
-        notifyError?.(new Error('未配置 VITE_AGENTICLAB_API_URL（接口地址）'), '', '无法提交')
-        return
-      }
-      const x = xnb()
-      const bitable = (await resolveBitableBySub(listSub)) ?? ((await x.getSubBitable(true)) as Record<string, unknown>)
-      const tickets = buildTicketsForComplete(bitable)
-      if (tickets.length === 0) {
-        notifyError?.(
-          new Error('当前表格行无法对应到已拉取的工单；请通过 ticket_ids 拉取列表后再提交'),
-          '',
-          '提交失败'
-        )
-        return
-      }
-      const valveId = resolveValveIdForSubmit()
-      await postAgenticlabExecutionComplete({
-        baseUrl,
-        token,
-        valveId,
-        tickets
-      })
-      notifySuccess?.(`已提交 ${tickets.length} 条工单（execution/complete）`)
-    } catch (e) {
-      notifyError?.(e, '', '提交失败')
-      throw e
-    } finally {
-      loadingHide?.()
-    }
-  }
-
-  return {
-    choreo,
-    lastRowCount,
-    bootstrap,
-    refreshTable,
-    checkRows,
-    submitRows
-  }
-}
+/* eslint-disable @typescript-eslint/typedef, prefer-destructuring, no-continue, quote-props, operator-linebreak */
+import { computed, ref, watch } from 'vue'
+import type { Ref } from 'vue'
+import { fetchAgenticlabTicketList, postAgenticlabExecutionComplete } from '@/api/agenticlabTickets'
+import type { XNBBitableChoreo, XnbSuperCellContext } from '@/types/xnb-context'
+import { extractTicketIdsFromPayload, extractValveIdFromPayload } from '@/utils/openerTicketIds'
+
+/** 与 Book 子表、updateSubBitable 最后一参 `name` 对齐（示例名） */
+export const DEMO_SUB_TABLE_NAME = '演示'
+
+/** index 须与子表编辑器一致；单主表且编辑器为空时可试 `''`（多子表勿用空串） */
+export const DEMO_LIST_SUB = { index: 'sheet-demo', name: DEMO_SUB_TABLE_NAME, row: 200 } as const
+
+const HEADER_GRAY = '#9e9e9e'
+
+/** 列定义：field 为表格中文列头，key 为接口/内存行字段 */
+export const DEMO_LIST_COLS = [
+  { field: '编码', key: 'code' },
+  { field: '名称', key: 'name' },
+  { field: '数量', key: 'qty' }
+] as const
+
+export interface DemoListRow {
+  id: string
+  code: string
+  name: string
+  qty: number
+}
+
+const bitableConfig = {
+  columnlen: { '0': 120, '1': 160, '2': 100 },
+  rowlen: { 0: 34 }
+}
+
+function buildDataColumns (): Array<Record<string, unknown>> {
+  const cols: Array<Record<string, unknown>> = [
+    {
+      w: 120,
+      dv: { type: 'text_length' },
+      field: '编码',
+      readonly: true,
+      visible: true,
+      dbRelated: false,
+      filters: null,
+      configurable: false,
+      headerColor: HEADER_GRAY
+    },
+    {
+      w: 160,
+      dv: { type: 'text_length' },
+      field: '名称',
+      readonly: true,
+      visible: true,
+      dbRelated: false,
+      filters: null,
+      configurable: false,
+      headerColor: HEADER_GRAY
+    },
+    {
+      w: 100,
+      dv: { type: 'number' },
+      ct: { fa: '0', t: 'n' },
+      field: '数量',
+      readonly: true,
+      visible: true,
+      dbRelated: false,
+      filters: null,
+      configurable: false,
+      headerColor: HEADER_GRAY
+    }
+  ]
+  cols.forEach((dc, i) => {
+    dc.c = i
+  })
+  return cols
+}
+
+const dataColumns = buildDataColumns()
+
+/** opener `payload` 中带 `demoRows` 时用于首屏/刷新数据源（类型宽松便于对接） */
+export function parseDemoRowsFromOpenerPayload (payload: unknown): DemoListRow[] | null {
+  if (payload == null || typeof payload !== 'object') return null
+  const rows = (payload as { demoRows?: unknown }).demoRows
+  if (!Array.isArray(rows) || rows.length === 0) return null
+  const out: DemoListRow[] = []
+  for (const r of rows) {
+    if (r == null || typeof r !== 'object') continue
+    const o = r as Record<string, unknown>
+    const id = o.id != null ? String(o.id) : ''
+    if (!id) continue
+    const code = o.code != null ? String(o.code) : ''
+    const name = o.name != null ? String(o.name) : ''
+    const qty = typeof o.qty === 'number' ? o.qty : Number(o.qty)
+    if (!Number.isFinite(qty)) continue
+    out.push({ id, code, name, qty })
+  }
+  return out.length ? out : null
+}
+
+/** opener 已预拉工单列表时（如父级合并的 `ticketList`），直接映射为表格行 */
+function parseTicketListFromOpenerPayload (payload: unknown): DemoListRow[] | null {
+  if (payload == null || typeof payload !== 'object') return null
+  const list = (payload as { ticketList?: unknown }).ticketList
+  if (!Array.isArray(list) || list.length === 0) return null
+  const rows = list.map((t) => mapAgenticlabTicketToDemoRow(t)).filter((r): r is DemoListRow => r != null)
+  return rows.length ? rows : null
+}
+
+function numOr0 (v: unknown): number {
+  const n = typeof v === 'number' ? v : Number(v)
+  return Number.isFinite(n) ? n : 0
+}
+
+/** 将 `/api/ticket/list` 单项映射为示例表列（编码/名称/数量） */
+function mapAgenticlabTicketToDemoRow (raw: unknown): DemoListRow | null {
+  if (raw == null || typeof raw !== 'object') return null
+  const t = raw as Record<string, unknown>
+  const id = t.id != null ? String(t.id) : ''
+  if (!id) return null
+  const detail = t.detail != null && typeof t.detail === 'object' ? (t.detail as Record<string, unknown>) : {}
+  const ticketId = detail.ticket_id != null ? String(detail.ticket_id) : id
+  const name =
+    detail.compound_id != null
+      ? String(detail.compound_id)
+      : detail.smiles != null
+        ? String(detail.smiles)
+        : String(t.uuid ?? ticketId)
+  const pp = detail.process_params != null && typeof detail.process_params === 'object'
+    ? (detail.process_params as Record<string, unknown>)
+    : {}
+  const qty =
+    numOr0(pp['@requested_amount_mg']) ||
+    numOr0(detail.target_amount_1_mg) ||
+    numOr0(detail.target_amount_2_mg) ||
+    0
+  return { id, code: ticketId, name, qty }
+}
+
+export interface ListSubShape {
+  index: string
+  name: string
+  row: number
+}
+
+function handleBitable (bitable: Record<string, unknown>, sub: ListSubShape | undefined): void {
+  bitable.name = sub?.name
+  if (sub && Object.prototype.hasOwnProperty.call(sub, 'index')) bitable.index = sub.index
+  bitable.row = sub?.row ?? 200
+  bitable.xnb_show_sheetbar = true
+  bitable.xnb_hide_statisticbar = true
+  bitable.xnb_hide_toolbar = false
+  bitable.xnb_hide_formulaBar = false
+  bitable.xnb_excel_with_bg = true
+  bitable.xnb_height = `${Math.floor((window.innerHeight - 100) * 0.72)}px`
+  bitable.config = bitable.config ?? bitableConfig
+}
+
+function dataColumnsMismatch (bitable: Record<string, unknown>, cols: Array<Record<string, unknown>>): boolean {
+  const dc = (bitable.data_columns as Array<{ field?: string }> | undefined) ?? []
+  if (dc.length !== cols.length) return true
+  return cols.some((c, i) => c.field !== dc[i]?.field)
+}
+
+export interface UseSuperTableBitableLifecycleResult {
+  choreo: Ref<XNBBitableChoreo | null>
+  lastRowCount: Ref<number>
+  /** 首屏：ensure 列结构 + 拉数 + 写 items */
+  bootstrap: () => Promise<void>
+  /** 与 bitable-list-lifecycle.js 中 refreshTable 一致：列不齐则补建，再拉数，整表替换 items 后 update */
+  refreshTable: (opts?: { silentNotify?: boolean; skipLoading?: boolean }) => Promise<number>
+  /** 校验当前子表行：数量列为正数；`skipLoading` 为 true 时不套 loading（供提交前复用）；`silentSuccess` 为 true 时通过不弹成功提示 */
+  checkRows: (opts?: { skipLoading?: boolean; silentSuccess?: boolean }) => Promise<boolean>
+  /** 先 `checkRows`，再 POST `/api/execution/complete`（不触发整书保存） */
+  submitRows: () => Promise<void>
+}
+
+/**
+ * Vue 版「超级表格列表」生命周期。
+ * 刷新使用全量 `items = mapped`（`applyRowsToBitable(..., { replaceAll: true })`）；全量 list 接口须同此写法（见 orbit skill §8.5.2）。
+ */
+export function useSuperTableBitableLifecycle (
+  getContext: () => XnbSuperCellContext,
+  getOpenerPayload: () => unknown
+): UseSuperTableBitableLifecycleResult {
+  const choreo = ref<XNBBitableChoreo | null>(null)
+  const lastRowCount = ref(0)
+  /** 最近一次从 AgenticLab `GET /api/ticket/list` 拉到的完整工单，用于提交时与表格合并为 `tickets` */
+  const lastAgenticRawTickets = ref<Record<string, unknown>[]>([])
+  const cellUid = computed(() => getContext().cellUid || '')
+
+  let _prevBookPath = ''
+  let _prevCellUid = ''
+
+  watch(
+    () => [getContext().bookPath, getContext().cellUid, getContext().XNBBitable] as const,
+    () => {
+      const ctx = getContext()
+      const bp = ctx.bookPath
+      const cu = ctx.cellUid
+      if (bp === _prevBookPath && cu === _prevCellUid && choreo.value != null) return
+      _prevBookPath = bp
+      _prevCellUid = cu
+      const Ctor = ctx.XNBBitable
+      choreo.value = Ctor != null ? new Ctor({ bookPath: bp, cellUid: cu }) : null
+    },
+    { immediate: true }
+  )
+
+  function xnb (): XNBBitableChoreo {
+    const c = choreo.value
+    if (c == null) throw new Error('XNBBitable 未注入')
+    return c
+  }
+
+  const listSub: ListSubShape = {
+    index: DEMO_LIST_SUB.index,
+    name: DEMO_LIST_SUB.name,
+    row: DEMO_LIST_SUB.row
+  }
+
+  async function resolveBitableBySub (sub: ListSubShape): Promise<Record<string, unknown> | null> {
+    const x = xnb()
+    if (!(await x.getSubCell())) return null
+    const all = await x.getAllSubBitable(true)
+    if (sub.index) {
+      const hit = all.find((b) => b.index === sub.index)
+      if (hit) return hit
+    }
+    if (all.length === 1) return all[0] ?? null
+    const main = (await x.getSubBitable(true)) as Record<string, unknown> | null
+    if (main == null) return null
+    if (!sub.index || main.index === sub.index) return main
+    return null
+  }
+
+  async function rebuildSubBitableColumns (
+    bitable: Record<string, unknown>,
+    sub: ListSubShape,
+    cols: Array<Record<string, unknown>>
+  ): Promise<void> {
+    const x = xnb()
+    bitable.items = []
+    bitable.data_columns = []
+    await x.addColumns(bitable, cols, [])
+    handleBitable(bitable, sub)
+    await x.updateSubBitable([bitable], { isMerge: false, name: DEMO_SUB_TABLE_NAME })
+    if (typeof x.delay === 'function') await x.delay(300)
+  }
+
+  async function createEmptyBitable (isMerge = false): Promise<void> {
+    const x = xnb()
+    if (await x.getSubCell()) {
+      const bitable = (await x.getSubBitable(true)) as Record<string, unknown>
+      bitable.items = []
+      bitable.data_columns = []
+      await x.addColumns(bitable, dataColumns, [])
+      handleBitable(bitable, listSub)
+      await x.updateSubBitable([bitable], { isMerge, name: DEMO_SUB_TABLE_NAME })
+      if (typeof x.delay === 'function') await x.delay(300)
+      return
+    }
+    const bitable: Record<string, unknown> = { items: [], data_columns: [] }
+    handleBitable(bitable, listSub)
+    await x.addColumns(bitable, dataColumns, [])
+    try {
+      await x.createSubBitable([bitable], DEMO_SUB_TABLE_NAME)
+    } catch {
+      if (typeof x.delay === 'function') await x.delay(500)
+      await x.createSubBitable([bitable], DEMO_SUB_TABLE_NAME)
+    }
+  }
+
+  async function fetchDemoList (): Promise<DemoListRow[]> {
+    const payload = getOpenerPayload()
+    const baseUrl = import.meta.env.VITE_AGENTICLAB_API_URL || ''
+    const token = import.meta.env.VITE_DEV_TOKEN || ''
+    const ids = extractTicketIdsFromPayload(payload)
+    if (baseUrl !== '' && ids.length > 0) {
+      const list = await fetchAgenticlabTicketList({
+        baseUrl,
+        token,
+        ticketIds: ids
+      })
+      const fromApi = list.map((t) => mapAgenticlabTicketToDemoRow(t)).filter((r): r is DemoListRow => r != null)
+      if (fromApi.length > 0) {
+        lastAgenticRawTickets.value = list.map((t) => {
+          return t != null && typeof t === 'object' ? (t as Record<string, unknown>) : {}
+        })
+        return fromApi
+      }
+    }
+    lastAgenticRawTickets.value = []
+    const fromTicketList = parseTicketListFromOpenerPayload(payload)
+    if (fromTicketList != null) return fromTicketList
+    const fromOpener = parseDemoRowsFromOpenerPayload(payload)
+    if (fromOpener != null) return fromOpener
+    /* 无 Agentic 列表、无 opener ticketList/demoRows 时不注入占位行 */
+    return []
+  }
+
+  function mapRowToItem (row: DemoListRow, i: number): { id: string; fields: Record<string, string> } {
+    const fields: Record<string, string> = {}
+    for (const { field, key } of DEMO_LIST_COLS) {
+      const raw = row[key as keyof DemoListRow]
+      fields[field] = raw == null ? '' : typeof raw === 'object' ? JSON.stringify(raw) : String(raw)
+    }
+    return {
+      id: String(row.id ?? `${cellUid.value}-${i}`),
+      fields
+    }
+  }
+
+  /**
+   * `replaceAll: true`（刷新列表）：整表 `items = mapped`，与全量 list 接口写法一致，宿主表格易重绘。
+   * 默认 `replaceAll: false`：无可见行时整表替换，有行时按 id 合并 fields（询价式增量示例）。
+   */
+  async function applyRowsToBitable (
+    bitable: Record<string, unknown>,
+    rows: DemoListRow[],
+    opts?: { replaceAll?: boolean }
+  ): Promise<void> {
+    const x = xnb()
+    const mapped = rows.map((row, i) => mapRowToItem(row, i))
+    const items = (bitable.items as Array<{ id: string; fields: Record<string, string>; visible?: boolean }> | undefined) ?? []
+    const visible = items.filter((it) => it?.visible !== false)
+    if (opts?.replaceAll === true || !visible.length) {
+      bitable.items = mapped
+    } else {
+      const byId = new Map(mapped.map((m) => [m.id, m]))
+      for (const item of items) {
+        const hit = byId.get(item.id)
+        if (hit != null) item.fields = { ...item.fields, ...hit.fields }
+      }
+      const have = new Set(items.map((it) => it.id))
+      for (const m of mapped) {
+        if (!have.has(m.id)) items.push(m)
+      }
+      bitable.items = items
+    }
+
+    await x.updateSubBitable([bitable], { isMerge: true, name: DEMO_SUB_TABLE_NAME })
+    if (typeof x.delay === 'function') await x.delay(300)
+  }
+
+  async function ensureBitableStructure (): Promise<void> {
+    const x = xnb()
+    if (!(await x.getSubCell())) {
+      await createEmptyBitable()
+      return
+    }
+    const bitable = await resolveBitableBySub(listSub)
+    if (bitable == null) throw new Error('无法解析子表：请核对 listSub.index / name 与 Book')
+    if (dataColumnsMismatch(bitable, dataColumns) || !((bitable.data_columns as unknown[])?.length)) {
+      await rebuildSubBitableColumns(bitable, listSub, dataColumns)
+    }
+  }
+
+  async function refreshTable (opts: { silentNotify?: boolean; skipLoading?: boolean } = {}): Promise<number> {
+    const { silentNotify, skipLoading } = opts
+    const ctx = getContext()
+    const loadingShow = ctx.loadingShow
+    const loadingHide = ctx.loadingHide
+    const notifySuccess = ctx.notifySuccess
+    const notifyError = ctx.notifyError
+    const outer = !skipLoading
+    if (outer) loadingShow?.()
+    try {
+      const x = xnb()
+      let bitable = await resolveBitableBySub(listSub)
+      if (bitable == null && (await x.getSubCell())) {
+        bitable = (await x.getSubBitable(true)) as Record<string, unknown>
+      }
+      if (bitable == null) throw new Error('未解析到 bitable')
+
+      if (dataColumnsMismatch(bitable, dataColumns) || !((bitable.data_columns as unknown[])?.length)) {
+        await rebuildSubBitableColumns(bitable, listSub, dataColumns)
+        bitable = (await resolveBitableBySub(listSub)) ?? bitable
+      }
+
+      const rows = await fetchDemoList()
+      await applyRowsToBitable(bitable, rows, { replaceAll: true })
+      lastRowCount.value = rows.length
+      if (!silentNotify) notifySuccess?.(`已刷新，共 ${rows.length} 条`)
+      return rows.length
+    } catch (e) {
+      notifyError?.(e, '', '刷新失败')
+      throw e
+    } finally {
+      if (outer) loadingHide?.()
+    }
+  }
+
+  async function bootstrap (): Promise<void> {
+    const ctx = getContext()
+    const loadingShow = ctx.loadingShow
+    const loadingHide = ctx.loadingHide
+    const notifySuccess = ctx.notifySuccess
+    const notifyError = ctx.notifyError
+    loadingShow?.()
+    try {
+      await ensureBitableStructure()
+      await refreshTable({ silentNotify: true, skipLoading: true })
+      notifySuccess?.('演示表已加载')
+    } catch (e) {
+      notifyError?.(e, '', '首屏加载失败')
+      throw e
+    } finally {
+      loadingHide?.()
+    }
+  }
+
+  async function checkRows (opts: { skipLoading?: boolean; silentSuccess?: boolean } = {}): Promise<boolean> {
+    const { skipLoading = false, silentSuccess = false } = opts
+    const ctx = getContext()
+    const notifySuccess = ctx.notifySuccess
+    const notifyError = ctx.notifyError
+    const loadingShow = ctx.loadingShow
+    const loadingHide = ctx.loadingHide
+    const outer = !skipLoading
+    if (outer) loadingShow?.()
+    try {
+      const x = xnb()
+      const bitable = (await resolveBitableBySub(listSub)) ?? ((await x.getSubBitable(true)) as Record<string, unknown>)
+      const items = (bitable.items as Array<{ fields?: Record<string, string> }> | undefined) ?? []
+      const visible = items.filter((it) => (it as { visible?: boolean }).visible !== false)
+      const qtyField = DEMO_LIST_COLS.find((c) => c.key === 'qty')?.field ?? '数量'
+      const bad: string[] = []
+      for (const it of visible) {
+        const raw = it.fields?.[qtyField]
+        const n = Number(raw)
+        if (!Number.isFinite(n) || n <= 0) bad.push(String(it.fields?.['编码'] ?? it.fields?.['名称'] ?? '?'))
+      }
+      if (bad.length) {
+        notifyError?.(new Error(`数量须为正数，行：${bad.join(', ')}`), '', '数据检查未通过')
+        return false
+      }
+      if (!silentSuccess) {
+        notifySuccess?.(`数据检查通过，共 ${visible.length} 行`)
+      }
+      return true
+    } catch (e) {
+      notifyError?.(e, '', '数据检查失败')
+      throw e
+    } finally {
+      if (outer) loadingHide?.()
+    }
+  }
+
+  function resolveValveIdForSubmit (): number {
+    const fromPayload = extractValveIdFromPayload(getOpenerPayload())
+    if (fromPayload != null) return fromPayload
+    const env = import.meta.env.VITE_AGENTICLAB_VALVE_ID
+    if (env != null && env !== '') {
+      const n = Number(env)
+      if (Number.isFinite(n)) return n
+    }
+    return 0
+  }
+
+  /** 将表格行中的「数量」写回工单 `detail`（与 `mapAgenticlabTicketToDemoRow` 读取路径对齐） */
+  function mergeEditedRowIntoAgenticTicket (ticket: Record<string, unknown>, row: DemoListRow): Record<string, unknown> {
+    const out = JSON.parse(JSON.stringify(ticket)) as Record<string, unknown>
+    const detail = (out.detail != null && typeof out.detail === 'object' ? out.detail : {}) as Record<string, unknown>
+    const pp =
+      detail.process_params != null && typeof detail.process_params === 'object'
+        ? ({ ...(detail.process_params as Record<string, unknown>) } as Record<string, unknown>)
+        : ({} as Record<string, unknown>)
+    pp['@requested_amount_mg'] = row.qty
+    detail.process_params = pp
+    detail.target_amount_1_mg = row.qty
+    out.detail = detail
+    return out
+  }
+
+  function buildTicketsForComplete (bitable: Record<string, unknown>): Record<string, unknown>[] {
+    const rows = itemsToRows(bitable)
+    const byId = new Map(lastAgenticRawTickets.value.map((t) => [String(t.id), t]))
+    const tickets: Record<string, unknown>[] = []
+    for (const row of rows) {
+      const raw = byId.get(String(row.id))
+      if (raw == null) continue
+      tickets.push(mergeEditedRowIntoAgenticTicket(raw, row))
+    }
+    return tickets
+  }
+
+  function itemsToRows (bitable: Record<string, unknown>): DemoListRow[] {
+    const items = (bitable.items as Array<{ id: string; fields?: Record<string, string> }> | undefined) ?? []
+    const qtyField = DEMO_LIST_COLS.find((c) => c.key === 'qty')?.field ?? '数量'
+    return items
+      .filter((it) => (it as { visible?: boolean }).visible !== false)
+      .map((it) => {
+        const f = it.fields ?? {}
+        return {
+          id: String(it.id),
+          code: f['编码'] ?? '',
+          name: f['名称'] ?? '',
+          qty: Number(f[qtyField])
+        }
+      })
+  }
+
+  async function submitRows (): Promise<void> {
+    const ctx = getContext()
+    const notifySuccess = ctx.notifySuccess
+    const notifyError = ctx.notifyError
+    const loadingShow = ctx.loadingShow
+    const loadingHide = ctx.loadingHide
+    loadingShow?.()
+    try {
+      if (!(await checkRows({ skipLoading: true, silentSuccess: true }))) {
+        return
+      }
+      const baseUrl = import.meta.env.VITE_AGENTICLAB_API_URL || ''
+      const token = import.meta.env.VITE_DEV_TOKEN || ''
+      if (baseUrl === '') {
+        notifyError?.(new Error('未配置 VITE_AGENTICLAB_API_URL（接口地址）'), '', '无法提交')
+        return
+      }
+      const x = xnb()
+      const bitable = (await resolveBitableBySub(listSub)) ?? ((await x.getSubBitable(true)) as Record<string, unknown>)
+      const tickets = buildTicketsForComplete(bitable)
+      if (tickets.length === 0) {
+        notifyError?.(
+          new Error('当前表格行无法对应到已拉取的工单；请通过 ticket_ids 拉取列表后再提交'),
+          '',
+          '提交失败'
+        )
+        return
+      }
+      const valveId = resolveValveIdForSubmit()
+      await postAgenticlabExecutionComplete({
+        baseUrl,
+        token,
+        valveId,
+        tickets
+      })
+      notifySuccess?.(`已提交 ${tickets.length} 条工单（execution/complete）`)
+    } catch (e) {
+      notifyError?.(e, '', '提交失败')
+      throw e
+    } finally {
+      loadingHide?.()
+    }
+  }
+
+  return {
+    choreo,
+    lastRowCount,
+    bootstrap,
+    refreshTable,
+    checkRows,
+    submitRows
+  }
+}