openxiangda 1.0.118 → 1.0.120

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,44 @@ 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 只适用于更新并保留平台已有密文`);
+    }
+    const cors = config.cors || item.cors;
+    if (cors?.managed === true) {
+      const allowedOrigins = normalizeManifestStringArray(
+        cors.allowedOrigins || cors.allowedOrigin || cors.origins || cors.origin
+      );
+      if (allowedOrigins.length === 0) {
+        warnings.push(`${label}.cors.allowedOrigins: 未声明时后端将尝试使用当前平台域名`);
+      }
+      const allowedMethods = normalizeManifestStringArray(
+        cors.allowedMethods || cors.allowedMethod || ['PUT', 'GET', 'HEAD']
+      );
+      if (allowedMethods.length === 0) errors.push(`${label}.cors.allowedMethods: 不能为空`);
+      const maxAgeSeconds = Number(cors.maxAgeSeconds || 600);
+      if (!Number.isFinite(maxAgeSeconds) || maxAgeSeconds < 0 || maxAgeSeconds > 86400) {
+        errors.push(`${label}.cors.maxAgeSeconds: 必须在 0 到 86400 秒之间`);
+      }
+    }
+  }
   if (kind === 'authConfigs') {
     const config = item.configJson || item.config || item;
     if (!Array.isArray(config.methods)) {
@@ -6214,6 +6277,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 +6351,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 +6379,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 +6561,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 +7337,44 @@ 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,
+      corsStatus: data?.corsStatus,
+    });
+  }
+}
+
 async function publishDataViewPermissionGroups(config, target, dataViewCode, permissionGroups) {
   await requestWithAuth(
     config,
@@ -7398,6 +7527,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 +7686,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 +7864,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 +8058,7 @@ function removeStateResource(target, kind, code) {
     route: 'routes',
     publicAccessPolicy: 'publicAccessPolicies',
     dataView: 'dataViews',
+    storageConfig: 'storageConfigs',
     pagePermissionGroup: 'pagePermissionGroups',
     formPermissionGroup: 'formPermissionGroups',
   };
@@ -8165,6 +8331,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 +8593,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 +8855,135 @@ function normalizeAuthConfigManifest(authConfig) {
   });
 }
 
+function normalizeStorageConfigManifest(storageConfig) {
+  const code = storageConfig.code || storageConfig.resourceCode;
+  const configJson = clonePlainJson(
+    storageConfig.configJson ||
+      storageConfig.config ||
+      withoutStorageConfigManifestMeta(storageConfig)
+  );
+  const cors = normalizeStorageCorsForPublish(configJson.cors || storageConfig.cors);
+  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,
+      cors,
+    }),
+    ...(credentials ? { credentials } : {}),
+  });
+}
+
+function normalizeStorageCorsForPublish(cors) {
+  if (cors === undefined || cors === null || cors === '') return undefined;
+  const managed =
+    cors === true ||
+    cors.managed === true ||
+    String(cors.managed || '').toLowerCase() === 'true';
+  if (!managed) return { managed: false };
+  return stripUndefinedValues({
+    managed: true,
+    allowedOrigins: normalizeManifestStringArray(
+      cors.allowedOrigins || cors.allowedOrigin || cors.origins || cors.origin
+    ),
+    allowedMethods: normalizeManifestStringArray(
+      cors.allowedMethods || cors.allowedMethod || ['PUT', 'GET', 'HEAD'],
+      { uppercase: true }
+    ),
+    allowedHeaders: normalizeManifestStringArray(
+      cors.allowedHeaders || cors.allowedHeader || ['content-type', 'x-oss-*']
+    ),
+    exposeHeaders: normalizeManifestStringArray(
+      cors.exposeHeaders || cors.exposeHeader || ['ETag', 'x-oss-request-id']
+    ),
+    maxAgeSeconds: Number(cors.maxAgeSeconds || 600),
+  });
+}
+
+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.cors;
+  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;
@@ -8934,6 +9261,16 @@ function normalizePermissionCodeArray(value) {
   );
 }
 
+function normalizeManifestStringArray(value, options = {}) {
+  const source = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+  const items = source
+    .flatMap(item => String(item || '').split(','))
+    .map(item => item.trim())
+    .filter(Boolean)
+    .map(item => options.uppercase ? item.toUpperCase() : item);
+  return unique(items);
+}
+
 function saveResourceEntry(target, bucket, code, extra = {}) {
   saveStateResource(target, bucket, code, pickStateFields(extra, ['formUuid']), [
     'formUuid',
@@ -9188,6 +9525,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,15 @@ 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" />
+```
+
+OSS 浏览器直传所需的 CORS 规则在 `src/resources/storage/<code>.json` 的 `configJson.cors.managed` 中声明，不要把 bucket 配置写进组件 props。
+
+> ✅ 一句话原则：**这些场景看到了，直接抄上表，不要自己写。**
 
 ---
 

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, optionally enable `configJson.cors.managed` for browser direct-upload CORS, 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/openxiangda-api.md

@@ -643,3 +643,71 @@ Requires Bearer token. Returns runtime bootstrap information for an existing cod
 ### GET `/apps/:appType/snapshot`
 
 Requires Bearer token. Returns app metadata, forms, menus, code page definitions, code page releases, and permission hints.
+
+## Storage Configs
+
+Storage config APIs manage application-level custom upload targets. The first provider is Aliyun OSS.
+
+### GET `/apps/:appType/storage-configs`
+
+Requires Bearer token and storage-config manage permission. Lists storage configs.
+
+### POST `/apps/:appType/storage-configs`
+
+Requires Bearer token and storage-config manage permission. Creates or upserts a storage config.
+
+Body:
+
+```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}}",
+    "allowedExtensions": ["txt", "pdf", "png"],
+    "cors": {
+      "managed": true,
+      "allowedOrigins": ["https://yida.wisejob.cn"],
+      "allowedMethods": ["PUT", "GET", "HEAD"],
+      "allowedHeaders": ["content-type", "x-oss-*"],
+      "exposeHeaders": ["ETag", "x-oss-request-id"],
+      "maxAgeSeconds": 600
+    }
+  },
+  "credentials": {
+    "accessKeyId": "resolved at publish time",
+    "accessKeySecret": "resolved at publish time"
+  }
+}
+```
+
+When `configJson.cors.managed` is true, the backend attempts to merge the required OSS bucket CORS rule after saving the storage config. The response may include `corsStatus`; `applied: false` means the storage config was saved but the OSS credentials could not manage bucket CORS.
+
+### GET `/apps/:appType/storage-configs/:code`
+
+Requires Bearer token and storage-config manage permission. Returns the storage config with credential status only, never plaintext AK/SK.
+
+### PUT `/apps/:appType/storage-configs/:code`
+
+Requires Bearer token and storage-config manage permission. Updates the storage config. Omit `credentials` to keep the existing encrypted credentials.
+
+### DELETE `/apps/:appType/storage-configs/:code`
+
+Requires Bearer token and storage-config manage permission. Deletes the storage config metadata; it does not delete existing OSS objects.
+
+### POST `/apps/:appType/storage-configs/:code/cors/apply`
+
+Requires Bearer token and storage-config manage permission. Re-applies the declared managed CORS rule for an existing config.
+
+### POST `/apps/:appType/storage-configs/:code/uploads/initiate`
+
+Requires Bearer token. Creates a short-lived signed OSS upload URL for browser direct upload.
+
+### POST `/apps/:appType/storage-configs/:code/objects/delete`
+
+Requires Bearer token. Deletes an OSS object under the configured `pathPrefix`.

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` 结构与普通表单一致，流程节点信息走另外的字段，不影响业务字段结构。