openxiangda 1.0.38 → 1.0.40

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

@@ -1,12 +1,13 @@
 # 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/`.
+Data views are OpenXiangda-managed read-only PostgreSQL materialized views. They turn repeated multi-form joins and predefined aggregate statistics into published resources 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.
+- 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.
 
@@ -16,13 +17,18 @@ Do not use a data view for:
 - 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.
+- 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`.
 
-Minimal example:
+Two view types are supported:
+
+- `viewType: "row"` or omitted: row-level joined materialized view using `select`.
+- `viewType: "aggregate"`: grouped statistics materialized view using `dimensions` and `measures`; query it with `stats`.
+
+Row view example:
 
 ```json
 {
@@ -61,13 +67,67 @@ Minimal example:
 }
 ```
 
+Aggregate statistics example:
+
+```json
+{
+  "code": "ticket_stats_by_customer",
+  "name": "Ticket Stats By Customer",
+  "viewType": "aggregate",
+  "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`.
-- Runtime `fields`, `filters`, `order`, indexes, field permissions, and row permissions reference output aliases, not source field references.
+- 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:
 
@@ -79,6 +139,7 @@ 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`.
 
 Refresh:
@@ -86,12 +147,45 @@ 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.
+- 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
+
+Data views move expensive joins and aggregations from page runtime to materialized-view refresh time. They reduce repeated page pressure only when the view shape, refresh cadence, and indexes 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.
+- **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, do not use a data view; query the source form directly or design a different backend workflow.
+
+Index guidance:
+
+- Index only materialized-view output aliases, not source references such as `customer.name`.
+- 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`.
@@ -105,6 +199,7 @@ Permission group behavior:
 - 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.
 
@@ -127,6 +222,8 @@ 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
+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
@@ -145,6 +242,23 @@ const response = await sdk.dataView.query("ticket_with_customer", {
 })
 ```
 
+Aggregate stats query:
+
+```ts
+const response = await sdk.dataView.stats("ticket_stats_by_customer", {
+  fields: ["customerName", "createdMonth", "ticketCount", "totalAmount"],
+  filters: [
+    { field: "customerName", operator: "contains", value: keyword },
+  ],
+  having: [
+    { field: "ticketCount", operator: ">", value: 0 },
+  ],
+  order: [{ field: "ticketCount", isAsc: "n" }],
+  currentPage: 1,
+  pageSize: 20,
+})
+```
+
 The response data is:
 
 ```ts
@@ -170,6 +284,15 @@ export default {
       defaultFilter: [
         { field: "ticketTitle", operator: "isNotEmpty" }
       ]
+    },
+    {
+      key: "ticketStats",
+      type: "dataView.stats",
+      code: "ticket_stats_by_customer",
+      fields: ["customerName", "ticketCount"],
+      defaultHaving: [
+        { field: "ticketCount", operator: ">", value: 0 }
+      ]
     }
   ]
 }
@@ -193,7 +316,8 @@ List page:
 
 Dashboard:
 
-- Use one or more data views as read-optimized sources.
+- 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.
 
@@ -206,6 +330,7 @@ Reusable lookup:
 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

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

@@ -1,6 +1,13 @@
 # Form Component Registry
 
-Use platform-supported component names in FormSchema.
+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:
 
@@ -26,9 +33,34 @@ Common field components:
 | `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.

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

@@ -6,7 +6,9 @@ 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.dataView.query` for published read-only multi-form row data views. Use `sdk.dataView.stats` for aggregate data views declared with `viewType: "aggregate"`.
+- Data view runtime queries can filter, sort, paginate, and select only output aliases.
+- Keep data view page calls paginated and field-scoped. Runtime filters/order should use aliases that the data view indexes, especially for aggregate dimensions and date buckets.
 - 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`.
@@ -32,6 +34,23 @@ const response = await sdk.dataView.query("ticket_with_customer", {
 })
 ```
 
+Data view stats:
+
+```ts
+const response = await sdk.dataView.stats("ticket_stats_by_customer", {
+  fields: ["customerName", "ticketCount", "totalAmount"],
+  filters: [
+    { field: "customerName", operator: "contains", value: keyword },
+  ],
+  having: [
+    { field: "ticketCount", operator: ">", value: 0 },
+  ],
+  order: [{ field: "ticketCount", isAsc: "n" }],
+  currentPage: 1,
+  pageSize: 20,
+})
+```
+
 Data view data source descriptor:
 
 ```ts
@@ -45,6 +64,15 @@ export default {
       defaultFilter: [
         { field: "ticketTitle", operator: "isNotEmpty" }
       ]
+    },
+    {
+      key: "ticketStats",
+      type: "dataView.stats",
+      code: "ticket_stats_by_customer",
+      fields: ["customerName", "ticketCount"],
+      defaultHaving: [
+        { field: "ticketCount", operator: ">", value: 0 }
+      ]
     }
   ]
 }
@@ -57,7 +85,7 @@ const response = await sdk.dataSource.run("tickets", {
 })
 ```
 
-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.
+Data view filters, having, and fields use output aliases such as `customerName` or `ticketCount`, 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.
 
 Logout and current-user role switching:
 

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -61,6 +61,14 @@ const data = await sdk.connector.call("crm.getCustomer", { body: { keyword } });
 
 ## 2. Data View — `src/resources/data-views/<code>.json`
 
+选择规则：
+
+- 多表只读联表列表 / lookup / 报表明细：用行级 data view，页面调用 `sdk.dataView.query`。
+- 固定口径统计 / 看板指标 / 图表数据源：用 `viewType: "aggregate"`，页面调用 `sdk.dataView.stats`。
+- ECharts 或自定义 dashboard 只负责展示；统计口径稳定时，数据源优先沉淀成 aggregate data view。
+- 发布前为常用筛选、排序、维度和时间桶声明 `indexes`，并确认刷新延迟是否能被业务接受。
+- 不用于单表 CRUD、简单 `linkedForm` 下拉、强实时、写回或临时 BI 查询。
+
 ```json
 {
   "code": "ticket_with_customer",
@@ -101,7 +109,35 @@ const list = await sdk.dataView.query("ticket_with_customer", {
 });
 ```
 
-适用：跨表只读联表 / 报表 / 大列表性能优化。**不适用**：单表 CRUD、`linkedForm` 下拉、强实时、写回。完整规则见 [`data-views.md`](data-views.md)。
+统计聚合视图：
+
+```json
+{
+  "code": "ticket_stats_by_customer",
+  "name": "Ticket Stats By Customer",
+  "viewType": "aggregate",
+  "base": { "formCode": "service_ticket", "alias": "ticket" },
+  "dimensions": [
+    { "field": "ticket.customer.value", "as": "customerId" },
+    { "field": "ticket.created_at", "as": "createdMonth", "bucket": "month" }
+  ],
+  "measures": [
+    { "type": "count", "as": "ticketCount" },
+    { "type": "sum", "field": "ticket.amount", "as": "totalAmount" }
+  ],
+  "having": { "field": "ticketCount", "op": ">", "value": 0 },
+  "indexes": [{ "fields": ["customerId", "createdMonth"] }]
+}
+```
+
+```ts
+const stats = await sdk.dataView.stats("ticket_stats_by_customer", {
+  fields: ["customerId", "createdMonth", "ticketCount", "totalAmount"],
+  having: [{ field: "ticketCount", op: ">", value: 0 }],
+});
+```
+
+性能要点：索引只能引用输出 alias；行级视图索引常用 filter/order 字段；聚合视图索引 dimensions/date buckets；`countDistinct` 和高基数维度刷新成本较高；低于 5 分钟的 scheduled refresh 需要用户明确确认时间敏感度。完整规则见 [`data-views.md`](data-views.md)。
 
 ## 3. Notification — `src/resources/notifications/<code>.json`
 

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

