openyida 2026.10.20-2 → 2026.10.21

package/lib/print-template/codes.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const { fail, object, unwrap } = require('./model');
+const FORMATS = ['qrcode', 'barcode'];
+const PREFIXES = ['textField', 'numberField', 'selectField', 'radioField', 'serialNo'];
+const CODE_EDITIONS = new Set(['pro', 'vip', 'isv', 'hybrid_cloud']);
+
+/** Match the native editor's field-code whitelist, without enabling unrelated field types. */
+function eligible(field) {
+  return typeof field?.key === 'string' && PREFIXES.some(prefix => field.key.startsWith(prefix))
+    && !/\.(qrcode|barcode)$/.test(field.key);
+}
+
+/** Read the existing edition and rollout gate; never change entitlements or gray configuration. */
+async function capabilities(client) {
+  const results = await Promise.allSettled([
+    client.get('/query/commodity/getSimpleCommodityInfo.json', {}).then(response => unwrap(response, 'getSimpleCommodityInfo')),
+    client.get('/query/compromiseDing/orgInGray.json', { grayKey: 'yida_fe_print_support_qrcode' }).then(response => unwrap(response, 'orgInGray')),
+  ]);
+  const edition = results[0].status === 'fulfilled' && object(results[0].value)
+    ? String(results[0].value.corpVersion || '').toLowerCase() : '';
+  const gray = results[1].status === 'fulfilled' && typeof results[1].value === 'boolean' ? results[1].value : null;
+  const enabled = CODE_EDITIONS.has(edition) && gray === true;
+  return { enabled, edition, gray, reason: enabled ? null : !edition ? 'edition_unverified'
+    : !CODE_EDITIONS.has(edition) ? 'edition_not_supported' : gray === false ? 'feature_not_enabled' : 'feature_unverified' };
+}
+
+/** Derive the native .qrcode/.barcode image key from a live, eligible field. */
+function transform(field, format) {
+  if (!FORMATS.includes(format) || !eligible(field)) { fail('UNSUPPORTED', `field code: ${field?.label || field?.key}`); }
+  if (!field.codeFormats?.includes(format)) {
+    fail('CODE_UNAVAILABLE', `${format}: ${field.codeUnavailableReason || 'capability_unverified'}`);
+  }
+  return { ...field, key: `${field.key}.${format}`, label: `${field.label}.${format === 'qrcode' ? '二维码' : '条形码'}`, type: 'img', codeFormat: format };
+}
+
+/** Validate derived keys in native exports as strictly as authored code blocks. */
+function resolveNative(key, dictionary) {
+  const match = typeof key === 'string' && /^(.*)\.(qrcode|barcode)$/.exec(key);
+  if (!match) { return null; }
+  const field = dictionary.find(item => item.key === match[1]);
+  if (!field) { fail('FIELD_REFERENCE', match[1]); }
+  return transform(field, match[2]);
+}
+
+module.exports = { FORMATS, eligible, capabilities, transform, resolveNative };

package/lib/print-template/contract.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const readActions = ['list', 'inspect', 'fields', 'files'];
+const writeActions = ['create', 'copy', 'save', 'restore', 'settings', 'status', 'order', 'render'];
+const usage = 'print-template <list|inspect|fields|build|create|copy|save|restore|settings|status|order|render|files> <appType> <formUuid> [templateId] [--config <file>] [--scene <order|quotation|delivery|receipt|approval|codes>] [--bindings <file>] [--name <title>] [--expected-hash <hash>] [--backup <file>] [--out <file>] [--status START|STOP] [--instance <id>] [--page <n>] [--size <n>] [--allow-permission-change] [--json] | print-template <list|render> --detail-url <url> [--template-id <id>] [--json]';
+
+/** Shared manifest metadata keeps ordinary and managed agents on the same native contract. */
+const printTemplateCommand = ['print-template', ['print-template'], usage, 'print_template.description', {
+  output: 'json',
+  managedRun: { scope: 'actions', actions: {
+    ...Object.fromEntries([...readActions, 'build'].map(action => [action, { scope: 'app', appPosition: 1 }])),
+    ...Object.fromEntries(writeActions.filter(action => action !== 'render').map(action => [action,
+      { scope: 'app', appPosition: 1, mutation: { operation: 'update_form', formUuidPosition: 2 } }])),
+    // PDF generation is explicit and may consume storage; managed app runs cannot invoke it.
+    render: { scope: 'denied', reason: 'native_pdf_generation' },
+  } },
+  examples: ['openyida print-template list --detail-url "https://tenant.aliwork.com/APP_XXX/formDetail/FORM_XXX?formInstId=FINST_XXX" --json',
+    'openyida print-template render --detail-url "https://tenant.aliwork.com/APP_XXX/formDetail/FORM_XXX?formInstId=FINST_XXX" --template-id 123 --json',
+    'openyida print-template fields APP_XXX FORM_XXX --json',
+    'openyida print-template build APP_XXX FORM_XXX --scene quotation --bindings quote-fields.json --out quote.json --json',
+    'openyida print-template create APP_XXX FORM_XXX --name "报价单" --config quote.json --json',
+    'openyida print-template save APP_XXX FORM_XXX 123 --config quote.json --expected-hash <inspect-hash> --json'],
+  notes: ['Native rich-text YiDA printing only; Word, DingDang and government printing use different editors. build compiles a named-field document or validates a complete native body, without saving it. build --scene selects one of six reusable samples and --bindings maps semantic roles to actual field names/IDs before validation. create --config validates first, creates and saves content; failures after creation expose createdTemplateId and must be resumed with inspect/save instead of repeated create. qrcode/barcode blocks and field/column render options use native dynamic image keys, with validated field prefixes, current edition and feature availability. fields reports codeFormats; barcode values must follow native character limits and are never silently rewritten. inspect --out exports a full snapshot; restore restores its content only to the same target. save is immediately effective, with no separate publish action. Hashes are required for updates; body saves also send the native gmtModified concurrency token when present. Every remote mutation backs up first, never retries, and verifies readback. Uncertain create/copy results must be inspected before retrying. settings preserves untranslated locales and does not change roleData unless supplied with --allow-permission-change. Built-in default template body cannot be edited. render requests one native PDF and returns a file ID, not proof of generation or physical printing; files lists generation records. list --instance and --detail-url use the runtime record-authorized template list instead of the administration list; render uses that same list and never reads an admin-only template body. URL mode only accepts known native detail routes and the authenticated origin; template choice is explicit. It prints record data through native templates, not arbitrary website pixels. No edition/quota changes. Custom CSS, fixed pages, paper size, margins, headers/footers and automatic totals are not guaranteed by this legacy editor.'],
+}];
+
+const printTemplateEffects = { mutates_yida: true, mutates_local: true, read_actions: readActions,
+  mutating_actions: ['build', ...writeActions], note: 'build only writes an optional local output; inspect/fields write local exports only with --out.' };
+const printTemplatePermission = { preauthorized_actions: ['build', 'create', 'copy', 'save', 'restore', 'status', 'order'],
+  ask_actions: ['settings', 'render'] };
+
+module.exports = { printTemplateCommand, printTemplateEffects, printTemplatePermission, usage };

package/lib/print-template/detail.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { fail } = require('./model');
+
+/** Parse native record links as identifiers only; never fetch arbitrary URLs or forward their query. */
+function parse(value) {
+  let url;
+  try { url = new URL(value); } catch (_) { fail('INVALID_CONFIG', 'detail URL'); }
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.hash) { fail('INVALID_CONFIG', 'native detail URL'); }
+  for (const key of ['appType', 'formUuid', 'formInstId', 'activityId']) {
+    if (url.searchParams.getAll(key).length > 1) { fail('INVALID_CONFIG', `duplicate ${key}`); }
+  }
+  const modern = /^\/(APP_[\w-]+)\/(formDetail|processDetail)\/(FORM[_-][\w-]+)\/?$/.exec(url.pathname);
+  const legacy = /^\/alibaba\/(?:web|mobile)\/(APP_[\w-]+)\/inst\/(formEdit|taskDetail)\.html$/.exec(url.pathname);
+  if (!modern && !legacy) { fail('UNSUPPORTED', 'native formDetail/processDetail link required'); }
+  const appType = (modern || legacy)[1];
+  const formUuid = modern ? modern[3] : url.searchParams.get('formUuid');
+  const instance = url.searchParams.get('formInstId');
+  const activityId = url.searchParams.get('activityId');
+  if (!/^FORM[_-][\w-]+$/.test(formUuid || '') || !/^[\w-]+$/.test(instance || '')
+    || activityId !== null && !/^[\w-]+$/.test(activityId)
+    || url.searchParams.has('appType') && url.searchParams.get('appType') !== appType
+    || url.searchParams.has('formUuid') && url.searchParams.get('formUuid') !== formUuid) { fail('INVALID_CONFIG', 'detail target'); }
+  return { appType, formUuid, instance, ...(activityId ? { activityId } : {}), origin: url.origin,
+    kind: modern ? modern[2] : legacy[2] === 'formEdit' ? 'formDetail' : 'processDetail' };
+}
+
+/** Refuse cross-organization routing; authenticate to the link's environment before printing. */
+function verifyOrigin(target, client) {
+  const base = client.getAuthRef?.()?.baseUrl;
+  let origin;
+  try { origin = new URL(base).origin; } catch (_) { fail('TARGET_MISMATCH', 'authenticated origin unavailable'); }
+  if (origin !== target.origin) { fail('TARGET_MISMATCH', 'detail URL origin differs from authenticated environment'); }
+}
+
+module.exports = { parse, verifyOrigin };

