openxiangda 1.0.147 → 1.0.148

package/README.md

@@ -216,6 +216,16 @@ openxiangda workspace bind --profile dev --app-type APP_XXXX
 
 表单页、流程表单页和自定义代码页都应在 `sy-lowcode-app-workspace` 中实现，由 `openxiangda workspace publish --profile <name>` 统一构建、上传 OSS 并注册到平台。`openxiangda form create`、`form publish`、`page publish` 只作为底层修复/诊断命令，不作为 AI 生成页面的主入口。
 
+表单数据导出使用 `openxiangda form export`，不要手写下载接口 URL：
+
+```bash
+openxiangda form export customer --mode xlsx --profile dev
+openxiangda form export customer --mode xlsx-images --profile dev --all
+openxiangda form export customer --mode package --profile dev --output ./exports/
+```
+
+`xlsx` 是普通 Excel；`xlsx-images` 会尽量把 `ImageField` 图片嵌入单元格；`package` 会下载 zip，包含 `data.xlsx`、`attachments/` 和 `manifest.json`。`--output` 指向目录时使用服务端文件名，指向文件路径时按该路径写入；`--json` 只输出 `{ file, filename, mime, bytes, mode, formUuid }` 摘要，不把二进制写到 stdout。
+
 运行时页面读取当前用户信息时，优先使用 `sdk.user.getCurrent<PageUserRecord>()`。用户对象会返回常规组织成员关系 `departments`，也会返回系统维护的所属单位字段 `affiliatedDepartmentId` / `affiliatedDepartment`。`departments` 表示用户真实所在的部门、班级、专业等成员关系；`affiliatedDepartment` 表示业务上用于统计、筛选和展示的归属单位，通常是学院、单位或在源单位缺失时可用的具体部门节点，不用于替代权限部门成员关系。
 
 ```ts

package/lib/cli.js

@@ -141,6 +141,7 @@ Usage:
   openxiangda form create <formCode> [--name text] [--type receipt]  # low-level shell only
   openxiangda form bind <formCode> --form-uuid <FORM_XXX>
   openxiangda form pull <formCode|formUuid> [--json]
+  openxiangda form export <formCode|formUuid> --mode xlsx|xlsx-images|package [--output <file-or-dir>]
   openxiangda form publish <formCode|formUuid> --bundle-url <url>     # repair only
   openxiangda form schema-plan <formCode|formUuid> --schema-json <file>|--components-json <file>
   openxiangda page list [--profile name] [--json]
@@ -2077,7 +2078,7 @@ async function form(args) {
   const [subcommand, ...rest] = args;
   const { flags, positional } = parseArgs(rest);
   if (wantsSubcommandHelp(subcommand, flags)) {
-    print('用法: openxiangda form list|create|bind|pull|publish|schema-plan [--profile name] [--json]');
+    print('用法: openxiangda form list|create|bind|pull|export|publish|schema-plan [--profile name] [--json]');
     return;
   }
   const config = loadConfig();
@@ -2155,6 +2156,46 @@ async function form(args) {
     return;
   }
 
+  if (subcommand === 'export') {
+    const [formKey] = positional;
+    if (!formKey) {
+      fail('用法: openxiangda form export <formCode|formUuid> --mode xlsx|xlsx-images|package');
+    }
+    const target = getWorkspaceTarget(config, profileName, flags);
+    const formUuid = resolveFormUuid(target.bound, formKey, flags);
+    const mode = normalizeFormExportMode(flags.mode);
+    const extension = mode === 'package' ? 'zip' : 'xlsx';
+    const endpoint =
+      mode === 'package' ? 'advancedExportPackage.zip' : 'advancedExport.xlsx';
+    const apiPath = apiPathWithQuery(
+      `/${encodeURIComponent(target.appType)}/v1/form/${endpoint}`,
+      buildFormExportQuery(formUuid, mode, flags)
+    );
+    const download = await downloadWithAuth(config, target.profileName, apiPath, {
+      timeoutMs: flags['timeout-ms'] || flags.timeout || 120000,
+    });
+    const fallbackFilename = `export_${formUuid}_${new Date()
+      .toISOString()
+      .replace(/[-:T.Z]/g, '')
+      .slice(0, 14)}.${extension}`;
+    const output = writeDownloadedFile(
+      download,
+      flags.output || '.',
+      fallbackFilename
+    );
+    const result = {
+      file: output.file,
+      filename: output.filename,
+      mime: download.mime,
+      bytes: download.bytes,
+      mode,
+      formUuid,
+    };
+    if (flags.json) return writeJson(result);
+    print(`已导出 ${mode}: ${output.file} (${download.bytes} bytes)`);
+    return;
+  }
+
   if (subcommand === 'publish') {
     const [formKey] = positional;
     if (!formKey || !flags['bundle-url']) {
@@ -2205,7 +2246,7 @@ async function form(args) {
     return;
   }
 
-  fail('用法: openxiangda form list|create|bind|pull|publish|schema-plan');
+  fail('用法: openxiangda form list|create|bind|pull|export|publish|schema-plan');
 }
 
 async function page(args) {
@@ -5379,7 +5420,7 @@ async function commands(args) {
       'env',
       'workspace init|bind|plan|check|publish [--app-name] [--changed|--since|--form|--page|--only|--dry-run|--force|--resources|--skip-resources|--prune]',
       'app list|create|snapshot',
-      'form list|create|bind|pull|publish|schema-plan',
+      'form list|create|bind|pull|export|publish|schema-plan',
       'page list|publish|bind|releases|activate',
       'menu list|create|update|sort|bind|delete',
       'workflow compile|list|create|bind|pull|publish|delete|validate',
@@ -6079,6 +6120,61 @@ function resolveFormUuid(bound, formKey, flags = {}) {
   return mapped || formKey;
 }
 
+function normalizeFormExportMode(value) {
+  const mode = String(value || 'xlsx').trim();
+  if (['xlsx', 'xlsx-images', 'package'].includes(mode)) return mode;
+  fail('--mode 只能是 xlsx、xlsx-images 或 package');
+}
+
+function buildFormExportQuery(formUuid, mode, flags = {}) {
+  const query = {
+    formUuid,
+    exportAll: flags.all ? 'y' : 'n',
+    embedImages: mode === 'xlsx-images' || mode === 'package' ? 'y' : 'n',
+    currentPage: flags.page,
+    pageSize: flags['page-size'],
+    conditionType: flags['condition-type'],
+    searchKeyWord: flags['search-keyword'],
+    instanceStatus: flags['instance-status'],
+    exportFields: flags.fields,
+  };
+  if (flags['filters-json']) {
+    query.filters = JSON.stringify(readJsonArg(flags['filters-json'], 'filters-json'));
+  }
+  if (flags['order-json']) {
+    query.order = JSON.stringify(readJsonArg(flags['order-json'], 'order-json'));
+  }
+  return query;
+}
+
+function writeDownloadedFile(download, outputFlag, fallbackFilename) {
+  const filename = sanitizeDownloadFilename(download.filename || fallbackFilename);
+  const target = String(outputFlag || '.');
+  const absoluteTarget = path.resolve(process.cwd(), target);
+  const targetIsDirectory =
+    target.endsWith('/') ||
+    target.endsWith(path.sep) ||
+    target === '.' ||
+    (fs.existsSync(absoluteTarget) && fs.statSync(absoluteTarget).isDirectory()) ||
+    (!fs.existsSync(absoluteTarget) && !path.extname(absoluteTarget));
+  const file = targetIsDirectory
+    ? path.join(absoluteTarget, filename)
+    : absoluteTarget;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, download.buffer);
+  return {
+    file,
+    filename: path.basename(file),
+  };
+}
+
+function sanitizeDownloadFilename(value) {
+  return String(value || 'download.bin')
+    .replace(/[\\/]+/g, '_')
+    .replace(/[\0\r\n]+/g, '')
+    .trim() || 'download.bin';
+}
+
 function readFormSchemaPlanBody(flags = {}) {
   if (flags['schema-json']) {
     return { schema: readJsonArg(flags['schema-json'], 'schema-json') };
@@ -12994,6 +13090,98 @@ async function retryTransientFetch(fn, options = {}) {
   throw lastError;
 }
 
+async function downloadWithAuth(config, profileName, apiPath, options = {}) {
+  const resolved = getProfile(config, profileName);
+  const profile = resolved.profile;
+  if (!profile.token?.accessToken) {
+    fail(`profile ${resolved.profileName} 未登录，请先执行 openxiangda login --profile ${resolved.profileName}`);
+  }
+  const requestOptions = {
+    method: 'GET',
+    timeoutMs: options.timeoutMs,
+    retries: options.retries,
+  };
+  const send = () =>
+    downloadBinary(profile.baseUrl, apiPath, profile.token.accessToken, requestOptions);
+  try {
+    return await retryTransientFetch(send, requestOptions);
+  } catch (error) {
+    if (!isUnauthorized(error) || !profile.token?.refreshToken) {
+      throw error;
+    }
+    await refreshProfile(config, resolved.profileName);
+    return await retryTransientFetch(send, requestOptions);
+  }
+}
+
+async function downloadBinary(baseUrl, apiPath, accessToken, options = {}) {
+  if (typeof fetch !== 'function') {
+    throw new Error('当前 Node.js 版本不支持 fetch，请使用 Node.js 18 或更高版本');
+  }
+  const url = `${baseUrl.replace(/\/+$/, '')}${apiPath}`;
+  const timeoutMs = normalizeRuntimeUploadTimeoutMs(options.timeoutMs);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetch(url, {
+      method: options.method || 'GET',
+      headers: {
+        accept: '*/*',
+        authorization: `Bearer ${accessToken}`,
+      },
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (isAbortError(error)) {
+      throw new Error(maskText(`HTTP download timed out after ${timeoutMs}ms: ${apiPath}`));
+    }
+    throw new Error(formatFetchError(error, apiPath));
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => '');
+    let payload = null;
+    try {
+      payload = text ? JSON.parse(text) : null;
+    } catch {
+      payload = { message: text };
+    }
+    const message = payload?.message || response.statusText || 'download failed';
+    const error = new Error(maskText(`HTTP ${response.status}: ${message}`));
+    error.status = response.status;
+    error.payload = payload;
+    throw error;
+  }
+
+  const arrayBuffer = await response.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  const disposition = response.headers.get('content-disposition') || '';
+  return {
+    buffer,
+    filename: parseContentDispositionFilename(disposition),
+    mime: response.headers.get('content-type') || 'application/octet-stream',
+    bytes: buffer.length,
+  };
+}
+
+function parseContentDispositionFilename(header) {
+  const value = String(header || '');
+  const encodedMatch = value.match(/filename\*=([^;]+)/i);
+  if (encodedMatch) {
+    const encoded = encodedMatch[1].trim().replace(/^UTF-8''/i, '');
+    try {
+      return sanitizeDownloadFilename(decodeURIComponent(encoded.replace(/^"|"$/g, '')));
+    } catch {
+      return sanitizeDownloadFilename(encoded);
+    }
+  }
+  const plainMatch = value.match(/filename="?([^";]+)"?/i);
+  return plainMatch ? sanitizeDownloadFilename(plainMatch[1]) : '';
+}
+
 async function requestWithAuth(config, profileName, apiPath, options = {}) {
   const resolved = getProfile(config, profileName);
   const profile = resolved.profile;

package/openxiangda-skills/SKILL.md

@@ -24,6 +24,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 | 创建应用 / 新建 app / scaffold / 初始化工作区            | `openxiangda-app`                                                                          | `openxiangda workspace init <dir> --profile <name> --app-name "..."`                                                                                     |
 | 绑定已有应用 / bind existing app                         | `openxiangda-app`                                                                          | `openxiangda workspace bind --profile <name> --app-type APP_XXX`                                                                                         |
 | 创建 / 修改表单字段 / 表单页 / schema                    | `openxiangda-form`                                                                         | edit `src/forms/<code>/{schema.ts,page.tsx}` → `workspace publish --form <code>`                                                                         |
+| 导出表单数据 / 图片 / 附件 / Excel / zip                 | `openxiangda-form`                                                                         | `openxiangda form export <formCode> --mode xlsx|xlsx-images|package --profile <name>`                                                                    |
 | 创建 / 修改自定义代码页 / portal / dashboard             | `openxiangda-page`                                                                         | edit `src/pages/<code>/` → `workspace publish --page <code>`                                                                                             |
 | 审批流程 / workflow / 流程节点 / JS_CODE                 | `openxiangda-workflow-automation`                                                          | `openxiangda workflow validate / create / publish`                                                                                                       |
 | 自动化 / 定时任务 / 提交触发 / cron                      | `openxiangda-workflow-automation`                                                          | `openxiangda automation validate / create / publish / enable`                                                                                            |
@@ -57,6 +58,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 - ✅ For form-entry UX, pick components in this order: OpenXiangda platform form components → `antd` / `antd-mobile` wrappers → custom component only when neither exists.
 - ✅ In React SPA apps, keep imports on public package entrypoints such as `openxiangda`, `openxiangda/runtime`, and `openxiangda/runtime/react`. The default template already groups large vendor chunks; if a bundle is too large, use route-level lazy loading and Vite `manualChunks`, not `openxiangda/packages/sdk/dist/...` internal paths.
 - ✅ For image thumbnails or lightweight previews, use `imageCompression` on `ImageField` or `AttachmentField`. Keep the original `url` for the source file and use `thumbUrl` / `previewUrl` / `variants` for smaller images.
+- ✅ For data delivery with files, use `openxiangda form export <formCode> --mode xlsx|xlsx-images|package --profile <name>`. `package` writes a zip with `data.xlsx`, `attachments/`, and `manifest.json`; do not hand-write export URLs or stream binary content to stdout.
 - ✅ List pages, linked options, remote selectors, and report drill-downs must use paginated server-side queries with explicit searchable fields. Do not fetch a large page and filter in local state.
 - ✅ Treat workflow forms as an exception. Ordinary ticket/order/task/asset lifecycles use status fields, state machines, action logs, permissions, and automations; workflows are for real approval tasks.
 - ✅ Proactively submit platform feedback when you discover a defect, missing capability, unclear rule, repeated workaround, user-visible UX gap, or implementation uncertainty worth improving.

package/openxiangda-skills/skills/openxiangda-core/SKILL.md

@@ -188,6 +188,9 @@ Read-only diagnosis can use resource commands:
 ```bash
 openxiangda form list --profile dev
 openxiangda form pull customer --profile dev