@@ -62,14 +62,14 @@ OPENXIANGDA_FEEDBACK_DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?acces
 OPENXIANGDA_FEEDBACK_DINGTALK_SECRET=SEC...
 ```
 
-When a user confirms that a suspected platform defect, bug, or optimization request should be reported, run:
+When a platform defect, missing capability, unclear design rule, repeated workaround, AI uncertainty, user-visible UX gap, bug, or optimization request appears during development, proactively report it:
 
 ```bash
 openxiangda feedback preview --profile <name> --summary "问题摘要" --description "..." --command "..." --log-file <file>
 openxiangda feedback submit --profile <name> --summary "问题摘要" --description "..." --command "..." --log-file <file> --yes
 ```
 
-Feedback includes the logged-in profile user name when available and detailed workspace/platform context. The CLI redacts tokens, cookies, secrets, phone numbers, and emails before sending.
+Prefer `feedback submit --yes` directly when the report is clear. Use `feedback preview` when robot env is missing, submission fails, or you need to capture a sanitized payload for the user. Feedback includes the logged-in profile user name when available and detailed workspace/platform context. The CLI redacts tokens, cookies, secrets, phone numbers, and emails before sending. After submission, tell the user what was reported and include the fingerprint.
 
 ## Private Routing
 

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

@@ -1,6 +1,6 @@
 ---
 name: openxiangda-form
-description: Create / edit / publish OpenXiangda normal forms and workflow forms in `sy-lowcode-app-workspace` — schema, fields, options, validation rules, layout, linkedForm select sources, hidden permission scope keys, top-level FormEffect, workflow form bundles, single-form publish. Trigger on 创建表单 / 新建表单 / 表单字段 / 修改 schema / form field / placeholder / options / SelectField / linkedForm / FormEffect / workflow form / 审批表单页 / form schema / formCode / src/forms, or any change to `src/forms/<code>/{schema.ts,page.tsx}`.
+description: Create / edit / publish OpenXiangda normal forms and workflow forms in `sy-lowcode-app-workspace` — schema, fields, options, validation rules, layout, linkedForm select sources, hidden permission scope keys, top-level FormEffect, workflow form bundles, single-form publish, and high-quality form-entry UX. Use OpenXiangda platform form components first, Ant Design / antd-mobile wrappers second, and never raw native HTML form controls in AI-authored app code. Trigger on 创建表单 / 新建表单 / 表单字段 / 表单录入 / 修改 schema / form field / placeholder / options / SelectField / linkedForm / FormEffect / workflow form / 审批表单页 / form schema / formCode / src/forms, or any change to `src/forms/<code>/{schema.ts,page.tsx}`.
 ---
 
 # OpenXiangda Form
@@ -35,12 +35,15 @@ openxiangda workspace publish --profile <name> --form <formCode>
 - ✅ Use `SelectField` / `RadioField` for enums; for cross-form sources use `SelectField` with `optionSource.type: "linkedForm"` (and `remoteSearch: true` + `searchFieldId` when source is large).
 - ✅ Permission scope keys / sync keys / derived fields stay in schema with `behavior: "HIDDEN"`, derived from visible select/person/department fields via `valueSync`.
 - ✅ Always provide `options` for option components (Select / MultiSelect / Radio / Checkbox / CascadeSelect).
+- ✅ `schema.ts` is the source of data fields and platform field components; `page.tsx` is presentation only and should render through the OpenXiangda standard form/runtime.
+- ✅ If a custom layout or widget is truly needed, wrap OpenXiangda platform components first. If no platform component exists, wrap `antd` / `antd-mobile` and preserve their props, refs, keyboard behavior, and overlay handling.
 - ❌ `AssociationFormField` for new form work (use `linkedForm` SelectField).
 - ❌ Top-level `schema.rules` as validation array. Top-level `rules` is `FormEffect[]` only (`when` / `then`).
 - ❌ Extra fields for system metadata (creator / updater / created/updated time / depts) — platform creates them automatically.
 - ❌ Developer notes / implementation comments inside labels / placeholders / tips / section titles / empty states.
 - ❌ `openxiangda form create` as page generation; it is a low-level repair command.
 - ❌ Copy `formUuid` from dev to prod — each profile has its own `formUuid` under `.openxiangda/state.json`.
+- ❌ Raw native form controls in app/workspace source: `<input>`, `<select>`, `<textarea>`, `<input type="file">`, hand-written pickers, hand-written uploaders, and custom employee/department selectors. These belong only inside OpenXiangda SDK/platform component internals.
 
 ## Required Workspace Flow
 
@@ -103,7 +106,7 @@ Read these references only when writing or reviewing schema:
 - `../../references/forms/component-registry.md`
 - `../../references/forms/layout-and-rules.md`
 - `../../references/platform-data-model.md` — how each field type is persisted (JSONB, `{label, value}` for option fields, attachment shape). Consult before designing schema or wiring values.
-- `../../references/component-guide.md` — when to pick platform form components vs. custom widgets, and the option-component rules.
+- `../../references/component-guide.md` — platform component first, `antd` / `antd-mobile` fallback, and native-control ban for AI-authored app code.
 - `../../references/best-practices.md` — status lifecycle fields, ownership redundancy, role-governance fields, and the boundary between normal forms and workflow forms.
 
 ## Rules
@@ -122,8 +125,12 @@ Read these references only when writing or reviewing schema:
 - 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.
 - In `schema.ts`, import `defineFormSchema` from `openxiangda` and default-export the schema.
+- Treat `schema.ts` as the field/component contract. Prefer platform field components listed in `../../references/forms/component-registry.md`; do not replace them with raw JSX controls in `page.tsx`.
+- Keep `page.tsx` presentation-only. It may customize layout, wrappers, sections, or routing, but should render a complete OpenXiangda standard form/runtime rather than assembling isolated raw controls.
+- If a platform field is missing for a real business need, submit feedback with `openxiangda feedback submit --yes` and then use an `antd` / `antd-mobile` wrapper as a local workaround. Report the workaround and fingerprint to the user.
 - Put validation on field-level `rules`; never generate old top-level validation arrays under `schema.rules`. Top-level `rules` is only for `FormEffect[]` with `when` and `then`.
 - Always provide `options` for option components. `SelectField`, `MultiSelectField`, `RadioField`, `CheckboxField`, and `CascadeSelectField` must not be emitted with `options` undefined. See `../../references/component-guide.md` for the full list and `../../references/platform-data-model.md` for the `{label, value}` storage contract.
+- Do not emit raw native form controls in app/workspace source. For basic entry use `TextField`, `TextAreaField`, `NumberField`, `DateField`, `SelectField`, `RadioField`, etc.; for platform-specific entry use `UserSelectField`, `DepartmentSelectField`, `AttachmentField`, `ImageField`, `EditorField`, `DigitalSignatureField`, and `LocationField`.
 - Workflow form pages use the same workspace form structure plus workflow v3 configuration; publish the form page bundle through workspace publish before treating it as complete.
 - After editing one form, use `workspace publish --form <formCode>` or preview `--changed --dry-run`; do not run full workspace publish by default.
 - Use `openxiangda form pull` or app snapshot before overwriting an existing form.

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

@@ -1,6 +1,6 @@
 ---
 name: openxiangda-page
-description: Build / edit / publish OpenXiangda custom code pages in `sy-lowcode-app-workspace/src/pages/<pageCode>/` using React + Ant Design + `openxiangda/runtime`. Covers app-shell portals, dashboards, workbenches, data-management lists, mobile portals, page-level connector calls, and single-page publish. Trigger on 创建页面 / 新建页面 / 修改页面 / portal / dashboard / 看板 / 驾驶舱 / 工作台 / 列表页 / mobile portal / app-shell / page.config.ts / pageCode / src/pages, JSX / React / Ant Design page work in this workspace, or any change to `src/pages/<code>/`.
+description: Build / edit / publish OpenXiangda custom code pages in `sy-lowcode-app-workspace/src/pages/<pageCode>/` using React + Ant Design + `openxiangda/runtime`. Covers app-shell portals, dashboards, workbenches, data-management lists, mobile portals, page-level connector calls, filters/search forms, and single-page publish. For platform data entry use OpenXiangda components first, Ant Design / antd-mobile wrappers second, and no raw native HTML form controls in AI-authored page code. Trigger on 创建页面 / 新建页面 / 修改页面 / portal / dashboard / 看板 / 驾驶舱 / 工作台 / 列表页 / mobile portal / app-shell / page.config.ts / pageCode / src/pages, JSX / React / Ant Design page work in this workspace, or any change to `src/pages/<code>/`.
 ---
 
 # OpenXiangda Page
@@ -33,10 +33,12 @@ openxiangda workspace publish --profile <name> --page <pageCode>
 - ✅ Default to **native Tailwind utilities** for new pages (`bg-white`, `border-slate-200`, `grid-cols-[240px_1fr]`, ...) and `cssIsolation: "none"`. Keep namespace/shadow only for explicit legacy compatibility.
 - ✅ Split complex pages into `domain/`, `shared/services/`, `shared/hooks/`, `components/`, route/config files, `styles.css` (see `references/best-practices.md` and `references/architecture-patterns.md`).
 - ✅ List/detail/CRUD pages: follow `DataManagementList` pattern from `references/architecture-patterns.md`. Pagination + structured `filterGroup` + `OR`. Never fetch huge `pageSize` and filter in browser.
-- ✅ For external APIs use `src/resources/connectors/<code>.json` + `sdk.connector.invoke()`; for joined read-only queries use `src/resources/data-views/<code>.json`.
+- ✅ For external APIs use `src/resources/connectors/<code>.json` + `sdk.connector.invoke()`; for joined read-only lists use row data views + `sdk.dataView.query`; for stable dashboard metrics use aggregate data views + `sdk.dataView.stats`.
+- ✅ Filters, search bars, modal forms, drawers, and inline edits use platform components for platform data fields, otherwise `antd` / `antd-mobile` controls.
 - ❌ Single-file giant pages. Split per `references/best-practices.md`.
 - ❌ Hardcoded `/view/...&isRenderNav=false` URLs scattered through page code; use the runtime navigation helper.
 - ❌ shadcn token classes like `bg-card` / `text-muted-foreground` / `text-foreground` unless explicitly configured.
+- ❌ Raw native form controls in AI-authored page code (`<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers/uploaders). Use platform components or `antd` / `antd-mobile`.
 - ❌ Embed a single `FormProvider` field component temporarily; navigate to a full standard form page or render a complete `StandardFormPage` instead.
 - ❌ Reuse one form UI for both PC and mobile without verifying overlay / picker / bottom-sheet behavior on both viewports.
 - ❌ Hardcode notification or platform API URLs; use `openxiangda/runtime` and `src/resources/notifications/` declarations.
@@ -96,7 +98,7 @@ Read these references only when editing page code:
 - `../../references/pages/publish-flow.md`
 - `../../references/style-system.md` — style isolation defaults, Tailwind/CSS guidance, and legacy namespace compatibility. Read before writing substantial page CSS or Tailwind classes.
 - `../../references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, and recommended `src/pages/<pageCode>/` layout. Read before scaffolding a new page or list view.
-- `../../references/component-guide.md` — when to pick platform components, raw Ant Design, or custom components. Read before introducing a new component.
+- `../../references/component-guide.md` — platform component first, `antd` / `antd-mobile` fallback, and native-control ban for AI-authored app code. Read before introducing a new component.
 - `../../references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and their fixes. Read when something does not behave as expected.
 
 ## Rules
@@ -120,7 +122,7 @@ Read these references only when editing page code:
 - Follow the style system in `../../references/style-system.md`: default to native Tailwind utilities and arbitrary values for business pages (`bg-white`, `border`, `border-slate-200`, `text-slate-600`, `grid-cols-[240px_1fr]`, etc.). New pages default to `cssIsolation: "none"` and do not need `.sy-app-workspace`; keep namespace/shadow handling only for legacy pages that explicitly configure it. Do not treat platform token classes as the default authoring pattern, and do not use shadcn token classes such as `bg-card`, `text-muted-foreground`, or `text-foreground` unless the workspace explicitly configures them.
 - For list / detail / CRUD pages, follow `../../references/architecture-patterns.md` (e.g. `DataManagementList`) before writing custom data-fetching loops.
 - Query pages must use pagination with structured conditions. Do not fetch a large `pageSize` and filter in the browser; avoid default `searchKeyWord`, and build multi-field fuzzy search with explicit `filterGroup` + `OR`.
-- Pick components per `../../references/component-guide.md`: prefer the platform component, fall back to Ant Design, and only build a custom component when neither fits.
+- Pick components per `../../references/component-guide.md`: prefer the platform component, fall back to Ant Design / antd-mobile wrappers, and only build a custom component when neither fits. In app/workspace page code, do not emit raw `<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers, or hand-written uploaders.
 - When a page misbehaves (lost styles, `options is undefined`, option labels showing raw values, etc.), consult `../../references/troubleshooting.md` before patching symptoms.
 - For custom portal pages and business modals, do not temporarily embed a single `FormProvider` field component from the standard form runtime. If a standard component is required, navigate to a full standard form page or render a complete `StandardFormPage` inside a dedicated carrier route.
 - Keep PC and mobile portal styles separate. Do not share one form UI implementation across both viewports unless the surrounding shell, modal layer, date picker, and bottom-sheet behavior have been tested in both contexts.

package/package.json

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