openxiangda 1.0.264 → 2.0.0-alpha.2

package/openxiangda-skills/references/data-views.md

@@ -1,360 +0,0 @@
-# Data View Resources
-
-Data views are OpenXiangda-managed read-only query resources under `src/resources/data-views/`. They can run as PostgreSQL materialized views (`storageMode: "materialized"`, the default) or as live logical views (`storageMode: "live"`). Use them to publish repeated multi-form joins and predefined aggregate statistics as reusable app resources.
-
-Use a data view when the app needs read-only joined data from multiple forms, such as:
-
-- Ticket list with customer name, owner, SLA, and status fields.
-- Order list with product, customer, and payment fields.
-- Project dashboard combining project, member, task, and risk forms.
-- Dashboard statistics such as monthly ticket count, order amount by customer, or task count by status.
-- Reusable lookup or report data consumed by several pages or automations.
-- Large list pages where repeated client-side cross-form joins would be slow or inconsistent.
-- Real-time multi-form reads where the query shape is fixed and the source data volume is bounded (`storageMode: "live"`).
-
-Do not use a data view for:
-
-- Single-form CRUD. Use `sdk.form.advancedSearch`, form pages, or `DataManagementList`.
-- Simple one-form dropdown options. Use `SelectField` with `optionSource.type: "linkedForm"`.
-- Writes or write-back. Data views are read-only.
-- Heavy real-time joins that cannot be paginated, indexed, filtered, or otherwise bounded.
-- Raw SQL, incremental refresh, source-table trigger refresh, ad-hoc BI/pivot/window analysis, or write-heavy realtime dashboards.
-
-## Authoring
-
-Place manifests in `src/resources/data-views/*.json`. Use logical `formCode` values in source files. The CLI resolves them to the current profile's `formUuid` during `resource publish`.
-
-Two view types are supported:
-
-- `viewType: "row"` or omitted: row-level joined view using `select`.
-- `viewType: "aggregate"`: grouped statistics view using `dimensions` and `measures`; query it with `stats`.
-
-Two storage modes are supported:
-
-- `storageMode: "materialized"` or omitted: create a PostgreSQL materialized view. Results may be stale until manual or scheduled refresh. Use `indexes` for common filters, sort fields, aggregate dimensions, and date buckets.
-- `storageMode: "live"`: do not create a materialized view. Every query is compiled and executed against source forms in real time. `indexes` are ignored and refresh APIs do not apply. Use it only for bounded real-time query shapes.
-
-Row view example:
-
-```json
-{
-  "code": "ticket_with_customer",
-  "name": "Ticket With Customer",
-  "storageMode": "materialized",
-  "base": { "formCode": "service_ticket", "alias": "ticket" },
-  "joins": [
-    {
-      "type": "left",
-      "formCode": "customer",
-      "alias": "customer",
-      "on": [
-        {
-          "left": "ticket.customer.value",
-          "op": "=",
-          "right": "customer.form_instance_id"
-        }
-      ]
-    }
-  ],
-  "select": [
-    { "field": "ticket.form_instance_id", "as": "ticketId" },
-    { "field": "ticket.title", "as": "ticketTitle" },
-    { "field": "customer.name", "as": "customerName" }
-  ],
-  "indexes": [{ "fields": ["ticketId"], "unique": true }],
-  "refresh": { "mode": "scheduled", "cron": "0 */10 * * * *" },
-  "permissionGroups": [
-    {
-      "code": "ticket_query",
-      "name": "Ticket Query",
-      "roles": ["manager"],
-      "operations": ["query"]
-    }
-  ]
-}
-```
-
-Aggregate statistics example:
-
-```json
-{
-  "code": "ticket_stats_by_customer",
-  "name": "Ticket Stats By Customer",
-  "viewType": "aggregate",
-  "storageMode": "materialized",
-  "base": { "formCode": "service_ticket", "alias": "ticket" },
-  "joins": [
-    {
-      "type": "left",
-      "formCode": "customer",
-      "alias": "customer",
-      "on": [
-        {
-          "left": "ticket.customer.value",
-          "op": "=",
-          "right": "customer.form_instance_id"
-        }
-      ]
-    }
-  ],
-  "dimensions": [
-    { "field": "customer.name", "as": "customerName" },
-    { "field": "ticket.created_at", "as": "createdMonth", "bucket": "month" }
-  ],
-  "measures": [
-    { "type": "count", "as": "ticketCount" },
-    { "type": "sum", "field": "ticket.amount", "as": "totalAmount" },
-    { "type": "avg", "field": "ticket.amount", "as": "avgAmount" }
-  ],
-  "having": { "field": "ticketCount", "op": ">", "value": 0 },
-  "indexes": [{ "fields": ["customerName", "createdMonth"] }],
-  "refresh": { "mode": "scheduled", "cron": "0 */10 * * * *" },
-  "permissionGroups": [
-    {
-      "code": "ticket_stats_query",
-      "name": "Ticket Stats Query",
-      "roles": ["manager"],
-      "operations": ["query"]
-    }
-  ]
-}
-```
-
-Field reference rules:
-
-- Use `alias.field`, for example `ticket.title`.
-- Use system fields directly, such as `form_instance_id`, `created_at`, `updated_at`, `created_by`, and `tenant_id`.
-- For option-like JSON fields that store `{ label, value }`, use `.value` for joins and `.label` for display when needed.
-- Every `select` item must have an explicit output alias in `as`.
-- Aggregate `dimensions` and `measures` also need explicit output aliases in `as`.
-- Runtime `fields`, `filters`, `having`, `order`, indexes, field permissions, and row permissions reference output aliases, not source field references.
-
-Aggregate rules:
-
-- Measures support `count`, `countDistinct`, `sum`, `avg`, `min`, and `max`.
-- `sum` and `avg` only support `NumberField`.
-- Date buckets support `hour`, `day`, `week`, `month`, `quarter`, and `year`, and only apply to `DateField`, `created_at`, and `updated_at`.
-- `where` filters source rows before grouping; `having` filters aggregate output aliases after grouping.
-- Use aggregate views for stable dashboard/query shapes. They are not an ad-hoc BI query engine.
-
-Join rules:
-
-- v1 supports `left` and `inner`.
-- Join operators are `=`, `!=`, `<>`, `>`, `>=`, `<`, `<=`.
-- The platform automatically constrains sources to the same tenant.
-
-Filters:
-
-- Definition `where` filters source rows before materialization and uses source references such as `ticket.status`.
-- Runtime query filters use output aliases such as `ticketTitle`.
-- Aggregate definition `having` and runtime stats `having` also use output aliases such as `ticketCount`.
-- Supported operators include `=`, `!=`, `<>`, `>`, `>=`, `<`, `<=`, `contains`, `notContains`, `in`, `isEmpty`, and `isNotEmpty`, with aliases such as `eq`, `neq`, `gte`, `lte`, `like`, `is_null`, and `is_not_null`.
-- Runtime SDK filters may be a search group/rule object or an array, for example `{ key: "statusValue", operator: "EQ", value: "已发布" }`; `field` is also accepted. Use output aliases, not source references.
-- If a row view outputs a full option-like JSON field, runtime string `EQ` and `IN` filters can match the JSON text for compatibility. For new data views, prefer selecting `.value` or `.label` into scalar aliases such as `statusValue` and indexing those aliases for exact, predictable filters.
-- Data view `permissionGroups.dataPermission` should use scalar hidden scope aliases such as `ownerUserScopeKey`, `unionGroupScopeKey`, or `departmentScopeKey`. Do not rely on fuzzy JSON option matching for permission boundaries.
-
-Refresh:
-
-- Refresh applies only to materialized data views.
-- `manual` means refresh only when an administrator runs refresh or the resource is recreated.
-- `scheduled` uses cron, for example `0 */10 * * * *`.
-- Materialized query results may be stale. Show or inspect `lastRefreshedAt` when freshness matters.
-- Live data views have no refresh state; `lastRefreshedAt` is `null` and refresh requests should be rejected.
-- Do not choose a high-frequency schedule by default. Ask or infer how stale the data may be before setting `scheduled`.
-
-Indexes:
-
-- Index output aliases that pages filter or sort by.
-- Row views should index stable IDs and common list filters/sort fields.
-- Aggregate views should index dimensions and date buckets used by charts, filters, drill-downs, or ordering.
-- Do not index every output field or every measure; extra indexes make refresh slower.
-- Use `unique: true` only when the output field combination is truly unique.
-
-## Performance And Freshness
-
-Materialized data views move expensive joins and aggregations from page runtime to refresh time. Live data views keep results current by executing the same declared query shape on each request. Both modes reduce repeated page code complexity only when the view shape, data scope, and query bounds are chosen deliberately.
-
-Before creating a data view, confirm these points:
-
-- **Freshness tolerance**: ask whether users need near-real-time data, 10-30 minute freshness, hourly/daily reports, or manual snapshots.
-- **Storage mode**: use `materialized` for read-heavy reports that tolerate refresh lag; use `live` for bounded real-time joins where source-table changes must appear immediately.
-- **Query shape**: list the fields users will filter, sort, group, or drill down by. These should become output aliases and usually indexes.
-- **Data scope**: if the business only needs active, recent, or in-scope records, put that rule in definition `where` so old/source-irrelevant rows are filtered before materialization.
-- **Visible fields**: output only fields the page or permission rules need. Use hidden scope aliases for data permissions when needed, but do not build one huge catch-all view.
-
-Refresh cadence guidance:
-
-- Use `manual` for admin diagnostics, imported snapshots, low-change reference data, or data that is refreshed after an intentional operation.
-- Use `scheduled` every 10-30 minutes for normal dashboards, joined report lists, and recurring management views.
-- Use hourly or daily schedules for leadership reports, historical statistics, and large aggregate views.
-- Avoid intervals below 5 minutes unless the user explicitly confirms the time sensitivity and expected source-table volume. High-frequency refreshes can pressure both source tables and the materialized view.
-- For strong real-time behavior after each form save, use `storageMode: "live"` only when the query is bounded. If the logic includes writes, side effects, raw platform orchestration, or expensive unbounded joins, use source-form queries, App Functions, or a different backend workflow instead.
-
-Index guidance:
-
-- For materialized mode, index only output aliases, not source references such as `customer.name`.
-- Live data views ignore `indexes`; keep their runtime filters and page size conservative.
-- For row views, index IDs used in drill-down (`ticketId`, `customerId`) and common filters/order fields (`statusValue`, `ownerId`, `createdAt`).
-- For aggregate views, index the dimensions/time buckets used in runtime `filters`, `having` drill-downs, and `order` (`customerId`, `statusValue`, `createdMonth`).
-- Keep compound indexes aligned with common query prefixes. For example, dashboard filters by customer then month should use `["customerId", "createdMonth"]`.
-- `searchKeyWord` across many text columns is inherently heavier than structured filters. Prefer explicit `filters` on indexed aliases.
-- `countDistinct` and high-cardinality dimensions are refresh-heavy. Confirm data volume and avoid very frequent schedules.
-- Show `lastRefreshedAt` on pages or in diagnostics when users may notice refresh delay.
-
-## Permissions
-
-Management APIs require `app:data-view:manage`.
-
-Runtime page queries use data view permission groups unless the user has app manage or data view manage runtime bypass permission.
-
-Permission group behavior:
-
-- `operations` can include `query` and `refresh`; omitted operations default to `query`.
-- Empty or omitted `roles` match all logged-in users.
-- Missing or empty `fieldPermissions` means all output fields are visible.
-- When multiple permission groups match, field permissions are most permissive: a field is visible if any matched group allows it.
-- `dataPermission` is a row condition over output aliases.
-- Hidden output aliases can still be used by `dataPermission`; this is useful for scope keys that should restrict rows but not be returned to pages.
-- Multiple matched row conditions are ORed.
-- If any matched group has no row condition, rows are unrestricted.
-
-## Commands
-
-Use the standard resource workflow:
-
-```bash
-openxiangda resource validate --profile dev
-openxiangda resource plan --profile dev
-openxiangda resource publish --profile dev
-openxiangda resource pull --profile dev
-```
-
-Diagnostic commands:
-
-```bash
-openxiangda data-view list --profile dev
-openxiangda data-view status ticket_with_customer --profile dev
-openxiangda data-view refresh ticket_with_customer --profile dev  # materialized only
-openxiangda data-view query ticket_with_customer --profile dev --fields ticketId,customerName
-openxiangda data-view query ticket_with_customer --profile dev --query-json query.json
-openxiangda data-view stats ticket_stats_by_customer --profile dev --fields customerName,ticketCount
-openxiangda data-view stats ticket_stats_by_customer --profile dev --query-json stats-query.json
-```
-
-## Runtime SDK
-
-`sdk.dataView.query` and `sdk.dataView.stats` work for both materialized and live data views. Responses include `storageMode`; materialized responses may include `lastRefreshedAt`, while live responses return current data and `lastRefreshedAt: null`.
-
-Direct query:
-
-```ts
-const response = await sdk.dataView.query("ticket_with_customer", {
-  fields: ["ticketId", "ticketTitle", "customerName"],
-  filters: [
-    { key: "customerName", operator: "contains", value: keyword },
-    { key: "statusValue", operator: "EQ", value: "已发布" },
-  ],
-  order: [{ field: "ticketTitle", isAsc: "y" }],
-  currentPage: 1,
-  pageSize: 20,
-})
-```
-
-Aggregate stats query:
-
-```ts
-const response = await sdk.dataView.stats("ticket_stats_by_customer", {
-  fields: ["customerName", "createdMonth", "ticketCount", "totalAmount"],
-  filters: [
-    { key: "customerName", operator: "contains", value: keyword },
-  ],
-  having: [
-    { key: "ticketCount", operator: ">", value: 0 },
-  ],
-  order: [{ field: "ticketCount", isAsc: "n" }],
-  currentPage: 1,
-  pageSize: 20,
-})
-```
-
-The response data is:
-
-```ts
-{
-  data: unknown[]
-  totalCount: number
-  currentPage: number
-  pageSize: number
-  lastRefreshedAt?: string | null
-}
-```
-
-Page data source descriptor:
-
-```ts
-export default {
-  dataSources: [
-    {
-      key: "tickets",
-      type: "dataView.query",
-      code: "ticket_with_customer",
-      fields: ["ticketId", "ticketTitle", "customerName"],
-      defaultFilter: [
-        { key: "ticketTitle", operator: "isNotEmpty" }
-      ]
-    },
-    {
-      key: "ticketStats",
-      type: "dataView.stats",
-      code: "ticket_stats_by_customer",
-      fields: ["customerName", "ticketCount"],
-      defaultHaving: [
-        { key: "ticketCount", operator: ">", value: 0 }
-      ]
-    }
-  ]
-}
-
-const response = await sdk.dataSource.run("tickets", {
-  filters: [
-    { key: "customerName", operator: "contains", value: keyword }
-  ],
-  pageSize: 20,
-})
-```
-
-## Common Patterns
-
-List page:
-
-- Define one data view for the list row shape.
-- Select only fields shown in the table, filters, and row actions.
-- Add indexes for common filters and sorts.
-- Query with `sdk.dataView.query`.
-
-Dashboard:
-
-- Use aggregate data views for stable metrics such as counts, totals, averages, status distribution, and time buckets.
-- Use row data views for drill-down lists behind those metrics.
-- Keep refresh scheduled.
-- Show `lastRefreshedAt` when business users care about freshness.
-
-Reusable lookup:
-
-- Use a data view if the display label depends on multiple forms.
-- Keep the output small, for example `id`, `label`, `status`, and `owner`.
-- For simple one-form lookup, keep using linkedForm instead.
-
-Automation diagnosis:
-
-- Query the data view with `openxiangda data-view query --query-json`.
-- Query aggregate views with `openxiangda data-view stats --query-json`.
-- Refresh manually after bulk imports or test data resets.
-
-## Troubleshooting
-
-- `formCode 未绑定`: publish or bind the source forms first so `.openxiangda/state.json` has their `formUuid`.
-- Empty joined fields: check whether the source field stores a scalar or `{ label, value }`; linked/select fields usually need `.value`.
-- Query field rejected: runtime filters and `fields` must use output aliases.
-- User sees no data: inspect role codes, permission groups, `fieldPermissions`, and `dataPermission`.
-- Data is stale: check `lastRefreshedAt`, scheduled cron, and refresh status.

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