package/lib/print-template/model.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { CliError } = require('../core/cli-error');
+const { t } = require('../core/i18n');
+const { resolveProjectRoot } = require('../core/utils');
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** Fail with a stable code; platform failures retain their native diagnostic. */
+function fail(code, detail, details) {
+  throw new CliError(t('print_template.error', detail), { code: `PRINT_TEMPLATE_${code}`, details });
+}
+
+/** Parse JSON strings used by the native print editor without evaluating them. */
+function json(value, label) {
+  try { return typeof value === 'string' ? JSON.parse(value) : value; }
+  catch (_) { return fail('INVALID_CONFIG', label); }
+}
+
+/** Reject prototype keys recursively, including imported native configurations. */
+function safe(value) {
+  if (!value || typeof value !== 'object') { return; }
+  for (const key of Object.keys(value)) {
+    if (['__proto__', 'constructor', 'prototype'].includes(key)) { fail('INVALID_CONFIG', key); }
+    safe(value[key]);
+  }
+}
+
+/** Normalize translated labels without discarding the original locale object. */
+function label(value) {
+  let parsed = value;
+  if (typeof value === 'string') {
+    try { parsed = JSON.parse(value); } catch (_) { return value; }
+  }
+  return object(parsed) ? parsed.zh_CN || parsed.en_US || parsed.key || '' : String(parsed ?? '');
+}
+
+/** Canonical object key ordering for stale-edit fingerprints. */
+function stable(value) {
+  if (Array.isArray(value)) { return value.map(stable); }
+  return object(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])])) : value;
+}
+
+/** Compare authored values while allowing the server to add nullable dictionary metadata. */
+function matches(expected, actual) {
+  if (Array.isArray(expected)) { return Array.isArray(actual) && actual.length === expected.length && expected.every((value, i) => matches(value, actual[i])); }
+  if (object(expected)) { return object(actual) && Object.entries(expected).every(([key, value]) => matches(value, actual[key])); }
+  return expected === actual;
+}
+
+/** Normalize only the native content fields; missing content means an unsaved template. */
+function content(raw) {
+  if (!object(raw)) { fail('INVALID_RESPONSE', 'template content'); }
+  if (!Object.keys(raw).length) { return { termContents: '', termJsonAttr: [], dictionaryList: [], gmtModified: null }; }
+  const result = { ...raw, termJsonAttr: json(raw.termJsonAttr ?? [], 'termJsonAttr'),
+    dictionaryList: json(raw.dictionaryList ?? [], 'dictionaryList') };
+  if (typeof result.termContents !== 'string' || !Array.isArray(result.termJsonAttr) || !Array.isArray(result.dictionaryList)) {
+    fail('INVALID_RESPONSE', 'termContents / termJsonAttr / dictionaryList');
+  }
+  safe(result);
+  return result;
+}
+
+/** Hash metadata and body together, including the server concurrency timestamp. */
+function hash(snapshot) {
+  return crypto.createHash('sha256').update(JSON.stringify(stable({ template: snapshot.template, content: snapshot.content }))).digest('hex');
+}
+
+/** Write exports/backups exclusively and keep business configuration private on disk. */
+function write(value, filename, kind = 'backup') {
+  const output = filename ? path.resolve(filename) : path.join(resolveProjectRoot().projectRoot,
+    '.cache', 'openyida', 'print-template', `${kind}-${Date.now()}-${crypto.randomUUID()}.json`);
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.writeFileSync(output, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  return output;
+}
+
+/** Load explicit user-authored input; never consume arbitrary files as instructions. */
+function read(filename) {
+  const result = json(fs.readFileSync(path.resolve(filename), 'utf8'), filename);
+  safe(result);
+  return result;
+}
+
+/** Strictly recognize native success envelopes, including auth sentinels and false payloads. */
+function unwrap(response, endpoint) {
+  if (!response || response.success !== true || response.__needLogin || response.__csrfExpired || response.content === false) {
+    fail('API_ERROR', response?.errorMsg || response?.message || endpoint,
+      { endpoint, platformErrorCode: response?.errorCode, needLogin: !!response?.__needLogin });
+  }
+  return response.content;
+}
+
+module.exports = { object, fail, json, safe, label, stable, matches, content, hash, write, read, unwrap };

package/lib/print-template/print-template.js

@@ -0,0 +1,302 @@
+'use strict';
+
+const { isDeepStrictEqual } = require('util');
+const { t } = require('../core/i18n');
+const { CliError } = require('../core/cli-error');
+const { createYidaClient } = require('../core/yida-client');
+const { buildYidaTitleI18n } = require('../core/yida-i18n');
+const m = require('./model');
+const builder = require('./builder');
+const codes = require('./codes');
+const scenes = require('./scenes');
+const detail = require('./detail');
+
+const ACTIONS = ['list', 'inspect', 'fields', 'build', 'create', 'copy', 'save', 'restore', 'settings', 'status', 'order', 'render', 'files'];
+const TARGETED = ['inspect', 'copy', 'save', 'restore', 'settings', 'status', 'render'];
+const HASHED = ['copy', 'save', 'restore', 'settings', 'status'];
+const OPTIONS = {
+  list: ['--instance', '--detail-url'], inspect: ['--out'], fields: ['--out'], build: ['--config', '--scene', '--bindings', '--out'], create: ['--name', '--config', '--backup'],
+  copy: ['--name', '--expected-hash', '--backup'], save: ['--config', '--expected-hash', '--backup'],
+  restore: ['--config', '--expected-hash', '--backup'], settings: ['--config', '--expected-hash', '--backup', '--allow-permission-change'],
+  status: ['--status', '--expected-hash', '--backup'], order: ['--config', '--expected-hash', '--backup'],
+  render: ['--instance', '--detail-url', '--template-id'], files: ['--page', '--size'],
+};
+
+/** Parse exact command contracts before auth or remote access. */
+function parseArgs(args) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (Object.hasOwn(flags, arg)) { m.fail('USAGE', arg); }
+    if (['--json', '--help', '-h', '--allow-permission-change'].includes(arg)) { flags[arg] = true; continue; }
+    if (Object.values(OPTIONS).flat().includes(arg)) {
+      if (!args[i + 1] || args[i + 1].startsWith('-')) { m.fail('USAGE', arg); }
+      flags[arg] = args[++i]; continue;
+    }
+    if (arg.startsWith('-')) { m.fail('USAGE', arg); }
+    positional.push(arg);
+  }
+  if (flags['--help'] || flags['-h']) { return { help: true }; }
+  if (flags['--detail-url']) {
+    if (!['list', 'render'].includes(positional[0]) || positional.length !== 1 || flags['--instance']) { m.fail('USAGE', '--detail-url: list/render only, without positional target'); }
+    const resolved = detail.parse(flags['--detail-url']);
+    positional.push(resolved.appType, resolved.formUuid);
+    if (positional[0] === 'render') { positional.push(flags['--template-id']); }
+    flags['--instance'] = resolved.instance;
+  } else if (flags['--template-id']) { m.fail('USAGE', '--template-id requires --detail-url'); }
+  const [action, appType, formUuid, templateId] = positional;
+  if (!ACTIONS.includes(action) || positional.length !== (TARGETED.includes(action) ? 4 : 3)
+    || !/^APP_[A-Za-z0-9_-]+$/.test(appType || '') || !/^[A-Za-z0-9_-]+$/.test(formUuid || '')
+    || TARGETED.includes(action) && !/^(0|[1-9]\d*)$/.test(templateId || '')
+    || Object.keys(flags).some(key => key !== '--json' && !OPTIONS[action].includes(key))) { m.fail('USAGE', t('print_template.usage')); }
+  if (['save', 'restore', 'settings', 'order'].includes(action) && !flags['--config']
+    || action === 'build' && (Boolean(flags['--config']) === Boolean(flags['--scene']) || flags['--bindings'] && !flags['--scene']
+      || flags['--scene'] && !scenes.names.includes(flags['--scene']))
+    || ['create', 'copy'].includes(action) && !flags['--name']?.trim()
+    || (HASHED.includes(action) || action === 'order') && !/^[a-f0-9]{64}$/.test(flags['--expected-hash'] || '')
+    || action === 'status' && !['START', 'STOP'].includes(flags['--status'])
+    || (action === 'render' || flags['--instance']) && !/^[A-Za-z0-9_-]+$/.test(flags['--instance'] || '')) { m.fail('USAGE', t('print_template.usage')); }
+  for (const [key, max] of [['--page', 100000], ['--size', 100]]) {
+    if (flags[key] !== undefined && (!/^[1-9]\d*$/.test(flags[key]) || Number(flags[key]) > max)) { m.fail('USAGE', key); }
+  }
+  if (['create', 'copy'].includes(action)) {
+    const name = flags['--name'].trim();
+    if ([...name].reduce((sum, ch) => sum + (ch.charCodeAt(0) > 127 ? 2 : 1), 0) > 40) { m.fail('INVALID_CONFIG', 'name: max 40 characters / 20 Chinese characters'); }
+  }
+  return { action, appType, formUuid, templateId, flags };
+}
+
+/** Validate a metadata-only patch, preserving translations and permission scope by default. */
+function settings(base, raw, allowPermissions) {
+  const allowed = ['title', 'description', 'fileNameConfig', 'roleData'];
+  if (!m.object(raw) || !Object.keys(raw).length || Object.keys(raw).some(key => !allowed.includes(key))) { m.fail('INVALID_CONFIG', allowed.join(', ')); }
+  const result = {};
+  for (const key of ['title', 'description']) {
+    if (!Object.hasOwn(raw, key)) { continue; }
+    const value = typeof raw[key] === 'string' ? { zh_CN: raw[key], en_US: raw[key] } : raw[key];
+    if (!m.object(value) || Object.values(value).some(item => item !== null && typeof item !== 'string')
+      || key === 'title' && !value.zh_CN?.trim()) { m.fail('INVALID_CONFIG', key); }
+    result[key] = { ...(m.object(base[key]) ? base[key] : {}), ...value };
+    if (key === 'title' && [...result[key].zh_CN].reduce((sum, ch) => sum + (ch.charCodeAt(0) > 127 ? 2 : 1), 0) > 40) { m.fail('INVALID_CONFIG', 'title length'); }
+  }
+  if (Object.hasOwn(raw, 'description') && !Object.hasOwn(raw, 'title')) { result.title = base.title; }
+  // The native rename endpoint also replaces description; preserve its sibling.
+  if (Object.hasOwn(raw, 'title') && !Object.hasOwn(raw, 'description')) { result.description = base.description; }
+  if (Object.hasOwn(raw, 'fileNameConfig')) {
+    if (typeof raw.fileNameConfig !== 'string' || !raw.fileNameConfig.trim() || raw.fileNameConfig.length > 256
+      || /#|\$[^!]|\$!(?!\{(?:originator|instanceTitle|createTime|serialNo)\})/.test(raw.fileNameConfig)) {
+      m.fail('INVALID_CONFIG', 'fileNameConfig: use $!{originator}, $!{instanceTitle}, $!{createTime}, $!{serialNo}');
+    }
+    result.fileNameConfig = raw.fileNameConfig;
+  }
+  if (Object.hasOwn(raw, 'roleData')) {
+    if (!allowPermissions) { m.fail('PERMISSION_FLAG_REQUIRED', '--allow-permission-change'); }
+    if (!Array.isArray(raw.roleData) || !raw.roleData.length || raw.roleData.some(role => !m.object(role) || typeof role.roleType !== 'string' || typeof role.roleValue !== 'string'
+      || Object.keys(role).some(key => !['roleUuid', 'roleType', 'roleValue', 'isExclude'].includes(key)))) {
+      m.fail('INVALID_CONFIG', 'native roleData');
+    }
+    result.roleData = raw.roleData;
+  }
+  return result;
+}
+
+/** Execute native print operations with exclusive backups, stale-edit checks and no write replay. */
+async function execute(parsed, client = createYidaClient(), preparedContent) {
+  const { action, appType, formUuid, templateId, flags } = parsed;
+  const detailTarget = flags['--detail-url'] ? detail.parse(flags['--detail-url']) : null;
+  if (detailTarget) { detail.verifyOrigin(detailTarget, client); }
+  const prefix = `/dingtalk/web/${appType}/query/printTemplate/`;
+  const target = { appType, formUuid, ...(templateId ? { templateId } : {}) };
+  const read = async (endpoint, params = {}) => m.unwrap(await client.get(prefix + endpoint + '.json', { formUuid, ...params }), endpoint);
+  const mutate = async (endpoint, params) => m.unwrap(await client.postFormOnce(prefix + endpoint + '.json', { formUuid, ...params }), endpoint);
+  const list = async (instance) => {
+    const raw = await read(instance ? 'listTemplateWithAuth' : 'listTemplate', instance ? { formInstId: instance } : {});
+    if (!Array.isArray(raw) || raw.some(item => !m.object(item) || !/^(0|[1-9]\d*)$/.test(String(item.templateId)) || item.formUuid !== formUuid)
+      || new Set(raw.map(item => String(item.templateId))).size !== raw.length) { m.fail('INVALID_RESPONSE', 'template list'); }
+    return raw.map(item => ({ ...item, templateId: String(item.templateId), title: m.json(item.title, 'title') || {}, description: m.json(item.description, 'description') || {} }));
+  };
+  const snapshot = async id => {
+    const template = (await list()).find(item => item.templateId === id);
+    if (!template) { m.fail('NOT_FOUND', id); }
+    if (!['', 'DEFAULT', 'CUSTOM', null, undefined].includes(template.templateType)) { m.fail('UNSUPPORTED', `templateType: ${template.templateType}`); }
+    const body = id === '0' ? {} : await read('queryTemplateById', { templateId: id });
+    const result = { appType, formUuid, templateId: id, template, content: m.content(body) };
+    return { ...result, configHash: m.hash(result) };
+  };
+  const getFields = async () => {
+    const [dictionary, codeCapability] = await Promise.all([
+      read('listDictionarys', { ccMode: 'tile' }), codes.capabilities(client),
+    ]);
+    return builder.fields(dictionary, codeCapability);
+  };
+  const output = { action, ...target };
+  if (action === 'list') {
+    const templates = await list(flags['--instance']);
+    return { ...output, templates, ...(flags['--instance'] ? { instance: flags['--instance'], authorizationScoped: true }
+      : { orderHash: m.hash({ template: templates, content: null }) }) };
+  }
+  if (action === 'fields') {
+    const result = { ...output, fields: await getFields() };
+    if (flags['--out']) { result.outputPath = m.write(result, flags['--out'], 'fields'); }
+    return result;
+  }
+  if (action === 'build') {
+    const source = flags['--scene'] ? scenes.document(flags['--scene'], flags['--bindings'] ? m.read(flags['--bindings']) : {}) : m.read(flags['--config']);
+    const config = builder.compile(source, await getFields());
+    const result = { ...output, config, saved: false, ...(flags['--scene'] ? { scene: flags['--scene'], document: source.document } : {}) };
+    if (flags['--out']) { result.outputPath = m.write(config, flags['--out'], 'built'); }
+    return result;
+  }
+  if (action === 'files') {
+    const result = m.unwrap(await client.get(`/dingtalk/web/${appType}/query/attach/list.json`, {
+      formUuid, currentPage: flags['--page'] || '1', pageSize: flags['--size'] || '50', source: 'PRINT',
+    }), 'attach/list');
+    if (!m.object(result) || !Array.isArray(result.data) || !Number.isFinite(result.totalCount)) { m.fail('INVALID_RESPONSE', 'print file list'); }
+    return { ...output, files: result };
+  }
+  // Validate content before creating anything. A later save failure must retain the created ID.
+  const initialContent = action === 'create' && flags['--config'] ? builder.compile(m.read(flags['--config']), await getFields()) : null;
+  let before;
+  if (action === 'render') {
+    const available = await list(flags['--instance']);
+    const template = available.find(item => item.templateId === templateId && item.status !== 'STOP');
+    if (!template) { m.fail('NOT_FOUND', 'template unavailable for this record'); }
+    if (!['', 'DEFAULT', 'CUSTOM', null, undefined].includes(template.templateType)) { m.fail('UNSUPPORTED', `templateType: ${template.templateType}`); }
+    before = { ...target, instance: flags['--instance'], template, authorizationScoped: true };
+  } else {
+    before = action === 'create' || action === 'order' ? { appType, formUuid, templates: await list() } : await snapshot(templateId);
+  }
+  if (action === 'inspect') {
+    if (flags['--out']) { before = { ...before, outputPath: m.write(before, flags['--out'], 'export') }; }
+    return { ...output, ...before };
+  }
+  const expectedHash = action === 'order' ? m.hash({ template: before.templates, content: null }) : before.configHash;
+  if ((HASHED.includes(action) || action === 'order') && flags['--expected-hash'] !== expectedHash) { m.fail('STALE_CONFIG', 'inspect again'); }
+  if (['save', 'restore'].includes(action) && (templateId === '0' || before.template.templateType === 'DEFAULT')) { m.fail('UNSUPPORTED', 'built-in default body'); }
+  let endpoint;
+  let params;
+  let expected;
+  if (action === 'save' || action === 'restore') {
+    let input = preparedContent || m.read(flags['--config']);
+    if (action === 'restore') {
+      if (input.appType !== appType || input.formUuid !== formUuid || String(input.templateId) !== templateId || !m.object(input.content)) { m.fail('TARGET_MISMATCH', 'backup target'); }
+      input = Object.fromEntries(['termContents', 'termJsonAttr', 'dictionaryList'].map(key => [key, input.content[key]]));
+    }
+    expected = builder.compile(input, await getFields());
+    endpoint = 'saveTemplate';
+    params = { templateId, termContents: expected.termContents, termJsonAttr: JSON.stringify(expected.termJsonAttr), dictionaryList: JSON.stringify(expected.dictionaryList) };
+    const modified = before.content.gmtModified;
+    if (modified !== null && modified !== undefined) {
+      const stamp = typeof modified === 'number' || /^\d+$/.test(String(modified)) ? Number(modified) : Date.parse(modified);
+      if (!Number.isFinite(stamp)) { m.fail('INVALID_RESPONSE', 'gmtModified'); }
+      params.gmtModified = String(stamp);
+    }
+  } else if (action === 'settings') {
+    expected = settings(before.template, m.read(flags['--config']), flags['--allow-permission-change']);
+    if (templateId === '0' && Object.keys(expected).some(key => key !== 'roleData')) { m.fail('UNSUPPORTED', 'default template settings: roleData only'); }
+    endpoint = 'updatePrintBaseInfo';
+    params = { templateId, ...Object.fromEntries(Object.entries(expected).map(([key, value]) => [key, typeof value === 'string' ? value : JSON.stringify(value)])) };
+  } else if (action === 'status') {
+    expected = flags['--status']; endpoint = 'savePrintTemplateStatus'; params = { templateId, status: expected };
+  } else if (action === 'order') {
+    expected = m.read(flags['--config']);
+    if (!Array.isArray(expected)) { m.fail('INVALID_CONFIG', 'template ID array'); }
+    expected = expected.map(String);
+    if (expected.length !== before.templates.length || new Set(expected).size !== expected.length || expected.some(id => !before.templates.some(item => item.templateId === id))) { m.fail('INVALID_CONFIG', 'include every template exactly once'); }
+    endpoint = 'savePrintTemplateOrder'; params = { templateIdList: JSON.stringify(expected.map(Number)) };
+  } else if (action === 'create' || action === 'copy') {
+    endpoint = action === 'create' ? 'createTemplate' : 'copyTemplateIndependently';
+    expected = flags['--name'].trim();
+    params = { title: JSON.stringify(buildYidaTitleI18n(expected)), description: JSON.stringify(buildYidaTitleI18n('')),
+      ...(action === 'copy' ? { originTemplateId: templateId } : {}) };
+  } else if (action === 'render') {
+    endpoint = 'print'; params = { ...(templateId === '0' ? {} : { templateId }), formInstId: flags['--instance'],
+      templateType: templateId === '0' ? 'DEFAULT' : 'CUSTOM', ...(detailTarget?.activityId ? { activityId: detailTarget.activityId } : {}) };
+  }
+  const backupPath = m.write({ ...before, action }, flags['--backup']);
+  const details = { target, backupPath, retrySafe: false, sideEffectState: 'unknown', readbackAllowed: true };
+  let accepted;
+  try { accepted = await mutate(endpoint, params); }
+  catch (error) { throw new CliError(error.message, { code: error.code || 'PRINT_TEMPLATE_WRITE_FAILED', details: { ...error.details, ...details } }); }
+  try {
+    if (action === 'render') {
+      if (!/^[1-9]\d*$/.test(String(accepted))) { m.fail('INVALID_RESPONSE', 'print file ID'); }
+      return { ...output, instance: flags['--instance'], authorizationScoped: true, backupPath, fileId: String(accepted), generationRequested: true, fileReadyVerified: false };
+    }
+    if (action === 'order') {
+      const after = await list();
+      if (!isDeepStrictEqual(after.map(item => item.templateId), expected)) { m.fail('READBACK_MISMATCH', action); }
+      return { ...output, backupPath, templates: after, readbackVerified: true };
+    }
+    let id = templateId;
+    if (action === 'create' || action === 'copy') {
+      id = String(accepted);
+      if (!/^[1-9]\d*$/.test(id)) { m.fail('INVALID_RESPONSE', 'new template ID'); }
+      details.createdTemplateId = id;
+    }
+    let after = await snapshot(id);
+    if (action === 'copy' && before.content.dictionaryList.length && !after.content.dictionaryList.length
+      && before.content.termContents === after.content.termContents
+      && isDeepStrictEqual(m.stable(before.content.termJsonAttr), m.stable(after.content.termJsonAttr))) {
+      // Native copy can omit the dictionary. Complete this specific known partial
+      // result once, preserving the new target's concurrency token and backup.
+      const copyBackupPath = m.write(after);
+      details.copyBackupPath = copyBackupPath;
+      details.createdTemplateId = id;
+      const native = builder.validateNative(before.content, await getFields());
+      const stamp = after.content.gmtModified;
+      await mutate('saveTemplate', { templateId: id, termContents: native.termContents,
+        termJsonAttr: JSON.stringify(native.termJsonAttr), dictionaryList: JSON.stringify(native.dictionaryList),
+        ...(stamp !== null && stamp !== undefined ? { gmtModified: String(stamp) } : {}) });
+      after = await snapshot(id);
+    }
+    if (['save', 'restore'].includes(action) && !m.matches(expected, after.content)) { m.fail('READBACK_MISMATCH', action); }
+    if (action === 'status' && after.template.status !== expected) { m.fail('READBACK_MISMATCH', action); }
+    if (['create', 'copy'].includes(action) && m.label(after.template.title) !== expected) { m.fail('READBACK_MISMATCH', 'title'); }
+    if (action === 'create' && initialContent) {
+      try {
+        const saved = await execute({ action: 'save', appType, formUuid, templateId: id,
+          flags: { '--config': flags['--config'], '--expected-hash': after.configHash } }, client, initialContent);
+        return { ...saved, action, created: true, contentSaved: true, createBackupPath: backupPath };
+      } catch (error) {
+        details.contentSaveDetails = error.details;
+        throw error;
+      }
+    }
+    if (action === 'copy' && !isDeepStrictEqual(m.stable(Object.fromEntries(['termContents', 'termJsonAttr', 'dictionaryList'].map(key => [key, before.content[key]]))),
+      m.stable(Object.fromEntries(['termContents', 'termJsonAttr', 'dictionaryList'].map(key => [key, after.content[key]]))))) { m.fail('READBACK_MISMATCH', 'copied content'); }
+    if (action === 'settings') {
+      for (const [key, value] of Object.entries(expected)) {
+        const saved = after.template[key];
+        if (key === 'roleData') {
+          const members = after.template.roleMembers;
+          if (!Array.isArray(members) || value.some(role => {
+            const member = members.find(item => item.roleType === role.roleType);
+            return !member || member.roleValue.map(item => item.key).sort().join(',') !== role.roleValue.split(',').sort().join(',')
+              || role.isExclude !== undefined && String(role.isExclude) !== String(member.isExclude ?? '');
+          }) || members.some(member => !value.some(role => role.roleType === member.roleType) && member.roleValue?.some(item => item.key && item.key !== 'n'))) { m.fail('READBACK_MISMATCH', key); }
+          continue;
+        }
+        if (['title', 'description'].includes(key)) {
+          if (Object.keys(value).some(locale => locale !== 'pureEn_US' && String(value[locale] ?? '') !== String(saved?.[locale] ?? ''))) { m.fail('READBACK_MISMATCH', key); }
+        } else if (!isDeepStrictEqual(m.stable(value), m.stable(saved))) { m.fail('READBACK_MISMATCH', key); }
+      }
+    }
+    return { ...output, ...after, backupPath, ...(details.copyBackupPath ? { copyBackupPath: details.copyBackupPath } : {}), readbackVerified: true };
+  } catch (error) {
+    throw new CliError(error.message, { code: error.code || 'PRINT_TEMPLATE_READBACK_FAILED',
+      details: { ...error.details, ...details, mutationAccepted: true, acceptedResult: accepted, sideEffectState: 'accepted_unverified' } });
+  }
+}
+
+/** CLI entry: JSON receipts share the same execution path as programmatic calls. */
+async function run(args, options = {}) {
+  const parsed = parseArgs(args);
+  if (parsed.help) { process.stdout.write(t('print_template.usage') + '\n'); return; }
+  const result = await execute(parsed, options.client);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  return result;
+}
+
+module.exports = { run, execute, parseArgs, settings };

