apaas-oapi-client 0.1.39 → 1.0.0

package/skills/apaas-schema/references/schema-maintenance-sop.md

@@ -0,0 +1,157 @@
+# Schema Maintenance SOP
+
+Use this reference for whole-application object maintenance: reading object structure, creating objects, editing fields, deleting fields, deleting objects, converting SQL/ER designs, and managing lookup/reference dependencies.
+
+## Non-Negotiable Rules
+
+- Read live object metadata before writing.
+- Do not modify or delete system objects `_user` and `_department`.
+- Do not create, replace, or remove fields whose API name starts with `_`.
+- Treat `schema.create`, `schema.update`, and `schema.delete` as high-risk writes.
+- Batch `schema.create/update/delete` calls by at most 10 objects.
+- After every write, re-read metadata and verify the expected object/field shape.
+
+## Response Validation
+
+Check three layers after every raw schema call with the SDK helper:
+
+```ts
+client.schema.checkResponse(result, "schema.update");
+```
+
+`code: "0"` with `data: null` is not success. It usually means a required setting is missing, for example `text.multiline` or `auto_number.generation_method`.
+
+## Create Objects: Three Stages
+
+Do not create a full object with raw `schema.create({ fields })`. Use `client.schema.createWithStages()` when fields are involved. It enforces this sequence even when there is no obvious dependency cycle.
+
+1. Stage 1a: create object shells only.
+2. Stage 1b: add base fields with `schema.update` and `operator: "add"`.
+3. Stage 2: add `lookup` / `lookup_multi` fields after all target objects exist.
+4. Stage 3: add `reference_field` after its single-value lookup exists.
+5. Final: update `display_name`, `allow_search_fields`, and `search_layout` after fields exist.
+
+```ts
+await client.schema.createWithStages({
+  objects: [{
+    api_name: "customer",
+    label: { zh_cn: "客户", en_us: "Customer" },
+    settings: { display_name: "name", allow_search_fields: ["_id", "name"], search_layout: [] },
+    fields: [{
+      operator: "add",
+      api_name: "name",
+      label: { zh_cn: "客户名称", en_us: "Name" },
+      type: {
+        name: "text",
+        settings: {
+          required: true,
+          unique: false,
+          case_sensitive: false,
+          multiline: false,
+          max_length: 100
+        }
+      },
+      encrypt_type: "none"
+    }]
+  }]
+});
+```
+
+## Update Fields
+
+- Add: send `operator: "add"` and the full field definition.
+- Replace: send `operator: "replace"` and the full `type.name + type.settings`; label-only replace fails.
+- Remove: send `operator: "remove"` and only `api_name`.
+- Skip existing fields when rerunning idempotently.
+
+```ts
+await client.schema.addFieldsIdempotent({
+  object_name: "customer",
+  fields: fieldsToAdd
+});
+```
+
+## Dependency Order
+
+Add order:
+
+1. Object shells
+2. Base fields
+3. `lookup` / `lookup_multi`
+4. `reference_field`
+
+Remove order:
+
+1. `reference_field`
+2. `lookup` / `lookup_multi`
+3. Other custom fields
+4. Custom objects
+
+Never add a lookup and a reference field that depends on it in the same `schema.update` batch; execution order is not guaranteed.
+
+## Delete All Custom Objects
+
+Use the SDK helper for environment cleanup or model rebuilds:
+
+```ts
+await client.schema.deleteAllCustomObjects({
+  confirm: true,
+  removeOtherFields: true
+});
+```
+
+The helper lists custom objects, reads fields, removes `referenceField`, then `lookup`, then optional other custom fields, deletes objects in batches of 10, and re-lists objects to verify deletion.
+
+## SQL / ER To aPaaS Mapping
+
+Map relational designs into aPaaS objects only after presenting a conversion table for user confirmation.
+
+| SQL Concept | aPaaS Mapping |
+| --- | --- |
+| Table | Object |
+| Primary key `id` | Ignore; aPaaS provides `_id` |
+| `created_at` / `updated_at` audit columns | Usually ignore; aPaaS provides system fields |
+| `VARCHAR(n)` / `CHAR(n)` | `text` with `max_length: n`, `multiline: false` |
+| `TEXT` / long text | `text` with `multiline: true`, `max_length: 100000` |
+| `INT` / `INTEGER` / `BIGINT` | `bigint` |
+| `FLOAT` / `DOUBLE` | `float` |
+| `DECIMAL(p,s)` | `decimal` with `decimal_places: s` |
+| `DATE` | `date` |
+| `DATETIME` / `TIMESTAMP` | `datetime` |
+| `BOOLEAN` / `TINYINT(1)` | `boolean` |
+| `ENUM(...)` | `enum` with `options` |
+| Foreign key | `lookup` with `multiple: false` |
+| Pure join table | Usually eliminate; use `lookup` with `multiple: true` on one side |
+| Join table with business fields | Keep as an object with two lookup fields |
+
+Semantic overrides:
+
+- Column names containing `email` / `mail`: prefer `email`.
+- Column names containing `phone` / `mobile` / `tel`: prefer `phone`.
+- Column names containing `avatar` / `logo`: prefer `avatar`.
+- Column names containing `region` / `province` / `city`: consider `region`, but ask before converting address text to region.
+
+Unsupported SQL features:
+
+- Stored procedures
+- Triggers
+- Views
+- Composite primary keys
+- Composite unique constraints
+- CHECK constraints
+- Partitioning
+
+## Confirmation Table
+
+Before creating from SQL/ER input, present a table like this and wait for confirmation:
+
+| SQL Table | aPaaS Object | Treatment |
+| --- | --- | --- |
+| customer | customer | Create |
+| customer_tag | - | Convert pure join table into multi lookup |
+
+| Object | SQL Column | SQL Type | aPaaS Type | API Name | Notes |
+| --- | --- | --- | --- | --- | --- |
+| customer | id | INT PK | - | - | Ignored; use `_id` |
+| customer | status | ENUM | enum | status | Confirm labels and colors |
+| order | customer_id | FK | lookup | customer | Target object must exist first |

