openxiangda-skill-kit 2.0.0-alpha.38 → 2.0.0-alpha.41

package/docs/architecture/school-contact-default-access-v2.md

@@ -0,0 +1,13 @@
+# School-contact default access v2
+
+## Decision
+
+- Problem evidence: the product contract says an authenticated application user defaults to the unrestricted tenant-local school-contact scope, while `OpenXiangdaSchoolContactV2Service.resolveAccess` currently denies a valid Principal when its active RoleSession has no explicit school-contact capability.
+- Capability owner: the platform school-contact service owns relation data-scope resolution. The Native authorization kernel remains the owner of Principal and RoleSession verification and is not bypassed or duplicated.
+- Stable invariants: platform identity codes remain descriptive claims rather than switchable application roles; tenant, application, environment, Principal, RoleSession, pagination, and query enforcement remain server-verified.
+- Contract: a verified non-guest Principal with no explicit school-contact scope defaults to `all`. Explicit `read`, `class:read`, and `self:read` resolve in the order `all > class > self`, allowing an application role to narrow the default. Invalid or missing Principal/RoleSession continues to fail before data access.
+- Failure and concurrency: authorization errors propagate unchanged; access resolution is read-only and introduces no cache, retry, queue, lock, or cross-request state.
+- Security and resource bounds: the default applies only after the existing v2 authentication and RoleSession boundary and never relaxes tenant/application isolation. The broader authenticated-user visibility is the explicitly accepted product policy.
+- Affected contracts: the typed NestJS school-contact client and response types do not change. Only the default scope selected by the platform service changes.
+- Rollback: code and documentation rollback only; there is no migration or persisted authorization rewrite.
+- Falsifiable verification: tests prove default `all`, explicit `class`/`self`, widest-capability precedence, and fail-closed missing Principal evidence; `pnpm verify:affected` must pass.

package/docs/architecture/school-contact-head-teacher-v2.md

@@ -0,0 +1,10 @@
+# School-contact head-teacher contract v2
+
+- Problem evidence: DingTalk returns head-teacher status only as `teacher` membership `feature.is_adviser`; the platform stores it but the Native school-contact API currently exposes only guardian/student relations and the three broad platform identities.
+- Capability owner: the platform organization service remains the sole owner of synchronized membership facts and `platformRoleCodes`. A 2.0 application reads them through the typed NestJS platform client and exposes its own App API; React never calls the platform endpoint directly.
+- Stable invariants: `SCHOOL_HEAD_TEACHER` is additive to `SCHOOL_TEACHER`; it means the user heads at least one current class and cannot identify which class. Exact class membership comes from `querySchoolContactTeachers` and `isHeadTeacher`. No application-local copy or fourth DingTalk source role is introduced.
+- Affected contracts: `openxiangda-nest` adds typed teacher/class query, record and page contracts plus `querySchoolContactTeachers`. Skills, docs and the standard template explain the global-role versus class-relation boundary. Existing guardian/student APIs are unchanged.
+- Failure and concurrency: the client is a bounded read using the verified authorization and RoleSession. It adds no retry, cache, queue, mutable state or browser credential exposure; platform sync retains its existing complete-snapshot transaction and tenant lock.
+- Security and resource bounds: the platform enforces tenant, app, RoleSession and all/self/class scope. Responses contain platform user ID, DingTalk userid, name and nullable mobile; applications return only fields needed by their App API and must not log full responses. Page size remains capped at 100.
+- Rollback boundary: the Nest method, docs and template are independently removable. The additive platform identity and migration may remain after an SDK rollback. Existing 1.x applications and other 2.0 methods ignore the new contract.
+- Falsifiable verification: typed tests must prove the exact `/school-contact/teachers` request, RoleSession headers and boolean serialization; package checks and `pnpm verify:affected` pass; Skills validation names both `SCHOOL_HEAD_TEACHER` and `teachers.list`/`querySchoolContactTeachers` without suggesting browser direct access.

package/docs/architecture/standard-surface-runtime-corrections-v2.md

