openyida 2026.9.9 → 2026.9.11-1

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

@@ -143,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,
@@ -347,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,14 +166,75 @@ 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); }
     });
   });
@@ -106,6 +246,9 @@ async function schedule(forms, concurrency, results, worker, save) {
     return !result || result.status === 'blocked' || (result.status === 'failed' && result.formUuid);
   }).map(form => form.key));
   const active = new Map();
+  const recoveryAttempted = new Set(forms.filter(form =>
+    form.formUuid || (results[form.key]?.status === 'failed' && results[form.key]?.formUuid)
+  ).map(form => form.key));
   try {
     while (pending.size || active.size) {
       const pendingBefore = pending.size;
@@ -117,6 +260,8 @@ async function schedule(forms, concurrency, results, worker, save) {
         }
         if (active.size >= concurrency || deps.some(status => status !== 'success')) { continue; }
         pending.delete(form.key);
+        const hadKnownFormUuid = Boolean(form.formUuid || results[form.key]?.formUuid);
+        if (hadKnownFormUuid) { recoveryAttempted.add(form.key); }
         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 => {
@@ -124,6 +269,13 @@ async function schedule(forms, concurrency, results, worker, save) {
         }, error => {
           results[form.key] = { ...results[form.key], status: 'failed', error: error.message,
             ...((error.output?.formUuid || error.output?.details?.formUuid) ? { formUuid: error.output.formUuid || error.output.details.formUuid } : {}) };
+          // A create may persist the form before a later schema/readback stage fails.
+          // Retry that known UUID once inside the same authoritative batch so its
+          // dependents remain pending and can run after conservative resume.
+          if (!hadKnownFormUuid && results[form.key].formUuid && !recoveryAttempted.has(form.key)) {
+            recoveryAttempted.add(form.key);
+            pending.add(form.key);
+          }
         }).then(() => { save(); }).finally(() => active.delete(form.key));
         active.set(form.key, task);
       }
@@ -140,7 +292,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 => {
@@ -202,14 +355,28 @@ async function run(args, dependencies = {}) {
       }
       state.results[form.key].formUuid = formUuid;
       save(state);
+      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);
       }
-      const schema = await call(['get-schema', options.appType, formUuid, '--field-map-json']);
-      if (schema.formUuid !== formUuid || !Array.isArray(schema.fields)) { invalid(`schema: ${form.key}`); }
       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;
@@ -218,4 +385,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.js

@@ -123,6 +123,29 @@ function createCreateFormError(message, code, details) {
   });
 }
 
+function createFormPreflightError(errorObject, appType, formTitle) {
+  const error = errorObject && errorObject.isCliError
+    ? errorObject
+    : createCreateFormError(
+      errorObject?.message || String(errorObject || 'Create form preflight failed'),
+      'CREATE_FORM_PREFLIGHT_FAILED'
+    );
+  const existing = error.details && typeof error.details === 'object' && !Array.isArray(error.details)
+    ? error.details
+    : {};
+  error.details = {
+    ...existing,
+    stage: 'preflight',
+    retryable: true,
+    retrySafe: true,
+    sideEffectState: 'not_started',
+    mutationAccepted: false,
+    mutationPerformed: false,
+    target: { resource: 'form', appType, formTitle },
+  };
+  return error;
+}
+
 const parseArgs = createParseArgs({
   parseOpenOption,
   normalizeYidaLocale,
@@ -4902,20 +4925,28 @@ async function mainCreate(parsedArgs, authRef) {
   label('Fields:', fieldsJsonOrFile);
 
   step(2, t('create_form.step_read_fields', 2));
-  assertNoEmojiInDefinitionFileName(fieldsJsonOrFile);
-  const { fields, columns, validations } = readFieldsDefinition(fieldsJsonOrFile);
-  assertNoEmojiInFormDefinition(formTitle, fields, validations);
-  validateFormFieldDefinitions(fields);
-  const iconResolution = resolveFormNavIcon(parsedArgs.icon, formTitle, fields);
-  if (!iconResolution.icon) {
-    throwCreateFormError(
-      `Unsupported form navigation icon: ${parsedArgs.icon}. Run openyida create-form icons --json for the supported catalog.`,
-      'CREATE_FORM_NAV_ICON_INVALID',
-      {
-        icon: parsedArgs.icon,
-        availableIconCount: FORM_NAV_ICONS.length,
-      }
-    );
+  let fields;
+  let columns;
+  let validations;
+  let iconResolution;
+  try {
+    assertNoEmojiInDefinitionFileName(fieldsJsonOrFile);
+    ({ fields, columns, validations } = readFieldsDefinition(fieldsJsonOrFile));
+    assertNoEmojiInFormDefinition(formTitle, fields, validations);
+    validateFormFieldDefinitions(fields);
+    iconResolution = resolveFormNavIcon(parsedArgs.icon, formTitle, fields);
+    if (!iconResolution.icon) {
+      throwCreateFormError(
+        `Unsupported form navigation icon: ${parsedArgs.icon}. Run openyida create-form icons --json for the supported catalog.`,
+        'CREATE_FORM_NAV_ICON_INVALID',
+        {
+          icon: parsedArgs.icon,
+          availableIconCount: FORM_NAV_ICONS.length,
+        }
+      );
+    }
+  } catch (preflightError) {
+    throw createFormPreflightError(preflightError, appType, formTitle);
   }
   const formIcon = iconResolution.icon;
   const fieldCount = countDataFieldDefinitions(fields);

package/lib/app/update-app.js

@@ -221,6 +221,16 @@ function normalizeLayoutDirection(layoutDirection) {
   return normalized;
 }
 
+/** 与 yc-utils 的应用配置归一化一致；不应用详情页 Shell 的 top_fold 覆盖。 */
+function normalizeStoredLayoutDirection(layoutDirection, navType) {
+  if (SUPPORTED_LAYOUT_DIRECTIONS.includes(layoutDirection)) {return layoutDirection;}
+  if (layoutDirection === 'hoz') {return navType === 'top_side' ? 'l_shape' : 'top';}
+  if (layoutDirection === 'ver') {return 'side';}
+  if (navType === 'top_fold') {return 'top';}
+  if (navType === 'top_side') {return 'l_shape';}
+  return 'side';
+}
+
 function pickAppField(currentApp, fieldName, configName) {
   if (currentApp[fieldName] !== undefined && currentApp[fieldName] !== null) {
     return currentApp[fieldName];
@@ -296,6 +306,8 @@ function buildUpdateAppPostData(params, currentApp = {}, authRef) {
   const currentCustomThemeStyle = pickAppField(currentApp, 'customThemeStyle', 'CUSTOM_THEME_STYLE');
   const addWaterMark = pickAppField(currentApp, 'addWaterMark', 'ADDWATERMARK');
   const sentryMode = pickAppField(currentApp, 'sentryMode', 'SENTRY_MODE');
+  const currentNavType = currentApp.navType || (currentApp.config && currentApp.config.NAVTYPE);
+  const currentLayoutDirection = currentApp.layoutDirection || (currentApp.config && currentApp.config.LAY_OUT_DIRECTION);
   if (params.colour === 'custom' && !params.themeColor && !currentThemeColor) {
     throw new Error(t('update_app.custom_theme_color_required'));
   }
@@ -319,9 +331,10 @@ function buildUpdateAppPostData(params, currentApp = {}, authRef) {
     mode: currentApp.mode || (currentApp.config && currentApp.config.APPMODE) || 'normal',
     type: currentApp.type || (currentApp.config && currentApp.config.APPTYPE) || 'single',
     navTheme: params.navTheme || currentApp.navTheme || (currentApp.config && currentApp.config.NAV_THEME) || 'light',
-    navType: currentApp.navType || (currentApp.config && currentApp.config.NAVTYPE) || 'top_side',
     navLayout: currentApp.navLayout || (currentApp.config && currentApp.config.NAVLAYOUT) || 'auto',
-    layoutDirection: params.layoutDirection || currentApp.layoutDirection || (currentApp.config && currentApp.config.LAY_OUT_DIRECTION) || 'side',
+    layoutDirection: params.layoutDirection
+      ? normalizeLayoutDirection(params.layoutDirection)
+      : normalizeStoredLayoutDirection(currentLayoutDirection, currentNavType),
     homepageLogo: currentApp.homepageLogo || (currentApp.config && currentApp.config.HOMEPAGELOGO) || '',
     logoSource: params.logoSource || currentApp.logoSource || (currentApp.config && currentApp.config.LOGO_SOURCE) || 'appIcon',
     logoLink: currentApp.logoLink || (currentApp.config && currentApp.config.LOGOLINK) || '',
@@ -346,6 +359,8 @@ function buildUpdateAppPostData(params, currentApp = {}, authRef) {
     pageFooter: currentApp.pageFooter || '',
   };
 
+  // ThemeNavSetting 保存现有 navType；新布局由 layoutDirection 控制，不反写或补造旧字段。
+  if (currentNavType) {postDataObj.navType = currentNavType;}
   if (addWaterMark !== undefined && addWaterMark !== null) {
     postDataObj.addWaterMark = addWaterMark;
   }

package/lib/core/cli-error.js

@@ -90,8 +90,17 @@ function shouldUseStructuredErrorOutput(error, args = []) {
     && details.retrySafe === false
     && details.sideEffectState === 'unknown'
   );
+  const deterministicPreflightFailure = !!(
+    details
+    && typeof details === 'object'
+    && !Array.isArray(details)
+    && details.stage === 'preflight'
+    && details.retrySafe === true
+    && details.sideEffectState === 'not_started'
+    && details.mutationPerformed === false
+  );
   const navigationOrderFailure = /^NAV_ORDER_/.test(error.code || '');
-  return ownedPartial || mutationOutcomeUnknown || navigationOrderFailure;
+  return ownedPartial || mutationOutcomeUnknown || deterministicPreflightFailure || navigationOrderFailure;
 }
 
 module.exports = {

package/lib/core/command-manifest.js

@@ -1555,8 +1555,8 @@ function summarizeLocalizedCommands(commands) {
         plan_command_ids: ['design-plan.init', 'design-plan.preview', 'design-plan.materialize', 'design-plan.patch'],
         theme_command_ids: ['sample', 'create-app', 'update-app'],
         navigation_command_ids: { platform: ['update-app', 'nav-group'], custom: ['update-app', 'update-form-config', 'get-form-config'] },
-        navigation_policy: 'Before PRD planning, reuse explicit navigation choices. During first-time intake, ask only when unknown: platform-l-shape, platform-top, platform-side, custom, with neutral descriptions and no preselection. For custom navigation also settle side/top/mixed/dock. Store type/source/reason/variant in the brief. Custom navigation requires app and per-page navigation hiding with readback; layout and navigation tone are separate choices.',
-        design_mode_policy: 'Analyze requirements first. First-time builds include new apps and existing apps without business pages. Reuse detailed supplied plans; if the mode is unspecified, ask whether to prepare a PRD for confirmation (Plan, more detailed and slower) or build from the supplied requirements (Fast). Without detailed requirements, offer Fast and Plan neutrally. Confirm unresolved navigation, custom navigation layout, visual style and page scope before planning or resource creation. Existing business apps only clarify the current change. Plan uses design-plan init parallelTasks for concurrent business and base visuals in separate files, then page visual bindings; publish settled modules with design-plan preview, then materialize --from-preview validates the complete draft and writes PRD, design, HTML and theme; the business-file/visual-file merge remains available; confirm the displayed revision before building.',
+        navigation_policy: 'Before PRD planning, reuse explicit navigation choices. During first-time intake, ask only when ownership is unknown and offer exactly two neutral options with no preselection: "宜搭原生导航" (使用宜搭自带的导航菜单。) and "自定义导航" (在自定义页面里定制菜单的样式和操作方式，替代宜搭自带的导航菜单。). Native means platform navigation. The agent chooses layout from module count, hierarchy, switching frequency, content width and target device; do not ask layout or presentation-style questions. Prefer top for few shallow modules and wide content, side for many frequently accessed modules, L-shaped/mixed for business domains with child modules, and custom dock for lightweight mobile entries. Preserve user-specified layouts. Store resolved type/source/reason/variant in the brief, distinguishing user ownership from agent layout reasoning. Platform navigation uses update-app --layout top|side|l_shape --show-app-nav, which writes layoutDirection=top|side|l_shape and hideAppNav=n. Preserve stored navType unchanged; do not derive or invent it and do not add a --nav-type option. Without --layout, normalize stored legacy layoutDirection and navType using the yc-utils application rules (hoz plus top_side means l_shape; missing layout uses top_fold/top_side for top/l_shape). Shell page-level top_fold/none overrides do not belong in app settings. Custom side/top/mixed/dock is a page layout and requires app and per-page navigation hiding with readback. Verify persisted layoutDirection and hideAppNav; updatedFields and themeVerification do not prove navigation persistence. Navigation tone is separate from layout.',
+        design_mode_policy: 'Analyze requirements first. First-time builds include new apps and existing apps without business pages. Reuse detailed supplied plans; if the mode is unspecified, ask whether to prepare a PRD for confirmation (Plan, more detailed and slower) or build from the supplied requirements (Fast). Without detailed requirements, offer Fast and Plan neutrally. Confirm unresolved navigation ownership, visual style and page scope before planning or resource creation; the agent determines navigation layout from the business context without a layout question. Existing business apps only clarify the current change. A named resource-only request with explicitScope.allowInferredResources=false skips unrelated navigation and visual questions. Standard Plan uses design-plan init parallelTasks, then executes the returned materialize.command exactly once with business-file and visual-file; preview and --from-preview are only for explicitly incremental large plans. Confirm the displayed revision before building, and do not materialize or patch again after confirmation.',
         product_design_policy: 'yida-requirement-analysis owns shared facts and first-time intake. yida-prd owns business planning; yida-design owns visual design. Reuse the same confirmed brief and supplied details. Prepare business and base visuals concurrently, then bind visuals to settled page tasks. yida-app merges and checks the artifacts before creating resources. Plan uses the compact authoring contract and selected theme context; the CLI reads full templates and renders all artifacts.',
         ui_guidance_policy: 'Page implementation consumes yida-prd prd.md for positioning, information architecture, page prototype, native form entry policy, material strategy, business-specific checks, resource creation order, page implementation delivery order, navigation order, and acceptance criteria; it consumes yida-design design.md for app custom theme CSS delivery, themeColor/navTheme, visual states, visualScaffold, surface material, rounded rules, density rules, components, and state styling. prd.md and design.md are the only design sources of truth. Page implementation may extract page-spec.json as a derived implementation handoff from prd.md + design.md; conflicts are resolved by sending business conflicts to yida-prd and visual conflicts to yida-design before regenerating the spec. Core normal forms default to 1-3 business sample records before page implementation, followed by query readback. An explicit opt-out, configuration dictionary, sensitive data, or lack of safely constructible values requires a recorded skip reason. Screenshots, public sharing, data-source deep binding, and fine navigation grouping are optional after explicit user request or PRD acceptance criteria.',
         default_nav_order_policy: 'For custom navigation, implement PRD navigation order in the custom shell and verify app/page navigation hiding; skip platform nav-group ordering. For platform navigation: after the primary page is successfully published, perform exactly one navigation order operation. If the PRD names a navigation order, publish without --auto-nav-order and then call openyida nav-group order <appType> <items...>. If the PRD only gives broad groups or is missing navigation order, use openyida publish ... --auto-nav-order and do not call nav-group order or auto-order afterward. Explicit and automatic ordering are mutually exclusive; never generate per-item move loops. The fallback priority is portal/home/workbench entry > business handling > data management > business analytics > system configuration.',

package/lib/design-plan/init.js

@@ -8,14 +8,49 @@ const { planBase } = require('./parallel');
 
 const ROOT = path.resolve(__dirname, '../../yida-skills/skills/yida-design/sub_skill/yida-design-plan');
 
+function list(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function customScene(scene) {
+  return !['form', 'process-form', 'report'].includes(scene?.kind);
+}
+
+function resourceOnlyScope(brief) {
+  if (brief.explicitScope?.allowInferredResources === false) {return true;}
+  const scopedForms = list(brief.explicitScope?.forms);
+  const confirmedCustomPages = list(brief.pageScenes).filter(customScene);
+  return scopedForms.length > 0 && confirmedCustomPages.length === 0;
+}
+
+function scopeEntryMatchesScene(entry, scene) {
+  const candidate = typeof entry === 'string' ? entry : entry?.key || entry?.name;
+  return candidate && [scene?.key, scene?.name].includes(candidate);
+}
+
 function initialize(inputPath, options = {}) {
   const input = path.resolve(inputPath);
   const brief = readJson(input, 'requirement-brief.json');
   const project = brief.projectName;
+  if ((project === undefined || project === null || project === '')
+    && typeof brief.meta?.projectName === 'string'
+    && brief.meta.projectName.trim()) {
+    throw new CliError('projectName 必须位于 requirement-brief.json 根级；检测到 meta.projectName，请将该字段移动到根级后重试，不要更换项目名', {
+      code: 'DESIGN_PLAN_PROJECT_NAME_MISPLACED',
+      details: {
+        expectedPath: 'projectName',
+        actualPath: 'meta.projectName',
+        nextAction: 'move_project_name_to_root',
+        retryable: true,
+        retrySafe: true,
+      },
+    });
+  }
   if (typeof project !== 'string' || !project.trim() || /[/\\]/.test(project) || ['.', '..'].includes(project)) {
     throw new CliError('projectName 必须是单层项目目录名', { code: 'DESIGN_PLAN_INVALID_PROJECT' });
   }
-  if (brief.intake?.confirmed !== true || brief.openQuestions?.length) {
+  const resourceOnly = resourceOnlyScope(brief);
+  if ((!resourceOnly && brief.intake?.confirmed !== true) || brief.openQuestions?.length) {
     throw new CliError('请先完成需求确认并记录 intake.confirmed=true', { code: 'DESIGN_PLAN_INTAKE_REQUIRED' });
   }
   if (!['platform-l-shape', 'platform-top', 'platform-side', 'custom'].includes(brief.navigation?.type)
@@ -38,7 +73,10 @@ function initialize(inputPath, options = {}) {
   if ([output, guide, business, visual].some(file => fs.existsSync(file))) {
     throw new CliError('计划或编写上下文已存在，请继续补充现有文件', { code: 'DESIGN_PLAN_ALREADY_EXISTS' });
   }
-  const scenes = (brief.pageScenes || []).filter(scene => !['form', 'process-form', 'report'].includes(scene?.kind));
+  const scopedPages = list(brief.explicitScope?.pages);
+  const scenes = list(brief.pageScenes)
+    .filter(customScene)
+    .filter(scene => !resourceOnly || scopedPages.some(entry => scopeEntryMatchesScene(entry, scene)));
   const pages = scenes.map((scene, index) => {
     const source = typeof scene === 'string' ? { name: scene } : scene;
     const { key, ...facts } = source;
@@ -49,19 +87,49 @@ function initialize(inputPath, options = {}) {
       density: '', permissionSummary: '', dataBinding: '', dataSources: [], ...facts };
   });
   const choice = brief.visualSelection || {};
-  const app = brief.resourceContext?.app || {};
+  const app = brief.resourceContext?.app || brief.resourceContext || {};
   const appConfig = { navigationType: brief.navigation.type };
   for (const key of ['appType', 'corpId', 'baseUrl']) {if (app[key]) {appConfig[key] = app[key];}}
+  const businessGoals = Array.isArray(brief.businessGoals)
+    ? brief.businessGoals
+    : (typeof brief.businessGoals === 'string' && brief.businessGoals.trim() ? [brief.businessGoals] : []);
+  const modelInputs = (resourceOnly && list(brief.explicitScope?.forms).length > 0
+    ? list(brief.explicitScope.forms)
+    : list(brief.businessObjects)).map(item => {
+    if (typeof item !== 'string') {return item;}
+    return list(brief.businessObjects).find(candidate => candidate?.name === item) || item;
+  });
+  const normalizedScope = {
+    ...brief.explicitScope,
+    ...(resourceOnly ? {
+      allowInferredResources: false,
+      pages: scopedPages.filter(entry => scenes.some(scene => scopeEntryMatchesScene(entry, scene))),
+    } : {}),
+  };
+  const rolePermissionSummary = list(brief.targetUsers)
+    .map(user => typeof user === 'string' ? `${user}：使用本轮范围内已授权资源` : '')
+    .filter(Boolean);
+  if (resourceOnly && rolePermissionSummary.length === 0) {
+    rolePermissionSummary.push('应用成员：使用本轮范围内已授权资源');
+  }
   const plan = {
     schemaVersion: '2.0',
-    meta: { projectName: project, appName: brief.appName || project, revision: '1', status: 'draft', source: input,
+    meta: { projectName: project, appName: brief.appName || brief.projectDisplayName || brief.meta?.displayName || project, revision: '1', status: 'draft', source: input,
       businessDomain: brief.industry || '', experienceTopology: '',
       planState: { planConfirmed: false, presentedRevision: null, confirmedRevision: null } },
-    overview: { summary: (brief.businessGoals || []).join('；'), businessGraph: { relations: [] }, rolePermissionSummary: [] },
-    dataModels: (brief.businessObjects || []).map(item => {
+    overview: { summary: businessGoals.join('；'), businessGraph: { relations: [] }, rolePermissionSummary },
+    dataModels: modelInputs.map(item => {
       const model = typeof item === 'string' ? { name: item } : item;
       return { ...model, name: model.name, formType: model.formType || '宜搭表单', description: model.description || '', fields: Array.isArray(model.fields) ? model.fields : [] };
-    }), businessFlows: [], pages: { customPageDetails: pages }, execution: { appConfig, explicitScope: { ...brief.explicitScope, navigation: brief.navigation } },
+    }), businessFlows: [], pages: { customPageDetails: pages }, execution: {
+      appConfig,
+      explicitScope: { ...normalizedScope, navigation: brief.navigation },
+      ...(resourceOnly ? {
+        sampleDataPlan: modelInputs
+          .filter(item => !String(item?.formType || '').includes('流程'))
+          .map(item => ({ form: typeof item === 'string' ? item : item.name, skipReason: '本轮显式窄范围不包含示例数据' })),
+      } : {}),
+    },
     visualStyle: {
       ...(choice.tokens ? { tokens: choice.tokens } : {}),
       ...(choice.evidence ? { evidence: choice.evidence } : {}),
@@ -82,14 +150,23 @@ function initialize(inputPath, options = {}) {
   const patterns = readJson(path.join(ROOT, 'templates/page-patterns/index.json')).patterns;
   const context = [
     '# 计划编写上下文', '', `需求事实：${input}`, `计划目录：${outputDir}`, '',
-    '先读 build-plan-compact-schema.md；标准首版一次完成 business.json，复用已预填的 visual.json 后合并物化。只有视觉选择不完整或存在品牌稿、参考图、逐页特殊视觉要求时才补充视觉。保留各文件 base、页面 ID 与已有需求细节；普通首版不逐模块调用 preview。', '',
+    `先读 build-plan-compact-schema.md，再读 init 已创建的 business.json；保留 base 并一次补完 facts 后写回。business facts 只能包含 overview、dataModels、businessFlows、pages 和可选 execution，不得写 visualStyle。写完后只执行一次：openyida design-plan materialize ${output} --business-file ${business} --visual-file ${visual} --json。标准首版禁止先调用 --from-preview、preview、--check 或无参数 materialize，也不要用 Glob 或额外 Read 检查产物；成功结果已返回 HTML 路径和 revision。只有视觉选择不完整或存在品牌稿、参考图、逐页特殊视觉要求时才补充视觉。保留页面 ID 与已有需求细节。`, '',
     '## 页面模式', ...patterns.map(item => `- ${item.id}（${item.label}）：${item.mustKeep.join('；')}`), '',
     `## 已选风格：${theme.label}`, overview.trim(), '',
     '用户确认的配色优先于模板固定灰阶：surfaceTone=brand-tinted 将浅色页面、填充和边界与主色协调，正文保留中性层级；用户明确只改强调色、保持中性或忠实参考配色时设为 theme。深色表面保留原层级。不要为了模板的无彩限制撤掉用户要求的品牌氛围。', '',
     '完整主题的 token、组件、状态和响应式规则由 CLI 注入 design.md；调整具体组件时按需读取对应模板章节。', '',
   ].join('\n');
   const base = planBase(plan);
-  const businessPart = `${JSON.stringify({ base, ready: false, facts: {} }, null, 2)}\n`;
+  const businessFacts = Object.fromEntries(
+    ['overview', 'dataModels', 'businessFlows', 'pages', 'execution'].map(key => [key, plan[key]]),
+  );
+  const businessReady = resourceOnly
+    && businessGoals.length > 0
+    && rolePermissionSummary.length > 0
+    && plan.dataModels.length > 0
+    && plan.dataModels.every(model => model.name && list(model.fields).length > 0
+      && model.fields.every(field => field?.name && field?.type && typeof field.required === 'boolean'));
+  const businessPart = `${JSON.stringify({ base, ready: businessReady, facts: businessFacts }, null, 2)}\n`;
   // The intake already records an atomic visual selection. Seed it here so a
   // standard first Plan only needs one model planning pass for business facts.
   const selectedVisual = plan.visualStyle.forUser;
@@ -100,10 +177,11 @@ function initialize(inputPath, options = {}) {
   const visualPart = `${JSON.stringify({ base, ready: visualReady, facts: { visualStyle: plan.visualStyle } }, null, 2)}\n`;
   writeFiles([[output, `${JSON.stringify(plan, null, 2)}\n`], [guide, context], [business, businessPart], [visual, visualPart]]);
   return { success: true, input, output, context: guide, contract: path.join(ROOT, 'references/build-plan-compact-schema.md'), draft: true,
-    preview: { command: `openyida design-plan preview ${output} --part-file <module.json> --json`, modules: ['overview', 'dataModels', 'businessFlows', 'pages', 'visualStyle'], finalize: `openyida design-plan materialize ${output} --from-preview --json` },
-    parallelTasks: [{ id: 'business', skill: 'yida-prd', output: business, dependsOn: [] },
+    materialize: { mode: 'complete_files_once', maxCalls: 1,
+      command: `openyida design-plan materialize ${output} --business-file ${business} --visual-file ${visual} --json` },
+    parallelTasks: [...(!businessReady ? [{ id: 'business', skill: 'yida-prd', output: business, dependsOn: [] }] : []),
       ...(!visualReady ? [{ id: 'visual-selection', skill: 'yida-design', output: visual, dependsOn: [] }] : [])],
-    preparedInputs: { visual, visualReady },
+    preparedInputs: { business, businessReady, visual, visualReady },
     optionalTasks: [{ id: 'visual-refinement', skill: 'yida-design', input: business, output: visual, dependsOn: ['business'],
       when: 'brand material, reference images, or explicit page-specific visual differences require refinement' }],
   };