package/lib/print-template/scenes.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { object, fail, safe } = require('./model');
+const names = ['order', 'quotation', 'delivery', 'receipt', 'approval', 'codes'];
+
+/** Map scene roles to explicit live field references; compilation verifies IDs and table ownership. */
+function document(scene, bindings = {}) {
+  if (!names.includes(scene)) { fail('INVALID_CONFIG', `scene: ${names.join('|')}`); }
+  safe(bindings);
+  if (!object(bindings) || Object.values(bindings).some(value => typeof value !== 'string' || !value.trim())) {
+    fail('INVALID_CONFIG', 'bindings: field role -> actual field name/key');
+  }
+  const result = JSON.parse(JSON.stringify(require(`../samples/yida-print-template/${scene}.json`)));
+  const used = new Set();
+  const ref = name => { used.add(name); return bindings[name] ?? name; };
+  for (const block of result.document.blocks) {
+    if (block.field) { block.field = ref(block.field); }
+    if (block.fields) { block.fields = block.fields.map(field => typeof field === 'string' ? ref(field) : { ...field, field: ref(field.field) }); }
+    if (block.columns && Array.isArray(block.columns)) {
+      block.columns = block.columns.map(field => typeof field === 'string' ? ref(field) : { ...field, field: ref(field.field) });
+    }
+    if (block.html) { block.html = block.html.replace(/\{\{([^{}]+)\}\}/g, (_, field) => `{{${ref(field.trim())}}}`); }
+  }
+  const unused = Object.keys(bindings).filter(key => !used.has(key));
+  if (unused.length) { fail('INVALID_CONFIG', `unknown scene roles: ${unused.join(', ')}`); }
+  return result;
+}
+
+module.exports = { names, document };

