openxiangda 1.0.260 → 1.0.262

package/README.md

@@ -3,11 +3,20 @@
 
 OpenXiangda is a lightweight CLI and skill package for private low-code platforms.
 
+## Two runtime generations
+
+OpenXiangda now has two deliberately separate development tracks:
+
+- `openxiangda` 1.x maintains existing resource-based applications and its legacy Delivery V2 protocol. Stable applications keep this runtime and are not migrated by a platform upgrade.
+- `v2/` contains the new platform-2.0 application toolchain: `create-openxiangda`, `@openxiangda/cli`, `@openxiangda/mcp`, standard React/NestJS packages, typed configuration, domain skills, and application-level deployment.
+
+For a new 2.0 application, start with [`v2/docs/getting-started.md`](v2/docs/getting-started.md). A 2.0 workspace has `openxiangda.config.ts`, `apps/web`, and `apps/server`; it must not use the 1.x resource/SDD publishing commands.
+
 Normal OpenXiangda app development uses platform-user login tokens through `/openxiangda-api/v1`; it does not use AK/SK. External backend and third-party integrations use the separate `openxiangda-open-api` skill, `/dingtalk-api/v1.0`, and a platform-managed AK/SK credential.
 
 Private platform routing is fixed: backend APIs are under `/service`, platform management is under `/platform`, and app runtime access is under `/view`. Passing a root domain such as `https://yida.wisejob.cn/` to the CLI is supported; OpenXiangda stores the API base as `https://yida.wisejob.cn/service`.
 
-## Delivery V2
+## OpenXiangda 1.x Delivery V2 (maintenance)
 
 New workspaces declare `deliveryVersion: 2`. The release flow is intentionally
 small and deterministic:
@@ -406,6 +415,8 @@ openxiangda form export customer --mode package --profile dev --output ./exports
 
 运行时页面读取当前用户信息时，优先使用 `sdk.user.getCurrent<PageUserRecord>()`。用户对象会返回常规组织成员关系 `departments`，也会返回系统维护的所属单位字段 `affiliatedDepartmentId` / `affiliatedDepartment`。`departments` 表示用户真实所在的部门、班级、专业等成员关系；`affiliatedDepartment` 表示业务上用于统计、筛选和展示的归属单位，通常是学院、单位或在源单位缺失时可用的具体部门节点，不用于替代权限部门成员关系。
 
+钉钉家校通讯录的家长、学生、教师身份和明确监护关系使用 `sdk.organization.schoolContact.*`（页面）或 `ctx.organization.schoolContact.*`（App Function）。角色声明 `app:organization:school-contact:read` 后默认可查询当前租户全部关系，返回平台用户 ID、手机号、钉钉 userid 和姓名；可选 `:self:read` / `:class:read` 用于收紧。完整示例见 [`docs/dingtalk-school-contact-relations.md`](docs/dingtalk-school-contact-relations.md)。
+
 ```ts
 import type { PageUserRecord } from "openxiangda/runtime"
 

package/lib/delivery-v2-package.js

@@ -335,6 +335,7 @@ function discoverResourceInventory(workspaceRoot, files) {
     workflow: new Map(),
   };
   const formPermissionGroupForms = new Map();
+  const automationSourceFilesByCode = new Map();
   const addFingerprint = (bucket, code, file) => {
     if (!code || !file) return;
     if (!bucket.has(code)) bucket.set(code, new Map());
@@ -396,6 +397,13 @@ function discoverResourceInventory(workspaceRoot, files) {
         ) {
           continue;
         }
+        if (prefix === 'src/automations/') {
+          if (!automationSourceFilesByCode.has(code)) {
+            automationSourceFilesByCode.set(code, []);
+          }
+          automationSourceFilesByCode.get(code).push(file);
+          continue;
+        }
         bucket.add(code);
         addFingerprint(fingerprintBucket, code, file);
       }
@@ -497,6 +505,15 @@ function discoverResourceInventory(workspaceRoot, files) {
       }
     }
   }
+  // Automation source directories may contain shared TypeScript helpers such
+  // as src/automations/_shared. Only a resource manifest declares a deployable
+  // automation; source files belonging to a declared code still participate in
+  // that automation's fingerprint and transitive dependency expansion.
+  for (const code of inventory.automations) {
+    for (const file of automationSourceFilesByCode.get(code) || []) {
+      addFingerprint(fingerprints.automations, code, file);
+    }
+  }
   for (const bucket of [
     fingerprints.forms,
     fingerprints.functions,

package/lib/skills.js

@@ -82,6 +82,62 @@ const SKILL_SPECS = [
     sourceRelativePath: 'openxiangda-skills/skills/openxiangda-open-api',
     type: 'subskill',
   },
+  {
+    name: 'openxiangda-v2',
+    displayName: 'OpenXiangda 2.0',
+    shortDescription: '标准 React/NestJS 应用与应用级交付入口。',
+    sourceRelativePath: 'v2/skills/openxiangda-v2',
+    type: 'subskill',
+  },
+  {
+    name: 'openxiangda-v2-architecture',
+    displayName: 'OpenXiangda 2.0 Architecture',
+    shortDescription: '设计 2.0 应用边界与类型化平台契约。',
+    sourceRelativePath: 'v2/skills/openxiangda-v2-architecture',
+    type: 'subskill',
+  },
+  {
+    name: 'openxiangda-v2-frontend',
+    displayName: 'OpenXiangda 2.0 Frontend',
+    shortDescription: '开发 React、Ant Design 与标准后台页面。',
+    sourceRelativePath: 'v2/skills/openxiangda-v2-frontend',
+    type: 'subskill',
+  },
+  {
+    name: 'openxiangda-v2-backend',
+    displayName: 'OpenXiangda 2.0 Backend',
+    shortDescription: '开发平台托管的标准 NestJS 应用后端。',
+    sourceRelativePath: 'v2/skills/openxiangda-v2-backend',
+    type: 'subskill',
+  },
+  {
+    name: 'openxiangda-v2-data-authz',
+    displayName: 'OpenXiangda 2.0 Data and AuthZ',
+    shortDescription: '设计 Data API、RBAC 与上下文数据权限。',
+    sourceRelativePath: 'v2/skills/openxiangda-v2-data-authz',
+    type: 'subskill',
+  },
+  {
+    name: 'openxiangda-v2-workflow-events',
+    displayName: 'OpenXiangda 2.0 Workflow and Events',
+    shortDescription: '开发 Workflow Kernel v2 与持久事件消费者。',
+    sourceRelativePath: 'v2/skills/openxiangda-v2-workflow-events',
+    type: 'subskill',
+  },
+  {
+    name: 'openxiangda-v2-delivery',
+    displayName: 'OpenXiangda 2.0 Delivery',
+    shortDescription: '构建、部署、观察、晋级和回滚完整应用。',
+    sourceRelativePath: 'v2/skills/openxiangda-v2-delivery',
+    type: 'subskill',
+  },
+  {
+    name: 'openxiangda-v1-maintenance',
+    displayName: 'OpenXiangda 1.x Maintenance',
+    shortDescription: '不迁移地安全维护稳定 1.x 应用。',
+    sourceRelativePath: 'v2/skills/openxiangda-v1-maintenance',
+    type: 'subskill',
+  },
 ];
 
 function getDefaultCodexSkillsDir(env = process.env) {

package/openxiangda-skills/SKILL.md

@@ -10,7 +10,13 @@ OpenXiangda connects an AI coding workspace to the private low-code platform thr
 
 This file is a router and safety card. Read only the one or two subskills selected below; do not load every OpenXiangda reference into the same turn.
 
-## Delivery V2 is the normal release path
+## Select the runtime generation first
+
+If the workspace contains `openxiangda.config.ts`, `apps/web`, and `apps/server`, it is a platform-2.0 application. Stop this 1.x resource flow and use `$openxiangda-v2` plus its architecture, frontend, backend, data-authz, workflow-events, and delivery skills. The 2.0 CLI operates on one immutable application package and does not use SDD or per-resource publishing.
+
+If the workspace contains `app-workspace.config.ts`, forms/pages/resource manifests, or an existing 1.x state directory, continue with this router. Never migrate a stable 1.x application merely because platform 2.0 is available.
+
+## 1.x Delivery V2 is the normal 1.x release path
 
 When `app-workspace.config.ts` declares `deliveryVersion: 2`, all later V1 SDD,
 Git-mainline, candidate/ship, `--change`, and `--only` release rules are
@@ -60,6 +66,7 @@ content/source/parent verification and never overwrites immutable storage.
 | React/classic page | `openxiangda-page` | inspect the target route/page |
 | Function, automation, workflow, JS_CODE | `openxiangda-workflow-automation` | inspect the exact resource codes |
 | Roles, permission groups, data scope | `openxiangda-permission-settings` | produce the permission matrix |
+| DingTalk school-contact guardian/student relationships | `openxiangda-page` plus `references/school-contact-relations.md` | use the platform relationship SDK, defaulting to unrestricted tenant scope |
 | New app architecture, auth, public access | `openxiangda-architecture-design` plus the relevant domain skill | run the design gate |
 | External backend/OpenAPI/AK-SK | `openxiangda-open-api` | describe the exact operation |
 
@@ -184,6 +191,10 @@ The lease is app-level promotion ownership, while worktree ownership prevents tw
 - Use platform roles, permission groups, public grants, and backend Function checks for authorization; frontend hiding is presentation only.
 - Keep tokens and secrets out of project files and chat.
 - Use official public SDK entrypoints and platform form/file components.
+- Read school-contact guardian/student relationships through
+  `sdk.organization.schoolContact` or the trusted App Function bridge. Keep the
+  default tenant-wide scope unless the product explicitly requires self/class
+  restrictions; never infer relations from department membership.
 - Report platform defects or repeated workarounds with `openxiangda feedback submit --yes` when a configured feedback channel is available.
 - Run `openxiangda update check --json` once at the start of substantial work, when a version mismatch is suspected, or when the cached check is older than one day. Do not repeat it on every confirmation turn.
 - Install an available update with `openxiangda update install`; it reuses the npm cache, avoids peer-resolution stalls, emits a heartbeat, and has a bounded timeout. Do not replace it with a bare repeated `npm install -g` unless bootstrapping the CLI for the first time.

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

@@ -32,7 +32,7 @@ Notification manifests live under `src/resources/notifications/` and contain `te
 
 Data view manifests live under `src/resources/data-views/` and define read-only joined or aggregate query resources. Use `storageMode: "materialized"` for refreshed lists/reports where lag is acceptable, and `storageMode: "live"` for bounded real-time query shapes. Use row views with `sdk.dataView.query` and aggregate views with `sdk.dataView.stats`. Before generating one, confirm freshness tolerance, query bounds, and indexes for materialized filters/sort fields/dimensions/date buckets. Do not use them for single-form CRUD, simple linkedForm selects, writes, write-back, or ad-hoc BI. See `data-views.md` before generating one.
 
-App Function manifests live under `src/resources/functions/`, with source in `src/functions/<functionCode>/index.ts`. Use them for reusable server-side logic that pages, automations, and workflows can share through `sdk.function.invoke` or `function_call` nodes. App Functions expose controlled runtime helpers such as `ctx.resources`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, `ctx.organization`, `ctx.platform.roles`, and `ctx.platform.api`; they do not expose raw SQL or Redis in the current MVP. Published trusted code may use all application-owned Forms/DataViews in the current tenant/app. Function `resources` remains optional code-to-ID mapping and audit metadata, while cross-app/cross-tenant access stays forbidden. Use `ctx.platform.roles.list/findByCode/addUsers/removeUser` for app role lookup and membership changes; raw `ctx.platform.api` returns an HTTP response plus platform envelope. Runtime page invocations also expose trusted role context on `ctx.operator.roleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, and `ctx.permissions`; use that context for business authorization, and never trust page-submitted role codes for sensitive actions. Page-call grants should use `definitionJson.runtimeInvoke.audience` (`authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`); `roleCodes` is only for current app-role grants and does not support `"*"` or `"all-app-roles"`. App Function form writes are trusted backend operations, not direct page-user submit access to the target form. For internal function-only forms, publish form settings with `runtimeWrite.mode="function_only"` so raw write endpoints are closed. App Function organization writes require `app:organization:manage` on the real operator/audit actor. Use JS_CODE V2 only for node-local workflow/automation scripts.
+App Function manifests live under `src/resources/functions/`, with source in `src/functions/<functionCode>/index.ts`. Use them for reusable server-side logic that pages, automations, and workflows can share through `sdk.function.invoke` or `function_call` nodes. App Functions expose controlled runtime helpers such as `ctx.resources`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, `ctx.organization`, `ctx.platform.roles`, and `ctx.platform.api`; they do not expose raw SQL or Redis in the current MVP. Published trusted code may use all application-owned Forms/DataViews in the current tenant/app. Function `resources` remains optional code-to-ID mapping and audit metadata, while cross-app/cross-tenant access stays forbidden. Use `ctx.platform.roles.list/findByCode/addUsers/removeUser` for app role lookup and membership changes; raw `ctx.platform.api` returns an HTTP response plus platform envelope. Runtime page invocations also expose trusted role context on `ctx.operator.roleCodes`, `ctx.operator.platformRoleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, and `ctx.permissions`; `platformRoleCodes` contains the synchronized platform identities `SCHOOL_GUARDIAN`, `SCHOOL_STUDENT`, and `SCHOOL_TEACHER`, while `roleCodes` contains app roles. Use that context for business authorization, and never trust page-submitted role codes for sensitive actions. Page-call grants should use `definitionJson.runtimeInvoke.audience` (`authenticated`, `page_permission_group`, `app_roles`, `platform_roles`, or `scope_policy`); use `roleCodes` for current app-role grants and `platformRoleCodes` for synchronized identities. App Function form writes are trusted backend operations, not direct page-user submit access to the target form. For internal function-only forms, publish form settings with `runtimeWrite.mode="function_only"` so raw write endpoints are closed. App Function organization writes require `app:organization:manage` on the real operator/audit actor. Use JS_CODE V2 only for node-local workflow/automation scripts.
 
 Auth manifests live under `src/resources/auth/`. Use them to enable app-level login methods and bind phone-code/CAS/custom providers to App Functions. Auth provider functions are called only by the platform auth flow. They validate external credentials and return identity assertions such as `phone`, `email`, `externalId`, or `unionId`; they must not issue tokens, set cookies, or mutate platform user/binding tables.
 

package/openxiangda-skills/references/openxiangda-api.md

@@ -743,10 +743,16 @@ Body:
 {
   "name": "销售可见页面",
   "roles": ["sales"],
+  "platformRoleCodes": ["SCHOOL_TEACHER"],
   "menuFormUuids": ["FORM_XXX", "MENU_ID_FOR_CODE_PAGE"]
 }
 ```
 
+`platformRoleCodes` is optional. It matches synchronized platform identities in addition to
+`roles` (OR semantics): `SCHOOL_GUARDIAN`, `SCHOOL_STUDENT`, and `SCHOOL_TEACHER`. Both arrays
+empty means unrestricted. These three system roles are maintained by the daily DingTalk
+school-contact sync and cannot be assigned through role-management APIs.
+
 An empty `menuFormUuids` array means all menus/pages are visible to the matched roles. For form menus this field can contain form UUIDs. For custom code page menus, the editable permission group should contain the menu ID, which is what the platform permission editor uses for tree check state. OpenXiangda CLI resolves `--page-codes` / `--menu-codes` to an editable menu-ID group and creates a companion `（运行时别名）` group for required page ID, route key, and legacy `PAGE_...` runtime aliases by default. This keeps the main group editable while satisfying `/view` runtime guards. Use `--no-runtime-aliases` only for deployments whose runtime checks menu IDs directly.
 
 ### GET `/apps/:appType/page-permission-groups/:groupId`
@@ -763,7 +769,8 @@ Requires Bearer token. Deletes a page permission group.
 
 ### GET `/apps/:appType/page-permission-groups/user-menu-permissions`
 
-Requires Bearer token. Returns the current user's menu visibility summary for the app.
+Requires Bearer token. Returns the current user's menu visibility summary for the app,
+including the synchronized `platformRoleCodes`.
 
 ### GET `/apps/:appType/forms/:formUuid/permission-groups`
 
@@ -780,6 +787,7 @@ Body:
   "name": "销售查看",
   "type": "view",
   "roles": ["sales"],
+  "platformRoleCodes": ["SCHOOL_GUARDIAN"],
   "dataScope": [{ "type": "self" }],
   "operations": ["view"],
   "fieldPermissions": [],

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

@@ -19,6 +19,8 @@ Guidelines:
 - Use `sdk.export.create` and `sdk.export.get` for asynchronous XLSX exports. Simple pages may send a declarative workbook definition. Complex or reusable exports should send only a published App Function `definitionCode`, the current query snapshot, export scope, and stable selected row IDs. The server executes `structured_export_provider_v1` with fresh user permissions; never upload executable rendering code from the browser. See `docs/structured-export-v1.md`.
 - Use `AttachmentPreviewList`, `ImagePreviewGrid`, or `useFilePreview` from `openxiangda/runtime/react` for in-page attachment previews in a custom React SPA page. They use the current PageSdk context and enforce the platform capability and ticket contracts. Use `sdk.createFileAccessTicket(bucketName, objectName, fileName, "preview", { appType })` only when the page needs a shareable or new-window preview link. `appType` defaults to the current page context. Open `response.result.previewPageUrl`; do not use `previewUrl` or `/service/file/preview-by-ticket/:ticket` as the page entry.
 - Use `sdk.organization.departments.*` and `sdk.organization.accounts.*` only for intentional organization pages. Read-only list/detail pages need `app:organization:read` or `app:organization:manage`; writes and password operations need `app:organization:manage`. Do not call legacy `/user` or `/department` endpoints from pages.
+- Use `sdk.organization.schoolContact.*` for synchronized guardian/student relationships. Declare `app:organization:school-contact:read`; it defaults to all relationships in the current tenant. Use the optional `self:read` or `class:read` permission only when the product explicitly needs a narrower data scope. The response intentionally includes platform user ID, mobile, DingTalk userid, and name. Read `references/school-contact-relations.md` before building a family or class page.
+- Synchronized school-contact users also receive platform identity codes: `SCHOOL_GUARDIAN`, `SCHOOL_STUDENT`, and `SCHOOL_TEACHER`. Page permission groups select them with `platformRoleCodes` (additive to app `roles`), and runtime permissions expose them in `permissions.platformRoleCodes`. App Functions can use a `platform_roles` invocation audience and trusted `ctx.operator.platformRoleCodes`; these roles are maintained only by the daily organization sync.
 - Use `sdk.workCenter.listItems({ boxType })` and `sdk.workCenter.getStats()` for current-user work center lists and counts. `boxType` is one of `todo`, `done`, `cc`, or `initiated`. This is the end-user task/handled/cc/initiated surface; do not build todo pages by reading workflow operation logs, automation logs, or raw process-task tables.
 - `sdk.form.create` returns identifiers and generated serial number values only. Treat `formInstId` / `formInstanceId` as the required success contract; `serialNumber` / `serialNumbers` are present only when the form has `SerialNumberField`. Do not expect the save response to contain the full row, formula results, or other server-generated field values. Call `sdk.form.getDetail` explicitly after create when those values are needed.
 - Missing `formInstId` / `formInstanceId` is a real error in strict mode. Do not create fake IDs, mock rows, or fallback display data to hide it.
@@ -188,7 +190,7 @@ App Function source should prefer `export default async function(ctx, input) {}`
 The second argument is the `input` passed by `sdk.function.invoke`, and the
 same value is also available as `ctx.input` for compatibility.
 
-Use App Functions when the logic must run server-side and be reusable by pages, automations, or workflows. Runtime invocation requires app automation management permission by default. To let ordinary app users call a function from a page, declare `definitionJson.runtimeInvoke.audience` with `authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`; use `roleCodes` only for current app-role grants. Do not use `"*"` or `"all-app-roles"` as role codes. Inside the function, authorize sensitive actions with trusted runtime context such as `ctx.operator.roleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, or `ctx.permissions`; do not trust role codes sent in the page input. Published trusted code may write any form in its current tenant/application; per-function `resources.forms` is optional mapping and audit metadata, not an authorization allowlist. Do not open direct submit permission on internal forms just for that page action.
+Use App Functions when the logic must run server-side and be reusable by pages, automations, or workflows. Runtime invocation requires app automation management permission by default. To let ordinary app users call a function from a page, declare `definitionJson.runtimeInvoke.audience` with `authenticated`, `page_permission_group`, `app_roles`, `platform_roles`, or `scope_policy`; use `roleCodes` only for current app-role grants and `platformRoleCodes` for synchronized identities. Do not use `"*"` or `"all-app-roles"` as role codes. Inside the function, authorize sensitive actions with trusted runtime context such as `ctx.operator.roleCodes`, `ctx.operator.platformRoleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, or `ctx.permissions`; do not trust role codes sent in the page input. Published trusted code may write any form in its current tenant/application; per-function `resources.forms` is optional mapping and audit metadata, not an authorization allowlist. Do not open direct submit permission on internal forms just for that page action.
 
 Server-defined export:
 
@@ -251,6 +253,8 @@ await sdk.organization.accounts.resetPassword("alice", {
 
 Use `ctx.organization.departments.*` and `ctx.organization.accounts.*` inside App Functions or trusted JS nodes for the same capability. Runtime service principals must resolve a real operator/audit actor; permission is checked against that user, not against the runtime service account. Keep password changes on dedicated endpoints: update account metadata with `update`, reset another user's password with `resetPassword`, and change the current user's password with `changeMyPassword({ oldPassword, newPassword })`.
 
+For synchronized school-contact relationships, use `sdk.organization.schoolContact.relations.list`, `children.list`, `guardians.list`, or `myFamily.get`; App Functions use the same paths under `ctx.organization.schoolContact`. Do not infer a family relationship from class membership or persist a second relationship master inside application forms. See `references/school-contact-relations.md` for permission codes, filters, response fields, and examples.
+
 Work center:
 
 ```ts