package/skills/apaas-shared/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: apaas-shared
-description: "Use for aPaaS Node SDK shared setup and safety rules: client initialization, credentials, namespace, token cache, logger level, pagination defaults, retry expectations, write/delete confirmation, and error triage before using module-specific apaas skills."
+description: "Use for aPaaS Node SDK shared setup and safety rules: client initialization, credentials, namespace, token cache, logger level, OpenAPI coverage, pagination defaults, retry expectations, write/delete confirmation, and error-code triage before using module-specific apaas skills."
 ---
 
 # aPaaS Shared
@@ -14,6 +14,8 @@ Use this skill before module-specific aPaaS SDK work.
 - Keep `clientId`, `clientSecret`, access tokens, and app secrets out of logs and final answers.
 - Prefer `client.setLoggerLevel(3)` for normal work, `4` for debugging, and `5` only when inspecting non-sensitive payloads.
 - Treat SDK responses with `code !== "0"` as failed even if the HTTP call succeeded.
+- Read [references/openapi-coverage.md](references/openapi-coverage.md) when checking whether an API doc endpoint is already wrapped.
+- Read [references/openapi-error-codes.md](references/openapi-error-codes.md) when triaging non-zero response codes.
 
 ```ts
 import { apaas } from "apaas-oapi-client";
@@ -39,8 +41,9 @@ client.setLoggerLevel(3);
 ## Module Routing
 
 - Object metadata and record CRUD: use `apaas-object`.
+- OQL, cross-object search, constant objects, and datasets: use `apaas-object`.
 - Object and field schema changes: use `apaas-schema`.
-- Cloud functions and automation flows: use `apaas-function-flow`.
+- Cloud functions, automation flows, workflow status, user tasks, and Lark integration tokens: use `apaas-function-flow`.
 - Builder page metadata and links: use `apaas-builder`.
 - Global options and variables: use `apaas-global`.
 - User/department ID exchange and attachments: use `apaas-exchange-attachment`.

package/skills/apaas-shared/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "aPaaS Shared"
-  short_description: "aPaaS SDK 认证、凭证、安全与通用调用规则指南"
-  default_prompt: "Use $apaas-shared to initialize aPaaS SDK access safely."
+  short_description: "aPaaS SDK 认证、凭证、安全、OpenAPI 覆盖与错误码规则指南"
+  default_prompt: "Use $apaas-shared to initialize aPaaS SDK access and route OpenAPI/error-code work safely."

package/skills/apaas-shared/references/openapi-coverage.md

@@ -0,0 +1,33 @@
+# OpenAPI Coverage
+
+Source snapshot: API doc share for namespace `package_154107__c`, fetched on 2026-06-30. The left navigation contained 167 doc nodes and 72 unique current endpoints after normalizing namespace/object placeholders.
+
+## Current SDK Coverage
+
+| Doc area | Endpoints | SDK entry |
+| --- | --- | --- |
+| Auth | `POST /auth/v1/appToken` | `client.init()` / token cache |
+| Page | list/detail/link | `client.page.list`, `client.page.detail`, `client.page.url` |
+| Object metadata | object list, object metadata, field metadata | `client.object.list*`, `client.object.metadata.*` |
+| Object records | get/list/create/update/delete/batch | `client.object.search/create/update/delete.*` |
+| Object other APIs | OQL, cross-object search | `client.object.oql`, `client.object.search.recordsAcrossObjects*` |
+| Schema | batch create/update/delete objects | `client.schema.create/update/delete`, plus staged helpers |
+| Constant objects | `_currency`, `_country`, `_timeZone` records and metadata | `client.constant.records`, `record`, `metadata.*` |
+| Dataset | dataset list | `client.dataset.list`, `client.dataset.listWithIterator` |
+| Attachments | files and images | `client.attachment.file.*`, `client.attachment.avatar.*` |
+| Global config | global options and variables | `client.global.options.*`, `client.global.variables.*` |
+| Workflow execution | async execution status, flow detail | `client.workflow.execution.status`, `client.workflow.definition.detail` |
+| Workflow user tasks | task/instance list, detail, agree/reject/transfer/add assignee/cc/expedite/cancel/rollback/chat | `client.workflow.userTask.*` |
+| Flow invocation | v1/v2 flow execute | `client.automation.v1.execute`, `client.automation.v2.execute` |
+| Lark integration | default/custom app and tenant tokens | `client.integration.lark.*` |
+| Feishu ID exchange | v2 user/department exchange | `client.user.*`, `client.department.*` |
+
+## Deprecated Docs
+
+The doc tree also exposes `历史版本（不推荐）`. Do not add those endpoints as default SDK methods unless a user explicitly asks for legacy compatibility. Prefer current `/v1/data/...`, `/api/data/v1/...`, `/api/flow/v1/...`, and `/api/integration/v1/...` endpoints.
+
+## Validation Checklist
+
+- Run `npm test -- --runInBand` after endpoint changes.
+- Run `npm run build` so `dist/index.d.ts` exposes new methods.
+- Run `npm pack --dry-run --json` and verify `skills/` plus `dist/` are included.

package/skills/apaas-shared/references/openapi-error-codes.md

@@ -0,0 +1,55 @@
+# OpenAPI Error Codes
+
+All OpenAPI responses use `code`, `msg`, and often `data`. Treat `code !== "0"` as failed even when HTTP status is 200.
+
+```json
+{
+  "code": "k_op_ec_10100",
+  "msg": "Request parameters are not valid: userId is empty"
+}
+```
+
+## Families
+
+The 2026-06-30 API doc bundle listed 531 error codes:
+
+| Family | Prefix | Count | Typical area |
+| --- | --- | ---: | --- |
+| 通用 | `k_ec_` | 26 | generic parameter, permission, naming, unsupported |
+| OpenAPI | `k_op_ec_` | 19 | auth, request parsing, rate limit, backend errors |
+| 身份集成 | `k_ident_` | 38 | identity provider, user/account integration |
+| 元数据 | `k_mt_ec_` | 329 | object/field/schema metadata, record constraints |
+| 规则引擎 | `k_ru_ec_` | 24 | rule/formula/field picker validation |
+| 流程 | `k_wf_ec_` | 70 | workflow definition, execution, user tasks |
+| 权限 | `k_perm_ec_` | 10 | permission and security group errors |
+| 图片/附件 | `k_img_ec_` | 15 | image/file upload, preview, storage |
+
+## High-Signal Codes
+
+| Code | Meaning | First action |
+| --- | --- | --- |
+| `k_ec_000009` | 权限不足 | Verify app permission, namespace, and API credential scope. |
+| `k_ec_000011` | 缺少必填参数 | Compare payload with SDK method params and doc body/query/path fields. |
+| `k_ec_000012` | 必填参数为空 | Check empty strings, empty arrays, and missing nested fields. |
+| `k_ec_000015` | 请求参数不合法 | Read `msg`; for schema writes also run `client.schema.validateResponse`. |
+| `k_op_ec_10100` | 请求参数不合法 | Validate body shape and enum values. |
+| `k_op_ec_10101` | 无法解析 body | Check JSON serialization and `Content-Type: application/json`. |
+| `k_op_ec_10102` | URL 路径参数错误 | Check path params such as object, field, task, flow, or integration API names. |
+| `k_op_ec_10201` | 鉴权失败 | Re-init client and verify `clientId/clientSecret`. |
+| `k_op_ec_10203` | 无访问权限 | Check package role and API credential permission. |
+| `k_op_ec_20003` | 请求被限流 | Reduce concurrency; prefer iterator helpers and ID cursor pagination. |
+| `k_mt_ec_900064` | 字段被报表/页面/规则引用，无法删除 | Remove dependent page/rule/report references before schema delete. |
+| `k_mt_ec_900075` | 一次最多创建或更新 1000 条记录 | Split record writes into chunks. |
+| `k_wf_ec_2001002` | 缺少流程入参 | Re-read flow definition and required input params. |
+| `k_wf_ec_2001005` | 流程实例 ID 不存在 | Verify `execution_id` or approval instance ID from list/status APIs. |
+| `k_wf_ec_2001008` | 幂等键已使用 | Generate a new idempotency key before resubmit. |
+| `k_perm_ec_000001` | 权限不足 | Do not retry blindly; fix permission first. |
+| `k_img_ec_000004` | 附件超过 100M | Compress or split file before upload. |
+| `k_img_ec_000011` | 文件 ID 错误 | Re-read upload response and avoid mixing image/file IDs. |
+
+## Triage Rules
+
+- Do not rely on HTTP status alone.
+- Log `code`, `msg`, and safe request identifiers; do not log secrets or access tokens.
+- For batch APIs, inspect item-level status in `data.items` because the request can be partially successful.
+- For schema writes, `code: "0"` with `data: null` is a silent failure and must be treated as failed.

package/src/FIELD_SCHEMA_RULES.md

@@ -7,6 +7,7 @@ This file summarizes the verified schema rules for field types in aPaaS.
 - Source object for metadata: `full_field_format`
 - Lookup target used in tests: `_user`
 - Reference field target used in tests: `_lark_user_id`
+- Option color live check: `package_154107__c.object_test2.option_colors` on `2026-06-30`
 
 ## Why this file exists
 
@@ -66,6 +67,41 @@ Allowed option colors:
 - `blueMagenta`
 - `grey`
 
+Use the colors in this order and cycle from the beginning when options exceed 10.
+
+Live metadata for option fields returns camelCase keys:
+
+- Type name: `option`
+- Options path: `type.settings.optionList`
+- Option source: `type.settings.optionSource`
+- Global option API name: `type.settings.globalOptionAPIName`
+
+Create/update schema payloads use snake_case keys:
+
+- Type name: `enum`
+- Options path: `type.settings.options`
+- Option source: `type.settings.option_source`
+- Global option API name: `type.settings.global_option_api_name`
+
+OpenAPI write payloads require color short codes, while metadata returns color names. The SDK normalizes these metadata names before writing:
+
+| Metadata color | OpenAPI write code |
+|---|---|
+| `blue` | `B` |
+| `cyan` | `W` |
+| `green` | `G` |
+| `yellow` | `Y` |
+| `orange` | `O` |
+| `red` | `R` |
+| `magenta` | `V` |
+| `purple` | `P` |
+| `blueMagenta` | `I` |
+| `grey` | `N` |
+
+Do not copy metadata `optionList` back into `schema.update`; convert it to `options`.
+
+Use `getOptionColor(index)` from the SDK to assign metadata color names in this stable 10-color cycle. Use `getOptionColorCode(color)` only when constructing raw OpenAPI payloads outside the SDK normalizer.
+
 ## Batch update (`batch_update`) rules
 
 - `add`: use `operator: "add"` and send full field definition.
@@ -79,3 +115,5 @@ Allowed option colors:
 ## Canonical machine-readable source
 
 Use `/Users/Ethan/apaas/apaas-sdk/node-client/src/field-schema-rules.ts` as the source of truth for code.
+
+The SDK exports `SQL_TYPE_TO_SCHEMA_TYPE`, `COLUMN_NAME_SEMANTIC_RULES`, and `SQL_CONSTRAINT_TO_SETTINGS` for SQL/ER conversion workflows.

package/src/field-schema-rules.ts

@@ -94,6 +94,74 @@ export const OPTION_COLOR_LIST = [
     'grey'
 ] as const;
 
+export type OptionColor = typeof OPTION_COLOR_LIST[number];
+
+export const OPTION_COLOR_CODE_BY_NAME: Record<OptionColor, string> = {
+    blue: 'B',
+    cyan: 'W',
+    green: 'G',
+    yellow: 'Y',
+    orange: 'O',
+    red: 'R',
+    magenta: 'V',
+    purple: 'P',
+    blueMagenta: 'I',
+    grey: 'N'
+} as const;
+
+export const OPTION_COLOR_NAME_BY_CODE = Object.fromEntries(
+    Object.entries(OPTION_COLOR_CODE_BY_NAME).map(([name, code]) => [code, name])
+) as Record<string, OptionColor>;
+
+export type OptionColorCode = typeof OPTION_COLOR_CODE_BY_NAME[OptionColor];
+
+export function getOptionColor(index: number): OptionColor {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error('Option color index must be a non-negative integer.');
+    }
+
+    return OPTION_COLOR_LIST[index % OPTION_COLOR_LIST.length];
+}
+
+export function getOptionColorCode(color: OptionColor): OptionColorCode {
+    return OPTION_COLOR_CODE_BY_NAME[color] as OptionColorCode;
+}
+
+export function normalizeOptionColorForSchema(color: unknown): unknown {
+    if (typeof color !== 'string') {
+        return color;
+    }
+
+    return OPTION_COLOR_CODE_BY_NAME[color as OptionColor] || color;
+}
+
+export const OPTION_COLOR_RULES = {
+    allowedColors: OPTION_COLOR_LIST,
+    assignment: 'Use OPTION_COLOR_LIST in order and cycle from the beginning when options exceed 10.',
+    verifiedBy: {
+        namespace: 'package_154107__c',
+        object: 'object_test2',
+        field: 'option_colors',
+        date: '2026-06-30'
+    },
+    metadataShape: {
+        typeName: 'option',
+        optionListPath: 'type.settings.optionList',
+        colorPath: 'type.settings.optionList[].color',
+        sourcePath: 'type.settings.optionSource',
+        globalOptionPath: 'type.settings.globalOptionAPIName'
+    },
+    createShape: {
+        typeName: 'enum',
+        optionsPath: 'type.settings.options',
+        colorPath: 'type.settings.options[].color',
+        colorInput: 'SDK accepts metadata color names and normalizes them to OpenAPI color codes before writing.',
+        colorCodeByName: OPTION_COLOR_CODE_BY_NAME,
+        sourcePath: 'type.settings.option_source',
+        globalOptionPath: 'type.settings.global_option_api_name'
+    }
+} as const;
+
 export const FIELD_SCHEMA_RULES: FieldCreateRule[] = [
     {
         metadataType: 'text',
@@ -175,7 +243,7 @@ export const FIELD_SCHEMA_RULES: FieldCreateRule[] = [
                 }
             ]
         },
-        notes: `Do not send create type as \`option\`. Available option colors: ${OPTION_COLOR_LIST.join(', ')}.`
+        notes: `Do not send create type as \`option\`. Metadata returns optionList/optionSource/globalOptionAPIName; create/update expects options/option_source/global_option_api_name. The SDK accepts metadata color names and sends OpenAPI color codes (${Object.entries(OPTION_COLOR_CODE_BY_NAME).map(([name, code]) => `${name}=${code}`).join(', ')}).`
     },
     {
         metadataType: 'boolean',
@@ -324,6 +392,67 @@ export const SCHEMA_TYPE_MISMATCHES: Array<{
         schemaType: rule.schemaType
     }));
 
