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

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/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

@@ -72,7 +72,7 @@ authz: {
 
 `roleCodes` 把一条数据规则限定到当前 `RoleSession` 选中的角色。同一用户同时是申请人、学院管理员时，切换到学院管理员后，`applicant` 的 `current_user` 规则不再参与 OR 计算。多角色应用的角色特有规则必须声明 `roleCodes`；未声明时表示该规则对所有活动角色通用。编译器会拒绝空数组、重复或未声明的角色代码。
 
-平台家校身份是另一条只读维度：使用 `platformRoleCodes`（`SCHOOL_GUARDIAN`、`SCHOOL_STUDENT`、`SCHOOL_TEACHER`）表达家长、学生、老师，不把它们塞进应用 `roleCodes`。这些编码由平台家校同步维护并在可信 Principal/RoleSession context 中返回；默认不增加数据限制，应用只有在明确需要时才在 App API 服务端做身份条件判断。浏览器请求中的同名字段不是授权凭据，不能用于放行。
+平台家校身份是另一条只读维度：使用 `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、相关会话撤销与审计。
 

package/docs/school-contact-relations.md

@@ -13,6 +13,7 @@
 | 家长 | `SCHOOL_GUARDIAN` | 家校成员 `guardian` |
 | 学生 | `SCHOOL_STUDENT` | 家校成员 `student` |
 | 老师 | `SCHOOL_TEACHER` | 家校成员 `teacher` |
+| 班主任 | `SCHOOL_HEAD_TEACHER` | 至少一个老师班级成员带 `is_adviser=true` |
 
 身份可组合，同一用户可以同时拥有多个编码。2.0 的 `NativePrincipal` / `Principal` 和 `RoleSessionContext` 以可选的 `platformRoleCodes` 暴露这些编码；它们只用于业务身份判断，不能替代当前应用角色、不能参与 `roleCodes` 的切换，也不能由浏览器提交。权限默认不限制，应用若需要按身份限制页面或 App API，应在服务端使用这些可信编码显式校验。
 
@@ -21,6 +22,8 @@ const isTeacher =
   request.openxiangda?.principal.platformRoleCodes?.includes('SCHOOL_TEACHER')
 ```
 
+`SCHOOL_HEAD_TEACHER` 表示此人至少在一个当前班级担任班主任，并不能说明具体班级。班主任同时保留 `SCHOOL_TEACHER`。需要判断具体班级时，使用下方 `querySchoolContactTeachers` 返回的 `isHeadTeacher`。
+
 应用开发者不直接写 `roles` 绑定，也不在本地复制同步结果；下一次完整同步会自动增删平台身份绑定。
 
 平台同步钉钉家校通讯录后，以只读关系返回监护人、学生和班级。关系两端都包含：
@@ -94,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')
@@ -111,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.39",
+  "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.28"
+    "openxiangda-devkit-core": "2.0.0-alpha.29"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/openxiangda-v2/SKILL.md

@@ -43,6 +43,9 @@ For a new repository, link it to the target platform and let an authorized platf
   `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

@@ -35,10 +35,13 @@ Model permissions as capability checks plus contextual data predicates. A role g
   business-operation capability and rely on the platform query boundary, not
   browser filtering.
 - The synchronized platform identities `SCHOOL_GUARDIAN`, `SCHOOL_STUDENT`,
-  and `SCHOOL_TEACHER` are additive `platformRoleCodes` on the trusted
+  `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
@@ -55,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.