package/lib/samples/yida-print-template/approval.json

@@ -0,0 +1,14 @@
+{
+  "document": {
+    "title": "申请审批单",
+    "style": "formal",
+    "blocks": [
+      { "type": "fields", "columns": 2, "fields": ["申请编号", "申请人", "申请日期", "申请金额"] },
+      { "type": "heading", "text": "申请事由" },
+      { "type": "field", "field": "申请说明" },
+      { "type": "heading", "text": "审批记录" },
+      { "type": "table", "field": "审批历史" },
+      { "type": "text", "text": "归档经办人：________________" }
+    ]
+  }
+}

package/lib/samples/yida-print-template/codes.json

@@ -0,0 +1,12 @@
+{
+  "document": {
+    "title": "订单扫码核验单",
+    "blocks": [
+      { "type": "fields", "fields": ["订单编号"] },
+      { "type": "heading", "text": "订单二维码" },
+      { "type": "qrcode", "field": "订单编号", "width": 128, "height": 128 },
+      { "type": "heading", "text": "订单条形码" },
+      { "type": "barcode", "field": "订单编号", "width": 320, "height": 100 }
+    ]
+  }
+}

package/lib/samples/yida-print-template/delivery.json

@@ -0,0 +1,14 @@
+{
+  "document": {
+    "title": "发货交接单",
+    "style": "document",
+    "blocks": [
+      { "type": "fields", "columns": 2, "fields": ["发货编号", "收货单位", "发货日期", "经办人"] },
+      { "type": "heading", "text": "交接明细" },
+      { "type": "table", "field": "发货明细", "columns": ["商品名称", "发货数量"] },
+      { "type": "fields", "fields": ["交接备注"] },
+      { "type": "text", "text": "发货人：________________　收货人：________________" },
+      { "type": "text", "text": "验收结果：________________　签收日期：________________" }
+    ]
+  }
+}

package/lib/samples/yida-print-template/order.json

@@ -0,0 +1,14 @@
+{
+  "document": {
+    "title": "销售订单",
+    "style": "document",
+    "font": "宋体",
+    "blocks": [
+      { "type": "fields", "columns": 2, "fields": ["订单编号", "客户名称", "订单日期", "经办人"] },
+      { "type": "heading", "text": "商品明细" },
+      { "type": "table", "field": "订单明细", "columns": ["商品名称", "数量", "单价", "金额"] },
+      { "type": "fields", "fields": ["合计金额", "备注"] },
+      { "type": "text", "text": "客户签字：________________　经办人签字：________________" }
+    ]
+  }
+}

package/lib/samples/yida-print-template/quotation.json

@@ -0,0 +1,13 @@
+{
+  "document": {
+    "title": "销售报价单",
+    "style": "formal",
+    "blocks": [
+      { "type": "fields", "columns": 2, "fields": ["报价编号", "客户名称", "报价日期", "经办人"] },
+      { "type": "heading", "text": "报价明细" },
+      { "type": "table", "field": "报价明细", "columns": ["商品名称", "数量", "单价", "金额"] },
+      { "type": "fields", "fields": ["报价总额", "报价说明"] },
+      { "type": "text", "text": "报价确认签字：________________　日期：________________" }
+    ]
+  }
+}