openxiangda 1.0.49 → 1.0.51

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

@@ -34,6 +34,17 @@ openxiangda workspace publish --profile <name> --only pages/dashboard,forms/cust
 openxiangda workspace publish --profile <name>
 ```
 
+For Phase 6 React SPA workspaces (`workspace init --runtime react-spa`), do not use `workspace publish` for frontend routes. Publish in two explicit steps:
+
+```bash
+openxiangda resource validate --profile <name>
+openxiangda resource plan --profile <name>
+openxiangda resource publish --profile <name>
+openxiangda runtime deploy --profile <name>
+```
+
+`runtime deploy` builds the Vite app with a release-specific asset base, uploads `dist/` to the platform runtime release store, and activates the release unless `--no-activate` is passed.
+
 ## DO NOT
 
 - ❌ `pnpm publish:all` / `pnpm publish:oss` / `pnpm register` / `lowcode-workspace publish-*` directly. They are workspace internals and miss `OPENXIANGDA_PROFILE / BASE_URL / ACCESS_TOKEN / APP_TYPE` injection.
@@ -116,6 +127,27 @@ pnpm install
 openxiangda env --profile dev
 ```
 
+For new Phase 6 React SPA apps:
+
+```bash
+openxiangda workspace init ./my-react-app \
+  --profile dev \
+  --app-name "测试应用" \
+  --runtime react-spa
+cd ./my-react-app
+pnpm install
+pnpm dev
+openxiangda resource typegen --profile dev
+openxiangda resource plan --profile dev
+```
+
+React SPA apps are standard React/Vite projects. Use React Router for routing,
+Tailwind CSS for styling, and `openxiangda/runtime/react` for runtime bootstrap,
+menus, and route permission checks. Do not publish React SPA pages through the
+old custom-page app-shell path unless explicitly maintaining a legacy app.
+Use `openxiangda resource publish` for roles/menus/page permission groups and
+`openxiangda runtime deploy` for the SPA frontend release.
+
 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/`.
@@ -194,7 +226,7 @@ The snapshot endpoint aggregates app metadata, forms, menus, code pages, release
 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 classic workspaces, 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:
 
@@ -225,6 +257,18 @@ The publish script is responsible for:
 4. Uploading assets to OSS.
 5. Registering bundles through `/openxiangda-api/v1` with `OPENXIANGDA_ACCESS_TOKEN`.
 
+For React SPA workspaces, the frontend publish command is:
+
+```bash
+openxiangda runtime deploy --profile prod
+```
+
+It is responsible for:
+
+1. Running the workspace build command with `OPENXIANGDA_APP_TYPE`, `OPENXIANGDA_BUILD_ID`, and `OPENXIANGDA_RUNTIME_ASSET_BASE`.
+2. Uploading `dist/` to `/openxiangda-api/v1/apps/:appType/runtime/releases`.
+3. Activating the new runtime release so `/view/:appType/*` enters the React app.
+
 ## References
 
 - `../../references/openxiangda-api.md` — exact endpoint contracts.

package/openxiangda-skills/skills/openxiangda-permission-settings/SKILL.md

@@ -64,6 +64,37 @@ openxiangda permission page-group-create portal_pages --name "门户页面" --pa
 
 Use `--page-codes` or `--menu-codes` for custom code page menus; the CLI resolves the permission group to the published menu ID and keeps required page ID, route key, and legacy `PAGE_...` runtime aliases in the same group so the platform editor can still round-trip the selection. Use `--form-codes` for form menus; the CLI resolves forms to profile-local form UUIDs. Empty target lists mean all menus/pages are visible to matched roles. Only pass `--no-runtime-aliases` after confirming the target platform checks menu IDs directly at runtime.
 
+For Phase 6 React SPA apps, define menu visibility and direct route access with
+resource codes instead of old platform menu-tree-only targets:
+
+```json
+{
+  "code": "sales_spa_pages",
+  "name": "销售 SPA 页面",
+  "roles": ["sales"],
+  "menuCodes": ["sales_dashboard", "customer_data"],
+  "routeCodes": ["sales.dashboard", "customer.data"],
+  "pathPatterns": ["/view/:appType/admin/sales/*"]
+}
+```
+
+Or create from CLI:
+
+```bash
+openxiangda permission page-group-create sales_spa_pages \
+  --name "销售 SPA 页面" \
+  --roles sales \
+  --menu-codes sales_dashboard,customer_data \
+  --route-codes sales.dashboard,customer.data \
+  --path-patterns '/view/:appType/admin/sales/*' \
+  --profile dev
+```
+
+Do not hardcode role checks in React pages. Use backend runtime bootstrap,
+`useAppMenus()`, `useCanAccessRoute()`, and `PermissionBoundary` from
+`openxiangda/runtime/react` for display control. Backend form, field, data,
+workflow, file, and connector permissions remain authoritative.
+
 ## Form Permission Groups
 
 Form permission groups control submit/view permissions, data scope, operations, and fields:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.49",
+  "version": "1.0.51",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -21,6 +21,11 @@
       "import": "./packages/sdk/dist/runtime/index.mjs",
       "require": "./packages/sdk/dist/runtime/index.cjs"
     },
+    "./runtime/react": {
+      "types": "./packages/sdk/dist/runtime/react.d.ts",
+      "import": "./packages/sdk/dist/runtime/react.mjs",
+      "require": "./packages/sdk/dist/runtime/react.cjs"
+    },
     "./build": {
       "types": "./packages/sdk/dist/build/index.d.ts",
       "import": "./packages/sdk/dist/build/index.mjs",
@@ -60,6 +65,7 @@
     "prepack": "npm run build:sdk",
     "test:profile-isolation": "bash scripts/profile-isolation-smoke.sh",
     "test:resource-plan": "node scripts/resource-plan-smoke.mjs",
+    "test:runtime-deploy": "node scripts/runtime-deploy-smoke.mjs",
     "test:skill-install": "bash scripts/skill-install-smoke.sh",
     "test:workspace-init": "bash scripts/workspace-init-smoke.sh"
   },