openxiangda 1.0.264 → 1.0.266

package/README.md

@@ -1,4 +1,5 @@
 <!-- OpenXiangda-Policy-Version: 7 -->
+
 # OpenXiangda
 
 OpenXiangda is a lightweight CLI and skill package for private low-code platforms.
@@ -106,6 +107,10 @@ openxiangda resource plan function --only customer_get,customer_save --profile d
 openxiangda sdd bundle mainline-release --changes add-customer-page,fix-customer-api
 # verify, wait for the lease, stage exact children, atomically finalize, and release
 openxiangda release publish --change mainline-release --profile dev
+# 仅限平台已核验的旧式多历史 lineage、精确非删除恢复
+openxiangda release publish --change mainline-release --profile dev \
+  --adopt-online-baseline \
+  --adoption-reason "已合入主线的目标来自多次历史发布，无法对应单一 Git 基线"
 openxiangda release status --change mainline-release --watch
 openxiangda release explain --change mainline-release --profile dev
 # 环境托管应用一次性登记（已有应用通常作为 preproduction）
@@ -361,7 +366,7 @@ The dev host also calls the backend runtime route resolver for the current `/vie
 Built-in route defaults come from the `openxiangda` SDK: `StandardFormPage`, `FormSubmitTemplate`, `FormDetailTemplate`, `ProcessDetailTemplate`, and `DataManagementList`. Workspaces can override whole built-in pages from `src/runtime/builtin-overrides.tsx`; exact `formUuid` entries win before the `*` fallback.
 
 ```tsx
-import type { BuiltinRouteOverrides } from "openxiangda/runtime"
+import type { BuiltinRouteOverrides } from "openxiangda/runtime";
 
 export const runtimeRouteOverrides: BuiltinRouteOverrides = {
   "form-submit": {
@@ -371,7 +376,7 @@ export const runtimeRouteOverrides: BuiltinRouteOverrides = {
   "form-detail": {},
   "process-detail": {},
   "data-manage-list": {},
-}
+};
 ```
 
 AI / Playwright verification should use real user identity, not a bypass mode. The backend exposes `POST /openxiangda-api/v1/apps/:appType/verification-login-links` for platform admins to create a short-lived, single-use `loginUrl` for a target user and redirect URI. Playwright can open the returned URL directly; the backend writes cookies and redirects back to the local or tenant `/view/...` page. Test users can be created with `POST /openxiangda-api/v1/apps/:appType/test-users`; they use the `__ox_ai_test__:<appType>:<key>` ID prefix and are intended to be used through verification login links.
@@ -379,13 +384,13 @@ AI / Playwright verification should use real user identity, not a bypass mode. T
 An independent production user shell can call `resolveBrowserRuntimeRoute()` from `openxiangda/runtime` first. It posts the current `/view/...` path to `/openxiangda-api/v1/apps/:appType/runtime/routes/resolve`; the backend classifies the route as `custom-page`, `builtin-route`, `legacy-fallback`, or `not-found`. Code pages return backend-authorized bootstrap data directly, so the shell can pass that to `mountBrowserPageRuntime()` or mount with `createBrowserPageContext()` without reusing the legacy view workbench logic. Built-in routes can be rendered with `BuiltinRouteRenderer`, which loads form schema through the same `/service` proxy and keeps backend permission checks authoritative.
 
 ```ts
-import { resolveBrowserRuntimeRoute } from "openxiangda/runtime"
+import { resolveBrowserRuntimeRoute } from "openxiangda/runtime";
 
 const route = await resolveBrowserRuntimeRoute({
   appType: "APP_XXXX",
   path: window.location.pathname,
   search: window.location.search,
-})
+});
 ```
 
 Local workspace state is authoritative. If the current folder has no `.openxiangda/state.json` app binding, create a new app instead of searching the platform for a similar app name:
@@ -415,16 +420,16 @@ 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）。已登录非游客用户无需给应用角色额外绑定权限，默认可查询当前租户全部关系，返回平台用户 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 和姓名；`teachers.list` 还返回 `teacher.managedClasses`、`class.headTeachers` 和同步/人工 `source`，用于班主任双向查询。应用可显式声明 `:self:read` / `:class:read` 收紧范围。完整示例见 [`docs/dingtalk-school-contact-relations.md`](docs/dingtalk-school-contact-relations.md)。
 
 ```ts
