openxiangda 1.0.262 → 1.0.264

package/README.md

@@ -415,7 +415,7 @@ 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)。
+钉钉家校通讯录的家长、学生、教师身份和明确监护关系使用 `sdk.organization.schoolContact.*`（页面）或 `ctx.organization.schoolContact.*`（App Function）。已登录非游客用户无需给应用角色额外绑定权限，默认可查询当前租户全部关系，返回平台用户 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/openxiangda-skills/SKILL.md

@@ -191,9 +191,12 @@ 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
+- Read school-contact guardian/student and teacher/class relationships through
+  `sdk.organization.schoolContact` or the trusted App Function bridge. Use
+  `SCHOOL_HEAD_TEACHER` only for global identity and `teachers.list` for the
+  exact class relationship. Keep the
+  authenticated non-guest default tenant-wide scope without adding an app-role
+  permission binding 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.

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

@@ -19,7 +19,7 @@ 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.
+- Use `sdk.organization.schoolContact.*` for synchronized guardian/student and teacher/class relationships. `SCHOOL_HEAD_TEACHER` identifies a user who currently heads at least one class; use `teachers.list({ classId, isHeadTeacher: true })` to resolve the exact class. Authenticated non-guest users default to all relationships in the current tenant without an app-role permission binding. 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.
@@ -253,7 +253,7 @@ 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.
+For synchronized school-contact relationships, use `sdk.organization.schoolContact.relations.list`, `teachers.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, infer a specific head-teacher class from the global role, 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:
 

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

@@ -4,7 +4,9 @@
 
 ## 权限与默认范围
 
-需要查询家校关系的应用角色在 `src/resources/roles/<code>.json` 的 `apiPermissionCodes` 中声明：
+已登录非游客用户无需给应用角色绑定家校权限，默认查询当前租户的全部关系，范围为 `all`。跨租户、游客和匿名访问仍然拒绝。
+
+应用若要显式保留全量范围，可以在 `src/resources/roles/<code>.json` 中声明：
 
 ```json
 {
@@ -14,24 +16,27 @@
 }
 ```
 
-`app:organization:school-contact:read` 默认允许当前租户内全部关系，不按本人或班级限制。只有产品明确要求收紧时，才改用以下权限之一：
+`app:organization:school-contact:read` 与未声明权限时的默认范围相同。只有产品明确要求收紧时，才改用以下权限之一：
 
 - `app:organization:school-contact:self:read`：只返回当前操作者作为家长或学生直接参与的关系。
 - `app:organization:school-contact:class:read`：只返回当前操作者以 `teacher` 身份加入的班级关系。
 
+同一应用角色拥有多项家校能力时按 `all > class > self` 取最宽范围。平台身份角色只表达用户身份，不参与通用应用权限计算；默认 `all` 由家校关系服务统一执行。
+
 默认全量可见不等于公开访问：跨租户、游客和匿名页面仍然拒绝。不要通过公开访问策略给游客授予家庭关系能力。
 
 ## 页面 SDK
 
 ### 平台内置身份角色
 
-每次成功的钉钉家校通讯录全量同步都会对账并维护三种平台层系统身份角色：
+每次成功的钉钉家校通讯录全量同步都会对账并维护四种平台层系统身份角色：
 
 | 展示名 | 稳定角色编码 | 含义 |
 | --- | --- | --- |
 | 家长 | `SCHOOL_GUARDIAN` | 在家校成员关系中作为 guardian |
 | 学生 | `SCHOOL_STUDENT` | 在家校成员关系中作为 student |
 | 老师 | `SCHOOL_TEACHER` | 在家校成员关系中作为 teacher |
+| 班主任 | `SCHOOL_HEAD_TEACHER` | 至少一个 teacher 班级成员带 `is_adviser=true` |
 
 身份角色可组合，一个平台用户可以同时是老师和家长；角色由同步维护，不能在平台角色管理中手工分配、修改、删除，也不会被当前平台角色切换隐藏。应用权限组把这些编码填入 `platformRoleCodes`，与应用角色 `roles` 是并列的 OR 条件；两个数组都为空仍表示不限制。
 
@@ -40,8 +45,13 @@
 ```ts
 const isGuardian =
   sdk.context.permissions?.platformRoleCodes?.includes("SCHOOL_GUARDIAN")