+openxiangda form export customer --mode xlsx --profile dev
+openxiangda form export customer --mode xlsx-images --profile dev --all
+openxiangda form export customer --mode package --profile dev --output ./exports/
 openxiangda page list --profile dev
 openxiangda workflow list --form-code customer --profile dev
 openxiangda automation list --form-code customer --profile dev

package/openxiangda-skills/skills/openxiangda-form/SKILL.md

@@ -106,6 +106,30 @@ openxiangda form publish customer --bundle-url <url> --profile <name>
 
 Do not use `openxiangda form create` as the normal way to generate a user-facing page. It creates the old platform form shell and will show the legacy default schema until a workspace bundle is published.
 
+## Data Export
+
+Use `openxiangda form export` for read-only data delivery. It reuses the active profile token and the workspace app binding, so do not hand-write export URLs or ask for AK/SK.
+
+```bash
+openxiangda form export customer --mode xlsx --profile dev
+openxiangda form export customer --mode xlsx-images --profile dev --all
+openxiangda form export customer --mode package --profile dev --output ./exports/
+```
+
+Modes:
+
+- `xlsx`: normal Excel export. Images and attachments stay as links/text.
+- `xlsx-images`: Excel export with `ImageField` images embedded when the server can read a supported `png` / `jpg` / `gif`; failures degrade to links.
+- `package`: zip export containing `data.xlsx`, `attachments/`, and `manifest.json`; attachment/image cells use package-relative paths and the `Attachments` sheet lists one file per row.
+
+Useful filters:
+
+```bash
+openxiangda form export customer --mode package --profile dev --all --fields formInstId,instance_title,field_xxx
+openxiangda form export customer --mode xlsx --profile dev --filters-json ./filters.json --order-json ./order.json
+openxiangda form export customer --mode xlsx --profile dev --page 1 --page-size 100 --condition-type and --search-keyword 张三 --instance-status completed
+```
+
 ## Workspace Form Rules
 
 Read these references only when writing or reviewing schema:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.147",
+  "version": "1.0.148",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -62,6 +62,7 @@
   "scripts": {
     "build:sdk": "tsup --config packages/sdk/tsup.config.ts",
     "check": "node --check bin/openxiangda.js && node --check lib/*.js && node --check packages/sdk/src/build-source/src/cli.mjs && node --check packages/sdk/src/build-source/scripts/*.mjs && node --check packages/sdk/src/build-source/scripts/utils/*.mjs",
+    "test": "npm run check && node scripts/form-export-cli-smoke.mjs",
     "prepack": "npm run build:sdk",
     "test:profile-isolation": "bash scripts/profile-isolation-smoke.sh",
     "test:resource-plan": "node scripts/resource-plan-smoke.mjs",

package/templates/openxiangda-react-spa/AGENTS.md

@@ -31,6 +31,7 @@ pnpm build
 pnpm build-js-code
 pnpm deploy -- --profile <name>
 openxiangda workspace publish --profile <name> --form <formCode>
+openxiangda form export <formCode> --mode package --profile <name> --output ./exports/
 openxiangda doctor --profile <name> --json
 openxiangda design gates --topic public-access --json
 openxiangda sdd context --json

package/templates/sy-lowcode-app-workspace/AGENTS.md

@@ -22,6 +22,7 @@
 | 创建应用 / 新建 app / 初始化工作区 | `openxiangda-app` | `openxiangda workspace init <dir> --profile <name> --app-name "..."` |
 | 绑定已有应用 | `openxiangda-app` | `openxiangda workspace bind --profile <name> --app-type APP_XXX` |
 | 创建 / 改表单字段、schema、表单页 | `openxiangda-form` | 编辑 `src/forms/<code>/{schema.ts,page.tsx}` → `workspace publish --form <code>` |
+| 导出表单数据 / 图片 / 附件 / Excel / zip | `openxiangda-form` | `openxiangda form export <formCode> --mode xlsx|xlsx-images|package --profile <name>` |
 | 创建 / 改自定义代码页、portal、看板 | `openxiangda-page` | 编辑 `src/pages/<code>/` → `workspace publish --page <code>` |
 | 审批流程 / 流程节点 / JS_CODE | `openxiangda-workflow-automation` | `openxiangda workflow validate / create / publish` |
 | 自动化 / 定时任务 / 提交触发 / cron | `openxiangda-workflow-automation` | `openxiangda automation validate / create / publish / enable` |