openxiangda 1.0.260 → 1.0.261

package/README.md

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

package/lib/skills.js

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

package/openxiangda-skills/SKILL.md

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

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

@@ -19,6 +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.workCenter.listItems({ boxType })` and `sdk.workCenter.getStats()` for current-user work center lists and counts. `boxType` is one of `todo`, `done`, `cc`, or `initiated`. This is the end-user task/handled/cc/initiated surface; do not build todo pages by reading workflow operation logs, automation logs, or raw process-task tables.
 - `sdk.form.create` returns identifiers and generated serial number values only. Treat `formInstId` / `formInstanceId` as the required success contract; `serialNumber` / `serialNumbers` are present only when the form has `SerialNumberField`. Do not expect the save response to contain the full row, formula results, or other server-generated field values. Call `sdk.form.getDetail` explicitly after create when those values are needed.
 - Missing `formInstId` / `formInstanceId` is a real error in strict mode. Do not create fake IDs, mock rows, or fallback display data to hide it.
@@ -251,6 +252,8 @@ await sdk.organization.accounts.resetPassword("alice", {
 
 Use `ctx.organization.departments.*` and `ctx.organization.accounts.*` inside App Functions or trusted JS nodes for the same capability. Runtime service principals must resolve a real operator/audit actor; permission is checked against that user, not against the runtime service account. Keep password changes on dedicated endpoints: update account metadata with `update`, reset another user's password with `resetPassword`, and change the current user's password with `changeMyPassword({ oldPassword, newPassword })`.
 
+For synchronized school-contact relationships, use `sdk.organization.schoolContact.relations.list`, `children.list`, `guardians.list`, or `myFamily.get`; App Functions use the same paths under `ctx.organization.schoolContact`. Do not infer a family relationship from class membership or persist a second relationship master inside application forms. See `references/school-contact-relations.md` for permission codes, filters, response fields, and examples.
+
 Work center:
 
 ```ts

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

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

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

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

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

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

package/package.json

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