+
+const isHeadTeacher =
+  sdk.context.permissions?.platformRoleCodes?.includes("SCHOOL_HEAD_TEACHER")
 ```
 
+`SCHOOL_HEAD_TEACHER` 只说明当前用户至少担任一个班的班主任。班主任是班级维度的关系；要判断具体班级，必须使用下方 `teachers.list` 返回的 `isHeadTeacher`，不能用全局角色推断。
+
 App Function 的调用受众可以声明平台身份角色，服务端按真实操作者的同步结果校验：
 
 ```json
@@ -84,6 +94,13 @@ await sdk.organization.schoolContact.guardians.list(studentUserId, {
 })
 
 await sdk.organization.schoolContact.myFamily.get({ pageSize: 50 })
+
+await sdk.organization.schoolContact.teachers.list({
+  classId,
+  isHeadTeacher: true,
+  page: 1,
+  pageSize: 20,
+})
 ```
 
 关系列表支持以下服务端过滤条件：
@@ -96,6 +113,16 @@ await sdk.organization.schoolContact.myFamily.get({ pageSize: 50 })
 - `role`：`guardian` 或 `student`，用于限定通用人员过滤作用在哪一端。
 - `relationCode`、`page`、`pageSize`；`pageSize` 最大为 100。
 
+老师班级成员列表 `teachers.list` 支持：
+
+- `userId`：老师的平台用户 ID。
+- `dingtalkUserId`：老师的钉钉 userid。
+- `mobile`：精确手机号。
+- `name`：老师姓名。
+- `classId`：平台家校班级 ID 或钉钉教育 `class_id`。
+- `isHeadTeacher`：布尔值；`true` 只返回班主任，`false` 只返回普通任课老师。
+- `page`、`pageSize`；`pageSize` 最大为 100。
+
 ## App Function
 
 App Function、Automation 或 Workflow 中需要复用关系时，调用对应的受控后端桥接：
@@ -112,10 +139,24 @@ export default async function(ctx, input) {
 }
 ```
 
+查询某位老师担任班主任的班级：
+
+```ts
+export default async function(ctx, input) {
+  return await ctx.organization.schoolContact.teachers.list({
+    userId: input.teacherUserId,
+    isHeadTeacher: true,
+    page: 1,
+    pageSize: 100,
+  })
+}
+```
+
 对应方法为：
 
 ```ts
 ctx.organization.schoolContact.relations.list(params)
+ctx.organization.schoolContact.teachers.list(params)
 ctx.organization.schoolContact.children.list(userId, params)
 ctx.organization.schoolContact.guardians.list(userId, params)
 ctx.organization.schoolContact.myFamily.get(params)
@@ -155,6 +196,24 @@ interface SchoolContactRelation {
 }
 ```
 
+老师班级成员的返回项为：
+
+```ts
+interface SchoolContactTeacherMembership {
+  membershipId: string
+  teacher: {
+    userId: string
+    dingtalkUserId: string
+    name: string
+    mobile: string | null
+  }
+  class: SchoolContactRelation["class"]
+  isHeadTeacher: boolean
+  syncedAt: string
+  syncState: "current" | "not_synced" | "disabled"
+}
+```
+
 手机号可能为空。`sync.state=disabled` 表示管理员关闭了后续同步，现有数据仍保留但可能过期；业务页面在对时效敏感时应展示 `lastSuccessfulSyncAt`。
 
 ## 持久化边界

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

@@ -36,7 +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`，声明家校关系读取权限并保持服务端分页。
+- ✅ 家长、学生、教师、班主任身份或班级/监护关系页面使用 `sdk.organization.schoolContact.*`；先读 `references/school-contact-relations.md`。用 `SCHOOL_HEAD_TEACHER` 判断全局身份，用 `teachers.list({ classId, isHeadTeacher: true })` 判断具体班主任班级；默认使用已登录用户的租户内全部关系，仅在业务要求时声明 self/class 收紧范围，并保持服务端分页。
 - ✅ 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.
@@ -132,7 +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` 读取；不要直连钉钉、查询系统表或用同班成员推断亲属关系。
+- 家校关系必须通过 `sdk.organization.schoolContact` / `ctx.organization.schoolContact` 读取；班主任班级使用 `teachers.list` 的 `isHeadTeacher`，不要用全局角色推断具体班级，也不要直连钉钉、查询系统表或用同班成员推断亲属关系。
 - 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.262",
+  "version": "1.0.264",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {