openyida 2026.7.18 → 2026.7.21

package/lib/app/get-schema.js

@@ -2,6 +2,7 @@
  * get-schema.js - 宜搭表单 Schema 获取命令
  *
  * 用法：
+ *   openyida get-schema <appType> <formUuid> [--compact] [--resolve-fields <labelOrFieldId,...>]
  *   openyida get-schema <appType> <formUuid> [--summary-json|--field-map-json]
  *   openyida get-schema <appType> --all [--summary-json] [--output-dir <dir>] [--concurrency N] [--retries N]
  */
@@ -18,7 +19,9 @@ const {
   requestWithAutoLogin,
 } = require('../core/utils');
 const { t } = require('../core/i18n');
+const { throwCommandError } = require('../core/command-errors');
 const { fetchFormPageList } = require('./form-navigation');
+const { buildFieldResolution } = require('./schema-field-resolution');
 
 // 需要在报表 fieldCode 中加 _value 后缀的字段类型
 const FIELD_TYPES_NEEDING_VALUE_SUFFIX = new Set([
@@ -201,8 +204,9 @@ function parseArgs(args) {
     concurrency: 3,
     retries: 1,
     keyword: '',
-    // --field <labelOrFieldId>：单字段过滤模式，命中时跳过 runBatch 分支，
-    // 仅返回目标字段的 {componentName, fieldId, label, props}
+    compact: false,
+    fields: [],
+    // 保留已有单字段参数，作为 --fields 的单值兼容别名。
     field: '',
     json: false,
     summaryJson: false,
@@ -224,7 +228,15 @@ function parseArgs(args) {
     } else if (arg === '--keyword' && args[index + 1]) {
       parsed.keyword = args[index + 1];
       index++;
-    } else if (arg === '--field' && args[index + 1]) {
+    } else if (arg === '--compact') {
+      parsed.compact = true;
+    } else if (arg === '--resolve-fields') {
+      parsed.compact = true;
+      if (args[index + 1] && !args[index + 1].startsWith('--')) {
+        appendFieldQueries(parsed.fields, args[index + 1]);
+        index++;
+      }
+    } else if (arg === '--field' && args[index + 1] && !args[index + 1].startsWith('--')) {
       parsed.field = args[index + 1];
       index++;
     } else if (arg === '--json') {
@@ -239,15 +251,27 @@ function parseArgs(args) {
   return parsed;
 }
 
+function appendFieldQueries(target, value) {
+  String(value || '')
+    .split(/[,，]/)
+    .map(item => item.trim())
+    .filter(Boolean)
+    .forEach((item) => {
+      if (!target.includes(item)) {
+        target.push(item);
+      }
+    });
+}
+
 function ensureUsage(parsed) {
   if (!parsed.appType || (!parsed.all && !parsed.formUuid)) {
     const { error: chalkError } = require('../core/chalk');
     chalkError(t('get_schema.usage'), { hint: t('get_schema.example') });
   }
-  // --field 模式必须同时提供 formUuid（单字段过滤不支持 --all 批量）
-  if (parsed.field && parsed.all) {
+  // contract v1 的 resource 对应单个 form，不与 --all 批量模式混用。
+  if ((parsed.compact || parsed.field) && parsed.all) {
     const { error: chalkError } = require('../core/chalk');
-    chalkError('--field 不支持与 --all 同时使用，请改为单 form 模式');
+    chalkError(t('get_schema.usage'), { hint: t('get_schema.example') });
   }
 }
 
@@ -502,21 +526,37 @@ async function runSingle(parsed, authRef) {
   banner(t('get_schema.title'));
   label('App', parsed.appType);
   label('Form', parsed.formUuid);
-  if (parsed.field) {label('Field', parsed.field);}
+  if (parsed.field) {
+    label('Field', parsed.field);
+  } else if (parsed.fields.length > 0) {
+    label('Fields', parsed.fields.join(', '));
+  }
 
   // Step 2: 获取表单 Schema
   step(2, t('get_schema.step_get'));
   info(t('get_schema.sending'));
 
-  const result = await fetchSchema(parsed.appType, parsed.formUuid, authRef);
+  let result;
+  try {
+    result = await fetchSchema(parsed.appType, parsed.formUuid, authRef);
+  } catch (error) {
+    if (!parsed.compact) {
+      throw error;
+    }
+    chalkResult(false, t('get_schema.failed', t('common.request_failed')));
+    process.exit(1);
+    return;
+  }
 
   if (!isSuccessfulSchemaResult(result)) {
-    const errorMsg = result ? result.errorMsg || t('common.unknown_error') : t('common.request_failed');
+    const errorMsg = parsed.compact
+      ? t('common.request_failed')
+      : result ? result.errorMsg || t('common.unknown_error') : t('common.request_failed');
     chalkResult(false, t('get_schema.failed', errorMsg));
-    process.exit(1);
+    throwCommandError(errorMsg);
   }
 
-  // --field 模式：只返回单个字段的详细 props（含 SelectField.dataSource 等）
+  // 保留既有 --field 返回结构；新 contract 仅由 --compact / --resolve-fields 触发。
   if (parsed.field) {
     const allFieldNodes = collectFieldNodes(result);
     const aliasMaps = buildComponentAliasMaps(result);
@@ -530,18 +570,29 @@ async function runSingle(parsed, authRef) {
     }
     const props = matched.props || {};
     const labelRaw = props.label;
-    const label = labelRaw
+    const fieldLabel = labelRaw
       ? (typeof labelRaw === 'object' ? (labelRaw.zh_CN || labelRaw.en_US || '') : String(labelRaw))
       : '';
-    const compact = {
+    const legacyField = {
       componentName: matched.componentName,
       fieldId: props.fieldId || '',
       alias: aliasMaps.aliasByFieldId[props.fieldId] || '',
-      label,
+      label: fieldLabel,
       props,
     };
     chalkSuccess(t('get_schema.success'));
-    console.log(JSON.stringify(compact, null, 2));
+    console.log(JSON.stringify(legacyField, null, 2));
+    return;
+  }
+
+  if (parsed.compact) {
+    chalkSuccess(t('get_schema.success'));
+    console.log(JSON.stringify(buildFieldResolution(
+      parsed.appType,
+      parsed.formUuid,
+      result,
+      parsed.fields
+    ), null, 2));
     return;
   }
 
@@ -630,6 +681,7 @@ module.exports = {
   buildSchemaSummary,
   buildComponentAliasMaps,
   parseArgs,
+  appendFieldQueries,
   filterForms,
   mapLimit,
   fetchSchemaRecord,

package/lib/app/import-app.js

@@ -15,31 +15,37 @@ const {
   httpPost,
   requestWithAutoLogin,
 } = require('../core/utils');
-const { createAuthRef } = require('../core/yida-client');
+const { createAuthRef, isTokenAuthRef } = require('../core/yida-client');
 const { t } = require('../core/i18n');
 const { buildYidaI18n, resolveContentLocale } = require('../core/yida-i18n');
 const { banner, step, label, success, fail, warn, info, error, result, usage, hint } = require('../core/chalk');
+const { throwUsage } = require('../core/command-errors');
+const { getSchemaServerRevision } = require('../schema/server-revision');
+const {
+  assertLegacyDirectWriteAllowed,
+  extractLegacyGuardArgs,
+} = require('../core/legacy-schema-guard');
 
 // ── 创建新应用 ────────────────────────────────────────
 
 async function createApp(appName, authRef) {
   const contentLocale = resolveContentLocale({ baseUrl: authRef.baseUrl });
-  const postData = querystring.stringify({
-    appName: JSON.stringify(buildYidaI18n(appName, { en_US: appName, ja_JP: appName })),
-    description: JSON.stringify(buildYidaI18n(appName, { en_US: appName, ja_JP: appName })),
-    icon: 'xian-yingyong%%#0089FF',
-    iconUrl: 'xian-yingyong%%#0089FF',
-    colour: 'blue',
-    defaultLanguage: contentLocale,
-    openExclusive: 'n',
-    openPhysicColumn: 'n',
-    openIsolationDatabase: 'n',
-    openExclusiveUnit: 'n',
-    group: 'ALL',
-  });
-
   const result = await requestWithAutoLogin((auth) => {
-    return httpPost(auth.baseUrl, '/query/app/registerApp.json', postData);
+    const postData = querystring.stringify({
+      _csrf_token: auth.csrfToken,
+      appName: JSON.stringify(buildYidaI18n(appName, { en_US: appName, ja_JP: appName })),
+      description: JSON.stringify(buildYidaI18n(appName, { en_US: appName, ja_JP: appName })),
+      icon: 'xian-yingyong%%#0089FF',
+      iconUrl: 'xian-yingyong%%#0089FF',
+      colour: 'blue',
+      defaultLanguage: contentLocale,
+      openExclusive: 'n',
+      openPhysicColumn: 'n',
+      openIsolationDatabase: 'n',
+      openExclusiveUnit: 'n',
+      group: 'ALL',
+    });
+    return httpPost(auth.baseUrl, '/query/app/registerApp.json', postData, auth.cookies);
   }, authRef);
 
   if (!result || !result.success || !result.content) {
@@ -57,22 +63,30 @@ function normalizeImportFormType(formType) {
   return normalized;
 }
 
-function buildCreateFormPostData(formTitle, formType = 'receipt') {
-  return querystring.stringify({
+function buildCreateFormPayload(formTitle, formType = 'receipt') {
+  return {
     formType: normalizeImportFormType(formType),
     title: JSON.stringify(buildYidaI18n(formTitle, { en_US: formTitle, ja_JP: formTitle })),
-  });
+  };
+}
+
+function buildCreateFormPostData(formTitle, formType = 'receipt') {
+  return querystring.stringify(buildCreateFormPayload(formTitle, formType));
 }
 
 // ── 创建空白表单/页面/报表 ──────────────────────────────
 
 async function createBlankForm(appType, formTitle, authRef, formType = 'receipt') {
-  const postData = buildCreateFormPostData(formTitle, formType);
   const result = await requestWithAutoLogin((auth) => {
+    const postData = querystring.stringify({
+      _csrf_token: auth.csrfToken,
+      ...buildCreateFormPayload(formTitle, formType),
+    });
     return httpPost(
       auth.baseUrl,
       `/dingtalk/web/${appType}/query/formdesign/saveFormSchemaInfo.json`,
-      postData
+      postData,
+      auth.cookies
     );
   }, authRef);
 
@@ -86,44 +100,72 @@ async function createBlankForm(appType, formTitle, authRef, formType = 'receipt'
 
 // ── 保存表单 Schema ───────────────────────────────────
 
-async function saveFormSchema(appType, formUuid, schema, authRef, formType = 'receipt') {
+async function saveFormSchema(appType, formUuid, schema, authRef, formType = 'receipt', serverRevision) {
+  const tokenReady = isTokenAuthRef(authRef);
+  const cookieReady = !!(
+    authRef &&
+    typeof authRef.csrfToken === 'string' &&
+    authRef.csrfToken &&
+    Array.isArray(authRef.cookies)
+  );
+  if (!authRef || !authRef.baseUrl || (!tokenReady && !cookieReady)) {
+    const err = new Error('Import schema save requires an authenticated request context.');
+    err.code = 'IMPORT_SCHEMA_WRITE_PRECHECK_FAILED';
+    throw err;
+  }
+  if (!schema || typeof schema !== 'object' || !Array.isArray(schema.pages)) {
+    const err = new Error('Imported schema content must include a pages array before writing.');
+    err.code = 'SCHEMA_REMOTE_READ_FAILED';
+    throw err;
+  }
+  if (!Number.isFinite(serverRevision) || serverRevision < 0) {
+    const err = new Error('Imported schema revision is missing or invalid.');
+    err.code = 'SCHEMA_REMOTE_READ_FAILED';
+    throw err;
+  }
+
   const payload = {
     appType,
     formUuid,
     content: JSON.stringify(schema),
     schemaVersion: 'V5',
+    gmtModified: serverRevision,
   };
   if (normalizeImportFormType(formType) === 'report') {
     payload.importSchema = 'true';
   }
-  const postData = querystring.stringify(payload);
-
-  const result = await requestWithAutoLogin((auth) => {
-    return httpPost(
-      auth.baseUrl,
-      `/alibaba/web/${appType}/_view/query/formdesign/saveFormSchema.json`,
-      postData
-    );
-  }, authRef);
 
-  return result;
+  const postData = querystring.stringify(Object.assign(
+    {},
+    authRef.csrfToken ? { _csrf_token: authRef.csrfToken } : {},
+    payload
+  ));
+  const authOptions = { projectRoot: authRef.projectRoot };
+  return httpPost(
+    authRef.baseUrl,
+    `/alibaba/web/${appType}/_view/query/formdesign/saveFormSchema.json`,
+    postData,
+    Array.isArray(authRef.cookies) ? authRef.cookies : authOptions,
+    Array.isArray(authRef.cookies) ? authOptions : undefined
+  );
 }
 
 // ── 更新表单配置（发布表单）─────────────────────────────
 
 async function updateFormConfig(appType, formUuid, authRef) {
-  const postData = querystring.stringify({
-    appType,
-    formUuid,
-    setting: JSON.stringify({ MINI_RESOURCE: 0 }),
-    version: 1,
-  });
-
   const result = await requestWithAutoLogin((auth) => {
+    const postData = querystring.stringify({
+      _csrf_token: auth.csrfToken,
+      appType,
+      formUuid,
+      setting: JSON.stringify({ MINI_RESOURCE: 0 }),
+      version: 1,
+    });
     return httpPost(
       auth.baseUrl,
       `/dingtalk/web/${appType}/query/formdesign/updateFormConfig.json`,
-      postData
+      postData,
+      auth.cookies
     );
   }, authRef);
 
@@ -177,11 +219,13 @@ function extractSchemaContent(schemaResult) {
 // ── 主逻辑 ────────────────────────────────────────────
 
 async function run(args) {
+  const guardSplit = extractLegacyGuardArgs(args || []);
+  args = guardSplit.args;
   if (args.length < 1) {
     usage(t('import.usage'));
     hint(t('import.example1'));
     hint(t('import.example2'));
-    process.exit(1);
+    throwUsage(t('import.usage'), `${t('import.example1')}\n${t('import.example2')}`);
   }
 
   const exportFilePath = path.resolve(args[0]);
@@ -215,6 +259,11 @@ async function run(args) {
   step(2, t('common.step_login_label'));
   const authRef = createAuthRef();
   success(t('common.login_ready', authRef.baseUrl));
+  assertLegacyDirectWriteAllowed({
+    command: 'import-app',
+    resourceType: 'app',
+    action: 'create',
+  }, { guardOptions: guardSplit.guardOptions });
 
   step(3, t('import.step_create_app'));
   let newAppType;
@@ -287,9 +336,10 @@ async function run(args) {
       oldFormUuid,
       newFormUuid
     );
+    const serverRevision = getSchemaServerRevision(formSchemaResult);
 
     // 4.3 保存 Schema
-    const saveResult = await saveFormSchema(newAppType, newFormUuid, adaptedSchema, authRef, formType);
+    const saveResult = await saveFormSchema(newAppType, newFormUuid, adaptedSchema, authRef, formType, serverRevision);
     if (!saveResult || !saveResult.success) {
       const errorMsg = saveResult ? saveResult.errorMsg || t('common.unknown_error') : t('common.request_failed');
       fail(t('import.save_schema_failed', errorMsg));
@@ -368,7 +418,9 @@ module.exports = {
   run,
   __test__: {
     normalizeImportFormType,
+    buildCreateFormPayload,
     buildCreateFormPostData,
+    saveFormSchema,
     adaptSchemaIdentifiers,
     extractSchemaContent,
   },

package/lib/app/list-forms.js

@@ -3,6 +3,7 @@
 const { createAuthRef, isAuthRefReady } = require('../core/yida-client');
 const { t } = require('../core/i18n');
 const { fetchFormPageList } = require('./form-navigation');
+const { throwCommandError, throwUsage } = require('../core/command-errors');
 
 function parseArgs(args) {
   const parsed = {
@@ -40,10 +41,7 @@ function filterForms(forms, keyword) {
 async function run(args) {
   const parsed = parseArgs(args);
   if (!parsed.appType) {
-    console.error(t('list_forms.usage'));
-    console.error(t('list_forms.example1'));
-    console.error(t('list_forms.example2'));
-    process.exit(1);
+    throwUsage(t('list_forms.usage'), `${t('list_forms.example1')}\n${t('list_forms.example2')}`);
   }
 
   const SEP = '='.repeat(50);
@@ -58,8 +56,7 @@ async function run(args) {
   console.error(t('common.step_login', 1));
   const authRef = createAuthRef();
   if (!isAuthRefReady(authRef)) {
-    console.error(t('list_forms.no_login'));
-    process.exit(1);
+    throwCommandError(t('list_forms.no_login'), { code: 'CLI_AUTH_REQUIRED' });
   }
   console.error(t('common.login_ready', authRef.baseUrl));
 
@@ -68,8 +65,7 @@ async function run(args) {
   try {
     forms = await fetchFormPageList(parsed.appType, authRef);
   } catch (error) {
-    console.error(t('list_forms.failed', error.message));
-    process.exit(1);
+    throwCommandError(t('list_forms.failed', error.message));
   }
 
   const filteredForms = filterForms(forms, parsed.keyword);

package/lib/app/page-ir.js

@@ -1168,6 +1168,137 @@ function normalizeMediaAssets(spec, defaults) {
   };
 }
 
+function hasValue(value) {
+  if (Array.isArray(value)) {
+    return value.some(hasValue);
+  }
+  if (isPlainObject(value)) {
+    return Object.keys(value).some((key) => hasValue(value[key]));
+  }
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+function hasBlockItems(block) {
+  return Boolean(block && Array.isArray(block.items) && block.items.some(hasValue));
+}
+
+function isSameJson(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function normalizeDomainSpecificity(rawSpec, options, blocks, defaults, normalized, scene) {
+  const spec = isPlainObject(rawSpec) ? rawSpec : {};
+  const optionInputs = isPlainObject(options) ? options : {};
+  const heroBlock = blocks.heroBlock || {};
+  const featureBlock = blocks.featureBlock || {};
+  const metricBlock = blocks.metricBlock || {};
+  const roadmapBlock = blocks.roadmapBlock || {};
+  const ctaBlock = blocks.ctaBlock || {};
+  const sampleFallbacks = [];
+  const missing = [];
+
+  const hasDomainText = hasValue([
+    spec.requirement,
+    spec.requirements,
+    spec.prompt,
+    spec.goal,
+    spec.industry,
+    spec.businessType,
+    spec.business_type,
+    spec.name,
+    spec.title,
+    spec.brandName,
+    spec.appName,
+    spec.appBlueprint,
+    spec.app_blueprint,
+  ]);
+  const provided = {
+    hero: hasValue(spec.brandName || spec.tagline || spec.heroText || heroBlock.brandName || heroBlock.tagline || heroBlock.text || heroBlock.heroText),
+    features: hasValue(spec.features) || hasBlockItems(featureBlock),
+    metrics: hasValue(spec.metrics) || hasBlockItems(metricBlock),
+    roadmap: hasValue(spec.roadmap) || hasBlockItems(roadmapBlock),
+    cta: hasValue(spec.ctaTitle || spec.ctaText || ctaBlock.title || ctaBlock.text),
+    visualProfile: hasValue(optionInputs.visualProfile || spec.visualProfile || spec.visual_profile || spec.visual),
+    appBlueprint: hasValue(optionInputs.appBlueprint || spec.appBlueprint || spec.app_blueprint || spec.pages || spec.roles || spec.navigation || spec.navGroups),
+    interactionProfile: hasValue(optionInputs.interactionProfile || spec.interactionProfile || spec.interaction_profile || spec.interactions || spec.primaryAction || spec.detailMode || spec.bulkActions),
+    insights: hasValue(optionInputs.insights || spec.insights || spec.insight),
+    dataBinding: hasValue(optionInputs.dataBinding || spec.dataBinding || spec.data_binding || spec.formUuid || spec.form_uuid || spec.dataUrl || spec.data_url),
+    assets: hasValue(spec.assets || spec.heroImage || spec.hero_image || spec.productImages || spec.images),
+  };
+
+  if (normalized.meta.brandName === defaults.meta.brandName) {
+    sampleFallbacks.push('brandName');
+  }
+  if (normalized.meta.tagline === defaults.meta.tagline) {
+    sampleFallbacks.push('tagline');
+  }
+  if (normalized.meta.heroText === defaults.meta.heroText) {
+    sampleFallbacks.push('heroText');
+  }
+  if (isSameJson(normalized.features, defaults.features)) {
+    sampleFallbacks.push('features');
+  }
+  if (isSameJson(normalized.metrics, defaults.metrics)) {
+    sampleFallbacks.push('metrics');
+  }
+  if (isSameJson(normalized.roadmap, defaults.roadmap)) {
+    sampleFallbacks.push('roadmap');
+  }
+
+  if (!provided.hero) {
+    missing.push('页面名称、业务定位和首屏说明');
+  }
+  if (!provided.features) {
+    missing.push('业务对象/模块，而不是模板卖点');
+  }
+  if (!provided.metrics && ['dashboard', 'screen', 'workbench'].includes(scene)) {
+    missing.push('贴合业务的指标口径');
+  }
+  if (!provided.roadmap && scene !== 'landing') {
+    missing.push('用户动作、处理路径或运营节奏');
+  }
+  if (!provided.interactionProfile && ['dashboard', 'list', 'detail', 'workbench'].includes(scene)) {
+    missing.push('主操作、下钻方式、筛选/批量动作和空载错状态');
+  }
+  if (!provided.visualProfile) {
+    missing.push('区别于 sample 的视觉方向');
+  }
+  if (scene === 'landing' && !provided.assets) {
+    missing.push('真实素材或素材缺口说明');
+  }
+
+  const weightedProvided = [
+    provided.hero,
+    provided.features,
+    provided.metrics,
+    provided.roadmap,
+    provided.cta,
+    provided.visualProfile,
+    provided.appBlueprint,
+    provided.interactionProfile,
+    provided.insights,
+    provided.dataBinding,
+    provided.assets,
+  ].filter(Boolean).length;
+  const score = Math.round((weightedProvided / 11) * 100);
+  const status = sampleFallbacks.length === 0 && missing.length <= 1
+    ? 'domain-ready'
+    : hasDomainText
+      ? 'draft-needs-domain-spec'
+      : 'sample-reference';
+
+  return {
+    status,
+    score,
+    sampleFallbacks,
+    missing,
+    provided,
+    guidance: status === 'domain-ready'
+      ? 'Spec 已覆盖主要业务语义；sample 仅作为编译骨架。'
+      : '补齐业务对象、指标口径、用户动作、视觉方向和素材/数据约束后再视为真实业务页；sample 只能作为可编译参考。',
+  };
+}
+
 function normalizeTodoItems(items, fallback) {
   const normalized = toList(items)
     .filter(isPlainObject)
@@ -1228,6 +1359,14 @@ function normalizeProductHomepageSpec(rawSpec, options, templateName = PRODUCT_H
     roadmapBlock.items || spec.roadmap,
     defaults.roadmap
   );
+  const domainFidelity = normalizeDomainSpecificity(
+    spec,
+    options,
+    { heroBlock, featureBlock, metricBlock, roadmapBlock, ctaBlock },
+    defaults,
+    { meta, features, metrics, roadmap },
+    scene
+  );
 
   return {
     irVersion: IR_VERSION,
@@ -1243,6 +1382,7 @@ function normalizeProductHomepageSpec(rawSpec, options, templateName = PRODUCT_H
     appBlueprint,
     interactionProfile,
     dataBinding,
+    domainFidelity,
     meta,
     assets,
     insights,