package/openxiangda-skills/references/permission-design-patterns.md

@@ -275,6 +275,9 @@ Before implementation, write a matrix with at least these columns:
 - Query parameters as sensitive authorization.
 - Frontend-only button hiding or route hiding.
 - Hardcoded role strings scattered through pages.
+- OR data policies whose role-specific rules omit `roleCodes`; otherwise a
+  user's applicant rule can remain active after switching to an administrator
+  RoleSession.
 - Delegated administrators without `app:role:manage` or required permission
   group management API permissions.
 - New roles created by delegated administrators without their own
@@ -301,6 +304,8 @@ Before implementation, write a matrix with at least these columns:
   matched grants, cache state, and final policy for at least one allow and one
   deny case.
 - Allowed role paths and denied role paths are both tested.
+- A multi-role user is tested after switching RoleSession, and rules bound to
+  the previously selected role no longer contribute to row visibility.
 - Query parameter tampering does not expand sensitive access.
 - App Functions that mutate sensitive data verify `ctx.operator.roleCodes`,
   `ctx.operator.currentRoleCode`, business scope, or explicit public ticket.

package/openxiangda-skills/references/permissions-settings.md

@@ -87,10 +87,16 @@ group so the platform tree can still round-trip the menu selection.
 {
   "name": "销售页面",
   "roles": ["sales"],
+  "platformRoleCodes": [],
   "menuFormUuids": ["FORM_CUSTOMER", "FORM_ORDER", "MENU_ID_FOR_CODE_PAGE"]
 }
 ```
 
+`platformRoleCodes` is optional and is evaluated alongside `roles` using OR semantics. Use the
+daily DingTalk school-contact identity codes `SCHOOL_GUARDIAN`, `SCHOOL_STUDENT`, and
+`SCHOOL_TEACHER`; the platform maintains these system roles and applications must not assign
+them manually. If both arrays are empty, the group is unrestricted.
+
 For custom code pages, keep the editable menu tree targets separate from runtime aliases. The
 platform permission editor only reliably checks real menu IDs, while `/view` runtime guards on
 some private deployments still check the code page id, route key, or legacy `PAGE_...` id. When
@@ -129,6 +135,7 @@ Submit group:
   "name": "销售提交",
   "type": "submit",
   "roles": ["sales"],
+  "platformRoleCodes": [],
   "operations": ["submit"]
 }
 ```
