openxiangda 1.0.19 → 1.0.21

package/openxiangda-skills/SKILL.md

@@ -74,6 +74,8 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - Before publishing to another platform, verify the workspace is bound for that profile. Resource IDs from one profile must not be reused for another profile.
 - Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` for diagnosis before changing an existing app.
 - Run write commands that update `.openxiangda/state.json` sequentially within the same workspace. Read-only commands can run in parallel.
+- JS_CODE is backend-executed workflow/automation logic, not frontend page code. Use it when logic must run after a backend trigger such as fixed cron schedules, form date-field schedules, form submit/update/delete/field-change events, or workflow approval/process events.
+- Use JS_CODE for cross-form data queries, create/update/batch update operations, process termination, platform API calls, external HTTP calls, and complex orchestration that the frontend cannot handle reliably. Do not use it for simple UI interactions, ordinary form validation, or display-only page behavior.
 - For workflow/automation JS_CODE nodes, prefer V2 `runtimeMode: "trusted_node"`. AI-authored source must be TypeScript under `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`. `pnpm build-js-code --script <scriptCode>` runs TypeScript validation before bundling, and `sourceFile.localPath` should point to the TS source; the CLI builds, uploads, and replaces it with snapshot metadata during validate/create.
 
 ## Subskills

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

@@ -7,6 +7,8 @@ Automations have two files:
 
 ## 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.
+
 Form submit trigger:
 
 ```json
@@ -96,7 +98,7 @@ Supported node types:
 
 ## JS_CODE V2
 
-Use trusted Node JS_CODE nodes for AI/admin automation logic:
+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.
 
 ```json
 {
@@ -117,7 +119,45 @@ Use trusted Node JS_CODE nodes for AI/admin automation logic:
 
 Author source in `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`. AI-authored source must be TypeScript. Build with `pnpm build-js-code --script <scriptCode>`; the command runs TypeScript validation before bundling. During validate/create, the CLI uploads the generated bundle, replaces `sourceFile.localPath` with `{ bucketName, objectName, sha256, ... }`, and the backend verifies sha256 before execution.
 
-Scripts may use `module.exports = async (ctx) => {}`, `require`, `process`, `Buffer`, legacy `methods.*`, arbitrary HTTP, and `platform.api` for `/openxiangda-api/v1`.
+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`. Data/process bridge methods include `ctx.methods.queryOneData`, `queryManyData`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
+
+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:
 

package/openxiangda-skills/references/pages/app-shell.md

@@ -0,0 +1,66 @@
+# App Shell Code Page Entries
+
+Use this pattern for formal user-facing entries such as admin consoles, PC
+portals, and mobile portals.
+
+## Required Page Config
+
+`page.config.ts` must declare app-shell entry metadata:
+
+```ts
+export default {
+  code: "instrument_admin",
+  name: "Instrument Admin",
+  route: { pathKey: "instrument_admin" },
+  entry: {
+    mode: "app-shell",
+    hidePlatformNav: true,
+    defaultRoute: "dashboard",
+  },
+};
+```
+
+Rules:
+
+- `entry.mode` is `"app-shell"` for formal product entries.
+- `entry.hidePlatformNav` is `true` unless the page is explicitly a debugging or maintenance page.
+- `entry.defaultRoute` is required and must point at the shell home route.
+- Plain one-off custom pages may omit `entry` or use `mode: "plain-page"`.
+
+## Expected File Shape
+
+Prefer this layout for app-shell pages:
+
+```text
+src/pages/<pageCode>/
+  page.config.ts
+  index.tsx
+  <Feature>Shell.tsx
+  routes.ts
+  modules/
+  __tests__/
+```
+
+`routes.ts` should export the route registry, default route, route parser, and
+route builder. Page components should navigate through that helper or
+`openxiangda/runtime` navigation.
+
+## Navigation Rules
+
+- Use the standard query key `route` for shell routes.
+- Use `navigation.pushRoute(route, query?)` and
+  `navigation.replaceRoute(route, query?)` for same-page shell navigation.
+- Do not scatter hardcoded `/view/...&isRenderNav=false` URLs through page code.
+- Menu links should bind the formal app-shell code page only. Native forms,
+  workflows, and view pages can stay as development resources or permission
+  targets, but should not become the product navigation shell.
+
+## Tests
+
+Add focused contract tests for:
+
+- `page.config.ts` includes `entry.mode: "app-shell"`.
+- default route fallback.
+- unknown route fallback.
+- preserving and deleting business query values.
+- preserving hidden platform nav when the route helper updates the URL.

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

