openxiangda 1.0.21 → 1.0.24

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

@@ -40,22 +40,35 @@ Use `--profile` for every destructive or publishing action. Treat the profile as
 
 Run write commands sequentially in the same workspace because they update `.openxiangda/state.json`. Read-only commands such as list, pull, snapshot, and inspect may run in parallel.
 
+## Updates
+
+Use the official npm registry for OpenXiangda package updates because domestic mirrors may lag:
+
+```bash
+npm install -g openxiangda@latest --registry=https://registry.npmjs.org
+openxiangda update check --json
+```
+
+At the start of substantial work, run `openxiangda update check --json`. If `updateAvailable` is true, run `openxiangda update install` before generating or publishing so the CLI and installed skills stay compatible. If the installed CLI does not support `update`, reinstall with the official registry command above, then run `openxiangda skill install --force`.
+
 ## Workspace State
 
 Create a workspace when the current project does not already contain a `sy-lowcode-app-workspace`:
 
 ```bash
-openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_DEV
+openxiangda workspace init ./my-app-workspace --profile dev --app-name "测试应用"
 cd ./my-app-workspace
 pnpm install
 openxiangda env --profile dev
 ```
 
-If the workspace already exists, bind each platform to its own app, then publish from `sy-lowcode-app-workspace`:
+Local workspace state is authoritative. If `.openxiangda/state.json` already contains an app binding for the target profile, use it. If there is no local binding, create a new app with `workspace init --app-name`; do not search platform apps for similar names.
+
+After workspace initialization, inspect `examples/best-practices/` before generating a real app. The examples are copied locally but are not published by default; copy only the selected pattern into `src/`.
+
+If the workspace already exists and the user explicitly provides an existing app, bind each platform to its own app, then publish from `sy-lowcode-app-workspace`:
 
 ```bash
-openxiangda app list --profile dev
-openxiangda app create "测试应用" --profile dev
 openxiangda workspace bind --profile dev --app-type APP_DEV
 openxiangda workspace bind --profile prod --app-type APP_PROD
 cd /path/to/sy-lowcode-app-workspace
@@ -96,6 +109,10 @@ Project state is stored in `.openxiangda/state.json`:
         "menus": {},
         "roles": {},
         "connectors": {},
+        "notifications": {
+          "templates": {},
+          "typeConfigs": {}
+        },
         "pagePermissionGroups": {},
         "formPermissionGroups": {},
         "formSettings": {}
@@ -145,3 +162,4 @@ The publish script is responsible for:
 - `../../references/openxiangda-api.md` — exact endpoint contracts.
 - `../../references/workspace-state.md` — `.openxiangda/state.json` shape and profile-scoped resource maps.
 - `../../references/architecture-patterns.md` — overall architecture of an OpenXiangda app workspace (CRUD data flow, page/form layering, recommended directory organization). Read this when you need to understand how forms, pages, workflows, and platform state fit together end-to-end.
+- `../../references/best-practices.md` — initialized best-practice templates and rules for modular pages, status lifecycles, role governance, data isolation, query performance, and workflow boundaries.

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

@@ -18,11 +18,13 @@ cd /path/to/sy-lowcode-app-workspace
 If the workspace does not exist yet, create it before writing form source:
 
 ```bash
-openxiangda workspace init ./my-app-workspace --profile <name> --app-type APP_XXX
+openxiangda workspace init ./my-app-workspace --profile <name> --app-name "应用名称"
 cd ./my-app-workspace
 pnpm install
 ```
 
+Use `--app-type APP_XXX` only when the user explicitly provides an existing app to reuse.
+
 Create or edit workspace source:
 
 ```text
@@ -61,10 +63,13 @@ Read these references only when writing or reviewing schema:
 - `../../references/forms/layout-and-rules.md`
 - `../../references/platform-data-model.md` — how each field type is persisted (JSONB, `{label, value}` for option fields, attachment shape). Consult before designing schema or wiring values.
 - `../../references/component-guide.md` — when to pick platform form components vs. custom widgets, and the option-component rules.
+- `../../references/best-practices.md` — status lifecycle fields, ownership redundancy, role-governance fields, and the boundary between normal forms and workflow forms.
 
 ## Rules
 
 - Prefer deterministic `formCode` as local key; bind live `formUuid` under the active profile.
+- For business lifecycles, model status with normal form fields (`status`, owner/responsibility fields, action-log relation fields) unless the scenario has real approval tasks. Do not create workflow forms for ordinary status transitions.
+- For permission isolation, add redundant ownership fields such as `collegeId`, `classId`, `ownerDeptId`, and `ownerUserId` at schema time so form permission groups can use structured conditions later.
 - For multi-platform publishing, create or bind the form separately for each profile.
 - Do not copy `formUuid` from dev to prod unless the target platform explicitly already uses that ID.
 - Keep `schema.ts` and `page.tsx` as the source for fields/layout/rules and presentation; generated build output is not the source of truth.

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

@@ -19,11 +19,13 @@ openxiangda workspace publish --profile <name>
 If the workspace does not exist yet, initialize it first:
 
 ```bash
-openxiangda workspace init ./my-app-workspace --profile <name> --app-type APP_XXX
+openxiangda workspace init ./my-app-workspace --profile <name> --app-name "应用名称"
 cd ./my-app-workspace
 pnpm install
 ```
 
+Use `--app-type APP_XXX` only when the user explicitly provides an existing app to reuse.
+
 Direct publish is only for already built assets or targeted repair:
 
 ```bash
@@ -41,7 +43,9 @@ Read these references only when editing page code:
 
 - `../../references/pages/workspace-structure.md`
 - `../../references/pages/app-shell.md` — formal backend / PC portal / mobile portal entry pattern. Read before creating any user-facing main entry or admin console.
+- `../../references/best-practices.md` — initialized examples for modular pages, status lifecycles, role governance, high-performance queries, portal shells, and interactive workbenches. Read before scaffolding complex pages or data management pages.
 - `../../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 the no-hardcoded-color rule. Read before writing any page CSS or Tailwind class.
 - `../../references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, and recommended `src/pages/<pageCode>/` layout. Read before scaffolding a new page or list view.
@@ -52,8 +56,11 @@ Read these references only when editing page code:
 
 - Keep `pageCode` stable and use it as the local logical key.
 - Formal user-facing entries such as admin consoles, PC portals, and mobile portals must be app-shell code pages. Declare `entry: { mode: "app-shell", hidePlatformNav: true, defaultRoute: "<home-route>" }` in `page.config.ts`.
+- Do not generate single-file large pages. Split complex code pages into `domain/`, `shared/services/`, `shared/hooks/`, shared/page-local `components/`, route/config files, and `styles.css` as described in `../../references/best-practices.md`.
+- Keep view code thin. Page components call hooks/services; business rules, state transition rules, permission predicates, and query builders live outside TSX and are reusable by PC and mobile pages.
 - Store live `pageId`, `routeKey`, and `legacyFormUuid` under the current profile only.
 - Use `openxiangda/runtime` for platform data access instead of hardcoding backend URLs in page code.
+- For reminders, alerts, and business messages, declare `src/resources/notifications/` first and call `sdk.notification`; do not hardcode notification API URLs.
 - Named imports from `@ant-design/icons` are supported by the `openxiangda` workspace build proxy, which enumerates icon module exports at runtime.
 - Publish through `openxiangda workspace publish --profile <name>` unless there is a specific repair reason to call `page publish` directly.
 - Do not create custom code pages by writing platform schema directly. The source is React workspace code plus `page.config.ts`.
@@ -62,6 +69,7 @@ Read these references only when editing page code:
 - 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`: never hardcode colors, fonts, spacing, or radii — use the platform CSS variables and the page CSS namespace.
 - 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.
 - When a page misbehaves (lost styles, `options is undefined`, option labels showing raw values, etc.), consult `../../references/troubleshooting.md` before patching symptoms.
 - For custom portal pages and business modals, do not temporarily embed a single `FormProvider` field component from the standard form runtime. If a standard component is required, navigate to a full standard form page or render a complete `StandardFormPage` inside a dedicated carrier route.

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

@@ -34,6 +34,8 @@ Use role codes in permission group JSON. Bind existing role IDs only inside the
 openxiangda permission role-bind sales --role-id <id> --profile dev
 ```
 
+For dynamic multi-role apps, do not hardcode role behavior only in page code. Create a role maintenance form, sync it to platform roles with automation / JS_CODE, and add redundant ownership fields to business forms (`collegeId`, `classId`, `ownerDeptId`, `ownerUserId`, `roleCode`). Use page permission groups for entry visibility and form permission groups with condition-based data permissions for real data isolation.
+
 ## Page Permission Groups
 
 Page permission groups control menu/page visibility:
@@ -92,5 +94,6 @@ Do not store platform-specific public access IDs locally. The CLI resolves by `a
 ## References
 
 - Permission model and examples: `../../references/permissions-settings.md`