@@ -0,0 +1,108 @@
+# Standard surface runtime corrections v2
+
+Status: accepted for implementation on 2026-08-20.
+
+## Problem evidence
+
+- Standard Admin filters send scalar `eq` predicates for stable JSON option and
+  directory values. PostgreSQL rejects values such as `software` as invalid
+  JSON with SQLSTATE `22P02`.
+- A department field is rendered by the platform field kit in forms, but its
+  search value is not normalized with the same field contract before a Data
+  API query is created.
+- Admin tabs persist path metadata while the active Umi `Outlet` is unmounted
+  on every navigation. Returning to a tab therefore recreates and reloads the
+  page. Query-string changes do not have an explicit page-instance invalidation
+  key.
+- The official mobile application shell explicitly contributes a role switcher
+  even though this surface is the normal end-user entry.
+- The procurement reference workflow binds department approval to an
+  application role scope. The configured platform organization department
+  supervisor is therefore not consulted.
+- Native clients request the durable record audit endpoint at
+  `/native/data/:resource/records/:id/audit`, but the Native Data controller has
+  no matching route. Desktop and mobile detail pages load data and audit in one
+  request group, so the missing audit route makes the whole detail page fail.
+- The desktop end-user workflow submission route removes primary navigation
+  without contributing a back action.
+
+## Capability owners
+
+- `openxiangda-admin` owns standard search-value normalization, tab metadata,
+  and bounded mounted page instances.
+- `openxiangda-field-kit` remains the owner of department and other platform
+  field controls and stable values; no application-specific selector is added.
+- Native Data API owns durable business-audit reads and row/field enforcement.
+- Platform organization data and `department_supervisor` resolution are the
+  only owners of configured department supervisors.
+- `openxiangda-user` owns standard desktop submission navigation affordances;
+  the application supplies the destination.
+- The application template owns which optional controls appear on its mobile
+  shell and which workflow provider its domain workflow selects.
+
+## Stable invariants and affected contracts
+
+1. Data API remains the only business-record store and query boundary. Stable
+   directory and option values keep their existing `{ label, value }` shapes.
+2. Search predicates for those values use JSON containment; text, dates,
+   numbers, booleans, and physical scalar identifiers keep their current
+   operators.
+3. Tabs, mounted page instances, query responses, and drafts remain separate
+   state. At most twelve tabs and six mounted pages are retained per identity.
+4. A tab is identified by pathname. A change to that pathname's search/hash
+   location key remounts the active page and therefore reloads URL-bound data.
+5. Identity epoch changes discard every mounted instance. Closing or LRU
+   eviction discards only the affected instance; the persisted tab may remain.
+6. Native audit returns the existing `openxiangda.data-audit-page/v2`
+   contract. No second application audit API or database is introduced.
+7. Native audit rechecks the current role's resource capability, row policy,
+   and field policy before returning each durable outbox event.
+8. Mobile RoleSession behavior is unchanged; only the visible top-level role
+   switch button is removed from the standard user template.
+9. Workflow Kernel contracts do not change. The reference binding selects the
+   already-supported `department_supervisor` provider with `departmentId`
+   facts.
+10. OpenXiangda 1.x applications and runtime contracts are not affected.
+
+## Failure, concurrency, security, and resource bounds
+
+- Invalid or unreadable search fields still fail closed at Data API. The Admin
+  never falls back to browser filtering.
+- Cached pages are hidden but remain mounted. LRU eviction is deterministic and
+  bounded to six instances; identity changes synchronously invalidate the pool.
+- A changed URL location key replaces only the active cached instance. Stale
+  requests remain guarded by each standard page's request generation.
+- Audit pagination is bounded, reads at most 500 matching durable events, and
+  omits events whose record snapshot no longer passes the current row policy.
+- Audit is read-only and introduces no lock, receipt, retry loop, or mutable
+  application state.
+- Department supervisor resolution remains tenant-scoped and uses the existing
+  organization service. Empty resolution continues to fail closed.
+
+## Rollback boundary
+
+- Platform rollback is the previous platform-server image; no SQL migration is
+  required.
+- Frontend rollback is the previous independently published package set.
+- Application rollback is the previous immutable preproduction AppVersion.
+- No compatibility switch or duplicate endpoint is kept after rollback.
+
+## Falsifiable verification
+
+1. Admin tests prove department search uses the Field Kit control and stable
+   option/directory values compile to JSON containment rather than scalar `eq`.
+2. Admin lifecycle tests prove switching between two tabs preserves component
+   state, the seventh cacheable page evicts the least recently used instance,
+   closing a tab unmounts it, identity changes clear all instances, and a query
+   change remounts the active instance.
+3. Native Data tests prove the audit route exists, returns masked durable
+   history, enforces current row policy, and supports bounded pagination.
+4. Workflow tests/config checks prove a configured platform department
+   supervisor resolves for `department-review` without an application-managed
+   department membership.
+5. Mobile Chromium has no role button and can open a purchase detail page.
+6. Desktop Chromium can return from the standalone submission page and URL
+   query changes reload the appropriate page.
+7. Platform `verify:openxiangda-v2:release`, toolchain `verify:release`, and the
+   standard application's generate/check/test/build gates pass before a new
+   preproduction deployment is activated.

package/docs/architecture/workflow-participant-surface-v2.md

@@ -0,0 +1,198 @@
+# Workflow participant surface v2
+
+Status: accepted for implementation on 2026-08-20.
+
+## Problem evidence
+
+- The standard purchase form already persists the selected department and
+  submits `departmentId` as a workflow fact, while the workflow definition also
+  asks the initiator to choose a submission department. The confirmation
+  surface therefore repeats a decision the user has already made and exposes a
+  second "resolve approval path" click.
+- Department supervisor resolution returns valid user identifiers without
+  display names. A node with four supervisors is rendered as four identical
+  unresolved placeholders even though assignment succeeded.
+- Workflow preview already contains its canonical end node. Admin, desktop user,
+  and mobile user renderers append another synthetic completion node.
+- Task surfaces project only a subset of their owning instance, omitting
+  `startedAt` and `completedAt`. The timeline endpoint returns command logs only,
+  so a newly started instance has no visible process history and no future-node
+  preview.
+- A department supervisor can be frozen into a workflow task by user identity
+  without owning an application role membership. Native RoleSession bootstrap
+  stops at `unassigned` before the Workflow Kernel can apply its existing
+  task/instance participant authorization.
+
+## Capability owners
+
+- Native RoleSession remains the only owner of the active human runtime
+  identity. It may expose one reserved `workflow_participant` subject when the
+  user is an initiator or participant in this application's environment.
+- Workflow Kernel remains the only owner of task assignment, instance access,
+  commands, node state, timestamps, and immutable operation logs.
+- Native Data remains the owner of physical business records. Workflow Surface
+  may request one revision-bound record for an already-authorized instance and
+  project only fields visible under the workflow field policy.
+- Workflow Definition and Binding remain the only owners of path shape and
+  assignee resolution. Renderers do not infer workflow transitions.
+- Admin and user renderers own only presentation and automatic re-prepare after
+  all required answers are present.
+
+## Stable invariants and affected contracts
+
+1. A business form's explicit department fact is used directly by a
+   `department_supervisor` binding. The reference workflow does not ask for a
+   second organization-context department.
+2. `prepare-start` remains revision-bound and side-effect free. When genuine
+   requirements remain, changing a complete answer set automatically requests a
+   new preparation; starting still requires a ready preparation token and one
+   explicit confirmation.
+3. Candidate identifiers and assignment semantics do not change. The platform
+   adds directory display names when they are available, and renderers fall back
+   to a concise assignee count instead of repeating unresolved labels.
+4. A canonical end node is the sole completion step. A synthetic completion
+   step is added only when a preview has no end node.
+5. Workflow timeline adds a deterministic `flow` projection containing submit,
+   planned nodes, node visit state, assignees, and lifecycle timestamps. Existing
+   immutable command logs remain available as `items`.
+6. Task Surface returns the complete public instance lifecycle projection and a
+   field-policy-filtered `presentation.businessData` record when the DataRef is
+   valid. The client does not need ordinary Data API read capability to render
+   an assigned approval.
+7. The reserved `workflow_participant` RoleSession has zero application
+   capabilities and no data scopes. It does not create an application role or
+   membership. Workflow endpoints still authorize every task, instance,
+   work-center row, timeline, and command from stored participation.
+8. `workflow_participant` cannot prepare or start a workflow and cannot call
+   ordinary Data/App APIs. Existing membership and super-admin behavior is
+   unchanged.
+9. OpenXiangda 1.x, unrelated tenants, and existing production AppVersions do
+   not consume these 2.0 contracts.
+
+## Failure, concurrency, security, and resource bounds
+
+- Automatic re-prepare is generation-guarded; a later answer change wins and a
+  stale response cannot replace the current preparation token.
+- RoleSession creation and switching keep the existing serializable transaction,
+  single-active-session rule, expiry, Head revision binding, and CAS behavior.
+- The reserved subject exists only while a matching workflow instance or task
+  participation row exists in the same tenant, application, environment, and
+  user identity. It is invalidated by the normal bootstrap/context checks when
+  that relation disappears.
+- Workflow instance, task, timeline, and business-data reads fail closed unless
+  the caller is the initiator, a stored participant, or the application super
+  admin. Completed participants retain read-only history access; only an active
+  task assignment receives command operations.
+- Timeline planning uses the activated immutable definition and frozen fact
+  snapshot. It is bounded by the existing 200-step planner limit. Business-data
+  projection reads exactly one referenced record and never enables list queries.
+
+## Rollback boundary
+
+- Platform rollback uses the previous platform-server image plus the down
+  section of the additive RoleSession subject-kind SQL migration.
+- Frontend and contract rollback uses the previous independently published
+  OpenXiangda 2.0 package versions.
+- Reference application rollback uses the previous immutable preproduction
+  AppVersion. No compatibility flag or duplicate authorization store remains.
+
+## Falsifiable verification
+
+1. Reference workflow tests prove that the department selected in the business
+   form is the only department input and resolves the configured platform
+   supervisor.
+2. Admin, desktop user, and mobile user tests prove answer changes re-prepare
+   automatically, real assignee names render, and previews contain one terminal
+   node.
+3. Platform tests prove task Surface carries start/completion timestamps and
+   field-policy-filtered business data, while timeline returns submit, complete,
+   active, and waiting node states plus immutable command logs.
+4. A user with no application membership but an assigned department-supervisor
+   task receives a `workflow_participant` RoleSession, can open and operate that
+   task, can view the instance history after completion, and cannot prepare a
+   new workflow or read ordinary Data API records.
+5. Users with no application role and no workflow relationship remain
+   `unassigned`; membership, multi-role selection, and super-admin tests remain
+   unchanged.
+6. Platform OpenXiangda v2 release verification, toolchain affected/release
+   verification, reference application generate/check/test/build, and desktop
+   plus mobile Chromium approval paths pass before preproduction activation.
+
+## Release-gate correction: local department supervisor resolution
+
+The first formal packed-distribution run failed in the fresh PostgreSQL
+application at `department-review` with
+`WORKFLOW_V2_APPROVER_RESOLUTION_EMPTY`. Production correctly delegates this
+provider to platform organization data, but the local platform adapter still
+expected every approval binding to carry an application `roleCode`; the
+standard `department_supervisor` binding intentionally has none.
+
+- Ownership and contracts remain unchanged: production organization data owns
+  configured supervisors, while the local adapter only emulates that provider
+  from the fixture's `department_manager` membership and department approval
+  scope.
+- The local adapter must require the binding's `departmentIdFrom` fact and a
+  matching `department` scope grant with `approve` (or `*`). Missing facts,
+  roles, or scope continue to fail closed with the existing resolution error.
+- No new state store, public API, environment branch, concurrency behavior, or
+  production authorization path is introduced. Rollback is the previous
+  `openxiangda-local-platform` package.
+- Unit verification covers both a matching and a non-matching department, and
+  the packed fresh-application PostgreSQL lifecycle must resolve the same
+  `department-review` node before this candidate can be published.
+
+## Release-gate correction: persistent delegation policy
+
+The next packed-distribution run resolved the department supervisor correctly,
+but PostgreSQL start rejected the direct assignment with
+`WORKFLOW_V2_PREPARATION_ASSIGNMENT_CHANGED`. The local assignment owner had
+correctly ignored an unrelated long-term delegation, while the transaction
+guard still queried delegation rules for every provider.
+
+- The activated workflow binding remains the sole owner of whether long-term
+  delegation applies. The local platform passes that resolved policy into the
+  PostgreSQL transaction; the store does not infer provider semantics.
+- Delegatable nodes retain the existing delegator lock, active-rule query, and
+  frozen participant comparison so a concurrent rule change still invalidates
+  preparation. Non-delegatable nodes validate a direct primary participant and
+  deliberately do not consult or lock unrelated delegation rules.
+- No public contract, persisted document, production provider, application
+  identity, or business-data path changes. The rollback boundary is the prior
+  `openxiangda-local-platform` package, and 1.x applications, other tenants,
+  and already deployed AppVersions remain outside the blast radius.
+- Verification must keep an active department-manager delegation present while
+  a `department_supervisor` preparation starts directly in the real local
+  PostgreSQL lifecycle. Its add-sign target remains a second explicit,
+  in-scope department-manager identity; the test must not widen the current
+  node to a finance role. Existing delegatable-node concurrency and snapshot
+  tests must continue to pass.
+
+## Release-gate correction: department supervisor participant targets
+
+The formal packed-distribution lifecycle then reached the explicit after-add-sign
+command, but the local platform rejected the second department-manager identity
+with `WORKFLOW_V2_TARGET_ROLE_SUBJECT_INVALID`. Initial assignee resolution
+already derived the implicit `department_manager` role and required the selected
+department's approval scope; participant-target validation still read only an
+explicit binding `roleCode`, which `department_supervisor` intentionally omits.
+
+- The activated Workflow binding remains the only owner of target eligibility.
+  The local adapter must apply the same implicit `department_manager` role,
+  `departmentIdFrom` fact, and `department` `approve` (or `*`) scope check to
+  transfer, delegate, and add-sign targets that it applies to the original
+  department-supervisor assignment.
+- Missing department facts, a different application role, an out-of-scope
+  department, an expired local target, or an unknown RoleSubject continues to
+  fail closed with the existing target-validation error. No fallback role or
+  second resolver is introduced.
+- Public Workflow contracts, remote provider behavior, participant persistence,
+  task/instance CAS, idempotency receipts, and concurrency behavior are
+  unchanged. Validation remains a bounded scan of declared local fixture roles
+  and scope grants and does not add remote calls or mutable state.
+- The rollback boundary is the prior `openxiangda-local-platform` package.
+  OpenXiangda 1.x, other tenants, production platform authorization, and already
+  deployed AppVersions remain outside the blast radius.
+- A focused local-platform test must accept a same-role target for the selected
+  department and reject the same target for another department. The full packed
+  PostgreSQL lifecycle must complete add-sign, restart recovery, and subsequent
+  approvals before this candidate can be published.

package/docs/data-authz.md

@@ -2,7 +2,7 @@
 
 2.0 权限由 RBAC 与上下文数据策略共同组成：角色回答“可以做什么”，策略回答“在当前角色下可以对哪些数据和字段做”。
 
-家校关系使用相同的活动角色边界。默认授予 `app:<appCode>:school-contact:read`，范围为不限制的 `all`；需要收紧时改授 `self:read` 或 `class:read`，范围由平台在查询中强制执行，页面不能靠客户端过滤。见[家校通讯录关系](./school-contact-relations.md)。
+家校关系使用相同的活动角色边界。有效 Principal/RoleSession 未声明任何 `school-contact:*` 范围能力时默认使用不限制的 `all`；需要收紧时显式授予 `self:read` 或 `class:read`，范围由平台在查询中强制执行，页面不能靠客户端过滤。应用自己的 App API 仍必须使用正常的业务操作 capability。见[家校通讯录关系](./school-contact-relations.md)。
 
 ## 请求模型
 
@@ -72,6 +72,8 @@ authz: {
 
 `roleCodes` 把一条数据规则限定到当前 `RoleSession` 选中的角色。同一用户同时是申请人、学院管理员时，切换到学院管理员后，`applicant` 的 `current_user` 规则不再参与 OR 计算。多角色应用的角色特有规则必须声明 `roleCodes`；未声明时表示该规则对所有活动角色通用。编译器会拒绝空数组、重复或未声明的角色代码。
 
+平台家校身份是另一条只读维度：使用 `platformRoleCodes`（`SCHOOL_GUARDIAN`、`SCHOOL_STUDENT`、`SCHOOL_TEACHER`、`SCHOOL_HEAD_TEACHER`）表达家长、学生、老师、班主任，不把它们塞进应用 `roleCodes`。班主任同时保留老师身份；`SCHOOL_HEAD_TEACHER` 只表达“至少担任一个班的班主任”，具体班级必须通过老师班级关系的 `isHeadTeacher` 判断。这些编码由平台家校同步维护并在可信 Principal/RoleSession context 中返回；默认不增加数据限制，应用只有在明确需要时才在 App API 服务端做身份条件判断。浏览器请求中的同名字段不是授权凭据，不能用于放行。
+
 角色成员、学院范围授权和“用户—仪器”关系授权属于环境运行数据，不进入不可变应用包。它们通过 Native 管理 API 维护，部署新版本不会删除。所有写操作要求 UUID `operationId`、目标资源 revision 和活动管理 RoleSession；平台在数据库事务内完成权限复核、幂等回执、CAS、相关会话撤销与审计。
 
 新应用由 `openxiangda app provision` 为创建者建立平台保留的 `platform.app-super-admin` grant。它不是应用包中的普通角色，不能被业务流程代理或通过多个角色合并获得。重复执行 provision 会复用同一个 grant，可用于补齐早期创建但尚未初始化 Native 管理员的 2.0 应用。

package/docs/school-contact-relations.md

@@ -4,6 +4,28 @@
 
 ## 数据合同
 
+### 平台内置身份角色
+
+成功的家校全量同步会维护平台层身份角色（不属于应用 `RoleSession` 的可切换角色）：
+
+| 展示名 | 稳定编码 | 来源 |
+| --- | --- | --- |
+| 家长 | `SCHOOL_GUARDIAN` | 家校成员 `guardian` |
+| 学生 | `SCHOOL_STUDENT` | 家校成员 `student` |
+| 老师 | `SCHOOL_TEACHER` | 家校成员 `teacher` |
+| 班主任 | `SCHOOL_HEAD_TEACHER` | 至少一个老师班级成员带 `is_adviser=true` |
+
+身份可组合，同一用户可以同时拥有多个编码。2.0 的 `NativePrincipal` / `Principal` 和 `RoleSessionContext` 以可选的 `platformRoleCodes` 暴露这些编码；它们只用于业务身份判断，不能替代当前应用角色、不能参与 `roleCodes` 的切换，也不能由浏览器提交。权限默认不限制，应用若需要按身份限制页面或 App API，应在服务端使用这些可信编码显式校验。
+
+```ts
+const isTeacher =
+  request.openxiangda?.principal.platformRoleCodes?.includes('SCHOOL_TEACHER')
+```
+
+`SCHOOL_HEAD_TEACHER` 表示此人至少在一个当前班级担任班主任，并不能说明具体班级。班主任同时保留 `SCHOOL_TEACHER`。需要判断具体班级时，使用下方 `querySchoolContactTeachers` 返回的 `isHeadTeacher`。
+
+应用开发者不直接写 `roles` 绑定，也不在本地复制同步结果；下一次完整同步会自动增删平台身份绑定。
+
 平台同步钉钉家校通讯录后，以只读关系返回监护人、学生和班级。关系两端都包含：
 
 - `userId`：平台用户 ID，业务数据应保存这个稳定标识；
@@ -15,15 +37,15 @@
 
 ## 权限与默认范围
 
-应用在 `openxiangda.config.ts` 声明需要的能力，并把其中一种能力授予角色：
+通过既有认证和 `RoleSession` 校验的非游客用户，在没有声明任何 `school-contact:*` 范围能力时，平台默认使用 `all`，可以查看当前租户全部已同步关系。应用自己的 App API 仍按正常方式声明业务操作能力，例如：
 
 ```ts
 authz: {
   capabilities: [
     {
-      code: 'app:school-service:school-contact:read',
+      code: 'app:school-service:family:read',
       kind: 'backend',
-      name: '读取全部家校关系',
+      name: '使用家庭关系功能',
     },
     {
       code: 'app:school-service:school-contact:self:read',
@@ -40,13 +62,13 @@ authz: {
     {
       code: 'user',
       name: '普通用户',
-      capabilities: ['app:school-service:school-contact:read'],
+      capabilities: ['app:school-service:family:read'],
     },
   ],
 }
 ```
 
-应用自己的查询接口也要进入不可变 App API 合同，并复用同一个能力：
+应用自己的查询接口进入不可变 App API 合同并使用业务操作能力：
 
 ```ts
 backend: {
@@ -55,7 +77,7 @@ backend: {
       code: 'family.mine',
       method: 'GET',
       path: '/api/family/mine',
-      capability: 'app:school-service:school-contact:read',
+      capability: 'app:school-service:family:read',
       requestSchema: { type: 'object', additionalProperties: false },
       responseSchema: { type: 'object' },
     },
@@ -63,7 +85,7 @@ backend: {
 }
 ```
 
-默认配置使用 `school-contact:read`，数据范围是 `all`，即不限制，可以查看全部已同步关系。只有业务明确需要最小化可见范围时，才把角色改为 `self:read` 或 `class:read`。同一角色同时获得多个能力时按 `all > class > self` 取最宽范围，避免前后端对范围产生不同解释。
+未给活动角色授予任何 `school-contact:*` 范围能力时，数据范围就是 `all`，不限制，可以查看全部已同步关系。只有业务明确需要最小化可见范围时，才给角色增加 `self:read` 或 `class:read`；可选的 `school-contact:read` 表示显式保持 `all`。同一角色同时获得多个范围能力时按 `all > class > self` 取最宽范围，避免前后端对范围产生不同解释。无有效 Principal/RoleSession、游客和跨租户请求仍然拒绝。
 
 ## NestJS App API
 
@@ -75,7 +97,7 @@ import {
   OpenXiangdaOperation,
   OpenXiangdaPlatformClient,
 } from 'openxiangda-nest';
-import { Controller, Get, Req } from '@nestjs/common';
+import { Controller, Get, Param, Req } from '@nestjs/common';
 import { appOperations } from '@app/contracts';
 
 @Controller('/api/family')
@@ -92,18 +114,35 @@ export class FamilyController {
       { page: 1, pageSize: 50 }
     );
   }
