openxiangda 1.0.264 → 2.0.0-alpha.2

package/openxiangda-skills/references/component-guide.md

@@ -1,287 +0,0 @@
-# Component Guide
-
-> 面向 AI Agent 的组件使用策略：优先复用平台组件，按需基于 antd / antd-mobile 包装，绝不重造已存在的平台能力。
-
----
-
-## 1. 核心原则
-
-1. **平台组件优先**：表单录入、平台数据选择、文件能力和数据管理默认先用 `openxiangda` 平台组件。它们已经接入组织架构、文件存储、权限、多端适配和平台数据格式，重写一遍 = 丢能力 + 后续无法维护。
-2. **antd / antd-mobile 是第二选择**：只有平台组件不存在、或正在做非平台数据的页面控件时，才使用 `antd` / `antd-mobile`。自定义组件必须包装它们，不能从原生 DOM 开始造。
-3. **AI-authored app code 禁止原生表单控件**：`src/forms/**`、`src/pages/**`、workspace 模板和示例中不要直接写 `<input>`、`<select>`、`<textarea>`、`<input type="file">`、手写 picker、手写 uploader、手写人员/部门选择器。原生控件只允许出现在 OpenXiangda SDK / 平台组件内部实现。
-4. **成熟能力先调研开源方案**：图表、动画、拖拽、虚拟列表、富文本、日历、导入导出、复杂表格等，不要直接手写。先查当前项目依赖、官方文档和维护状态，再决定使用库或轻量封装。
-5. **样式默认走 Tailwind 原生类**：业务页面默认使用 Tailwind 原生工具类和任意值；平台变量、平台语义类和 Ant Design token 主要用于平台组件、主题兼容或确实需要统一主题时，不作为业务页面的强制范式。
-6. **谨慎覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变；确实需要覆盖时要限定页面作用域，并优先考虑组件 props、`className`、CSS 变量或 `ConfigProvider`。
-
----
-
-## 1.1 组件选择梯度
-
-| 优先级 | 使用对象 | 适用场景 | 禁止事项 |
-| --- | --- | --- | --- |
-| 1 | OpenXiangda 平台组件 | 表单字段、平台数据选择、文件/图片/富文本/签名/定位、数据管理列表、标准表单容器 | 不要用 antd 或原生控件复刻 |
-| 2 | `antd` / `antd-mobile` | 页面筛选、弹窗、抽屉、步骤条、非平台数据控件、平台暂无组件时的临时包装 | 不要手写 DOM 行为；保留 props/ref/a11y/键盘能力 |
-| 3 | 自定义组件 | 平台和 antd 都不能满足的特殊业务交互 | 先反馈平台缺口；实现只写业务适配层 |
-| 4 | 原生 HTML 控件 | 仅 OpenXiangda SDK / 平台组件内部实现 | AI 生成的 app/workspace 代码禁止使用 |
-
----
-
-## 1.2 开源库选型规则
-
-AI 在实现成熟交互前必须先判断是否已有可靠组件或库：
-
-| 场景 | 优先方案 | 说明 |
-| --- | --- | --- |
-| 表单录入字段 | `openxiangda` 平台字段组件 | 文本、数字、日期、选择、人员、部门、附件、图片、富文本、位置、子表等优先 schema/platform field。 |
-| 平台数据录入能力 | `openxiangda` 平台字段组件 | 人员、部门、附件、图片、富文本、签名、位置、数据管理列表必须平台组件。 |
-| PC 页面控件、筛选、弹窗、表格、步骤条 | `antd` | 仅用于非平台数据控件或平台组件缺失时的包装。不要用原生 `<input>` / `<select>` 复刻。 |
-| 移动端操作、列表、弹层、Tab | `antd-mobile` | 移动端不要强行套 PC 组件；平台字段组件已多端适配时直接用平台组件。 |
-| 图表、仪表盘、经营看板 | `echarts` + `echarts-for-react` | 不要手写 canvas/SVG 图表，除非只是非常小的装饰图形。 |
-| 复杂时间轴动画、编排动画、滚动动画 | `gsap` | 需要动画库时先查 GSAP 官方文档；如果当前 Agent 有动画/GSAP skill，先读取该 skill。简单 hover/transition 用 CSS 即可。 |
-| 拖拽排序、看板、可拖卡片 | `@dnd-kit/*` | 不要自己处理 pointer/mouse/touch 全套事件。 |
-| 大列表虚拟滚动 | antd Table virtual / `rc-virtual-list` | 不要一次渲染几千行 DOM。 |
-| 日期时间处理 | `dayjs` + antd 日期组件 | 不要手写日期解析、时区格式化。 |
-| 富文本 | 平台 `EditorField` 或成熟编辑器封装 | 不要用 contenteditable 从零做编辑器。 |
-
-选型流程：
-
-1. 先查是否已有 OpenXiangda 平台组件或 schema 字段能表达。
-2. 平台没有时，看模板 `package.json` 已有依赖，已有依赖优先复用。
-3. 没有依赖但功能成熟复杂时，调研官方文档、维护状态、包体积和授权，再通过包管理器加入。
-4. 页面代码只写业务适配层，不复制第三方库内部逻辑。
-5. 新增依赖或平台能力缺口后，通过 `openxiangda feedback submit --yes` 反馈选择原因或能力缺口。
-
----
-
-## 2. 必须使用平台组件（重做即丢能力）
-
-| 场景 | 平台组件 | 不重做的原因 | 自动接入的能力 |
-| --- | --- | --- | --- |
-| 选择人员 | `UserSelectField` | 直接接入组织架构 | 人员列表、搜索、按部门筛选、层级树 |
-| 选择部门 | `DepartmentSelectField` | 直接接入组织架构 | 部门树、搜索、多选 |
-| 上传附件 | `AttachmentField` | 接入平台存储或声明式 OSS 存储 | 上传、预览、下载、鉴权 URL 或真实 OSS URL |
-| 上传图片 | `ImageField` | 接入平台存储 | 上传、压缩、缩略图、预览 |
-| 富文本编辑 | `EditorField` | 含图片上传集成 | 完整工具栏、平台图床、粘贴清洗 |
-| 数字签名 | `DigitalSignatureField` | 平台级签名 | 签名采集、验证、归档 |
-| 地理位置 | `LocationField` | 接入地图服务 | 定位、地图选点、地址解析 |
-| 数据管理列表 | `DataManagementList` | 接入数据查询 API | 分页、筛选、导出、批量操作、字段权限、后端 action summary 按钮控制 |
-
-### 示例
-
-```tsx
-import {
-  UserSelectField,
-  DepartmentSelectField,
-  AttachmentField,
-  ImageField,
-} from 'openxiangda';
-
-<UserSelectField name="owner" label="负责人" multiple={false} />
-<DepartmentSelectField name="dept" label="所属部门" />
-<AttachmentField name="files" label="附件" maxCount={5} />
-<AttachmentField name="ossFiles" label="OSS 附件" uploadProvider="oss" storageCode="evaluate_oss" />
-<ImageField name="photos" label="照片" imageCompression={{ enabled: true }} />
-```
-
-OSS 浏览器直传所需的 CORS 规则在 `src/resources/storage/<code>.json` 的 `configJson.cors.managed` 中声明，不要把 bucket 配置写进组件 props。
-
-`AttachmentField` 和 `ImageField` 都可设置 `imageCompression`。启用后只压缩图片文件，保存值会额外包含 `thumbUrl`、`previewUrl` 和 `variants`，用于列表缩略图、小图预览或详情页轻量展示；原图 `url` 仍保留用于下载和高清预览。
-
-预览能力也由运行时统一接管：表单上下文使用 `ImageField` / `AttachmentField`；自定义 React SPA 页面展示任意业务数据中的只读附件时，从 `openxiangda/runtime/react` 使用 `ImagePreviewGrid` / `AttachmentPreviewList`，或使用 `useFilePreview({ items })` 接入自定义卡片、表格和详情操作。不要为只读附件伪造 `FormProvider`。
-
-自定义编辑页确需嵌入平台字段时，使用 `usePageFormRuntimeApi()` 生成 `FormProvider` 的 `config.api`；非 Hook 场景使用 `createPageFormRuntimeApi(sdk)`。不要把所有请求手工转给 `sdk.request()`，因为附件预览的 `responseType: "blob"` 必须走 PageSdk 二进制下载通道。
-
-```tsx
-import { AttachmentPreviewList, ImagePreviewGrid } from "openxiangda/runtime/react"
-
-<AttachmentPreviewList items={record.attachments || []} />
-<ImagePreviewGrid items={record.photos || []} />
-```
-
-这些 API 先调用平台 capability，只为 `canPreview: true` 的文件显示或执行预览，并在站内弹窗中打开图片画廊、视频、音频、PDF、DOCX、XLSX、文本等内容。不要在应用代码中维护扩展名白名单，不要直接引用内部 `FilePreviewContent` / `useFilePreviewController`，也不要把文件流 URL 当成页面入口。DOC/XLS/PPT、ODF 等格式是否可预览由部署侧 ONLYOFFICE 配置决定。
-
-声明式 OSS 文件需要 bucket CORS 允许应用域名读取对象，浏览器端 DOCX/XLSX/HEIC 解析才能工作；平台私有附件由 ticket 文件流处理，不直接暴露对象地址。
-
-业务应用只能从 `openxiangda`、`openxiangda/runtime`、`openxiangda/runtime/react` 等公开入口导入组件和 SDK。不要为了减小包体积去引用 `openxiangda/packages/sdk/dist/...` 内部文件；React SPA 模板已提供 vendor chunk 分组，SDK 会把 `antd-mobile`、`dayjs` 等大型 UI 依赖交给应用构建器按路由拆分。
-
-`DataManagementList` 默认 `permissionMode="auto"`，进入页面会读取表单 action
-summary，并用 `can.create/export/import/delete/workflow/change_records` 隐藏新增、
-导入、导出、删除、流程等按钮。`readonly=true` 仍会强制关闭新增、编辑、删除和
-导入。`actionOverrides` 只能关闭按钮，不能扩大后端权限；敏感授权必须依赖后端
-form actions、`scope_policy` 或 App Function 服务端校验。
-
-> ✅ 一句话原则：**这些场景看到了，直接抄上表，不要自己写。**
-
----
-
-## 3. 推荐使用平台组件（可自定义但不建议从零重做）
-
-| 场景 | 平台组件 | 何时考虑自定义 |
-| --- | --- | --- |
-| 短文本 | `TextField` | 需要复合输入（如扫码 + 输入）时，包装平台字段或 antd `Input` |
-| 长文本 | `TextAreaField` | 需要模板片段、语音转写等增强时包装 |
-| 数字 | `NumberField` | 需要特殊单位联动或计算器式输入时包装 |
-| 下拉选择 | `SelectField` | 需要复杂远程搜索、级联、虚拟滚动时，包装而非重写 |
-| 多选 / 单选 / 复选 | `MultiSelectField` / `RadioField` / `CheckboxField` | 需要特殊展示时包装 |
-| 日期选择 | `DateField` | 特殊日期范围联动、节假日高亮 |
-| 级联日期 / 级联选择 | `CascadeDateField` / `CascadeSelectField` | 需要特殊联动时包装 |
-| 子表 | `SubFormField` | 需要完整行级业务动作时包装 |
-| 表单容器 | `FormProvider` + `FormRenderer` | 需要极度定制布局（分栏、Tab 嵌套表单） |
-| 审批时间线 | `ApprovalTimeline` | 需要自定义节点渲染（增加业务标签、跳转链接） |
-| 摘要卡片 | `FormSummaryCard` | 需要高度自定义字段展示样式 |
-
-自定义时仍应**包装**这些组件，而不是从 antd 从零实现一遍。
-
----
-
-## 4. 自定义组件开发规范
-
-### 4.1 推荐：平台组件缺失时，基于 antd 包装 + 原生 Tailwind 类
-
-先判断平台组件确实不能满足；如果是平台能力缺口，先用 `openxiangda feedback submit --yes` 反馈，再写本地包装作为临时方案。
-
-```tsx
-import { Select, SelectProps } from 'antd';
-import clsx from 'clsx';
-
-type Option = { label: string; value: string };
-
-interface CustomSelectProps extends Omit<SelectProps, 'options'> {
-  options: Option[];
-}
-
-export function CustomSelect({ options, className, ...rest }: CustomSelectProps) {
-  return (
-    <Select
-      className={clsx('w-full rounded-md', className)}
-      getPopupContainer={(trigger) => trigger.parentElement ?? document.body}
-      options={options}
-      {...rest}
-    />
-  );
-}
-```
-
-要点：
-- 透传 `...rest`，保留 antd 全部 API。
-- `getPopupContainer` 解决弹层被裁切问题（详见第 7 节常见错误）。
-- 默认 `cssIsolation: "none"` 时不要额外给弹层加 `sy-app-workspace`；只有 legacy `namespace/shadow` 页面才需要给弹层或容器补 namespace class。
-- 使用 `w-full`、`rounded-md`、`text-slate-600`、`border-slate-200` 等 Tailwind 原生类作为默认基线；如果组件视觉需要精调，可以继续使用 Tailwind 任意值或局部 CSS。
-
-### 4.2 错误：从头实现选择器或原生表单控件
-
-```tsx
-// ❌ 反例：AI-authored app code 不要这样写。
-// 丢失键盘导航、可访问性、移动端体验、平台主题和平台数据格式。
-function BadSelect({ options }) {
-  return (
-    <div style={{ border: '1px solid #d9d9d9', borderRadius: '4px', padding: '4px 11px' }}>
-      {options.map((opt) => (
-        <div key={opt.value} onClick={() => /* ... */}>
-          {opt.label}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-```tsx
-// ❌ 反例：表单录入不要直接写原生控件
-<input value={name} onChange={(event) => setName(event.target.value)} />
-<select value={type} onChange={(event) => setType(event.target.value)} />
-<input type="file" onChange={uploadManually} />
-```
-
-问题清单：
-- 硬编码颜色 `#d9d9d9` → 切主题失效。
-- 丢失 antd 的键盘 / a11y / 输入法行为。
-- 移动端无适配。
-- 平台主题升级时不会跟随。
-- 绕过平台表单 schema、字段权限、文件鉴权、组织架构和标准数据格式。
-
----
-
-## 5. 平台组件的样式自定义
-
-按推荐顺序由轻到重：
-
-1. **className 注入 Tailwind 原生类**
-   ```tsx
-   <UserSelectField className="w-full max-w-md" />
-   ```
-
-2. **CSS 变量覆盖**
-   ```css
-   /* src/index.css */
-   :root,
-   .sy-app-workspace {
-     /* 调整表单控件圆角和品牌色 */
-     --sy-radius-md: 8px;
-     --sy-color-primary: #2563eb;
-   }
-   ```
-
-   > 平台变量可用于统一主题或平台组件兼容，但业务页面不必为了使用 token 牺牲视觉效果。需要页面专属视觉时，可以新增页面级 CSS 变量，建议加业务前缀，避免与平台变量冲突。
-
-3. **antd `ConfigProvider` 主题**
-   ```tsx
-   <ConfigProvider theme={{ token: { colorPrimary: '#2563eb', borderRadius: 8 } }}>
-     <App />
-   </ConfigProvider>
-   ```
-
-4. **谨慎**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）属于私有 API，升级风险较高。确实需要时必须限定在页面根类下；legacy 页面也可以兼容限定在 `.sy-app-workspace` 下。优先考虑 `ConfigProvider`、`className`、组件 props 或 CSS 变量是否能解决。
-
----
-
-## 6. 移动端组件策略
-
-| 场景 | PC | Mobile |
-| --- | --- | --- |
-| 基础组件库 | `antd` | `antd-mobile` |
-| 平台业务组件（如 `UserSelectField`） | ✅ 内置多端适配，**直接用** | ✅ 同左 |
-| 自定义组件 | 自行 `useDeviceDetect` 分支或拆两份实现 | 同左 |
-
-```tsx
-import { useDeviceDetect } from 'openxiangda';
-import { Button as PcButton } from 'antd';
-import { Button as MobileButton } from 'antd-mobile';
-
-export function ActionButton(props) {
-  const { isMobile } = useDeviceDetect();
-  return isMobile ? <MobileButton {...props} /> : <PcButton {...props} />;
-}
-```
-
-> 推荐：能用平台组件就别自己写多端分支；自定义组件且双端差异大时，按 `src/pages/pc` 与 `src/pages/mobile` 整体拆分（详见 `architecture-patterns.md`）。
-
----
-
-## 7. 常见错误（AI Agent 高频踩坑）
-
-| 错误 | 正确做法 |
-| --- | --- |
-| 在 `src/forms/**` 或 `src/pages/**` 直接写 `<input>` / `<select>` / `<textarea>` | 用平台字段组件；平台没有时包装 antd / antd-mobile |
-| 自己写人员选择器（搜员工 + 列表） | 用 `UserSelectField` |
-| 自己实现部门树 | 用 `DepartmentSelectField` |
-| 用 `<input type="file">` 上传 | 用 `AttachmentField` / `ImageField` |
-| 用第三方富文本（TinyMCE 等） | 用 `EditorField` |
-| 自己写列表 + 分页 + 导出 | 用 `DataManagementList` |
-| 常规组件大量写 `style={{ color: '#333', padding: 16 }}` | 优先 Tailwind 原生工具类、任意值或局部 CSS；动态值和少量精调 inline style 可接受 |
-| Select / Date / Modal 弹层错位、被滚动容器裁切 | 默认加 `getPopupContainer={(trigger) => trigger.parentElement}`；legacy `namespace/shadow` 页面才额外使用 `sy-app-workspace` |
-| 不分端，PC 组件直接放移动端 | 按端拆页 + 端内用对应 UI 库 |
-| 无作用域覆盖 `.ant-xxx` 内部 class | 优先用 `className`、CSS 变量或 `ConfigProvider` 主题；必要覆盖时限定到页面命名空间 |
-| 在自定义组件中不透传 `...rest` / `ref` | 透传 props 与 `forwardRef`，保留底层组件全部能力 |
-
----
-
-## 速查 Checklist（提交前自检）
-
-- [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
-- [ ] 表单录入字段 → 优先使用了 `TextField` / `SelectField` / `DateField` 等平台字段，而不是 antd 或原生控件？
-- [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
-- [ ] app/workspace 源码 → 没有直接出现原生 `<input>` / `<select>` / `<textarea>` / file input / 手写 picker 或 uploader？
-- [ ] 样式 → 默认用 Tailwind 原生类 / 任意值 / 局部 CSS；平台 token 只在主题兼容或平台组件需要时使用，且作用域收敛？
-- [ ] 弹层 → 默认使用正常容器；只有 legacy 隔离页面才额外设置 `sy-app-workspace` 样式作用域？
-- [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？

package/openxiangda-skills/references/connector-resources.md

@@ -1,80 +0,0 @@
-# Connector Resources
-
-OpenXiangda engineering resources live under `src/resources/`.
-
-Common folders:
-
-- `connectors`
-- `notifications`
-- `roles`
-- `menus`
-- `workflows`
-- `automations`
-- `data-views`
-- `functions`
-- `auth`
-- `permissions/page-groups`
-- `permissions/form-groups`
-- `settings/forms`
-
-Commands:
-
-```bash
-openxiangda resource validate --profile dev
-openxiangda resource plan --profile dev
-openxiangda resource publish --profile dev
-openxiangda resource pull --profile dev
-```
-
-Connector manifests use stable `code` values. The platform maps connector `code` to the existing connector `methodName`, and API `code` to the existing connector API `methodName`.
-
-Notification manifests live under `src/resources/notifications/` and contain `templates` plus `typeConfigs`. See `notifications.md` before generating reminders or message templates.
-
-Data view manifests live under `src/resources/data-views/` and define read-only joined or aggregate query resources. Use `storageMode: "materialized"` for refreshed lists/reports where lag is acceptable, and `storageMode: "live"` for bounded real-time query shapes. Use row views with `sdk.dataView.query` and aggregate views with `sdk.dataView.stats`. Before generating one, confirm freshness tolerance, query bounds, and indexes for materialized filters/sort fields/dimensions/date buckets. Do not use them for single-form CRUD, simple linkedForm selects, writes, write-back, or ad-hoc BI. See `data-views.md` before generating one.
-
-App Function manifests live under `src/resources/functions/`, with source in `src/functions/<functionCode>/index.ts`. Use them for reusable server-side logic that pages, automations, and workflows can share through `sdk.function.invoke` or `function_call` nodes. App Functions expose controlled runtime helpers such as `ctx.resources`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, `ctx.organization`, `ctx.platform.roles`, and `ctx.platform.api`; they do not expose raw SQL or Redis in the current MVP. Published trusted code may use all application-owned Forms/DataViews in the current tenant/app. Function `resources` remains optional code-to-ID mapping and audit metadata, while cross-app/cross-tenant access stays forbidden. Use `ctx.platform.roles.list/findByCode/addUsers/removeUser` for app role lookup and membership changes; raw `ctx.platform.api` returns an HTTP response plus platform envelope. Runtime page invocations also expose trusted role context on `ctx.operator.roleCodes`, `ctx.operator.platformRoleCodes`, `ctx.operator.currentRoleCode`, `ctx.operator.hasFullAccess`, `ctx.currentUser`, and `ctx.permissions`; `platformRoleCodes` contains the synchronized platform identities `SCHOOL_GUARDIAN`, `SCHOOL_STUDENT`, and `SCHOOL_TEACHER`, while `roleCodes` contains app roles. Use that context for business authorization, and never trust page-submitted role codes for sensitive actions. Page-call grants should use `definitionJson.runtimeInvoke.audience` (`authenticated`, `page_permission_group`, `app_roles`, `platform_roles`, or `scope_policy`); use `roleCodes` for current app-role grants and `platformRoleCodes` for synchronized identities. App Function form writes are trusted backend operations, not direct page-user submit access to the target form. For internal function-only forms, publish form settings with `runtimeWrite.mode="function_only"` so raw write endpoints are closed. App Function organization writes require `app:organization:manage` on the real operator/audit actor. Use JS_CODE V2 only for node-local workflow/automation scripts.
-
-Auth manifests live under `src/resources/auth/`. Use them to enable app-level login methods and bind phone-code/CAS/custom providers to App Functions. Auth provider functions are called only by the platform auth flow. They validate external credentials and return identity assertions such as `phone`, `email`, `externalId`, or `unionId`; they must not issue tokens, set cookies, or mutate platform user/binding tables.
-
-```json
-{
-  "code": "crm",
-  "name": "CRM Service",
-  "url": "https://crm.internal.example.com/api",
-  "authType": "apiKey",
-  "authConfig": {
-    "apiKey": {
-      "key": "X-API-Key",
-      "value": "internal-secret",
-      "in": "header"
-    }
-  },
-  "userContext": {
-    "enabled": true,
-    "inject": [
-      { "target": "header", "key": "X-User-Id", "value": "userId" },
-      { "target": "body", "key": "operator", "value": "user" }
-    ]
-  },
-  "apis": [
-    {
-      "code": "getCustomer",
-      "name": "Get Customer",
-      "method": "POST",
-      "path": "/customers/search",
-      "requestBodyType": "json",
-      "responseType": "json"
-    }
-  ]
-}
-```
-
-Runtime page code:
-
-```ts
-await sdk.connector.call("crm.getCustomer", {
-  body: { keyword: "Acme" },
-})
-```
-
-Do not put third-party domains or API keys in page source. The runtime page calls `/:appType/v1/connectors/actions/invoke` for normal responses and `/:appType/v1/connectors/actions/download` for binary downloads; the platform backend applies auth, user context, and redaction.