openxiangda 1.0.264 → 2.0.0-alpha.2

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

@@ -1,224 +0,0 @@
-# 家校通讯录关系
-
-家校关系由平台组织中心统一同步和维护。应用不得直连钉钉，也不得根据班级成员自行推断家长和学生关系。
-
-## 权限与默认范围
-
-已登录非游客用户无需给应用角色绑定家校权限，默认查询当前租户的全部关系，范围为 `all`。跨租户、游客和匿名访问仍然拒绝。
-
-应用若要显式保留全量范围，可以在 `src/resources/roles/<code>.json` 中声明：
-
-```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` 身份加入的班级关系。
-
-同一应用角色拥有多项家校能力时按 `all > class > self` 取最宽范围。平台身份角色只表达用户身份，不参与通用应用权限计算；默认 `all` 由家校关系服务统一执行。
-
-默认全量可见不等于公开访问：跨租户、游客和匿名页面仍然拒绝。不要通过公开访问策略给游客授予家庭关系能力。
-
-## 页面 SDK
-
-### 平台内置身份角色
-
-每次成功的钉钉家校通讯录全量同步都会对账并维护四种平台层系统身份角色：
-
-| 展示名 | 稳定角色编码 | 含义 |
-| --- | --- | --- |
-| 家长 | `SCHOOL_GUARDIAN` | 在家校成员关系中作为 guardian |
-| 学生 | `SCHOOL_STUDENT` | 在家校成员关系中作为 student |
-| 老师 | `SCHOOL_TEACHER` | 在家校成员关系中作为 teacher |
-| 班主任 | `SCHOOL_HEAD_TEACHER` | 至少一个 teacher 班级成员带 `is_adviser=true` |
-
-身份角色可组合，一个平台用户可以同时是老师和家长；角色由同步维护，不能在平台角色管理中手工分配、修改、删除，也不会被当前平台角色切换隐藏。应用权限组把这些编码填入 `platformRoleCodes`，与应用角色 `roles` 是并列的 OR 条件；两个数组都为空仍表示不限制。
-
-运行时页面权限会在 `permissions.platformRoleCodes` 返回当前用户的身份编码，它与 `permissions.roleCodes` 分开：
-
-```ts
-const isGuardian =
-  sdk.context.permissions?.platformRoleCodes?.includes("SCHOOL_GUARDIAN")
-
-const isHeadTeacher =
-  sdk.context.permissions?.platformRoleCodes?.includes("SCHOOL_HEAD_TEACHER")
-```
-
-`SCHOOL_HEAD_TEACHER` 只说明当前用户至少担任一个班的班主任。班主任是班级维度的关系；要判断具体班级，必须使用下方 `teachers.list` 返回的 `isHeadTeacher`，不能用全局角色推断。
-
-App Function 的调用受众可以声明平台身份角色，服务端按真实操作者的同步结果校验：
-
-```json
-{
-  "runtimeInvoke": {
-    "audience": {
-      "type": "platform_roles",
-      "platformRoleCodes": ["SCHOOL_GUARDIAN", "SCHOOL_TEACHER"]
-    }
-  }
-}
-```
-
-函数可信上下文同时提供 `ctx.operator.platformRoleCodes` 和 `ctx.permissions.platformRoleCodes`。不要信任页面输入中的角色编码；需要家庭双方或班级关系时，继续使用下方的 `schoolContact` 关系 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 })
-
-await sdk.organization.schoolContact.teachers.list({
-  classId,
-  isHeadTeacher: true,
-  page: 1,
-  pageSize: 20,
-})
-```
-
-关系列表支持以下服务端过滤条件：
-
-- `userId`、`guardianUserId`、`studentUserId`：平台用户 ID。
-- `dingtalkUserId`：钉钉 userid。
-- `mobile`：精确手机号。
-- `name`：家长或学生姓名。
-- `classId`：平台家校班级 ID 或钉钉教育 `class_id`。
-- `role`：`guardian` 或 `student`，用于限定通用人员过滤作用在哪一端。
-- `relationCode`、`page`、`pageSize`；`pageSize` 最大为 100。
-
-老师班级成员列表 `teachers.list` 支持：
-
-- `userId`：老师的平台用户 ID。
-- `dingtalkUserId`：老师的钉钉 userid。
-- `mobile`：精确手机号。
-- `name`：老师姓名。
-- `classId`：平台家校班级 ID 或钉钉教育 `class_id`。
-- `isHeadTeacher`：布尔值；`true` 只返回班主任，`false` 只返回普通任课老师。
-- `page`、`pageSize`；`pageSize` 最大为 100。
-
-## App Function
-
-App Function、Automation 或 Workflow 中需要复用关系时，调用对应的受控后端桥接：
-
-```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
-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)
-```
-
-运行时使用平台提供的真实操作者做权限校验。不要信任页面 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"
-}
-```
-
-老师班级成员的返回项为：
-
-```ts
-interface SchoolContactTeacherMembership {
-  membershipId: string
-  teacher: {
-    userId: string
-    dingtalkUserId: string
-    name: string
-    mobile: string | null
-  }
-  class: SchoolContactRelation["class"]
-  isHeadTeacher: boolean
-  syncedAt: string
-  syncState: "current" | "not_synced" | "disabled"
-}
-```
-
-手机号可能为空。`sync.state=disabled` 表示管理员关闭了后续同步，现有数据仍保留但可能过期；业务页面在对时效敏感时应展示 `lastSuccessfulSyncAt`。
-
-## 持久化边界
-
-- 平台关系是当前事实，不要复制全量关系到应用表单或 Data View。
-- 业务单据确实需要历史证据时，只保存 `relationId`、双方平台用户 ID 和当时的最小显示快照。
-- 不保存或依赖 `unionid`、同步原文、行业部门 ID，也不要假设行业 `dept_id` 等于教育 `class_id`。
-- 所有列表保持分页；不要拉取全部关系后在浏览器过滤。