+
+  @Get('/classes/:classId/head-teachers')
+  @OpenXiangdaOperation(appOperations.familyMine)
+  async headTeachers(
+    @Req() request: OpenXiangdaHttpRequest,
+    @Param('classId') classId: string,
+  ) {
+    const context = request.openxiangda!;
+    return await this.platform.querySchoolContactTeachers(
+      context.authorization,
+      context.roleSessionId!,
+      { classId, isHeadTeacher: true, page: 1, pageSize: 100 }
+    );
+  }
 }
 ```
 
 可用方法：
 
 - `querySchoolContactRelations(authorization, roleSessionId, query)`：按平台用户 ID、手机号、钉钉 userid、姓名、班级或关系类型分页检索；
+- `querySchoolContactTeachers(authorization, roleSessionId, query)`：按老师的平台用户 ID、手机号、钉钉 userid、姓名、班级和 `isHeadTeacher` 分页检索老师班级成员；
 - `schoolContactChildren(..., userId, query)`：查询指定监护人的学生；
 - `schoolContactGuardians(..., userId, query)`：查询指定学生的监护人；
 - `mySchoolContactFamily(...)`：同时查询当前用户作为监护人和学生的两个方向。
 
 应用前端用 `useOpenXiangdaAdmin().appApi()` 调用上面的 App API。不要把登录 token、RoleSession ID、平台 URL 或完整关系快照放入浏览器缓存；手机号只展示给确有业务需要的页面，日志不得记录手机号和完整返回体。
 
+老师成员返回 `teacher`（`userId`、`dingtalkUserId`、`name`、可空 `mobile`）、`class`、布尔值 `isHeadTeacher`、`syncedAt` 和 `syncState`。查询某班班主任使用 `{ classId, isHeadTeacher: true }`；不要只用 `SCHOOL_HEAD_TEACHER` 推断班级。
+
 ## 失效与降级
 
 - `sync.state = disabled`：租户未开启后续同步，历史关系仍可能存在；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.38",
+  "version": "2.0.0-alpha.41",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.0.0-alpha.27"
+    "openxiangda-devkit-core": "2.0.0-alpha.29"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/openxiangda-v2/SKILL.md

@@ -39,8 +39,13 @@ For a new repository, link it to the target platform and let an authorized platf
 - Build one immutable application package; the platform owns deployment execution, health gates, promotion, and rollback.
 - Reject any workspace that does not declare the native 2.0 application configuration.
 - Read school-contact relationships only through a NestJS App API bound to the
-  active RoleSession. The default relation scope is unrestricted; narrower
-  self/class access must be an explicit authorization decision.
+  active RoleSession. A verified non-guest Principal defaults to unrestricted
+  `all` without a school-contact scope capability; narrower self/class access
+  must be an explicit authorization decision. The App API still requires its
+  normal business-operation capability.
+- Treat `SCHOOL_HEAD_TEACHER` as a global platform identity only. Resolve the
+  exact class through `querySchoolContactTeachers(..., { isHeadTeacher: true })`;
+  never infer a class from the role code or call the platform from React.
 
 ## Delivery Gate
 

package/skills/openxiangda-v2-backend/SKILL.md

@@ -24,6 +24,10 @@ Build a normal NestJS service in `apps/server`. The platform deploys one contain
    the NestJS backend with the verified authorization and RoleSession. Expose
    only an application App API to the browser; never call the platform relation
    endpoint from React.
+10. A head teacher keeps `SCHOOL_TEACHER` and additionally receives
+    `SCHOOL_HEAD_TEACHER`. Use `querySchoolContactTeachers` and its
+    `isHeadTeacher` field for the exact class; the global role alone is not a
+    class authorization fact.
 
 ## Runtime Path
 

package/skills/openxiangda-v2-data-authz/SKILL.md

@@ -27,10 +27,21 @@ Model permissions as capability checks plus contextual data predicates. A role g
 - Require the application directory capability before using department or user
   selectors. Store stable IDs and resolve display labels through Directory v2;
   do not copy tenant contact data into application records.
-- School-contact access defaults to the unrestricted `school-contact:read`
-  capability. Use `school-contact:self:read` or
+- School-contact access defaults to unrestricted `all` for a verified
+  non-guest Principal/RoleSession even when no `school-contact:*` scope
+  capability is assigned. Use `school-contact:self:read` or
   `school-contact:class:read` only when the product explicitly requires a
-  narrower scope; rely on the platform query boundary, not browser filtering.
+  narrower scope; keep the application's own App API behind its normal
+  business-operation capability and rely on the platform query boundary, not
+  browser filtering.
+- The synchronized platform identities `SCHOOL_GUARDIAN`, `SCHOOL_STUDENT`,
+  `SCHOOL_TEACHER`, and `SCHOOL_HEAD_TEACHER` are additive `platformRoleCodes` on the trusted
+  Principal/RoleSession context, not selectable application `roleCodes`.
+  They are maintained by the platform sync and are unrestricted by default;
+  use them only for an explicit server-side identity check.
+- `SCHOOL_HEAD_TEACHER` means the user heads at least one current class and is
+  additive to `SCHOOL_TEACHER`. Authorize the exact class from the platform
+  teacher-membership result `isHeadTeacher`, never from the global role alone.
 - Apply field policies consistently to queries, search controls, forms, CSV
   transfer and restricted transactions.
 - Use the bounded server-side aggregate endpoint for charts and summaries. Only
@@ -47,4 +58,4 @@ Run `openxiangda check` and `openxiangda test` after every policy or schema chan
 
 Read [Data and Authorization](../../docs/data-authz.md) for policy examples and
 [School contact relations](../../docs/school-contact-relations.md) for the
-guardian/student contract.
+guardian/student and teacher/class contracts.