+export interface SqlTypeMapping {
+    /** SQL type regex pattern, case-insensitive. */
+    sqlPattern: string;
+    /** Mapped aPaaS schema type. */
+    schemaType: SchemaFieldType;
+    /** Settings derivation rule. */
+    settingsMapping: string;
+}
+
+export const SQL_TYPE_TO_SCHEMA_TYPE: SqlTypeMapping[] = [
+    { sqlPattern: 'VARCHAR\\(\\d+\\)|CHAR\\(\\d+\\)', schemaType: 'text', settingsMapping: 'max_length from (n), multiline: false' },
+    { sqlPattern: 'TEXT|LONGTEXT|MEDIUMTEXT|TINYTEXT|CLOB', schemaType: 'text', settingsMapping: 'multiline: true, max_length: 100000' },
+    { sqlPattern: 'INT|INTEGER|BIGINT|SMALLINT|TINYINT(?!\\(1\\))|MEDIUMINT|SERIAL', schemaType: 'bigint', settingsMapping: 'required/unique from constraints' },
+    { sqlPattern: 'FLOAT|DOUBLE|REAL', schemaType: 'float', settingsMapping: 'decimal_places_number: 2' },
+    { sqlPattern: 'DECIMAL\\(\\d+,\\d+\\)|NUMERIC\\(\\d+,\\d+\\)', schemaType: 'decimal', settingsMapping: 'decimal_places from scale (s)' },
+    { sqlPattern: 'DATE', schemaType: 'date', settingsMapping: 'required from constraints' },
+    { sqlPattern: 'DATETIME|TIMESTAMP', schemaType: 'datetime', settingsMapping: 'required from constraints' },
+    { sqlPattern: 'BOOLEAN|BOOL|TINYINT\\(1\\)|BIT', schemaType: 'boolean', settingsMapping: 'default_value from DEFAULT' },
+    { sqlPattern: 'ENUM\\(.*\\)', schemaType: 'enum', settingsMapping: 'options from enum values, colors auto-assigned with getOptionColor(index)' },
+    { sqlPattern: 'BLOB|BINARY|VARBINARY|LONGBLOB|MEDIUMBLOB', schemaType: 'attachment', settingsMapping: 'any_type: true' },
+    { sqlPattern: 'JSON', schemaType: 'richText', settingsMapping: 'only when JSON stores rich text content' }
+];
+
+export interface ColumnNameSemanticRule {
+    /** Column name regex pattern, case-insensitive. */
+    columnPattern: string;
+    /** Inferred aPaaS schema type. */
+    schemaType: SchemaFieldType;
+    /** Inference notes. */
+    notes: string;
+}
+
+export const COLUMN_NAME_SEMANTIC_RULES: ColumnNameSemanticRule[] = [
+    { columnPattern: '(^|_)(e?mail)(s?$|_)', schemaType: 'email', notes: 'Column name contains email/mail' },
+    { columnPattern: '(^|_)(phone|mobile|tel)(s?$|_)', schemaType: 'phone', notes: 'Column name contains phone/mobile/tel' },
+    { columnPattern: '(^|_)(avatar|logo|profile_image)(s?$|_)', schemaType: 'avatar', notes: 'Column name contains avatar/logo' },
+    { columnPattern: '(^|_)(region|province|city|district|address)(s?$|_)', schemaType: 'region', notes: 'Column name implies geographic data' }
+];
+
+export interface SqlConstraintMapping {
+    /** SQL constraint. */
+    sqlConstraint: string;
+    /** Mapped aPaaS settings field. */
+    settingsField: string;
+    /** Mapped value. */
+    settingsValue: string;
+    /** Mapping notes. */
+    notes: string;
+}
+
+export const SQL_CONSTRAINT_TO_SETTINGS: SqlConstraintMapping[] = [
+    { sqlConstraint: 'NOT NULL', settingsField: 'required', settingsValue: 'true', notes: 'Maps to required: true' },
+    { sqlConstraint: 'UNIQUE', settingsField: 'unique', settingsValue: 'true', notes: 'Maps to unique: true' },
+    { sqlConstraint: 'PRIMARY KEY', settingsField: '-', settingsValue: '-', notes: 'Ignored: aPaaS uses system _id' },
+    { sqlConstraint: 'AUTO_INCREMENT', settingsField: '-', settingsValue: '-', notes: 'Ignored: aPaaS _id auto-increments. For business serial numbers, use auto_number' },
+    { sqlConstraint: 'FOREIGN KEY', settingsField: 'referenced_object_api_name', settingsValue: '(target table)', notes: 'Convert to lookup field' },
+    { sqlConstraint: 'DEFAULT', settingsField: 'default_value', settingsValue: '(value)', notes: 'Only boolean type supports default_value in aPaaS' },
+    { sqlConstraint: 'CHECK', settingsField: '-', settingsValue: '-', notes: 'Not supported in aPaaS, handle in application logic' },
+    { sqlConstraint: 'INDEX', settingsField: '-', settingsValue: '-', notes: 'Not applicable, aPaaS manages indexing automatically' }
+];
+
 export const BATCH_UPDATE_REQUIREMENTS = {
     add: 'Use operator=add with full field definition.',
     replace: 'Use operator=replace and include full `type` (name + settings). Label-only replace fails.',

package/src/field-types.ts

@@ -92,8 +92,8 @@ export interface CreateObjectDefinition {
     label: MultilingualText;
     /** 对象设置（可选） */
     settings?: ObjectSettings;
-    /** 字段列表（必填，至少包含一个自定义字段） */
-    fields: CreateFieldDefinition[];
+    /** 字段列表（可选）。schema.create 会忽略 fields，安全做法是先建空壳，再用 schema.update 添加字段。 */
+    fields?: CreateFieldDefinition[];
 }
 
 /**