package/openxiangda-skills/references/style-system.md

@@ -1,218 +0,0 @@
-# OpenXiangda 样式体系参考
-
-> 面向 AI Agent 的代码页、表单页和自定义节点样式基线。默认直接使用 Tailwind 原生工具类和 Tailwind 任意值；平台 token 是兼容能力和平台组件内部能力，不是业务页面的强制范式。
-
----
-
-## 1. 默认规则
-
-1. **业务页面默认写原生 Tailwind**：优先使用 `bg-white`、`border`、`border-slate-200`、`text-slate-600`、`shadow-sm`、`rounded-lg`、`p-4`、`gap-4`、`grid-cols-[240px_1fr]` 这类 Tailwind 原生类和任意值。
-2. **不要强制平台 token**：不要把 `bg-container`、`text-secondary`、`rounded-form`、`shadow-card` 当默认示例或默认范式。历史项目或平台组件需要时可以兼容使用，但新业务页面不推荐主动依赖。
-3. **不要直接套 shadcn token**：`bg-card`、`text-muted-foreground`、`text-foreground`、`bg-background` 等不是 Tailwind 原生类。除非项目已经在 `tailwind.config.cjs` 明确配置这些 token，否则必须改成 Tailwind 原生类或任意值。
-4. **默认不启用样式隔离**：新发布页面默认 `cssIsolation: "none"`，Tailwind 类按原样输出，不需要 `.sy-app-workspace` 前缀即可生效。
-5. **legacy 隔离仅用于兼容**：历史页面或显式配置 `cssIsolation: "namespace" | "shadow"` 时，runtime 仍会保留 `.sy-app-workspace`、legacy portal 和旧样式前缀。
-6. **CSS 作用域要收敛**：页面级 CSS 写在 `styles.css`，选择器优先限定在页面根类下，避免无意覆盖宿主平台或其他页面。
-
----
-
-## 2. 推荐写法
-
-### 2.1 页面容器
-
-```tsx
-export function DashboardPage() {
-  return (
-    <main className="min-h-screen bg-slate-50 px-6 py-5 text-slate-900">
-      <section className="rounded-lg border border-slate-200 bg-white p-5 shadow-sm">
-        <h1 className="text-xl font-semibold">排队预约</h1>
-        <p className="mt-1 text-sm text-slate-600">查看排队申请、安排上机时间、处理冲突。</p>
-      </section>
-    </main>
-  );
-}
-```
-
-### 2.2 卡片和状态
-
-```tsx
-<div className="rounded-lg border border-slate-200 bg-white p-4 shadow-sm">
-  <div className="text-sm text-slate-500">待分配</div>
-  <div className="mt-2 text-2xl font-semibold text-amber-700">2</div>
-</div>
-
-<span className="inline-flex rounded-full bg-emerald-50 px-2 py-0.5 text-xs font-medium text-emerald-700">
-  已完成
-</span>
-```
-
-### 2.3 精确布局和品牌色
-
-```tsx
-<div className="grid min-h-[calc(100vh-64px)] grid-cols-[280px_1fr] gap-5">
-  <aside className="border-r border-slate-200 bg-white" />
-  <section className="bg-[#f7fafc] p-6" />
-</div>
-
-<button className="rounded-md bg-[#1677ff] px-4 py-2 text-sm font-medium text-white hover:bg-[#0958d9]">
-  提交
-</button>
-```
-
-### 2.4 局部 CSS
-
-```css
-.queue-booking-page {
-  min-height: 100%;
-  background: #f8fafc;
-}
-
-.queue-booking-page .queue-booking-page__calendar-grid {
-  display: grid;
-  grid-template-columns: repeat(7, minmax(120px, 1fr));
-  gap: 12px;
-}
-```
-
----
-
-## 3. Tailwind 配置要求
-
-OpenXiangda workspace 的 `tailwind.config.cjs` 必须保留：
-
-```js
-const openxiangdaPath = require("node:path");
-const openxiangdaPresetModule = require("openxiangda/tailwind-preset");
-const openxiangdaPreset =
-  openxiangdaPresetModule.default ?? openxiangdaPresetModule;
-
-function resolveOpenXiangdaContent() {
-  try {
-    const packagePath = require.resolve("openxiangda");
-    const distDir = openxiangdaPath.dirname(packagePath);
-    return [openxiangdaPath.join(distDir, "..", "**/*.{js,mjs,cjs}")];
-  } catch {
-    return [];
-  }
-}
-
-const openxiangdaContent = resolveOpenXiangdaContent();
-
-module.exports = {
-  content: [
-    "./index.html",
-    "./src/**/*.{js,ts,jsx,tsx}",
-    ...openxiangdaContent,
-  ],
-  blocklist: ["[-:T]", "[-:TZ.]"],
-  presets: [openxiangdaPreset],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-};
-```
-
-这个配置的作用：
-
-- `openxiangdaPreset` 保留平台组件 safelist、平台 token 兼容类和平台组件需要的工具类；不再强制 Tailwind 输出 `.sy-app-workspace` 前缀。
-- `...openxiangdaContent` 确保平台组件内部 class 会被 Tailwind 扫描到。
-- `blocklist` 避免 Tailwind 误生成日期字符串相关的异常类。
-
-不要移除这些平台构建能力；自由写 Tailwind 原生类和保留平台组件兼容能力并不冲突。
-
----
-
-## 4. 入口 CSS 要求
-
-`src/index.css` 默认只需要 Tailwind 指令和少量基础样式：
-
-```css
-@layer tailwind-base {
-  @tailwind base;
-}
-
-@tailwind components;
-@tailwind utilities;
-
-* {
-  box-sizing: border-box;
-}
-
-body {
-  margin: 0;
-  min-width: 320px;
-  background: #f8fafc;
-  color: #0f172a;
-  font-family:
-    -apple-system,
-    BlinkMacSystemFont,
-    "Segoe UI",
-    sans-serif;
-}
-
-#root {
-  min-height: 100dvh;
-}
-```
-
-`openxiangda/styles/tokens.css` 不再是新业务页面的默认依赖。旧项目已经引入时可以保留，或在确实需要平台 CSS 变量统一主题时手动引入。
-
----
-
-## 5. Ant Design 和弹层
-
-PC 控件优先用 `antd`，移动端控件优先用 `antd-mobile`。默认 `cssIsolation: "none"` 时使用 Ant Design 默认 `ant` class 和 `document.body` 弹层容器即可；只有 legacy `namespace/shadow` 页面才需要显式挂到当前隔离容器：
-
-```tsx
-<ConfigProvider>
-  <App />
-</ConfigProvider>
-```
-
-legacy 页面可使用 `getPopupContainer={(trigger) => trigger?.closest(".sy-app-workspace") ?? document.body}`。不要无作用域覆盖 `.ant-select-selector`、`.ant-modal` 等私有 class；确实需要覆盖时限定在页面根类下。
-
----
-
-## 6. 平台 Token 兼容说明
-
-OpenXiangda 仍保留部分平台语义类和 CSS 变量，主要用于：
-
-- 平台标准表单、数据管理列表、审批时间线等组件内部样式。
-- 老项目兼容。
-- 多应用统一主题或深度主题定制。
-
-常见兼容类包括 `text-primary`、`text-secondary`、`bg-container`、`bg-layout`、`border-secondary`、`rounded-form`、`shadow-card` 等。AI 编写新业务页面时不要默认使用这些类；除非用户明确要求跟随平台变量主题，或当前项目已有一致的 token 体系。
-
-如果需要统一主题，推荐把主题限制在应用根类下；兼容旧页面时也可以同时声明 `.sy-app-workspace`：
-
-```css
-.theme-brand,
-.sy-app-workspace.theme-brand {
-  --sy-color-primary: #0f766e;
-  --sy-radius-md: 8px;
-}
-```
-
----
-
-## 7. 构建期提醒
-
-OpenXiangda 构建会扫描源码里的 shadcn token 类。如果发现 `bg-card`、`text-muted-foreground`、`text-foreground` 等类，但项目没有显式配置对应 token，会输出 warning。
-
-收到 warning 时优先修正为：
-
-- Tailwind 原生类：`bg-white border border-slate-200 text-slate-600`
-- Tailwind 任意值：`bg-[#1677ff] text-[13px] grid-cols-[240px_1fr]`
-- 或在 `tailwind.config.cjs` 中显式配置这些 shadcn token
-
-warning 不会阻断构建，但它通常意味着页面会出现“颜色、边框、文本层级异常”的视觉问题。
-
----
-
-## 8. 提交前检查
-
-- [ ] 页面样式默认使用 Tailwind 原生类和任意值，而不是平台 token 类？
-- [ ] 没有使用未配置的 shadcn token 类，例如 `bg-card`、`text-muted-foreground`、`text-foreground`？
-- [ ] `tailwind.config.cjs` 保留 OpenXiangda preset、content 扫描和 blocklist？
-- [ ] 业务 CSS 限定在页面根类下，而不是全局裸覆盖？
-- [ ] 只有 legacy `namespace/shadow` 页面才额外配置 `.sy-app-workspace` 弹层容器？