@@ -52,6 +52,8 @@ Supported node types:
 
 ## JS_CODE V2
 
+Workflow JS_CODE runs on the backend when the process reaches the `js_code` node. Use it before or after approval nodes, in branches, or before ending a process when the workflow needs server-side side effects such as cross-form synchronization, audit record creation, external API calls, or terminating a related process. Do not use it for frontend-only behavior.
+
 Inline:
 
 ```json
@@ -87,7 +89,43 @@ File snapshot:
 }
 ```
 
-AI-authored JS_CODE source must be TypeScript under `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`. When validating or creating, the CLI runs `pnpm build-js-code --script <scriptCode>`, which runs TypeScript validation first, bundles to `dist/js-code-nodes/<scriptCode>/index.cjs`, uploads the bundle, and replaces `sourceFile.localPath` with immutable snapshot metadata. Scripts can export `export default async function (ctx) {}` or `module.exports = async (ctx) => {}` and call `ctx.platform.api` or global `platform.api`; the default API namespace is `/openxiangda-api/v1`.
+AI-authored JS_CODE source must be TypeScript under `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`. When validating or creating, the CLI runs `pnpm build-js-code --script <scriptCode>`, which runs TypeScript validation first, bundles to `dist/js-code-nodes/<scriptCode>/index.cjs`, uploads the bundle, and replaces `sourceFile.localPath` with immutable snapshot metadata. The backend verifies snapshot `sha256`, runs it 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 can export `export default async function (ctx) {}` or `module.exports = async (ctx) => {}`. The runtime exposes `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, `ctx.methods.*`, `ctx.platform.api.*`, `ctx.utils`, `require`, `process`, and `Buffer`. Use `ctx.methods.queryOneData/queryManyData/updateOneData/updateDataByFormInstanceId/updateManyData/createOneData/terminateProcess/getAllParentDepartments` for platform-side data and process operations.
+
+Example `src/js-code-nodes/sync_customer/index.ts`:
+
+```ts
+export default async function syncCustomer(ctx) {
+  const current = ctx.formData?.current || {};
+  const appType = ctx.app.appType;
+  const customerNo = current.customer_no;
+
+  const customer = await ctx.methods.queryOneData(appType, "FORM_CUSTOMER", {
+    customer_no: customerNo,
+  });
+
+  if (customer) {
+    await ctx.methods.updateOneData(
+      appType,
+      "FORM_CUSTOMER",
+      { customer_no: customerNo },
+      { last_approved_at: new Date().toISOString() }
+    );
+  }
+
+  const log = await ctx.methods.createOneData(appType, "FORM_SYNC_LOG", {
+    source: "workflow",
+    customer_no: customerNo,
+    result: customer ? "updated" : "missing",
+  });
+
+  return {
+    customerFound: Boolean(customer),
+    logId: log?.formInstanceId || log?.id,
+  };
+}
+```
 
 Field permission config lives in `flowConfig` by node ID:
 

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

@@ -40,6 +40,7 @@ openxiangda page publish dashboard \
 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/pages/page-sdk.md`
 - `../../references/pages/publish-flow.md`
 - `../../references/style-system.md` — three-layer style architecture, CSS namespace, and the no-hardcoded-color rule. Read before writing any page CSS or Tailwind class.
@@ -50,11 +51,14 @@ Read these references only when editing page code:
 ## Rules
 
 - 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`.
 - 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.
 - 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.
 - 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.

package/openxiangda-skills/skills/openxiangda-workflow-automation/SKILL.md

@@ -44,7 +44,9 @@ Use `workflow pull` to inspect the live definition. Use logical workflow codes l
 
 ## JS_CODE V2
 
-For non-trivial logic, prefer JS_CODE V2 trusted Node scripts over large inline snippets. AI-authored JS_CODE source must be TypeScript:
+JS_CODE is the backend execution escape hatch for workflow and automation. Use it when the logic must run on the server after a backend trigger, such as a fixed cron schedule, a form date-field schedule, a form submit/update/delete/field-change event, or a workflow approval/process event. It is appropriate for cross-form data queries, create/update/batch update operations, process termination, platform API calls, external HTTP calls, and complex orchestration that the frontend cannot handle reliably.
+
+Do not use JS_CODE for simple UI interactions, ordinary form validation, display-only page behavior, or logic that belongs in a normal React code page. For non-trivial backend logic, prefer JS_CODE V2 trusted Node scripts over large inline snippets. AI-authored JS_CODE source must be TypeScript:
 
 1. Put source in `sy-lowcode-app-workspace/src/js-code-nodes/<scriptCode>/index.ts`.
 2. Run `pnpm build-js-code --script <scriptCode>`. This command runs TypeScript validation first and only bundles after `tsc` passes.
@@ -68,7 +70,14 @@ For non-trivial logic, prefer JS_CODE V2 trusted Node scripts over large inline
 
 The CLI requires `sourceFile.localPath` to point to `src/js-code-nodes/<scriptCode>/index.ts`. During validate/create it runs `pnpm build-js-code --script <scriptCode>`, uploads the generated `dist/js-code-nodes/<scriptCode>/index.cjs` to `/file/js-code-snapshot/upload`, verifies the server snapshot metadata, and replaces it with `{ bucketName, objectName, sha256, ... }`.
 
-Inside the TypeScript script, prefer `export default async function (ctx) {}` or `module.exports = async (ctx) => {}`. The runtime exposes Node `require`, `process`, `Buffer`, installed dependencies, arbitrary HTTP, legacy `methods.*`, and `platform.api` for `/openxiangda-api/v1`.
+The backend verifies the uploaded snapshot sha256 before execution, runs it in the trusted Node runtime, applies the node timeout (`30000` ms by default), stores console/runtime logs in the execution record, and writes the returned value to the node output and `variables.node_<nodeId>`.
+
+Inside the TypeScript script, prefer `export default async function (ctx) {}` or `module.exports = async (ctx) => {}`. The runtime exposes:
+
+- Context: `ctx.triggerEvent`, `ctx.formData`, `ctx.workflowData`, `ctx.operator`, `ctx.app`, `ctx.variables`, and `ctx.node`.
+- Data/process methods: `ctx.methods.queryOneData`, `queryManyData`, `updateOneData`, `updateDataByFormInstanceId`, `updateManyData`, `createOneData`, `terminateProcess`, and `getAllParentDepartments`.
+- Platform API bridge: `ctx.platform.api.get/post/put/patch/delete/request` for `/openxiangda-api/v1`.
+- Node runtime helpers: `require`, `process`, `Buffer`, `ctx.utils`, `ctx.utils.http`, and `ctx.console`.
 
 ## Automation Flow
 

package/package.json

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

package/packages/sdk/dist/runtime/index.d.mts

@@ -127,6 +127,13 @@ interface PageDataSourceDescriptor {
     defaultFilter?: SearchExpression | string;
     [key: string]: unknown;
 }
+type CustomPageEntryMode = "app-shell" | "plain-page";
+interface CustomPageEntryConfig {
+    mode?: CustomPageEntryMode | string;
+    hidePlatformNav?: boolean;
+    defaultRoute?: string;
+    [key: string]: unknown;
+}
 interface PageInfo {
     id: string;
     code: string;
@@ -138,6 +145,7 @@ interface PageInfo {
     status: string;
     props: Record<string, unknown>;
     route: Record<string, unknown> | object;
+    entry?: CustomPageEntryConfig;
     dataSources: PageDataSourceDescriptor[];
     capabilities: Record<string, unknown>;
     version?: string;
@@ -164,6 +172,8 @@ interface PageNavigationApi {
      */
     pushPage(pageKey: string, query?: Record<string, unknown>): void;
     replacePage(pageKey: string, query?: Record<string, unknown>): void;
+    pushRoute(route: string, query?: Record<string, unknown>): void;
+    replaceRoute(route: string, query?: Record<string, unknown>): void;
     updateQuery(query: Record<string, unknown>): void;
     setHash(hash: string): void;
     back(): void;
@@ -856,4 +866,4 @@ declare const usePageRoute: () => PageRouteInfo;
 
 declare const usePageSdk: () => PageSdk;
 
-export { type ApiPermissionListParams, type ApproveTaskParams, type AssignPermissionsParams, type AssignRolesParams, type BatchAddUsersToRoleParams, type BatchSendNotificationByTypeParams, type ChangeUserRoleParams, type ConnectorCallParams, type ConnectorInvokeParams, type ConnectorInvokeResult, type ConnectorRequestBodyType, type ConnectorResponseType, type CreateApiPermissionParams, type CreateFormPermissionGroupDto, type CreatePagePermissionGroupDto, type CreateRoleParams, type CreateUiPermissionParams, type CreateUserParams, type CurrentUserDepartmentParents, type DataManagementConfigParams, type DataManagementFilterState, type DataPermissionConditionDto, type DataPermissionDto, type DataPermissionRuleDto, type FieldPermissionDto, type FormAdvancedSearchParams, type FormChangeRecordParams, type FormCreateParams, type FormExportParams, type FormGetDetailParams, type FormImportParams, type FormPermissionGroup, type FormRemoveParams, type FormSearchParams, type FormUpdateParams, type GetParentDepartmentsOptions, type GetProcessInstanceParams, type GetUserRolesParams, type ImportExportRecordDownloadParams, type ImportExportRecordQuery, type InstanceStatus, type NotificationChannel, type NotificationMessageRecord, type PageApiPermissionRecord, type PageApiResponse, type PageAppInfo, type PageBinaryResponse, type PageBridgeApi, type PageContext, type PageDataManagementConfig, type PageDataSourceDescriptor, type PageDepartmentInfo, type PageDepartmentRecord, type PageHttpMethod, type PageInfo, type PageListResult, type PageMessageApi, type PageModalApi, type PageNavigationApi, type PageOffsetListResult, type PagePermissionGroup, type PagePermissionInfo, PageProvider, type PageQueryValue, type PageRequestOptions, type PageRoleRecord, type PageRouteInfo, type PageScope, type PageSdk, type PageSdkError, type PageSdkMeta, type PageTransportDownloadPayload, type PageTransportRequestPayload, type PageUiPermissionRecord, type PageUiPermissionType, type PageUserInfo, type PageUserRecord, type PageUserType, type ProcessApproveAction, type QueryFormPermissionGroupDto, type QueryPagePermissionGroupDto, type RoleListParams, type RoleUsersParams, type SaveDataManagementConfigParams, type SearchComponentName, type SearchExpression, type SearchFieldKey, type SearchGroup, type SearchLogic, type SearchOperator, type SearchRule, type SearchSortItem, type SearchSystemField, type SendNotificationByTypeParams, type SendNotificationResult, type SubFormRule, type SwitchAppRoleParams, type SwitchPlatformRoleParams, type TerminateProcessInstanceParams, type TriggerCallbackTaskParams, type UiPermissionListParams, type UpdateApiPermissionParams, type UpdateFormPermissionGroupDto, type UpdatePagePermissionGroupDto, type UpdateRoleParams, type UpdateUiPermissionParams, type UpdateUserParams, type UserListParams, type UserMenuPermissionsResponse, type ValidateUserParams, type ViewFieldPermissionValue, type ViewOperationPermission, type ViewPermissionSummary, createPageSdk, createReactPage, useCurrentUser, useDataSource, useFormViewPermissions, useMessage, useModal, useNavigation, usePageContext, usePageProps, usePageRoute, usePageSdk };
+export { type ApiPermissionListParams, type ApproveTaskParams, type AssignPermissionsParams, type AssignRolesParams, type BatchAddUsersToRoleParams, type BatchSendNotificationByTypeParams, type ChangeUserRoleParams, type ConnectorCallParams, type ConnectorInvokeParams, type ConnectorInvokeResult, type ConnectorRequestBodyType, type ConnectorResponseType, type CreateApiPermissionParams, type CreateFormPermissionGroupDto, type CreatePagePermissionGroupDto, type CreateRoleParams, type CreateUiPermissionParams, type CreateUserParams, type CurrentUserDepartmentParents, type CustomPageEntryConfig, type CustomPageEntryMode, type DataManagementConfigParams, type DataManagementFilterState, type DataPermissionConditionDto, type DataPermissionDto, type DataPermissionRuleDto, type FieldPermissionDto, type FormAdvancedSearchParams, type FormChangeRecordParams, type FormCreateParams, type FormExportParams, type FormGetDetailParams, type FormImportParams, type FormPermissionGroup, type FormRemoveParams, type FormSearchParams, type FormUpdateParams, type GetParentDepartmentsOptions, type GetProcessInstanceParams, type GetUserRolesParams, type ImportExportRecordDownloadParams, type ImportExportRecordQuery, type InstanceStatus, type NotificationChannel, type NotificationMessageRecord, type PageApiPermissionRecord, type PageApiResponse, type PageAppInfo, type PageBinaryResponse, type PageBridgeApi, type PageContext, type PageDataManagementConfig, type PageDataSourceDescriptor, type PageDepartmentInfo, type PageDepartmentRecord, type PageHttpMethod, type PageInfo, type PageListResult, type PageMessageApi, type PageModalApi, type PageNavigationApi, type PageOffsetListResult, type PagePermissionGroup, type PagePermissionInfo, PageProvider, type PageQueryValue, type PageRequestOptions, type PageRoleRecord, type PageRouteInfo, type PageScope, type PageSdk, type PageSdkError, type PageSdkMeta, type PageTransportDownloadPayload, type PageTransportRequestPayload, type PageUiPermissionRecord, type PageUiPermissionType, type PageUserInfo, type PageUserRecord, type PageUserType, type ProcessApproveAction, type QueryFormPermissionGroupDto, type QueryPagePermissionGroupDto, type RoleListParams, type RoleUsersParams, type SaveDataManagementConfigParams, type SearchComponentName, type SearchExpression, type SearchFieldKey, type SearchGroup, type SearchLogic, type SearchOperator, type SearchRule, type SearchSortItem, type SearchSystemField, type SendNotificationByTypeParams, type SendNotificationResult, type SubFormRule, type SwitchAppRoleParams, type SwitchPlatformRoleParams, type TerminateProcessInstanceParams, type TriggerCallbackTaskParams, type UiPermissionListParams, type UpdateApiPermissionParams, type UpdateFormPermissionGroupDto, type UpdatePagePermissionGroupDto, type UpdateRoleParams, type UpdateUiPermissionParams, type UpdateUserParams, type UserListParams, type UserMenuPermissionsResponse, type ValidateUserParams, type ViewFieldPermissionValue, type ViewOperationPermission, type ViewPermissionSummary, createPageSdk, createReactPage, useCurrentUser, useDataSource, useFormViewPermissions, useMessage, useModal, useNavigation, usePageContext, usePageProps, usePageRoute, usePageSdk };

package/packages/sdk/dist/runtime/index.d.ts

@@ -127,6 +127,13 @@ interface PageDataSourceDescriptor {
     defaultFilter?: SearchExpression | string;
     [key: string]: unknown;
 }
+type CustomPageEntryMode = "app-shell" | "plain-page";
+interface CustomPageEntryConfig {
+    mode?: CustomPageEntryMode | string;
+    hidePlatformNav?: boolean;
+    defaultRoute?: string;
+    [key: string]: unknown;
+}
 interface PageInfo {
     id: string;
     code: string;
@@ -138,6 +145,7 @@ interface PageInfo {
     status: string;
     props: Record<string, unknown>;
     route: Record<string, unknown> | object;
+    entry?: CustomPageEntryConfig;
     dataSources: PageDataSourceDescriptor[];
     capabilities: Record<string, unknown>;
     version?: string;
@@ -164,6 +172,8 @@ interface PageNavigationApi {
      */
     pushPage(pageKey: string, query?: Record<string, unknown>): void;
     replacePage(pageKey: string, query?: Record<string, unknown>): void;
+    pushRoute(route: string, query?: Record<string, unknown>): void;
+    replaceRoute(route: string, query?: Record<string, unknown>): void;
     updateQuery(query: Record<string, unknown>): void;
     setHash(hash: string): void;
     back(): void;
@@ -856,4 +866,4 @@ declare const usePageRoute: () => PageRouteInfo;
 
 declare const usePageSdk: () => PageSdk;
 
-export { type ApiPermissionListParams, type ApproveTaskParams, type AssignPermissionsParams, type AssignRolesParams, type BatchAddUsersToRoleParams, type BatchSendNotificationByTypeParams, type ChangeUserRoleParams, type ConnectorCallParams, type ConnectorInvokeParams, type ConnectorInvokeResult, type ConnectorRequestBodyType, type ConnectorResponseType, type CreateApiPermissionParams, type CreateFormPermissionGroupDto, type CreatePagePermissionGroupDto, type CreateRoleParams, type CreateUiPermissionParams, type CreateUserParams, type CurrentUserDepartmentParents, type DataManagementConfigParams, type DataManagementFilterState, type DataPermissionConditionDto, type DataPermissionDto, type DataPermissionRuleDto, type FieldPermissionDto, type FormAdvancedSearchParams, type FormChangeRecordParams, type FormCreateParams, type FormExportParams, type FormGetDetailParams, type FormImportParams, type FormPermissionGroup, type FormRemoveParams, type FormSearchParams, type FormUpdateParams, type GetParentDepartmentsOptions, type GetProcessInstanceParams, type GetUserRolesParams, type ImportExportRecordDownloadParams, type ImportExportRecordQuery, type InstanceStatus, type NotificationChannel, type NotificationMessageRecord, type PageApiPermissionRecord, type PageApiResponse, type PageAppInfo, type PageBinaryResponse, type PageBridgeApi, type PageContext, type PageDataManagementConfig, type PageDataSourceDescriptor, type PageDepartmentInfo, type PageDepartmentRecord, type PageHttpMethod, type PageInfo, type PageListResult, type PageMessageApi, type PageModalApi, type PageNavigationApi, type PageOffsetListResult, type PagePermissionGroup, type PagePermissionInfo, PageProvider, type PageQueryValue, type PageRequestOptions, type PageRoleRecord, type PageRouteInfo, type PageScope, type PageSdk, type PageSdkError, type PageSdkMeta, type PageTransportDownloadPayload, type PageTransportRequestPayload, type PageUiPermissionRecord, type PageUiPermissionType, type PageUserInfo, type PageUserRecord, type PageUserType, type ProcessApproveAction, type QueryFormPermissionGroupDto, type QueryPagePermissionGroupDto, type RoleListParams, type RoleUsersParams, type SaveDataManagementConfigParams, type SearchComponentName, type SearchExpression, type SearchFieldKey, type SearchGroup, type SearchLogic, type SearchOperator, type SearchRule, type SearchSortItem, type SearchSystemField, type SendNotificationByTypeParams, type SendNotificationResult, type SubFormRule, type SwitchAppRoleParams, type SwitchPlatformRoleParams, type TerminateProcessInstanceParams, type TriggerCallbackTaskParams, type UiPermissionListParams, type UpdateApiPermissionParams, type UpdateFormPermissionGroupDto, type UpdatePagePermissionGroupDto, type UpdateRoleParams, type UpdateUiPermissionParams, type UpdateUserParams, type UserListParams, type UserMenuPermissionsResponse, type ValidateUserParams, type ViewFieldPermissionValue, type ViewOperationPermission, type ViewPermissionSummary, createPageSdk, createReactPage, useCurrentUser, useDataSource, useFormViewPermissions, useMessage, useModal, useNavigation, usePageContext, usePageProps, usePageRoute, usePageSdk };
+export { type ApiPermissionListParams, type ApproveTaskParams, type AssignPermissionsParams, type AssignRolesParams, type BatchAddUsersToRoleParams, type BatchSendNotificationByTypeParams, type ChangeUserRoleParams, type ConnectorCallParams, type ConnectorInvokeParams, type ConnectorInvokeResult, type ConnectorRequestBodyType, type ConnectorResponseType, type CreateApiPermissionParams, type CreateFormPermissionGroupDto, type CreatePagePermissionGroupDto, type CreateRoleParams, type CreateUiPermissionParams, type CreateUserParams, type CurrentUserDepartmentParents, type CustomPageEntryConfig, type CustomPageEntryMode, type DataManagementConfigParams, type DataManagementFilterState, type DataPermissionConditionDto, type DataPermissionDto, type DataPermissionRuleDto, type FieldPermissionDto, type FormAdvancedSearchParams, type FormChangeRecordParams, type FormCreateParams, type FormExportParams, type FormGetDetailParams, type FormImportParams, type FormPermissionGroup, type FormRemoveParams, type FormSearchParams, type FormUpdateParams, type GetParentDepartmentsOptions, type GetProcessInstanceParams, type GetUserRolesParams, type ImportExportRecordDownloadParams, type ImportExportRecordQuery, type InstanceStatus, type NotificationChannel, type NotificationMessageRecord, type PageApiPermissionRecord, type PageApiResponse, type PageAppInfo, type PageBinaryResponse, type PageBridgeApi, type PageContext, type PageDataManagementConfig, type PageDataSourceDescriptor, type PageDepartmentInfo, type PageDepartmentRecord, type PageHttpMethod, type PageInfo, type PageListResult, type PageMessageApi, type PageModalApi, type PageNavigationApi, type PageOffsetListResult, type PagePermissionGroup, type PagePermissionInfo, PageProvider, type PageQueryValue, type PageRequestOptions, type PageRoleRecord, type PageRouteInfo, type PageScope, type PageSdk, type PageSdkError, type PageSdkMeta, type PageTransportDownloadPayload, type PageTransportRequestPayload, type PageUiPermissionRecord, type PageUiPermissionType, type PageUserInfo, type PageUserRecord, type PageUserType, type ProcessApproveAction, type QueryFormPermissionGroupDto, type QueryPagePermissionGroupDto, type RoleListParams, type RoleUsersParams, type SaveDataManagementConfigParams, type SearchComponentName, type SearchExpression, type SearchFieldKey, type SearchGroup, type SearchLogic, type SearchOperator, type SearchRule, type SearchSortItem, type SearchSystemField, type SendNotificationByTypeParams, type SendNotificationResult, type SubFormRule, type SwitchAppRoleParams, type SwitchPlatformRoleParams, type TerminateProcessInstanceParams, type TriggerCallbackTaskParams, type UiPermissionListParams, type UpdateApiPermissionParams, type UpdateFormPermissionGroupDto, type UpdatePagePermissionGroupDto, type UpdateRoleParams, type UpdateUiPermissionParams, type UpdateUserParams, type UserListParams, type UserMenuPermissionsResponse, type ValidateUserParams, type ViewFieldPermissionValue, type ViewOperationPermission, type ViewPermissionSummary, createPageSdk, createReactPage, useCurrentUser, useDataSource, useFormViewPermissions, useMessage, useModal, useNavigation, usePageContext, usePageProps, usePageRoute, usePageSdk };

package/packages/sdk/src/build-source/scripts/utils/register-payload.mjs

@@ -66,6 +66,7 @@ export function buildDirectPagePublishPayload(config, pages) {
         code: page.config.code,
         name: page.config.name,
         description: page.config.description || "",
+        entry: page.config.entry || {},
         route: page.config.route,
         props: page.config.props || {},
         dataSources: page.config.dataSources || [],

package/packages/sdk/src/build-source/scripts/utils/register-payload.test.ts

@@ -1,7 +1,9 @@
-import { describe, expect, it } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { describe, expect, it, vi } from "vitest";
 
 import { getFormBundleUrl, getPageAssetUrl } from "./load-config.mjs";
-import { discoverPages } from "./pages.mjs";
 import { buildDirectPagePublishPayload } from "./register-payload.mjs";
 
 const config = {
@@ -25,10 +27,47 @@ const config = {
 
 describe("register payload helpers", () => {
   it("discovers publishable code pages", async () => {
-    const pages = await discoverPages("customer-dashboard");
+    const workspaceRoot = await mkdtemp(
+      join(process.cwd(), ".tmp-openxiangda-pages-test-"),
+    );
+    const previousWorkspaceRoot = process.env.LOWCODE_WORKSPACE_ROOT;
+
+    try {
+      const pageDir = join(workspaceRoot, "src/pages/customer-dashboard");
+      await mkdir(pageDir, { recursive: true });
+      await writeFile(join(pageDir, "index.tsx"), "export {};\n", "utf8");
+      await writeFile(
+        join(pageDir, "App.tsx"),
+        "export default function App() { return null; }\n",
+        "utf8",
+      );
+      await writeFile(
+        join(pageDir, "page.config.ts"),
+        `export default {
+  code: "customer-dashboard",
+  name: "客户经营看板",
+  route: { pathKey: "customer-dashboard" },
+};
+`,
+        "utf8",
+      );
+
+      process.env.LOWCODE_WORKSPACE_ROOT = workspaceRoot;
+      vi.resetModules();
+      const { discoverPages } = await import("./pages.mjs");
+      const pages = await discoverPages("customer-dashboard");
 
-    expect(pages).toHaveLength(1);
-    expect(pages[0].config.code).toBe("customer-dashboard");
+      expect(pages).toHaveLength(1);
+      expect(pages[0].config.code).toBe("customer-dashboard");
+    } finally {
+      if (previousWorkspaceRoot === undefined) {
+        delete process.env.LOWCODE_WORKSPACE_ROOT;
+      } else {
+        process.env.LOWCODE_WORKSPACE_ROOT = previousWorkspaceRoot;
+      }
+      vi.resetModules();
+      await rm(workspaceRoot, { recursive: true, force: true });
+    }
   });
 
   it("builds stable form and page asset URLs from one build id", () => {
@@ -46,6 +85,11 @@ describe("register payload helpers", () => {
         config: {
           code: "customer-dashboard",
           name: "客户经营看板",
+          entry: {
+            mode: "app-shell",
+            hidePlatformNav: true,
+            defaultRoute: "home",
+          },
           route: { pathKey: "customer-dashboard" },
           props: { title: "客户经营看板" },
           dataSources: [],
@@ -56,6 +100,11 @@ describe("register payload helpers", () => {
     expect(payload.pages[0].runtime.entryUrl).toBe(
       "https://bucket.oss-cn-hangzhou.aliyuncs.com/lowcode/app-workspace/dev/1.2.3/BUILD_001/pages/customer-dashboard/index.js",
     );
+    expect(payload.pages[0].entry).toEqual({
+      mode: "app-shell",
+      hidePlatformNav: true,
+      defaultRoute: "home",
+    });
     expect(JSON.stringify(payload)).not.toMatch(/manifest/i);
   });
 

package/templates/sy-lowcode-app-workspace/src/types/app-workspace.types.ts

@@ -26,6 +26,42 @@ export interface AppWorkspaceConfig {
   };
 }
 
+export type CustomPageEntryMode = "app-shell" | "plain-page";
+
+export interface CustomPageEntryConfig {
+  mode?: CustomPageEntryMode | string;
+  hidePlatformNav?: boolean;
+  defaultRoute?: string;
+}
+
+export interface CustomPageConfig {
+  code: string;
+  name: string;
+  description?: string;
+  publish?: boolean;
+  route?: {
+    pathKey?: string;
+    allowQueryKeys?: string[];
+    allowHash?: boolean;
+    subRouteMode?: "hash" | "memory" | string;
+    defaultQuery?: Record<string, unknown>;
+  };
+  entry?: CustomPageEntryConfig;
+  props?: Record<string, unknown>;
+  dataSources?: Array<Record<string, unknown>>;
+  menu?: {
+    enabled?: boolean;
+    name?: string;
+    parentId?: string | null;
+    icon?: string | null;
+  };
+  cssIsolation?: "namespace" | "shadow" | "none";
+}
+
 export function defineAppWorkspaceConfig<T extends AppWorkspaceConfig>(config: T): T {
   return config;
 }
+
+export function definePageConfig<T extends CustomPageConfig>(config: T): T {
+  return config;
+}