openxiangda 1.0.268 → 1.0.270

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

@@ -1,9 +1,9 @@
-# Component Guide
-
-> 面向 AI Agent 的组件使用策略：优先复用平台组件，按需基于 antd / antd-mobile 包装，绝不重造已存在的平台能力。
-
----
-
+# Component Guide
+
+> 面向 AI Agent 的组件使用策略：优先复用平台组件，按需基于 antd / antd-mobile 包装，绝不重造已存在的平台能力。
+
+---
+
 ## 1. 核心原则
 
 1. **平台组件优先**：表单录入、平台数据选择、文件能力和数据管理默认先用 `openxiangda` 平台组件。它们已经接入组织架构、文件存储、权限、多端适配和平台数据格式，重写一遍 = 丢能力 + 后续无法维护。
@@ -52,23 +52,23 @@ AI 在实现成熟交互前必须先判断是否已有可靠组件或库：
 5. 新增依赖或平台能力缺口后，通过 `openxiangda feedback submit --yes` 反馈选择原因或能力缺口。
 
 ---
-
-## 2. 必须使用平台组件（重做即丢能力）
-
-| 场景 | 平台组件 | 不重做的原因 | 自动接入的能力 |
-| --- | --- | --- | --- |
-| 选择人员 | `UserSelectField` | 直接接入组织架构 | 人员列表、搜索、按部门筛选、层级树 |
-| 选择部门 | `DepartmentSelectField` | 直接接入组织架构 | 部门树、搜索、多选 |
+
+## 2. 必须使用平台组件（重做即丢能力）
+
+| 场景 | 平台组件 | 不重做的原因 | 自动接入的能力 |
+| --- | --- | --- | --- |
+| 选择人员 | `UserSelectField` | 直接接入组织架构 | 人员列表、搜索、按部门筛选、层级树 |
+| 选择部门 | `DepartmentSelectField` | 直接接入组织架构 | 部门树、搜索、多选 |
 | 上传附件 | `AttachmentField` | 接入平台存储或声明式 OSS 存储 | 上传、预览、下载、鉴权 URL 或真实 OSS URL |
-| 上传图片 | `ImageField` | 接入平台存储 | 上传、压缩、缩略图、预览 |
-| 富文本编辑 | `EditorField` | 含图片上传集成 | 完整工具栏、平台图床、粘贴清洗 |
-| 数字签名 | `DigitalSignatureField` | 平台级签名 | 签名采集、验证、归档 |
-| 地理位置 | `LocationField` | 接入地图服务 | 定位、地图选点、地址解析 |
+| 上传图片 | `ImageField` | 接入平台存储 | 上传、压缩、缩略图、预览 |
+| 富文本编辑 | `EditorField` | 含图片上传集成 | 完整工具栏、平台图床、粘贴清洗 |
+| 数字签名 | `DigitalSignatureField` | 平台级签名 | 签名采集、验证、归档 |
+| 地理位置 | `LocationField` | 接入地图服务 | 定位、地图选点、地址解析 |
 | 数据管理列表 | `DataManagementList` | 接入数据查询 API | 分页、筛选、导出、批量操作、字段权限、后端 action summary 按钮控制 |
-
-### 示例
-
-```tsx
+
+### 示例
+
+```tsx
 import {
   UserSelectField,
   DepartmentSelectField,
@@ -113,7 +113,7 @@ form actions、`scope_policy` 或 App Function 服务端校验。
 > ✅ 一句话原则：**这些场景看到了，直接抄上表，不要自己写。**
 
 ---
-
+
 ## 3. 推荐使用平台组件（可自定义但不建议从零重做）
 
 | 场景 | 平台组件 | 何时考虑自定义 |
@@ -129,45 +129,45 @@ form actions、`scope_policy` 或 App Function 服务端校验。
 | 表单容器 | `FormProvider` + `FormRenderer` | 需要极度定制布局（分栏、Tab 嵌套表单） |
 | 审批时间线 | `ApprovalTimeline` | 需要自定义节点渲染（增加业务标签、跳转链接） |
 | 摘要卡片 | `FormSummaryCard` | 需要高度自定义字段展示样式 |
-
-自定义时仍应**包装**这些组件，而不是从 antd 从零实现一遍。
-
----
-
-## 4. 自定义组件开发规范
-
+
+自定义时仍应**包装**这些组件，而不是从 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 (
+
+```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
@@ -176,13 +176,13 @@ export function CustomSelect({ options, className, ...rest }: CustomSelectProps)
 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>
-  );
+      {options.map((opt) => (
+        <div key={opt.value} onClick={() => /* ... */}>
+          {opt.label}
+        </div>
+      ))}
+    </div>
+  );
 }
 ```
 
@@ -199,89 +199,89 @@ function BadSelect({ options }) {
 - 移动端无适配。
 - 平台主题升级时不会跟随。
 - 绕过平台表单 schema、字段权限、文件鉴权、组织架构和标准数据格式。
-
----
-
-## 5. 平台组件的样式自定义
-
-按推荐顺序由轻到重：
-
+
+---
+
+## 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;
-   }
-   ```
-
+   ```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>
-   ```
-
+
+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
+
+---
+
+## 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 高频踩坑）
-
+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` |
+| 用第三方富文本（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 库 |
+| 不分端，PC 组件直接放移动端 | 按端拆页 + 端内用对应 UI 库 |
 | 无作用域覆盖 `.ant-xxx` 内部 class | 优先用 `className`、CSS 变量或 `ConfigProvider` 主题；必要覆盖时限定到页面命名空间 |
-| 在自定义组件中不透传 `...rest` / `ref` | 透传 props 与 `forwardRef`，保留底层组件全部能力 |
-
----
-
-## 速查 Checklist（提交前自检）
-
+| 在自定义组件中不透传 `...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，业务逻辑共享？
+- [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？

package/openxiangda-skills/references/openxiangda-api.md

@@ -969,3 +969,15 @@ Requires Bearer token. Creates a short-lived signed OSS upload URL for browser d
 ### POST `/apps/:appType/storage-configs/:code/objects/delete`
 
 Requires Bearer token. Deletes an OSS object under the configured `pathPrefix`.
+## Inbound Webhook
+
+- Management: `GET|POST /openxiangda-api/v1/apps/:appType/webhooks`
+- Detail/update/disable: `GET|POST|PUT|DELETE /openxiangda-api/v1/apps/:appType/webhooks/:code`
+- Delivery list/detail: `GET /openxiangda-api/v1/apps/:appType/webhooks/:code/deliveries[/:deliveryId]`
+- Public callback: `POST /openxiangda-webhooks/v1/:endpointId`
+
+The public `endpointId` resolves tenant/application ownership and is never
+replaced with `appType`. Management calls use normal profile authentication;
+the public callback is unauthenticated at the platform edge and the target
+Function must verify the provider signature from the exact raw body. See
+`webhooks.md` for the declaration and runtime envelope.