openxiangda 1.0.22 → 1.0.24

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/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.

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,6 +43,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,6 +56,8 @@ 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.
@@ -64,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:
@@ -101,6 +107,7 @@ 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`

package/package.json

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

package/templates/sy-lowcode-app-workspace/examples/best-practices/README.md

@@ -0,0 +1,32 @@
+# OpenXiangda Best Practices
+
+These examples are intentionally placed under `examples/best-practices/`.
+They are copied by `workspace init`, but they are not scanned by
+`lowcode-workspace build` or `openxiangda workspace publish`.
+
+Copy the pieces you need into `src/`:
+
+```bash
+cp -R examples/best-practices/src/domain/service-ticket src/domain/
+cp -R examples/best-practices/src/shared/services/service-ticket.ts src/shared/services/
+cp -R examples/best-practices/src/pages/service-ticket-ops src/pages/
+cp -R examples/best-practices/src/forms/service-ticket src/forms/
+```
+
+Run `pnpm examples:check` after editing examples, and run the normal
+`pnpm check` after copying code into `src/`.
+
+## Core Rules
+
+- Keep view code thin. Pages compose components, hooks, and services.
+- Put business rules in `domain/`; keep it free of React, SDK, and UI imports.
+- Put platform calls in `shared/services/`.
+- Put reusable loading, empty, error, status, and confirmation UI in
+  `shared/components/`.
+- Use state fields and operation logs for business lifecycle flows.
+- Use workflow only for real approval tasks.
+- Query with pagination and structured conditions. Avoid large page sizes,
+  client-side filtering, and broad `searchKeyWord` queries.
+
+Read `decision-guide.md`, `module-structure.md`, and `design-style.md` before
+using any template.

package/templates/sy-lowcode-app-workspace/examples/best-practices/catalog.json

@@ -0,0 +1,61 @@
+{
+  "version": 1,
+  "publishedByDefault": false,
+  "copyInto": "src/",
+  "templates": [
+    {
+      "code": "customer-profile",
+      "type": "form",
+      "path": "src/forms/customer-profile",
+      "description": "Standard form schema covering field types, validation, users, departments, attachments, and subforms."
+    },
+    {
+      "code": "service-ticket-lifecycle",
+      "type": "state-flow",
+      "path": "src/domain/service-ticket",
+      "description": "Lifecycle state machine with ticket and action-log forms. Does not use workflow."
+    },
+    {
+      "code": "service-ticket-ops",
+      "type": "page",
+      "path": "src/pages/service-ticket-ops",
+      "description": "DataManagementList-based ops page with modular actions, drawer, timeline, hook, and service."
+    },
+    {
+      "code": "role-governance",
+      "type": "permissions",
+      "path": "src/domain/role-governance",
+      "description": "Dynamic role maintenance, role sync, redundant ownership fields, and permission-group resource examples."
+    },
+    {
+      "code": "pc-portal-shell",
+      "type": "app-shell-page",
+      "path": "src/pages/pc-portal-shell",
+      "description": "PC app-shell entry with routes, modules, shared domain usage, and no hardcoded view URLs."
+    },
+    {
+      "code": "mobile-portal-shell",
+      "type": "app-shell-page",
+      "path": "src/pages/mobile-portal-shell",
+      "description": "Mobile app-shell entry sharing domain/service logic with the PC portal."
+    },
+    {
+      "code": "interactive-workbench",
+      "type": "page",
+      "path": "src/pages/interactive-workbench",
+      "description": "Pure interaction workbench with reducer state, modular panels, and unified query states."
+    },
+    {
+      "code": "expense-approval-workflow",
+      "type": "workflow",
+      "path": "src/resources/workflows/expense-approval-workflow.json",
+      "description": "True approval workflow example. Use only when approval tasks are required."
+    },
+    {
+      "code": "daily-ticket-digest",
+      "type": "automation",
+      "path": "src/resources/automations/daily-ticket-digest",
+      "description": "Scheduled JS_CODE automation that queries paginated data and sends notification resources."
+    }
+  ]
+}

package/templates/sy-lowcode-app-workspace/examples/best-practices/decision-guide.md

@@ -0,0 +1,44 @@
+# Decision Guide
+
+## Page And Data Shape
+
+Use a form when you need a data table. Each form schema defines fields,
+validation, storage shape, and generated platform data APIs.
+
+Use a code page when you need a workbench, portal, dashboard, cross-form
+composition, custom list actions, or complex interaction.
+
+Use `DataManagementList` for list/search/export/batch-management pages. Extend
+it with row actions, custom renderers, and drawers instead of rebuilding
+pagination, export, and filters from scratch.
+
+## State Flow Is Not Workflow
+
+Most business "processes" are lifecycle state changes:
+
+- work tickets: new -> accepted -> processing -> resolved -> closed
+- orders: draft -> submitted -> paid -> fulfilled -> completed
+- assets: available -> reserved -> in_use -> maintenance -> retired
+
+Use a normal form with a `status` field, ownership fields, and an operation-log
+form. Define allowed transitions in `domain/<feature>/state-machine.ts`, and
+execute changes through a service method that updates state and writes logs.
+
+Use workflow only when the platform must create approval tasks with approvers,
+approval comments, agree/reject actions, copy nodes, node field permissions, and
+approval history.
+
+## Automation And JS_CODE
+
+Use automation or workflow JS_CODE when logic must run on the backend after a
+trigger: scheduled scans, cross-form synchronization, notification fan-out,
+external HTTP calls, or platform role synchronization.
+
+Frontend code must not be responsible for data isolation or background jobs.
+
+## Permissions
+
+For dynamic multi-role apps, create a business role table and synchronize it to
+platform app roles. Add redundant ownership fields to business forms, such as
+`collegeId`, `classId`, `ownerDeptId`, and `ownerUserId`. Use form permission
+groups with condition-style data permissions to enforce data isolation.

package/templates/sy-lowcode-app-workspace/examples/best-practices/design-style.md

@@ -0,0 +1,30 @@
+# Design Style
+
+OpenXiangda business apps should feel like focused operational tools.
+
+## Interaction Defaults
+
+- Every async page has loading, refreshing, empty, error, and submit-pending
+  states.
+- List refresh should keep existing rows visible and show a small refresh state.
+- Mutating actions need confirmation, pending feedback, success feedback, and a
+  failure refresh or rollback path.
+- Mobile actions should use a bottom action area, drawer, or action sheet; do
+  not copy a dense PC table toolbar to mobile.
+
+## Layout Defaults
+
+- Use dense but readable workbench layouts for admin and ops pages.
+- Put high-value filters near the list, not in hidden configuration pages.
+- Use status tags, responsibility fields, and latest action summaries for
+  lifecycle data.
+- Do not build marketing-style hero pages for business tools.
+
+## Styling Rules
+
+- Use platform CSS variables, Tailwind semantic classes, Ant Design, and
+  antd-mobile.
+- Keep page styles in `styles.css`; avoid large inline style objects.
+- Keep reusable visual states in shared components: status tags, query states,
+  confirmation triggers, and operation timelines.
+- Do not override private Ant Design class names.

package/templates/sy-lowcode-app-workspace/examples/best-practices/module-structure.md

@@ -0,0 +1,48 @@
+# Module Structure
+
+Use this structure for substantial features:
+
+```text
+src/
+  domain/<feature>/
+    types.ts
+    state-machine.ts
+    permissions.ts
+    query.ts
+    index.ts
+  shared/
+    services/<feature>.ts
+    hooks/use<Feature>.ts
+    components/
+      QueryState.tsx
+      StatusTag.tsx
+  pages/<feature>/
+    page.config.ts
+    index.tsx
+    App.tsx
+    styles.css
+    components/
+  forms/<feature>/
+    schema.ts
+    page.tsx
+```
+
+## Dependency Direction
+
+```text
+pages -> shared/hooks -> shared/services -> domain
+forms -> shared -> domain
+```
+
+- `domain/` has no React, Ant Design, SDK, or page imports.
+- `shared/` does not import from `pages/`.
+- `pages/` compose modules and call hooks; they do not build complex query
+  payloads inline.
+- PC and mobile views can have different components and styles, but they reuse
+  the same domain and service logic.
+
+## File Size
+
+Avoid large single-file pages. If a page grows beyond roughly 250 lines, split
+table actions, drawers, timelines, query builders, hooks, and styles into
+separate files.

package/templates/sy-lowcode-app-workspace/examples/best-practices/src/domain/role-governance/index.ts

@@ -0,0 +1,2 @@
+export * from "./permissions";
+export * from "./types";