openyida 2026.7.18 → 2026.7.21

package/lib/process/services/process-stage-checkpoint.js

@@ -0,0 +1,246 @@
+'use strict';
+
+const { schemaError } = require('../../schema/errors');
+
+const PROCESS_STAGES = Object.freeze([
+  'draft_created',
+  'saved',
+  'published',
+  'readback_verified',
+  'completed',
+]);
+const ADAPTER_CHECKPOINT_STAGES = new Set(PROCESS_STAGES.slice(0, 3));
+const STAGE_CHECKPOINT_KEYS = new Set([
+  'stage',
+  'processCode',
+  'processId',
+  'processVersion',
+  'nodeBindings',
+  'desiredManagedHash',
+  'observedManagedHash',
+]);
+const ADAPTER_PARTIAL_KEYS = new Set([
+  'processCode',
+  'processId',
+  'processVersion',
+  'nodeBindings',
+]);
+const NODE_BINDING_KEYS = new Set(['nodeId', 'componentName']);
+const HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const SEMANTIC_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+function validateProcessStageCheckpoint(checkpoint, options = {}) {
+  assertObject(checkpoint);
+  assertAllowedKeys(checkpoint, STAGE_CHECKPOINT_KEYS);
+  if (!PROCESS_STAGES.includes(checkpoint.stage)) {
+    invalidCheckpoint();
+  }
+  assertHash(checkpoint.desiredManagedHash);
+  if (options.desiredManagedHash !== undefined && checkpoint.desiredManagedHash !== options.desiredManagedHash) {
+    invalidCheckpoint();
+  }
+  if (stageIndex(checkpoint.stage) >= stageIndex('readback_verified')) {
+    assertHash(checkpoint.observedManagedHash);
+  } else if (checkpoint.observedManagedHash !== undefined) {
+    invalidCheckpoint();
+  }
+  for (const property of ['processCode', 'processId']) {
+    if (checkpoint[property] !== undefined && !isNonEmptyString(checkpoint[property])) {
+      invalidCheckpoint();
+    }
+  }
+  if (
+    checkpoint.processVersion !== undefined &&
+    (!Number.isInteger(checkpoint.processVersion) || checkpoint.processVersion < 0)
+  ) {
+    invalidCheckpoint();
+  }
+  if (checkpoint.nodeBindings !== undefined) {
+    validateNodeBindings(checkpoint.nodeBindings);
+  }
+  if (options.operation === 'stateRepair') {
+    invalidCheckpoint();
+  }
+  if (checkpoint.stage === 'completed' && options.operationStatus !== undefined && options.operationStatus !== 'completed') {
+    invalidCheckpoint();
+  }
+  if (options.operationStatus === 'completed' && checkpoint.stage !== 'completed') {
+    invalidCheckpoint();
+  }
+  return checkpoint;
+}
+
+function advanceProcessStagedCheckpoint(previous, event, input = {}) {
+  assertObject(input);
+  if (event === 'adapterCheckpoint') {
+    assertAllowedKeys(input, new Set(['desiredManagedHash', 'partial', 'stage']));
+    assertAdapterCheckpointStage(input.stage);
+    return advanceProcessStageCheckpoint(previous, input.stage, input.partial || {}, {
+      desiredManagedHash: input.desiredManagedHash,
+    });
+  }
+  if (event === 'reconciledRemoteComplete') {
+    assertAllowedKeys(input, new Set(['desiredManagedHash']));
+    let checkpoint = previous;
+    let index = checkpoint ? stageIndex(checkpoint.stage) : -1;
+    const publishedIndex = stageIndex('published');
+    while (index < publishedIndex) {
+      index += 1;
+      checkpoint = advanceProcessStageCheckpoint(checkpoint, PROCESS_STAGES[index], {}, {
+        desiredManagedHash: input.desiredManagedHash,
+      });
+    }
+    return checkpoint;
+  }
+  if (event === 'readbackVerified') {
+    assertAllowedKeys(input, new Set(['desiredManagedHash', 'observedManagedHash']));
+    if (previous && previous.stage === 'readback_verified') {
+      validateProcessStageCheckpoint(previous, { desiredManagedHash: input.desiredManagedHash });
+      if (previous.observedManagedHash !== input.observedManagedHash) {
+        invalidCheckpoint();
+      }
+      return clonePlain(previous);
+    }
+    return advanceProcessStageCheckpoint(previous, 'readback_verified', {}, input);
+  }
+  if (event === 'completed') {
+    assertAllowedKeys(input, new Set(['desiredManagedHash']));
+    return advanceProcessStageCheckpoint(previous, 'completed', {}, {
+      desiredManagedHash: input.desiredManagedHash,
+    });
+  }
+  invalidCheckpoint();
+}
+
+function isProcessStageCheckpointRemoteComplete(checkpoint, options = {}) {
+  if (!checkpoint) {
+    return false;
+  }
+  validateProcessStageCheckpoint(checkpoint, options);
+  return stageIndex(checkpoint.stage) >= stageIndex('published');
+}
+
+function advanceProcessStageCheckpoint(previous, stage, partial = {}, options = {}) {
+  if (previous !== undefined && previous !== null) {
+    validateProcessStageCheckpoint(previous, {
+      desiredManagedHash: options.desiredManagedHash,
+    });
+  }
+  assertObject(partial);
+  assertAllowedKeys(partial, ADAPTER_PARTIAL_KEYS);
+  const expectedIndex = previous ? stageIndex(previous.stage) + 1 : 0;
+  if (PROCESS_STAGES[expectedIndex] !== stage) {
+    invalidCheckpoint();
+  }
+
+  const next = clonePlain(previous) || {};
+  next.stage = stage;
+  mergeIdentityProperty(next, partial, 'processCode');
+  mergeIdentityProperty(next, partial, 'processId');
+  mergeIdentityProperty(next, partial, 'processVersion');
+  mergeNodeBindings(next, partial.nodeBindings);
+  next.desiredManagedHash = options.desiredManagedHash;
+  if (options.observedManagedHash !== undefined) {
+    next.observedManagedHash = options.observedManagedHash;
+  }
+  return validateProcessStageCheckpoint(next, {
+    desiredManagedHash: options.desiredManagedHash,
+  });
+}
+
+function assertAdapterCheckpointStage(stage) {
+  if (!ADAPTER_CHECKPOINT_STAGES.has(stage)) {
+    invalidCheckpoint();
+  }
+}
+
+function mergeIdentityProperty(target, source, property) {
+  if (source[property] === undefined) {
+    return;
+  }
+  if (target[property] !== undefined && target[property] !== source[property]) {
+    invalidCheckpoint();
+  }
+  target[property] = source[property];
+}
+
+function mergeNodeBindings(target, incoming) {
+  if (incoming === undefined) {
+    return;
+  }
+  validateNodeBindings(incoming);
+  const merged = Object.create(null);
+  for (const [key, binding] of Object.entries(target.nodeBindings || {})) {
+    merged[key] = clonePlain(binding);
+  }
+  for (const [key, binding] of Object.entries(incoming)) {
+    if (Object.prototype.hasOwnProperty.call(merged, key)) {
+      if (
+        merged[key].nodeId !== binding.nodeId ||
+        merged[key].componentName !== binding.componentName
+      ) {
+        invalidCheckpoint();
+      }
+      continue;
+    }
+    merged[key] = clonePlain(binding);
+  }
+  target.nodeBindings = merged;
+}
+
+function validateNodeBindings(value) {
+  assertObject(value);
+  for (const [key, binding] of Object.entries(value)) {
+    if (!SEMANTIC_KEY_PATTERN.test(key)) {
+      invalidCheckpoint();
+    }
+    assertObject(binding);
+    assertAllowedKeys(binding, NODE_BINDING_KEYS);
+    if (!isNonEmptyString(binding.nodeId) || !isNonEmptyString(binding.componentName)) {
+      invalidCheckpoint();
+    }
+  }
+}
+
+function assertObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    invalidCheckpoint();
+  }
+}
+
+function assertAllowedKeys(value, allowed) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      invalidCheckpoint();
+    }
+  }
+}
+
+function assertHash(value) {
+  if (typeof value !== 'string' || !HASH_PATTERN.test(value)) {
+    invalidCheckpoint();
+  }
+}
+
+function stageIndex(stage) {
+  return PROCESS_STAGES.indexOf(stage);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function clonePlain(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function invalidCheckpoint() {
+  throw schemaError('SCHEMA_APPLY_JOURNAL_INVALID', 'Schema staged apply checkpoint is invalid.');
+}
+
+module.exports = {
+  advanceProcessStageCheckpoint,
+  advanceProcessStagedCheckpoint,
+  isProcessStageCheckpointRemoteComplete,
+  validateProcessStageCheckpoint,
+};

package/lib/report/append.js

@@ -16,7 +16,7 @@
 const fs = require('fs');
 
 const { CliError } = require('../core/cli-error');
-const { createAuthRef, createYidaClient, isAuthRefReady } = require('../core/yida-client');
+const { createAuthRef, isAuthRefReady } = require('../core/yida-client');
 const { CHART_COMPONENT_MAP } = require('./constants');
 const {
   buildDataSetModelMap,
@@ -32,32 +32,12 @@ const {
 const { genNodeId, genFieldId, randomId } = require('./constants');
 const { warn } = require('../core/chalk');
 const { parseOpenOption, withBrowserHandoff } = require('../core/browser-handoff');
+const { getReportSchema, saveReportSchema } = require('./http');
+const { requireSchemaServerRevision } = require('../schema/server-revision');
 
 // ── HTTP：获取已有报表 Schema ─────────────────────────
 // GET 用 /alibaba/web/ 路径
 
-async function getReportSchema(authRef, appType, reportId) {
-  return createYidaClient({ authRef }).get(
-    `/alibaba/web/${appType}/_view/query/formdesign/getFormSchema.json`,
-    { formUuid: reportId, schemaVersion: 'V5' }
-  );
-}
-
-// ── HTTP：保存报表 Schema ─────────────────────────────
-// SAVE 用 /dingtalk/web/ 路径
-
-async function saveSchema(authRef, appType, reportId, schema) {
-  return createYidaClient({ authRef }).postForm(
-    `/dingtalk/web/${appType}/_view/query/formdesign/saveFormSchema.json`,
-    {
-      formUuid: reportId,
-      content: JSON.stringify(schema),
-      schemaVersion: 'V5',
-      importSchema: 'true',
-    }
-  );
-}
-
 function ensureSession() {
   const authRef = createAuthRef();
   if (!isAuthRefReady(authRef)) {
@@ -189,7 +169,7 @@ async function main(args) {
   // Step 1: 读取登录态
   warn('\n[Step 1] 读取登录态...');
   const authRef = ensureSession();
-  const corpId = authRef.corpId || (authRef.authData && authRef.authData.corp_id) || '';
+  const corpId = authRef.corpId || authRef.cookieData.corp_id || '';
   warn('登录态就绪，域名:', authRef.baseUrl);
 
   // Step 2: 读取图表定义
@@ -228,6 +208,7 @@ async function main(args) {
   const schema = typeof getResult.content === 'string'
     ? JSON.parse(getResult.content)
     : getResult.content;
+  const serverRevision = requireSchemaServerRevision(getResult);
 
   const page = schema.pages[0];
   const rootContent = page.componentsTree[0].children.find(
@@ -305,7 +286,7 @@ async function main(args) {
 
   // Step 6: 保存 Schema
   warn('\n[Step 5] 保存 Schema...');
-  const saveResult = await saveSchema(authRef, appType, reportId, schema);
+  const saveResult = await saveReportSchema(authRef, appType, reportId, schema, serverRevision);
 
   if (!saveResult || !saveResult.success) {
     const errorMsg = saveResult ? saveResult.errorMsg || '未知错误' : '请求失败';
@@ -352,5 +333,5 @@ module.exports = {
   parseArgs,
   readChartsDefinition,
   getReportSchema,
-  saveSchema,
+  saveSchema: saveReportSchema,
 };

package/lib/report/http.js

@@ -2,30 +2,56 @@
 
 const { createYidaClient } = require('../core/yida-client');
 const { buildYidaI18n } = require('../core/yida-i18n');
+const { requireSchemaServerRevision } = require('../schema/server-revision');
 
 /**
  * 调用 saveFormSchemaInfo 创建空白报表
  */
 async function createBlankReport(authRef, appType, reportTitle) {
-  return createYidaClient({ authRef }).postForm(`/dingtalk/web/${appType}/query/formdesign/saveFormSchemaInfo.json`, {
+  return createYidaClient({ authRef }).postForm(`/dingtalk/web/${appType}/query/formdesign/saveFormSchemaInfo.json`, auth => ({
+    _csrf_token: auth.csrfToken,
     formType: 'report',
     title: JSON.stringify(buildYidaI18n(reportTitle, { en_US: reportTitle, ja_JP: reportTitle })),
-  });
+  }));
+}
+
+async function getReportSchema(authRef, appType, reportId) {
+  const result = await createYidaClient({ authRef }).get(
+    `/alibaba/web/${appType}/_view/query/formdesign/getFormSchema.json`,
+    { formUuid: reportId, schemaVersion: 'V5' }
+  );
+  if (result && result.success !== false) {
+    requireSchemaServerRevision(result, createRevisionError);
+  }
+  return result;
 }
 
 /**
  * 调用 saveFormSchema 保存报表 Schema
  */
-async function saveReportSchema(authRef, appType, reportId, schema) {
-  return createYidaClient({ authRef }).postForm(`/dingtalk/web/${appType}/_view/query/formdesign/saveFormSchema.json`, {
+async function saveReportSchema(authRef, appType, reportId, schema, serverRevision) {
+  const gmtModified = requireSchemaServerRevision(
+    { gmtModified: serverRevision },
+    createRevisionError
+  );
+  return createYidaClient({ authRef }).postFormOnce(`/dingtalk/web/${appType}/_view/query/formdesign/saveFormSchema.json`, auth => ({
+    _csrf_token: auth.csrfToken,
     formUuid: reportId,
     content: JSON.stringify(schema),
     schemaVersion: 'V5',
     importSchema: 'true',
-  });
+    gmtModified,
+  }));
+}
+
+function createRevisionError() {
+  const error = new Error('Report Schema revision is missing or invalid.');
+  error.code = 'REPORT_SCHEMA_REVISION_INVALID';
+  return error;
 }
 
 module.exports = {
   createBlankReport,
+  getReportSchema,
   saveReportSchema,
 };

package/lib/report/index.js

@@ -16,7 +16,8 @@ const {
 const { genFieldId } = require('./constants');
 
 const { warn } = require('../core/chalk');
-const { createBlankReport, saveReportSchema } = require('./http');
+const { createBlankReport, getReportSchema, saveReportSchema } = require('./http');
+const { requireSchemaServerRevision } = require('../schema/server-revision');
 const { parseOpenOption, withBrowserHandoff } = require('../core/browser-handoff');
 
 // ── 参数解析 ──────────────────────────────────────────
@@ -284,6 +285,13 @@ async function main(args) {
   const reportId = createResult.content.formUuid || createResult.content;
   warn('报表创建成功，ID:', reportId);
 
+  const shellResult = await getReportSchema(authRef, appType, reportId);
+  if (!shellResult || shellResult.success === false) {
+    const errorMsg = shellResult ? shellResult.errorMsg || '未知错误' : '请求失败';
+    throw new CliError(errorMsg, { code: 'CREATE_REPORT_GET_SCHEMA_FAILED' });
+  }
+  const serverRevision = requireSchemaServerRevision(shellResult);
+
   // Step 4: 构建报表 Schema
   warn('\n[Step 4] 构建报表 Schema...');
   const schema = buildReportSchema(reportTitle, charts, reportId, corpId);
@@ -416,7 +424,7 @@ async function main(args) {
 
   // Step 5: 保存报表 Schema
   warn('\n[Step 5] 保存报表 Schema...');
-  const saveResult = await saveReportSchema(authRef, appType, reportId, schema);
+  const saveResult = await saveReportSchema(authRef, appType, reportId, schema, serverRevision);
 
   if (!saveResult || !saveResult.success) {
     const errorMsg = saveResult

package/lib/samples/yida-canvas-custom-page/business-list.canvas.jsx

@@ -136,7 +136,12 @@ const DEFAULT_INSIGHTS = [
     suggestion: '高频批量动作固定在列表底部，选中记录后右侧展示下一步。',
   },
 ];
-const DEFAULT_DATA_BINDING = { enabled: false, mode: 'seed' };
+const DEFAULT_DATA_BINDING = { enabled: false, mode: 'seed', seedStrategy: 'sample-only' };
+const EMPTY_METRICS = [
+  { label: '真实记录', value: '0', hint: '未接入表单数据' },
+  { label: '数据来源', value: '未接入', hint: '请在 page-spec.json 配置 dataBinding' },
+  { label: '演示记录', value: '0', hint: '演示记录需先写入真实表单' },
+];
 const BACKGROUND_IMAGES = {
   hero: 'https://images.unsplash.com/photo-1566346654781-14e3ef6ee988?auto=format&fit=crop&w=1400&q=80',
   card: 'https://images.unsplash.com/photo-1759884247160-27b8465544b6?auto=format&fit=crop&w=1200&q=80',
@@ -268,6 +273,11 @@ function isDataBindingEnabled(binding) {
   return Boolean(binding && binding.enabled && binding.mode && binding.mode !== 'seed');
 }
 
+function isSampleSeedPreview(binding) {
+  const mode = binding && binding.mode ? binding.mode : 'seed';
+  return RESEARCH_LEVEL === 'sample' && !isDataBindingEnabled(binding) && mode === 'seed';
+}
+
 function getCsrfToken() {
   try {
     return (window.g_config && (window.g_config._csrf_token || window.g_config.csrfToken)) || '';
@@ -393,7 +403,7 @@ function normalizeBoundRows(rows, binding) {
 }
 
 function useYidaData(binding) {
-  const [state, setState] = React.useState({ loading: false, error: '', rows: [], totalCount: null });
+  const [state, setState] = React.useState(() => ({ loading: isDataBindingEnabled(binding), error: '', rows: [], totalCount: null }));
   React.useEffect(() => {
     if (!isDataBindingEnabled(binding)) { return undefined; }
     const controller = new AbortController();
@@ -446,7 +456,9 @@ function YidaComp() {
     period: index % 2 === 0 ? 'week' : 'month',
   })), []);
   const dataState = useYidaData(DATA_BINDING);
-  const rows = dataState.rows.length ? dataState.rows : seedRows;
+  const usesSeedRows = isSampleSeedPreview(DATA_BINDING);
+  const metricItems = usesSeedRows || isDataBindingEnabled(DATA_BINDING) ? METRICS : EMPTY_METRICS;
+  const rows = dataState.rows.length ? dataState.rows : (usesSeedRows ? seedRows : []);
   const filteredRows = useMemo(() => {
     const kw = (filters.keyword || '').trim().toLowerCase();
     return rows.filter((row) => {
@@ -547,6 +559,11 @@ function YidaComp() {
           .oy-list-insight { padding: 12px 14px; margin: 0 0 16px; border-radius: 14px; border: 1px solid color-mix(in srgb, var(--oy-brand), transparent 70%); background: #EFF6FF; }
           .oy-list-brief { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin-top: 10px; }
           .oy-data-status { margin: 0 0 12px; padding: 10px 12px; border-radius: 8px; border: 1px solid var(--oy-line); background: var(--oy-surface-soft); display: flex; gap: 8px; flex-wrap: wrap; align-items: center; }
+          .oy-list-empty-state { min-height: 278px; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 8px; padding: 32px 22px; text-align: center; border: 1px dashed var(--oy-line); border-radius: 14px; background: color-mix(in srgb, var(--oy-brand-soft), #fff 58%); }
+          .oy-list-empty-state h4 { margin: 0; color: var(--oy-text); }
+          .oy-list-empty-state .ant-typography { max-width: 540px; }
+          .oy-list-empty-actions { display: flex; gap: 10px; flex-wrap: wrap; justify-content: center; margin-top: 8px; }
+          .oy-list-empty-detail { min-height: 360px; display: flex; flex-direction: column; justify-content: center; padding: 8px; }
           @media (max-width: 960px) {
             .oy-business-list { padding: 20px; }
             .oy-list-grid, .oy-list-metrics, .oy-list-filter, .oy-list-hero { grid-template-columns: 1fr; }
@@ -573,7 +590,7 @@ function YidaComp() {
             </header>
 
             <section className="oy-list-metrics">
-              {METRICS.slice(0, 3).map((item) => (
+              {metricItems.slice(0, 3).map((item) => (
                 <div className="oy-list-metric" key={item.label}>
                   <Text>{item.label}</Text>
                   <div className="oy-list-number">{item.value}</div>
@@ -594,15 +611,39 @@ function YidaComp() {
                       {dataState.error || (dataState.loading ? '正在读取真实数据' : '真实数据已接入' + (dataState.totalCount === null ? '' : '：' + dataState.totalCount + ' 条'))}
                     </Text>
                   </div>
-                ) : null}
-                <Table
-                  columns={columns}
-                  dataSource={filteredRows}
-                  pagination={false}
-                  size="middle"
-                  rowClassName={(_, index) => index === activeIndex ? 'is-selected-row' : ''}
-                  onRow={(_, index) => ({ onClick: () => setSelected(index || 0) })}
-                />
+                ) : (
+                  <div className="oy-data-status">
+                    <Tag color={usesSeedRows ? 'warning' : 'default'}>{usesSeedRows ? 'Sample seed' : '未接数据'}</Tag>
+                    <Text type="secondary">
+                      {usesSeedRows ? '当前为 sample/seed 预览数据，未接真实表单。' : '未配置真实表单 dataBinding，当前不显示前端 seed 列表。'}
+                    </Text>
+                  </div>
+                )}
+                {filteredRows.length ? (
+                  <Table
+                    columns={columns}
+                    dataSource={filteredRows}
+                    pagination={false}
+                    size="middle"
+                    rowClassName={(_, index) => index === activeIndex ? 'is-selected-row' : ''}
+                    onRow={(_, index) => ({ onClick: () => setSelected(index || 0) })}
+                  />
+                ) : (
+                  <div className="oy-list-empty-state">
+                    <Title level={4}>{dataState.loading ? '正在读取真实表单数据' : isDataBindingEnabled(DATA_BINDING) ? '暂无真实表单记录' : usesSeedRows ? '暂无匹配的 sample 记录' : '未接入真实表单数据'}</Title>
+                    <Paragraph type="secondary">
+                      {isDataBindingEnabled(DATA_BINDING)
+                        ? '当前数据源已接入宜搭表单。若需要演示内容，请先通过表单数据写入链路创建 demo records，再刷新本页读取。'
+                        : usesSeedRows
+                          ? '这是模板原样发布的 sample/seed 数据，仅用于离线预览模板结构。'
+                          : '完整应用交付页不会用前端 seedRows 冒充业务记录。请在 page-spec.json 写入 dataBinding.mode=form，或先登记真实表单记录。'}
+                    </Paragraph>
+                    <div className="oy-list-empty-actions">
+                      <Button type="primary">{PAGE.primaryCta || '登记记录'}</Button>
+                      <Button>刷新数据</Button>
+                    </div>
+                  </div>
+                )}
               </div>
               <BulkActionBar actions={INTERACTION_PROFILE.bulkActions} count={filteredRows.length} />
             </section>
@@ -613,7 +654,15 @@ function YidaComp() {
                   <Text strong>{insight.suggestion}</Text>
                 </div>
               ) : null}
-              <DetailPreview active={active} page={PAGE} roadmap={ROADMAP} />
+              {filteredRows.length ? (
+                <DetailPreview active={active} page={PAGE} roadmap={ROADMAP} />
+              ) : (
+                <div className="oy-list-empty-detail">
+                  <Tag color="default">空态入口</Tag>
+                  <Title level={4} style={{ marginTop: 14 }}>等待真实记录</Title>
+                  <Paragraph type="secondary">接入表单后，选中列表记录将在这里展示摘要、负责人、状态和处理路径。</Paragraph>
+                </div>
+              )}
             </aside>
           </div>
         </div>