openxiangda 1.0.35 → 1.0.37

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

@@ -1,11 +1,45 @@
 ---
 name: openxiangda-page
-description: Build and publish OpenXiangda code pages in sy-lowcode-app-workspace using React, Ant Design, openxiangda/runtime, profile-isolated page IDs, and token-based openxiangda page commands.
+description: Build / edit / publish OpenXiangda custom code pages in `sy-lowcode-app-workspace/src/pages/<pageCode>/` using React + Ant Design + `openxiangda/runtime`. Covers app-shell portals, dashboards, workbenches, data-management lists, mobile portals, page-level connector calls, and single-page publish. Trigger on 创建页面 / 新建页面 / 修改页面 / portal / dashboard / 看板 / 驾驶舱 / 工作台 / 列表页 / mobile portal / app-shell / page.config.ts / pageCode / src/pages, JSX / React / Ant Design page work in this workspace, or any change to `src/pages/<code>/`.
 ---
 
 # OpenXiangda Page
 
-Use this when the user asks to create, update, inspect, or publish a custom code page. Normal form pages and workflow form pages also live in `sy-lowcode-app-workspace`, but under `src/forms/`; this skill covers `src/pages/`.
+## When to use this skill
+
+- User wants to **create / edit a custom code page** under `src/pages/<pageCode>/` (portal, dashboard, list/detail, workbench, mobile portal, etc.).
+- User wants to **publish only a page** (`workspace publish --page <code>`) or rebuild a single page bundle.
+- User asks about page SDK (`openxiangda/runtime`), `page.config.ts`, app-shell entry mode, namespace/style isolation, ECharts, drag-drop, antd icons, or named imports from `@ant-design/icons`.
+- User asks about **portal / admin console / mobile portal entry** — these must be app-shell code pages.
+
+## Quick recipe
+
+```bash
+# 1. preflight
+openxiangda env --profile <name>
+openxiangda page list --profile <name>
+
+# 2. edit source under src/pages/<pageCode>/
+#    page.config.ts (entry mode, route, navigation), domain/, shared/services/, shared/hooks/, components/, styles.css
+
+# 3. preview + publish single page
+openxiangda workspace publish --profile <name> --page <pageCode> --dry-run
+openxiangda workspace publish --profile <name> --page <pageCode>
+```
+
+## DO / DO NOT
+
+- ✅ Formal user-facing entries (admin console / PC portal / mobile portal) MUST be app-shell pages: `entry: { mode: "app-shell", hidePlatformNav: true, defaultRoute: "<home>" }` in `page.config.ts`.
+- ✅ Default to **native Tailwind utilities** for new pages (`bg-white`, `border-slate-200`, `grid-cols-[240px_1fr]`, ...) and `cssIsolation: "none"`. Keep namespace/shadow only for explicit legacy compatibility.
+- ✅ Split complex pages into `domain/`, `shared/services/`, `shared/hooks/`, `components/`, route/config files, `styles.css` (see `references/best-practices.md` and `references/architecture-patterns.md`).
+- ✅ List/detail/CRUD pages: follow `DataManagementList` pattern from `references/architecture-patterns.md`. Pagination + structured `filterGroup` + `OR`. Never fetch huge `pageSize` and filter in browser.
+- ✅ For external APIs use `src/resources/connectors/<code>.json` + `sdk.connector.invoke()`; for joined read-only queries use `src/resources/data-views/<code>.json`.
+- ❌ Single-file giant pages. Split per `references/best-practices.md`.
+- ❌ Hardcoded `/view/...&isRenderNav=false` URLs scattered through page code; use the runtime navigation helper.
+- ❌ shadcn token classes like `bg-card` / `text-muted-foreground` / `text-foreground` unless explicitly configured.
+- ❌ Embed a single `FormProvider` field component temporarily; navigate to a full standard form page or render a complete `StandardFormPage` instead.
+- ❌ Reuse one form UI for both PC and mobile without verifying overlay / picker / bottom-sheet behavior on both viewports.
+- ❌ Hardcode notification or platform API URLs; use `openxiangda/runtime` and `src/resources/notifications/` declarations.
 
 ## CLI Flow
 
@@ -60,7 +94,7 @@ Read these references only when editing page code:
 - `../../references/pages/page-sdk.md`
 - `../../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` — three-layer style architecture, CSS namespace, and flexible Tailwind/CSS guidance. Read before writing substantial page CSS or Tailwind classes.
+- `../../references/style-system.md` — style isolation defaults, Tailwind/CSS guidance, and legacy namespace compatibility. Read before writing substantial page CSS or Tailwind classes.
 - `../../references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, and recommended `src/pages/<pageCode>/` layout. Read before scaffolding a new page or list view.
 - `../../references/component-guide.md` — when to pick platform components, raw Ant Design, or custom components. Read before introducing a new component.
 - `../../references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and their fixes. Read when something does not behave as expected.
@@ -83,7 +117,7 @@ Read these references only when editing page code:
 - Do not scatter hardcoded `/view/...&isRenderNav=false` URLs through page code. Use the runtime navigation API or the local route helper generated for the app shell.
 - Platform menus should bind only the formal app-shell code page for user-facing entry points. Original forms, workflows, and native view pages may remain as development / maintenance resources or permission targets, but should not become the product navigation shell.
 - For prod, explicitly run with `--profile prod`; never rely on the current profile for release operations.
-- Follow the style system in `../../references/style-system.md`: default to native Tailwind utilities and arbitrary values for business pages (`bg-white`, `border`, `border-slate-200`, `text-slate-600`, `grid-cols-[240px_1fr]`, etc.). Keep the page CSS namespace and platform component styles, but do not treat platform token classes as the default authoring pattern. Do not use shadcn token classes such as `bg-card`, `text-muted-foreground`, or `text-foreground` unless the workspace explicitly configures them.
+- Follow the style system in `../../references/style-system.md`: default to native Tailwind utilities and arbitrary values for business pages (`bg-white`, `border`, `border-slate-200`, `text-slate-600`, `grid-cols-[240px_1fr]`, etc.). New pages default to `cssIsolation: "none"` and do not need `.sy-app-workspace`; keep namespace/shadow handling only for legacy pages that explicitly configure it. Do not treat platform token classes as the default authoring pattern, and do not use shadcn token classes such as `bg-card`, `text-muted-foreground`, or `text-foreground` unless the workspace explicitly configures them.
 - For list / detail / CRUD pages, follow `../../references/architecture-patterns.md` (e.g. `DataManagementList`) before writing custom data-fetching loops.
 - Query pages must use pagination with structured conditions. Do not fetch a large `pageSize` and filter in the browser; avoid default `searchKeyWord`, and build multi-field fuzzy search with explicit `filterGroup` + `OR`.
 - Pick components per `../../references/component-guide.md`: prefer the platform component, fall back to Ant Design, and only build a custom component when neither fits.

package/openxiangda-skills/skills/openxiangda-permission-settings/SKILL.md

@@ -1,11 +1,28 @@
 ---
 name: openxiangda-permission-settings
-description: Manage OpenXiangda app roles, page permission groups, form permission groups, and lightweight form settings with profile-isolated IDs and ordinary user token permissions.
+description: Manage OpenXiangda app **roles** (角色), **page permission groups** (页面权限组 / 菜单可见), **form permission groups** (表单权限组 / 提交 / 查看 / 字段权限 / 数据范围 / 数据隔离), and **form settings** (表单设置 / 索引 / 数据管理页 / 公开访问 / public access / 分享) with profile-isolated IDs and ordinary user token permissions. Trigger on 角色 / role / 权限 / permission / 数据范围 / data scope / 字段权限 / field permission / 菜单可见 / menu visibility / 公开访问 / public access / 分享 / share, or any work touching `permission ...` / `settings ...` CLI commands or `src/resources/{roles,pagePermissionGroups,formPermissionGroups,formSettings}/`.
 ---
 
 # OpenXiangda Permission And Settings
 
-Use this skill when the user asks for app roles, visible menus/pages, form submit/view permissions, field permissions, data scopes, or app/form settings.
+## When to use this skill
+
+- User wants to **define / modify roles** for the app.
+- User wants to **gate menu / page visibility** (page permission groups).
+- User wants to **gate form submit / view / edit / data scope / field permissions** (form permission groups).
+- User wants to **publish a form publicly** or change form runtime settings, indexes, data-management page config.
+- User asks about **dynamic role governance** (role maintenance form synced to platform via automation).
+
+## DO / DO NOT
+
+- ✅ Use logical role / group codes locally; live IDs go under the active profile in `.openxiangda/state.json`.
+- ✅ For dynamic multi-role apps, build a role maintenance form + automation/JS_CODE sync, not hardcoded role logic in page code.
+- ✅ For permission scope keys, derive hidden scalars (`collegeScopeKey`, `classScopeKey`, `ownerDeptScopeKey`, `ownerUserScopeKey`, `roleCode`) via `valueSync` from visible select/person/department fields.
+- ✅ Use page permission groups for entry visibility, form permission groups for real data isolation with condition-based data permissions.
+- ❌ Expose raw ID text fields to users for permission scopes.
+- ❌ Store platform-specific public-access IDs locally; CLI resolves by `appType + formUuid` per profile.
+- ❌ Reuse role / permission-group IDs across profiles.
+- ❌ Use AK/SK or legacy `/dingtalk-api/v1.0` — the logged-in user must have the matching app permission.
 
 ## Required Context
 