-import type { PageUserRecord } from "openxiangda/runtime"
+import type { PageUserRecord } from "openxiangda/runtime";
 
-const currentUser = await sdk.user.getCurrent<PageUserRecord>()
-const user = currentUser.result
+const currentUser = await sdk.user.getCurrent<PageUserRecord>();
+const user = currentUser.result;
 
-const affiliatedDepartmentName = user?.affiliatedDepartment?.name
-const affiliatedDepartmentExternalId = user?.affiliatedDepartment?.externalId
+const affiliatedDepartmentName = user?.affiliatedDepartment?.name;
+const affiliatedDepartmentExternalId = user?.affiliatedDepartment?.externalId;
 ```
 
 工程化资源放在工作区 `src/resources/` 下，由 `openxiangda resource validate|plan|publish|pull` 管理。`workspace publish` 会先构建并注册 workspace 表单/页面，再执行非破坏性资源 upsert，这样菜单、权限组、流程和表单设置可以解析最新的 profile-local ID。需要删除平台中 manifest 未声明的资源时，显式传 `--prune`。连接器页面运行时通过 `sdk.connector.invoke()` / `sdk.connector.call("connector.api")` 调用平台运行时接口，第三方密钥只保存在后端连接器配置中。
@@ -460,7 +465,15 @@ React SPA 新应用的无需登录访问统一使用 `/view/:appType/public/*`
           "text/csv",
           "application/json"
         ],
-        "allowedExtensions": ["pdf", "docx", "xlsx", "pptx", "txt", "csv", "json"],
+        "allowedExtensions": [
+          "pdf",
+          "docx",
+          "xlsx",
+          "pptx",
+          "txt",
+          "csv",
+          "json"
+        ],
         "maxSizeBytes": 31457280,
         "visibility": "private",
         "pathPrefix": "public/register/attachments/"
@@ -477,10 +490,10 @@ React SPA 新应用的无需登录访问统一使用 `/view/:appType/public/*`
 公开页面里的图片和附件分两类处理。真正可以对公网长期公开的资产，例如仪器封面图、公开说明书、门户 banner，应上传到平台公开文件区，默认 bucket 为 `public-assets`，上传后保存的 `url` / `previewUrl` / `downloadUrl` 会是 `/file/public/...`，未登录浏览器可以直接读取并被浏览器/CDN 缓存。仍可能包含隐私、审批材料、订单报告、结算单、维保现场照片的附件不要放入公开区，应继续保存在私有 bucket，并通过登录态或受控文件票据访问。
 
 ```ts
-import { createFormRuntimeApi } from "openxiangda"
+import { createFormRuntimeApi } from "openxiangda";
 
-const api = createFormRuntimeApi({ baseUrl: "/service" })
-const file = await api.uploadPublicFile(imageFile, "public-assets")
+const api = createFormRuntimeApi({ baseUrl: "/service" });
+const file = await api.uploadPublicFile(imageFile, "public-assets");
 
 // file.url === "/service/file/public/public-assets/..."
 // file.visibility === "public"
@@ -503,7 +516,7 @@ import {
 这些独立 API 必须在模板默认提供的 `OpenXiangdaProvider` 和 `OpenXiangdaPageProvider` 内使用。它们会从 PageSdk 获取当前 `appType`，并统一处理 preview ticket、metadata 和二进制文件响应。默认覆盖 PDF、常见媒体、文本、DOCX 和 XLSX，更多 DOC/XLS/PPT、ODF 格式由部署侧 ONLYOFFICE 配置决定。只有在需要复制、分享或新窗口打开预览页时，才通过 PageSdk `sdk.createFileAccessTicket(..., "preview", { appType })` 获取并打开 `previewPageUrl`；不要直接打开文件内容流 `previewUrl`。
 
 ```tsx
-import { ImageField } from "openxiangda"
+import { ImageField } from "openxiangda";
 
 <ImageField
   fieldId="photos"
@@ -514,9 +527,9 @@ import { ImageField } from "openxiangda"
     enabled: true,
     skipBelowBytes: 200 * 1024,
     thumb: { maxWidth: 320, maxHeight: 320, quality: 0.72 },
-    preview: { maxWidth: 1280, maxHeight: 1280, quality: 0.82 }
+    preview: { maxWidth: 1280, maxHeight: 1280, quality: 0.82 },
   }}
-/>
+/>;
 ```
 
 压缩默认 `format: "source"`，会尽量沿用原图片格式。如果显式输出 `webp`、`png` 或 `jpeg`，对应 OSS storage resource 的 `allowedExtensions` 也要包含该扩展名。
@@ -602,15 +615,15 @@ openxiangda organization account-reset-password user-alice --profile dev --body-
 页面 SDK 和 App Function 使用同一套后端权限：
 
 ```ts
-const capabilities = await sdk.organization.capabilities()
+const capabilities = await sdk.organization.capabilities();
 if (!capabilities.result?.canManage) {
-  throw new Error("当前账号没有组织账号管理权限")
+  throw new Error("当前账号没有组织账号管理权限");
 }
 
 await sdk.organization.departments.create({
   name: "销售部",
   parentId: "dept-root",
-})
+});
 
 await sdk.organization.accounts.create({
   id: "user-alice",
@@ -618,12 +631,12 @@ await sdk.organization.accounts.create({
   password: initialPassword,
   name: "Alice",
   departmentIds: ["dept-sales"],
-})
+});
 
 // App Function / trusted JS uses ctx.organization with the same permission check.
 await ctx.organization.accounts.resetPassword("user-alice", {
   newPassword,
-})
+});
 ```
 
 应用登录能力通过 auth resource 和 runtime SDK 提供：登录配置放在 `src/resources/auth/<code>.json`，默认 React SPA 模板已包含 `/view/:appType/login`，自定义页面可使用 `createAuthClient({ appType, servicePrefix })` 或 `LoginPage` / `useAuth` from `openxiangda/runtime/react`。钉钉登录默认使用 `dingtalkFlow="auto"`：只有明确位于钉钉容器且 JSAPI 可用时才走免登码，普通浏览器会请求应用级 OAuth 地址并跳转钉钉认证页；自定义页可调用 `getDingTalkOAuthUrl({ returnUrl })` 接入相同能力。手机号验证码、CAS/SSO 或其他外部登录可以由 App Function provider 校验外部凭证，但 provider 只能返回 `phone` / `email` / `externalId` / `unionId` 等身份声明；平台后端按 auth resource 策略执行账号匹配、绑定、创建或拒绝，并由平台统一签发 token/cookie。默认注册策略是拒绝，开启自动注册或白名单注册前必须确认身份匹配键、默认角色、验证码 TTL/频率/失败次数、审计字段和错误文案策略。

package/lib/application-environments.js

@@ -1025,7 +1025,7 @@ function releaseExecutionPath(changeId, deploymentId, cwd = process.cwd()) {
 }
 
 function withManagedReleaseForwardedFlags(stepId, args = [], flags = {}) {
-  const forwarded = [...args];
+  let forwarded = [...args];
   if (stepId === 'runtime-stage' && flags['allow-runtime-rollback']) {
     forwarded.push('--allow-runtime-rollback');
     const rollbackReason = String(flags.reason || '').trim();
@@ -1058,6 +1058,19 @@ function withManagedReleaseForwardedFlags(stepId, args = [], flags = {}) {
       forwarded.push('--reason', replacementReason);
     }
   }
+  forwarded = withOnlineBaselineAdoptionFlags(forwarded, flags);
+  return forwarded;
+}
+
+function withOnlineBaselineAdoptionFlags(args = [], flags = {}) {
+  const forwarded = [...args];
+  const isExactResourcePublish =
+    forwarded[0] === 'resource' &&
+    forwarded[1] === 'publish' &&
+    (forwarded.includes('--only') || forwarded.includes('--code'));
+  if (!isExactResourcePublish) {
+    return forwarded;
+  }
   if (flags['adopt-online-baseline']) {
     forwarded.push('--adopt-online-baseline');
     const adoptionReason = String(
@@ -1129,6 +1142,7 @@ module.exports = {
   saveCandidate,
   sha256Canonical,
   withManagedReleaseForwardedFlags,
+  withOnlineBaselineAdoptionFlags,
   withReleaseClientSessionArgs,
   writePrivateJsonAtomic,
 };

package/lib/cli.js

@@ -163,6 +163,7 @@ const {
   saveCandidate,
   sha256Canonical,
   withManagedReleaseForwardedFlags,
+  withOnlineBaselineAdoptionFlags,
   withReleaseClientSessionArgs,
 } = require('./application-environments');
 const { startDeveloperCenter } = require('./developer-center');
@@ -336,7 +337,7 @@ Usage:
   openxiangda status <runId> [--environment preproduction|production] [--json]
   openxiangda retry <runId> [--environment preproduction|production] [--json]
   openxiangda rollback <preproduction|production> --to <appReleaseId> [--json]
-  openxiangda release publish|begin|status|integration-status|renew|end [--change id] [--profile name] [--watch] [--json]
+  openxiangda release publish|begin|status|integration-status|renew|end [--change id] [--profile name] [--adopt-online-baseline --adoption-reason text] [--watch] [--json]
   openxiangda release ship|candidate|deploy|reconcile|test|fail|promote|rollback [--candidate id] [--deployment id] [--environment target] [--replace-manifest] [--allow-runtime-rollback --reason text] [--adopt-online-baseline --adoption-reason text] [--confirm-production] [--json]
   openxiangda task status --change <id> [--profile name] [--watch] [--json]
   openxiangda release backend-head|backend-list|backend-detail|backend-diff|backend-rollback|backend-abort|backend-retry [releaseId] [--profile name] [--json]
@@ -2075,14 +2076,18 @@ async function endReleaseWithoutLocalLease(
 }
 
 function decorateEnvironmentReleaseSteps(steps, target, flags = {}) {
-  if (!target.environmentId || !target.targetName) return steps;
+  const managedEnvironment = Boolean(
+    target.environmentId && target.targetName
+  );
   const deploymentId = readStringFlag(flags, 'deployment-id');
   for (const step of steps) {
-    step.args = withManagedReleaseForwardedFlags(
-      step.id,
-      step.args,
-      flags
-    );
+    step.args = managedEnvironment
+      ? withManagedReleaseForwardedFlags(step.id, step.args, flags)
+      : withOnlineBaselineAdoptionFlags(step.args, flags);
+    if (!managedEnvironment) {
+      step.command = commandFromArgs(step.args);
+      continue;
+    }
     step.args.push('--environment', target.targetName);
     if (deploymentId) step.args.push('--deployment-id', deploymentId);
     if (step.id === 'runtime-stage' && flags.__verifiedCandidate) {
@@ -2132,6 +2137,43 @@ function decorateEnvironmentReleaseSteps(steps, target, flags = {}) {
   return steps;
 }
 
+function assertReleasePublishAdoptionFlags(flags = {}) {
+  const adoptionRequested = Boolean(flags['adopt-online-baseline']);
+  const adoptionReasonSupplied = Object.prototype.hasOwnProperty.call(
+    flags,
+    'adoption-reason'
+  );
+  const adoptionReason = String(flags['adoption-reason'] || '').trim();
+  if (!adoptionRequested && adoptionReasonSupplied) {
+    const error = new Error(
+      'RELEASE_PUBLISH_ADOPTION_FLAG_REQUIRED: --adoption-reason 必须与 --adopt-online-baseline 一起使用；命令已在任何发布租约或资源写入前终止'
+    );
+    error.code = 'RELEASE_PUBLISH_ADOPTION_FLAG_REQUIRED';
+    throw error;
+  }
+  if (adoptionRequested && adoptionReason.length < 8) {
+    const error = new Error(
+      'RELEASE_PUBLISH_ADOPTION_REASON_REQUIRED: --adopt-online-baseline 必须提供至少 8 个字符的 --adoption-reason；命令已在任何发布租约或资源写入前终止'
+    );
+    error.code = 'RELEASE_PUBLISH_ADOPTION_REASON_REQUIRED';
+    throw error;
+  }
+}
+
+function assertReleasePublishAdoptionScope(steps = [], flags = {}) {
+  if (!flags['adopt-online-baseline']) return;
+  const adoptionSteps = steps.filter(step =>
+    step.args?.includes('--adopt-online-baseline')
+  );
+  if (adoptionSteps.length === 0) {
+    const error = new Error(
+      'RELEASE_PUBLISH_ADOPTION_SCOPE_REQUIRED: 当前发布计划没有可精确采纳线上基线的 resource publish --only/--code 阶段；命令已在任何发布租约或资源写入前终止'
+    );
+    error.code = 'RELEASE_PUBLISH_ADOPTION_SCOPE_REQUIRED';
+    throw error;
+  }
+}
+
 function changeIdFromStep(step) {
   const index = step.args.indexOf('--change');
   return index >= 0 ? step.args[index + 1] : 'change';
@@ -2145,6 +2187,7 @@ async function publishWorkspaceRelease(config, target, flags = {}) {
   if (!changeId) {
     fail('用法: openxiangda release publish --change <id> --profile <name>');
   }
+  assertReleasePublishAdoptionFlags(flags);
   assertManagedRuntimeRollbackFlags(flags);
   const releaseCandidate = flags.__verifiedCandidate
     ? assertLocalCandidate(flags.__verifiedCandidate)
@@ -2171,6 +2214,7 @@ async function publishWorkspaceRelease(config, target, flags = {}) {
     changeId
   );
   decorateEnvironmentReleaseSteps(steps, target, flags);
+  assertReleasePublishAdoptionScope(steps, flags);
   const releaseScope = getSddChangeScope({
     cwd: process.cwd(),
     configText: readWorkspaceConfigText(),
@@ -5308,7 +5352,7 @@ async function release(args) {
   const { flags, positional } = parseArgs(rest);
   if (wantsSubcommandHelp(subcommand, flags)) {
     print([
-      '用法: openxiangda release publish|begin|status|explain|integration-status|renew|end [--change id] [--profile name] [--json]',
+      '用法: openxiangda release publish|begin|status|explain|integration-status|renew|end [--change id] [--profile name] [--adopt-online-baseline --adoption-reason text] [--json]',
       '      openxiangda release ship|candidate|deploy|reconcile|test|fail|promote|rollback [--candidate id] [--deployment id] [--environment target] [--replace-manifest] [--allow-runtime-rollback --reason text] [--adopt-online-baseline --adoption-reason text] [--confirm-production] [--json]',
       '      openxiangda release backend-head|backend-list|backend-detail|backend-diff|backend-rollback|backend-abort|backend-retry [releaseId] [--profile name] [--json]',
       '      openxiangda release app-capture|app-head|app-list|app-detail|app-diff|app-post-commit|app-retry|app-prepare|app-verify|app-activate|app-finalize|app-rollback|app-abort [releaseId] [--staged-resources-json <JSON|file>] [--activate-staged-children] [--break-glass-adopt-verified-root --reason text] [--force-activate-without-validation] [--profile name] [--json]',
@@ -5321,6 +5365,7 @@ async function release(args) {
       '  openxiangda release ship --change <id> --profile <name> --confirm-production',
       '  openxiangda release fail --deployment <id> --message "UAT 未通过" --code UAT_FAILED --details-json <JSON|file> --environment preproduction --profile <name>',
       '  openxiangda release publish --change <id> --profile <name>',
+      '  openxiangda release publish --change <id> --profile <name> --adopt-online-baseline --adoption-reason "已审计目标来自多次历史发布"',
       '  openxiangda release begin --change <id> --profile <name>',
       '  openxiangda resource publish function --only <code> --change <id> --profile <name>',
       '  openxiangda runtime deploy --change <id> --profile <name>',
@@ -5339,6 +5384,7 @@ async function release(args) {
       '  - release fail 只允许显式选择 preproduction target，并会先核对 deployment 的 targetEnvironmentId；message 必填，code/details 会一并写入平台审计。',
       '  - ship 当前不支持 --dry-run；任何未声明参数都会在 candidate/deployment 写入前 fail-closed。需要只读检查时使用 environment status/diff 与 release status。',
       '  - publish 默认等待租约并按私有执行日志恢复；上次写结果不确定时必须只读核对后显式 --resume-after-review。',
+      '  - 旧式非环境托管 publish 也会把线上基线采纳意图仅透传给精确的 resource publish --only/--code 阶段；无精确资源阶段、原因不足或单独提供 reason 均在获取租约前 fail-closed。',
       '  - app-head 默认只输出紧凑 head 摘要；需要完整 manifest 时显式追加 --full。',
       '  - begin 获取应用级单写者 promotion lease；不同工作区仍可并行开发和验证。',
       '  - 带 --change 的 resource/runtime 写命令在没有本地 lease 时会自动 begin，并在后续命令复用。',
@@ -31065,6 +31111,8 @@ function buildWorkspacePublishEnv(
 }
 
 module.exports = {
+  assertReleasePublishAdoptionFlags,
+  assertReleasePublishAdoptionScope,
   assertRuntimeReleaseReusable,
   buildOpenXiangdaUpdateInstallPlan,
   buildResourceManifestSddTargets,
@@ -31081,4 +31129,5 @@ module.exports = {
   resolveDataViewSourceFormCodes,
   satisfiedFormCodesFromContext,
   stagedDataViewFormReleaseDependencies,
+  decorateEnvironmentReleaseSteps,
 };

package/openxiangda-skills/SKILL.md

@@ -4,6 +4,7 @@ description: "Use OpenXiangda for private low-code platform work: app workspaces
 ---
 
 <!-- OpenXiangda-Policy-Version: 7 -->
+
 # OpenXiangda
 
 OpenXiangda connects an AI coding workspace to the private low-code platform through a normal-user profile and `/openxiangda-api/v1`. External backends using AK/SK are a separate `openxiangda-open-api` flow.
@@ -57,18 +58,18 @@ content/source/parent verification and never overwrites immutable storage.
 
 ## Decide the track
 
-| Intent | Read next | First action |
-| --- | --- | --- |
-| Diagnose, snapshot, compare, explain an error | `openxiangda-inspect` | read-only snapshot/inspect |
-| Login, profile, release, CLI/state issue | `openxiangda-core` | resolve explicit profile and workspace |
-| Create or bind an app | `openxiangda-app` | inspect local binding, then init/bind |
-| Form/schema/data view | `openxiangda-form` | inspect the target form and schema |
-| 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 |
+| Intent                                                 | Read next                                                        | First action                                                               |
+| ------------------------------------------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Diagnose, snapshot, compare, explain an error          | `openxiangda-inspect`                                            | read-only snapshot/inspect                                                 |
+| Login, profile, release, CLI/state issue               | `openxiangda-core`                                               | resolve explicit profile and workspace                                     |
+| Create or bind an app                                  | `openxiangda-app`                                                | inspect local binding, then init/bind                                      |
+| Form/schema/data view                                  | `openxiangda-form`                                               | inspect the target form and schema                                         |
+| 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 |
+| 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                                               |
 
 ## Scope before work
 
@@ -160,7 +161,7 @@ When the sealed Runtime source intentionally does not descend from the active Ru
 
 `resource plan` and publish dry-runs are strictly GET/HEAD-only. `READ_ONLY_AUTH_REQUIRED` means the access token expired; run `openxiangda auth refresh --profile <name>` or log in again before retrying. Never add an automatic refresh POST inside a plan.
 
-`release publish` is the default promotion entrypoint only for legacy unmanaged workspaces. It verifies without rewriting reviewed `change.json`/`release.json`, waits for the app lease, freezes the App capture after ownership is acquired, executes deterministic exact staged steps, resumes from `.openxiangda/releases/<change>/execution.json`, atomically finalizes, verifies mainline integration, and releases the lease. Environment-managed applications use the two-phase `release ship`; candidate/deploy/test/fail/promote, `release begin`, and child commands remain recovery/diagnostic primitives.
+`release publish` is the default promotion entrypoint only for legacy unmanaged workspaces. It verifies without rewriting reviewed `change.json`/`release.json`, waits for the app lease, freezes the App capture after ownership is acquired, executes deterministic exact staged steps, resumes from `.openxiangda/releases/<change>/execution.json`, atomically finalizes, verifies mainline integration, and releases the lease. When the same audited historical-lineage condition applies, legacy `release publish` accepts `--adopt-online-baseline --adoption-reason "..."` and forwards the pair only to exact `resource publish --only/--code` stages; missing reasons or plans without an exact resource stage fail before lease acquisition. Environment-managed applications use the two-phase `release ship`; candidate/deploy/test/fail/promote, `release begin`, and child commands remain recovery/diagnostic primitives.
 
 Reviewed bundle commands may retain `<profile>` as a template. The explicit real `release publish --profile <name>` value is bound to actual child argv without rewriting tracked SDD. React SPA page codes are logical coverage targets and activate through one Runtime child; they do not require PageRelease. `release app-head` and `runtime releases` are compact by default; use `--full` only when the complete manifest is required.
 
@@ -194,7 +195,9 @@ The lease is app-level promotion ownership, while worktree ownership prevents tw
 - 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
+  exact class relationship; consume `teacher.managedClasses` and
+  `class.headTeachers` for the two relationship directions and inspect
+  `source` when synced/manual provenance matters. 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.

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

@@ -1,6 +1,6 @@
 # 家校通讯录关系
 
-家校关系由平台组织中心统一同步和维护。应用不得直连钉钉，也不得根据班级成员自行推断家长和学生关系。
+家校关系由平台组织中心统一同步和维护。同步成员和人工成员都直接位于班级部门下，通过 `guardian`、`student`、`teacher` 和班主任标记区分，不再依赖“家长/学生/老师”子部门。应用不得直连钉钉，也不得根据班级成员自行推断家长和学生关系。
 
 ## 权限与默认范围
 
@@ -10,9 +10,7 @@
 
 ```json
 {
-  "apiPermissionCodes": [
-    "app:organization:school-contact:read"
-  ]
+  "apiPermissionCodes": ["app:organization:school-contact:read"]
 }
 ```
 
@@ -31,11 +29,11 @@
 
 每次成功的钉钉家校通讯录全量同步都会对账并维护四种平台层系统身份角色：
 
-| 展示名 | 稳定角色编码 | 含义 |
-| --- | --- | --- |
-| 家长 | `SCHOOL_GUARDIAN` | 在家校成员关系中作为 guardian |
-| 学生 | `SCHOOL_STUDENT` | 在家校成员关系中作为 student |
-| 老师 | `SCHOOL_TEACHER` | 在家校成员关系中作为 teacher |
+| 展示名 | 稳定角色编码          | 含义                                          |
+| ------ | --------------------- | --------------------------------------------- |
+| 家长   | `SCHOOL_GUARDIAN`     | 在家校成员关系中作为 guardian                 |
+| 学生   | `SCHOOL_STUDENT`      | 在家校成员关系中作为 student                  |
+| 老师   | `SCHOOL_TEACHER`      | 在家校成员关系中作为 teacher                  |
 | 班主任 | `SCHOOL_HEAD_TEACHER` | 至少一个 teacher 班级成员带 `is_adviser=true` |
 
 身份角色可组合，一个平台用户可以同时是老师和家长；角色由同步维护，不能在平台角色管理中手工分配、修改、删除，也不会被当前平台角色切换隐藏。应用权限组把这些编码填入 `platformRoleCodes`，与应用角色 `roles` 是并列的 OR 条件；两个数组都为空仍表示不限制。
@@ -44,10 +42,11 @@
 
 ```ts
 const isGuardian =
-  sdk.context.permissions?.platformRoleCodes?.includes("SCHOOL_GUARDIAN")
+  sdk.context.permissions?.platformRoleCodes?.includes("SCHOOL_GUARDIAN");
 
-const isHeadTeacher =
-  sdk.context.permissions?.platformRoleCodes?.includes("SCHOOL_HEAD_TEACHER")
+const isHeadTeacher = sdk.context.permissions?.platformRoleCodes?.includes(
+  "SCHOOL_HEAD_TEACHER",
+);
 ```
 
 `SCHOOL_HEAD_TEACHER` 只说明当前用户至少担任一个班的班主任。班主任是班级维度的关系；要判断具体班级，必须使用下方 `teachers.list` 返回的 `isHeadTeacher`，不能用全局角色推断。
@@ -75,9 +74,9 @@ const response = await sdk.organization.schoolContact.relations.list({
   classId,
   page: 1,
   pageSize: 20,
-})
+});
 
-const relations = response.result?.items || []
+const relations = response.result?.items || [];
 ```
 
 常用方法：
@@ -86,23 +85,31 @@ const relations = response.result?.items || []
 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 })
+await sdk.organization.schoolContact.myFamily.get({ pageSize: 50 });
 
 await sdk.organization.schoolContact.teachers.list({
   classId,
   isHeadTeacher: true,
   page: 1,
   pageSize: 20,
-})
+});
 ```
 
+`teachers.list` 的每个结果同时提供两个方向的班主任信息：
+
+- `teacher.managedClasses`：该老师当前作为班主任管理的全部班级。
+- `class.headTeachers`：该班级当前的全部班主任。
+- `source`：班级身份来源，值为 `dingtalk_school_contact` 或 `manual`。
+
+这两个字段可直接用于“我管理的班级”和“班级班主任”场景，不要在应用中自行维护第二份映射。
+
 关系列表支持以下服务端过滤条件：
 
 - `userId`、`guardianUserId`、`studentUserId`：平台用户 ID。
@@ -128,38 +135,38 @@ await sdk.organization.schoolContact.teachers.list({
 App Function、Automation 或 Workflow 中需要复用关系时，调用对应的受控后端桥接：
 
 ```ts
-export default async function(ctx, input) {
+export default async function (ctx, input) {
   const result = await ctx.organization.schoolContact.relations.list({
     guardianUserId: input.guardianUserId,
     page: 1,
     pageSize: 20,
-  })
+  });
 
-  return result.items
+  return result.items;
 }
 ```
 
 查询某位老师担任班主任的班级：
 
 ```ts
-export default async function(ctx, input) {
+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)
+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);
 ```
 
 运行时使用平台提供的真实操作者做权限校验。不要信任页面 input 中伪造的租户、角色或当前用户 ID。
@@ -168,31 +175,31 @@ ctx.organization.schoolContact.myFamily.get(params)
 
 ```ts
 interface SchoolContactRelation {
-  relationId: string
-  relationCode: string | null
-  relationName: string | null
+  relationId: string;
+  relationCode: string | null;
+  relationName: string | null;
   guardian: {
-    userId: string
-    dingtalkUserId: string
-    name: string
-    mobile: string | null
-  }
+    userId: string;
+    dingtalkUserId: string | null;
+    name: string;
+    mobile: string | null;
+  };
   student: {
-    userId: string
-    dingtalkUserId: string
-    name: string
-    mobile: string | null
-  }
+    userId: string;
+    dingtalkUserId: string | null;
+    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"
+    id: string;
+    dingtalkClassId: string;
+    name: string;
+    campusName: string | null;
+    periodName: string | null;
+    gradeName: string | null;
+  };
+  syncedAt: string;
+  syncState: "current" | "not_synced" | "disabled";
 }
 ```
 
@@ -200,22 +207,33 @@ interface SchoolContactRelation {
 
 ```ts
 interface SchoolContactTeacherMembership {
-  membershipId: string
+  membershipId: string;
   teacher: {
-    userId: string
-    dingtalkUserId: string
-    name: string
-    mobile: string | null
-  }
-  class: SchoolContactRelation["class"]
-  isHeadTeacher: boolean
-  syncedAt: string
-  syncState: "current" | "not_synced" | "disabled"
+    userId: string;
+    dingtalkUserId: string | null;
+    name: string;
+    mobile: string | null;
+    managedClasses: SchoolContactRelation["class"][];
+  };
+  class: SchoolContactRelation["class"] & {
+    headTeachers: Array<{
+      userId: string;
+      dingtalkUserId: string | null;
+      name: string;
+      mobile: string | null;
+    }>;
+  };
+  isHeadTeacher: boolean;
+  source: "dingtalk_school_contact" | "manual";
+  syncedAt: string;
+  syncState: "current" | "not_synced" | "disabled";
 }
 ```
 
 手机号可能为空。`sync.state=disabled` 表示管理员关闭了后续同步，现有数据仍保留但可能过期；业务页面在对时效敏感时应展示 `lastSuccessfulSyncAt`。
 
+平台管理员人工添加的班级身份也会由 `teachers.list` 返回，并标记 `source=manual`。人工家长/学生身份会维护对应平台身份和班级归属，但不会自动生成监护关系；只有明确存在的家庭关系才会出现在 `relations`、`children`、`guardians` 和 `myFamily`。
+
 ## 持久化边界
 
 - 平台关系是当前事实，不要复制全量关系到应用表单或 Data View。