openxiangda 1.0.21 → 1.0.24

package/lib/workspace-init.js

@@ -41,8 +41,14 @@ function initWorkspace(options = {}) {
             automations: {},
             menus: {},
             roles: {},
+            connectors: {},
+            notifications: {
+              templates: {},
+              typeConfigs: {},
+            },
             pagePermissionGroups: {},
             formPermissionGroups: {},
+            formSettings: {},
           },
           updatedAt: new Date().toISOString(),
         },
@@ -69,6 +75,12 @@ function initWorkspace(options = {}) {
   };
 }
 
+function assertCanInitializeWorkspace(options = {}) {
+  const targetDir = path.resolve(options.dir || process.cwd());
+  ensureCanInitialize(targetDir, Boolean(options.force));
+  return targetDir;
+}
+
 function ensureCanInitialize(targetDir, force) {
   if (!fs.existsSync(TEMPLATE_DIR)) {
     throw new Error(`workspace 模板不存在: ${TEMPLATE_DIR}`);
@@ -135,5 +147,6 @@ function buildNextSteps(targetDir, installedDependencies, bound) {
 }
 
 module.exports = {
+  assertCanInitializeWorkspace,
   initWorkspace,
 };

package/openxiangda-skills/SKILL.md

@@ -35,27 +35,36 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
    ```bash
    openxiangda login https://dev-lowcode.example.com --profile dev
    ```
-4. Check current context before any write:
+4. Check the CLI version and current context before any write:
    ```bash
+   openxiangda update check --json
    openxiangda env --profile dev
    openxiangda auth status --profile dev
    ```
-5. Ensure there is a local app workspace. If the current directory is not a `sy-lowcode-app-workspace` and no app workspace exists yet, initialize one:
+   If `updateAvailable` is true, update from the official npm registry before continuing:
    ```bash
-   openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
+   openxiangda update install
+   ```
+5. Ensure there is a local app workspace. Local workspace state is authoritative:
+   - If the current workspace already has `.openxiangda/state.json` with an app binding for the target profile, use that app.
+   - If the user explicitly provides an `appType` or asks to reuse an existing app, bind to that exact app.
+   - If the current folder is empty or has no local app binding, create a new app and workspace; do not search the platform for similar app names.
+   ```bash
+   openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
    cd ./my-app-workspace
    pnpm install
    ```
-6. Bind the local workspace to the app for the selected platform:
+6. To bind an existing app only when explicitly requested:
    ```bash
-   openxiangda app list --profile dev
-   # or create one when needed:
-   openxiangda app create "示例应用" --profile dev
+   openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
+   # or, inside an existing workspace:
    openxiangda workspace bind --profile dev --app-type APP_XXXX
-   cd /path/to/sy-lowcode-app-workspace
+   ```
+7. Publish from the local workspace:
+   ```bash
    openxiangda workspace publish --profile dev
    ```
-7. For multi-platform publishing, always pass `--profile` explicitly:
+8. For multi-platform publishing, always pass `--profile` explicitly:
    ```bash
    openxiangda workspace publish --profile prod
    ```
@@ -63,7 +72,10 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 ## Rules
 
 - Never ask the user for `appKey`, `appSecret`, `AK`, or `SK`.
-- If `openxiangda` is not available in PATH, the CLI package is not installed or linked. In this repo, use `npm link`; in a packaged install, use `npm install -g .` or the published package.
+- If `openxiangda` is not available in PATH, the CLI package is not installed or linked. In this repo, use `npm link`; in a packaged install, use `npm install -g openxiangda@latest --registry=https://registry.npmjs.org`.
+- Always prefer the official npm registry for OpenXiangda updates. Domestic mirrors may lag and return an older package.
+- Run `openxiangda update check --json` when starting substantial work or diagnosing version/skill mismatches. If it reports an update, run `openxiangda update install` so the CLI and installed skills match. If the installed CLI does not support `update`, run `npm install -g openxiangda@latest --registry=https://registry.npmjs.org` and then `openxiangda skill install --force`.
+- Local `.openxiangda/state.json` is the source of truth for app binding. In an empty folder or unbound workspace, create a new app with `workspace init --app-name`; do not infer reuse from similar platform app names.
 - If there is no `sy-lowcode-app-workspace`, create one with `openxiangda workspace init <dir>` before writing forms, pages, or JS_CODE nodes.
 - Never treat `openxiangda form create` as page generation. It only creates a low-level platform form shell for diagnostics or for workspace publish internals. The source of user-facing pages is `sy-lowcode-app-workspace`.
 - Publish normal form pages, workflow form pages, and custom code pages through `openxiangda workspace publish --profile <name>` from the app workspace.
@@ -71,6 +83,7 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - Use logical resource codes in local files. Platform-specific IDs such as `formUuid`, `pageId`, `workflowId`, and `automationId` must be isolated by profile.
 - Put engineering-managed resources in `src/resources/` and use `openxiangda resource validate|plan|publish|pull`. `workspace publish` publishes workspace forms/pages first, then runs non-destructive resource upsert. Only pass `--prune` when the user explicitly wants local manifests to delete platform-side extras.
 - For external APIs, create a connector manifest in `src/resources/connectors/` and call it from pages through `sdk.connector`; never put third-party API keys in page source.
+- Before scaffolding a real app, complex page, data management page, portal shell, status lifecycle, role governance, or automation, read `references/best-practices.md` and pick the architecture first. Prefer copying the relevant pattern from `examples/best-practices/` into `src/` instead of generating a single large page file.
 - Before publishing to another platform, verify the workspace is bound for that profile. Resource IDs from one profile must not be reused for another profile.
 - Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` for diagnosis before changing an existing app.
 - Run write commands that update `.openxiangda/state.json` sequentially within the same workspace. Read-only commands can run in parallel.
@@ -105,6 +118,8 @@ Core CLI / state:
 - `references/openxiangda-api.md` — `/openxiangda-api/v1` request and response fields.
 - `references/workspace-state.md` — `.openxiangda/state.json` shape and profile isolation rules.
 - `references/connector-resources.md` — `src/resources` manifests, connector schema, and SDK connector calls.
+- `references/notifications.md` — `src/resources/notifications`, notification templates/type bindings, and `sdk.notification` / `ctx.notification`.
+- `references/best-practices.md` — initialized examples for modular pages, state lifecycles, role governance, permission isolation, high-performance queries, portal shells, workflow boundaries, and automation patterns.
 
 Form authoring:
 
@@ -129,5 +144,6 @@ Platform domain knowledge (read these first when generating forms or pages so th
 - `references/platform-data-model.md` — how the platform persists field values (JSONB, `{label, value}` for option fields, attachment shape, etc.). Use this whenever you write, render, or diagnose form data.
 - `references/style-system.md` — three-layer style architecture, CSS namespace, and the no-hardcoded-color rule. Use this before writing any page or form CSS.
 - `references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, recommended directory layout for `src/pages` and `src/forms`. Use this before scaffolding a new page or list view.
+- `references/best-practices.md` — read this before implementing app-level business patterns; it points to `examples/best-practices/` and explains when to use status fields instead of workflow.
 - `references/component-guide.md` — when to pick platform components vs. raw Ant Design vs. custom components, with the rules for option fields. Use this before introducing a new component.
 - `references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and how to fix them. Use this when something does not behave as expected.

package/openxiangda-skills/references/architecture-patterns.md

@@ -29,9 +29,10 @@
 | 编写 REST API | 平台自动生成数据 API |
 | 维护权限中间件 | 表单字段级权限 + 部门/角色 |
 | 自建文件存储 | `AttachmentField` 直接接入平台存储 |
-| 自研流程引擎 | 表单 + workflow + js-code-nodes |
-
-AI Agent 在该平台上写代码时，**不应该考虑数据库、表结构、后端接口**——这些由表单 schema 自动派生。
+| 业务状态流转 | 表单 + `status` 字段 + 操作日志 + domain/service |
+| 真审批流程 | 表单 + workflow + js-code-nodes |
+
+AI Agent 在该平台上写代码时，**不应该考虑数据库、表结构、后端接口**——这些由表单 schema 自动派生。
 
 ---
 
@@ -144,12 +145,20 @@ export default function InstrumentListPage() {
 | 页面类型 | 实现方式 | 适用场景 |
 | --- | --- | --- |
 | 表单录入 / 编辑页 | `src/forms/xxx/` (`schema.ts` + `page.tsx`) | 新增数据、修改数据 |
-| 数据管理页 | `src/pages/xxx/` 使用 `DataManagementList` | 列表、查询、批量操作、导出 |
-| 流程表单页 | `src/forms/xxx/` 关联 workflow | 审批流程发起、节点处理 |
-| 自定义业务页 | `src/pages/xxx/` 自由编码 | 仪表盘、看板、复杂交互、对外门户 |
-| 详情页 | `src/pages/xxx/[id].tsx` 使用 `FormSummaryCard` 等 | 查看单条数据、关联记录 |
-
-> AI Agent 在创建新页面前，先按上表判断「应该走表单还是代码页」，避免把列表场景误塞进表单页。
+| 数据管理页 | `src/pages/xxx/` 使用 `DataManagementList` | 列表、查询、批量操作、导出 |
+| 状态流转页 | 普通表单 + 状态字段 + 操作日志 + 代码页 service | 工单、订单、任务等业务状态变化 |
+| 流程表单页 | `src/forms/xxx/` 关联 workflow | 真实审批流程发起、节点处理、审批意见 |
+| 自定义业务页 | `src/pages/xxx/` 自由编码 | 仪表盘、看板、复杂交互、对外门户 |
+| 详情页 | `src/pages/xxx/[id].tsx` 使用 `FormSummaryCard` 等 | 查看单条数据、关联记录 |
+
+> AI Agent 在创建新页面前，先按上表判断「应该走表单还是代码页」，避免把列表场景误塞进表单页。
+
+### 4.1 状态流转不是审批流
+
+- 普通业务流转默认使用普通表单：`status` 字段、责任人/归属冗余字段、操作日志表、domain 状态机、service 统一提交。
+- 每次状态变更都由 service 完成，统一写操作日志并更新责任人、归属、更新时间等冗余字段。
+- workflow 只用于真实审批：审批人、审批任务、同意/驳回、审批意见、节点权限、流程记录明确存在的场景。
+- 不要把「待处理 / 处理中 / 已完成 / 已关闭」这类状态流转建成流程表单。
 
 ---
 
@@ -175,7 +184,7 @@ export default function InstrumentListPage() {
 - **UI 库分端**：
   - PC → `antd`
   - Mobile → `antd-mobile`
-- **逻辑层共享**：`src/domain/` 与 `src/shared/services/` 在两端复用，确保业务规则一处实现。
+- **逻辑层共享**：`src/domain/` 与 `src/shared/services/` 在两端复用，确保业务规则一处实现。
 
 ### 5.2 共享 / 分离原则
 
@@ -228,15 +237,28 @@ forms ──▶ shared ──▶ domain
 ```
 
 - `domain/` 不依赖 `shared/` 或 UI。
-- `shared/` 不依赖 `pages/` 或 `forms/`。
-- 反向依赖（如 domain 导入 pages）= 立刻拒绝。
-
----
-
-## 速查 Checklist（AI Agent 自检）
-
-- [ ] 新增数据场景：是否已经定义表单 schema？
-- [ ] 列表/查询场景：是否使用 `DataManagementList` 而非平台 view？
-- [ ] 菜单绑定：是否指向代码页 `--type=page`？
-- [ ] PC/Mobile：是否分离页面、共享 domain？
-- [ ] 目录：业务逻辑是否落在 `domain/`，未污染 UI 层？
+- `shared/` 不依赖 `pages/` 或 `forms/`。
+- 反向依赖（如 domain 导入 pages）= 立刻拒绝。
+
+---
+
+## 7. 查询与交互性能
+
+- 列表必须走分页接口，传 `currentPage`、`pageSize`、排序和结构化条件。
+- 禁止一次取大 `pageSize` 再在页面内筛选。
+- 默认不要使用 `searchKeyWord`；多字段模糊查询用 `filterGroup` + `OR`，并显式指定字段。
+- 查询条件构造放在 `domain/` 或 `shared/services/`，不要散落在 TSX 事件处理里。
+- 列表刷新时保留当前数据，使用局部刷新态，避免整页闪烁。
+- 操作需要统一的确认、pending、成功反馈、失败刷新或回滚。
+
+---
+
+## 速查 Checklist（AI Agent 自检）
+
+- [ ] 新增数据场景：是否已经定义表单 schema？
+- [ ] 列表/查询场景：是否使用 `DataManagementList` 而非平台 view？
+- [ ] 查询：是否使用分页和结构化条件，而不是大 pageSize、页面内过滤或 `searchKeyWord`？
+- [ ] 流程判断：是否确认这是「真审批」，而不是普通状态流转？
+- [ ] 菜单绑定：是否指向代码页 `--type=page`？
+- [ ] PC/Mobile：是否分离页面、共享 domain？
+- [ ] 目录：业务逻辑是否落在 `domain/`，未污染 UI 层？

package/openxiangda-skills/references/automation-v3.md

@@ -123,6 +123,8 @@ The backend runs the snapshot in the trusted Node runtime, applies the node time
 
 Runtime context includes `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, and `ctx.node`. Data/process bridge methods include `ctx.methods.queryOneData`, `queryManyData`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
 
+Notification bridge methods include `ctx.notification.sendByType`, `batchSendByType`, `findConfig`, and `previewTemplate`. For custom business messages, create `src/resources/notifications/` first and use its `notificationType`; do not call legacy `/api/notification-config/*` endpoints directly.
+
 Example `src/js-code-nodes/scheduled_reconcile/index.ts`:
 
 ```ts

package/openxiangda-skills/references/best-practices.md

@@ -0,0 +1,163 @@
+# OpenXiangda Best Practices
+
+Use this reference before scaffolding a real app, a complex page, a data
+management view, a portal shell, role governance, notification automation, or a
+business lifecycle flow.
+
+The workspace template includes examples under:
+
+```text
+examples/best-practices/
+```
+
+These examples are copied by `openxiangda workspace init`, but they are not
+published by default. Copy only the selected pattern into `src/`, then adapt the
+form codes, field names, permissions, and page route names.
+
+## AI Development Flow
+
+1. Choose the architecture before writing code:
+   - normal form
+   - custom form page
+   - data management page
+   - custom data management page
+   - app-shell PC portal
+   - app-shell mobile portal
+   - pure interactive workbench
+   - business status lifecycle
+   - real approval workflow
+   - automation / JS_CODE
+   - role governance / permissions
+2. Read the matching files in `examples/best-practices/`.
+3. Copy the smallest useful slice into `src/`.
+4. Keep view code thin; put reusable business logic in `domain/` and platform
+   calls in `shared/services/`.
+5. Run `pnpm examples:check` while changing examples, and `pnpm check` after
+   copying code into the app source.
+
+## State Flow Is Not Workflow
+
+Most business processes are status lifecycles, not approval workflows.
+
+Use a normal form plus:
+
+- a `status` field
+- responsibility fields such as `ownerUserId`, `ownerDeptId`, `collegeId`,
+  `classId`
+- an action log form
+- a pure state machine in `domain/<feature>/state-machine.ts`
+- a service method that changes status and writes the log in one path
+- optional automation / JS_CODE for timed reminders or backend follow-up
+
+Use workflow only when there are real approval tasks:
+
+- approver assignment
+- agree / reject / transfer / countersign behavior
+- approval opinions
+- node-level permissions
+- process task records and audit requirements
+- notification or JS_CODE nodes tied to approval nodes
+
+Do not model ordinary "pending -> processing -> resolved -> closed" state
+changes as workflow forms.
+
+## Layering Rules
+
+Use this dependency direction:
+
+```text
+pages/forms -> shared -> domain
+```
+
+- `domain/<feature>/`: pure TypeScript business types, state machine,
+  permission predicates, and query condition builders. No React, Ant Design,
+  runtime SDK, CSS, or platform IDs.
+- `shared/services/<feature>.ts`: SDK/API access, paginated queries, status
+  updates, log writes, resource calls.
+- `shared/hooks/<feature>/`: loading, refresh, submit pending, error handling,
+  optimistic or rollback behavior.
+- `shared/components/`: reusable empty, loading, error, status tag,
+  confirmation, timeline, and list action components.
+- `pages/<feature>/components/`: page-local reusable components.
+- `pages/<feature>/styles.css`: page CSS namespace. Do not put all styling in
+  TSX.
+- `pages/<feature>/index.tsx`: entry and composition only. Avoid large business
+  logic blocks here.
+
+PC and mobile pages may have different layout/components, but must reuse the
+same `domain/` and `shared/services/` when the business behavior is the same.
+
+## Module Size Rules
+
+- Avoid single-file pages. A page file over about 250 lines should be split.
+- Move table columns, filter definitions, route configs, status configs, and
+  action visibility rules into separate files.
+- Do not let page components assemble complex API payloads directly. Call a hook
+  or service.
+- Keep shared modules independent from specific page folders.
+- Keep domain functions unit-testable without a browser or platform runtime.
+
+## Permission And Data Isolation
+
+For apps with dynamic roles:
+
+1. Create an app role maintenance form, such as `app-role`.
+2. Use automation / JS_CODE to sync role records to platform roles.
+3. Add redundant ownership fields to business forms, for example:
+   - `collegeId`
+   - `classId`
+   - `ownerDeptId`
+   - `ownerUserId`
+   - `roleCode`
+4. Create page permission groups for entry visibility.
+5. Create form permission groups with condition-based data permissions for real
+   data isolation.
+
+Frontend button hiding is only user experience. It is not permission control.
+Every sensitive action must still be protected by platform role/form permission
+groups or backend-side JS_CODE checks.
+
+## Query Performance
+
+- Always use paginated APIs with `currentPage`, `pageSize`, sort, and structured
+  conditions.
+- Do not fetch a huge page and filter in the browser.
+- Do not default to `searchKeyWord`. It is broad and expensive.
+- For multi-field fuzzy search, build `filterGroup` with `OR` across explicit
+  fields.
+- Put query construction in `domain/<feature>/ticket-query.ts` or the service
+  layer, not inside JSX.
+- Keep current table/list data visible during refresh and show local refresh
+  state to avoid flicker.
+
+## Interaction Rules
+
+- Every list/detail page needs loading, empty, error, refresh, and submit-pending
+  states.
+- Destructive or state-changing actions need confirmation.
+- Show processing feedback and success/failure feedback.
+- On failure, refresh or rollback the affected row instead of leaving stale UI.
+- Keep interaction styles consistent across PC and mobile, but do not force the
+  same layout component onto both viewports.
+
+## Template Catalog
+
+- `customer-profile`: standard form schema with validation, members,
+  departments, attachments, and child table.
+- `service-ticket-lifecycle`: status lifecycle with ticket form, action-log
+  form, state machine, service layer, and operation log.
+- `service-ticket-ops`: custom data management page based on
+  `DataManagementList`, split into page, components, hook, query builder, and
+  detail drawer.
+- `role-governance`: role maintenance form, role sync JS_CODE, redundant
+  ownership fields, and permission-group resource examples.
+- `pc-portal-shell`: app-shell PC portal with routes, modules, components, and
+  services.
+- `mobile-portal-shell`: app-shell mobile portal with mobile-only components
+  reusing the same domain/service layer.
+- `interactive-workbench`: pure interactive page with reducer, modular panels,
+  preview, loading/error, and batch operations.
+- `expense-approval-workflow`: real approval workflow example; use only for
+  approval scenarios.
+- `daily-ticket-digest`: automation / JS_CODE example for paginated overdue
+  query, notification, and log writing.

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

@@ -5,6 +5,7 @@ OpenXiangda engineering resources live under `src/resources/`.
 Common folders:
 
 - `connectors`
+- `notifications`
 - `roles`
 - `menus`
 - `workflows`
@@ -24,6 +25,8 @@ 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.
+
 ```json
 {
   "code": "crm",

package/openxiangda-skills/references/notifications.md

@@ -0,0 +1,80 @@
+# Notification Resources
+
+Use notification resources when a page, workflow, or automation needs reusable message templates.
+
+AI generation rule: declare notification resources first, then call `sdk.notification` in code pages or `ctx.notification` in JS_CODE. Do not hardcode `/api/notification-config/*` or store channel credentials in source.
+
+## Resource Files
+
+Place JSON under `src/resources/notifications/`.
+
+```json
+{
+  "templates": [
+    {
+      "code": "reservation_reminder",
+      "name": "预约提醒",
+      "content": "{{title}}",
+      "variables": ["title", "instrumentName", "startTime"],
+      "channelsConfig": {
+        "inapp": {
+          "enabled": true,
+          "content": "{{instrumentName}} 将于 {{startTime}} 开始"
+        },
+        "dingding": {
+          "enabled": true,
+          "content": "{{title}}"
+        }
+      }
+    }
+  ],
+  "typeConfigs": [
+    {
+      "notificationType": "reservation_reminder",
+      "templateCode": "reservation_reminder",
+      "enabled": true,
+      "priority": 0
+    }
+  ]
+}
+```
+
+For form-level notifications, add `level: "form"` and `formCode` to both the template and type config. Prefer `formCode`; the CLI resolves `formUuid` per profile.
+
+Allowed channels: `inapp`, `email`, `dingding`, `wechat`, `thirdparty_todo`.
+
+Do not include `token`, `secret`, `password`, `authorization`, `auth`, `credential`, or `headers` fields. Platform admins configure channel credentials outside resources.
+
+## Runtime Calls
+
+Code pages:
+
+```ts
+await sdk.notification.sendByType({
+  notificationType: "reservation_reminder",
+  recipientId: userId,
+  payload: {
+    title: "预约提醒",
+    instrumentName,
+    startTime,
+  },
+});
+```
+
+Automation or workflow JS_CODE:
+
+```ts
+export default async function notify(ctx) {
+  await ctx.notification.sendByType({
+    notificationType: "reservation_reminder",
+    recipientId: ctx.operator.userId,
+    payload: {
+      title: "预约提醒",
+      instrumentName: ctx.formData.current.instrument_name,
+      startTime: ctx.formData.current.start_time,
+    },
+  });
+}
+```
+
+Use `work_notification` for simple declarative notifications. Use JS_CODE only for dynamic recipients, conditional sending, or payload assembly.

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

@@ -205,6 +205,51 @@ Requires Bearer token. Deletes a menu item.
 
 Requires Bearer token. Updates menu sorting and parent relationships in batch.
 
+## Notifications
+
+### POST `/apps/:appType/notifications/send-by-type`
+
+Requires Bearer token. Sends a notification in the current app scope.
+
+```json
+{
+  "notificationType": "reservation_reminder",
+  "recipientId": "user-id",
+  "payload": {
+    "title": "预约提醒"
+  },
+  "channels": ["inapp"]
+}
+```
+
+### POST `/apps/:appType/notifications/batch-send-by-type`
+
+Requires Bearer token. Sends one notification type to multiple recipients.
+
+### GET `/apps/:appType/notifications/templates`
+
+Requires Bearer token. Lists app/form notification templates.
+
+### PUT `/apps/:appType/notifications/templates/:code`
+
+Requires app admin permission. Upserts an app/form notification template by code.
+
+### POST `/apps/:appType/notifications/templates/preview`
+
+Requires Bearer token. Body uses `templateCode` or `templateId` plus `payload`.
+
+### GET `/apps/:appType/notifications/type-configs`
+
+Requires Bearer token. Lists notification type bindings.
+
+### GET `/apps/:appType/notifications/type-configs/:notificationType`
+
+Requires Bearer token. Resolves the active binding by notification type and optional `formUuid`.
+
+### PUT `/apps/:appType/notifications/type-configs/:notificationType`
+
+Requires app admin permission. Upserts a binding with `templateCode` or `templateId`.
+
 ### GET `/apps/:appType/workflows`
 
 Requires Bearer token. Lists workflow definitions in the app. Supports `formUuid`, `isPublished`, `page`, and `pageSize` query parameters.

package/openxiangda-skills/references/pages/page-sdk.md

@@ -7,6 +7,7 @@ Guidelines:
 - Do not hardcode `/openxiangda-api` calls inside end-user page components unless the page is explicitly an admin tool.
 - Prefer SDK modules for form data, user context, permissions, and platform navigation.
 - Use `sdk.connector.invoke`, `sdk.connector.call("connector.api")`, or `sdk.connector.download` for external services. The SDK calls the platform runtime connector endpoint; it must not call third-party domains directly.
+- Use `sdk.notification.sendByType` and `batchSendByType` for reusable business messages. Custom notification types must be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
 - For the current user's department hierarchy, use `sdk.department.getCurrentUserParentDepartments()`; do not hardcode `GET /department/:id/parentDepartments` in page code.
 - Keep API calls behind small local functions so generated UI stays testable.
 - Treat user context and tenant context as runtime-provided values.

package/openxiangda-skills/references/pages/workspace-structure.md

@@ -5,16 +5,18 @@ Form pages, workflow form pages, and custom code pages live in `sy-lowcode-app-w
 Create a new workspace with:
 
 ```bash
-openxiangda workspace init ./my-app-workspace
+openxiangda workspace init ./my-app-workspace --profile <name> --app-name "应用名称"
 cd ./my-app-workspace
 pnpm install
-openxiangda workspace bind --profile <name> --app-type APP_XXXX
 ```
 
-You can bind during initialization when the target app is already known:
+Local workspace state is authoritative. If the current folder has no app binding, create a new app; do not search the platform for similar app names.
+
+Bind an existing app only when the user explicitly provides `appType` or asks to reuse that app:
 
 ```bash
 openxiangda workspace init ./my-app-workspace --profile <name> --app-type APP_XXXX
+openxiangda workspace bind --profile <name> --app-type APP_XXXX
 ```
 
 Typical code page layout:

package/openxiangda-skills/references/workspace-state.md

@@ -31,6 +31,10 @@ Tokens never belong in the project. User tokens live in `~/.openxiangda/profiles
         "menus": {},
         "roles": {},
         "connectors": {},
+        "notifications": {
+          "templates": {},
+          "typeConfigs": {}
+        },
         "pagePermissionGroups": {},
         "formPermissionGroups": {},
         "formSettings": {}
@@ -44,6 +48,8 @@ Tokens never belong in the project. User tokens live in `~/.openxiangda/profiles
 
 - Profile is the deployment boundary.
 - `baseUrl` is the backend API base. On standard private deployments it is `<origin>/service`; management pages use `/platform`, and app runtime pages use `/view`.
+- Local state is authoritative for app binding. If a workspace has no `appType` for the target profile, create a new app/workspace with `openxiangda workspace init <dir> --profile <name> --app-name "应用名称"`.
+- Do not search platform apps or reuse similar names unless the user explicitly asks to reuse an existing app or provides an `appType`.
 - Local resource keys are logical codes.
 - Live IDs and lightweight runtime aliases are nested under the profile that produced them.
 - Do not store business configuration or secrets in `.openxiangda/state.json`; store those in `src/resources/`.

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

@@ -19,16 +19,16 @@ openxiangda auth status --profile <name>
 If the workspace is not bound:
 
 ```bash
-openxiangda app list --profile <name>
-openxiangda workspace bind --profile <name> --app-type APP_XXX
+openxiangda workspace init ./my-app-workspace --profile <name> --app-name "应用名称"
+cd ./my-app-workspace
+pnpm install
 ```
 
-If there is no local app workspace yet:
+Bind to an existing app only when the user explicitly provides `appType` or asks to reuse an existing platform app:
 
 ```bash
 openxiangda workspace init ./my-app-workspace --profile <name> --app-type APP_XXX
-cd ./my-app-workspace
-pnpm install
+openxiangda workspace bind --profile <name> --app-type APP_XXX
 ```
 
 For menu work:
@@ -39,7 +39,7 @@ openxiangda menu create main --name "主菜单" --type nav --profile <name>
 openxiangda menu create customer-entry --name "客户信息" --type receipt --form-code customer --profile <name>
 ```
 
-If the app does not exist:
+If the user explicitly asks to create an app without initializing a workspace:
 
 ```bash
 openxiangda app create "应用名称" --profile <name>
@@ -50,9 +50,11 @@ openxiangda workspace bind --profile <name> --app-type APP_XXX
 
 - Never ask for AK/SK.
 - Always pass `--profile` for publish or cross-platform operations.
-- Use `openxiangda workspace init <dir>` before page/form work when the user starts from a new empty directory.
+- Local `.openxiangda/state.json` is authoritative. If the user starts from a new empty directory or the workspace has no app binding, create a new app with `openxiangda workspace init <dir> --profile <name> --app-name "应用名称"`.
+- Do not search platform apps or reuse similar app names unless the user explicitly asks to reuse an existing app or gives an `appType`.
 - Store platform-specific IDs only in `.openxiangda/state.json`.
 - Use logical local codes for forms, pages, workflows, automations, and menus.
+- Before scaffolding a new business app, read `../../references/best-practices.md` and pick an architecture from the initialized `examples/best-practices/` catalog. Do not generate a large single-file app page when a template pattern already covers the scenario.
 - Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` before changing an existing app.
 
 ## Resource State
@@ -62,3 +64,5 @@ Read `../../references/workspace-state.md` when changing `.openxiangda/state.jso
 Read `../../references/openxiangda-api.md` when exact endpoint fields are needed.
 
 Read `../../references/architecture-patterns.md` to understand the overall app structure (how forms, pages, menus, workflows, and permissions compose into an app, and the recommended `src/forms` / `src/pages` layout) before scaffolding or restructuring an app workspace.
+
+Read `../../references/best-practices.md` before implementing app-level patterns such as status lifecycles, role governance, PC/mobile portals, high-performance data management pages, workflow boundaries, and automation.