openxiangda 1.0.0

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

@@ -0,0 +1,466 @@
+# OpenXiangda API
+
+Base path: `/openxiangda-api/v1`
+
+OpenXiangda APIs use `/openxiangda-api/v1`. Legacy `/dingtalk-api/v1.0` exists only for compatibility and should not be used for new AI workflow or automation work.
+
+Standard private deployment public paths:
+
+- Backend APIs: `<origin>/service/openxiangda-api/v1`
+- Platform management and login UI: `<origin>/platform`
+- App runtime pages: `<origin>/view`
+
+CLI profiles store the backend API base, usually `<origin>/service`. Do not call `/openxiangda-api/v1` directly at the root origin.
+
+Authentication:
+
+- Normal CLI calls use `Authorization: Bearer <accessToken>`.
+- Refresh calls use the `refreshToken` request body.
+- Legacy `/dingtalk-api/v1.0` AK/SK authentication is not part of OpenXiangda.
+
+## Auth
+
+### POST `/auth/cli-sessions`
+
+Creates a one-time CLI login session.
+
+Response data:
+
+```json
+{
+  "sessionId": "string",
+  "loginUrl": "https://platform/service/openxiangda-api/v1/auth/cli-sessions/:id/login",
+  "qrText": "string",
+  "expireIn": 300
+}
+```
+
+### GET `/auth/cli-sessions/:sessionId`
+
+Polls login state. Pending response:
+
+```json
+{
+  "status": "pending",
+  "expireIn": 298
+}
+```
+
+Authorized response:
+
+```json
+{
+  "status": "authorized",
+  "accessToken": "jwt",
+  "refreshToken": "jwt",
+  "accessTokenExpiresAt": 1770000000000,
+  "refreshTokenExpiresAt": 1772000000000,
+  "user": {},
+  "tenant": {}
+}
+```
+
+### GET `/auth/whoami`
+
+Requires Bearer token. Returns user, tenant, platform admin status, and manageable app scope.
+
+### POST `/auth/refresh`
+
+Body:
+
+```json
+{
+  "refreshToken": "jwt"
+}
+```
+
+### POST `/auth/logout`
+
+Requires Bearer token. Revokes the current CLI token session.
+
+## App Snapshot
+
+### GET `/apps/`
+
+Requires Bearer token. Returns apps visible to the current user.
+
+### POST `/apps/`
+
+Requires Bearer token. Creates an app with the current user's permissions.
+
+### GET `/apps/:appType`
+
+Requires Bearer token. Returns app detail.
+
+### GET `/apps/:appType/forms`
+
+Requires Bearer token. Returns forms under the app.
+
+### POST `/apps/:appType/forms`
+
+Requires Bearer token. Creates a normal or workflow form shell.
+
+This endpoint is not the AI page generation path. User-facing normal form pages and workflow form pages must be built from `sy-lowcode-app-workspace` and registered through workspace publish; otherwise the platform only has the legacy/default schema page.
+
+### GET `/apps/:appType/forms/:formUuid`
+
+Requires Bearer token. Returns schema, packages, fields, runtime settings, and custom page publish settings.
+
+### PUT `/apps/:appType/forms/:formUuid`
+
+Requires Bearer token. Updates lightweight form metadata such as name.
+
+### PUT `/apps/:appType/forms/:formUuid/schema`
+
+Requires Bearer token. Updates the form schema and packages. The request may pass `schema` and `packages` as JSON values or JSON strings.
+
+### POST `/apps/:appType/forms/:formUuid/publish`
+
+Requires Bearer token. Registers the built form bundle by writing custom page runtime settings to the form.
+
+### GET `/apps/:appType/forms/:formUuid/settings`
+
+Requires Bearer token. Returns normalized form settings.
+
+### PUT `/apps/:appType/forms/:formUuid/settings`
+
+Requires Bearer token. Deep-merges form settings.
+
+### GET `/apps/:appType/forms/:formUuid/field-indexes`
+
+Requires Bearer token. Returns indexable fields, system indexes, and custom field index status.
+
+### PUT `/apps/:appType/forms/:formUuid/field-indexes`
+
+Requires Bearer token. Saves custom field index definitions and reconciles database indexes.
+
+Body:
+
+```json
+{
+  "indexes": [
+    { "id": "idx_customer", "fields": ["customerName"] }
+  ]
+}
+```
+
+### GET `/apps/:appType/forms/:formUuid/data-management`
+
+Requires Bearer token. Returns data management page config.
+
+### PUT `/apps/:appType/forms/:formUuid/data-management`
+
+Requires Bearer token. Saves data management page config.
+
+Body:
+
+```json
+{
+  "config": {
+    "columns": [],
+    "filters": [],
+    "actions": []
+  }
+}
+```
+
+### GET `/apps/:appType/forms/:formUuid/public-access`
+
+Requires Bearer token. Returns public/guest access config for the form.
+
+### PUT `/apps/:appType/forms/:formUuid/public-access`
+
+Requires Bearer token. Creates or updates public/guest access config.
+
+Body:
+
+```json
+{
+  "isPublic": true,
+  "description": "公开填报"
+}
+```
+
+### DELETE `/apps/:appType/forms/:formUuid/public-access`
+
+Requires Bearer token. Deletes public/guest access config for the form.
+
+### GET `/apps/:appType/menus`
+
+Requires Bearer token. Returns menu tree under the app.
+
+### POST `/apps/:appType/menus`
+
+Requires Bearer token. Creates a menu item.
+
+### PUT `/apps/:appType/menus/:menuId`
+
+Requires Bearer token. Updates a menu item.
+
+### DELETE `/apps/:appType/menus/:menuId`
+
+Requires Bearer token. Deletes a menu item.
+
+### PUT `/apps/:appType/menus/actions/sort`
+
+Requires Bearer token. Updates menu sorting and parent relationships in batch.
+
+### GET `/apps/:appType/workflows`
+
+Requires Bearer token. Lists workflow definitions in the app. Supports `formUuid`, `isPublished`, `page`, and `pageSize` query parameters.
+
+### POST `/apps/:appType/workflows`
+
+Requires Bearer token. Creates a workflow definition draft for a form.
+
+Body:
+
+```json
+{
+  "formUuid": "FORM_XXX",
+  "definitionJson": { "version": "v3", "nodes": [], "edges": [], "flowConfig": {} },
+  "viewJson": {}
+}
+```
+
+### POST `/apps/:appType/workflows/definition/validate`
+
+Requires Bearer token. Validates workflow v3 JSON before saving or publishing.
+
+### GET `/apps/:appType/workflows/:workflowId`
+
+Requires Bearer token. Returns a workflow definition detail.
+
+### PUT `/apps/:appType/workflows/:workflowId`
+
+Requires Bearer token. Updates a workflow draft. If the workflow is already published, the backend creates a new unpublished version.
+
+### POST `/apps/:appType/workflows/:workflowId/publish`
+
+Requires Bearer token. Publishes the workflow definition. Pass `{ "isPublished": false }` to unpublish.
+
+### DELETE `/apps/:appType/workflows/:workflowId`
+
+Requires Bearer token. Deletes an unpublished workflow definition.
+
+### GET `/apps/:appType/automations`
+
+Requires Bearer token. Lists automations in the app. Supports `formUuid`, `isPublished`, `isEnabled`, `triggerType`, `keyword`, `page`, and `pageSize`.
+
+### POST `/apps/:appType/automations`
+
+Requires Bearer token. Creates an automation draft.
+
+Body:
+
+```json
+{
+  "name": "客户提交后通知",
+  "description": "",
+  "formUuid": "FORM_XXX",
+  "triggerConfig": {
+    "type": "form_data_submitted",
+    "appType": "APP_XXX",
+    "formUuid": "FORM_XXX",
+    "enabled": true
+  },
+  "definitionJson": { "version": "v3", "nodes": [], "edges": [] },
+  "viewJson": {}
+}
+```
+
+### POST `/apps/:appType/automations/definition/validate`
+
+Requires Bearer token. Validates automation designer-v3 JSON and optional trigger config.
+
+### POST `/apps/:appType/automations/cron/validate`
+
+Requires Bearer token. Validates a cron expression used by scheduled automations.
+
+### GET `/apps/:appType/automations/:automationId`
+
+Requires Bearer token. Returns automation detail.
+
+### PUT `/apps/:appType/automations/:automationId`
+
+Requires Bearer token. Updates automation draft metadata, trigger config, definition JSON, or view JSON. Published automations create a new draft version.
+
+### POST `/apps/:appType/automations/:automationId/publish`
+
+Requires Bearer token. Publishes an automation.
+
+### POST `/apps/:appType/automations/:automationId/unpublish`
+
+Requires Bearer token. Unpublishes and disables an automation.
+
+### POST `/apps/:appType/automations/:automationId/enable`
+
+Requires Bearer token. Enables a published automation.
+
+### POST `/apps/:appType/automations/:automationId/disable`
+
+Requires Bearer token. Disables an automation.
+
+### DELETE `/apps/:appType/automations/:automationId`
+
+Requires Bearer token. Deletes an unpublished automation.
+
+### GET `/apps/:appType/automations/:automationId/versions`
+
+Requires Bearer token. Lists versions in the same automation group.
+
+### GET `/apps/:appType/automations/:automationId/executions`
+
+Requires Bearer token. Lists execution records for diagnosis.
+
+### GET `/apps/:appType/roles`
+
+Requires Bearer token. Lists app roles visible to the current user.
+
+### POST `/apps/:appType/roles`
+
+Requires Bearer token. Creates an app-scoped role.
+
+Body:
+
+```json
+{
+  "code": "sales",
+  "name": "销售",
+  "description": ""
+}
+```
+
+### GET `/apps/:appType/roles/:roleId`
+
+Requires Bearer token. Returns app role detail.
+
+### PUT `/apps/:appType/roles/:roleId`
+
+Requires Bearer token. Updates app role metadata.
+
+### DELETE `/apps/:appType/roles/:roleId`
+
+Requires Bearer token. Deletes a non-system app role.
+
+### GET `/apps/:appType/roles/:roleId/users`
+
+Requires Bearer token. Lists users under an app role.
+
+### POST `/apps/:appType/roles/:roleId/users`
+
+Requires Bearer token. Adds users to an app role.
+
+### DELETE `/apps/:appType/roles/:roleId/users/:userId`
+
+Requires Bearer token. Removes one user from an app role.
+
+### GET `/apps/:appType/page-permission-groups`
+
+Requires Bearer token. Lists page permission groups.
+
+### POST `/apps/:appType/page-permission-groups`
+
+Requires Bearer token. Creates a page permission group.
+
+Body:
+
+```json
+{
+  "name": "销售可见页面",
+  "roles": ["sales"],
+  "menuFormUuids": ["FORM_XXX"]
+}
+```
+
+An empty `menuFormUuids` array means all menus/pages are visible to the matched roles.
+
+### GET `/apps/:appType/page-permission-groups/:groupId`
+
+Requires Bearer token. Returns page permission group detail.
+
+### PUT `/apps/:appType/page-permission-groups/:groupId`
+
+Requires Bearer token. Updates a page permission group.
+
+### DELETE `/apps/:appType/page-permission-groups/:groupId`
+
+Requires Bearer token. Deletes a page permission group.
+
+### GET `/apps/:appType/page-permission-groups/user-menu-permissions`
+
+Requires Bearer token. Returns the current user's menu visibility summary for the app.
+
+### GET `/apps/:appType/forms/:formUuid/permission-groups`
+
+Requires Bearer token. Lists form permission groups.
+
+### POST `/apps/:appType/forms/:formUuid/permission-groups`
+
+Requires Bearer token. Creates a form permission group.
+
+Body:
+
+```json
+{
+  "name": "销售查看",
+  "type": "view",
+  "roles": ["sales"],
+  "dataScope": [{ "type": "self" }],
+  "operations": ["view"],
+  "fieldPermissions": [],
+  "dataPermission": null
+}
+```
+
+### GET `/apps/:appType/forms/:formUuid/permission-groups/:groupId`
+
+Requires Bearer token. Returns form permission group detail.
+
+### PUT `/apps/:appType/forms/:formUuid/permission-groups/:groupId`
+
+Requires Bearer token. Updates a form permission group.
+
+### DELETE `/apps/:appType/forms/:formUuid/permission-groups/:groupId`
+
+Requires Bearer token. Deletes a form permission group.
+
+### GET `/apps/:appType/forms/:formUuid/permission-summary`
+
+Requires Bearer token. Returns the merged current-user view permission summary for a form.
+
+### GET `/apps/:appType/forms/:formUuid/field-permissions`
+
+Requires Bearer token. Returns merged current-user field permissions for a form.
+
+### GET `/apps/:appType/pages`
+
+Requires Bearer token. Returns code page definitions.
+
+### POST `/apps/:appType/pages/manifest/import`
+
+Requires Bearer token. Imports an application-level code page manifest.
+
+### GET `/apps/:appType/pages/releases`
+
+Requires Bearer token. Returns application-level code page release summaries.
+
+### POST `/apps/:appType/pages/releases/activate`
+
+Requires Bearer token. Activates a release by `version` and `buildId`.
+
+### POST `/apps/:appType/pages/publish`
+
+Requires Bearer token. Publishes one or more code pages directly.
+
+### POST `/apps/:appType/pages/:pageCode/publish`
+
+Requires Bearer token. Publishes one code page directly, using `pageCode` as the stable logical key.
+
+### GET `/apps/:appType/pages/:pageKey/bootstrap`
+
+Requires Bearer token. Returns runtime bootstrap information for an existing code page.
+
+### GET `/apps/:appType/snapshot`
+
+Requires Bearer token. Returns app metadata, forms, menus, code page definitions, code page releases, and permission hints.

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

@@ -0,0 +1,13 @@
+# Page Runtime SDK
+
+Use `openxiangda/runtime` for platform data access in code pages.
+
+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.
+- 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.
+
+When the SDK lacks a capability, document the fallback and keep it isolated.

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

@@ -0,0 +1,36 @@
+# Code Page Publish Flow
+
+Preferred publish command:
+
+```bash
+openxiangda workspace publish --profile <name>
+```
+
+The CLI injects:
+
+- `OPENXIANGDA_PROFILE`
+- `OPENXIANGDA_BASE_URL`
+- `OPENXIANGDA_ACCESS_TOKEN`
+- `OPENXIANGDA_APP_TYPE`
+
+Workspace tools then:
+
+1. Scan `src/forms/*/schema.ts` and `page.tsx` for normal and workflow form pages.
+2. Scan `src/pages/*/page.config.ts` and React entries for custom code pages.
+3. Create or bind platform form shells only as needed.
+4. Build shared form/page runtimes and per-form/per-page bundles.
+5. Upload assets to OSS.
+6. Sync form metadata and register form/page bundles through `/openxiangda-api/v1`.
+
+Direct code page publish:
+
+```bash
+openxiangda page publish <pageCode> \
+  --entry-url <url> \
+  --css-urls <url1,url2> \
+  --version <version> \
+  --build-id <buildId> \
+  --profile <name>
+```
+
+Use direct publish only for already built assets or targeted repair. It is not the normal AI generation flow.

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

@@ -0,0 +1,38 @@
+# App Workspace Structure
+
+Form pages, workflow form pages, and custom code pages live in `sy-lowcode-app-workspace`.
+
+Create a new workspace with:
+
+```bash
+openxiangda workspace init ./my-app-workspace
+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:
+
+```bash
+openxiangda workspace init ./my-app-workspace --profile <name> --app-type APP_XXXX
+```
+
+Typical code page layout:
+
+```text
+src/pages/<pageCode>/
+├── page.tsx
+├── index.tsx
+├── styles.css
+└── assets/
+```
+
+Rules:
+
+- `pageCode` is the stable local key.
+- Form pages use `src/forms/<formCode>/schema.ts` plus `src/forms/<formCode>/page.tsx`.
+- Workflow form pages use the same form page structure; workflow v3 definitions are separate platform resources.
+- Keep page-specific assets under the page directory.
+- Shared components can live under `src/components/` when reused.
+- Build artifacts under `dist/` are generated and should not be hand edited.
+- Publish through `openxiangda workspace publish --profile <name>`.

package/openxiangda-skills/references/permissions-settings.md

@@ -0,0 +1,147 @@
+# Permissions And Settings Reference
+
+OpenXiangda permission APIs use ordinary user Bearer tokens. The effective permissions are the same as the current frontend user.
+
+## Role Codes
+
+Use stable local role codes:
+
+```json
+{
+  "code": "sales",
+  "name": "销售",
+  "description": "销售人员"
+}
+```
+
+Role IDs are platform-specific. Store them only in `.openxiangda/state.json` under the active profile.
+
+## Page Permission Groups
+
+Page permission groups map role codes to visible menu `formUuid` values:
+
+```json
+{
+  "name": "销售页面",
+  "roles": ["sales"],
+  "menuFormUuids": ["FORM_CUSTOMER", "FORM_ORDER"]
+}
+```
+
+Rules:
+
+- `roles: []` means all roles can match.
+- `menuFormUuids: []` means all menus/pages are visible to matched roles.
+- Prefer `--form-codes` in CLI so each profile resolves its own form UUIDs.
+
+## Form Permission Groups
+
+Submit group:
+
+```json
+{
+  "name": "销售提交",
+  "type": "submit",
+  "roles": ["sales"],
+  "operations": ["submit"]
+}
+```
+
+View group:
+
+```json
+{
+  "name": "销售查看",
+  "type": "view",
+  "roles": ["sales"],
+  "dataScope": [{ "type": "self" }],
+  "operations": ["view", "edit"],
+  "fieldPermissions": [
+    {
+      "componentName": "Text",
+      "fieldName": "客户名称",
+      "label": "customerName",
+      "value": "FORM_FILED_VIEW"
+    }
+  ]
+}
+```
+
+Field permission values:
+
+- `FORM_FILED_EDIT`
+- `FORM_FILED_VIEW`
+- `FORM_FILED_HIDDEN`
+
+Common data scopes:
+
+- `all`
+- `self`
+- `current_department`
+- `sub_departments`
+- `same_level_departments`
+- `custom_departments`
+
+Condition-style data permission:
+
+```json
+{
+  "type": "condition",
+  "condition": {
+    "logic": "AND",
+    "rules": [
+      {
+        "field": "owner",
+        "componentType": "Employee",
+        "op": "=",
+        "value": "${CURRENT_USER_ID}"
+      }
+    ]
+  }
+}
+```
+
+## Settings
+
+Form settings are deep-merged:
+
+```json
+{
+  "customPage": {
+    "enabled": true,
+    "bundleUrl": "https://cdn.example.com/form.js"
+  }
+}
+```
+
+Field index config:
+
+```json
+[
+  { "id": "idx_customer_name", "fields": ["customerName"] },
+  { "id": "idx_owner", "fields": ["owner"] }
+]
+```
+
+Data management config is stored as an opaque JSON object by the platform. Keep it profile-neutral and avoid embedding form UUIDs from another platform:
+
+```json
+{
+  "columns": [
+    { "fieldId": "customerName", "title": "客户名称", "visible": true }
+  ],
+  "filters": [],
+  "actions": []
+}
+```
+
+Public access config:
+
+```json
+{
+  "isPublic": true,
+  "description": "公开填报"
+}
+```
+
+Public access is resolved by `appType + formUuid`; no local ID mapping is needed.