apaas-oapi-client 0.1.36 → 0.1.37

package/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+    // Code Runner 配置：使用 tsx 运行 TypeScript 文件
+    "code-runner.executorMap": {
+        "typescript": "npx tsx"
+    },
+    "code-runner.runInTerminal": true,
+    "code-runner.clearPreviousOutput": true,
+    "code-runner.saveFileBeforeRun": true
+}

package/README.md

@@ -11,11 +11,19 @@
 
 ## ✨ **功能特性**
 
-- ✅ 获取 accessToken
+### 数据操作
 - ✅ records 查询（支持分页迭代）
-- ✅ record 单条查询
-- ✅ record 单条更新、批量更新
-- ✅ record 单条删除、批量删除
+- ✅ record 单条查询、单条更新、单条删除
+- ✅ record 批量创建、批量更新、批量删除
+
+### 对象结构管理（Schema）
+- ✅ **创建数据对象**（批量）
+- ✅ **更新数据对象**（批量，支持添加/修改/删除字段）
+- ✅ **删除数据对象**（批量）
+- ✅ **字段类型完整文档**（20+ 字段类型，含示例）
+
+### 其他功能
+- ✅ 获取 accessToken（自动刷新）
 - ✅ **导出数据对象文档为 Markdown**
 - ✅ 内置 Bottleneck 限流器
 - ✅ 自定义日志等级
@@ -30,6 +38,60 @@ npm install apaas-oapi-client
 
 ---
 
+## � **快速开始**
+
+### 创建数据对象
+
+```typescript
+import { apaas } from 'apaas-oapi-client';
+
+const client = new apaas.Client({
+    clientId: 'your_client_id',
+    clientSecret: 'your_client_secret',
+    namespace: 'your_namespace'
+});
+
+await client.init();
+
+// 创建数据对象
+await client.schema.create({
+    objects: [{
+        api_name: 'product',
+        label: { zh_cn: '产品', en_us: 'Product' },
+        settings: {
+            display_name: 'code',
+            allow_search_fields: ['_id', 'code']
+        },
+        fields: [
+            {
+                api_name: 'code',
+                label: { zh_cn: '编号', en_us: 'Code' },
+                type: { name: 'text', settings: { required: true } },
+                encrypt_type: 'none'
+            }
+        ]
+    }]
+});
+
+// 更新对象：添加字段
+await client.schema.update({
+    objects: [{
+        api_name: 'product',
+        fields: [{
+            operator: 'add',  // 添加新字段
+            api_name: 'name',
+            label: { zh_cn: '名称', en_us: 'Name' },
+            type: { name: 'text', settings: { required: true } },
+            encrypt_type: 'none'
+        }]
+    }]
+});
+```
+
+---
+
 ## 📖 **使用文档**
 
-- 完整说明、初始化示例与 API 用法请查看 [UserManual.md](./UserManual.md)。
+- 完整说明、初始化示例与 API 用法请查看 [UserManual.md](./UserManual.md)
+- Schema 管理完整示例请查看 [examples/schema-operations.ts](./examples/schema-operations.ts)
+- **关联字段创建示例**（lookup/lookup_multi/referenceField/rollup）请查看 [examples/schema-reference-fields.ts](./examples/schema-reference-fields.ts)

package/dist/field-schema-rules.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Canonical field rules for schema.create/schema.update.
+ * Verified in namespace `package_5dc5b7__c` on 2026-02-10.
+ *
+ * Notes:
+ * - `metadataType` is usually the type name returned by object.metadata.fields.
+ * - Some entries are rule extensions for practical schema usage (`text_multiline`, `lookup_multi`).
+ * - `schemaType` is the type name that should be sent to schema.create/update.
+ */
+export type MetadataFieldType = 'text' | 'text_multiline' | 'bigint' | 'number' | 'date' | 'datetime' | 'option' | 'boolean' | 'lookup' | 'lookup_multi' | 'referenceField' | 'file' | 'autoId' | 'richText' | 'mobileNumber' | 'avatarOrLogo' | 'email' | 'region' | 'decimal' | 'multilingual';
+export type SchemaFieldType = 'text' | 'bigint' | 'float' | 'date' | 'datetime' | 'enum' | 'boolean' | 'lookup' | 'reference_field' | 'attachment' | 'auto_number' | 'richText' | 'phone' | 'avatar' | 'email' | 'region' | 'decimal' | 'multilingual';
+export interface FieldCreateRule {
+    metadataType: MetadataFieldType;
+    schemaType: SchemaFieldType;
+    settingsExample: Record<string, unknown>;
+    dependsOn?: string[];
+    notes?: string;
+}
+export declare const SCHEMA_TYPE_BY_METADATA_TYPE: Record<MetadataFieldType, SchemaFieldType>;
+export declare const OPTION_COLOR_LIST: readonly ["blue", "cyan", "green", "yellow", "orange", "red", "magenta", "purple", "blueMagenta", "grey"];
+export declare const FIELD_SCHEMA_RULES: FieldCreateRule[];
+export declare const SCHEMA_TYPE_MISMATCHES: Array<{
+    metadataType: MetadataFieldType;
+    schemaType: SchemaFieldType;
+}>;
+export declare const BATCH_UPDATE_REQUIREMENTS: {
+    readonly add: "Use operator=add with full field definition.";
+    readonly replace: "Use operator=replace and include full `type` (name + settings). Label-only replace fails.";
+    readonly remove: "Use operator=remove with api_name only.";
+    readonly dependencyOrder: {
+        readonly add: readonly ["lookup/lookup_multi before reference_field"];
+        readonly remove: readonly ["reference_field before lookup/lookup_multi"];
+    };
+    readonly referenceFieldConstraint: "reference_field only works with single lookup (`multiple: false`).";
+};

package/dist/field-types.d.ts

@@ -0,0 +1,313 @@
+/**
+ * aPaaS 数据对象 Schema 管理完整规范
+ *
+ * 本文档包含：
+ * 1. Schema 接口规范（创建、更新对象）
+ * 2. 字段类型完整定义（20+ 字段类型）
+ * 3. 系统字段说明（6 个自动创建字段）
+ * 4. 最佳实践和注意事项
+ */
+/**
+ * 多语文本结构
+ */
+export interface MultilingualText {
+    zh_cn: string;
+    en_us: string;
+}
+/**
+ * 对象设置
+ */
+export interface ObjectSettings {
+    /** 可搜索字段列表 - 注意：不要包含 _name，会报错 */
+    allow_search_fields?: string[];
+    /** 展示名称字段 - 注意：不要使用 _name，应使用自定义字段 */
+    display_name?: string;
+    /** 搜索布局字段列表 */
+    search_layout?: string[];
+}
+/**
+ * 字段类型定义
+ */
+export interface FieldTypeDefinition {
+    /** 字段类型名称 */
+    name: string;
+    /** 字段类型设置（根据不同类型有不同的结构） */
+    settings?: any;
+}
+/**
+ * 加密类型枚举
+ */
+export type EncryptType = 'none' | 'rand' | 'fix' | 'ope';
+/**
+ * 字段操作类型（用于 update 接口）
+ */
+export type FieldOperator = 'add' | 'replace' | 'remove';
+/**
+ * 创建对象时的字段定义
+ */
+export interface CreateFieldDefinition {
+    /** 字段 API 名称（必填） */
+    api_name: string;
+    /** 字段标签（必填） */
+    label: MultilingualText;
+    /** 字段类型（必填） */
+    type: FieldTypeDefinition;
+    /** 加密类型（建议显式指定，默认 'none'） */
+    encrypt_type?: EncryptType | null;
+}
+/**
+ * 更新对象时的字段定义
+ */
+export interface UpdateFieldDefinition {
+    /** 操作类型（必填）：add=添加字段, replace=修改字段, remove=删除字段 */
+    operator: FieldOperator;
+    /** 字段 API 名称（必填） */
+    api_name: string;
+    /** 字段标签（operator=add/replace 时需要） */
+    label?: MultilingualText;
+    /** 字段类型（operator=add/replace 时需要） */
+    type?: FieldTypeDefinition;
+    /** 加密类型（可选） */
+    encrypt_type?: EncryptType | null;
+}
+/**
+ * 创建对象的定义
+ */
+export interface CreateObjectDefinition {
+    /** 对象 API 名称（必填） */
+    api_name: string;
+    /** 对象标签（必填） */
+    label: MultilingualText;
+    /** 对象设置（可选） */
+    settings?: ObjectSettings;
+    /** 字段列表（必填，至少包含一个自定义字段） */
+    fields: CreateFieldDefinition[];
+}
+/**
+ * 更新对象的定义
+ */
+export interface UpdateObjectDefinition {
+    /** 对象 API 名称（必填） */
+    api_name: string;
+    /** 对象标签（可选，不传则不修改） */
+    label?: MultilingualText;
+    /** 对象设置（可选，不传则不修改） */
+    settings?: ObjectSettings;
+    /** 字段列表（可选，不传则不修改字段） */
+    fields?: UpdateFieldDefinition[];
+}
+/**
+ * Schema 接口最佳实践和限制说明
+ */
+export declare const SCHEMA_GUIDELINES: {
+    /** 批量操作限制 */
+    readonly limits: {
+        readonly batch_size: 10;
+    };
+    /** 系统字段说明 */
+    readonly system_fields: {
+        readonly description: "系统字段会自动创建，不需要在 fields 数组中定义";
+        readonly fields: readonly ["_id", "_name", "_createdBy", "_createdAt", "_updatedBy", "_updatedAt"];
+    };
+    /** display_name 限制 */
+    readonly display_name: {
+        readonly restriction: "不能使用 _name 作为 display_name";
+        readonly reason: "系统会误认为是包含 NOW/TODAY 函数的公式";
+        readonly solution: "使用自定义字段（如 code、name 等）";
+        readonly example: "display_name: \"code\"";
+    };
+    /** allow_search_fields 限制 */
+    readonly allow_search_fields: {
+        readonly restriction: "不能包含 _name 字段";
+        readonly reason: "系统不允许在可搜索字段中使用包含公式的字段";
+        readonly solution: "只包含 _id 和其他自定义字段";
+        readonly example: "allow_search_fields: [\"_id\", \"code\", \"name\"]";
+    };
+    /** encrypt_type 说明 */
+    readonly encrypt_type: {
+        readonly required: true;
+        readonly description: "建议每个字段都显式指定 encrypt_type";
+        readonly options: {
+            readonly none: "不加密（默认）";
+            readonly rand: "非确定性加密";
+            readonly fix: "固定加密";
+            readonly ope: "保序加密";
+        };
+    };
+    /** operator 说明（用于 update） */
+    readonly operator: {
+        readonly required: true;
+        readonly description: "更新字段时必须指定操作类型";
+        readonly options: {
+            readonly add: {
+                readonly description: "添加新字段";
+                readonly required_fields: readonly ["api_name", "label", "type"];
+            };
+            readonly replace: {
+                readonly description: "修改现有字段";
+                readonly required_fields: readonly ["api_name"];
+                readonly note: "只传需要修改的属性";
+            };
+            readonly remove: {
+                readonly description: "删除字段";
+                readonly required_fields: readonly ["api_name"];
+                readonly note: "只需要 api_name";
+            };
+        };
+    };
+    /** 关联字段说明 */
+    readonly reference_fields: {
+        readonly description: "关联字段用于在对象之间建立关联关系";
+        readonly types: {
+            readonly lookup: {
+                readonly description: "关联对象（单值）- 关联另一个对象的单条记录";
+                readonly settings: {
+                    readonly objectAPIName: "目标对象的 API 名称（必填）";
+                    readonly required: "是否必填（可选）";
+                    readonly displayStyle: "显示样式（可选）";
+                };
+                readonly example: "type: { name: \"lookup\", settings: { objectAPIName: \"supplier\" } }";
+                readonly write_format: "写入时只需要 _id：{ supplier: { _id: 123456 } }";
+            };
+            readonly lookup_multi: {
+                readonly description: "关联对象（多值）- 关联另一个对象的多条记录";
+                readonly settings: {
+                    readonly objectAPIName: "目标对象的 API 名称（必填）";
+                    readonly multiple: "true（多选）";
+                };
+                readonly limit: "最多可以关联 200 条记录";
+                readonly example: "type: { name: \"lookup_multi\", settings: { objectAPIName: \"category\", multiple: true } }";
+                readonly write_format: "写入时提供多个 _id：{ categories: [{ _id: 111 }, { _id: 222 }] }";
+            };
+            readonly referenceField: {
+                readonly description: "引用字段 - 引用关联对象中的字段值（系统自动维护，不可直接写入）";
+                readonly settings: {
+                    readonly guideFieldAPIName: "引导字段（lookup 字段）";
+                    readonly fieldAPIName: "引用的目标字段";
+                    readonly referenceObjectApiName: "引用的对象";
+                };
+                readonly example: "type: { name: \"referenceField\", settings: { guideFieldAPIName: \"supplier\", fieldAPIName: \"name\", referenceObjectApiName: \"supplier\" } }";
+                readonly note: "系统根据 lookup 字段自动计算，不能直接写入数据";
+            };
+            readonly rollup: {
+                readonly description: "汇总字段 - 对关联对象的数据进行聚合计算（系统自动维护，不可直接写入）";
+                readonly settings: {
+                    readonly objectAPIName: "被汇总的对象";
+                    readonly lookupFieldAPIName: "关联字段（当前对象中的 lookup 字段）";
+                    readonly fieldAPIName: "要汇总的字段";
+                    readonly functionType: "汇总函数：sum/avg/count/max/min/countDistinct";
+                    readonly rangeFilter: "过滤条件（可选）";
+                };
+                readonly example: "type: { name: \"rollup\", settings: { objectAPIName: \"order_item\", lookupFieldAPIName: \"order\", fieldAPIName: \"amount\", functionType: \"sum\" } }";
+                readonly note: "系统根据关联数据自动汇总，不能直接写入数据";
+            };
+        };
+        readonly prerequisites: {
+            readonly description: "创建关联字段的前置条件";
+            readonly rules: readonly ["目标对象必须已存在", "objectAPIName 必须准确（区分大小写）", "referenceField 和 rollup 依赖的 lookup 字段必须先创建", "删除 lookup 字段前，需要先删除依赖它的 referenceField 和 rollup 字段"];
+        };
+        readonly system_maintained: {
+            readonly description: "系统自动维护的字段不能直接写入数据";
+            readonly fields: readonly ["referenceField", "rollup", "formula"];
+            readonly reason: "这些字段的值由系统根据其他字段或公式自动计算";
+        };
+    };
+    /** 响应结构说明 */
+    readonly response: {
+        readonly structure: "双层响应结构";
+        readonly top_level: {
+            readonly code: "0 表示请求格式正确";
+            readonly msg: "success";
+            readonly data: "包含 items 数组";
+        };
+        readonly item_level: {
+            readonly description: "每个对象的实际创建/更新状态";
+            readonly location: "data.items[].status";
+            readonly check: "需要检查 status.code 判断是否真正成功";
+        };
+    };
+};
+/**
+ * 创建对象示例
+ */
+export declare const CREATE_OBJECT_EXAMPLE: CreateObjectDefinition;
+/**
+ * 更新对象示例（添加字段）
+ */
+export declare const UPDATE_OBJECT_ADD_FIELD_EXAMPLE: UpdateObjectDefinition;
+/**
+ * 更新对象示例（修改字段）
+ */
+export declare const UPDATE_OBJECT_REPLACE_FIELD_EXAMPLE: UpdateObjectDefinition;
+/**
+ * 更新对象示例（删除字段）
+ */
+export declare const UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE: UpdateObjectDefinition;
+/**
+ * 更新对象示例（只修改标签和设置）
+ */
+export declare const UPDATE_OBJECT_SETTINGS_EXAMPLE: UpdateObjectDefinition;
+/**
+ * 字段类型元数据接口
+ */
+export interface FieldTypeMetadata {
+    /** API 名称 */
+    api_name: string;
+    /** 字段类型中文名称 */
+    label: string;
+    /** 存储数据类型 */
+    storage_type: 'String' | 'Number' | 'Boolean' | 'Object' | 'Array';
+    /** 是否为系统字段 */
+    is_system: boolean;
+    /** 字段描述 */
+    description: string;
+    /** 存储示例 */
+    example: any;
+    /** 特殊说明 */
+    notes?: string;
+}
+/**
+ * aPaaS 平台所有字段类型定义
+ */
+export declare const FIELD_TYPES: Record<string, FieldTypeMetadata>;
+/**
+ * 系统默认字段列表（每个对象都会自动创建）
+ */
+export declare const SYSTEM_FIELDS: readonly ["_id", "_name", "_createdBy", "_createdAt", "_updatedBy", "_updatedAt"];
+/**
+ * 获取系统字段
+ */
+export declare function getSystemFields(): FieldTypeMetadata[];
+/**
+ * 获取自定义字段类型
+ */
+export declare function getCustomFieldTypes(): FieldTypeMetadata[];
+/**
+ * 根据 API 名称获取字段类型信息
+ */
+export declare function getFieldType(apiName: string): FieldTypeMetadata | undefined;
+/**
+ * 判断是否为系统字段
+ */
+export declare function isSystemField(apiName: string): boolean;
+/**
+ * 语言代码常量
+ */
+export declare const LANGUAGE_CODES: {
+    readonly EN_US: 1033;
+    readonly ZH_CN: 2052;
+};
+/**
+ * 多语文本辅助函数：创建多语文本对象
+ */
+export declare function createMultilingualText(zhCn: string, enUs?: string): Array<{
+    language_code: number;
+    text: string;
+}>;
+/**
+ * 多语文本辅助函数：从多语文本对象中提取文本
+ */
+export declare function extractMultilingualText(multilingualText: Array<{
+    language_code: number;
+    text: string;
+}>, languageCode?: number): string;