@@ -1,90 +0,0 @@
-# Form Component Registry
-
-Use platform-supported component names in FormSchema. AI-authored app code must prefer these platform fields for form-entry UX; do not replace them with raw `<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers, or hand-written uploaders in `src/forms/**` or `src/pages/**`.
-
-Priority:
-
-1. Use the platform field component in `schema.ts`.
-2. If the standard form layout is not enough, customize presentation in `page.tsx` while still rendering the OpenXiangda standard form/runtime.
-3. If a real field component is missing, submit feedback with `openxiangda feedback submit --yes`, then use an `antd` / `antd-mobile` wrapper as a local workaround.
-4. Native HTML controls are only acceptable inside OpenXiangda SDK/platform component internals.
-
-Common field components:
-
-| Component | Use |
-| --- | --- |
-| `TextField` | Short text |
-| `TextAreaField` | Long text |
-| `NumberField` | Numeric value |
-| `DateField` | Date or datetime |
-| `CascadeDateField` | Date range |
-| `SelectField` | Single select |
-| `MultiSelectField` | Multi select |
-| `RadioField` | Radio group |
-| `CheckboxField` | Checkbox group |
-| `UserSelectField` | User picker |
-| `DepartmentSelectField` | Department picker |
-| `AttachmentField` | File upload |
-| `ImageField` | Image upload |
-| `AddressField` | Address |
-| `CascadeSelectField` | Cascading select |
-| `LocationField` | Location |
-| `EditorField` | Rich text |
-| `JSONField` | Structured JSON |
-| `SubFormField` | Child table; do not recursively flatten child fields unless the runtime requires it |
-
-Must-use platform components:
-
-| Scenario | Component |
-| --- | --- |
-| User picker | `UserSelectField` |
-| Department picker | `DepartmentSelectField` |
-| File upload | `AttachmentField` |
-| Image upload | `ImageField` |
-| Rich text | `EditorField` |
-| Signature | `DigitalSignatureField` |
-| Location | `LocationField` |
-
-Preferred platform components:
-
-| Scenario | Component |
-| --- | --- |
-| Text / textarea / number | `TextField` / `TextAreaField` / `NumberField` |
-| Date / date range | `DateField` / `CascadeDateField` |
-| Select / multi-select / radio / checkbox | `SelectField` / `MultiSelectField` / `RadioField` / `CheckboxField` |
-| Cascading select | `CascadeSelectField` |
-| Child rows | `SubFormField` |
-| Standard form rendering | `FormProvider` + `FormRenderer` |
-
-Rules:
-
-- Prefer simple field types first.
-- Prefer platform fields over page-level custom JSX controls for all normal data entry.
-- Do not emit raw native controls in AI-authored workspace code. Use an `antd` / `antd-mobile` wrapper only when no platform field can represent the UX, and submit feedback for the platform gap.
-- Do not use a code page where a normal form can solve the workflow.
-- Keep option values stable; labels may be user-facing.
-- Avoid generated random field IDs after initial creation.
-- Use field-level `rules` for validation. Required fields should set both `required: true` and `rules: [{ required: true, message: "..." }]` when a custom message is needed.
-- For option components (`SelectField`, `MultiSelectField`, `RadioField`, `CheckboxField`, `CascadeSelectField`), always provide an `options` array. Use `options: [{ value: "stable_code", label: "显示名" }]`; if options will be loaded elsewhere later, still emit `options: []` so the runtime does not crash on `options.map(...)`.
-- Do not rely on custom `relation` metadata alone for normal form pages. A `SelectField` with `relation` but no `options` can white-screen with `Cannot read properties of undefined (reading 'map')`. Use static `options`, or use `SelectField` with `optionSource.type: "linkedForm"` so the runtime queries source form records through the SDK.
-- Do not model business enums or data-source references as free text IDs. Use `SelectField` / `RadioField` with `options` for enums. For records maintained by another form, use `SelectField` with `options: []` and `optionSource.linkedForm`; set `remoteSearch: true`, `searchFieldId`, and a modest `pageSize` when the source data can be large.
-- If a selected option value must also be stored as a hidden scalar key for permission conditions, add `valueSync: [{ targetFieldId: "scopeKey", valuePath: "value" }]` to the visible `SelectField`.
-- `AssociationFormField` is kept only for backward compatibility. Do not use it for new form pages.
-- For `NumberField`, prefer explicit `min`, `max`, `precision`, and `unit` when the business meaning is constrained.
-- For `DateField`, use `mode: "date"` or `mode: "datetime"` and a stable `format` such as `YYYY-MM-DD` or `YYYY-MM-DD HH:mm`.
-- 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 or image 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` or `ImageField`. Never put OSS AK/SK values in schema, page code, or committed resource files.
-- For image thumbnails or lightweight previews, set `imageCompression: { enabled: true }` on `ImageField` or `AttachmentField`. The runtime keeps the original `url` and adds `thumbUrl`, `previewUrl`, and `variants` when compressed image variants are created.
-- For `SubFormField`, use `columns` for child fields and keep child `fieldId` values stable within the subform.
-- `JSONField` renders a validated structured-text editor in `NORMAL` / `DISABLED` mode and a formatted value in `READONLY` mode. Invalid JSON becomes a form validation error and cannot be silently saved as an older value. For one field, use its `renderer` / `editor` callbacks; for a whole standard form or a `DataManagementList` detail/submit drawer, pass `components={{ JSONField: CustomJsonField }}` so the registry is preserved through `StandardFormPage` and `FormProvider`.
-- `TextAreaField` is accepted by workspace tools and normalized to runtime `TextareaField`; prefer `TextAreaField` in OpenXiangda docs for readability.
-
-Common validation rule examples:
-
-```ts
-rules: [{ required: true, message: "请填写名称" }]
-rules: [{ preset: "phone", message: "请输入有效手机号" }]
-rules: [{ min: 0, message: "不能小于 0" }]
-```

package/openxiangda-skills/references/forms/form-schema.md

@@ -1,146 +0,0 @@
-# FormSchema
-
-Form source lives in `sy-lowcode-app-workspace`. `schema.ts` describes fields, persistence, and rules; `page.tsx` renders the actual form page using platform components. The generated platform page must come from the workspace bundle, not the legacy default platform schema page.
-
-Typical file:
-
-```text
-src/forms/<formCode>/schema.ts
-src/forms/<formCode>/page.tsx
-```
-
-The schema must default-export a `defineFormSchema(...)` result from `openxiangda`.
-
-Minimal schema:
-
-```ts
-import { defineFormSchema } from "openxiangda";
-
-export default defineFormSchema({
-  formMeta: {
-    formUuid: "",
-    appType: process.env.OPENXIANGDA_APP_TYPE || "APP_XXXX",
-    title: "客户信息",
-  },
-  fields: [
-    {
-      fieldId: "customer_name",
-      componentName: "TextField",
-      label: "客户名称",
-      required: true,
-      rules: [{ required: true, message: "请填写客户名称" }],
-      placeholder: "请输入客户名称",
-    },
-    {
-      fieldId: "customer_type",
-      componentName: "SelectField",
-      label: "客户类型",
-      placeholder: "请选择客户类型",
-      options: [
-        { value: "enterprise", label: "企业客户" },
-        { value: "individual", label: "个人客户" },
-      ],
-    },
-  ],
-});
-```
-
-## Required Metadata
-
-- `formMeta.formUuid`: live form ID. It may start empty during local authoring; publish tools can create and write it back.
-- `formMeta.appType`: target app. In OpenXiangda mode, `OPENXIANGDA_APP_TYPE` may override local config.
-- `formMeta.title`: user-facing form name.
-- Do not require `formMeta.formType`; the current `openxiangda` schema type only requires `formUuid`, `appType`, and `title`.
-
-## Field Rules
-
-- Each persisted field needs a stable `fieldId`.
-- Field labels should be user-facing Chinese names when the app is Chinese.
-- Each visible field should include a concise user-facing `placeholder`. Hidden/internal fields do not need placeholders.
-- Use `tips` only for special constraints, unusual formats, compliance notes, or non-obvious business rules. Do not add tips to every field.
-- Use `SelectField` / `RadioField` for enum values and always provide `options`.
-- Use `SelectField` with `optionSource.type: "linkedForm"` for values maintained in another form or data source, such as class, college, customer, project, category, or asset. The runtime queries source form data through the SDK and builds `{ label, value }` options. For large source forms, set `remoteSearch: true`, an explicit `searchFieldId`, and a modest `pageSize` so typing in the dropdown triggers remote search. Do not use `AssociationFormField` for new form pages, and do not ask users to type raw IDs in `TextField`.
-- Keep only user-needed fields visible. If a scalar key is needed for permissions, synchronization, computed state, or internal logic, derive it from a visible select/person/department field and keep it in the schema with `behavior: "HIDDEN"`. For `SelectField`, use `valueSync` when the selected option value should be copied into a hidden scalar field.
-- Do not create duplicate platform system fields such as creator, updater, creator department, updater department, created time, or updated time unless the user explicitly needs a distinct business field. The platform already creates system metadata for every form.
-- Labels, placeholders, tips, section titles, descriptions, and empty states must be end-user-facing. Do not write developer-facing implementation explanations into visible form copy.
-- Use platform-supported field components from `component-registry.md`.
-- Do not generate fields that are only visual layout containers.
-- Put validation rules on fields as `field.rules`. Do not put validation objects in top-level `schema.rules`.
-- For option components (`SelectField`, `MultiSelectField`, `RadioField`, `CheckboxField`, `CascadeSelectField`), always include `options`. If a linked lookup is not ready, use `options: []` instead of omitting it.
-
-Linked form dropdown example:
-
-```ts
-{
-  fieldId: "college",
-  componentName: "SelectField",
-  label: "所属学院",
-  placeholder: "请选择所属学院",
-  showSearch: true,
-  allowClear: true,
-  options: [],
-  valueSync: [{ targetFieldId: "collegeScopeKey", valuePath: "value" }],
-  optionSource: {
-    type: "linkedForm",
-    linkedForm: {
-      formUuid: "FORM_COLLEGE_PROFILE",
-      fieldId: "collegeName",
-      labelFieldId: "collegeName",
-      valueFieldId: "collegeCode",
-      searchFieldId: "collegeName",
-      sortField: "collegeName",
-      pageSize: 20,
-      remoteSearch: true,
-      deduplicate: true,
-    },
-  },
-}
-```
-
-## Effects vs Validation
-
-Top-level `schema.rules` is reserved for `FormEffect[]`, not validation. A `FormEffect` must have both `when` and `then`:
-
-```ts
-rules: [
-  {
-    id: "show_invoice_title",
-    when: { field: "need_invoice", operator: "eq", value: "yes" },
-    then: [{ action: "show", target: "invoice_title" }],
-  },
-]
-```
-
-Do not generate old-style top-level validation rules like this:
-
-```ts
-// Wrong: this causes runtime white screens because `when` is missing.
-rules: [
-  { id: "rule_required_name", type: "validation", field: "name", required: true },
-]
-```
-
-Use field-level validation instead:
-
-```ts
-{
-  fieldId: "name",
-  componentName: "TextField",
-  label: "姓名",
-  required: true,
-  rules: [{ required: true, message: "请填写姓名" }],
-}
-```
-
-## Layout
-
-`layout` is optional. If omitted, the standard runtime renders fields in declaration order. When using `layout`, only use `FormLayoutNode` structures supported by `openxiangda` (`field`, `section`, `grid`, `tabs`, `steps`).
-
-## Publish Rules
-
-- Build output is registered through `openxiangda workspace publish --profile <name>`.
-- The publish path uses `/openxiangda-api/v1` with `OPENXIANGDA_ACCESS_TOKEN`.
-- Do not use AK/SK for new OpenXiangda work.
-- Do not stop after `openxiangda form create`; that only creates the platform form shell. A form page is complete only after workspace publish builds and registers the bundle.
-- If a published form page is blank and the browser console says `Cannot use 'in' operator to search for 'all' in undefined`, check for invalid top-level `schema.rules` entries missing `when`.
-- If a published form page is blank and the browser console says `Cannot read properties of undefined (reading 'map')` near `SelectField`, check for option components missing `options`.

package/openxiangda-skills/references/forms/layout-and-rules.md

@@ -1,24 +0,0 @@
-# Form Layout And Rules
-
-## Layout
-
-- Keep forms scan-friendly: sections, rows, and field order should follow the user's real workflow.
-- Use groups for semantic sections, not for decoration.
-- Required fields should be limited to data that is actually needed to submit.
-- A process form should put approval-relevant fields near the top.
-
-## Rules
-
-Use declarative rules when possible:
-
-- Required validation
-- Numeric range validation
-- Option visibility
-- Field visibility
-- Computed/default values
-
-Avoid hidden custom script unless the behavior cannot be expressed declaratively.
-
-## Data Management
-
-Data management views are settings/resources around a form, not separate source forms. Store their live IDs under the current profile when they are created.