openxiangda 1.0.22 → 1.0.25

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/best-practices.md

@@ -0,0 +1,180 @@
+# 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.
+
+## Library Selection
+
+- Do not hand-write mature controls or engines. Use platform components for
+  personnel, departments, files, images, rich text, locations, and data lists.
+- Use `antd` / `antd-mobile` for standard controls, overlays, tables, steps,
+  tabs, forms, and feedback. Avoid raw native inputs unless the behavior is
+  truly trivial and already styled by a wrapper.
+- Use ECharts for charts and dashboards.
+- Use GSAP for complex timeline/scroll/sequence animations; simple transitions
+  can stay in CSS. If an animation-specific skill is available, read it before
+  implementing.
+- For drag/drop, virtual lists, calendars, spreadsheet-like input, QR/barcode,
+  or export/import, research maintained packages and official docs before
+  writing code.
+- New dependencies should have a clear reason and a small adapter layer in the
+  app, not copied third-party internals.
+
+## 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/component-guide.md

@@ -4,14 +4,40 @@
 
 ---
 
-## 1. 核心原则
-
-1. **平台组件优先**：所有平台组件已经接入了组织架构、文件存储、权限、多端适配等平台能力，重写一遍 = 丢能力 + 后续无法维护。
-2. **基于 antd / antd-mobile 包装**：自定义组件必须站在 antd 之上，保证 PC 和移动端的基础体验一致。
-3. **样式走变量与语义类**：使用 CSS 变量、Tailwind 语义类，**禁止**在 JSX 中硬编码颜色、间距、字号、圆角。
-4. **不覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变。
-
----
+## 1. 核心原则
+
+1. **平台组件优先**：所有平台组件已经接入了组织架构、文件存储、权限、多端适配等平台能力，重写一遍 = 丢能力 + 后续无法维护。
+2. **基于 antd / antd-mobile 包装**：自定义组件必须站在 antd 之上，保证 PC 和移动端的基础体验一致。
+3. **成熟能力先调研开源方案**：图表、动画、拖拽、虚拟列表、富文本、日历、导入导出、复杂表格等，不要直接手写。先查当前项目依赖、官方文档和维护状态，再决定使用库或轻量封装。
+4. **样式走变量与语义类**：使用 CSS 变量、Tailwind 语义类，**禁止**在 JSX 中硬编码颜色、间距、字号、圆角。
+5. **不覆盖组件内部 class**：组件库内部类名（`ant-select-selector` 等）是私有 API，下个版本就可能变。
+
+---
+
+## 1.1 开源库选型规则
+
+AI 在实现成熟交互前必须先判断是否已有可靠组件或库：
+
+| 场景 | 优先方案 | 说明 |
+| --- | --- | --- |
+| PC 表单控件、筛选、弹窗、表格、步骤条 | `antd` | 不要用原生 `<input>` / `<select>` 复刻。用 `Input`、`Input.Search`、`Select`、`DatePicker`、`Table`、`Modal`、`Drawer`、`Form` 等。 |
+| 移动端操作、列表、弹层、Tab | `antd-mobile` | 移动端不要强行套 PC 组件。 |
+| 平台数据录入能力 | `openxiangda` 平台字段组件 | 人员、部门、附件、图片、富文本、位置、数据管理列表优先平台组件。 |
+| 图表、仪表盘、经营看板 | `echarts` + `echarts-for-react` | 不要手写 canvas/SVG 图表，除非只是非常小的装饰图形。 |
+| 复杂时间轴动画、编排动画、滚动动画 | `gsap` | 需要动画库时先查 GSAP 官方文档；如果当前 Agent 有动画/GSAP skill，先读取该 skill。简单 hover/transition 用 CSS 即可。 |
+| 拖拽排序、看板、可拖卡片 | `@dnd-kit/*` | 不要自己处理 pointer/mouse/touch 全套事件。 |
+| 大列表虚拟滚动 | antd Table virtual / `rc-virtual-list` | 不要一次渲染几千行 DOM。 |
+| 日期时间处理 | `dayjs` + antd 日期组件 | 不要手写日期解析、时区格式化。 |
+| 富文本 | 平台 `EditorField` 或成熟编辑器封装 | 不要用 contenteditable 从零做编辑器。 |
+
+选型流程：
+
+1. 先看模板 `package.json` 已有依赖，已有依赖优先复用。
+2. 没有依赖但功能成熟复杂时，调研官方文档、维护状态、包体积和授权，再通过包管理器加入。
+3. 页面代码只写业务适配层，不复制第三方库内部逻辑。
+4. 新增依赖后，在提交说明或实现注释中保留一句选择原因。
+
+---
 
 ## 2. 必须使用平台组件（重做即丢能力）
 

package/openxiangda-skills/references/pages/publish-flow.md

