openxiangda 1.0.0

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

@@ -0,0 +1,198 @@
+# Component Guide
+
+> 面向 AI Agent 的组件使用策略：优先复用平台组件，按需基于 antd / antd-mobile 包装，绝不重造已存在的平台能力。
+
+---
+
+## 1. 核心原则
+
+1. **平台组件优先**：所有平台组件已经接入了组织架构、文件存储、权限、多端适配等平台能力，重写一遍 = 丢能力 + 后续无法维护。
+2. **基于 antd / antd-mobile 包装**：自定义组件必须站在 antd 之上，保证 PC 和移动端的基础体验一致。
+3. **样式走变量与语义类**：使用 CSS 变量、Tailwind 语义类，**禁止**在 JSX 中硬编码颜色、间距、字号、圆角。
+4. **不覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变。
+
+---
+
+## 2. 必须使用平台组件（重做即丢能力）
+
+| 场景 | 平台组件 | 不重做的原因 | 自动接入的能力 |
+| --- | --- | --- | --- |
+| 选择人员 | `UserSelectField` | 直接接入组织架构 | 人员列表、搜索、按部门筛选、层级树 |
+| 选择部门 | `DepartmentSelectField` | 直接接入组织架构 | 部门树、搜索、多选 |
+| 上传附件 | `AttachmentField` | 接入平台存储 | 上传、预览、下载、鉴权 URL |
+| 上传图片 | `ImageField` | 接入平台存储 | 上传、压缩、缩略图、预览 |
+| 富文本编辑 | `EditorField` | 含图片上传集成 | 完整工具栏、平台图床、粘贴清洗 |
+| 数字签名 | `DigitalSignatureField` | 平台级签名 | 签名采集、验证、归档 |
+| 地理位置 | `LocationField` | 接入地图服务 | 定位、地图选点、地址解析 |
+| 数据管理列表 | `DataManagementList` | 接入数据查询 API | 分页、筛选、导出、批量操作、字段权限 |
+
+### 示例
+
+```tsx
+import {
+  UserSelectField,
+  DepartmentSelectField,
+  AttachmentField,
+} from 'openxiangda';
+
+<UserSelectField name="owner" label="负责人" multiple={false} />
+<DepartmentSelectField name="dept" label="所属部门" />
+<AttachmentField name="files" label="附件" maxCount={5} />
+```
+
+> ✅ 一句话原则：**这些场景看到了，直接抄上表，不要自己写。**
+
+---
+
+## 3. 推荐使用平台组件（可自定义但不建议从零重做）
+
+| 场景 | 平台组件 | 何时考虑自定义 |
+| --- | --- | --- |
+| 下拉选择 | `SelectField` | 需要复杂远程搜索、级联、虚拟滚动时，包装而非重写 |
+| 日期选择 | `DateField` | 特殊日期范围联动、节假日高亮 |
+| 表单容器 | `FormProvider` + `FormRenderer` | 需要极度定制布局（分栏、Tab 嵌套表单） |
+| 审批时间线 | `ApprovalTimeline` | 需要自定义节点渲染（增加业务标签、跳转链接） |
+| 摘要卡片 | `FormSummaryCard` | 需要高度自定义字段展示样式 |
+
+自定义时仍应**包装**这些组件，而不是从 antd 从零实现一遍。
+
+---
+
+## 4. 自定义组件开发规范
+
+### 4.1 正确：基于 antd 包装 + CSS 变量 + 语义类
+
+```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-form', className)}
+      popupClassName="sy-app-workspace"
+      getPopupContainer={(trigger) => trigger.parentElement ?? document.body}
+      options={options}
+      {...rest}
+    />
+  );
+}
+```
+
+要点：
+- 透传 `...rest`，保留 antd 全部 API。
+- `popupClassName="sy-app-workspace"` 确保弹层应用平台样式作用域。
+- `getPopupContainer` 解决弹层被裁切问题（详见第 7 节常见错误）。
+- 使用 `w-full`、`rounded-form` 等语义类，不写 `style={{ width: '100%' }}`。
+
+### 4.2 错误：从头实现选择器
+
+```tsx
+// ❌ 反例：丢失键盘导航、可访问性、移动端体验、平台主题
+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>
+  );
+}
+```
+
+问题清单：
+- 硬编码颜色 `#d9d9d9` → 切主题失效。
+- 丢失 antd 的键盘 / a11y / 输入法行为。
+- 移动端无适配。
+- 平台主题升级时不会跟随。
+
+---
+
+## 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;
+   }
+   ```
+
+   > 覆盖时只能使用 `style-system.md` 中定义的 `--sy-color-*`、`--sy-radius-*`、`--sy-spacing-*` 等变量名，自创变量不会生效。
+
+3. **antd `ConfigProvider` 主题**
+   ```tsx
+   <ConfigProvider theme={{ token: { colorPrimary: '#2563eb', borderRadius: 8 } }}>
+     <App />
+   </ConfigProvider>
+   ```
+
+4. **禁止**：直接覆盖组件内部 class（`.ant-select-selector { ... }`）—— fragile，升级即坏。
+
+---
+
+## 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 高频踩坑）
+
+| 错误 | 正确做法 |
+| --- | --- |
+| 自己写人员选择器（搜员工 + 列表） | 用 `UserSelectField` |
+| 自己实现部门树 | 用 `DepartmentSelectField` |
+| 用 `<input type="file">` 上传 | 用 `AttachmentField` / `ImageField` |
+| 用第三方富文本（TinyMCE 等） | 用 `EditorField` |
+| 自己写列表 + 分页 + 导出 | 用 `DataManagementList` |
+| `style={{ color: '#333', padding: 16 }}` 硬编码 | Tailwind 语义类或 CSS 变量 |
+| Select / Date / Modal 弹层错位、被滚动容器裁切 | 加 `getPopupContainer={(trigger) => trigger.parentElement}`，并在弹层 `popupClassName` 上加 `sy-app-workspace` |
+| 不分端，PC 组件直接放移动端 | 按端拆页 + 端内用对应 UI 库 |
+| 覆盖 `.ant-xxx` 内部 class | 用 `className`、CSS 变量或 `ConfigProvider` 主题 |
+| 在自定义组件中不透传 `...rest` / `ref` | 透传 props 与 `forwardRef`，保留底层组件全部能力 |
+
+---
+
+## 速查 Checklist（提交前自检）
+
+- [ ] 涉及人员 / 部门 / 文件 / 图片 / 富文本 / 签名 / 地图 / 列表 → 用了平台组件？
+- [ ] 自定义组件 → 基于 antd / antd-mobile 包装并透传 props？
+- [ ] 样式 → 全部走 Tailwind 语义类 / CSS 变量 / ConfigProvider，无硬编码？
+- [ ] 弹层 → 设置了 `getPopupContainer` 与 `sy-app-workspace` 弹层样式作用域？
+- [ ] 多端 → PC 用 antd、Mobile 用 antd-mobile，业务逻辑共享？

package/openxiangda-skills/references/forms/component-registry.md

@@ -0,0 +1,53 @@
+# Form Component Registry
+
+Use platform-supported component names in FormSchema.
+
+Common field components:
+
+| Component | Use |
+| --- | --- |
+| `TextField` | Short text |
+| `TextAreaField` | Long text |
+| `NumberField` | Numeric value |
+| `DateField` | Date or datetime |
+| `CascadeDateField` | Date range |
+| `SelectField` | Single select |
+| `MultiSelectField` | Multi select |
+| `RadioField` | Radio group |
+| `CheckboxField` | Checkbox group |
+| `UserSelectField` | User picker |
+| `DepartmentSelectField` | Department picker |
+| `AttachmentField` | File upload |
+| `ImageField` | Image upload |
+| `AddressField` | Address |
+| `CascadeSelectField` | Cascading select |
+| `AssociationFormField` | Select records from another form when a linked-form picker is required |
+| `LocationField` | Location |
+| `EditorField` | Rich text |
+| `JSONField` | Structured JSON |
+| `SubFormField` | Child table; do not recursively flatten child fields unless the runtime requires it |
+
+Rules:
+
+- Prefer simple field types first.
+- Do not use a code page where a normal form can solve the workflow.
+- Keep option values stable; labels may be user-facing.
+- Avoid generated random field IDs after initial creation.
+- Use field-level `rules` for validation. Required fields should set both `required: true` and `rules: [{ required: true, message: "..." }]` when a custom message is needed.
+- For option components (`SelectField`, `MultiSelectField`, `RadioField`, `CheckboxField`, `CascadeSelectField`), always provide an `options` array. Use `options: [{ value: "stable_code", label: "显示名" }]`; if options will be loaded elsewhere later, still emit `options: []` so the runtime does not crash on `options.map(...)`.
+- Do not rely on custom `relation` metadata alone for normal form pages. A `SelectField` with `relation` but no `options` can white-screen with `Cannot read properties of undefined (reading 'map')`. Use static `options`, `AssociationFormField`, or a custom code page that resolves linked records.
+- For `NumberField`, prefer explicit `min`, `max`, `precision`, and `unit` when the business meaning is constrained.
+- For `DateField`, use `mode: "date"` or `mode: "datetime"` and a stable `format` such as `YYYY-MM-DD` or `YYYY-MM-DD HH:mm`.
+- For `CascadeDateField`, store a date range and document whether the value is inclusive.
+- For `UserSelectField` and `DepartmentSelectField`, do not invent user or department IDs. Use runtime/platform selection.
+- For `AttachmentField` and `ImageField`, do not hardcode OSS URLs in defaults unless the file has already been uploaded by platform tooling.
+- For `SubFormField`, use `columns` for child fields and keep child `fieldId` values stable within the subform.
+- `TextAreaField` is accepted by workspace tools and normalized to runtime `TextareaField`; prefer `TextAreaField` in OpenXiangda docs for readability.
+
+Common validation rule examples:
+
+```ts
+rules: [{ required: true, message: "请填写名称" }]
+rules: [{ preset: "phone", message: "请输入有效手机号" }]
+rules: [{ min: 0, message: "不能小于 0" }]
+```

package/openxiangda-skills/references/forms/form-schema.md

@@ -0,0 +1,109 @@
+# FormSchema
+
+Form source lives in `sy-lowcode-app-workspace`. `schema.ts` describes fields, persistence, and rules; `page.tsx` renders the actual form page using platform components. The generated platform page must come from the workspace bundle, not the legacy default platform schema page.
+
+Typical file:
+
+```text
+src/forms/<formCode>/schema.ts
+src/forms/<formCode>/page.tsx
+```
+
+The schema must default-export a `defineFormSchema(...)` result from `openxiangda`.
+
+Minimal schema:
+
+```ts
+import { defineFormSchema } from "openxiangda";
+
+export default defineFormSchema({
+  formMeta: {
+    formUuid: "",
+    appType: process.env.OPENXIANGDA_APP_TYPE || "APP_XXXX",
+    title: "客户信息",
+  },
+  fields: [
+    {
+      fieldId: "customer_name",
+      componentName: "TextField",
+      label: "客户名称",
+      required: true,
+      rules: [{ required: true, message: "请填写客户名称" }],
+      placeholder: "请输入客户名称",
+    },
+    {
+      fieldId: "customer_type",
+      componentName: "SelectField",
+      label: "客户类型",
+      options: [
+        { value: "enterprise", label: "企业客户" },
+        { value: "individual", label: "个人客户" },
+      ],
+    },
+  ],
+});
+```
+
+## Required Metadata
+
+- `formMeta.formUuid`: live form ID. It may start empty during local authoring; publish tools can create and write it back.
+- `formMeta.appType`: target app. In OpenXiangda mode, `OPENXIANGDA_APP_TYPE` may override local config.
+- `formMeta.title`: user-facing form name.
+- Do not require `formMeta.formType`; the current `openxiangda` schema type only requires `formUuid`, `appType`, and `title`.
+
+## Field Rules
+
+- Each persisted field needs a stable `fieldId`.
+- Field labels should be user-facing Chinese names when the app is Chinese.
+- Use platform-supported field components from `component-registry.md`.
+- Do not generate fields that are only visual layout containers.
+- Put validation rules on fields as `field.rules`. Do not put validation objects in top-level `schema.rules`.
+- For option components (`SelectField`, `MultiSelectField`, `RadioField`, `CheckboxField`, `CascadeSelectField`), always include `options`. If a linked lookup is not ready, use `options: []` instead of omitting it.
+
+## Effects vs Validation
+
+Top-level `schema.rules` is reserved for `FormEffect[]`, not validation. A `FormEffect` must have both `when` and `then`:
+
+```ts
+rules: [
+  {
+    id: "show_invoice_title",
+    when: { field: "need_invoice", operator: "eq", value: "yes" },
+    then: [{ action: "show", target: "invoice_title" }],
+  },
+]
+```
+
+Do not generate old-style top-level validation rules like this:
+
+```ts
+// Wrong: this causes runtime white screens because `when` is missing.
+rules: [
+  { id: "rule_required_name", type: "validation", field: "name", required: true },
+]
+```
+
+Use field-level validation instead:
+
+```ts
+{
+  fieldId: "name",
+  componentName: "TextField",
+  label: "姓名",
+  required: true,
+  rules: [{ required: true, message: "请填写姓名" }],
+}
+```
+
+## Layout
+
+`layout` is optional. If omitted, the standard runtime renders fields in declaration order. When using `layout`, only use `FormLayoutNode` structures supported by `openxiangda` (`field`, `section`, `grid`, `tabs`, `steps`).
+
+## Publish Rules
+
+- Build output is registered through `openxiangda workspace publish --profile <name>`.
+- The publish path uses `/openxiangda-api/v1` with `OPENXIANGDA_ACCESS_TOKEN`.
+- Do not use AK/SK for new OpenXiangda work.
+- Do not stop after `openxiangda form create`; that only creates the platform form shell. A form page is complete only after workspace publish builds and registers the bundle.
+- If a published form page is blank and the browser console says `Cannot use 'in' operator to search for 'all' in undefined`, check for invalid top-level `schema.rules` entries missing `when`.
+- If a published form page is blank and the browser console says `Cannot read properties of undefined (reading 'map')` near `SelectField`, check for option components missing `options`.

package/openxiangda-skills/references/forms/layout-and-rules.md

@@ -0,0 +1,24 @@
+# Form Layout And Rules
+
+## Layout
+
+- Keep forms scan-friendly: sections, rows, and field order should follow the user's real workflow.
+- Use groups for semantic sections, not for decoration.
+- Required fields should be limited to data that is actually needed to submit.
+- A process form should put approval-relevant fields near the top.
+
+## Rules
+
+Use declarative rules when possible:
+
+- Required validation
+- Numeric range validation
+- Option visibility
+- Field visibility
+- Computed/default values
+
+Avoid hidden custom script unless the behavior cannot be expressed declaratively.
+
+## Data Management
+
+Data management views are settings/resources around a form, not separate source forms. Store their live IDs under the current profile when they are created.