openxiangda 1.0.33 → 1.0.34

package/openxiangda-skills/SKILL.md

@@ -84,6 +84,11 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - Never store token data in the project directory. User tokens live in `~/.openxiangda/profiles.json`; project state lives in `.openxiangda/state.json` and stores only IDs and mappings.
 - Shared workspace env values such as `APP_OSS_*` should live in `~/.openxiangda/.env` by default. Project `.env` files are only per-workspace overrides.
 - For suspected platform defects, bugs, or product optimization requests, ask the user to confirm first, then use `openxiangda feedback preview` and `openxiangda feedback submit --yes` to send a detailed DingTalk robot report. Include the command, error, relevant files, and logs/context files when available. The CLI redacts tokens, cookies, secrets, phone numbers, and emails before sending.
+- For form pages, every visible field should have a concise user-facing `placeholder`. Use `tips` only for special constraints or non-obvious business rules; do not add tips to every field.
+- Form pages should display only fields the user needs to see. Use `SelectField` / `RadioField` for enums and `AssociationFormField` for data maintained by another form, such as class, college, customer, or project. Do not make users maintain raw ID text fields.
+- Permission scope keys, computed fields, sync fields, and developer/internal fields should be present only when needed for permissions or logic, and should normally be derived from a visible select/association field and marked `behavior: "HIDDEN"`.
+- Do not add extra fields for platform system metadata such as creator, updater, creator department, updater department, created time, or updated time unless the user explicitly needs a separate business field; the platform already creates system fields for each form.
+- All visible copy in forms and pages must be written for end users. Do not put implementation notes, developer explanations, schema descriptions, or "this area is generated by..." text into page sections, cards, labels, tips, or empty states.
 - Use logical resource codes in local files. Platform-specific IDs such as `formUuid`, `pageId`, `workflowId`, and `automationId` must be isolated by profile.
 - Put engineering-managed resources in `src/resources/` and use `openxiangda resource validate|plan|publish|pull`. `workspace publish` publishes workspace forms/pages first, then runs non-destructive resource upsert. Only pass `--prune` when the user explicitly wants local manifests to delete platform-side extras.
 - For external APIs, create a connector manifest in `src/resources/connectors/` and call it from pages through `sdk.connector`; never put third-party API keys in page source.

package/openxiangda-skills/references/architecture-patterns.md

