openxiangda-devkit-core 2.19.0 → 2.20.0

package/dist/compiler/config.js

@@ -22,6 +22,7 @@ const DATE_TRIGGER_RESERVED_DATA_FIELDS = new Set([
     'dueAt',
 ]);
 const APP_DATA_FIELD_TYPES = new Set(DATA_FIELD_TYPES);
+const WORKFLOW_RUNTIME_CODE_PATTERN = /^[a-z][a-z0-9-]{2,63}$/;
 function adminNavigationItem(page, options = {}) {
     return Object.freeze({ page: Object.freeze(page), ...options });
 }
@@ -448,6 +449,11 @@ export const openXiangdaAppConfigSchema = {
             required: ['resources'],
             properties: {
                 resources: { type: 'array', maxItems: 100, items: { type: 'object' } },
+                subjectReadSurfaces: {
+                    type: 'array',
+                    maxItems: 50,
+                    items: { type: 'object' },
+                },
             },
         },
         authz: {
@@ -878,11 +884,36 @@ export function validateAppConfig(value) {
             })),
         ];
     }));
+    const declaredResourceFields = new Map((Array.isArray(object(config.data).resources)
+        ? object(config.data).resources
+        : []).map(resource => {
+        const item = object(resource);
+        const schema = object(item.schema);
+        const fields = Array.isArray(schema.fields) ? schema.fields : [];
+        return [
+            string(item.code),
+            new Map(fields.map(field => {
+                const declaration = object(field);
+                return [string(declaration.code), declaration];
+            })),
+        ];
+    }));
     const declaredResourceCodes = new Set(declaredResources.keys());
+    validateSubjectReadSurfaces(string(object(config.app).code), object(config.data).subjectReadSurfaces, object(config.data).resources, new Set((Array.isArray(object(config.authz).capabilities)
+        ? object(config.authz).capabilities
+        : []).map(item => string(object(item).code))), diagnostics);
     const declaredWorkflowCodes = new Set((Array.isArray(object(config.workflows).activations)
         ? object(config.workflows).activations
         : []).map(item => string(object(item).workflowCode)));
-    validateBackendOperations(backend.operations, declaredResources, declaredWorkflowCodes, new Set((Array.isArray(object(config.authz).roles) ? object(config.authz).roles : []).map(role => string(object(role).code))), diagnostics);
+    validateBackendOperations(backend.operations, declaredResources, declaredResourceFields, declaredWorkflowCodes, new Set((Array.isArray(object(config.authz).roles) ? object(config.authz).roles : []).map(role => string(object(role).code))), new Map((Array.isArray(object(config.data).subjectReadSurfaces)
+        ? object(config.data).subjectReadSurfaces
+        : []).map(surface => {
+        const declaration = object(surface);
+        return [
+            string(declaration.code),
+            string(object(declaration.subject).resourceCode),
+        ];
+    })), diagnostics);
     const eventConfig = object(config.events);
     const workflowConfig = object(config.workflows);
     if (backend.enabled === false &&
@@ -2244,7 +2275,13 @@ export function validateAppConfig(value) {
                 string(object(declaration.definition).code)) {
                 diagnostics.push(diagnostic('APP_CONFIG_WORKFLOW_USER_TITLE_REQUIRED', 'Workflow title 必须是用户可读本地化名称，不能等于内部 code', `${path}.definition.title`));
             }
+            if (!WORKFLOW_RUNTIME_CODE_PATTERN.test(string(definition.code))) {
+                diagnostics.push(diagnostic('APP_CONFIG_WORKFLOW_CODE_INVALID', 'Workflow code 必须匹配 /^[a-z][a-z0-9-]{2,63}$/，不能包含下划线或大写字母', `${path}.definition.code`));
+            }
             const subject = object(definition.subject);
+            if (!WORKFLOW_RUNTIME_CODE_PATTERN.test(string(subject.resourceCode))) {
+                diagnostics.push(diagnostic('APP_CONFIG_WORKFLOW_SUBJECT_RESOURCE_CODE_INVALID', 'Workflow subject.resourceCode 必须匹配 /^[a-z][a-z0-9-]{2,63}$/', `${path}.definition.subject.resourceCode`));
+            }
             const factProjection = object(subject.factProjection);
             const factEntries = Object.entries(factProjection);
             const subjectFields = eventResourceFields.get(string(subject.resourceCode));
@@ -2283,9 +2320,8 @@ export function validateAppConfig(value) {
             if (summaryFieldsInvalid) {
                 diagnostics.push(diagnostic('APP_CONFIG_WORKFLOW_SUMMARY_FIELDS_INVALID', `Workflow summaryFields 最多 ${WORKFLOW_SUMMARY_MAX_FIELDS} 个，必须是不重复的已声明 scalar/reference 字段；禁止 system/rich/json/subtable/file/image/signature，且 text.long 不超过 ${WORKFLOW_SUMMARY_TEXT_LONG_MAX_BYTES} bytes`, `${path}.definition.subject.summaryFields`));
             }
-            // 快照字段（option/user/department/resource-ref/cascade）投影出 { label, value }
-            // 对象；标量 inputSchema 属性会在运行时 INPUT_SCHEMA_MISMATCH 且命令无限重试。
-            // 编译期强制形状一致，把错误从"部署后静默重试"提前到"编写时"。
+            // 快照字段的投影形状必须与 Native 存储一致；否则命令会在运行时
+            // INPUT_SCHEMA_MISMATCH 并无限重试。编译期把错误提前到编写时。
             const SNAPSHOT_FIELD_PROJECTION_TYPES = new Set([
                 'option.single',
                 'option.multiple',
@@ -2310,11 +2346,30 @@ export function validateAppConfig(value) {
                         continue;
                     }
                     const property = workflowInputProperties[factKey];
-                    const propertyType = isRecord(property)
-                        ? string(property.type)
-                        : '';
-                    if (propertyType !== 'object') {
-                        diagnostics.push(diagnostic('APP_CONFIG_WORKFLOW_FACT_PROJECTION_SHAPE_INVALID', `fact "${factKey}" 投影的字段 ${fieldCode} 是 ${fieldType} 快照字段，运行时投影为 { label, value } 对象；inputSchema.properties.${factKey} 必须声明 type: "object"（multiple 字段用 array + object items），条件表达式用 path "${factKey}.value" 比较`, `${path}.definition.inputSchema.properties.${factKey}`));
+                    const propertyRecord = isRecord(property) ? property : {};
+                    const propertyType = string(propertyRecord.type);
+                    const itemRecord = isRecord(propertyRecord.items)
+                        ? propertyRecord.items
+                        : {};
+                    const itemType = string(itemRecord.type);
+                    const nestedItemRecord = isRecord(itemRecord.items)
+                        ? itemRecord.items
+                        : {};
+                    const nestedItemType = string(nestedItemRecord.type);
+                    const expected = fieldType === 'cascade.multiple'
+                        ? 'array（items.type=array，items.items.type=object）'
+                        : fieldType.endsWith('.multiple')
+                            ? 'array（items.type=object）'
+                            : 'object';
+                    const shapeValid = fieldType === 'cascade.multiple'
+                        ? propertyType === 'array' &&
+                            itemType === 'array' &&
+                            nestedItemType === 'object'
+                        : fieldType.endsWith('.multiple')
+                            ? propertyType === 'array' && itemType === 'object'
+                            : propertyType === 'object';
+                    if (!shapeValid) {
+                        diagnostics.push(diagnostic('APP_CONFIG_WORKFLOW_FACT_PROJECTION_SHAPE_INVALID', `fact "${factKey}" 投影的字段 ${fieldCode} 是 ${fieldType} 快照字段；inputSchema.properties.${factKey} 必须声明 ${expected}`, `${path}.definition.inputSchema.properties.${factKey}`));
                     }
                 }
             }
@@ -2514,7 +2569,126 @@ function validateCapabilityDeclarations(appCode, declarations, diagnostics) {
         seen.add(code);
     });
 }
-function validateBackendOperations(rawOperations, declaredResources, declaredWorkflowCodes, declaredRoleCodes, diagnostics) {
+function validateSubjectReadSurfaces(appCode, rawSurfaces, rawResources, declaredCapabilityCodes, diagnostics) {
+    if (rawSurfaces !== undefined && !Array.isArray(rawSurfaces)) {
+        diagnostics.push(diagnostic('APP_CONFIG_SUBJECT_READ_SURFACES_INVALID', 'data.subjectReadSurfaces 必须是数组', 'data.subjectReadSurfaces'));
+        return;
+    }
+    const resources = new Map((Array.isArray(rawResources) ? rawResources : []).map(raw => {
+        const resource = object(raw);
+        const schema = object(resource.schema);
+        const fields = Array.isArray(schema.fields) ? schema.fields : [];
+        return [
+            string(resource.code),
+            new Map(fields.map(field => [string(object(field).code), object(field)])),
+        ];
+    }));
+    const systemFields = new Set([
+        'id',
+        'revision',
+        'created_at',
+        'updated_at',
+        'created_by',
+        'updated_by',
+    ]);
+    const surfaceCodes = new Set();
+    (Array.isArray(rawSurfaces) ? rawSurfaces : []).forEach((raw, index) => {
+        const surface = object(raw);
+        const path = `data.subjectReadSurfaces[${index}]`;
+        const code = string(surface.code);
+        const capability = string(surface.capability);
+        const subject = object(surface.subject);
+        const subjectResourceCode = string(subject.resourceCode);
+        const subjectFields = Array.isArray(subject.fields)
+            ? subject.fields.map(string)
+            : [];
+        const subjectResource = resources.get(subjectResourceCode);
+        let invalid = Object.keys(surface).some(key => !['code', 'name', 'capability', 'subject', 'relations'].includes(key)) ||
+            !OPERATION_CODE_PATTERN.test(code) ||
+            surfaceCodes.has(code) ||
+            !string(surface.name) ||
+            !CAPABILITY_PATTERN.test(capability) ||
+            !capability.startsWith(`app:${appCode}:`) ||
+            !declaredCapabilityCodes.has(capability) ||
+            Object.keys(subject).some(key => !['resourceCode', 'fields'].includes(key)) ||
+            !subjectResource ||
+            subjectFields.length < 1 ||
+            subjectFields.length > 100 ||
+            new Set(subjectFields).size !== subjectFields.length ||
+            subjectFields.some(field => {
+                const declaration = subjectResource?.get(field);
+                return !declaration || string(declaration.type) === 'subtable';
+            });
+        const relations = Array.isArray(surface.relations)
+            ? surface.relations
+            : [];
+        invalid ||= relations.length < 1 || relations.length > 8;
+        const relationCodes = new Set();
+        let totalRows = 0;
+        relations.forEach(rawRelation => {
+            const relation = object(rawRelation);
+            const relationCode = string(relation.code);
+            const resourceCode = string(relation.resourceCode);
+            const foreignKeyField = string(relation.foreignKeyField);
+            const relationFields = Array.isArray(relation.fields)
+                ? relation.fields.map(string)
+                : [];
+            const resource = resources.get(resourceCode);
+            const foreignKey = resource?.get(foreignKeyField);
+            const source = object(foreignKey?.source);
+            const limit = Number(relation.limit);
+            const order = Array.isArray(relation.order) ? relation.order : [];
+            invalid ||=
+                Object.keys(relation).some(key => ![
+                    'code',
+                    'resourceCode',
+                    'foreignKeyField',
+                    'fields',
+                    'order',
+                    'limit',
+                ].includes(key)) ||
+                    !OPERATION_CODE_PATTERN.test(relationCode) ||
+                    relationCodes.has(relationCode) ||
+                    !resource ||
+                    !foreignKey ||
+                    !['uuid', 'resource-ref.single'].includes(string(foreignKey.type)) ||
+                    (string(foreignKey.type) === 'resource-ref.single' &&
+                        (string(source.kind) !== 'resource' ||
+                            string(source.resourceCode) !== subjectResourceCode)) ||
+                    relationFields.length < 1 ||
+                    relationFields.length > 100 ||
+                    new Set(relationFields).size !== relationFields.length ||
+                    relationFields.some(field => {
+                        const declaration = resource?.get(field);
+                        return !declaration || string(declaration.type) === 'subtable';
+                    }) ||
+                    !Number.isSafeInteger(limit) ||
+                    limit < 1 ||
+                    limit > 100 ||
+                    order.length > 10 ||
+                    order.some(rawOrder => {
+                        const item = object(rawOrder);
+                        const field = string(item.field);
+                        const declaration = resource?.get(field);
+                        return (Object.keys(item).some(key => !['field', 'direction'].includes(key)) ||
+                            (!systemFields.has(field) && !declaration) ||
+                            string(declaration?.type) === 'subtable' ||
+                            (!systemFields.has(field) &&
+                                !supportsSort(string(declaration?.type))) ||
+                            !['asc', 'desc'].includes(string(item.direction)));
+                    });
+            relationCodes.add(relationCode);
+            if (Number.isSafeInteger(limit))
+                totalRows += limit;
+        });
+        invalid ||= totalRows > 400;
+        if (invalid) {
+            diagnostics.push(diagnostic('APP_CONFIG_SUBJECT_READ_SURFACE_INVALID', 'subject read surface 必须声明唯一 code、显式 capability、一个可读父资源，以及最多 8 个直接等值且总计不超过 400 行的有界关系', path, '关系外键仅支持 uuid 或指向父资源的 resource-ref.single；字段、排序和行数必须全部由声明固定，不能由浏览器传入。'));
+        }
+        surfaceCodes.add(code);
+    });
+}
+function validateBackendOperations(rawOperations, declaredResources, declaredResourceFields, declaredWorkflowCodes, declaredRoleCodes, declaredSubjectSurfaces, diagnostics) {
     const declaredResourceCodes = new Set(declaredResources.keys());
     if (rawOperations !== undefined && !Array.isArray(rawOperations)) {
         diagnostics.push(diagnostic('APP_CONFIG_BACKEND_OPERATIONS_INVALID', 'backend.operations 必须是数组', 'backend.operations'));
@@ -2678,6 +2852,123 @@ function validateBackendOperations(rawOperations, declaredResources, declaredWor
                 diagnostics.push(diagnostic('APP_CONFIG_BACKEND_OPERATION_PLATFORM_ACCESS_INVALID', 'operation.platformAccess 必须只声明有界的发起人目录、托管文件、托管文件复制、标准通知、现有工作流或已声明角色条件依赖', `${path}.platformAccess`));
             }
         }
+        if (operation.browser !== undefined) {
+            const browser = object(operation.browser);
+            const subject = object(browser.subject);
+            const subjectResourceCode = string(subject.resourceCode);
+            const inputField = string(subject.inputField);
+            const requestSchema = object(operation.requestSchema);
+            const responseSchema = object(operation.responseSchema);
+            const requestProperties = object(requestSchema.properties);
+            const subjectInputSchema = object(requestProperties[inputField]);
+            const requiredFields = Array.isArray(requestSchema.required)
+                ? requestSchema.required.map(string)
+                : [];
+            const refreshTargets = Array.isArray(browser.refreshTargets)
+                ? browser.refreshTargets
+                : [];
+            const refreshKeys = refreshTargets.map(rawTarget => {
+                const target = object(rawTarget);
+                return `${string(target.kind)}:${string(target.code)}`;
+            });
+            let invalid = !isRecord(operation.browser) ||
+                Object.keys(browser).some(key => ![
+                    'exposure',
+                    'behavior',
+                    'idempotency',
+                    'subject',
+                    'refreshTargets',
+                    'fileIntent',
+                ].includes(key)) ||
+                browser.exposure !== 'authenticated' ||
+                !['read', 'controlled'].includes(string(browser.behavior)) ||
+                !['none', 'required'].includes(string(browser.idempotency)) ||
+                (browser.behavior === 'controlled' &&
+                    browser.idempotency !== 'required') ||
+                (browser.behavior === 'read' && browser.idempotency !== 'none') ||
+                !isRecord(browser.subject) ||
+                Object.keys(subject).some(key => !['resourceCode', 'inputField'].includes(key)) ||
+                !declaredResources.has(subjectResourceCode) ||
+                requestSchema.type !== 'object' ||
+                requestSchema.additionalProperties !== false ||
+                responseSchema.type !== 'object' ||
+                responseSchema.additionalProperties !== false ||
+                !/^[A-Za-z][A-Za-z0-9_]{0,127}$/.test(inputField) ||
+                !(inputField in requestProperties) ||
+                !requiredFields.includes(inputField) ||
+                subjectInputSchema.type !== 'string' ||
+                subjectInputSchema.format !== 'uuid' ||
+                refreshTargets.length > 16 ||
+                new Set(refreshKeys).size !== refreshKeys.length;
+            for (const rawTarget of refreshTargets) {
+                const target = object(rawTarget);
+                const targetCode = string(target.code);
+                invalid ||=
+                    Object.keys(target).some(key => !['kind', 'code'].includes(key)) ||
+                        target.kind !== 'subject-surface' ||
+                        !declaredSubjectSurfaces.has(targetCode) ||
+                        declaredSubjectSurfaces.get(targetCode) !== subjectResourceCode;
+            }
+            if (browser.fileIntent !== undefined) {
+                const fileIntent = object(browser.fileIntent);
+                const recordResourceCode = string(fileIntent.recordResourceCode);
+                const fields = declaredResourceFields.get(recordResourceCode);
+                const recordIdInputField = string(fileIntent.recordIdInputField);
+                const recordInputSchema = object(requestProperties[recordIdInputField]);
+                const relationField = string(fileIntent.relationField);
+                const relation = fields?.get(relationField);
+                const relationSource = object(relation?.source);
+                const fileNameField = string(fileIntent.fileNameField);
+                const contentTypeField = string(fileIntent.contentTypeField);
+                const sizeField = string(fileIntent.sizeField);
+                const purposes = Array.isArray(fileIntent.purposes)
+                    ? fileIntent.purposes.map(string)
+                    : [];
+                const allowedKeys = new Set([
+                    'recordResourceCode',
+                    'recordIdInputField',
+                    'relationField',
+                    'fileNameField',
+                    'contentTypeField',
+                    'sizeField',
+                    'purposes',
+                    'maxTtlSeconds',
+                    'maxBytes',
+                ]);
+                invalid ||=
+                    !isRecord(browser.fileIntent) ||
+                        Object.keys(fileIntent).some(key => !allowedKeys.has(key)) ||
+                        Object.keys(fileIntent).some(key => fileIntent[key] === undefined) ||
+                        method !== 'GET' ||
+                        browser.behavior !== 'read' ||
+                        browser.idempotency !== 'none' ||
+                        !fields ||
+                        !requiredFields.includes(recordIdInputField) ||
+                        recordInputSchema.type !== 'string' ||
+                        recordInputSchema.format !== 'uuid' ||
+                        !relation ||
+                        !['uuid', 'resource-ref.single'].includes(string(relation.type)) ||
+                        (relation.type === 'resource-ref.single' &&
+                            (relationSource.kind !== 'resource' ||
+                                relationSource.resourceCode !== subjectResourceCode)) ||
+                        !['text.short', 'text.long'].includes(string(fields?.get(fileNameField)?.type)) ||
+                        !['text.short', 'text.long'].includes(string(fields?.get(contentTypeField)?.type)) ||
+                        string(fields?.get(sizeField)?.type) !== 'number.integer' ||
+                        purposes.length < 1 ||
+                        purposes.length > 2 ||
+                        new Set(purposes).size !== purposes.length ||
+                        purposes.some(purpose => !['preview', 'download'].includes(purpose)) ||
+                        !Number.isSafeInteger(Number(fileIntent.maxTtlSeconds)) ||
+                        Number(fileIntent.maxTtlSeconds) < 1 ||
+                        Number(fileIntent.maxTtlSeconds) > 300 ||
+                        !Number.isSafeInteger(Number(fileIntent.maxBytes)) ||
+                        Number(fileIntent.maxBytes) < 1 ||
+                        Number(fileIntent.maxBytes) > 104857600;
+            }
+            if (invalid) {
+                diagnostics.push(diagnostic('APP_CONFIG_BACKEND_OPERATION_BROWSER_INVALID', 'browser operation 必须绑定已声明父资源和必填请求字段；controlled 必须强制幂等，刷新目标必须引用同一父资源的 subject surface；fileIntent 必须是只读、绑定关系记录与元数据字段，并限制为 5 分钟/100 MiB 内', `${path}.browser`));
+            }
+        }
         if (operation.ai !== undefined) {
             const ai = object(operation.ai);
             const aiResources = Array.isArray(ai.resources) ? ai.resources : [];
@@ -4460,7 +4751,12 @@ export function defineOpenXiangdaApp(declaration) {
         },
         platform: { root: 'platform', ...declaration.platform },
         ...(modules || declaration.data ? {
-            data: { resources: [...(declaration.data?.resources || []), ...projected.resources] },
+            data: {
+                resources: [...(declaration.data?.resources || []), ...projected.resources],
+                ...(declaration.data?.subjectReadSurfaces
+                    ? { subjectReadSurfaces: declaration.data.subjectReadSurfaces }
+                    : {}),
+            },
         } : {}),
     });
     // 生成式用户标准面：登录默认路由仍是模板占位时，指向首页资源的标准页。
@@ -4491,6 +4787,9 @@ export function defineOpenXiangdaApp(declaration) {
             ? {
                 data: {
                     resources: data.resources.map(resource => materializeDataResource(normalizedDeclaration.app.code, resource)),
+                    ...(data.subjectReadSurfaces
+                        ? { subjectReadSurfaces: data.subjectReadSurfaces }
+                        : {}),
                 },
             }
             : {}),