openxiangda 1.0.34 → 1.0.36

package/openxiangda-skills/references/best-practices.md

@@ -43,7 +43,7 @@ Use a normal form plus:
 
 - a `status` field
 - user-facing responsibility fields such as personnel, department, enum, or
-  association fields
+  SDK-backed select fields
 - hidden permission scope keys, when form permission groups require scalar
   matching
 - an action log form
@@ -109,7 +109,11 @@ For apps with dynamic roles:
    - personnel and departments use platform personnel/department fields
    - enum scopes use `SelectField` / `RadioField` with `options`
    - class, college, project, customer, and similar maintained records use
-     `AssociationFormField`
+     `SelectField` with `optionSource.type: "linkedForm"` so the runtime queries
+     source form records through the SDK and builds dropdown options
+   - when the source form can have many records, set `remoteSearch: true`,
+     `searchFieldId`, and a reasonable `pageSize` so typing in the dropdown
+     triggers remote search
 4. Add hidden derived scope keys only when platform form permission conditions
    require scalar matching, for example:
    - `collegeScopeKey`
@@ -129,12 +133,13 @@ groups or backend-side JS_CODE checks.
 - Every visible form field should have a short, user-facing placeholder.
 - Do not add tips to every field. Tips are only for special constraints,
   unusual formats, compliance notes, or non-obvious business rules.
-- Use select/radio controls for enums and association controls for values
-  maintained by other forms. Do not ask users to type raw IDs.
+- Use select/radio controls for enums. For values maintained by other forms, use
+  `SelectField` with SDK-backed `optionSource` options. Do not ask users to type
+  raw IDs.
 - Hide permission scope keys, computed, sync, and developer/internal fields with
   `behavior: "HIDDEN"` when they must exist in the schema. Scope keys should be
-  derived from visible select/association/person/department fields, not typed by
-  users.
+  derived from visible select/person/department fields, not typed by
+  users. For select-derived scalar keys, use `valueSync`.
 - Do not add separate creator, updater, creator department, updater department,
   created time, or updated time fields unless the user explicitly needs a
   separate business field. The platform creates system metadata for every form.

package/openxiangda-skills/references/component-guide.md

@@ -102,19 +102,18 @@ export function CustomSelect({ options, className, ...rest }: CustomSelectProps)
   return (
     <Select
       className={clsx('w-full rounded-md', className)}
-      popupClassName="sy-app-workspace"
-      getPopupContainer={(trigger) => trigger.parentElement ?? document.body}
-      options={options}
-      {...rest}
+      getPopupContainer={(trigger) => trigger.parentElement ?? document.body}
+      options={options}
+      {...rest}
     />
   );
 }
 ```
 
-要点：
-- 透传 `...rest`，保留 antd 全部 API。
-- `popupClassName="sy-app-workspace"` 确保弹层应用平台样式作用域。
-- `getPopupContainer` 解决弹层被裁切问题（详见第 7 节常见错误）。
+要点：
+- 透传 `...rest`，保留 antd 全部 API。
+- `getPopupContainer` 解决弹层被裁切问题（详见第 7 节常见错误）。
+- 默认 `cssIsolation: "none"` 时不要额外给弹层加 `sy-app-workspace`；只有 legacy `namespace/shadow` 页面才需要给弹层或容器补 namespace class。
 - 使用 `w-full`、`rounded-md`、`text-slate-600`、`border-slate-200` 等 Tailwind 原生类作为默认基线；如果组件视觉需要精调，可以继续使用 Tailwind 任意值或局部 CSS。
 
 ### 4.2 错误：从头实现选择器
@@ -171,7 +170,7 @@ function BadSelect({ options }) {
    </ConfigProvider>
    ```
 
