openxiangda 1.0.118 → 1.0.119

package/lib/cli.js

@@ -1458,6 +1458,7 @@ async function workspace(args) {
         roles: {},
         connectors: {},
         dataViews: {},
+        storageConfigs: {},
         pagePermissionGroups: {},
         formPermissionGroups: {},
         formSettings: {},
@@ -4909,6 +4910,7 @@ function ensureResourceBuckets(bound) {
   bound.resources.roles = bound.resources.roles || {};
   bound.resources.connectors = bound.resources.connectors || {};
   bound.resources.dataViews = bound.resources.dataViews || {};
+  bound.resources.storageConfigs = bound.resources.storageConfigs || {};
   bound.resources.authConfigs = bound.resources.authConfigs || {};
   bound.resources.routes = bound.resources.routes || {};
   bound.resources.publicAccessPolicies = bound.resources.publicAccessPolicies || {};
@@ -5122,6 +5124,14 @@ function saveDataViewResource(target, dataViewCode, dataViewId, extra = {}) {
   }, keys);
 }
 
+function saveStorageConfigResource(target, storageCode, storageConfigId, extra = {}) {
+  const keys = ['storageConfigId', 'provider', 'status'];
+  saveStateResource(target, 'storageConfigs', storageCode, {
+    ...pickStateFields(extra, keys),
+    storageConfigId,
+  }, keys);
+}
+
 function saveRouteResource(target, routeCode, routeId, extra = {}) {
   const keys = ['routeId', 'pathPattern', 'publicAccess', 'publicPolicyCode'];
   saveStateResource(target, 'routes', routeCode, {
@@ -5253,6 +5263,7 @@ const RESOURCE_SPECS = [
   { key: 'automations', dir: 'automations', topFiles: ['automations.json'], pluralKeys: ['automations'] },
   { key: 'functions', dir: 'functions', topFiles: ['functions.json'], pluralKeys: ['functions'] },
   { key: 'dataViews', dir: 'data-views', topFiles: ['data-views.json'], pluralKeys: ['dataViews', 'data-views'] },
+  { key: 'storageConfigs', dir: 'storage', topFiles: ['storage.json'], pluralKeys: ['storageConfigs', 'storage'] },
   { key: 'authConfigs', dir: 'auth', topFiles: ['auth.json'], pluralKeys: ['authConfigs', 'auth'] },
   { key: 'routes', dir: 'routes', topFiles: ['routes.json'], pluralKeys: ['routes'] },
   {
@@ -5305,6 +5316,15 @@ const RESOURCE_TYPE_ALIASES = new Map([
   ['dataview', 'dataViews'],
   ['dataviews', 'dataViews'],
   ['data-view-resource', 'dataViews'],
+  ['storage', 'storageConfigs'],
+  ['storages', 'storageConfigs'],
+  ['storage-config', 'storageConfigs'],
+  ['storage-configs', 'storageConfigs'],
+  ['storageconfig', 'storageConfigs'],
+  ['storageconfigs', 'storageConfigs'],
+  ['oss', 'storageConfigs'],
+  ['oss-config', 'storageConfigs'],
+  ['oss-configs', 'storageConfigs'],
   ['auth', 'authConfigs'],
   ['auth-config', 'authConfigs'],
   ['auth-configs', 'authConfigs'],
@@ -5369,7 +5389,7 @@ function getResourceTypeFilters(positional = [], flags = {}) {
     if (!key) {
       fail(
         `未知资源类型: ${rawType}。常用类型包括 workflow, notification, route, menu, role, ` +
-          `page-permission-group, form-permission-group, public-access。`
+          `storage, page-permission-group, form-permission-group, public-access。`
       );
     }
     filters.add(key);
@@ -5636,6 +5656,7 @@ function generateResourceTypes(manifest, outputFile) {
   );
   const dataViewCodes = unique((manifest.dataViews || []).map(item => item.code).filter(Boolean));
   const functionCodes = unique((manifest.functions || []).map(item => item.code).filter(Boolean));
+  const storageConfigCodes = unique((manifest.storageConfigs || []).map(item => item.code).filter(Boolean));
   const authConfigCodes = unique((manifest.authConfigs || []).map(item => item.code).filter(Boolean));
   const publicAccessPolicyCodes = unique((manifest.publicAccessPolicies || []).map(item => item.code).filter(Boolean));
   const content = [
@@ -5654,6 +5675,9 @@ function generateResourceTypes(manifest, outputFile) {
     `export const dataViewCodes = ${JSON.stringify(dataViewCodes, null, 2)} as const`,
     'export type DataViewCode = typeof dataViewCodes[number]',
     '',
+    `export const storageConfigCodes = ${JSON.stringify(storageConfigCodes, null, 2)} as const`,
+    'export type StorageConfigCode = typeof storageConfigCodes[number]',
+    '',
     `export const functionCodes = ${JSON.stringify(functionCodes, null, 2)} as const`,
     'export type FunctionCode = typeof functionCodes[number]',
     '',
@@ -5678,6 +5702,7 @@ function generateResourceTypes(manifest, outputFile) {
     routeCodes: routeCodes.length,
     pagePermissionGroups: pagePermissionGroupCodes.length,
     dataViews: dataViewCodes.length,
+    storageConfigs: storageConfigCodes.length,
     functions: functionCodes.length,
     authConfigs: authConfigCodes.length,
     publicAccessPolicies: publicAccessPolicyCodes.length,
@@ -5759,6 +5784,27 @@ function validateResourceItem(kind, item, errors, warnings) {
     }
     validateDataViewPerformance(label, definition, errors, warnings, storageMode);
   }
+  if (kind === 'storageConfigs') {
+    const config = item.configJson || item.config || item;
+    const provider = String(item.provider || config.provider || 'oss').toLowerCase();
+    if (provider !== 'oss') errors.push(`${label}: 当前仅支持 provider=oss`);
+    if (!item.name && !config.name) warnings.push(`${label}: 未声明 name，将使用 code`);
+    if (!config.region) errors.push(`${label}: 缺少 OSS region`);
+    if (!config.bucket) errors.push(`${label}: 缺少 OSS bucket`);
+    const status = item.status === undefined ? 'active' : String(item.status);
+    if (!['active', 'disabled'].includes(status)) {
+      errors.push(`${label}: status 只能是 active 或 disabled`);
+    }
+    const credentials = item.credentials || item.secret || item.secretJson || {};
+    for (const key of ['accessKeyId', 'accessKeySecret']) {
+      if (credentials[key] !== undefined && !isEnvReference(credentials[key])) {
+        errors.push(`${label}.credentials.${key}: OSS 凭据必须使用环境变量引用`);
+      }
+    }
+    if (!credentials.accessKeyId || !credentials.accessKeySecret) {
+      warnings.push(`${label}: 未声明凭据；publish 只适用于更新并保留平台已有密文`);
+    }
+  }
   if (kind === 'authConfigs') {
     const config = item.configJson || item.config || item;
     if (!Array.isArray(config.methods)) {
@@ -6214,6 +6260,7 @@ async function buildResourcePlan(config, target, manifest) {
   addPlanActions(actions, 'publicAccessPolicy', manifest.publicAccessPolicies, existing.publicAccessPolicies, (item, current) => publicAccessPolicyEquals(target.bound, item, current));
   await addAutomationPlanActions(config, target, actions, manifest.automations, existing.automations);
   addPlanActions(actions, 'dataView', manifest.dataViews, existing.dataViews, (item, current) => dataViewEquals(target.bound, item, current));
+  addPlanActions(actions, 'storageConfig', manifest.storageConfigs, existing.storageConfigs, (item, current) => storageConfigEquals(item, current));
   addPlanActions(actions, 'pagePermissionGroup', manifest.pagePermissionGroups, existing.pagePermissionGroups, (item, current) => pagePermissionGroupEquals(target.bound, item, current));
   addPlanActions(actions, 'formPermissionGroup', manifest.formPermissionGroups, existing.formPermissionGroups, (item, current) => formPermissionGroupEquals(target.bound, item, current));
   for (const item of manifest.formSettings || []) {
@@ -6287,6 +6334,7 @@ async function publishResourceManifest(config, target, manifest, options = {}) {
   await publishRouteResources(config, target, manifest.routes || [], result, publishOptions);
   await publishAutomationResources(config, target, manifest.automations || [], result, publishOptions);
   await publishDataViewResources(config, target, manifest.dataViews || [], result, publishOptions);
+  await publishStorageConfigResources(config, target, manifest.storageConfigs || [], result, publishOptions);
   await publishPublicAccessPolicyResources(config, target, manifest.publicAccessPolicies || [], result, publishOptions);
   await publishPagePermissionGroupResources(config, target, manifest.pagePermissionGroups || [], result, publishOptions);
   await publishFormPermissionGroupResources(config, target, manifest.formPermissionGroups || [], result, publishOptions);
@@ -6314,6 +6362,7 @@ async function fetchExistingResourceMaps(config, target, manifest) {
     publicAccessPolicies: new Map(),
     automations: new Map(),
     dataViews: new Map(),
+    storageConfigs: new Map(),
     pagePermissionGroups: new Map(),
     formPermissionGroups: new Map(),
   };
@@ -6495,6 +6544,31 @@ async function fetchExistingResourceMaps(config, target, manifest) {
       });
     }
   }
+  if ((manifest.storageConfigs || []).length > 0) {
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs`, {
+        page: 1,
+        pageSize: 1000,
+      })
+    );
+    indexByCode(maps.storageConfigs, normalizeItems(data), item => item.code || item.resourceCode);
+    for (const item of manifest.storageConfigs || []) {
+      const code = item.code || item.resourceCode;
+      const existing = maps.storageConfigs.get(code);
+      if (!existing) continue;
+      const detail = await requestOptionalWithAuth(
+        config,
+        target.profileName,
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs/${encodeURIComponent(code)}`
+      );
+      maps.storageConfigs.set(code, {
+        ...existing,
+        ...(detail || {}),
+      });
+    }
+  }
   if ((manifest.pagePermissionGroups || []).length > 0) {
     const data = await requestWithAuth(
       config,
@@ -7246,6 +7320,43 @@ async function publishDataViewResources(config, target, dataViews, result, optio
   }
 }
 
+async function publishStorageConfigResources(config, target, storageConfigs, result, options = {}) {
+  for (const storageItem of storageConfigs) {
+    const code = storageItem.code || storageItem.resourceCode;
+    if (shouldSkipNoopResource(options, 'storageConfig', code)) {
+      recordNoopResource(result, 'storageConfig', code, options);
+      continue;
+    }
+    const existing = await findExistingStorageConfig(config, target, code);
+    const body = normalizeStorageConfigManifest(storageItem);
+    const data = existing
+      ? await requestWithAuth(
+          config,
+          target.profileName,
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs/${encodeURIComponent(code)}`,
+          { method: 'PUT', body }
+        )
+      : await requestWithAuth(
+          config,
+          target.profileName,
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs`,
+          { method: 'POST', body }
+        );
+    if (data?.id) {
+      saveStorageConfigResource(target, data.code || code, data.id, {
+        provider: data.provider || body.provider,
+        status: data.status || body.status,
+      });
+    }
+    result.published.push({
+      kind: 'storageConfig',
+      code,
+      action: existing ? 'update' : 'create',
+      id: data?.id,
+    });
+  }
+}
+
 async function publishDataViewPermissionGroups(config, target, dataViewCode, permissionGroups) {
   await requestWithAuth(
     config,
@@ -7398,6 +7509,18 @@ async function findExistingDataView(config, target, code) {
   return null;
 }
 
+async function findExistingStorageConfig(config, target, code) {
+  const stateId = target.bound.resources?.storageConfigs?.[code]?.storageConfigId;
+  const byCode = await requestOptionalWithAuth(
+    config,
+    target.profileName,
+    `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs/${encodeURIComponent(code)}`
+  );
+  if (byCode?.id) return byCode;
+  if (stateId) return { id: stateId, code };
+  return null;
+}
+
 async function findExistingAutomation(config, target, code) {
   const stateId = target.bound.resources?.automations?.[code]?.automationId;
   if (stateId) {
@@ -7545,6 +7668,7 @@ async function pruneResourceManifest(config, target, manifest, result) {
   await pruneAuthConfigs(config, target, desiredCodes(manifest.authConfigs), result);
   await pruneRoutes(config, target, desiredCodes(manifest.routes), result);
   await pruneDataViews(config, target, desiredCodes(manifest.dataViews), result);
+  await pruneStorageConfigs(config, target, desiredCodes(manifest.storageConfigs), result);
   await prunePublicAccessPolicies(
     config,
     target,
@@ -7722,6 +7846,29 @@ async function pruneDataViews(config, target, desired, result) {
   }
 }
 
+async function pruneStorageConfigs(config, target, desired, result) {
+  const data = await requestWithAuth(
+    config,
+    target.profileName,
+    apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs`, {
+      page: 1,
+      pageSize: 1000,
+    })
+  );
+  for (const item of normalizeItems(data)) {
+    const code = item.code || item.resourceCode;
+    if (!code || desired.has(code)) continue;
+    await pruneOne(config, target, result, 'storageConfig', code, item.id, async () => {
+      await requestWithAuth(
+        config,
+        target.profileName,
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs/${encodeURIComponent(code)}`,
+        { method: 'DELETE' }
+      );
+    });
+  }
+}
+
 async function pruneFunctions(config, target, desired, result) {
   const data = await requestWithAuth(
     config,
@@ -7893,6 +8040,7 @@ function removeStateResource(target, kind, code) {
     route: 'routes',
     publicAccessPolicy: 'publicAccessPolicies',
     dataView: 'dataViews',
+    storageConfig: 'storageConfigs',
     pagePermissionGroup: 'pagePermissionGroups',
     formPermissionGroup: 'formPermissionGroups',
   };
@@ -8165,6 +8313,26 @@ async function pullResources(config, target) {
     written.push(path.relative(process.cwd(), filePath));
   }
 
+  const storageConfigs = await requestWithAuth(
+    config,
+    target.profileName,
+    apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs`, {
+      page: 1,
+      pageSize: 1000,
+    })
+  );
+  for (const storageConfig of normalizeItems(storageConfigs)) {
+    const code = storageConfig.code || storageConfig.resourceCode || storageConfig.id;
+    const detail = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/storage-configs/${encodeURIComponent(code)}`
+    );
+    const filePath = path.join(baseDir, 'storage', `${code}.json`);
+    writeResourceJsonFile(filePath, toPulledStorageConfig(detail));
+    written.push(path.relative(process.cwd(), filePath));
+  }
+
   const pageGroups = await requestWithAuth(
     config,
     target.profileName,
@@ -8407,6 +8575,18 @@ function toPulledAuthConfig(authConfig) {
   });
 }
 
+function toPulledStorageConfig(storageConfig) {
+  return stripUndefinedValues({
+    code: storageConfig.code || storageConfig.resourceCode,
+    name: storageConfig.name,
+    description: storageConfig.description || '',
+    provider: storageConfig.provider || 'oss',
+    status: storageConfig.status || 'active',
+    configJson: storageConfig.configJson || storageConfig.config || {},
+    credentialStatus: storageConfig.credentials || storageConfig.credentialStatus || undefined,
+  });
+}
+
 function rewriteDataViewDefinitionForManifest(definition, lookups) {
   rewriteDataViewSourceForManifest(definition.base, lookups);
   for (const join of definition.joins || []) {
@@ -8657,6 +8837,106 @@ function normalizeAuthConfigManifest(authConfig) {
   });
 }
 
+function normalizeStorageConfigManifest(storageConfig) {
+  const code = storageConfig.code || storageConfig.resourceCode;
+  const configJson = clonePlainJson(
+    storageConfig.configJson ||
+      storageConfig.config ||
+      withoutStorageConfigManifestMeta(storageConfig)
+  );
+  const credentials = normalizeStorageCredentialsForPublish(storageConfig);
+  return stripUndefinedValues({
+    code,
+    name: storageConfig.name || configJson.name || code,
+    description:
+      storageConfig.description !== undefined
+        ? storageConfig.description
+        : configJson.description || '',
+    provider: storageConfig.provider || configJson.provider || 'oss',
+    status: storageConfig.status || configJson.status || 'active',
+    configJson: stripUndefinedValues({
+      region: configJson.region,
+      bucket: configJson.bucket,
+      endpoint: configJson.endpoint,
+      publicBaseUrl: configJson.publicBaseUrl,
+      pathPrefix: configJson.pathPrefix,
+      maxFileSizeMb: configJson.maxFileSizeMb,
+      allowedExtensions: configJson.allowedExtensions,
+      uploadUrlExpiresSeconds: configJson.uploadUrlExpiresSeconds,
+    }),
+    ...(credentials ? { credentials } : {}),
+  });
+}
+
+function withoutStorageConfigManifestMeta(storageConfig) {
+  const next = withoutResourceMeta(storageConfig);
+  delete next.code;
+  delete next.resourceCode;
+  delete next.name;
+  delete next.description;
+  delete next.provider;
+  delete next.status;
+  delete next.config;
+  delete next.configJson;
+  delete next.credentials;
+  delete next.secret;
+  delete next.secretJson;
+  delete next.credentialStatus;
+  return next;
+}
+
+function normalizeStorageCredentialsForPublish(storageConfig) {
+  const source =
+    storageConfig.credentials || storageConfig.secret || storageConfig.secretJson || {};
+  const hasAccessKeyId = source.accessKeyId !== undefined;
+  const hasAccessKeySecret = source.accessKeySecret !== undefined;
+  if (!hasAccessKeyId && !hasAccessKeySecret) return null;
+  return {
+    accessKeyId: resolveEnvReference(source.accessKeyId, 'OSS accessKeyId'),
+    accessKeySecret: resolveEnvReference(
+      source.accessKeySecret,
+      'OSS accessKeySecret'
+    ),
+  };
+}
+
+let cachedManifestEnv = null;
+
+function getManifestEnv() {
+  if (!cachedManifestEnv) {
+    cachedManifestEnv = {
+      ...loadGlobalEnv(),
+      ...process.env,
+    };
+  }
+  return cachedManifestEnv;
+}
+
+function isEnvReference(value) {
+  return Boolean(parseEnvReferenceName(value));
+}
+
+function resolveEnvReference(value, label) {
+  const envName = parseEnvReferenceName(value);
+  if (!envName) fail(`${label} 必须使用环境变量引用`);
+  const env = getManifestEnv();
+  const resolved = env[envName];
+  if (resolved === undefined || resolved === '') {
+    fail(`${label} 引用的环境变量未设置: ${envName}`);
+  }
+  return resolved;
+}
+
+function parseEnvReferenceName(value) {
+  const text = String(value || '').trim();
+  const match =
+    text.match(/^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/) ||
+    text.match(/^\$([A-Za-z_][A-Za-z0-9_]*)$/) ||
+    text.match(/^env:([A-Za-z_][A-Za-z0-9_]*)$/) ||
+    text.match(/^\{\{env\.([A-Za-z_][A-Za-z0-9_]*)\}\}$/);
+  return match?.[1];
+}
+
 function withoutAuthConfigManifestMeta(authConfig) {
   const next = withoutResourceMeta(authConfig);
   delete next.code;
@@ -9188,6 +9468,24 @@ function authConfigEquals(desired, existing) {
   );
 }
 
+function storageConfigEquals(desired, existing) {
+  if (!existing) return false;
+  const expected = normalizeStorageConfigManifest({
+    ...desired,
+    credentials: undefined,
+    secret: undefined,
+    secretJson: undefined,
+  });
+  return (
+    String(existing.code || existing.resourceCode || '') === String(expected.code || '') &&
+    String(existing.name || '') === String(expected.name || '') &&
+    String(existing.description || '') === String(expected.description || '') &&
+    String(existing.provider || 'oss') === String(expected.provider || 'oss') &&
+    String(existing.status || 'active') === String(expected.status || 'active') &&
+    jsonEqualsForPlan(existing.configJson || existing.config || {}, expected.configJson || {}, desired.__dir)
+  );
+}
+
 function routeEquals(desired, existing) {
   if (!existing) return false;
   const expected = normalizeRouteManifest(desired);

package/lib/workspace-init.js

@@ -57,6 +57,7 @@ function initWorkspace(options = {}) {
             roles: {},
             connectors: {},
             dataViews: {},
+            storageConfigs: {},
             notifications: {
               templates: {},
               typeConfigs: {},

package/openxiangda-skills/references/component-guide.md

@@ -59,7 +59,7 @@ AI 在实现成熟交互前必须先判断是否已有可靠组件或库：
 | --- | --- | --- | --- |
 | 选择人员 | `UserSelectField` | 直接接入组织架构 | 人员列表、搜索、按部门筛选、层级树 |
 | 选择部门 | `DepartmentSelectField` | 直接接入组织架构 | 部门树、搜索、多选 |
-| 上传附件 | `AttachmentField` | 接入平台存储 | 上传、预览、下载、鉴权 URL |
+| 上传附件 | `AttachmentField` | 接入平台存储或声明式 OSS 存储 | 上传、预览、下载、鉴权 URL 或真实 OSS URL |
 | 上传图片 | `ImageField` | 接入平台存储 | 上传、压缩、缩略图、预览 |
 | 富文本编辑 | `EditorField` | 含图片上传集成 | 完整工具栏、平台图床、粘贴清洗 |
 | 数字签名 | `DigitalSignatureField` | 平台级签名 | 签名采集、验证、归档 |
@@ -75,12 +75,13 @@ import {
   AttachmentField,
 } from 'openxiangda';
 
-<UserSelectField name="owner" label="负责人" multiple={false} />
-<DepartmentSelectField name="dept" label="所属部门" />
-<AttachmentField name="files" label="附件" maxCount={5} />
-```
-
-> ✅ 一句话原则：**这些场景看到了，直接抄上表，不要自己写。**
+<UserSelectField name="owner" label="负责人" multiple={false} />
+<DepartmentSelectField name="dept" label="所属部门" />
+<AttachmentField name="files" label="附件" maxCount={5} />
+<AttachmentField name="ossFiles" label="OSS 附件" uploadProvider="oss" storageCode="evaluate_oss" />
+```
+
+> ✅ 一句话原则：**这些场景看到了，直接抄上表，不要自己写。**
 
 ---
 

package/openxiangda-skills/references/forms/component-registry.md

@@ -75,6 +75,7 @@ Rules:
 - For `CascadeDateField`, store a date range and document whether the value is inclusive.
 - For `UserSelectField` and `DepartmentSelectField`, do not invent user or department IDs. Use runtime/platform selection.
 - For `AttachmentField` and `ImageField`, do not hardcode OSS URLs in defaults unless the file has already been uploaded by platform tooling.
+- For custom OSS attachment upload, first declare a `src/resources/storage/<code>.json` resource, then set `uploadProvider: "oss"` and `storageCode: "<code>"` on `AttachmentField`. Never put OSS AK/SK values in schema, page code, or committed resource files.
 - For `SubFormField`, use `columns` for child fields and keep child `fieldId` values stable within the subform.
 - `TextAreaField` is accepted by workspace tools and normalized to runtime `TextareaField`; prefer `TextAreaField` in OpenXiangda docs for readability.
 

package/openxiangda-skills/references/platform-data-model.md

@@ -43,7 +43,7 @@
 | 人员选择（单） | `UserSelectField` (单选) | `{"label": "张三", "value": "user_001"}` | `value.label` | `value.value` 作为 userId |
 | 人员选择（多） | `UserSelectField` (多选) | `[{"label":"张三","value":"user_001"},{"label":"李四","value":"user_002"}]` | `items.map(i => i.label).join(', ')` | `items.map(i => i.value)` 作为 userId 列表 |
 | 部门选择 | `DepartmentSelectField` | 单选 `{"label": "研发部", "value": "dept_001"}`；多选 `[{...}, ...]` | `value.label` 或 `items.map(i => i.label)` | `value.value` / `items.map(i => i.value)` |
-| 附件 | `AttachmentField` | `[{"name":"文件.pdf","url":"https://...","size":1024,"type":"application/pdf"}]` | 文件名+下载链接列表 | 通过 `url` 下载 |
+| 附件 | `AttachmentField` | `[{"name":"文件.pdf","url":"https://...","size":1024,"type":"application/pdf","provider":"platform或oss","storageCode":"evaluate_oss"}]` | 文件名+下载链接列表 | 通过 `url` 下载；OSS 附件保存真实 OSS URL |
 | 图片 | `ImageField` | `[{"name":"图片.png","url":"https://...","thumbUrl":"https://..."}]` | 缩略图网格 | 通过 `url` 预览 |
 | 子表单 | `SubFormField` | `[{字段A: ..., 字段B: ...}, {...}]` (对象数组) | 渲染为子行表格 | 遍历每行，按字段 code 取值 |
 | 位置 | `LocationField` | `{"address":"杭州市xxx","lng":120.12,"lat":30.27}` | `value.address` | `value.lng`/`value.lat` 用于地图 |
@@ -244,7 +244,7 @@ const filter = {
 3. **提交表单时必须组装完整 `{label, value}` 结构**：仅传 value 会导致历史展示丢失中文名。
 4. **多选字段始终是数组**，即便只有一项也写成 `[{label, value}]`；空值用 `[]`，不要用 `null`。
 5. **`UserSelectField` / `DepartmentSelectField` 与普通 `SelectField` 的格式完全一致**，唯一区别是 `value` 语义为 userId / departmentId。
-6. **附件 / 图片字段始终是数组**：单文件场景也是 `[{name, url, ...}]`，没有则 `[]`。
+6. **附件 / 图片字段始终是数组**：单文件场景也是 `[{name, url, ...}]`，没有则 `[]`。使用 OSS 自定义上传时，附件项会额外带 `provider: "oss"`、`storageCode`、`publicUrl` 等元信息，但仍以 `url` 作为主访问地址。
 7. **子表单 `SubFormField` 是对象数组**，每个对象代表一行，键为子字段 code。读取时遍历数组，按字段 code 访问；空子表单为 `[]`。
 8. **不要尝试"翻译"或"规范化" label/value**：数据库存的就是最终展示格式，前后端皆然。任何二次翻译都是 bug 来源。
 9. **流程表单的数据格式与普通表单一致**：`formData` 结构与普通表单一致，流程节点信息走另外的字段，不影响业务字段结构。

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -50,6 +50,7 @@ openxiangda notification template-upsert --json-file src/resources/notifications
 openxiangda notification type-upsert --json-file src/resources/notifications/register.json
 openxiangda notification preview public_register_notice --body-json '{"payload":{"title":"测试"}}'
 
+openxiangda resource plan storage --profile <name>
 openxiangda data-view upsert --json-file src/resources/data-views/public_lookup.json
 openxiangda menu update public_register --json-file src/resources/menus/public_register.json --write-manifest
 openxiangda permission audit --json
@@ -138,6 +139,44 @@ await auth.phoneCodeLogin({ phone, code, challengeId: sent.challengeId });
 
 设计前必须确认启用方式、注册策略、身份匹配键、provider 边界、默认权限、安全参数、第三方配置归属。
 
+## 1. Storage — `src/resources/storage/<code>.json`
+
+用于给附件字段声明自定义 OSS 上传目标。manifest 里只能写环境变量引用，不能写真实 AK/SK；发布时 CLI 解析环境变量，后端密文保存。
+
+```json
+{
+  "code": "evaluate_oss",
+  "name": "Evaluate OSS",
+  "provider": "oss",
+  "status": "active",
+  "configJson": {
+    "region": "oss-cn-hangzhou",
+    "bucket": "evaluate-oss",
+    "publicBaseUrl": "https://evaluate-oss.oss-cn-hangzhou.aliyuncs.com",
+    "pathPrefix": "openxiangda/{{appType}}/{{yyyy}}/{{MM}}/{{dd}}",
+    "maxFileSizeMb": 20,
+    "allowedExtensions": ["txt", "pdf", "png"]
+  },
+  "credentials": {
+    "accessKeyId": "${APP_OSS_ACCESS_KEY_ID}",
+    "accessKeySecret": "${APP_OSS_ACCESS_KEY_SECRET}"
+  }
+}
+```
+
+表单字段引用：
+
+```tsx
+<AttachmentField
+  name="attachments"
+  label="附件"
+  uploadProvider="oss"
+  storageCode="evaluate_oss"
+/>
+```
+
+默认附件不配置 `uploadProvider`/`storageCode` 时仍走平台上传。OSS 附件保存真实 OSS URL；预览、下载、删除对象都通过 storage 配置对应的运行时接口处理。
+
 ## 1. Public Route — `src/resources/routes/<code>.json`
 
 新 React SPA 公开页使用 `/view/:appType/public/*`，不要再使用旧 `?publicAccess=guest`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.118",
+  "version": "1.0.119",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {

package/packages/sdk/dist/{ProcessPreview-Cw7X8odD.d.mts → ProcessPreview-CFmuu427.d.mts}

@@ -252,11 +252,16 @@ interface RuntimeRequestConfig {
     headers?: Record<string, string>;
     responseType?: 'json' | 'blob';
 }
+interface RuntimeUploadOptions {
+    uploadProvider?: 'platform' | 'oss';
+    storageCode?: string;
+    appType?: string;
+}
 interface FormRuntimeApi {
     request: <T = any>(config: RuntimeRequestConfig) => Promise<RuntimeResponse<T> | Blob>;
-    uploadFile: (file: File, bucketName?: string, onProgress?: (percent: number) => void) => Promise<AttachmentItem>;
+    uploadFile: (file: File, bucketName?: string, onProgress?: (percent: number) => void, options?: RuntimeUploadOptions) => Promise<AttachmentItem>;
     uploadPublicFile: (file: File, bucketName?: string, onProgress?: (percent: number) => void) => Promise<AttachmentItem>;
-    deleteFile: (objectName: string, bucketName?: string) => Promise<{
+    deleteFile: (objectName: string, bucketName?: string, options?: RuntimeUploadOptions) => Promise<{
         success: boolean;
     }>;
     createDownloadTicket: (bucketName: string, objectName: string, fileName?: string) => Promise<any>;
@@ -571,6 +576,9 @@ interface AttachmentItem {
     id: string;
     uid?: string;
     status?: 'uploading' | 'done' | 'error';
+    provider?: 'platform' | 'oss';
+    storageCode?: string;
+    appType?: string;
     objectName?: string;
     bucketName?: string;
     originalName?: string;
@@ -593,6 +601,8 @@ interface AttachmentFieldProps extends BaseFieldProps {
     maxSize?: number;
     uploadAction?: string;
     bucketName?: string;
+    uploadProvider?: 'platform' | 'oss';
+    storageCode?: string;
     multiple?: boolean;
     allowedTypes?: string[];
     showPreview?: boolean;
@@ -1095,4 +1105,4 @@ interface ProcessPreviewProps {
 }
 declare const ProcessPreview: React__default.FC<ProcessPreviewProps>;
 
-export { type FormRuntimeConfig as $, type AddressFieldProps as A, type BaseFieldProps as B, type CascadeDateFieldProps as C, type DataFilter as D, type DepartmentTreeNode as E, type DigitalSignatureFieldProps as F, type DigitalSignatureValue as G, type EditorChoiceOption as H, type EditorFieldProps as I, type EditorToolbarAction as J, type FieldBehavior as K, type FieldDefinition as L, type FieldLayoutNode as M, type FieldValueSyncConfig as N, type FormAppearanceConfig as O, type FormDataDeleteParams as P, type FormDataQueryParams as Q, type FormEffect as R, type FormEffectAction as S, type FormEffectCondition as T, type FormEffectConditionOperator as U, type FormEngineConfig as V, type FormEngineMode as W, type FormInstanceData as X, type FormLayoutNode as Y, type FormRuntimeApi as Z, type FormRuntimeApiConfig as _, type AddressValue as a, type TextFieldProps as a$, type FormSchema as a0, FormSection as a1, type FormSectionProps as a2, type FormSubmitBehavior as a3, type FormTemplateConfig as a4, type GridLayoutCell as a5, type GridLayoutNode as a6, type ImageFieldProps as a7, type InitiatorSelectCandidate as a8, type InitiatorSelectRequirement as a9, type ProcessStatus as aA, type ProcessTask as aB, type RadioFieldProps as aC, type ResubmitParams as aD, type ReturnParams as aE, type ReturnPolicy as aF, type ReturnableNode as aG, type ReturnableNodeResult as aH, type RuntimeDataQueryParams as aI, type RuntimeDataQueryResult as aJ, type RuntimeRequestConfig as aK, type RuntimeResponse as aL, type SaveTaskParams as aM, type SectionLayoutNode as aN, type SelectFieldProps as aO, type SerialNumberFieldProps as aP, type SignaturePoint as aQ, type StandardFormPageMode as aR, type StatusMeta as aS, type StepLayoutItem as aT, type StepsLayoutNode as aU, type SubFormColumn as aV, type SubFormFieldProps as aW, type TabLayoutItem as aX, type TabsLayoutNode as aY, type TaskStatus as aZ, type TextAreaFieldProps as a_, type InitiatorSelectScope as aa, type InitiatorSelectedApprovers as ab, type JSONFieldProps as ac, type LayoutVisibleWhen as ad, type LinkedFormOptionConfig as ae, type LocationFieldProps as af, type LocationValue as ag, type LowcodePageMeta as ah, type LowcodePageNode as ai, type LowcodePageNodeType as aj, type LowcodePageSchema as ak, type MultiSelectFieldProps as al, type NumberFieldProps as am, type OptionItem as an, type OptionSourceConfig as ao, type OptionSourceType as ap, type PeopleShortcutConfig as aq, type PeopleShortcutType as ar, type PreviewParams as as, type ProcessAction as at, type ProcessBasicInfo as au, type ProcessDefinition as av, type ProcessNodeType as aw, ProcessPreview as ax, type ProcessPreviewProps as ay, type ProcessRoute as az, type ApprovalActionType as b, type TextShortcutConfig as b0, type TextShortcutType as b1, type TransferParams as b2, type UserDisplayFormat as b3, type UserItem as b4, type UserSelectFieldProps as b5, type ValidationPreset as b6, type ValidationRule as b7, type ViewPermissionQueryParams as b8, type ViewPermissionSummary as b9, type WithdrawParams as ba, type ApprovalPermission as c, ApprovalTimeline as d, type ApprovalTimelineProps as e, type ApproveParams as f, type AssociationFormConfig as g, type AssociationFormFieldProps as h, type AssociationValue as i, type AttachmentFieldProps as j, type AttachmentItem as k, type BaseLayoutNode as l, type CascadeSelectFieldProps as m, type ChangeRecord as n, type ChangeRecordListResponse as o, type ChangeRecordQueryParams as p, type CheckboxFieldProps as q, type DataLinkageCondition as r, type DataLinkageConfig as s, type DateFieldProps as t, type DateRangeRestriction as u, type DateRestrictionConfig as v, type DateShortcutConfig as w, type DateShortcutType as x, type DefaultValueLinkageConfig as y, type DepartmentSelectFieldProps as z };
+export { type FormRuntimeConfig as $, type AddressFieldProps as A, type BaseFieldProps as B, type CascadeDateFieldProps as C, type DataFilter as D, type DepartmentTreeNode as E, type DigitalSignatureFieldProps as F, type DigitalSignatureValue as G, type EditorChoiceOption as H, type EditorFieldProps as I, type EditorToolbarAction as J, type FieldBehavior as K, type FieldDefinition as L, type FieldLayoutNode as M, type FieldValueSyncConfig as N, type FormAppearanceConfig as O, type FormDataDeleteParams as P, type FormDataQueryParams as Q, type FormEffect as R, type FormEffectAction as S, type FormEffectCondition as T, type FormEffectConditionOperator as U, type FormEngineConfig as V, type FormEngineMode as W, type FormInstanceData as X, type FormLayoutNode as Y, type FormRuntimeApi as Z, type FormRuntimeApiConfig as _, type AddressValue as a, type TextAreaFieldProps as a$, type FormSchema as a0, FormSection as a1, type FormSectionProps as a2, type FormSubmitBehavior as a3, type FormTemplateConfig as a4, type GridLayoutCell as a5, type GridLayoutNode as a6, type ImageFieldProps as a7, type InitiatorSelectCandidate as a8, type InitiatorSelectRequirement as a9, type ProcessStatus as aA, type ProcessTask as aB, type RadioFieldProps as aC, type ResubmitParams as aD, type ReturnParams as aE, type ReturnPolicy as aF, type ReturnableNode as aG, type ReturnableNodeResult as aH, type RuntimeDataQueryParams as aI, type RuntimeDataQueryResult as aJ, type RuntimeRequestConfig as aK, type RuntimeResponse as aL, type RuntimeUploadOptions as aM, type SaveTaskParams as aN, type SectionLayoutNode as aO, type SelectFieldProps as aP, type SerialNumberFieldProps as aQ, type SignaturePoint as aR, type StandardFormPageMode as aS, type StatusMeta as aT, type StepLayoutItem as aU, type StepsLayoutNode as aV, type SubFormColumn as aW, type SubFormFieldProps as aX, type TabLayoutItem as aY, type TabsLayoutNode as aZ, type TaskStatus as a_, type InitiatorSelectScope as aa, type InitiatorSelectedApprovers as ab, type JSONFieldProps as ac, type LayoutVisibleWhen as ad, type LinkedFormOptionConfig as ae, type LocationFieldProps as af, type LocationValue as ag, type LowcodePageMeta as ah, type LowcodePageNode as ai, type LowcodePageNodeType as aj, type LowcodePageSchema as ak, type MultiSelectFieldProps as al, type NumberFieldProps as am, type OptionItem as an, type OptionSourceConfig as ao, type OptionSourceType as ap, type PeopleShortcutConfig as aq, type PeopleShortcutType as ar, type PreviewParams as as, type ProcessAction as at, type ProcessBasicInfo as au, type ProcessDefinition as av, type ProcessNodeType as aw, ProcessPreview as ax, type ProcessPreviewProps as ay, type ProcessRoute as az, type ApprovalActionType as b, type TextFieldProps as b0, type TextShortcutConfig as b1, type TextShortcutType as b2, type TransferParams as b3, type UserDisplayFormat as b4, type UserItem as b5, type UserSelectFieldProps as b6, type ValidationPreset as b7, type ValidationRule as b8, type ViewPermissionQueryParams as b9, type ViewPermissionSummary as ba, type WithdrawParams as bb, type ApprovalPermission as c, ApprovalTimeline as d, type ApprovalTimelineProps as e, type ApproveParams as f, type AssociationFormConfig as g, type AssociationFormFieldProps as h, type AssociationValue as i, type AttachmentFieldProps as j, type AttachmentItem as k, type BaseLayoutNode as l, type CascadeSelectFieldProps as m, type ChangeRecord as n, type ChangeRecordListResponse as o, type ChangeRecordQueryParams as p, type CheckboxFieldProps as q, type DataLinkageCondition as r, type DataLinkageConfig as s, type DateFieldProps as t, type DateRangeRestriction as u, type DateRestrictionConfig as v, type DateShortcutConfig as w, type DateShortcutType as x, type DefaultValueLinkageConfig as y, type DepartmentSelectFieldProps as z };