+- Dynamic role governance and data-isolation pattern: `../../references/best-practices.md`
 - Profile-isolated IDs: `../../references/workspace-state.md`
 - API fields: `../../references/openxiangda-api.md`

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

@@ -7,6 +7,12 @@ description: Build, validate, publish, enable, and inspect OpenXiangda workflow
 
 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.
 
+## Architecture Boundary
+
+Most business lifecycle flows are not workflows. For ordinary status changes such as `pending -> processing -> resolved -> closed`, use a normal form, a `status` field, redundant responsibility fields, an action-log form, a domain state machine, a service method, and optional automation / JS_CODE.
+
+Create workflow definitions only when the scenario has real approval semantics: approvers, approval tasks, agree/reject actions, approval opinions, node-level permissions, process records, or approval-node side effects.
+
 ## Required Context
 
 Before any write:
@@ -76,6 +82,7 @@ Inside the TypeScript script, prefer `export default async function (ctx) {}` or
 
 - Context: `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, and `ctx.node`.
 - Data/process methods: `ctx.methods.queryOneData`, `queryManyData`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
+- Notification bridge: `ctx.notification.sendByType`, `batchSendByType`, `findConfig`, and `previewTemplate`. Declare templates in `src/resources/notifications/` before using custom `notificationType`.
 - Platform API bridge: `ctx.platform.api.get/post/put/patch/delete/request` for `/openxiangda-api/v1`.
 - Node runtime helpers: `require`, `process`, `Buffer`, `ctx.utils`, `ctx.utils.http`, and `ctx.console`.
 
@@ -100,7 +107,9 @@ Use `automation disable` before risky edits. Published automations create a draf
 
 ## References
 
+- Best-practice architecture and status-flow boundary: `../../references/best-practices.md`
 - Workflow v3 JSON: `../../references/workflow-v3.md`
 - Automation v3 JSON and triggers: `../../references/automation-v3.md`
+- Notification resources and runtime calls: `../../references/notifications.md`
 - API fields: `../../references/openxiangda-api.md`
 - Profile-isolated IDs: `../../references/workspace-state.md`

package/package.json

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

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

@@ -65,6 +65,9 @@ var resolveAppType = (context, explicitAppType) => {
   return appType;
 };
 var buildAppPath = (context, explicitAppType, suffix) => `/${resolveAppType(context, explicitAppType)}${suffix}`;
+var buildOpenXiangdaAppPath = (context, explicitAppType, suffix) => `/openxiangda-api/v1/apps/${encodePathSegment(
+  resolveAppType(context, explicitAppType)
+)}${suffix}`;
 var encodePathSegment = (value) => encodeURIComponent(String(value));
 var getHeaderValue = (headers, name) => {
   if (!headers) {
@@ -1077,7 +1080,11 @@ var createPageSdk = (context) => {
   };
   const notification = {
     sendByType: (params) => request({
-      path: "/api/notification-config/send-by-type",
+      path: buildOpenXiangdaAppPath(
+        context,
+        params.appType,
+        "/notifications/send-by-type"
+      ),
       method: "post",
       body: {
         ...params,
@@ -1085,7 +1092,32 @@ var createPageSdk = (context) => {
       }
     }),
     batchSendByType: (params) => request({
-      path: "/api/notification-config/batch-send-by-type",
+      path: buildOpenXiangdaAppPath(
+        context,
+        params.appType,
+        "/notifications/batch-send-by-type"
+      ),
+      method: "post",
+      body: {
+        ...params,
+        appType: resolveAppType(context, params.appType)
+      }
+    }),
+    findConfig: (notificationType, params = {}) => request({
+      path: buildOpenXiangdaAppPath(
+        context,
+        params.appType,
+        `/notifications/type-configs/${encodePathSegment(notificationType)}`
+      ),
+      method: "get",
+      query: params.formUuid ? { formUuid: params.formUuid } : void 0
+    }),
+    previewTemplate: (params) => request({
+      path: buildOpenXiangdaAppPath(
+        context,
+        params.appType,
+        "/notifications/templates/preview"
+      ),
       method: "post",
       body: {
         ...params,