openyida 2026.9.8 → 2026.9.10

package/README.md

@@ -174,6 +174,8 @@ openyida update-app APP_XXX --theme-file .cache/openyida/crm/app-theme.css --nav
 openyida corp-efficiency
 openyida create-form create APP_XXX "Customer" .cache/openyida/forms/customer-fields.json
 openyida create-form update APP_XXX FORM_XXX .cache/openyida/forms/customer-changes.json
+openyida create-form update APP_XXX FORM_XXX --data-file .cache/openyida/forms/customer-changes.json
+openyida create-form resume APP_XXX FORM_XXX .cache/openyida/forms/customer-fields.json --json
 openyida sample openyida-page-template form-fields --output .cache/openyida/forms/customer-fields.json
 openyida sample openyida-page-template canvas-form-drawer --output project/pages/src/customer-entry.canvas.jsx --var APP_TYPE=APP_XXX --var FORM_UUID=FORM_XXX
 openyida get-schema APP_XXX FORM_XXX
@@ -413,7 +415,8 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida create-form create <appType> "<formTitle>" <fieldsJsonFile> [--icon auto\|<iconName>] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
 | `openyida create-form icons [--json]` | List available form navigation icons |
 | `openyida create-form validate-fields <fieldsJsonOrFile> [--json]` | Validate form field JSON locally |
