openxiangda 1.0.33 → 1.0.35

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

@@ -42,8 +42,10 @@ Most business processes are status lifecycles, not approval workflows.
 Use a normal form plus:
 
 - a `status` field
-- responsibility fields such as `ownerUserId`, `ownerDeptId`, `collegeId`,
-  `classId`
+- user-facing responsibility fields such as personnel, department, enum, or
+  SDK-backed select fields
+- hidden permission scope keys, when form permission groups require scalar
+  matching
 - an action log form
 - a pure state machine in `domain/<feature>/state-machine.ts`
 - a service method that changes status and writes the log in one path
@@ -103,20 +105,48 @@ For apps with dynamic roles:
 
 1. Create an app role maintenance form, such as `app-role`.
 2. Use automation / JS_CODE to sync role records to platform roles.
-3. Add redundant ownership fields to business forms, for example:
-   - `collegeId`
-   - `classId`
-   - `ownerDeptId`
-   - `ownerUserId`
-   - `roleCode`
-4. Create page permission groups for entry visibility.
-5. Create form permission groups with condition-based data permissions for real
+3. Model visible scope fields with maintainable controls:
+   - personnel and departments use platform personnel/department fields
+   - enum scopes use `SelectField` / `RadioField` with `options`
+   - class, college, project, customer, and similar maintained records use
+     `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`
+   - `classScopeKey`
+   - `ownerDeptScopeKey`
+   - `ownerUserScopeKey`
+5. Create page permission groups for entry visibility.
+6. Create form permission groups with condition-based data permissions for real
    data isolation.
 
 Frontend button hiding is only user experience. It is not permission control.
 Every sensitive action must still be protected by platform role/form permission
 groups or backend-side JS_CODE checks.
 
+## Form Copy And Field Visibility
+
+- 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. 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/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.
+- All visible copy must be written for end users. Do not put implementation
+  notes, schema descriptions, or development explanations in sections, cards,
+  labels, tips, helper text, or empty states.
+
 ## Query Performance
 
 - Always use paginated APIs with `currentPage`, `pageSize`, sort, and structured
@@ -166,8 +196,8 @@ groups or backend-side JS_CODE checks.
 - `service-ticket-ops`: custom data management page based on
   `DataManagementList`, split into page, components, hook, query builder, and
   detail drawer.
-- `role-governance`: role maintenance form, role sync JS_CODE, redundant
-  ownership fields, and permission-group resource examples.
+- `role-governance`: role maintenance form, role sync JS_CODE, maintainable
+  scope fields, hidden permission keys, and permission-group resource examples.
 - `pc-portal-shell`: app-shell PC portal with routes, modules, components, and
   services.
 - `mobile-portal-shell`: app-shell mobile portal with mobile-only components

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,7 +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 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

@@ -35,6 +35,7 @@ export default defineFormSchema({
       fieldId: "customer_type",
       componentName: "SelectField",
       label: "客户类型",
+      placeholder: "请选择客户类型",
       options: [
         { value: "enterprise", label: "企业客户" },
         { value: "individual", label: "个人客户" },
@@ -55,11 +56,47 @@ export default defineFormSchema({
 
 - 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`:

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/pages/workspace-structure.md

@@ -38,3 +38,4 @@ Rules:
 - Shared components can live under `src/components/` when reused.
 - Build artifacts under `dist/` are generated and should not be hand edited.
 - Publish through `openxiangda workspace publish --profile <name>`.
+- Visible page copy must be written for end users. Do not show implementation notes, schema explanations, or developer-only guidance inside page sections, cards, alerts, tooltips, or empty states.

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

@@ -74,8 +74,15 @@ Read these references only when writing or reviewing schema:
 ## Rules
 
 - Prefer deterministic `formCode` as local key; bind live `formUuid` under the active profile.
+- 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.
+- 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, add redundant ownership fields such as `collegeId`, `classId`, `ownerDeptId`, and `ownerUserId` at schema time so form permission groups can use structured conditions later.
+- 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-page/SKILL.md

@@ -71,6 +71,7 @@ Read these references only when editing page code:
 - Formal user-facing entries such as admin consoles, PC portals, and mobile portals must be app-shell code pages. Declare `entry: { mode: "app-shell", hidePlatformNav: true, defaultRoute: "<home-route>" }` in `page.config.ts`.
 - Do not generate single-file large pages. Split complex code pages into `domain/`, `shared/services/`, `shared/hooks/`, shared/page-local `components/`, route/config files, and `styles.css` as described in `../../references/best-practices.md`.
 - Keep view code thin. Page components call hooks/services; business rules, state transition rules, permission predicates, and query builders live outside TSX and are reusable by PC and mobile pages.
+- All visible page copy must be end-user-facing business text. Do not put developer explanations, implementation notes, schema descriptions, or "this module is generated by..." text into sections, cards, alerts, empty states, tooltips, or helper copy.
 - Store live `pageId`, `routeKey`, and `legacyFormUuid` under the current profile only.
 - Use `openxiangda/runtime` for platform data access instead of hardcoding backend URLs in page code.
 - For reminders, alerts, and business messages, declare `src/resources/notifications/` first and call `sdk.notification`; do not hardcode notification API URLs.

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, sync it to platform roles with automation / JS_CODE, and add redundant ownership fields to business forms (`collegeId`, `classId`, `ownerDeptId`, `ownerUserId`, `roleCode`). 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.33",
+  "version": "1.0.35",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {