openxiangda 1.0.34 → 1.0.35

package/openxiangda-skills/references/connector-resources.md

@@ -10,6 +10,7 @@ Common folders:
 - `menus`
 - `workflows`
 - `automations`
+- `data-views`
 - `permissions/page-groups`
 - `permissions/form-groups`
 - `settings/forms`
@@ -27,6 +28,8 @@ Connector manifests use stable `code` values. The platform maps connector `code`
 
 Notification manifests live under `src/resources/notifications/` and contain `templates` plus `typeConfigs`. See `notifications.md` before generating reminders or message templates.
 
+Data view manifests live under `src/resources/data-views/` and define read-only materialized views for repeated multi-form joins. Use them for joined list/report/lookup sources where refresh lag is acceptable. Do not use them for single-form CRUD, simple linkedForm selects, real-time writes, or write-back. See `data-views.md` before generating one.
+
 ```json
 {
   "code": "crm",

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

@@ -0,0 +1,217 @@
+# Data View Resources
+
+Data views are OpenXiangda-managed read-only PostgreSQL materialized views. They turn repeated multi-form joins into a published resource under `src/resources/data-views/`.
+
+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.
+- 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.
+
+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.
+- Strong real-time views after every form update. Data views update after manual or scheduled refresh.
+- Raw SQL, incremental refresh, source-table trigger refresh, or group-by aggregation. v1 does not support them.
+
+## 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`.
+
+Minimal example:
+
+```json
+{
+  "code": "ticket_with_customer",
+  "name": "Ticket With Customer",
+  "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"]
+    }
+  ]
+}
+```
+
+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`.
+- Runtime `fields`, `filters`, `order`, indexes, field permissions, and row permissions reference output aliases, not source field references.
+
+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`.
+- Supported operators include `=`, `!=`, `<>`, `>`, `>=`, `<`, `<=`, `contains`, `notContains`, `in`, `isEmpty`, and `isNotEmpty`, with aliases such as `eq`, `neq`, `gte`, `lte`, `like`, `is_null`, and `is_not_null`.
+
+Refresh:
+
+- `manual` means refresh only when an administrator runs refresh or the resource is recreated.
+- `scheduled` uses cron, for example `0 */10 * * * *`.
+- Query results may be stale. Show or inspect `lastRefreshedAt` when freshness matters.
+
+Indexes:
+
+- Index output aliases that pages filter or sort by.
+- Use `unique: true` only when the output field combination is truly unique.
+
+## 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.
+- 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
+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
+```
+
+## Runtime SDK
+
+Direct query:
+
+```ts
+const response = await sdk.dataView.query("ticket_with_customer", {
+  fields: ["ticketId", "ticketTitle", "customerName"],
+  filters: [
+    { field: "customerName", operator: "contains", value: keyword },
+  ],
+  order: [{ field: "ticketTitle", isAsc: "y" }],
+  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: [
+        { field: "ticketTitle", operator: "isNotEmpty" }
+      ]
+    }
+  ]
+}
+
+const response = await sdk.dataSource.run("tickets", {
+  filters: [
+    { field: "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 one or more data views as read-optimized sources.
+- 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`.
+- 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

@@ -21,7 +21,6 @@ Common field components:
 | `ImageField` | Image upload |
 | `AddressField` | Address |
 | `CascadeSelectField` | Cascading select |
-| `AssociationFormField` | Select records from another form when a linked-form picker is required |
 | `LocationField` | Location |
 | `EditorField` | Rich text |
 | `JSONField` | Structured JSON |
@@ -35,8 +34,10 @@ Rules:
 - 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`, `AssociationFormField`, or a custom code page that resolves linked records.
-- Do not model business enums or data-source references as free text IDs. Use `SelectField` / `RadioField` with `options` for enums, and use `AssociationFormField` for records maintained by another form.
+- 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.

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

@@ -59,8 +59,8 @@ export default defineFormSchema({
 - 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 `AssociationFormField` for values maintained in another form or data source, such as class, college, customer, project, category, or asset. 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/association/person/department field and keep it in the schema with `behavior: "HIDDEN"`.
+- 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`.
@@ -68,6 +68,35 @@ export default defineFormSchema({
 - 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`:

package/openxiangda-skills/references/pages/page-sdk.md

@@ -6,6 +6,8 @@ Guidelines:
 
 - Do not hardcode `/openxiangda-api` calls inside end-user page components unless the page is explicitly an admin tool.
 - Prefer SDK modules for form data, user context, permissions, and platform navigation.
+- Use `sdk.dataView.query` for published read-only multi-form data views. Data view runtime queries can filter, sort, paginate, and select only output aliases.
+- Use `sdk.dataSource.run()` with a page data source descriptor when the page config should own the data view code, default fields, or default filters.
 - Use `sdk.connector.invoke`, `sdk.connector.call("connector.api")`, or `sdk.connector.download` for external services. The SDK calls the platform runtime connector endpoint; it must not call third-party domains directly.
 - Use `sdk.notification.sendByType` and `batchSendByType` for reusable business messages. Custom notification types must be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
 - For the current user's department hierarchy, use `sdk.department.getCurrentUserParentDepartments()`; do not hardcode `GET /department/:id/parentDepartments` in page code.
@@ -13,3 +15,44 @@ Guidelines:
 - Treat user context and tenant context as runtime-provided values.
 
 When the SDK lacks a capability, document the fallback and keep it isolated.
+
+Data view query:
+
+```ts
+const response = await sdk.dataView.query("ticket_with_customer", {
+  fields: ["ticketId", "ticketTitle", "customerName"],
+  filters: [
+    { field: "customerName", operator: "contains", value: keyword },
+  ],
+  order: [{ field: "ticketTitle", isAsc: "y" }],
+  currentPage: 1,
+  pageSize: 20,
+})
+```
+
+Data view data source descriptor:
+
+```ts
+export default {
+  dataSources: [
+    {
+      key: "tickets",
+      type: "dataView.query",
+      code: "ticket_with_customer",
+      fields: ["ticketId", "ticketTitle", "customerName"],
+      defaultFilter: [
+        { field: "ticketTitle", operator: "isNotEmpty" }
+      ]
+    }
+  ]
+}
+
+const response = await sdk.dataSource.run("tickets", {
+  filters: [
+    { field: "customerName", operator: "contains", value: keyword }
+  ],
+  pageSize: 20,
+})
+```
+
+Data view filters and fields use output aliases such as `customerName`, not source references such as `customer.name`. If the page only needs one form, prefer `sdk.form.advancedSearch`. If the page only needs a simple one-form dropdown, prefer linkedForm options.

package/openxiangda-skills/references/workspace-state.md

@@ -31,6 +31,13 @@ Tokens never belong in the project. User tokens live in `~/.openxiangda/profiles
         "menus": {},
         "roles": {},
         "connectors": {},
+        "dataViews": {
+          "ticket_with_customer": {
+            "dataViewId": "DV_XXX",
+            "materializedViewName": "mv_dv_abc123",
+            "status": "active"
+          }
+        },
         "notifications": {
           "templates": {},
           "typeConfigs": {}
@@ -52,6 +59,8 @@ Tokens never belong in the project. User tokens live in `~/.openxiangda/profiles
 - Do not search platform apps or reuse similar names unless the user explicitly asks to reuse an existing app or provides an `appType`.
 - Local resource keys are logical codes.
 - Live IDs and lightweight runtime aliases are nested under the profile that produced them.
+- `resources.dataViews` is keyed by data view `code` and stores only profile-local platform metadata such as `dataViewId`, `materializedViewName`, and last known `status`.
+- Data view definitions, refresh config, permissions, and source `formCode` references belong in `src/resources/data-views/*.json`, not in state.
 - Do not store business configuration or secrets in `.openxiangda/state.json`; store those in `src/resources/`.
 - A prod publish must not read dev IDs.
 - Before publishing to another platform, run `openxiangda workspace bind --profile <name> --app-type <APP_XXX>`.

package/openxiangda-skills/skills/openxiangda-form/SKILL.md

@@ -77,12 +77,12 @@ Read these references only when writing or reviewing schema:
 - Every visible field should have a concise, user-facing `placeholder` that tells the user what to enter or select.
 - Use `tips` sparingly. Add tips only for special constraints, unusual formats, or non-obvious business rules; ordinary fields should not have tips.
 - Use `SelectField` or `RadioField` for enumerable business values. Do not model enums as `TextField` values that users must type manually.
-- Use `AssociationFormField` when the value is maintained by another form or data source, such as class, college, customer, project, category, or asset. Do not make users maintain raw ID text fields for those values.
-- Display only fields the user needs to interact with. Permission scope keys, computed fields, sync fields, and developer/internal fields should normally be derived from visible select/association fields and stay in the schema with `behavior: "HIDDEN"` instead of appearing on the form page.
+- When a value is maintained by another form or data source, such as class, college, customer, project, category, or asset, use `SelectField` with `optionSource.type: "linkedForm"`. The runtime queries the source form through the SDK, converts records to `{ label, value }` options, and can use `remoteSearch: true` plus `searchFieldId` for large datasets. Do not use `AssociationFormField` for new form work, and do not make users maintain raw ID text fields for those values.
+- Display only fields the user needs to interact with. Permission scope keys, computed fields, sync fields, and developer/internal fields should normally be derived from visible select/person/department fields and stay in the schema with `behavior: "HIDDEN"` instead of appearing on the form page. For select-derived scalar keys, use `valueSync`.
 - Do not create separate fields for platform system metadata such as creator, updater, creator department, updater department, created time, or updated time unless the user explicitly asks for a separate business concept. The platform creates those system fields for every form.
 - All labels, placeholders, tips, section titles, empty states, and helper text must be end-user-facing business copy. Do not write developer explanations or implementation notes into visible page copy.
 - For business lifecycles, model status with normal form fields (`status`, owner/responsibility fields, action-log relation fields) unless the scenario has real approval tasks. Do not create workflow forms for ordinary status transitions.
-- For permission isolation, collect user-facing ownership with select, personnel, department, or association fields. If form permission groups require scalar matching, add hidden derived keys such as `collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, and `ownerUserScopeKey`; never expose those keys as editable text inputs.
+- For permission isolation, collect user-facing ownership with select, personnel, or department fields. If form permission groups require scalar matching, add hidden derived keys such as `collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, and `ownerUserScopeKey`; never expose those keys as editable text inputs.
 - For multi-platform publishing, create or bind the form separately for each profile.
 - Do not copy `formUuid` from dev to prod unless the target platform explicitly already uses that ID.
 - Keep `schema.ts` and `page.tsx` as the source for fields/layout/rules and presentation; generated build output is not the source of truth.

package/openxiangda-skills/skills/openxiangda-permission-settings/SKILL.md

@@ -34,7 +34,7 @@ Use role codes in permission group JSON. Bind existing role IDs only inside the
 openxiangda permission role-bind sales --role-id <id> --profile dev
 ```
 
-For dynamic multi-role apps, do not hardcode role behavior only in page code. Create a role maintenance form and sync it to platform roles with automation / JS_CODE. Visible scope fields should be maintainable controls: personnel/department fields for people and orgs, `SelectField` / `RadioField` for enums, and `AssociationFormField` for records maintained by other forms. If form permission groups need scalar matching, derive hidden keys such as `collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, `ownerUserScopeKey`, and `roleCode`; do not expose raw ID text fields to users. Use page permission groups for entry visibility and form permission groups with condition-based data permissions for real data isolation.
+For dynamic multi-role apps, do not hardcode role behavior only in page code. Create a role maintenance form and sync it to platform roles with automation / JS_CODE. Visible scope fields should be maintainable controls: personnel/department fields for people and orgs, `SelectField` / `RadioField` for enums, and `SelectField` with `optionSource.type: "linkedForm"` for records maintained by other forms. When the source form can have many records, set `remoteSearch: true` and `searchFieldId` so typing in the dropdown triggers an SDK query instead of loading every record. If form permission groups need scalar matching, derive hidden keys such as `collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, `ownerUserScopeKey`, and `roleCode`; do not expose raw ID text fields to users. Use page permission groups for entry visibility and form permission groups with condition-based data permissions for real data isolation.
 
 ## Page Permission Groups
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.34",
+  "version": "1.0.35",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {