@carthooks/arcubase-cli 0.1.2 → 0.1.3

package/src/runtime/errors.ts

@@ -8,12 +8,23 @@ export type CLITSTypeHint = {
   file: string
 }
 
+export type CLIDocHint = {
+  title: string
+  file: string
+}
+
 export type CLIErrorDetails = {
   operation?: string
   requestType?: string
   issues?: CLIValidationIssue[]
   tsHints?: CLITSTypeHint[]
+  docHints?: CLIDocHint[]
   reason?: string
+  endpoint?: string
+  method?: string
+  traceId?: string
+  upstreamError?: unknown
+  suggestions?: string[]
 }
 
 export class CLIError extends Error {

package/src/runtime/execute.ts

@@ -2,9 +2,9 @@ import { parseCLIArgs, hasFlag, flagValue } from './argv.js'
 import { loadRuntimeEnv, type RuntimeEnv } from './env.js'
 import { CLIError } from './errors.js'
 import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js'
-import { listModules, listModuleCommands, findCommand, type CommandScope } from './command_registry.js'
+import { listModules, listModuleCommands, findCommand, findCommandSuggestions, type CommandScope } from './command_registry.js'
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js'
-import { getBodySchema, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
+import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
 
 export type CommandExecutionSummary = {
   scope: CommandScope
@@ -29,7 +29,8 @@ export function renderRootHelp(scope: CommandScope): string {
 export function renderModuleHelp(scope: CommandScope, moduleName: string): string {
   const items = listModuleCommands(scope, moduleName)
   if (items.length === 0) {
-    throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2)
+    const suggestions = findCommandSuggestions(moduleName, '').map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`)
+    throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2, suggestions.length > 0 ? { suggestions } : undefined)
   }
   return [
     `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} <command> [flags]`,
@@ -42,15 +43,24 @@ export function renderModuleHelp(scope: CommandScope, moduleName: string): strin
 export function renderCommandHelp(scope: CommandScope, moduleName: string, commandName: string): string {
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
-    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
+    const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`)
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, suggestions.length > 0 ? { suggestions } : undefined)
   }
+  const docHints = [
+    ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`),
+    ...(command.requestType ? getDocHints(command.requestType) : []),
+  ].filter((item, index, list) => list.findIndex((candidate) => candidate.file === item.file) === index)
   return [
     `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} ${commandName}`,
     `method: ${command.method}`,
     `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
     command.requestType ? `body: ${command.requestType} via --body-file` : 'body: none',
+    'query flags: --query-file',
     command.endpointParams.length ? `path flags: ${command.endpointParams.map((item) => `--${item.replace(/_/g, '-')}`).join(', ')}` : 'path flags: none',
     command.scalarParams.length ? `scalar flags: ${command.scalarParams.map((item) => `--${item.name.replace(/([A-Z])/g, '-$1').toLowerCase()}`).join(', ')}` : 'scalar flags: none',
+    ...(docHints.length > 0
+      ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
+      : []),
   ].join('\n')
 }
 
@@ -98,10 +108,86 @@ function buildScalarQuery(command: ReturnType<typeof findCommand>, flags: Record
   return Object.keys(out).length > 0 ? out : undefined
 }
 
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function throwBodyValidationFailure(message: string, requestType: string, path: string, scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>) {
+  throw new CLIError('BODY_VALIDATION_FAILED', message, 2, {
+    operation: `${scope}.${command.module}.${command.functionName}`,
+    requestType,
+    issues: [
+      {
+        path,
+        message,
+      },
+    ],
+    tsHints: getTypeHints(requestType),
+    docHints: getDocHints(requestType),
+  })
+}
+
+function validateActionSpecificBody(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  flags: Record<string, string | boolean>,
+  body: unknown,
+) {
+  if (!isRecord(body) || !command.requestType) {
+    return
+  }
+
+  if (command.module === 'workflow' && command.functionName === 'queryEntitySelection') {
+    const action = flagValue(flags, 'action')
+    const selection = body.selection
+    if (!isRecord(selection) || typeof selection.type !== 'string') {
+      return
+    }
+
+    const type = selection.type
+    const condition = isRecord(selection.condition) ? selection.condition : undefined
+    const conditionKeys = condition ? Object.keys(condition).filter((key) => key !== 'selectAll') : []
+
+    if (action === 'query') {
+      if (type === 'condition') {
+        throwBodyValidationFailure(
+          'selection.type=condition is not supported for action=query; use selection.type=ids or selection.type=all, or use workflow query-entity for search conditions',
+          command.requestType,
+          'body.selection.type',
+          scope,
+          command,
+        )
+      }
+      return
+    }
+
+    if ((action === 'archive' || action === 'delete' || action === 'batch_print') && type === 'all') {
+      throwBodyValidationFailure(
+        `selection.type=all is not supported for action=${action}; use ids or condition`,
+        command.requestType,
+        'body.selection.type',
+        scope,
+        command,
+      )
+    }
+
+    if ((action === 'archive' || action === 'delete') && type === 'condition' && conditionKeys.length === 0) {
+      throwBodyValidationFailure(
+        `selection.condition for action=${action} requires at least one q, tab, or filter_* key in addition to selectAll`,
+        command.requestType,
+        'body.selection.condition',
+        scope,
+        command,
+      )
+    }
+  }
+}
+
 export function summarizeCommand(scope: CommandScope, moduleName: string, commandName: string): CommandExecutionSummary {
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
-    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
+    const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`)
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, suggestions.length > 0 ? { suggestions } : undefined)
   }
   return {
     scope,
@@ -114,7 +200,7 @@ export function summarizeCommand(scope: CommandScope, moduleName: string, comman
   }
 }
 
-export async function executeCLI(scope: CommandScope, argv: string[], env: RuntimeEnv = loadRuntimeEnv(scope), fetchImpl: typeof fetch = fetch): Promise<any> {
+export async function executeCLI(scope: CommandScope, argv: string[], env?: RuntimeEnv, fetchImpl: typeof fetch = fetch): Promise<any> {
   const parsed = parseCLIArgs(argv)
   if (parsed.commandTokens.length === 0) {
     return { kind: 'help', text: renderRootHelp(scope) }
@@ -130,6 +216,8 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
     return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName) }
   }
 
+  const runtimeEnv = env ?? loadRuntimeEnv(scope)
+
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
     throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
@@ -140,6 +228,7 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
   const fileQuery = loadQueryFromFlags(parsed.flags)
   const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) }
   const body = loadBodyFromFlags(parsed.flags)
+  let validatedBody = body
 
   if (command.requestType) {
     if (body === undefined) {
@@ -161,9 +250,12 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
               message: issue.message,
             })),
             tsHints: getTypeHints(command.requestType),
+            docHints: getDocHints(command.requestType),
           }
         )
       }
+      validatedBody = parsedBody.data
+      validateActionSpecificBody(scope, command, parsed.flags, validatedBody)
     } else {
       const unsupportedReason = getUnsupportedBodySchemaReason(command.requestType)
       if (unsupportedReason) {
@@ -172,19 +264,19 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
           requestType: command.requestType,
           reason: unsupportedReason,
           tsHints: getTypeHints(command.requestType),
+          docHints: getDocHints(command.requestType),
         })
       }
     }
   }
 
-  const headers = buildRequestHeaders(env)
-  const response = await fetchImpl(buildURL(env.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
+  const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
     method: command.method,
     headers: {
-      ...headers,
+      ...buildRequestHeaders(runtimeEnv),
       'Content-Type': 'application/json',
     },
-    body: body === undefined || command.method === 'GET' ? undefined : JSON.stringify(body),
+    body: validatedBody === undefined || command.method === 'GET' ? undefined : JSON.stringify(validatedBody),
   })
 
   const raw = await response.text()
@@ -197,6 +289,27 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
   if (!response.ok) {
     throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1)
   }
+  if (parsedResponse && typeof parsedResponse === 'object' && 'error' in parsedResponse && parsedResponse.error) {
+    const upstreamError = parsedResponse.error
+    const upstreamMessage =
+      typeof upstreamError === 'object' && upstreamError && 'message' in upstreamError && typeof upstreamError.message === 'string'
+        ? upstreamError.message
+        : typeof upstreamError === 'string'
+          ? upstreamError
+          : JSON.stringify(upstreamError)
+    const traceId =
+      typeof parsedResponse.trace_id === 'string'
+        ? parsedResponse.trace_id
+        : typeof parsedResponse.request_id === 'string'
+          ? parsedResponse.request_id
+          : undefined
+    throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
+      endpoint,
+      method: command.method,
+      traceId,
+      upstreamError,
+    })
+  }
   return {
     kind: 'result',
     commandPath: command.commandPath,

package/src/runtime/zod_registry.ts

@@ -1,10 +1,38 @@
 import type { ZodTypeAny } from 'zod'
 import { bodySchemas, unsupportedBodySchemas } from '../generated/zod_registry.generated.js'
 import { typeIndex } from '../generated/type_index.generated.js'
+import {
+  AppCreateByTenantsReqVOSchemaOverride,
+  EntityBulkUpdateReqVOSchemaOverride,
+  EntityInvokeBatchOperatorReqVOSchemaOverride,
+  EntityQueryReqVOSchemaOverride,
+  EntitySaveReqVOSchemaOverride,
+  EntitySelectionActionReqVOSchemaOverride,
+  EntityTagsBatchReqVOSchemaOverride,
+  EntityTagsSelectionReqVOSchemaOverride,
+  EntityUpdateReqVOSchemaOverride,
+  InsertReqVOSchemaOverride,
+} from './entity_save_schema.js'
+
+const schemaOverrides: Record<string, ZodTypeAny> = {
+  AppCreateByTenantsReqVO: AppCreateByTenantsReqVOSchemaOverride,
+  EntityBulkUpdateReqVO: EntityBulkUpdateReqVOSchemaOverride,
+  'EntityInvokeBatchOperatorReqVO & InvokeRequestVO': EntityInvokeBatchOperatorReqVOSchemaOverride,
+  EntityQueryReqVO: EntityQueryReqVOSchemaOverride,
+  EntitySaveReqVO: EntitySaveReqVOSchemaOverride,
+  EntitySelectionActionReqVO: EntitySelectionActionReqVOSchemaOverride,
+  '{ policy_id: string selection: any }': EntityTagsSelectionReqVOSchemaOverride,
+  '{ policy_id: string selection: any tag_names: string[] }': EntityTagsBatchReqVOSchemaOverride,
+  EntityUpdateReqVO: EntityUpdateReqVOSchemaOverride,
+  InsertReqVO: InsertReqVOSchemaOverride,
+}
 
 export function getBodySchema(typeName: string): ZodTypeAny | null {
   const name = String(typeName || '').trim()
   if (!name) return null
+  if (schemaOverrides[name]) {
+    return schemaOverrides[name]
+  }
   return (bodySchemas as Record<string, ZodTypeAny | undefined>)[name] ?? null
 }
 
@@ -29,6 +57,68 @@ export type RuntimeTypeHint = {
   file: string
 }
 
+export type RuntimeDocHint = {
+  title: string
+  file: string
+}
+
+const examplesIndexDocHint: RuntimeDocHint = {
+  title: 'Examples index',
+  file: '/opt/arcubase-sdk/docs/runtime-reference/examples/README.md',
+}
+
+const omsExampleDocHint: RuntimeDocHint = {
+  title: 'OMS example 01',
+  file: '/opt/arcubase-sdk/docs/runtime-reference/examples/oms-01/README.md',
+}
+
+const docHintIndex: Record<string, RuntimeDocHint[]> = {
+  AppCreateByTenantsReqVO: [
+    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    examplesIndexDocHint,
+    omsExampleDocHint,
+  ],
+  AppCreateEntityReqVO: [
+    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    examplesIndexDocHint,
+    omsExampleDocHint,
+  ],
+  EntitySaveReqVO: [
+    { title: 'Entity schema', file: '/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md' },
+    omsExampleDocHint,
+  ],
+  EntityQueryReqVO: [
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    omsExampleDocHint,
+  ],
+  EntityUpdateReqVO: [
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    omsExampleDocHint,
+  ],
+  EntitySelectionActionReqVO: [
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    omsExampleDocHint,
+  ],
+  InsertReqVO: [
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    omsExampleDocHint,
+  ],
+  EntityBulkUpdateReqVO: [
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    omsExampleDocHint,
+  ],
+  'EntityInvokeBatchOperatorReqVO & InvokeRequestVO': [
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+  ],
+  '{ policy_id: string selection: any }': [
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+  ],
+  '{ policy_id: string selection: any tag_names: string[] }': [
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+  ],
+}
+
 export function getTypeHints(typeName: string): RuntimeTypeHint[] {
   const name = String(typeName || '').trim()
   if (!name) return []
@@ -51,3 +141,67 @@ export function getTypeHints(typeName: string): RuntimeTypeHint[] {
   }
   return out
 }
+
+export function getDocHints(typeName: string): RuntimeDocHint[] {
+  const name = String(typeName || '').trim()
+  if (!name) return []
+  return docHintIndex[name] ?? []
+}
+
+const commandDocHintIndex: Record<string, RuntimeDocHint[]> = {
+  'admin.app.createAppByTenants': [
+    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    examplesIndexDocHint,
+    omsExampleDocHint,
+  ],
+  'admin.app.createEntity': [
+    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    omsExampleDocHint,
+  ],
+  'admin.entity.adminGetEntityInfo': [
+    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    omsExampleDocHint,
+  ],
+  'admin.entity.adminSaveEntity': [
+    { title: 'Entity schema', file: '/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md' },
+    omsExampleDocHint,
+  ],
+  'user.workflow.insertEntity': [
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    omsExampleDocHint,
+  ],
+  'user.workflow.queryEntity': [
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    omsExampleDocHint,
+  ],
+  'user.workflow.getEntityRow': [
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    omsExampleDocHint,
+  ],
+  'user.workflow.updateEntityRow': [
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    omsExampleDocHint,
+  ],
+  'user.workflow.queryEntitySelection': [
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    omsExampleDocHint,
+  ],
+  'user.workflow.deleteEntityRow': [
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    omsExampleDocHint,
+  ],
+  'user.workflow.restoreEntityRow': [
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    omsExampleDocHint,
+  ],
+  'user.entity.updateEntityBulk': [
+    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    omsExampleDocHint,
+  ],
+}
+
+export function getCommandDocHints(operation: string): RuntimeDocHint[] {
+  const key = String(operation || '').trim()
+  if (!key) return []
+  return commandDocHintIndex[key] ?? []
+}

package/src/tests/command_registry.test.ts

@@ -2,6 +2,7 @@ import test from 'node:test'
 import assert from 'node:assert/strict'
 
 import { adminCommands, userCommands } from '../generated/command_registry.generated.js'
+import { findCommandSuggestions } from '../runtime/command_registry.js'
 
 test('admin app create-entity command exists', () => {
   assert.ok(adminCommands.some((c) => c.commandPath.join(' ') === 'app create-entity'))
@@ -25,3 +26,8 @@ test('tag commands no longer emit truncated inline request type', () => {
   assert.match(String(typed.requestType), /^\{\s*policy_id:\s*string.*selection:\s*any.*tag_names:\s*string\[\]\s*\}$/)
   assert.equal(typed.scalarParams.length, 0)
 })
+
+test('suggestions can point wrong admin delete guess to user workflow delete command', () => {
+  const suggestions = findCommandSuggestions('entity', 'admin-delete-entity-row')
+  assert.ok(suggestions.some((item) => item.binary === 'arcubase' && item.moduleName === 'workflow' && item.commandName === 'delete-entity-row'))
+})

package/src/tests/entity_save_schema.test.ts

@@ -0,0 +1,236 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { getBodySchema } from '../runtime/zod_registry.js'
+
+const schema = getBodySchema('EntitySaveReqVO')
+
+function buildMinimalField(id = 1001) {
+  return {
+    id,
+    label: '订单号',
+    type: 'text',
+    required: true,
+    unique: false,
+    editable: true,
+    visible: true,
+    show_label: true,
+    scannable: false,
+    default_value_mode: 0,
+    description: '',
+    value: null,
+    number_decimal: 0,
+    depends: [],
+    key: 'order_id',
+    code_index: false,
+    options: {},
+    transfers: null,
+    children: null,
+  }
+}
+
+test('EntitySaveReqVO accepts fields as array', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    id: 2188889845,
+    app_id: 2188889844,
+    name: '订单',
+    schema_version: 1,
+    field_id_seq: 1002,
+    layout: [[1001]],
+    fields: [buildMinimalField()],
+    workflow_enabled: false,
+  })
+  assert.equal(parsed.success, true)
+})
+
+test('EntitySaveReqVO rejects fields as object', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    name: '订单',
+    fields: {
+      order_id: {
+        id: 1001,
+        label: '订单号',
+      },
+    },
+  })
+  assert.equal(parsed.success, false)
+})
+
+test('EntitySaveReqVO rejects field_id_seq not greater than max field id', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1001,
+    layout: [[1001]],
+    fields: [buildMinimalField(1001)],
+  })
+  assert.equal(parsed.success, false)
+  assert.ok(parsed.error.issues.some((issue) => issue.path.join('.') === 'field_id_seq'))
+})
+
+test('EntitySaveReqVO rejects layout unknown top-level field id', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1002,
+    layout: [[9999]],
+    fields: [buildMinimalField(1001)],
+  })
+  assert.equal(parsed.success, false)
+  assert.ok(parsed.error.issues.some((issue) => issue.path.join('.') === 'layout.0.0'))
+})
+
+test('EntitySaveReqVO rejects non-subform field children', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1003,
+    layout: [[1001]],
+    fields: [{
+      ...buildMinimalField(1001),
+      children: [buildMinimalField(1002)],
+    }],
+  })
+  assert.equal(parsed.success, false)
+})
+
+test('EntitySaveReqVO requires status options items', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1002,
+    layout: [[1001]],
+    fields: [{
+      ...buildMinimalField(1001),
+      type: 'status',
+      options: {},
+    }],
+  })
+  assert.equal(parsed.success, false)
+})
+
+test('EntitySaveReqVO requires serialnumber parts', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1002,
+    layout: [[1001]],
+    fields: [{
+      ...buildMinimalField(1001),
+      type: 'serialnumber',
+      options: {},
+    }],
+  })
+  assert.equal(parsed.success, false)
+})
+
+test('EntitySaveReqVO requires lookup relation structure', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1002,
+    layout: [[1001]],
+    fields: [{
+      ...buildMinimalField(1001),
+      type: 'lookup',
+      options: {},
+    }],
+  })
+  assert.equal(parsed.success, false)
+})
+
+test('EntitySaveReqVO requires relationfield relation app and entity ids', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1002,
+    layout: [[1001]],
+    fields: [{
+      ...buildMinimalField(1001),
+      type: 'relationfield',
+      options: {
+        relation: {},
+      },
+    }],
+  })
+  assert.equal(parsed.success, false)
+})
+
+test('EntitySaveReqVO requires rollup relation and aggregation formula', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1002,
+    layout: [[1001]],
+    fields: [{
+      ...buildMinimalField(1001),
+      type: 'rollup',
+      options: {
+        relation: {
+          local_linkto_field_id: 1009,
+          target_field_id: 1010,
+          target_field_type: 'number',
+        },
+      },
+    }],
+  })
+  assert.equal(parsed.success, false)
+})
+
+test('EntitySaveReqVO rejects subform layout that references non-child field id', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1004,
+    layout: [[1001]],
+    fields: [{
+      ...buildMinimalField(1001),
+      type: 'subform',
+      children: [buildMinimalField(1002)],
+      layout: [[1003]],
+    }],
+  })
+  assert.equal(parsed.success, false)
+  assert.ok(parsed.error.issues.some((issue) => issue.path.join('.') === 'fields.0.layout.0.0'))
+})
+
+test('EntitySaveReqVO rejects lookup local_linkto_field_id that does not point to linkto field', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1004,
+    layout: [[1001], [1002]],
+    fields: [
+      buildMinimalField(1001),
+      {
+        ...buildMinimalField(1002),
+        type: 'lookup',
+        options: {
+          relation: {
+            local_linkto_field_id: 1001,
+            target_field_id: 2001,
+            target_field_type: 'text',
+          },
+        },
+      },
+    ],
+  })
+  assert.equal(parsed.success, false)
+  assert.ok(parsed.error.issues.some((issue) => issue.path.join('.') === 'fields.1.options.relation.local_linkto_field_id'))
+})
+
+test('EntitySaveReqVO rejects formula references to unknown field ids', () => {
+  assert.ok(schema)
+  const parsed = schema!.safeParse({
+    field_id_seq: 1003,
+    layout: [[1001]],
+    fields: [
+      buildMinimalField(1001),
+      {
+        ...buildMinimalField(1002),
+        key: 'calc',
+        label: '计算值',
+        type: 'formula',
+        options: {
+          formula: {
+            code: '[[订单号:9999]]',
+            jsonlogic: { var: '9999' },
+          },
+        },
+      },
+    ],
+  })
+  assert.equal(parsed.success, false)
+  assert.ok(parsed.error.issues.some((issue) => issue.message.includes('unknown field id 9999')))
+})