-| `openyida create-form update <appType> ... [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Update a form page |
+| `openyida create-form update <appType> <formUuid> (<changesJsonOrFile> \| --data-file <changesJsonOrFile>) [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Update a form page |
+| `openyida create-form resume <appType> <formUuid> <fieldsJsonOrFile> [--json]` | Update a form page |
 | `openyida create-form patch <appType> <formUuid> <patchJsonOrFile> [--open\|--no-open]` | Update a form page |
 | `openyida create-form rule <appType> <formUuid> <rulesJsonOrFile> [--open\|--no-open]` | Update a form page |
 | `openyida create-form validation <appType> <formUuid> <validationsJsonOrFile> [--open\|--no-open]` | Update a form page |

package/lib/app/create-form/args.js

@@ -89,6 +89,7 @@ function createParseArgs(dependencies) {
       contentLocale: null,
       browserOpenMode: openOption.mode,
     };
+    let dataFileInput;
 
     const args = [...rawArgs];
 
@@ -111,6 +112,14 @@ function createParseArgs(dependencies) {
         i--;
       } else if (args[i] === '--icon') {
         throwCreateFormError('--icon requires a value', 'CREATE_FORM_INVALID_ARGUMENTS');
+      } else if (args[i] === '--data-file') {
+        const next = args[i + 1];
+        if (dataFileInput !== undefined || !next || next.startsWith('--')) {
+          throwCreateFormError('--data-file requires exactly one value', 'CREATE_FORM_INVALID_ARGUMENTS');
+        }
+        dataFileInput = next;
+        args.splice(i, 2);
+        i--;
       } else if ((args[i] === '--locale' || args[i] === '--content-locale' || args[i] === '--lang') && i + 1 < args.length) {
         options.contentLocale = args[i + 1];
         if (!normalizeYidaLocale(options.contentLocale)) {
@@ -134,8 +143,10 @@ function createParseArgs(dependencies) {
     if (args.includes('--help') || args.includes('-h')) {
       usage(t('create_form.usage_create_short'));
       hint(t('create_form.usage_update_short'));
+      hint('  batch: openyida create-form batch <appType> <plan.json> [--concurrency 1..4] [--json]');
       hint(t('create_form.example_create'));
       hint(t('create_form.example_update'));
+      hint('Example: openyida create-form batch "APP_XXX" .cache/openyida/forms/forms.json --json');
       return {
         mode: 'help',
         help: true,
@@ -145,6 +156,10 @@ function createParseArgs(dependencies) {
 
     const mode = args[0];
 
+    if (dataFileInput !== undefined && mode !== 'update') {
+      throwCreateFormError('--data-file is only supported by create-form update', 'CREATE_FORM_INVALID_ARGUMENTS');
+    }
+
     if (mode === 'icons' || mode === 'list-icons') {
       return {
         mode: 'icons',
@@ -182,7 +197,12 @@ function createParseArgs(dependencies) {
     }
 
     if (mode === 'update') {
-      if (args.length < 4) {
+      const positionalInput = args[3];
+      if (args.length > 4 || (positionalInput && dataFileInput !== undefined)) {
+        throwCreateFormError('Use either <changesJsonOrFile> or --data-file, not both', 'CREATE_FORM_INVALID_ARGUMENTS');
+      }
+      const changesJsonOrFile = dataFileInput !== undefined ? dataFileInput : positionalInput;
+      if (args.length < 3 || !changesJsonOrFile) {
         usage(t('create_form.usage_update'), t('create_form.example_update'));
         throwCreateFormError(t('create_form.usage_update'), 'CREATE_FORM_INVALID_ARGUMENTS');
       }
@@ -190,7 +210,23 @@ function createParseArgs(dependencies) {
         mode: 'update',
         appType: args[1],
         formUuid: args[2],
-        changesJsonOrFile: args[3],
+        changesJsonOrFile,
+        ...options
+      };
+    }
+
+    if (mode === 'resume') {
+      if (args.length !== 4) {
+        throwCreateFormError(
+          'openyida create-form resume <appType> <formUuid> <fieldsJsonOrFile> --json',
+          'CREATE_FORM_INVALID_ARGUMENTS'
+        );
+      }
+      return {
+        mode: 'resume',
+        appType: args[1],
+        formUuid: args[2],
+        fieldsJsonOrFile: args[3],
         ...options
       };
     }
@@ -313,8 +349,10 @@ function createParseArgs(dependencies) {
 
     usage(t('create_form.usage_create_short'));
     hint(t('create_form.usage_update_short'));
+    hint('  batch: openyida create-form batch <appType> <plan.json> [--concurrency 1..4] [--json]');
     hint(t('create_form.example_create'));
     hint(t('create_form.example_update'));
+    hint('Example: openyida create-form batch "APP_XXX" .cache/openyida/forms/forms.json --json');
     throwCreateFormError(t('create_form.usage_create_short'), 'CREATE_FORM_INVALID_ARGUMENTS');
   };
 }

package/lib/app/create-form/batch.js

@@ -6,12 +6,50 @@ const crypto = require('crypto');
 const { execFile } = require('child_process');
 const { CliError } = require('../../core/cli-error');
 const { t } = require('../../core/i18n');
+const { usage, hint } = require('../../core/chalk');
+const { assertNoEmojiInText, assertNoEmojiInValue } = require('../../core/no-emoji-guard');
+const { normalizeYidaLocale } = require('../../core/yida-i18n');
+const { FORM_NAV_ICONS, resolveFormNavIcon } = require('./nav-icon');
+
+const BATCH_USAGE = 'openyida create-form batch <appType> <plan.json> [--concurrency 1..4] [--check] [--json]';
+const BATCH_PLAN_EXAMPLE = '{"forms":[{"key":"customer","title":"客户","fieldsFile":"customer-fields.json"},{"key":"order","title":"订单","fieldsFile":"order-fields.json","dependsOn":["customer"]}]}';
 
 function invalid(reason) {
   throw new CliError(t('create_form.batch_invalid'), { code: 'FORM_BATCH_INVALID', details: { reason } });
 }
 
+function validateStaticDefinition(form, fields) {
+  try {
+    assertNoEmojiInText(form.title, { artifact: `forms.${form.key}.title` });
+    assertNoEmojiInValue(fields, { artifact: `forms.${form.key}.fields` });
+  } catch (error) {
+    invalid({
+      formKey: form.key,
+      errorCode: error?.code || 'OPENYIDA_ARTIFACT_EMOJI_FORBIDDEN',
+      errorMsg: error?.message || String(error),
+    });
+  }
+  if (form.icon !== undefined && !resolveFormNavIcon(form.icon, form.title, fields).icon) {
+    invalid({
+      formKey: form.key,
+      errorCode: 'CREATE_FORM_NAV_ICON_INVALID',
+      errorMsg: `Unsupported form navigation icon: ${form.icon}`,
+      icon: form.icon,
+      availableIconCount: FORM_NAV_ICONS.length,
+    });
+  }
+  if (form.locale !== undefined && !normalizeYidaLocale(form.locale)) {
+    invalid({
+      formKey: form.key,
+      errorCode: 'CREATE_FORM_INVALID_ARGUMENTS',
+      errorMsg: `Unsupported locale: ${form.locale}`,
+      locale: form.locale,
+    });
+  }
+}
+
 function parseArgs(args) {
+  if (args.includes('--help') || args.includes('-h')) { return { help: true }; }
   const options = { concurrency: 3, check: false };
   const positional = [];
   for (let i = 0; i < args.length; i++) {
@@ -25,11 +63,19 @@ function parseArgs(args) {
     }
   }
   if (positional.length !== 2 || !Number.isInteger(options.concurrency) || options.concurrency < 1 || options.concurrency > 4) {
-    invalid('create-form batch <appType> <plan.json> [--concurrency 1..4] [--check] [--json]');
+    invalid(BATCH_USAGE.replace(/^openyida /, ''));
   }
   return { ...options, appType: positional[0], file: path.resolve(positional[1]) };
 }
 
+function showHelp() {
+  usage(BATCH_USAGE);
+  hint('plan.json: ' + BATCH_PLAN_EXAMPLE);
+  hint('fieldsFile is resolved relative to plan.json; use dependsOn and {"$form":"key","field":"label"} for dependencies.');
+  hint('Run one authoritative batch. If it continues in background, do not stop it, delete its state, or fall back to create/update/resume.');
+  return { success: true, help: true, usage: BATCH_USAGE };
+}
+
 // References occupy a complete JSON value; ordinary text is preserved.
 function mapReferences(value, resolve) {
   if (Array.isArray(value)) { return value.map(item => mapReferences(item, resolve)); }
@@ -42,7 +88,38 @@ function mapReferences(value, resolve) {
   return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, mapReferences(item, resolve)]));
 }
 
-function loadPlan(file) {
+function normalizeAssociationReferences(value, appType) {
+  if (Array.isArray(value)) {
+    return value.map(item => normalizeAssociationReferences(item, appType));
+  }
+  if (!value || typeof value !== 'object') { return value; }
+  const normalized = Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    normalizeAssociationReferences(item, appType),
+  ]));
+  const association = value.associationForm;
+  if (
+    value.type === 'AssociationFormField' &&
+    association &&
+    typeof association === 'object' &&
+    !Array.isArray(association) &&
+    typeof association.$form === 'string'
+  ) {
+    const reference = { $form: association.$form };
+    normalized.associationForm = {
+      ...(appType ? { appType } : {}),
+      formUuid: reference,
+      ...(typeof association.field === 'string' && association.field.trim() ? {
+        mainFieldId: { ...reference, field: association.field },
+        mainFieldLabel: association.field,
+        mainComponentName: 'TextField',
+      } : {}),
+    };
+  }
+  return normalized;
+}
+
+function loadPlan(file, options = {}) {
   const input = JSON.parse(fs.readFileSync(file, 'utf8'));
   if (!Array.isArray(input.forms) || !input.forms.length) { invalid('forms'); }
   const forms = input.forms.map(form => {
@@ -52,7 +129,9 @@ function loadPlan(file) {
     if (Object.keys(form).some(key => !['key', 'title', 'fields', 'fieldsFile', 'dependsOn', 'formUuid', 'icon', 'locale'].includes(key))) { invalid(form.key); }
     if (form.formUuid !== undefined && (typeof form.formUuid !== 'string' || !form.formUuid.startsWith('FORM'))) { invalid(form.key); }
     for (const key of ['icon', 'locale']) { if (form[key] !== undefined && typeof form[key] !== 'string') { invalid(key); } }
-    const fields = form.fieldsFile === undefined ? form.fields : JSON.parse(fs.readFileSync(path.resolve(path.dirname(file), form.fieldsFile), 'utf8'));
+    const rawFields = form.fieldsFile === undefined ? form.fields : JSON.parse(fs.readFileSync(path.resolve(path.dirname(file), form.fieldsFile), 'utf8'));
+    const fields = normalizeAssociationReferences(rawFields, options.appType);
+    validateStaticDefinition(form, fields);
     const dependencies = new Set(form.dependsOn || []);
     mapReferences(fields, key => { dependencies.add(key); return 'FORM-PRECHECK'; });
     return { ...form, fields, dependsOn: [...dependencies] };
@@ -87,21 +166,85 @@ function parseOutput(stdout) {
   return output;
 }
 
-function execute(args) {
+function mergeCommandOutput(stdout, stderr, failed) {
+  const stdoutOutput = parseOutput(stdout);
+  const stderrOutput = parseOutput(stderr);
+  if (!failed) { return stdoutOutput || stderrOutput; }
+  if (!stdoutOutput) { return stderrOutput; }
+  if (!stderrOutput) { return stdoutOutput; }
+  return { ...stdoutOutput, ...stderrOutput };
+}
+
+function boundedDiagnostic(value) {
+  const text = String(value || '').trim();
+  return text.length > 4000 ? text.slice(-4000) : text;
+}
+
+function expectedReadbackFields(fields) {
+  const expected = [];
+  for (const field of Array.isArray(fields) ? fields : []) {
+    if (Array.isArray(field)) {
+      expected.push(...expectedReadbackFields(field));
+      continue;
+    }
+    if (!field || typeof field !== 'object') { continue; }
+    if (field.type === 'ColumnContainer') {
+      expected.push(...expectedReadbackFields(field.children));
+      continue;
+    }
+    if (['Divider', 'RichText', 'PageSection', 'GroupContainer'].includes(field.type)) { continue; }
+    if (typeof field.label === 'string' && field.label.trim()) {
+      expected.push({ label: field.label.trim(), componentName: field.type });
+    }
+  }
+  return expected;
+}
+
+function readbackMatchesExpectedFields(schema, fields) {
+  if (!schema || typeof schema.formUuid !== 'string' || !Array.isArray(schema.fields)) { return false; }
+  const actual = schema.fields.filter(field => field && typeof field === 'object');
+  return expectedReadbackFields(fields).every(expected => actual.some(field =>
+    field.label === expected.label && (!expected.componentName || field.componentName === expected.componentName)
+  ));
+}
+
+function readbackMismatch(formUuid, form, schema) {
+  const expected = expectedReadbackFields(form.fields);
+  const actual = Array.isArray(schema?.fields) ? schema.fields.map(field => ({
+    label: field?.label,
+    componentName: field?.componentName,
+  })) : [];
+  return Object.assign(new Error(`Form batch readback mismatch: ${form.key}`), {
+    output: {
+      success: false,
+      errorCode: 'FORM_BATCH_READBACK_MISMATCH',
+      errorMsg: `Created form ${form.key} did not contain all expected fields`,
+      formUuid,
+      details: { formKey: form.key, formUuid, expected, actual },
+    },
+  });
+}
+
+function execute(args, { execFile: execFileImpl = execFile } = {}) {
   return new Promise((resolve, reject) => {
-    execFile(process.execPath, [path.resolve(__dirname, '../../../bin/yida.js'), ...args, '--quiet'], {
+    execFileImpl(process.execPath, [path.resolve(__dirname, '../../../bin/yida.js'), ...args, '--quiet'], {
       env: { ...process.env, YIDA_QUIET: '1' }, timeout: 180000, maxBuffer: 8 * 1024 * 1024,
-    }, (error, stdout) => {
-      const output = parseOutput(stdout);
+    }, (error, stdout, stderr) => {
+      const output = mergeCommandOutput(stdout, stderr, Boolean(error));
       if (error || !output || typeof output !== 'object' || output.success === false) {
-        reject(Object.assign(new Error(output?.errorMsg || output?.error || error?.message || 'Missing command result'), { output }));
+        reject(Object.assign(new Error(
+          output?.errorMsg || output?.error || output?.message || boundedDiagnostic(stderr) || error?.message || 'Missing command result'
+        ), { output }));
       } else { resolve(output); }
     });
   });
 }
 
 async function schedule(forms, concurrency, results, worker, save) {
-  const pending = new Set(forms.filter(form => !results[form.key] || results[form.key].status === 'blocked').map(form => form.key));
+  const pending = new Set(forms.filter(form => {
+    const result = results[form.key];
+    return !result || result.status === 'blocked' || (result.status === 'failed' && result.formUuid);
+  }).map(form => form.key));
   const active = new Map();
   try {
     while (pending.size || active.size) {
@@ -114,7 +257,7 @@ async function schedule(forms, concurrency, results, worker, save) {
         }
         if (active.size >= concurrency || deps.some(status => status !== 'success')) { continue; }
         pending.delete(form.key);
-        results[form.key] = { status: 'running' };
+        results[form.key] = { ...results[form.key], status: 'running' };
         save(); // Record intent before the request; an interrupted create is never retried automatically.
         const task = Promise.resolve().then(() => worker(form)).then(output => {
           results[form.key] = { ...output, status: 'success' };
@@ -137,7 +280,8 @@ async function schedule(forms, concurrency, results, worker, save) {
 
 async function run(args, dependencies = {}) {
   const options = parseArgs(args);
-  const { forms, groups } = loadPlan(options.file);
+  if (options.help) { return showHelp(); }
+  const { forms, groups } = loadPlan(options.file, { appType: options.appType });
   const call = dependencies.execute || execute;
   // Preflight all definitions before the first remote mutation.
   await schedule(forms.map(form => ({ ...form, dependsOn: [] })), options.concurrency, {}, async form => {
@@ -178,21 +322,49 @@ async function run(args, dependencies = {}) {
       return matches[0].fieldId;
     };
     await schedule(forms, options.concurrency, state.results, async form => {
-      let formUuid = form.formUuid;
+      let formUuid = form.formUuid || state.results[form.key]?.formUuid;
+      let shouldResume = Boolean(!form.formUuid && formUuid);
+      const resolvedFields = mapReferences(form.fields, resolve);
       if (!formUuid) {
-        const argv = ['create-form', 'create', options.appType, form.title, JSON.stringify(mapReferences(form.fields, resolve)), '--no-open'];
+        const argv = ['create-form', 'create', options.appType, form.title, JSON.stringify(resolvedFields), '--no-open'];
         for (const key of ['icon', 'locale']) { if (form[key]) { argv.push(`--${key}`, form[key]); } }
-        const created = await call(argv);
-        if (typeof created.formUuid !== 'string' || !created.formUuid.startsWith('FORM')) { invalid(`create result: ${form.key}`); }
-        formUuid = created.formUuid;
+        try {
+          const created = await call(argv);
+          if (typeof created.formUuid !== 'string' || !created.formUuid.startsWith('FORM')) { invalid(`create result: ${form.key}`); }
+          formUuid = created.formUuid;
+        } catch (error) {
+          const createdFormUuid = error.output?.formUuid || error.output?.details?.formUuid;
+          if (typeof createdFormUuid !== 'string' || !createdFormUuid.startsWith('FORM')) {
+            throw error;
+          }
+          formUuid = createdFormUuid;
+          shouldResume = true;
+        }
       }
       state.results[form.key].formUuid = formUuid;
       save(state);
-      const schema = await call(['get-schema', options.appType, formUuid, '--field-map-json']);
-      if (schema.formUuid !== formUuid || !Array.isArray(schema.fields)) { invalid(`schema: ${form.key}`); }
+      let resumed = false;
+      if (shouldResume) {
+        await call(['create-form', 'resume', options.appType, formUuid, JSON.stringify(resolvedFields), '--json']);
+        resumed = true;
+      }
+      let schema = await call(['get-schema', options.appType, formUuid, '--field-map-json']);
+      if (!readbackMatchesExpectedFields(schema, resolvedFields) && !resumed && !form.formUuid) {
+        await call(['create-form', 'resume', options.appType, formUuid, JSON.stringify(resolvedFields), '--json']);
+        resumed = true;
+        schema = await call(['get-schema', options.appType, formUuid, '--field-map-json']);
+      }
+      if (schema.formUuid !== formUuid || !readbackMatchesExpectedFields(schema, resolvedFields)) {
+        throw readbackMismatch(formUuid, { ...form, fields: resolvedFields }, schema);
+      }
       return { formUuid, fields: schema.fields };
     }, () => save(state));
-    const output = { success: Object.values(state.results).every(item => item.status === 'success'), groups, stateFile, results: state.results };
+    const success = Object.values(state.results).every(item => item.status === 'success');
+    const output = { success, groups, stateFile, results: state.results };
+    if (!success) {
+      output.errorCode = 'FORM_BATCH_PARTIAL_FAILURE';
+      output.nextAction = 'Inspect the saved state and child error, then fix the batch input or recover known formUuid values. Do not fall back to create-form create.';
+    }
     console.log(JSON.stringify(output));
     if (!output.success) { process.exitCode = 1; }
     return output;
@@ -201,4 +373,17 @@ async function run(args, dependencies = {}) {
   }
 }
 
-module.exports = { run, parseArgs, loadPlan, mapReferences, schedule, parseOutput };
+module.exports = {
+  run,
+  parseArgs,
+  loadPlan,
+  mapReferences,
+  normalizeAssociationReferences,
+  schedule,
+  parseOutput,
+  mergeCommandOutput,
+  execute,
+  expectedReadbackFields,
+  readbackMatchesExpectedFields,
+  validateStaticDefinition,
+};

package/lib/app/create-form/commands.js

@@ -6,6 +6,8 @@ function dispatchCreateFormCommand(parsedArgs, authContext, handlers) {
   switch (parsedArgs.mode) {
     case 'update':
       return handlers.update(...args);
+    case 'resume':
+      return handlers.resume(...args);
     case 'patch':
       return handlers.patch(...args);
     case 'rule':