@carthooks/arcubase-cli 0.1.2 → 0.1.3

package/dist/runtime/execute.js

@@ -2,9 +2,9 @@ import { parseCLIArgs, hasFlag, flagValue } from './argv.js';
 import { loadRuntimeEnv } from './env.js';
 import { CLIError } from './errors.js';
 import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js';
-import { listModules, listModuleCommands, findCommand } from './command_registry.js';
+import { listModules, listModuleCommands, findCommand, findCommandSuggestions } 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 function renderRootHelp(scope) {
     const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase';
     return [
@@ -17,7 +17,8 @@ export function renderRootHelp(scope) {
 export function renderModuleHelp(scope, moduleName) {
     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]`,
@@ -29,15 +30,24 @@ export function renderModuleHelp(scope, moduleName) {
 export function renderCommandHelp(scope, moduleName, commandName) {
     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');
 }
 function coerceScalar(value, typeText) {
@@ -84,10 +94,55 @@ function buildScalarQuery(command, flags) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function throwBodyValidationFailure(message, requestType, path, scope, command) {
+    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, command, flags, body) {
+    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, moduleName, commandName) {
     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,
@@ -99,7 +154,7 @@ export function summarizeCommand(scope, moduleName, commandName) {
         scalarFlags: command.scalarParams.map((item) => item.name.replace(/([A-Z])/g, '-$1').toLowerCase()),
     };
 }
-export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl = fetch) {
+export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     const parsed = parseCLIArgs(argv);
     if (parsed.commandTokens.length === 0) {
         return { kind: 'help', text: renderRootHelp(scope) };
@@ -114,6 +169,7 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
     if (hasFlag(parsed.flags, 'help')) {
         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);
@@ -123,6 +179,7 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
     const fileQuery = loadQueryFromFlags(parsed.flags);
     const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) };
     const body = loadBodyFromFlags(parsed.flags);
+    let validatedBody = body;
     if (command.requestType) {
         if (body === undefined) {
             throw new CLIError('MISSING_BODY_FILE', `command requires --body-file for ${command.requestType}`, 2);
@@ -139,8 +196,11 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
                         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);
@@ -150,18 +210,18 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
                     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();
     let parsedResponse = raw;
@@ -174,6 +234,25 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
     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/dist/runtime/zod_registry.d.ts

@@ -6,5 +6,11 @@ export type RuntimeTypeHint = {
     symbol: string;
     file: string;
 };
+export type RuntimeDocHint = {
+    title: string;
+    file: string;
+};
 export declare function getTypeHints(typeName: string): RuntimeTypeHint[];
+export declare function getDocHints(typeName: string): RuntimeDocHint[];
+export declare function getCommandDocHints(operation: string): RuntimeDocHint[];
 //# sourceMappingURL=zod_registry.d.ts.map

package/dist/runtime/zod_registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zod_registry.d.ts","sourceRoot":"","sources":["../../src/runtime/zod_registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AAIrC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAIjE;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQ9D;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAqBhE"}
+{"version":3,"file":"zod_registry.d.ts","sourceRoot":"","sources":["../../src/runtime/zod_registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AA6BrC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAOjE;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQ9D;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AA2DD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAqBhE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAI9D;AAsDD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAItE"}

package/dist/runtime/zod_registry.js

@@ -1,9 +1,25 @@
 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 = {
+    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) {
     const name = String(typeName || '').trim();
     if (!name)
         return null;
+    if (schemaOverrides[name]) {
+        return schemaOverrides[name];
+    }
     return bodySchemas[name] ?? null;
 }
 export function getUnsupportedBodySchemaReason(typeName) {
@@ -22,6 +38,60 @@ export function requireBodySchema(typeName) {
     }
     throw new Error(`runtime validation schema not found for ${typeName}`);
 }
+const examplesIndexDocHint = {
+    title: 'Examples index',
+    file: '/opt/arcubase-sdk/docs/runtime-reference/examples/README.md',
+};
+const omsExampleDocHint = {
+    title: 'OMS example 01',
+    file: '/opt/arcubase-sdk/docs/runtime-reference/examples/oms-01/README.md',
+};
+const docHintIndex = {
+    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) {
     const name = String(typeName || '').trim();
     if (!name)
@@ -48,3 +118,66 @@ export function getTypeHints(typeName) {
     }
     return out;
 }
+export function getDocHints(typeName) {
+    const name = String(typeName || '').trim();
+    if (!name)
+        return [];
+    return docHintIndex[name] ?? [];
+}
+const commandDocHintIndex = {
+    '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) {
+    const key = String(operation || '').trim();
+    if (!key)
+        return [];
+    return commandDocHintIndex[key] ?? [];
+}

package/dist/tests/command_registry.test.js

@@ -1,6 +1,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'));
 });
@@ -20,3 +21,7 @@ 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/dist/tests/entity_save_schema.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entity_save_schema.test.d.ts.map

package/dist/tests/entity_save_schema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity_save_schema.test.d.ts","sourceRoot":"","sources":["../../src/tests/entity_save_schema.test.ts"],"names":[],"mappings":""}

package/dist/tests/entity_save_schema.test.js

@@ -0,0 +1,221 @@
+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')));
+});