@@ -155,8 +155,8 @@ export default function InstrumentListPage() {
 
 ### 4.1 状态流转不是审批流
 
-- 普通业务流转默认使用普通表单：`status` 字段、责任人/归属冗余字段、操作日志表、domain 状态机、service 统一提交。
-- 每次状态变更都由 service 完成，统一写操作日志并更新责任人、归属、更新时间等冗余字段。
+- 普通业务流转默认使用普通表单：`status` 字段、可维护的责任人/归属字段、必要的隐藏权限键、操作日志表、domain 状态机、service 统一提交。
+- 每次状态变更都由 service 完成，统一写操作日志并更新责任人、归属、更新时间和隐藏权限键等派生字段。
 - workflow 只用于真实审批：审批人、审批任务、同意/驳回、审批意见、节点权限、流程记录明确存在的场景。
 - 不要把「待处理 / 处理中 / 已完成 / 已关闭」这类状态流转建成流程表单。
 

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
+  association 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,43 @@ 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
+     `AssociationFormField`
+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 and association controls for values
+  maintained by other forms. 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.
+- 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 +191,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/forms/component-registry.md

@@ -36,6 +36,7 @@ Rules:
 - 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.
 - 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,6 +56,13 @@ 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 `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"`.
+- 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`.

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/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.
+- 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.
+- 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, 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 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 `AssociationFormField` for records maintained by other forms. If form permission groups need scalar matching, derive hidden keys such as `collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, `ownerUserScopeKey`, and `roleCode`; do not expose raw ID text fields to users. Use page permission groups for entry visibility and form permission groups with condition-based data permissions for real data isolation.
 
 ## Page Permission Groups
 

package/package.json

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

package/templates/sy-lowcode-app-workspace/examples/best-practices/catalog.json

@@ -25,7 +25,7 @@
       "code": "role-governance",
       "type": "permissions",
       "path": "src/domain/role-governance",
-      "description": "Dynamic role maintenance, role sync, redundant ownership fields, and permission-group resource examples."
+      "description": "Dynamic role maintenance, role sync, maintainable scope fields, hidden permission keys, and permission-group resource examples."
     },
     {
       "code": "pc-portal-shell",

package/templates/sy-lowcode-app-workspace/examples/best-practices/decision-guide.md

@@ -20,9 +20,10 @@ Most business "processes" are lifecycle state changes:
 - orders: draft -> submitted -> paid -> fulfilled -> completed
 - assets: available -> reserved -> in_use -> maintenance -> retired
 
-Use a normal form with a `status` field, ownership fields, and an operation-log
-form. Define allowed transitions in `domain/<feature>/state-machine.ts`, and
-execute changes through a service method that updates state and writes logs.
+Use a normal form with a `status` field, maintainable ownership/scope fields,
+and an operation-log form. Define allowed transitions in
+`domain/<feature>/state-machine.ts`, and execute changes through a service
+method that updates state and writes logs.
 
 Use workflow only when the platform must create approval tasks with approvers,
 approval comments, agree/reject actions, copy nodes, node field permissions, and
@@ -39,6 +40,10 @@ Frontend code must not be responsible for data isolation or background jobs.
 ## Permissions
 
 For dynamic multi-role apps, create a business role table and synchronize it to
-platform app roles. Add redundant ownership fields to business forms, such as
-`collegeId`, `classId`, `ownerDeptId`, and `ownerUserId`. Use form permission
-groups with condition-style data permissions to enforce data isolation.
+platform app roles. User-facing scope fields should be maintainable controls:
+personnel/department fields for people and orgs, enum fields for fixed option
+sets, and association fields for classes, colleges, projects, customers, and
+other records maintained by forms. If the platform permission condition needs a
+scalar value, derive a hidden scope key such as `collegeScopeKey` or
+`ownerDeptScopeKey`. Use form permission groups with condition-style data
+permissions to enforce data isolation.

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/role-governance/permissions.test.ts

@@ -1,7 +1,11 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 
-import { buildConditionDataPermission, buildRoleCode } from "./permissions";
+import {
+  buildConditionDataPermission,
+  buildRoleCode,
+  deriveRoleScopeKeys,
+} from "./permissions";
 
 describe("role-governance permission helpers", () => {
   it("normalizes dynamic role codes", () => {
@@ -9,23 +13,36 @@ describe("role-governance permission helpers", () => {
     assert.equal(buildRoleCode({ roleCode: "class  advisor" }), "class_advisor");
   });
 
-  it("builds condition-based data permissions from redundant fields", () => {
+  it("derives hidden scope keys from maintainable association values", () => {
+    assert.deepEqual(
+      deriveRoleScopeKeys({
+        collegeScope: { label: "理学院", value: "college_science" },
+        classScope: { label: "2026 级一班", value: "class_2026_01" },
+      }),
+      {
+        collegeScopeKey: "college_science",
+        classScopeKey: "class_2026_01",
+      },
+    );
+  });
+
+  it("builds condition-based data permissions from hidden scope keys", () => {
     const permission = buildConditionDataPermission({
-      collegeId: "college_science",
-      classId: "",
-      ownerDeptId: "dept_lab",
+      collegeScopeKey: "college_science",
+      classScopeKey: "",
+      ownerDeptScopeKey: "dept_lab",
     });
 
     assert.equal(permission.type, "condition");
     assert.deepEqual(permission.condition.rules, [
       {
-        field: "collegeId",
+        field: "collegeScopeKey",
         componentType: "Text",
         op: "=",
         value: "college_science",
       },
       {
-        field: "ownerDeptId",
+        field: "ownerDeptScopeKey",
         componentType: "Text",
         op: "=",
         value: "dept_lab",

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/role-governance/permissions.ts

@@ -4,6 +4,19 @@ export function buildRoleCode(role: Pick<AppRoleRecord, "roleCode">) {
   return role.roleCode.trim().replace(/\s+/g, "_").toLowerCase();
 }
 
+function scopeKey(value: { value?: string | number } | undefined) {
+  return value?.value === undefined || value.value === null ? "" : String(value.value);
+}
+
+export function deriveRoleScopeKeys(
+  role: Pick<AppRoleRecord, "collegeScope" | "classScope">,
+) {
+  return {
+    collegeScopeKey: scopeKey(role.collegeScope),
+    classScopeKey: scopeKey(role.classScope),
+  };
+}
+
 export function buildConditionDataPermission(scope: DataOwnershipFields) {
   const rules = Object.entries(scope)
     .filter(([, value]) => Boolean(value))

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/role-governance/types.ts

@@ -3,15 +3,17 @@ export interface AppRoleRecord {
   roleCode: string;
   roleName: string;
   members?: Array<{ label: string; value: string }>;
-  collegeId?: string;
-  classId?: string;
+  collegeScope?: { label: string; value: string };
+  classScope?: { label: string; value: string };
+  collegeScopeKey?: string;
+  classScopeKey?: string;
   enabled?: { label: string; value: "enabled" | "disabled" };
   lastSyncedAt?: string;
 }
 
 export interface DataOwnershipFields {
-  collegeId?: string;
-  classId?: string;
-  ownerDeptId?: string;
-  ownerUserId?: string;
+  collegeScopeKey?: string;
+  classScopeKey?: string;
+  ownerDeptScopeKey?: string;
+  ownerUserScopeKey?: string;
 }

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/permissions.test.ts

@@ -8,16 +8,16 @@ const ticket: TicketRecord = {
   formInstanceId: "ticket_001",
   title: "实验室报修",
   status: "accepted",
-  ownerUserId: "owner_001",
-  ownerDeptId: "dept_lab",
-  collegeId: "college_science",
+  ownerUserScopeKey: "owner_001",
+  ownerDeptScopeKey: "dept_lab",
+  collegeScopeKey: "college_science",
 };
 
 describe("service-ticket permission helpers", () => {
-  it("allows admins and redundant ownership matches", () => {
+  it("allows admins and hidden scope-key matches", () => {
     assert.equal(canViewTicket(ticket, user({ roleCodes: ["app_admin"] })), true);
     assert.equal(canViewTicket(ticket, user({ userId: "owner_001" })), true);
-    assert.equal(canViewTicket(ticket, user({ collegeIds: ["college_science"] })), true);
+    assert.equal(canViewTicket(ticket, user({ collegeScopeKeys: ["college_science"] })), true);
     assert.equal(canViewTicket(ticket, user({ departmentIds: ["dept_lab"] })), true);
   });
 

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/permissions.ts

@@ -3,12 +3,14 @@ import { getAvailableTicketActions } from "./state-machine";
 
 export function canViewTicket(ticket: TicketRecord, operator: TicketOperator) {
   if (operator.roleCodes.includes("app_admin")) return true;
-  if (ticket.ownerUserId === operator.userId) return true;
-  if (ticket.collegeId && operator.collegeIds?.includes(ticket.collegeId)) return true;
-  if (ticket.classId && operator.classIds?.includes(ticket.classId)) return true;
+  if (ticket.ownerUserScopeKey === operator.userId) return true;
+  if (ticket.collegeScopeKey && operator.collegeScopeKeys?.includes(ticket.collegeScopeKey)) {
+    return true;
+  }
+  if (ticket.classScopeKey && operator.classScopeKeys?.includes(ticket.classScopeKey)) return true;
   if (
-    ticket.ownerDeptId &&
-    operator.departmentIds?.includes(ticket.ownerDeptId)
+    ticket.ownerDeptScopeKey &&
+    operator.departmentIds?.includes(ticket.ownerDeptScopeKey)
   ) {
     return true;
   }

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/state-machine.test.ts

@@ -18,7 +18,7 @@ const ticket: TicketRecord = {
   formInstanceId: "ticket_001",
   title: "设备故障",
   status: "new",
-  ownerDeptId: "dept_lab",
+  ownerDeptScopeKey: "dept_lab",
 };
 
 describe("service-ticket state machine", () => {

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/state-machine.ts

@@ -39,10 +39,10 @@ export function getNextTicketStatus(
 
 export function canOperateTicket(ticket: TicketRecord, operator: TicketOperator) {
   if (operator.roleCodes.includes("app_admin")) return true;
-  if (ticket.ownerUserId && ticket.ownerUserId === operator.userId) return true;
+  if (ticket.ownerUserScopeKey && ticket.ownerUserScopeKey === operator.userId) return true;
   if (
-    ticket.ownerDeptId &&
-    operator.departmentIds?.includes(ticket.ownerDeptId)
+    ticket.ownerDeptScopeKey &&
+    operator.departmentIds?.includes(ticket.ownerDeptScopeKey)
   ) {
     return true;
   }

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/ticket-query.test.ts

@@ -9,13 +9,13 @@ describe("service-ticket query builder", () => {
       keyword: "离心机",
       statuses: ["new", "processing"],
       priorities: ["urgent"],
-      collegeId: "college_science",
+      collegeScopeKey: "college_science",
     });
 
     assert.equal(group.logic, "AND");
     assert.deepEqual(
       group.rules.map((item) => item.key),
-      ["status", "priority", "collegeId"],
+      ["status", "priority", "collegeScopeKey"],
     );
     assert.equal(group.conditions.length, 1);
     assert.equal(group.conditions[0]?.logic, "OR");

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/ticket-query.ts

@@ -44,17 +44,17 @@ export function buildTicketFilterGroup(search: TicketSearchState): FilterGroup {
   if (search.priorities?.length) {
     group.rules.push(rule("priority", "SelectField", "IN", search.priorities));
   }
-  if (search.ownerUserId) {
-    group.rules.push(rule("ownerUserId", "TextField", "EQ", search.ownerUserId));
+  if (search.ownerUserScopeKey) {
+    group.rules.push(rule("ownerUserScopeKey", "TextField", "EQ", search.ownerUserScopeKey));
   }
-  if (search.ownerDeptId) {
-    group.rules.push(rule("ownerDeptId", "TextField", "EQ", search.ownerDeptId));
+  if (search.ownerDeptScopeKey) {
+    group.rules.push(rule("ownerDeptScopeKey", "TextField", "EQ", search.ownerDeptScopeKey));
   }
-  if (search.collegeId) {
-    group.rules.push(rule("collegeId", "TextField", "EQ", search.collegeId));
+  if (search.collegeScopeKey) {
+    group.rules.push(rule("collegeScopeKey", "TextField", "EQ", search.collegeScopeKey));
   }
-  if (search.classId) {
-    group.rules.push(rule("classId", "TextField", "EQ", search.classId));
+  if (search.classScopeKey) {
+    group.rules.push(rule("classScopeKey", "TextField", "EQ", search.classScopeKey));
   }
   if (search.keyword?.trim()) {
     const keyword = search.keyword.trim();

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/service-ticket/types.ts

@@ -23,10 +23,12 @@ export interface TicketRecord {
   title: string;
   status: TicketStatus;
   priority?: TicketPriority;
-  ownerUserId?: string;
-  ownerDeptId?: string;
-  collegeId?: string;
-  classId?: string;
+  ownerUserScopeKey?: string;
+  ownerDeptScopeKey?: string;
+  collegeScopeKey?: string;
+  classScopeKey?: string;
+  college?: { label: string; value: string };
+  classGroup?: { label: string; value: string };
   requester?: { label: string; value: string };
   currentOwner?: { label: string; value: string };
   description?: string;
@@ -48,8 +50,8 @@ export interface TicketOperator {
   userId: string;
   userName?: string;
   roleCodes: string[];
-  collegeIds?: string[];
-  classIds?: string[];
+  collegeScopeKeys?: string[];
+  classScopeKeys?: string[];
   departmentIds?: string[];
 }
 
@@ -57,8 +59,8 @@ export interface TicketSearchState {
   keyword?: string;
   statuses?: TicketStatus[];
   priorities?: TicketPriority[];
-  ownerUserId?: string;
-  ownerDeptId?: string;
-  collegeId?: string;
-  classId?: string;
+  ownerUserScopeKey?: string;
+  ownerDeptScopeKey?: string;
+  collegeScopeKey?: string;
+  classScopeKey?: string;
 }

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/forms/app-role/schema.ts

@@ -19,29 +19,62 @@ export default createFormSchema({
       componentName: "TextField",
       label: "角色名称",
       required: true,
+      placeholder: "请输入角色名称",
     },
     {
       fieldId: "members",
       componentName: "UserSelectField",
       label: "成员",
       multiple: true,
+      placeholder: "请选择角色成员",
     },
     {
-      fieldId: "collegeId",
+      fieldId: "collegeScope",
+      componentName: "AssociationFormField",
+      label: "适用学院",
+      placeholder: "请选择适用学院",
+      associationForm: {
+        appType: process.env.OPENXIANGDA_APP_TYPE || "APP_XXXX",
+        formUuid: "FORM_COLLEGE_PROFILE",
+        mainFieldId: "collegeName",
+        selectorColumns: [
+          { title: "学院名称", dataIndex: "collegeName" },
+          { title: "学院编码", dataIndex: "collegeCode" },
+        ],
+      },
+    },
+    {
+      fieldId: "classScope",
+      componentName: "AssociationFormField",
+      label: "适用班级",
+      placeholder: "请选择适用班级",
+      associationForm: {
+        appType: process.env.OPENXIANGDA_APP_TYPE || "APP_XXXX",
+        formUuid: "FORM_CLASS_PROFILE",
+        mainFieldId: "className",
+        selectorColumns: [
+          { title: "班级名称", dataIndex: "className" },
+          { title: "所属学院", dataIndex: "collegeName" },
+        ],
+      },
+    },
+    {
+      fieldId: "collegeScopeKey",
       componentName: "TextField",
-      label: "学院 ID",
-      tips: "与业务表冗余字段配合，用于条件式数据权限。",
+      label: "学院权限键",
+      behavior: "HIDDEN",
     },
     {
-      fieldId: "classId",
+      fieldId: "classScopeKey",
       componentName: "TextField",
-      label: "班级 ID",
-      tips: "与业务表冗余字段配合，用于条件式数据权限。",
+      label: "班级权限键",
+      behavior: "HIDDEN",
     },
     {
       fieldId: "enabled",
       componentName: "RadioField",
       label: "启用状态",
+      placeholder: "请选择启用状态",
       defaultValue: { label: "启用", value: "enabled" },
       options: [
         { label: "启用", value: "enabled" },
@@ -52,6 +85,7 @@ export default createFormSchema({
       fieldId: "lastSyncedAt",
       componentName: "DateField",
       label: "最近同步时间",
+      behavior: "HIDDEN",
     },
   ],
 });

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/forms/customer-profile/schema.ts

@@ -19,6 +19,7 @@ export default createFormSchema({
       componentName: "SelectField",
       label: "客户等级",
       required: true,
+      placeholder: "请选择客户等级",
       options: [
         { label: "重点客户", value: "key" },
         { label: "普通客户", value: "normal" },
@@ -30,45 +31,53 @@ export default createFormSchema({
       componentName: "UserSelectField",
       label: "负责人",
       required: true,
+      placeholder: "请选择负责人",
     },
     {
       fieldId: "ownerDept",
       componentName: "DepartmentSelectField",
       label: "负责部门",
       required: true,
+      placeholder: "请选择负责部门",
     },
     {
       fieldId: "contactPhone",
       componentName: "TextField",
       label: "联系电话",
+      placeholder: "请输入联系电话",
       rules: [{ preset: "phone", message: "请输入有效手机号" }],
     },
     {
       fieldId: "attachments",
       componentName: "AttachmentField",
       label: "附件",
+      placeholder: "请上传客户相关附件",
       maxCount: 5,
     },
     {
       fieldId: "contacts",
       componentName: "SubFormField",
       label: "联系人",
+      placeholder: "请添加联系人",
       columns: [
         {
           fieldId: "contactName",
           componentName: "TextField",
           label: "姓名",
           required: true,
+          placeholder: "请输入联系人姓名",
         },
         {
           fieldId: "contactRole",
           componentName: "TextField",
           label: "角色",
+          placeholder: "请输入联系人角色",
         },
         {
           fieldId: "contactMobile",
           componentName: "TextField",
           label: "手机",
+          placeholder: "请输入联系人手机",
           rules: [{ preset: "phone", message: "请输入有效手机号" }],
         },
       ],

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/forms/service-ticket/schema.ts

@@ -12,12 +12,14 @@ export default createFormSchema({
       componentName: "TextField",
       label: "标题",
       required: true,
+      placeholder: "请输入工单标题",
     },
     {
       fieldId: "status",
       componentName: "SelectField",
       label: "状态",
       required: true,
+      placeholder: "请选择工单状态",
       defaultValue: { label: "新建", value: "new" },
       options: [
         { label: "新建", value: "new" },
@@ -33,6 +35,7 @@ export default createFormSchema({
       fieldId: "priority",
       componentName: "SelectField",
       label: "优先级",
+      placeholder: "请选择优先级",
       defaultValue: { label: "普通", value: "normal" },
       options: [
         { label: "紧急", value: "urgent" },
@@ -42,55 +45,90 @@ export default createFormSchema({
       ],
     },
     {
-      fieldId: "ownerUserId",
-      componentName: "TextField",
-      label: "负责人 ID",
-      tips: "权限隔离冗余字段，服务层从人员字段同步写入。",
+      fieldId: "currentOwner",
+      componentName: "UserSelectField",
+      label: "当前处理人",
+      placeholder: "请选择当前处理人",
+    },
+    {
+      fieldId: "college",
+      componentName: "AssociationFormField",
+      label: "所属学院",
+      placeholder: "请选择所属学院",
+      associationForm: {
+        appType: process.env.OPENXIANGDA_APP_TYPE || "APP_XXXX",
+        formUuid: "FORM_COLLEGE_PROFILE",
+        mainFieldId: "collegeName",
+        selectorColumns: [
+          { title: "学院名称", dataIndex: "collegeName" },
+          { title: "学院编码", dataIndex: "collegeCode" },
+        ],
+      },
     },
     {
-      fieldId: "ownerDeptId",
+      fieldId: "classGroup",
+      componentName: "AssociationFormField",
+      label: "所属班级",
+      placeholder: "请选择所属班级",
+      associationForm: {
+        appType: process.env.OPENXIANGDA_APP_TYPE || "APP_XXXX",
+        formUuid: "FORM_CLASS_PROFILE",
+        mainFieldId: "className",
+        selectorColumns: [
+          { title: "班级名称", dataIndex: "className" },
+          { title: "所属学院", dataIndex: "collegeName" },
+        ],
+      },
+    },
+    {
+      fieldId: "ownerUserScopeKey",
       componentName: "TextField",
-      label: "负责部门 ID",
-      tips: "权限隔离冗余字段，权限组按此字段配置条件。",
+      label: "负责人权限键",
+      behavior: "HIDDEN",
     },
     {
-      fieldId: "collegeId",
+      fieldId: "ownerDeptScopeKey",
       componentName: "TextField",
-      label: "学院 ID",
-      tips: "示例冗余字段，可换成业务组织维度。",
+      label: "负责部门权限键",
+      behavior: "HIDDEN",
     },
     {
-      fieldId: "classId",
+      fieldId: "collegeScopeKey",
       componentName: "TextField",
-      label: "班级 ID",
-      tips: "示例冗余字段，可换成业务组织维度。",
+      label: "学院权限键",
+      behavior: "HIDDEN",
     },
     {
-      fieldId: "currentOwner",
-      componentName: "UserSelectField",
-      label: "当前处理人",
+      fieldId: "classScopeKey",
+      componentName: "TextField",
+      label: "班级权限键",
+      behavior: "HIDDEN",
     },
     {
       fieldId: "requester",
       componentName: "UserSelectField",
       label: "提交人",
       required: true,
+      placeholder: "请选择提交人",
     },
     {
       fieldId: "description",
       componentName: "TextAreaField",
       label: "问题描述",
       required: true,
+      placeholder: "请描述问题现象、影响范围和期望处理结果",
     },
     {
       fieldId: "lastActionAt",
       componentName: "DateField",
       label: "最近操作时间",
+      behavior: "HIDDEN",
     },
     {
       fieldId: "attachments",
       componentName: "AttachmentField",
       label: "附件",
+      placeholder: "请上传问题相关附件",
       maxCount: 8,
     },
   ],

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/pages/service-ticket-ops/components/TicketDetailDrawer.tsx

@@ -24,10 +24,13 @@ export function TicketDetailDrawer(props: {
               <StatusTag status={props.ticket.status} />
             </Descriptions.Item>
             <Descriptions.Item label="负责人">
-              {props.ticket.currentOwner?.label || props.ticket.ownerUserId || "-"}
+              {props.ticket.currentOwner?.label || "-"}
             </Descriptions.Item>
-            <Descriptions.Item label="归属部门">
-              {props.ticket.ownerDeptId || "-"}
+            <Descriptions.Item label="所属学院">
+              {props.ticket.college?.label || "-"}
+            </Descriptions.Item>
+            <Descriptions.Item label="所属班级">
+              {props.ticket.classGroup?.label || "-"}
             </Descriptions.Item>
           </Descriptions>
           <Typography.Paragraph className="bp-ticket-detail__description">

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/pages/service-ticket-ops/components/TicketTableActions.tsx

@@ -14,10 +14,12 @@ const normalizeTicket = (record: any): TicketRecord => ({
   title: record.title || record.formData?.title || "未命名工单",
   status: record.status || record.formData?.status?.value || record.formData?.status || "new",
   priority: record.priority?.value || record.formData?.priority?.value,
-  ownerUserId: record.ownerUserId || record.formData?.ownerUserId,
-  ownerDeptId: record.ownerDeptId || record.formData?.ownerDeptId,
-  collegeId: record.collegeId || record.formData?.collegeId,
-  classId: record.classId || record.formData?.classId,
+  ownerUserScopeKey: record.ownerUserScopeKey || record.formData?.ownerUserScopeKey,
+  ownerDeptScopeKey: record.ownerDeptScopeKey || record.formData?.ownerDeptScopeKey,
+  collegeScopeKey: record.collegeScopeKey || record.formData?.collegeScopeKey,
+  classScopeKey: record.classScopeKey || record.formData?.classScopeKey,
+  college: record.college || record.formData?.college,
+  classGroup: record.classGroup || record.formData?.classGroup,
   requester: record.requester || record.formData?.requester,
   currentOwner: record.currentOwner || record.formData?.currentOwner,
   description: record.description || record.formData?.description,

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/resources/permissions/form-groups/service-ticket-college.json

@@ -10,10 +10,10 @@
       "logic": "AND",
       "rules": [
         {
-          "field": "collegeId",
+          "field": "collegeScopeKey",
           "componentType": "Text",
           "op": "=",
-          "value": "${ROLE_SCOPE_COLLEGE_ID}"
+          "value": "${ROLE_SCOPE_COLLEGE_KEY}"
         }
       ]
     }

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/resources/permissions/roles.json

@@ -7,11 +7,11 @@
   {
     "code": "college_admin",
     "name": "学院管理员",
-    "description": "通过业务角色表动态维护，按 collegeId 隔离数据"
+    "description": "通过业务角色表动态维护，按学院权限键隔离数据"
   },
   {
     "code": "class_owner",
     "name": "班级负责人",
-    "description": "通过业务角色表动态维护，按 classId 隔离数据"
+    "description": "通过业务角色表动态维护，按班级权限键隔离数据"
   }
 ]

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/shared/services/service-ticket.ts

@@ -58,10 +58,10 @@ export async function transitionTicket(
     data: {
       status: nextStatus,
       lastActionAt: operatedAt,
-      ownerUserId: ticket.ownerUserId,
-      ownerDeptId: ticket.ownerDeptId,
-      collegeId: ticket.collegeId,
-      classId: ticket.classId,
+      ownerUserScopeKey: ticket.ownerUserScopeKey,
+      ownerDeptScopeKey: ticket.ownerDeptScopeKey,
+      collegeScopeKey: ticket.collegeScopeKey,
+      classScopeKey: ticket.classScopeKey,
     },
   } as never);
 

package/templates/sy-lowcode-app-workspace/examples/forms/customer/schema.ts

@@ -26,6 +26,7 @@ export default createFormSchema({
       fieldId: "customer_type",
       componentName: "SelectField",
       label: "客户类型",
+      placeholder: "请选择客户类型",
       options: [
         { value: "enterprise", label: "企业客户" },
         { value: "individual", label: "个人客户" },

package/templates/sy-lowcode-app-workspace/src/shared/form-schema.ts

@@ -16,6 +16,7 @@ export type FormComponentName =
   | "ImageField"
   | "AddressField"
   | "CascadeSelectField"
+  | "AssociationFormField"
   | "LocationField"
   | "EditorField"
   | "JSONField"
@@ -33,6 +34,7 @@ export type FieldDefinition = {
   componentName: FormComponentName;
   label: string;
   required?: boolean;
+  behavior?: "NORMAL" | "READONLY" | "DISABLED" | "HIDDEN";
   rules?: Array<{
     required?: boolean;
     message?: string;