@@ -6,6 +6,32 @@ Preferred publish command:
 openxiangda workspace publish --profile <name>
 ```
 
+For day-to-day AI edits, prefer a targeted publish:
+
+```bash
+# Preview what git-touched forms/pages would publish.
+openxiangda workspace publish --profile <name> --changed --dry-run
+
+# Publish only git-touched src/forms/* and src/pages/* modules.
+openxiangda workspace publish --profile <name> --changed
+
+# Publish one code page or one form when the changed module is known.
+openxiangda workspace publish --profile <name> --page dashboard
+openxiangda workspace publish --profile <name> --form customer
+
+# Publish several explicit modules.
+openxiangda workspace publish --profile <name> --only pages/dashboard,forms/customer
+```
+
+Do not use full workspace publish as a reflex. Full publish is only appropriate
+when many modules were intentionally changed, shared/config changes affect many
+pages, or the incremental cache needs a repair pass. For a single page edit,
+publish that page.
+
+Targeted publish skips `src/resources` by default. Add `--resources` if resource
+manifests changed too, or run `openxiangda resource plan|publish` separately.
+Use `--skip-resources` when you explicitly want forms/pages only.
+
 The CLI injects:
 
 - `OPENXIANGDA_PROFILE`

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,12 @@ 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.
+- When publishing after app edits, prefer targeted commands (`workspace publish --changed --dry-run`, then `--changed`, `--page`, `--form`, or `--only`). Do not publish all forms/pages just because one page changed.
 - Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` before changing an existing app.
 
 ## Resource State
@@ -62,3 +65,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.

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": {}
@@ -125,6 +142,18 @@ openxiangda workspace publish --profile prod
 
 The CLI checks that the target profile is logged in and bound to an app. It then runs the workspace publish script with these environment variables:
 
+For normal development, inspect and publish only changed or targeted modules:
+
+```bash
+openxiangda workspace publish --profile dev --changed --dry-run
+openxiangda workspace publish --profile dev --changed
+openxiangda workspace publish --profile dev --page dashboard
+openxiangda workspace publish --profile dev --form customer
+openxiangda workspace publish --profile dev --only pages/dashboard,forms/customer
+```
+
+Do not run a full publish automatically after a single page or form edit. Full publish is for intentional broad changes, shared/config changes that affect many modules, or cache repair. Targeted publish skips resources by default; pass `--resources` or run `openxiangda resource publish` when resource manifests changed.
+
 - `OPENXIANGDA_PROFILE`
 - `OPENXIANGDA_BASE_URL`
 - `OPENXIANGDA_ACCESS_TOKEN`
@@ -145,3 +174,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
@@ -37,6 +39,12 @@ Then publish:
 openxiangda workspace publish --profile <name>
 ```
 
+For a single form edit, publish that form only:
+
+```bash
+openxiangda workspace publish --profile <name> --form <formCode>
+```
+
 The workspace publish script receives `OPENXIANGDA_BASE_URL`, `OPENXIANGDA_ACCESS_TOKEN`, and `OPENXIANGDA_APP_TYPE` from the CLI. It creates/binds the platform form shell only when needed, syncs form metadata, builds the React form page bundle, uploads assets, and registers the bundle.
 
 ## Low-level Commands
@@ -61,10 +69,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.
@@ -72,5 +83,6 @@ Read these references only when writing or reviewing schema:
 - Put validation on field-level `rules`; never generate old top-level validation arrays under `schema.rules`. Top-level `rules` is only for `FormEffect[]` with `when` and `then`.
 - Always provide `options` for option components. `SelectField`, `MultiSelectField`, `RadioField`, `CheckboxField`, and `CascadeSelectField` must not be emitted with `options` undefined. See `../../references/component-guide.md` for the full list and `../../references/platform-data-model.md` for the `{label, value}` storage contract.
 - Workflow form pages use the same workspace form structure plus workflow v3 configuration; publish the form page bundle through workspace publish before treating it as complete.
+- After editing one form, use `workspace publish --form <formCode>` or preview `--changed --dry-run`; do not run full workspace publish by default.
 - Use `openxiangda form pull` or app snapshot before overwriting an existing form.
 - Before assuming a value shape (e.g. dates, attachments, member fields, option fields), verify against `../../references/platform-data-model.md` instead of guessing.

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

@@ -16,14 +16,29 @@ cd /path/to/sy-lowcode-app-workspace
 openxiangda workspace publish --profile <name>
 ```
 
+For a page-only edit, prefer targeted publish:
+
+```bash
+openxiangda workspace publish --profile <name> --page <pageCode>
+```
+
+If multiple files changed and the target is not obvious, preview first:
+
+```bash
+openxiangda workspace publish --profile <name> --changed --dry-run
+openxiangda workspace publish --profile <name> --changed
+```
+
 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,6 +56,7 @@ 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`
@@ -53,17 +69,22 @@ 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.
+- Before hand-writing mature UI behavior, consult `../../references/component-guide.md` and use established libraries: platform components for platform data fields, antd/antd-mobile for controls and overlays, ECharts for charts, GSAP for complex animation timelines, and maintained packages such as dnd-kit for drag/drop. Do not rebuild mature controls with raw DOM/native inputs.
 - 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.
+- After editing one code page, publish with `--page <pageCode>` instead of triggering all forms/pages. Use `--changed --dry-run` before `--changed` when git touched several modules.
 - Do not create custom code pages by writing platform schema directly. The source is React workspace code plus `page.config.ts`.
 - 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`: 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.