@@ -140,6 +147,7 @@ View group:
   "name": "销售查看",
   "type": "view",
   "roles": ["sales"],
+  "platformRoleCodes": [],
   "dataScope": [{ "type": "self" }],
   "operations": ["view", "edit"],
   "fieldPermissions": [

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

@@ -614,10 +614,13 @@ export default async function reservationReminderSummary(
     { headers: { authorization: `Bearer ${providerToken}` } },
   );
   const roleCodes = ctx.operator?.roleCodes || ctx.permissions?.roleCodes || [];
+  const platformRoleCodes =
+    ctx.operator?.platformRoleCodes || ctx.permissions?.platformRoleCodes || [];
   const canManage =
     ctx.operator?.hasFullAccess === true ||
     ctx.permissions?.hasFullAccess === true ||
-    roleCodes.includes("union_admin");
+    roleCodes.includes("union_admin") ||
+    platformRoleCodes.includes("SCHOOL_TEACHER");
   if (!canManage) throw new Error("当前账号无权执行该操作。");
 
   const orders = await ctx.form.queryMany({
@@ -678,7 +681,7 @@ const result = await sdk.function.invoke("reservation_reminder_summary", {
 }
 ```
 
-适用边界：可复用后端业务逻辑、跨页面/自动化/流程共享的查询编排、连接器调用、通知编排、受控平台 API 调用。App Function 支持 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.platform.roles`、`ctx.platform.api` 等受控 helper，当前 MVP 不暴露原始 SQL/Redis。应用角色查询和成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`；底层 `ctx.platform.api` 返回 HTTP 包装与平台 envelope，需要自行解包。已发布可信代码可以访问当前租户、当前应用内的资源；function manifest 的 `resources` 是可选映射、审计和影响分析信息，不再是逐函数权限白名单。页面用户仍不能直接提交内部表单，跨应用和跨租户访问仍被拒绝。运行时接口默认需要应用自动化管理权限；普通用户页面要调用时，用 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles` 或 `scope_policy`，不要把 `"*"`、`"all-app-roles"` 写进 `roleCodes`。若表单只能由函数/流程写入，在 `src/resources/settings/forms/<formCode>.json` 设置 `runtimeWrite.mode="function_only"` 关闭原始写入接口。
+适用边界：可复用后端业务逻辑、跨页面/自动化/流程共享的查询编排、连接器调用、通知编排、受控平台 API 调用。App Function 支持 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.platform.roles`、`ctx.platform.api` 等受控 helper，当前 MVP 不暴露原始 SQL/Redis。应用角色查询和成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`；底层 `ctx.platform.api` 返回 HTTP 包装与平台 envelope，需要自行解包。已发布可信代码可以访问当前租户、当前应用内的资源；function manifest 的 `resources` 是可选映射、审计和影响分析信息，不再是逐函数权限白名单。页面用户仍不能直接提交内部表单，跨应用和跨租户访问仍被拒绝。运行时接口默认需要应用自动化管理权限；普通用户页面要调用时，用 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles`、`platform_roles` 或 `scope_policy`，使用 `roleCodes` 匹配应用角色、使用 `platformRoleCodes` 匹配同步身份 `SCHOOL_GUARDIAN`、`SCHOOL_STUDENT`、`SCHOOL_TEACHER`，不要把 `"*"`、`"all-app-roles"` 写进角色编码。若表单只能由函数/流程写入，在 `src/resources/settings/forms/<formCode>.json` 设置 `runtimeWrite.mode="function_only"` 关闭原始写入接口。
 
 ## 5. Workflow — `src/resources/workflows/<code>/workflow.json`（manifest）+ `src/workflows/<code>/workflow.ts`（代码优先）
 

package/openxiangda-skills/references/school-contact-relations.md

@@ -0,0 +1,165 @@
+# 家校通讯录关系
+
+家校关系由平台组织中心统一同步和维护。应用不得直连钉钉，也不得根据班级成员自行推断家长和学生关系。
+
+## 权限与默认范围
+
+需要查询家校关系的应用角色在 `src/resources/roles/<code>.json` 的 `apiPermissionCodes` 中声明：
+
+```json
+{
+  "apiPermissionCodes": [
+    "app:organization:school-contact:read"
+  ]
+}
+```
+
+`app:organization:school-contact:read` 默认允许当前租户内全部关系，不按本人或班级限制。只有产品明确要求收紧时，才改用以下权限之一：
+
+- `app:organization:school-contact:self:read`：只返回当前操作者作为家长或学生直接参与的关系。
+- `app:organization:school-contact:class:read`：只返回当前操作者以 `teacher` 身份加入的班级关系。
+
+默认全量可见不等于公开访问：跨租户、游客和匿名页面仍然拒绝。不要通过公开访问策略给游客授予家庭关系能力。
+
+## 页面 SDK
+
+### 平台内置身份角色
+
+每次成功的钉钉家校通讯录全量同步都会对账并维护三种平台层系统身份角色：
+
+| 展示名 | 稳定角色编码 | 含义 |
+| --- | --- | --- |
+| 家长 | `SCHOOL_GUARDIAN` | 在家校成员关系中作为 guardian |
+| 学生 | `SCHOOL_STUDENT` | 在家校成员关系中作为 student |
+| 老师 | `SCHOOL_TEACHER` | 在家校成员关系中作为 teacher |
+
+身份角色可组合，一个平台用户可以同时是老师和家长；角色由同步维护，不能在平台角色管理中手工分配、修改、删除，也不会被当前平台角色切换隐藏。应用权限组把这些编码填入 `platformRoleCodes`，与应用角色 `roles` 是并列的 OR 条件；两个数组都为空仍表示不限制。
+
+运行时页面权限会在 `permissions.platformRoleCodes` 返回当前用户的身份编码，它与 `permissions.roleCodes` 分开：
+
+```ts
+const isGuardian =
+  sdk.context.permissions?.platformRoleCodes?.includes("SCHOOL_GUARDIAN")
+```
+
+App Function 的调用受众可以声明平台身份角色，服务端按真实操作者的同步结果校验：
+
+```json
+{
+  "runtimeInvoke": {
+    "audience": {
+      "type": "platform_roles",
+      "platformRoleCodes": ["SCHOOL_GUARDIAN", "SCHOOL_TEACHER"]
+    }
+  }
+}
+```
+
+函数可信上下文同时提供 `ctx.operator.platformRoleCodes` 和 `ctx.permissions.platformRoleCodes`。不要信任页面输入中的角色编码；需要家庭双方或班级关系时，继续使用下方的 `schoolContact` 关系 SDK。
+
+在 React SPA 或代码页中通过 Page SDK 查询，不要硬编码接口地址：
+
+```ts
+const response = await sdk.organization.schoolContact.relations.list({
+  name: keyword,
+  classId,
+  page: 1,
+  pageSize: 20,
+})
+
+const relations = response.result?.items || []
+```
+
+常用方法：
+
+```ts
+await sdk.organization.schoolContact.children.list(guardianUserId, {
+  page: 1,
+  pageSize: 20,
+})
+
+await sdk.organization.schoolContact.guardians.list(studentUserId, {
+  page: 1,
+  pageSize: 20,
+})
+
+await sdk.organization.schoolContact.myFamily.get({ pageSize: 50 })
+```
+
+关系列表支持以下服务端过滤条件：
+
+- `userId`、`guardianUserId`、`studentUserId`：平台用户 ID。
+- `dingtalkUserId`：钉钉 userid。
+- `mobile`：精确手机号。
+- `name`：家长或学生姓名。
+- `classId`：平台家校班级 ID 或钉钉教育 `class_id`。
+- `role`：`guardian` 或 `student`，用于限定通用人员过滤作用在哪一端。
+- `relationCode`、`page`、`pageSize`；`pageSize` 最大为 100。
+
+## App Function
+
+App Function、Automation 或 Workflow 中需要复用关系时，调用对应的受控后端桥接：
+
+```ts
+export default async function(ctx, input) {
+  const result = await ctx.organization.schoolContact.relations.list({
+    guardianUserId: input.guardianUserId,
+    page: 1,
+    pageSize: 20,
+  })
+
+  return result.items
+}
+```
+
+对应方法为：
+
+```ts
+ctx.organization.schoolContact.relations.list(params)
+ctx.organization.schoolContact.children.list(userId, params)
+ctx.organization.schoolContact.guardians.list(userId, params)
+ctx.organization.schoolContact.myFamily.get(params)
+```
+
+运行时使用平台提供的真实操作者做权限校验。不要信任页面 input 中伪造的租户、角色或当前用户 ID。
+
+## 返回结构
+
+```ts
+interface SchoolContactRelation {
+  relationId: string
+  relationCode: string | null
+  relationName: string | null
+  guardian: {
+    userId: string
+    dingtalkUserId: string
+    name: string
+    mobile: string | null
+  }
+  student: {
+    userId: string
+    dingtalkUserId: string
+    name: string
+    mobile: string | null
+  }
+  class: {
+    id: string
+    dingtalkClassId: string
+    name: string
+    campusName: string | null
+    periodName: string | null
+    gradeName: string | null
+  }
+  syncedAt: string
+  syncState: "current" | "not_synced" | "disabled"
+}
+```
+
+手机号可能为空。`sync.state=disabled` 表示管理员关闭了后续同步，现有数据仍保留但可能过期；业务页面在对时效敏感时应展示 `lastSuccessfulSyncAt`。
+
+## 持久化边界
+
+- 平台关系是当前事实，不要复制全量关系到应用表单或 Data View。
+- 业务单据确实需要历史证据时，只保存 `relationId`、双方平台用户 ID 和当时的最小显示快照。
+- 不保存或依赖 `unionid`、同步原文、行业部门 ID，也不要假设行业 `dept_id` 等于教育 `class_id`。
+- 所有列表保持分页；不要拉取全部关系后在浏览器过滤。

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

@@ -36,6 +36,7 @@ openxiangda workspace publish --profile <name> --page <pageCode>
 - ✅ For external APIs use `src/resources/connectors/<code>.json` + `sdk.connector.invoke()`; for joined read-only lists use row data views + `sdk.dataView.query`; for stable dashboard metrics use aggregate data views + `sdk.dataView.stats`.
 - ✅ Choose data view `storageMode` deliberately: `materialized` for refreshed reports/lists that tolerate delay, `live` for bounded real-time multi-form reads.
 - ✅ For reusable backend orchestration use App Function (`src/functions/<functionCode>/index.ts` + `src/resources/functions/<functionCode>.json`) and call `sdk.function.invoke(code, { input })`; keep page components out of multi-table business orchestration.
+- ✅ 家长、学生、教师身份或监护关系页面使用 `sdk.organization.schoolContact.*`；先读 `references/school-contact-relations.md`，声明家校关系读取权限并保持服务端分页。
 - ✅ Filters, search bars, modal forms, drawers, and inline edits use platform components for platform data fields, otherwise `antd` / `antd-mobile` controls.
 - ❌ Single-file giant pages. Split per `references/best-practices.md`.
 - ❌ Hardcoded `/view/...&isRenderNav=false` URLs scattered through page code; use the runtime navigation helper.
@@ -114,6 +115,7 @@ Read these references only when editing page code:
 - `references/pages/app-shell.md` — formal backend / PC portal / mobile portal entry pattern. Read before creating any user-facing main entry or admin console.
 - `references/best-practices.md` — initialized examples for modular pages, status lifecycles, role governance, high-performance queries, portal shells, and interactive workbenches. Read before scaffolding complex pages or data management pages.
 - `references/pages/page-sdk.md`
+- `references/school-contact-relations.md` — 家校关系权限、分页查询、返回字段以及 Page SDK/App Function 示例。创建家长、学生或班级关系页面前读取。
 - `references/notifications.md` — notification resources and `sdk.notification` usage. Read before adding reminders, alerts, or message templates to a page.
 - `references/pages/publish-flow.md`
 - `references/style-system.md` — style isolation defaults, Tailwind/CSS guidance, and legacy namespace compatibility. Read before writing substantial page CSS or Tailwind classes.
@@ -130,6 +132,7 @@ Read these references only when editing page code:
 - 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.
+- 家校关系必须通过 `sdk.organization.schoolContact` / `ctx.organization.schoolContact` 读取；不要直连钉钉、查询系统表或用同班成员推断亲属关系。
 - For reminders, alerts, and business messages, declare `src/resources/notifications/` first and call `sdk.notification`; do not hardcode notification API URLs.
 - For backend business logic shared by pages, automations, or workflows, declare an App Function and call `sdk.function.invoke`; do not duplicate the same multi-form query/connector/notification orchestration in page code.
 - Before hand-writing mature UI behavior, consult `references/component-guide.md` and use established libraries: platform components for platform data fields, antd/antd-mobile for controls and overlays, ECharts for charts, GSAP for complex animation timelines, and maintained packages such as dnd-kit for drag/drop. Do not rebuild mature controls with raw DOM/native inputs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.260",
+  "version": "1.0.262",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -55,6 +55,7 @@
     "bin/",
     "lib/",
     "openxiangda-skills/",
+    "v2/skills/",
     "policy/",
     "templates/",
     "packages/sdk/bin/",