-4. **谨慎**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）属于私有 API，升级风险较高。确实需要时必须限定在页面根类或 `.sy-app-workspace` 下，并优先考虑 `ConfigProvider`、`className`、组件 props 或 CSS 变量是否能解决。
+4. **谨慎**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）属于私有 API，升级风险较高。确实需要时必须限定在页面根类下；legacy 页面也可以兼容限定在 `.sy-app-workspace` 下。优先考虑 `ConfigProvider`、`className`、组件 props 或 CSS 变量是否能解决。
 
 ---
 
@@ -208,7 +207,7 @@ export function ActionButton(props) {
 | 用第三方富文本（TinyMCE 等） | 用 `EditorField` |
 | 自己写列表 + 分页 + 导出 | 用 `DataManagementList` |
 | 常规组件大量写 `style={{ color: '#333', padding: 16 }}` | 优先 Tailwind 原生工具类、任意值或局部 CSS；动态值和少量精调 inline style 可接受 |
-| Select / Date / Modal 弹层错位、被滚动容器裁切 | 加 `getPopupContainer={(trigger) => trigger.parentElement}`，并在弹层 `popupClassName` 上加 `sy-app-workspace` |
+| Select / Date / Modal 弹层错位、被滚动容器裁切 | 默认加 `getPopupContainer={(trigger) => trigger.parentElement}`；legacy `namespace/shadow` 页面才额外使用 `sy-app-workspace` |
 | 不分端，PC 组件直接放移动端 | 按端拆页 + 端内用对应 UI 库 |
 | 无作用域覆盖 `.ant-xxx` 内部 class | 优先用 `className`、CSS 变量或 `ConfigProvider` 主题；必要覆盖时限定到页面命名空间 |
 | 在自定义组件中不透传 `...rest` / `ref` | 透传 props 与 `forwardRef`，保留底层组件全部能力 |
@@ -220,5 +219,5 @@ export function ActionButton(props) {
 - [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
 - [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
 - [ ] 样式 → 默认用 Tailwind 原生类 / 任意值 / 局部 CSS；平台 token 只在主题兼容或平台组件需要时使用，且作用域收敛？
-- [ ] 弹层 → 设置了 `getPopupContainer` 与 `sy-app-workspace` 弹层样式作用域？
+- [ ] 弹层 → 默认使用正常容器；只有 legacy 隔离页面才额外设置 `sy-app-workspace` 样式作用域？
 - [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？

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/style-system.md

@@ -9,8 +9,9 @@
 1. **业务页面默认写原生 Tailwind**：优先使用 `bg-white`、`border`、`border-slate-200`、`text-slate-600`、`shadow-sm`、`rounded-lg`、`p-4`、`gap-4`、`grid-cols-[240px_1fr]` 这类 Tailwind 原生类和任意值。
 2. **不要强制平台 token**：不要把 `bg-container`、`text-secondary`、`rounded-form`、`shadow-card` 当默认示例或默认范式。历史项目或平台组件需要时可以兼容使用，但新业务页面不推荐主动依赖。
 3. **不要直接套 shadcn token**：`bg-card`、`text-muted-foreground`、`text-foreground`、`bg-background` 等不是 Tailwind 原生类。除非项目已经在 `tailwind.config.cjs` 明确配置这些 token，否则必须改成 Tailwind 原生类或任意值。
-4. **保留 OpenXiangda 隔离能力**：Tailwind 仍通过 `.sy-app-workspace` namespace 输出，workspace 仍扫描 `openxiangda` 包内容，平台组件 safelist 仍保留。
-5. **CSS 作用域要收敛**：页面级 CSS 写在 `styles.css`，选择器限定在 `.sy-app-workspace` 或页面根类下，避免污染宿主平台。
+4. **默认不启用样式隔离**：新发布页面默认 `cssIsolation: "none"`，Tailwind 类按原样输出，不需要 `.sy-app-workspace` 前缀即可生效。
+5. **legacy 隔离仅用于兼容**：历史页面或显式配置 `cssIsolation: "namespace" | "shadow"` 时，runtime 仍会保留 `.sy-app-workspace`、legacy portal 和旧样式前缀。
+6. **CSS 作用域要收敛**：页面级 CSS 写在 `styles.css`，选择器优先限定在页面根类下，避免无意覆盖宿主平台或其他页面。
 
 ---
 
@@ -60,12 +61,12 @@ export function DashboardPage() {
 ### 2.4 局部 CSS
 
 ```css
-.sy-app-workspace .queue-booking-page {
+.queue-booking-page {
   min-height: 100%;
   background: #f8fafc;
 }
 
-.sy-app-workspace .queue-booking-page__calendar-grid {
+.queue-booking-page .queue-booking-page__calendar-grid {
   display: grid;
   grid-template-columns: repeat(7, minmax(120px, 1fr));
   gap: 12px;
@@ -113,11 +114,11 @@ module.exports = {
 
 这个配置的作用：
 
-- `openxiangdaPreset` 保留 `.sy-app-workspace` namespace、平台组件 safelist 和平台组件需要的工具类。
+- `openxiangdaPreset` 保留平台组件 safelist、平台 token 兼容类和平台组件需要的工具类；不再强制 Tailwind 输出 `.sy-app-workspace` 前缀。
 - `...openxiangdaContent` 确保平台组件内部 class 会被 Tailwind 扫描到。
 - `blocklist` 避免 Tailwind 误生成日期字符串相关的异常类。
 
-不要为了“更自由”移除这些平台构建能力；自由写 Tailwind 原生类和保留构建隔离能力并不冲突。
+不要移除这些平台构建能力；自由写 Tailwind 原生类和保留平台组件兼容能力并不冲突。
 
 ---
 
@@ -160,21 +161,15 @@ body {
 
 ## 5. Ant Design 和弹层
 
-PC 控件优先用 `antd`，移动端控件优先用 `antd-mobile`。弹层必须挂到当前页面容器或 `.sy-app-workspace` 内，避免宿主平台污染或滚动容器裁切：
+PC 控件优先用 `antd`，移动端控件优先用 `antd-mobile`。默认 `cssIsolation: "none"` 时使用 Ant Design 默认 `ant` class 和 `document.body` 弹层容器即可；只有 legacy `namespace/shadow` 页面才需要显式挂到当前隔离容器：
 
 ```tsx
-<ConfigProvider
-  getPopupContainer={(trigger) =>
-    trigger?.closest('.sy-app-workspace') ??
-    (document.querySelector('.sy-app-workspace') as HTMLElement) ??
-    document.body
-  }
->
+<ConfigProvider>
   <App />
 </ConfigProvider>
 ```
 
-局部组件也可以使用 `getPopupContainer={(trigger) => trigger.parentElement ?? document.body}`。不要无作用域覆盖 `.ant-select-selector`、`.ant-modal` 等私有 class；确实需要覆盖时限定在页面根类下。
+legacy 页面可使用 `getPopupContainer={(trigger) => trigger?.closest(".sy-app-workspace") ?? document.body}`。不要无作用域覆盖 `.ant-select-selector`、`.ant-modal` 等私有 class；确实需要覆盖时限定在页面根类下。
 
 ---
 
@@ -188,9 +183,10 @@ OpenXiangda 仍保留部分平台语义类和 CSS 变量，主要用于：
 
 常见兼容类包括 `text-primary`、`text-secondary`、`bg-container`、`bg-layout`、`border-secondary`、`rounded-form`、`shadow-card` 等。AI 编写新业务页面时不要默认使用这些类；除非用户明确要求跟随平台变量主题，或当前项目已有一致的 token 体系。
 
-如果需要统一主题，推荐把主题限制在 `.sy-app-workspace` 或应用根类下：
+如果需要统一主题，推荐把主题限制在应用根类下；兼容旧页面时也可以同时声明 `.sy-app-workspace`：
 
 ```css
+.theme-brand,
 .sy-app-workspace.theme-brand {
   --sy-color-primary: #0f766e;
   --sy-radius-md: 8px;
@@ -218,5 +214,5 @@ warning 不会阻断构建，但它通常意味着页面会出现“颜色、边
 - [ ] 页面样式默认使用 Tailwind 原生类和任意值，而不是平台 token 类？
 - [ ] 没有使用未配置的 shadcn token 类，例如 `bg-card`、`text-muted-foreground`、`text-foreground`？
 - [ ] `tailwind.config.cjs` 保留 OpenXiangda preset、content 扫描和 blocklist？
-- [ ] 业务 CSS 限定在 `.sy-app-workspace` 或页面根类下？
-- [ ] antd / antd-mobile 弹层设置了合适的挂载容器？
+- [ ] 业务 CSS 限定在页面根类下，而不是全局裸覆盖？
+- [ ] 只有 legacy `namespace/shadow` 页面才额外配置 `.sy-app-workspace` 弹层容器？

package/openxiangda-skills/references/troubleshooting.md

@@ -23,18 +23,18 @@
 
 **症状**：Select / Dropdown / Popup / Modal 等组件的弹出层没有样式，直接跑到屏幕外，或呈现为无样式的裸 HTML。
 
-**根因**：当页面启用了 Shadow DOM 样式隔离（`cssIsolation: "shadow"`）时，antd 组件的弹出层默认会渲染到 `document.body`，从而脱离 Shadow DOM 的样式作用域；即使未使用 Shadow DOM，如果没有正确配置弹层容器，antd-mobile 的 Popup 也可能因 namespace 未被继承而失去样式。
-
-**解决方案**：
-1. 推荐使用 CSS Namespace 隔离（`cssIsolation: "namespace"`）替代 Shadow DOM。
-2. 为 antd `ConfigProvider` 配置 `getPopupContainer` 指向页面根容器。
-3. 对于 antd-mobile，确保 `Popup` / `Modal` 的 `getContainer` 指向正确容器。
-4. 确保弹层的 `className` 中包含 namespace class（如 `sy-app-workspace`）。
-
-**示例**：
-```tsx
-import { useRef } from 'react';
-import { ConfigProvider } from 'antd';
+**根因**：新页面默认 `cssIsolation: "none"`，弹层使用 `document.body` 和默认 Ant Design 样式即可。只有历史页面显式启用 `cssIsolation: "namespace" | "shadow"` 时，弹层渲染到 `document.body` 才可能脱离 legacy 样式作用域；移动端 Popup 也可能因 namespace 未被继承而失去样式。
+
+**解决方案**：
+1. 新页面优先保持 `cssIsolation: "none"`，不要为了修弹层问题手动加 `.sy-app-workspace`。
+2. legacy `shadow` 页面优先迁移为 `none`；无法迁移时可使用 `namespace` 兼容模式。
+3. legacy 页面为 antd `ConfigProvider` 配置 `getPopupContainer` 指向页面根容器。
+4. 对于 legacy antd-mobile 页面，确保 `Popup` / `Modal` 的 `getContainer` 指向正确容器，并按需补 namespace class。
+
+**legacy 示例**：
+```tsx
+import { useRef } from 'react';
+import { ConfigProvider } from 'antd';
 
 const rootRef = useRef<HTMLDivElement>(null);
 
@@ -188,7 +188,7 @@ export default defineConfig({
 **解决方案**：
 1. 在 `vite.config.ts` 的 `optimizeDeps.include` 中显式添加 `antd-mobile`，避免运行时多次预构建。
 2. 调整 Tailwind preflight 策略，确保不会覆盖 antd-mobile 的基础样式（必要时关闭 preflight 或使用 `important` 选择器）。
-3. 确保 antd-mobile 组件渲染在 `sy-app-workspace` namespace 容器内，弹层 `getContainer` 指向该容器。
+3. 仅 legacy `namespace/shadow` 页面需要确保 antd-mobile 组件渲染在 `sy-app-workspace` namespace 容器内，弹层 `getContainer` 指向该容器；新页面默认不需要。
 
 **示例**：
 ```typescript

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.