package/openxiangda-skills/skills/openxiangda-workflow-automation/SKILL.md

@@ -1,11 +1,35 @@
 ---
 name: openxiangda-workflow-automation
-description: Build, validate, publish, enable, and inspect OpenXiangda workflow definitions and automations with profile-isolated resource IDs and ordinary user token permissions.
+description: Build / validate / publish / enable / inspect OpenXiangda **workflows** (审批流程 / approval / approve / reject / transfer / withdraw, v3 graph, JS_CODE trusted_node) and **automations** (自动化 / 集成 / 定时任务 / cron / form data submit/update/delete events, form field change, workflow task / process events, message notifications). Includes architecture boundary between workflow and normal status-machine forms, code-first workflows (`src/workflows/<code>/workflow.ts`) and code-first automations (`src/automations/<code>/index.ts`). Trigger on 审批 / 流程 / workflow / approval / process / 节点 / 并行分支 / 条件分支 / 代办 / 转交 / 撤回 / 驳回 / 自动化 / automation / cron / 定时 / 提交后 / 字段变更 / JS_CODE / trusted_node / src/js-code-nodes.
 ---
 
 # OpenXiangda Workflow And Automation
 
-Use this skill when the user asks for approval workflows, workflow forms, automation rules, scheduled jobs, form-event triggers, or process-triggered automation in OpenXiangda.
+## When to use this skill
+
+- User asks for **approval workflows / 审批 / 流程 / approve / reject / transfer / withdraw / process records / approval-node side effects**.
+- User asks for **automation / 自动化 / cron / 定时 / form-data-submitted/updated/deleted / field-changed / workflow-task-approved / message notification triggers**.
+- User asks for **JS_CODE backend script** (cross-form query, batch update, terminate process, external HTTP, complex orchestration that frontend can't handle).
+- User wants **code-first workflow / automation** (TypeScript source under `src/workflows/` or `src/automations/`).
+
+## Boundary — workflow vs. status field
+
+**Most business lifecycle flows are NOT workflows.** For ordinary `pending → processing → resolved → closed`, use a normal form + `status` field + responsibility fields + action-log form + state machine + automation/JS_CODE.
+
+Create a workflow only when the scenario has **real approval semantics**: approvers, approval tasks, agree/reject actions, opinions, node-level field permissions, process records, approval-node side effects.
+
+## DO / DO NOT
+
+- ✅ New AI-authored automations: prefer **code-first** `automation_code_ts` (`src/automations/<code>/index.ts` + `definition.code.json` + `preview.json`).
+- ✅ New AI-authored workflows that don't need canvas editing: prefer **code-first** `src/workflows/<code>/workflow.ts` using `openxiangda/workflow`.
+- ✅ JS_CODE V2 trusted_node: source in TypeScript under `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`. Run `pnpm build-js-code --script <code>` (validates with `tsc` first).
+- ✅ Use `trigger_v2` for new automation triggers; CLI fills root `appType` / `formUuid` from active profile when `--form-code` is provided.
+- ✅ Use logical `workflowCode` / `automationCode` locally; live IDs are profile-isolated under `.openxiangda/state.json`.
+- ✅ `ctx.logger.debug/info/warn/error(message, data?)` at every important step — inspect via `automation executions` / `automation logs` / `automation diagnose`.
+- ❌ JS_CODE for simple UI interactions, ordinary form validation, or display-only logic — those belong to a normal React code page.
+- ❌ Workflow definitions for non-approval status changes — use a status field instead.
+- ❌ Copy `workflowId` / `automationId` across profiles. Always create/bind separately for each profile.
+- ❌ Inline large JS code blobs in v3 JSON for new work — use trusted_node TypeScript snapshots.
 
 ## Architecture Boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {

package/packages/sdk/dist/runtime/index.cjs

@@ -1279,8 +1279,7 @@ var PageProvider = ({
 };
 
 // packages/sdk/src/styles/antd-theme.ts
-var antdTheme = {
-  cssVar: { prefix: "sy-ant" },
+var baseTheme = {
   hashed: false,
   token: {
     colorPrimary: "#1677ff",
@@ -1308,6 +1307,14 @@ var antdTheme = {
     Card: { paddingLG: 24 }
   }
 };
+var antdTheme = {
+  ...baseTheme,
+  cssVar: { prefix: "ant" }
+};
+var legacyAntdTheme = {
+  ...baseTheme,
+  cssVar: { prefix: "sy-ant" }
+};
 
 // packages/sdk/src/runtime/react/createReactPage.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
@@ -1328,6 +1335,21 @@ var MESSAGE_METHODS = [
 var createRuntimeRoot = (el) => {
   return (0, import_client2.createRoot)(el);
 };
+var normalizeCssIsolation = (value) => {
+  if (value === "namespace" || value === "shadow") return value;
+  return "none";
+};
+var usesLegacyCssIsolation = (cssIsolation) => cssIsolation === "namespace" || cssIsolation === "shadow";
+var getRuntimeCssIsolation = (context) => normalizeCssIsolation(context.page?.capabilities?.cssIsolation);
+var getAntdRuntimeOptions = (cssIsolation) => {
+  const legacy = usesLegacyCssIsolation(cssIsolation);
+  return {
+    prefixCls: legacy ? "sy-ant" : "ant",
+    iconPrefixCls: legacy ? "sy-anticon" : "anticon",
+    messagePrefixCls: legacy ? "sy-ant-message" : "ant-message",
+    theme: legacy ? legacyAntdTheme : antdTheme
+  };
+};
 var isShadowRoot = (rootNode) => typeof ShadowRoot !== "undefined" && rootNode instanceof ShadowRoot;
 var getStyleContainer = (el) => {
   const rootNode = el.getRootNode?.();
@@ -1356,14 +1378,19 @@ var getRuntimeOverlayContainer = (el, portalContainer) => {
     getTargetContainer: () => getRuntimeRoot(el)
   };
 };
-var createAntdConfig = (overlayContainer) => ({
-  locale: import_zh_CN.default,
-  prefixCls: "sy-ant",
-  iconPrefixCls: "sy-anticon",
-  theme: antdTheme,
-  getPopupContainer: overlayContainer.getPopupContainer,
-  getTargetContainer: overlayContainer.getTargetContainer
-});
+var createAntdConfig = (overlayContainer, cssIsolation) => {
+  const antdOptions = getAntdRuntimeOptions(cssIsolation);
+  return {
+    locale: import_zh_CN.default,
+    prefixCls: antdOptions.prefixCls,
+    iconPrefixCls: antdOptions.iconPrefixCls,
+    theme: antdOptions.theme,
+    ...usesLegacyCssIsolation(cssIsolation) ? {
+      getPopupContainer: overlayContainer.getPopupContainer,
+      getTargetContainer: overlayContainer.getTargetContainer
+    } : {}
+  };
+};
 var createPortalContainer = (el) => {
   const rootNode = el.getRootNode?.();
   const parent = isShadowRoot(rootNode) ? rootNode : el.ownerDocument?.body || document.body;
@@ -1413,11 +1440,12 @@ var registerAntdMessageApi = (api) => {
     }
   };
 };
-var installRuntimePortalContainer = (el) => {
+var installRuntimePortalContainer = (el, cssIsolation) => {
   const globalScope = globalThis;
-  const portalContainer = createPortalContainer(el);
+  const portalContainer = usesLegacyCssIsolation(cssIsolation) ? createPortalContainer(el) : null;
   const stack = Array.isArray(globalScope[PORTAL_CONTAINER_STACK_GLOBAL]) ? globalScope[PORTAL_CONTAINER_STACK_GLOBAL] : [];
-  stack.push(portalContainer);
+  const stackTarget = portalContainer ?? el.ownerDocument?.body ?? document.body;
+  stack.push(stackTarget);
   globalScope[PORTAL_CONTAINER_STACK_GLOBAL] = stack;
   globalScope[PORTAL_CONTAINER_RESOLVER_GLOBAL] = () => {
     for (let index = stack.length - 1; index >= 0; index -= 1) {
@@ -1431,42 +1459,43 @@ var installRuntimePortalContainer = (el) => {
   return {
     container: portalContainer,
     release: () => {
-      const position = stack.lastIndexOf(portalContainer);
+      const position = stack.lastIndexOf(stackTarget);
       if (position >= 0) {
         stack.splice(position, 1);
       }
-      portalContainer.remove();
+      portalContainer?.remove();
     }
   };
 };
-var installAntdStaticHolder = (el, portalContainer) => {
+var installAntdStaticHolder = (el, portalContainer, cssIsolation) => {
   installAntdMessageProxy();
+  const antdOptions = getAntdRuntimeOptions(cssIsolation);
   const getMessageContainer = () => {
     if (portalContainer?.isConnected) return portalContainer;
-    return getRuntimeRoot(el);
+    return usesLegacyCssIsolation(cssIsolation) ? getRuntimeRoot(el) : document.body;
   };
   import_antd.ConfigProvider.config({
-    prefixCls: "sy-ant",
-    iconPrefixCls: "sy-anticon",
-    theme: antdTheme,
+    prefixCls: antdOptions.prefixCls,
+    iconPrefixCls: antdOptions.iconPrefixCls,
+    theme: antdOptions.theme,
     holderRender: (children) => {
       if (!el.isConnected) {
         return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
           import_antd.ConfigProvider,
           {
-            prefixCls: "sy-ant",
-            iconPrefixCls: "sy-anticon",
-            theme: antdTheme,
+            prefixCls: antdOptions.prefixCls,
+            iconPrefixCls: antdOptions.iconPrefixCls,
+            theme: antdOptions.theme,
             children
           }
         );
       }
       const overlayContainer = getRuntimeOverlayContainer(el, portalContainer);
-      return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_cssinjs.StyleProvider, { hashPriority: "high", container: getStyleContainer(el), children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_antd.ConfigProvider, { ...createAntdConfig(overlayContainer), children }) });
+      return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_cssinjs.StyleProvider, { hashPriority: "high", container: getStyleContainer(el), children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_antd.ConfigProvider, { ...createAntdConfig(overlayContainer, cssIsolation), children }) });
     }
   });
   import_antd.message.config({
-    prefixCls: "sy-ant-message",
+    prefixCls: antdOptions.messagePrefixCls,
     getContainer: getMessageContainer
   });
 };
@@ -1484,20 +1513,27 @@ var createReactPage = (AppComponent) => {
   let currentContainer = null;
   let releasePortalContainer = null;
   let portalContainer = null;
+  let currentCssIsolation = null;
   const render = (el, context) => {
-    el.classList.add(NAMESPACE_ROOT_CLASS);
-    if (!root || currentContainer !== el || !portalContainer?.isConnected) {
+    const cssIsolation = getRuntimeCssIsolation(context);
+    if (usesLegacyCssIsolation(cssIsolation)) {
+      el.classList.add(NAMESPACE_ROOT_CLASS);
+    } else {
+      el.classList.remove(NAMESPACE_ROOT_CLASS);
+    }
+    if (!root || currentContainer !== el || currentCssIsolation !== cssIsolation || usesLegacyCssIsolation(cssIsolation) && !portalContainer?.isConnected) {
       root?.unmount();
       releasePortalContainer?.();
       root = createRuntimeRoot(el);
       currentContainer = el;
-      const portalHandle = installRuntimePortalContainer(el);
+      currentCssIsolation = cssIsolation;
+      const portalHandle = installRuntimePortalContainer(el, cssIsolation);
       portalContainer = portalHandle.container;
       releasePortalContainer = portalHandle.release;
     }
     const overlayContainer = getRuntimeOverlayContainer(el, portalContainer);
-    installAntdStaticHolder(el, portalContainer);
-    const antdConfig = createAntdConfig(overlayContainer);
+    installAntdStaticHolder(el, portalContainer, cssIsolation);
+    const antdConfig = createAntdConfig(overlayContainer, cssIsolation);
     root.render(
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_cssinjs.StyleProvider, { hashPriority: "high", container: getStyleContainer(el), children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_antd.ConfigProvider, { ...antdConfig, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_antd.App, { children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(RuntimeMessageBridge, { children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(PageProvider, { context, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(AppComponent, {}) }) }) }) }) })
     );
@@ -1516,6 +1552,7 @@ var createReactPage = (AppComponent) => {
       currentContainer = null;
       releasePortalContainer = null;
       portalContainer = null;
+      currentCssIsolation = null;
     }
   };
 };