openxiangda 1.0.264 → 2.0.0-alpha.2

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

@@ -1,349 +0,0 @@
-# Automation V3 Reference
-
-Automations have two files:
-
-- `trigger.json`: when the automation runs.
-- `automation.json`: what the automation does.
-
-## Trigger Config
-
-Automation can run from form events, workflow events, fixed cron schedules, or a form date field reaching a configured time. Pair these triggers with JS_CODE when the action must execute on the backend and cannot be handled reliably by a frontend page.
-
-AI-authored automations must use `trigger_v2`. The CLI passes this JSON through unchanged and only fills the root `appType` and `formUuid` when they are missing and can be resolved from the active workspace/profile.
-
-Form submit trigger:
-
-```json
-{
-  "version": "trigger_v2",
-  "mode": "event",
-  "appType": "APP_XXX",
-  "formUuid": "FORM_XXX",
-  "enabled": true,
-  "event": {
-    "source": "form_data",
-    "action": "submitted"
-  },
-  "filters": {
-    "conditions": []
-  }
-}
-```
-
-Form update/delete triggers use the same shape with `event.action` set to `updated` or `deleted`. Update events expose `ctx.formData.current`, `ctx.formData.previous`, `ctx.formData.changes`, and `ctx.triggerEvent.data.metadata.changeRecords`.
-
-Form field change trigger:
-
-```json
-{
-  "version": "trigger_v2",
-  "mode": "event",
-  "appType": "APP_XXX",
-  "formUuid": "FORM_XXX",
-  "enabled": true,
-  "event": {
-    "source": "form_field",
-    "action": "changed"
-  },
-  "filters": {
-    "fieldChange": {
-      "fieldId": "status",
-      "changeType": "to_value",
-      "toValue": "approved"
-    }
-  }
-}
-```
-
-`fieldChange.changeType` can be `any`, `from_to`, `to_value`, or `from_value`.
-
-Workflow task trigger:
-
-```json
-{
-  "version": "trigger_v2",
-  "mode": "event",
-  "appType": "APP_XXX",
-  "formUuid": "FORM_XXX",
-  "enabled": true,
-  "event": {
-    "source": "workflow_task",
-    "action": "approved"
-  },
-  "filters": {
-    "workflow": {
-      "processDefinitionId": "workflow-id",
-      "nodeId": "approval-node-id",
-      "operatorId": "",
-      "assigneeId": "",
-      "previousAssigneeId": ""
-    }
-  }
-}
-```
-
-Workflow task actions are `approved`, `rejected`, `returned`, `transferred`, and `cancelled`. Returned task events include `ctx.workflowData.targetNodeId` and `ctx.workflowData.targetNodeName` when the platform can resolve the target node.
-
-Workflow process trigger:
-
-```json
-{
-  "version": "trigger_v2",
-  "mode": "event",
-  "appType": "APP_XXX",
-  "formUuid": "FORM_XXX",
-  "enabled": true,
-  "event": {
-    "source": "workflow_process",
-    "action": "rejected"
-  },
-  "filters": {
-    "workflow": {
-      "processDefinitionId": "workflow-id",
-      "finalResult": "rejected"
-    }
-  }
-}
-```
-
-Workflow process actions are `started`, `approved`, `rejected`, `terminated`, and `withdrawn`. Final approval is backed by `workflow_process_completed`; final rejection is backed by `workflow_process_terminated` with `finalResult: "rejected"`; manual termination uses `finalResult: "terminated"`.
-
-Fixed-time scheduled trigger:
-
-```json
-{
-  "version": "trigger_v2",
-  "mode": "scheduled",
-  "appType": "APP_XXX",
-  "enabled": true,
-  "schedule": {
-    "type": "fixed_time",
-    "fixedTime": {
-      "startTime": "2026-05-21T09:00:00+08:00",
-      "cronExpression": "0 0 9 * * *",
-      "maxExecutions": 1
-    }
-  }
-}
-```
-
-Form date-field scheduled trigger:
-
-```json
-{
-  "version": "trigger_v2",
-  "mode": "scheduled",
-  "appType": "APP_XXX",
-  "formUuid": "FORM_XXX",
-  "enabled": true,
-  "schedule": {
-    "type": "form_date_field",
-    "formDateField": {
-      "fieldId": "dueAt",
-      "startOffset": {
-        "type": "before",
-        "days": 1,
-        "time": "09:00:00"
-      },
-      "endFieldId": "",
-      "cronExpression": "0 0 9 * * *",
-      "maxExecutions": 1
-    }
-  }
-}
-```
-
-Use CLI flags such as `--form-code customer` so the CLI can fill `formUuid` from the current profile. Do not hardcode IDs from another profile.
-
-## Definition JSON
-
-AI-authored automations should prefer code-first definitions when the logic is mainly backend orchestration and does not need a visual editable canvas.
-
-Code automation definition:
-
-```json
-{
-  "kind": "automation_code_ts",
-  "version": "code_v1",
-  "runtimeMode": "trusted_node",
-  "sourceType": "file_snapshot",
-  "scriptCode": "daily_ticket_digest",
-  "sourceFile": {
-    "localPath": "src/automations/daily_ticket_digest/index.ts"
-  },
-  "timeoutMs": 30000
-}
-```
-
-Author source in `src/automations/<resourceCode>/index.ts`. During validate/create/publish, the CLI runs `pnpm build-js-code --script <resourceCode> --source automations`, uploads `dist/automations/<resourceCode>/index.cjs`, and replaces `sourceFile.localPath` with immutable snapshot metadata.
-
-Pair it with a structured preview file:
-
-```json
-{
-  "kind": "automation_code_preview",
-  "version": "preview_v1",
-  "steps": [
-    { "id": "load", "type": "data_read", "label": "查询待处理数据" },
-    { "id": "notify", "type": "notification", "label": "发送提醒" }
-  ],
-  "edges": [{ "source": "load", "target": "notify" }]
-}
-```
-
-Resource manifest shape:
-
-```json
-{
-  "code": "daily_ticket_digest",
-  "name": "每日工单摘要",
-  "triggerConfig": {
-    "version": "trigger_v2",
-    "mode": "scheduled",
-    "enabled": true,
-    "schedule": {
-      "type": "fixed_time",
-      "fixedTime": {
-        "startTime": "2026-05-21T09:00:00+08:00",
-        "cronExpression": "0 0 9 * * *"
-      }
-    }
-  },
-  "definitionFile": "definition.code.json",
-  "previewFile": "preview.json",
-  "publish": true,
-  "enable": true
-}
-```
-
-Minimum shape:
-
-```json
-{
-  "version": "v3",
-  "nodes": [
-    { "id": "start", "type": "start", "data": { "label": "开始" } },
-    { "id": "notify", "type": "work_notification", "data": { "label": "通知" } },
-    { "id": "end", "type": "end", "data": { "label": "结束" } }
-  ],
-  "edges": [
-    { "id": "e1", "source": "start", "target": "notify" },
-    { "id": "e2", "source": "notify", "target": "end" }
-  ]
-}
-```
-
-Supported node types:
-
-- `start`
-- `end`
-- `condition`
-- `condition_branch`
-- `branch`
-- `js_code`
-- `data_retrieve_single`
-- `data_retrieve_batch`
-- `data_create`
-- `data_update`
-- `connector_call`
-- `callback_wait`
-- `work_notification`
-- `dingtalk_card`
-
-## JS_CODE V2
-
-Use trusted Node JS_CODE nodes for AI/admin automation logic that runs after an automation trigger. Typical cases include scheduled data cleanup, date-field reminders, cross-form synchronization after submit/update/delete, workflow-completed follow-up writes, calling internal platform APIs, calling external HTTP services, and other backend-only orchestration.
-
-For reusable backend logic that should be shared by pages, multiple automations, and workflows, prefer an App Function under `src/functions/<functionCode>/index.ts` plus `src/resources/functions/<functionCode>.json`. Automation graphs can call it with a `function_call` node:
-
-```json
-{
-  "id": "call_summary",
-  "type": "function_call",
-  "data": {
-    "functionCode": "reservation_reminder_summary",
-    "input": { "scope": "today" },
-    "saveResponseTo": "summary"
-  }
-}
-```
-
-Use JS_CODE V2 when the script is local to one automation graph node.
-
-```json
-{
-  "id": "sync_customer",
-  "type": "js_code",
-  "data": {
-    "label": "同步客户",
-    "runtimeMode": "trusted_node",
-    "sourceType": "file_snapshot",
-    "scriptCode": "sync_customer",
-    "sourceFile": {
-      "localPath": "src/js-code-nodes/sync_customer/index.ts"
-    },
-    "timeout": 30000
-  }
-}
-```
-
-Author source in `src/js-code-nodes/<scriptCode>/index.ts`. AI-authored source must be TypeScript. Build with `pnpm build-js-code --script <scriptCode>`; the explicit selector typechecks only that entry plus its transitive/shared/ambient dependencies before bundling, while an unscoped build validates the whole workspace. During validate/create, the CLI uploads the generated bundle, replaces `sourceFile.localPath` with `{ bucketName, objectName, sha256, ... }`, and the backend verifies sha256 before execution.
-
-The backend runs the snapshot in the trusted Node runtime, applies the node timeout (`30000` ms by default), stores execution logs, and writes the returned value to the node output and `variables.node_<nodeId>`. Scripts may use `export default async function (ctx) {}`, `module.exports = async (ctx) => {}`, `require`, `process`, `Buffer`, arbitrary HTTP, and `platform.api` for `/openxiangda-api/v1`.
-
-Runtime context includes `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, and `ctx.node`. Prefer the higher-level resource helpers when available: `ctx.resources.resolveForm/resolveDataView/resolveConnector`, `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`, `ctx.files.readAsBase64`, `ctx.dataView.query/stats`, `ctx.connector.call/invoke`, `ctx.notification.*`, `ctx.platform.roles.*`, and `ctx.platform.api.*`. `ctx.files.readAsBase64` reads only server-authorized image attachments from current form data or an explicit form record/field reference, never an arbitrary URL; the file limit is 10 MiB and its Base64 result must not be logged or persisted. Use `ctx.platform.roles.findByCode/addUsers/removeUser` for app role member synchronization; raw `ctx.platform.api.*` returns an HTTP response and platform envelope. Published App Function and trusted-node code may write forms in its current tenant/application; per-resource declarations are mapping and audit metadata, not an application-internal allowlist. This does not grant page users direct submit access, so keep internal forms closed to raw user submission unless the business requires it. Legacy data/process bridge methods remain available as `ctx.methods.queryOneData`, `queryManyData`, `getDataByFormInstanceId`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
-
-Code automation also exposes `ctx.logger.debug/info/warn/error(message, data?)`. AI-authored code should log input parsing, query conditions, external calls, writes, branch decisions, and caught errors. Logs are stored as full raw execution data by default. Use CLI diagnosis commands:
-
-```bash
-openxiangda automation executions daily_ticket_digest --status failed --profile dev
-openxiangda automation logs <instanceId> --automation daily_ticket_digest --profile dev
-openxiangda automation diagnose daily_ticket_digest --profile dev
-```
-
-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
-export default async function scheduledReconcile(ctx) {
-  const appType = ctx.app.appType;
-  const current = ctx.formData?.current || {};
-  const formInstanceId =
-    ctx.triggerEvent?.data?.formInstanceId ||
-    current.formInstanceId ||
-    current.formInstId;
-
-  const pendingRows = await ctx.methods.queryManyData(appType, "FORM_ORDER", {
-    status: "pending",
-  });
-
-  if (formInstanceId) {
-    await ctx.methods.updateDataByFormInstanceId(
-      appType,
-      "FORM_ORDER",
-      formInstanceId,
-      { last_checked_at: new Date().toISOString() }
-    );
-  }
-
-  const log = await ctx.methods.createOneData(appType, "FORM_JOB_LOG", {
-    trigger_type: ctx.triggerEvent?.type || "scheduled",
-    processed_count: Array.isArray(pendingRows) ? pendingRows.length : 0,
-  });
-
-  return {
-    processedCount: pendingRows?.length || 0,
-    logId: log?.formInstanceId || log?.id,
-  };
-}
-```
-
-Validation rules:
-
-- `version` must be `v3`.
-- `nodes` and `edges` must be arrays.
-- Exactly one `start` node is required.
-- Each node needs `id`, `type`, and object `data`.
-- Each edge needs `id`, `source`, and `target`.
-- Use `openxiangda automation validate --strict` before publishing.

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

@@ -1,272 +0,0 @@
-# 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
-   - access governance / role governance / permissions
-   - optional admin UI template:
-     `glass-home-dashboard`, `mint-analytics-dashboard`,
-     `ops-monitor-dashboard`, or `work-order-list-drawer`
-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
-- user-facing responsibility fields such as personnel, department, enum, or
-  SDK-backed select fields
-- hidden permission scope keys only for small fixed data-permission conditions;
-  for dynamic customer/project/region/store/college/class-like scopes, use
-  business authorization forms plus `scope_policy`
-- 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 account, role, RBAC, data-scope, or query-parameter authorization
-requirements, read `permission-design-patterns.md` and choose one mode before
-writing code:
-
-- `managed-platform-account`: the app owns platform account/department lifecycle
-  and role synchronization.
-- `existing-platform-user-assignment`: the app assigns existing platform users
-  to app roles and business scopes.
-- `static-role-permission`: roles and permission groups are fixed resources.
-- `query-param-context`: query parameters are context, filters, or ticket input
-  only; sensitive access still needs real authorization.
-
-For apps with managed accounts or dynamic roles:
-
-1. Create the minimum governance forms required by the chosen mode:
-   `organization_unit`, `system_account`, `role_assignment`, or a smaller app
-   role maintenance form such as `app-role`.
-2. Use App Functions, automation, or JS_CODE to sync organization units,
-   platform accounts, and role records to platform departments/accounts/roles.
-3. Model visible scope fields with maintainable controls:
-   - personnel and departments use platform personnel/department fields
-   - enum scopes use `SelectField` / `RadioField` with `options`
-   - class, college, project, customer, and similar maintained records use
-     `SelectField` with `optionSource.type: "linkedForm"` so the runtime queries
-     source form records through the SDK and builds dropdown options
-   - when the source form can have many records, set `remoteSearch: true`,
-     `searchFieldId`, and a reasonable `pageSize` so typing in the dropdown
-     triggers remote search
-4. Add hidden derived scope keys only when platform form permission conditions
-   require scalar matching in a small fixed app, for example:
-   - `collegeScopeKey`
-   - `classScopeKey`
-   - `ownerDeptScopeKey`
-   - `ownerUserScopeKey`
-5. Create page permission groups for entry visibility.
-6. For dynamic business ranges, declare
-   `permissions/scope-dimensions`, `permissions/scope-grant-sources`, and
-   `permissions/data-scope-policies`, then reference the policy from form
-   permission groups or Data View permission groups with
-   `dataPermission.type = "scope_policy"`.
-7. Use condition-based data permissions only when the scope values are a small,
-   fixed set or map cleanly to platform organization/departments.
-8. For delegated administrators, add role API permissions in
-   `src/resources/roles/<code>.json` with `apiPermissionCodes`, for example
-   `app:role:manage`, `app:page-permission-group:manage`,
-   `app:form-permission-group:manage`, and `app:organization:manage`.
-9. Put sensitive writes behind App Functions with server-side role/scope checks.
-
-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.
-
-Do not generate one role or one permission group per customer, project, region,
-store, college, class, or other maintained business object. That configuration
-will not scale and should be replaced with a form-maintained authorization
-relationship and `scope_policy`.
-
-Query parameters are not permission control either. They may prefill context,
-select filters, or carry a signed/expiring ticket, but tampering with a query
-parameter must not expand sensitive data access.
-
-## Form Copy And Field Visibility
-
-- Every visible form field should have a short, user-facing placeholder.
-- Do not add tips to every field. Tips are only for special constraints,
-  unusual formats, compliance notes, or non-obvious business rules.
-- Use select/radio controls for enums. For values maintained by other forms, use
-  `SelectField` with SDK-backed `optionSource` options. Do not ask users to type
-  raw IDs.
-- Hide permission scope keys, computed, sync, and developer/internal fields with
-  `behavior: "HIDDEN"` when they must exist in the schema. Scope keys should be
-  derived from visible select/person/department fields, not typed by
-  users. For select-derived scalar keys, use `valueSync`.
-- Do not add separate creator, updater, creator department, updater department,
-  created time, or updated time fields unless the user explicitly needs a
-  separate business field. The platform creates system metadata for every form.
-- All visible copy must be written for end users. Do not put implementation
-  notes, schema descriptions, or development explanations in sections, cards,
-  labels, tips, helper text, or empty states.
-
-## 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.
-- For PC CRUD, ticket, approval, and data-management pages, use overlay drawers
-  or modals for detail, create, edit, approve/reject, and process forms. Do not
-  keep a permanent right-side detail/form column that narrows the table.
-- 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 first
-  for form-entry fields, personnel, departments, files, images, rich text,
-  signatures, locations, standard forms, and data lists.
-- Use `antd` / `antd-mobile` as the fallback for non-platform page controls,
-  overlays, tables, steps, tabs, and temporary wrappers for missing platform
-  capabilities. AI-authored app/workspace code must not emit raw native form
-  controls; native inputs belong inside OpenXiangda SDK/platform component
-  internals only.
-- 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
-
-- `glass-home-dashboard`: optional default for PC admin home pages, management
-  portals, and business overviews. Includes sidebar, top search, welcome
-  banner, quick actions, KPI cards, charts, ranking, activity feed, query
-  states, and drawer form actions.
-- `mint-analytics-dashboard`: optional default for data-analysis and BI-like
-  dashboards. Includes dense metric cards, line/bar/donut charts, notifications,
-  todos, business summary, system health, query states, and drawer form actions.
-- `ops-monitor-dashboard`: optional default for realtime operations,
-  monitoring, task execution, alerts, system health, and device status. Uses
-  lightweight CSS motion by default; do not add GSAP unless a real timeline
-  requirement exists.
-- `work-order-list-drawer`: default CRUD/list template for tickets, approvals,
-  data-management pages, orders, and assets. Includes filters, toolbar, status
-  stats, table, loading/empty/error branches, and right-side overlay drawers for
-  detail, create, edit, and process forms.
-- `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.
-- `access-governance`: account/role permission mode decision, organization,
-  account, role assignment, sync function, roles, page-group, and form-group
-  skeletons.
-- `role-governance`: role maintenance form, role sync JS_CODE, maintainable
-  scope fields, hidden permission keys, 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.