@oj-module/runtime 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 CondorHero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @oj-module/runtime
+
+框架运行时。模块工程**唯一**应该 import 的框架入口。
+
+## 定位
+
+| | |
+|---|---|
+| 消费者 | 模块工程（`entry.ts` 与页面代码）、宿主（`@oj-module/cli` 内置 `shell-dist`） |
+| 产物 | `dist/runtime.js`（单文件 ESM）。`dist/runtime.d.ts` 尚未产出，类型出口在 P3 随出口冻结一起收敛 |
+| 加载方式 | 由宿主 importmap 映射为 `/assets/runtime.js`，全站唯一实例（单例，见设计文档 D5） |
+
+产物只保留**相对路径**代码；所有裸说明符（`react` / `antd` / `react-router` …）都被 external，交给宿主 importmap 解析。这是单例的实现前提——模块与宿主 import 到的是同一个 URL，因而是同一份实例。
+
+## 安装
+
+模块工程把它放在 `devDependencies`（仅用于类型检查与 IDE 跳转），运行期由宿主提供：
+
+```jsonc
+{
+  "devDependencies": {
+    "@oj-module/runtime": "^x.y.z"
+  }
+}
+```
+
+## 对外出口
+
+出口在 `src/index.ts` 收敛，当前为最小集合（P3 阶段依据实际用量冻结）：
+
+```ts
+// 模块契约
+import type {
+  AppRouteRecordRaw,
+  ModuleDefinition,
+  RouteMeta,
+} from "@oj-module/runtime";
+import {
+  BasicContent,
+  defineModule,
+} from "@oj-module/runtime";
+
+// 宿主侧模块加载（模块工程一般不需要）
+import {
+  getModule,
+  getModules,
+  getRegisteredApiPrefix,
+  getRegisteredStore,
+  getRoutes,
+  loadAll,
+} from "@oj-module/runtime";
+```
+
+> `antd`、`react`、`react-router`、`@tanstack/react-query` 等共享依赖**不从 runtime 转出**。模块请直接 import 这些包，由 importmap 命中宿主提供的同一份实例。
+
+## 模块定义示例
+
+```ts
+import type { AppRouteRecordRaw, ModuleDefinition } from "@oj-module/runtime";
+import { defineModule } from "@oj-module/runtime";
+import { lazy } from "react";
+
+const routes: AppRouteRecordRaw[] = [
+  {
+    path: "/demo",
+    Component: lazy(() => import("./pages/demo")),
+    handle: {
+      title: "demo:menu.demo",
+      // 布局语义：container（默认）| parent | none
+      layout: "container",
+    },
+  },
+];
+
+export default defineModule({
+  name: "demo",
+  description: "示例模块",
+  version: "1.0.0",
+  routes,
+  i18n: {
+    "zh-CN": () => import("./locales/zh-CN.json"),
+    "en-US": () => import("./locales/en-US.json"),
+  },
+} satisfies ModuleDefinition);
+```
+
+## 内置能力（非出口，但影响模块行为）
+
+- **路由级缓存**：KeepAlive 位于宿主固定层，缓存开关由各模块路由的 `handle.keepAlive` 汇总得出，不依赖任何具体布局组件是否存在。
+- **布局语义**：`handle.layout` 决定该路由用哪层布局包裹（`container` / `parent` / `none`）。迁移期未声明时按 `container` 处理，保持既有行为。
+- **兜底页**：`NotFound`（404）与 `UnknownComponent`（后端下发路由找不到前端组件）由框架内置，模块无需提供；需要自定义时用自己的路由覆盖。
+
+## 构建
+
+```bash
+# 只出 JS（shell 构建链路走这条，当前唯一可用的构建）
+pnpm --filter @oj-module/runtime exec vite build
+
+# vite build + tsc 出 d.ts + 重写 d.ts 里的 #src/* 说明符
+# ⚠️ 目前 tsc 声明阶段仍有 3 处 declaration-emit 报错，属 P3 待办
+pnpm --filter @oj-module/runtime build
+```
+
+`dist/` 是**随仓库分发的预置产物**（`.gitignore` 中已显式放行），改动 runtime 源码后需要重新构建并提交。
+
+## 目录约定
+
+```
+packages/runtime/src/
+├── index.ts          # 唯一对外出口
+├── components/       # 框架组件（含 not-found / unknown-component 兜底页）
+├── layout/           # 布局与 keep-alive-layer（宿主固定层）
+├── module-loader/    # 模块加载、拓扑排序、生命周期、i18n 合并
+├── router/           # 路由类型、工具、核心路由表
+├── locales/          # 框架文案（模块文案由模块自带）
+└── store/            # 框架状态
+```
+
+内部引用统一走 `#src/*` 子路径 imports；**禁止**出现 `#modules/*`（框架不得反向依赖业务模块，CI 有卡口）。

package/dist/api/notifications/index.d.ts

@@ -0,0 +1,2 @@
+import type { NotificationItem } from "../../layout/widgets/notification/types";
+export declare function fetchNotifications(): Promise<NotificationItem[]>;

package/dist/api/system/menu/index.d.ts

@@ -0,0 +1,6 @@
+import type { MenuItemType } from "./types";
+export * from "./types";
+export declare function fetchMenuList(data: any): Promise<ListData<MenuItemType>>;
+export declare function fetchAddMenuItem(data: MenuItemType): Promise<string>;
+export declare function fetchUpdateMenuItem(data: MenuItemType): Promise<string>;
+export declare function fetchDeleteMenuItem(id: number): Promise<string>;

package/dist/api/system/menu/types.d.ts

@@ -0,0 +1,19 @@
+export interface MenuItemType {
+    parentId: string;
+    id: number;
+    menuType: 0 | 1 | 2 | 3;
+    name: string;
+    path: string;
+    component: string;
+    order: number;
+    icon: string;
+    currentActiveMenu: string;
+    iframeLink: string;
+    keepAlive: number;
+    externalLink: string;
+    hideInMenu: number;
+    ignoreAccess: number;
+    status: 1;
+    createTime: number;
+    updateTime: number;
+}

package/dist/api/system/role/api/client.d.ts

@@ -0,0 +1,19 @@
+import type { z } from "zod";
+import type { schemas } from "./client.schemas";
+export type FetchAddRoleItemBody = z.input<(typeof schemas)["fetchAddRoleItem"]["body"]>;
+export type FetchAddRoleItemData = z.infer<(typeof schemas)["fetchAddRoleItem"]["data"]>;
+export declare function fetchAddRoleItem(body: FetchAddRoleItemBody): Promise<FetchAddRoleItemData>;
+export type FetchDeleteRoleItemBody = z.input<(typeof schemas)["fetchDeleteRoleItem"]["body"]>;
+export type FetchDeleteRoleItemData = z.infer<(typeof schemas)["fetchDeleteRoleItem"]["data"]>;
+export declare function fetchDeleteRoleItem(body: FetchDeleteRoleItemBody): Promise<FetchDeleteRoleItemData>;
+export type FetchMenuByRoleIdQuery = z.input<(typeof schemas)["fetchMenuByRoleId"]["query"]>;
+export type FetchMenuByRoleIdData = z.infer<(typeof schemas)["fetchMenuByRoleId"]["data"]>;
+export declare function fetchMenuByRoleId(query: FetchMenuByRoleIdQuery): Promise<FetchMenuByRoleIdData>;
+export type FetchRoleListQuery = z.input<(typeof schemas)["fetchRoleList"]["query"]>;
+export type FetchRoleListData = z.infer<(typeof schemas)["fetchRoleList"]["data"]>;
+export declare function fetchRoleList(query: FetchRoleListQuery): Promise<FetchRoleListData>;
+export type FetchRoleMenuData = z.infer<(typeof schemas)["fetchRoleMenu"]["data"]>;
+export declare function fetchRoleMenu(): Promise<FetchRoleMenuData>;
+export type FetchUpdateRoleItemBody = z.input<(typeof schemas)["fetchUpdateRoleItem"]["body"]>;
+export type FetchUpdateRoleItemData = z.infer<(typeof schemas)["fetchUpdateRoleItem"]["data"]>;
+export declare function fetchUpdateRoleItem(body: FetchUpdateRoleItemBody): Promise<FetchUpdateRoleItemData>;

package/dist/api/system/role/api/client.schemas.d.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+export declare const schemas: {
+    fetchAddRoleItem: {
+        body: z.ZodObject<{
+            id: z.ZodOptional<z.ZodNumber>;
+            name: z.ZodString;
+            code: z.ZodString;
+            status: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<0>]>;
+            remark: z.ZodOptional<z.ZodString>;
+            menus: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>;
+        data: z.ZodObject<{
+            id: z.ZodOptional<z.ZodNumber>;
+            name: z.ZodString;
+            code: z.ZodString;
+            status: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<0>]>;
+            remark: z.ZodOptional<z.ZodString>;
+            menus: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>;
+    };
+    fetchDeleteRoleItem: {
+        body: z.ZodNumber;
+        data: z.ZodNumber;
+    };
+    fetchMenuByRoleId: {
+        query: z.ZodObject<{
+            id: z.ZodNumber;
+        }, z.core.$strip>;
+        data: z.ZodArray<z.ZodNumber>;
+    };
+    fetchRoleList: {
+        query: z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            code: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<0>]>>;
+            current: z.ZodOptional<z.ZodNumber>;
+            pageSize: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        data: z.ZodObject<{
+            list: z.ZodArray<z.ZodObject<{
+                id: z.ZodNumber;
+                createTime: z.ZodNumber;
+                updateTime: z.ZodNumber;
+                name: z.ZodString;
+                code: z.ZodString;
+                status: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<0>]>;
+                remark: z.ZodString;
+            }, z.core.$strip>>;
+            total: z.ZodNumber;
+            pageSize: z.ZodNumber;
+            current: z.ZodNumber;
+        }, z.core.$strip>;
+    };
+    fetchRoleMenu: {
+        data: z.ZodArray<z.ZodObject<{
+            parentId: z.ZodString;
+            id: z.ZodNumber;
+            menuType: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+            name: z.ZodString;
+            path: z.ZodString;
+            component: z.ZodString;
+            order: z.ZodNumber;
+            icon: z.ZodString;
+            currentActiveMenu: z.ZodString;
+            iframeLink: z.ZodString;
+            keepAlive: z.ZodNumber;
+            externalLink: z.ZodString;
+            hideInMenu: z.ZodNumber;
+            ignoreAccess: z.ZodNumber;
+            permission: z.ZodString;
+            status: z.ZodNumber;
+            createTime: z.ZodNumber;
+            updateTime: z.ZodNumber;
+        }, z.core.$strip>>;
+    };
+    fetchUpdateRoleItem: {
+        body: z.ZodObject<{
+            id: z.ZodOptional<z.ZodNumber>;
+            name: z.ZodString;
+            code: z.ZodString;
+            status: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<0>]>;
+            remark: z.ZodOptional<z.ZodString>;
+            menus: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>;
+        data: z.ZodObject<{
+            id: z.ZodOptional<z.ZodNumber>;
+            name: z.ZodString;
+            code: z.ZodString;
+            status: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<0>]>;
+            remark: z.ZodOptional<z.ZodString>;
+            menus: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>;
+    };
+};

package/dist/api/system/role/index.d.ts

@@ -0,0 +1,9 @@
+import type { FetchAddRoleItemBody, FetchAddRoleItemData, FetchDeleteRoleItemBody, FetchDeleteRoleItemData, FetchMenuByRoleIdData, FetchMenuByRoleIdQuery, FetchRoleListData, FetchRoleListQuery, FetchRoleMenuData, FetchUpdateRoleItemBody, FetchUpdateRoleItemData } from "./api/client";
+export declare function fetchRoleList(query: FetchRoleListQuery): Promise<FetchRoleListData>;
+export declare function fetchAddRoleItem(body: FetchAddRoleItemBody): Promise<FetchAddRoleItemData>;
+export declare function fetchUpdateRoleItem(body: FetchUpdateRoleItemBody): Promise<FetchUpdateRoleItemData>;
+export declare function fetchDeleteRoleItem(body: FetchDeleteRoleItemBody): Promise<FetchDeleteRoleItemData>;
+export declare function fetchRoleMenu(): Promise<FetchRoleMenuData>;
+export declare function fetchMenuByRoleId(query: FetchMenuByRoleIdQuery): Promise<FetchMenuByRoleIdData>;
+export { fetchAddMenuItem, fetchDeleteMenuItem, fetchMenuList, fetchUpdateMenuItem, } from "../menu";
+export * from "./types";

package/dist/api/system/role/types.d.ts

@@ -0,0 +1,9 @@
+export interface RoleItemType {
+    id: number;
+    createTime: number;
+    updateTime: number;
+    name: string;
+    code: string;
+    status: 1 | 0;
+    remark: string;
+}

package/dist/api/user/index.d.ts

@@ -0,0 +1,12 @@
+import type { AppRouteRecordRaw } from "../../router/types";
+import type { AuthType, LoginInfo, UserInfoType } from "./types";
+export * from "./types";
+export declare function fetchLogin(data: LoginInfo): Promise<AuthType>;
+export declare function fetchLogout(data?: {
+    readonly refreshToken?: string;
+}): Promise<void>;
+export declare function fetchAsyncRoutes(): Promise<AppRouteRecordRaw[]>;
+export declare function fetchUserInfo(): Promise<UserInfoType>;
+export declare function fetchRefreshToken(data: {
+    readonly refreshToken: string;
+}): Promise<AuthType>;

package/dist/api/user/types.d.ts

@@ -0,0 +1,26 @@
+import type { AppRouteRecordRaw } from "../../router/types";
+export interface AuthType {
+    token: string;
+    refreshToken: string;
+}
+export interface LoginInfo {
+    username: string;
+    password: string;
+}
+export interface UserInfoType {
+    id: string;
+    avatar: string;
+    username: string;
+    email: string;
+    phoneNumber: string;
+    description: string;
+    roles: Array<string>;
+    /** 权限码列表（后端下发；模块级 requiredPermissions 门禁消费，P7.12） */
+    permissions?: Array<string>;
+    menus?: AppRouteRecordRaw[];
+}
+export interface AuthListProps {
+    label: string;
+    name: string;
+    auth: string[];
+}

package/dist/components/access-control/index.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+interface AccessControlProps {
+    type?: "code" | "role";
+    codes?: string | string[];
+    children?: ReactNode;
+    fallback?: ReactNode;
+}
+/**
+ * 权限验证组件
+ *
+ * @param AccessControlProps 权限验证组件的属性
+ * @returns 若子组件存在，并且传入的权限值有效，则返回子组件；否则返回 null
+ */
+export declare function AccessControl({ type, codes, children, fallback }: AccessControlProps): ReactNode;
+export {};

package/dist/components/basic-button/index.d.ts

@@ -0,0 +1,7 @@
+import type { ButtonProps } from "antd";
+import type { ReactNode } from "react";
+interface BasicButtonProps extends ButtonProps {
+    children?: ReactNode;
+}
+export declare function BasicButton(props: BasicButtonProps): import("#node_modules/@types/react").JSX.Element;
+export {};

package/dist/components/basic-content/index.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    style?: React.CSSProperties;
+    className?: string;
+    children: React.ReactNode;
+}
+export declare function BasicContent(props: Props): import("#node_modules/@types/react").JSX.Element;
+export {};

package/dist/components/basic-form/form-items/form-avatar-item.d.ts

@@ -0,0 +1,6 @@
+interface FormAvatarItemProps {
+    value?: string;
+    onChange?: (value: any) => void;
+}
+export declare function FormAvatarItem({ value, onChange }: FormAvatarItemProps): import("#node_modules/@types/react").JSX.Element;
+export {};

package/dist/components/basic-form/form-items/form-tree-item.d.ts

@@ -0,0 +1,13 @@
+import type { BasicDataNode } from "antd/lib/tree";
+export interface TreeDataNodeWithId extends BasicDataNode {
+    id: string;
+    title: string;
+    children: TreeDataNodeWithId[];
+}
+interface FormTreeItemProps {
+    treeData: TreeDataNodeWithId[];
+    value?: React.Key[];
+    onChange?: (value: React.Key[]) => void;
+}
+export declare function FormTreeItem({ treeData, value, onChange }: FormTreeItemProps): import("#node_modules/@types/react").JSX.Element;
+export {};

package/dist/components/basic-form/form-items/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./form-avatar-item";
+export * from "./form-tree-item";

package/dist/components/basic-form/index.d.ts

@@ -0,0 +1 @@
+export * from "./form-items";

package/dist/components/basic-table/constants.d.ts

@@ -0,0 +1 @@
+export declare const BASIC_TABLE_ROOT_CLASS_NAME = "basic-table";

package/dist/components/basic-table/index.d.ts

@@ -0,0 +1,12 @@
+import type { ParamsType, ProTableProps } from "@ant-design/pro-components";
+export interface BasicTableProps<D, U, V> extends ProTableProps<D, U, V> {
+    /**
+     * @description 自适应内容区高度，如果设置了 scroll.y，则不进行自适应
+     * @default false
+     */
+    adaptive?: boolean | {
+        /** 表格距离页面底部的偏移量，默认值为 `16` */
+        offsetBottom?: number;
+    };
+}
+export declare function BasicTable<DataType extends Record<string, any>, Params extends ParamsType = ParamsType, ValueType = "text">(props: BasicTableProps<DataType, Params, ValueType>): import("#node_modules/@types/react").JSX.Element;

package/dist/components/basic-table/styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 显式标注返回的 classes 形状（P3.1 / TS2883，同 P3.5 的 layout-menu、
+ * layout-tabbar 修法）：推断类型会引用 jss 的 Classes（非直接依赖，
+ * 声明不可移植），这里用结构化等价类型 Record<C, string> 替代。
+ */
+export declare const useStyles: (data?: any) => Record<"basicTable", string>;

package/dist/components/exception-page/index.d.ts

@@ -0,0 +1,3 @@
+export default function ExceptionPage({ status }: {
+    status: "403" | "404" | "500";
+}): import("#node_modules/@types/react").JSX.Element;

package/dist/components/fullscreen-button/index.d.ts

@@ -0,0 +1,17 @@
+import type { ButtonProps } from "antd";
+import type { RefObject } from "react";
+export interface FullscreenButtonProps extends Omit<ButtonProps, "target"> {
+    target: HTMLElement | (() => Element) | RefObject<Element>;
+    fullscreenIcon?: React.ReactNode;
+    fullscreenExitIcon?: React.ReactNode;
+}
+/**
+ * 全屏按钮组件
+ *
+ * @param target 全屏目标元素
+ * @param fullscreenIcon 全屏时图标
+ * @param fullscreenExitIcon 退出全屏时图标
+ * @param restProps 其他属性
+ * @returns 返回全屏按钮组件
+ */
+export declare const FullscreenButton: React.FC<FullscreenButtonProps>;

package/dist/components/global-spin/index.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react";
+export interface GlobalSpinProps {
+    className?: string;
+    children: ReactNode;
+}
+export declare function GlobalSpin({ children, className }: GlobalSpinProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("#node_modules/@types/react").ReactPortal | import("#node_modules/@types/react").ReactElement<unknown, string | import("#node_modules/@types/react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("#node_modules/@types/react").JSX.Element | null | undefined;

package/dist/components/iframe/index.d.ts

@@ -0,0 +1 @@
+export declare function Iframe(): import("#node_modules/@types/react").JSX.Element | null;

package/dist/components/jss-theme-provider/index.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+/**
+ * 自定义的JSS主题提供者组件
+ *
+ * @zh 自定义的 JSS 主题提供者组件，用于在 React 应用中提供 JSS 主题
+ * @en Custom JSS theme provider component, used to provide JSS themes in React applications
+ */
+export interface JSSThemeProviderProps {
+    /**
+     * 子组件
+     *
+     * @zh 子组件，该组件将接收JSS主题
+     * @en Children components, which will receive the JSS theme
+     */
+    children: ReactNode;
+}
+/**
+ * JSSThemeProvider 组件
+ *
+ * @zh JSSThemeProvider 组件，用于将 Ant Design 的 token 和全局主题状态传递给子组件
+ * @en JSSThemeProvider component, used to pass Ant Design tokens and global theme state to child components
+ *
+ * @param {JSSThemeProviderProps} props 组件属性
+ * @returns {JSX.Element} 返回的JSX元素
+ */
+export declare function JSSThemeProvider({ children }: JSSThemeProviderProps): import("#node_modules/@types/react").JSX.Element;

package/dist/components/not-found/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @zh 框架内置 404 兜底页。模块可通过自定义 `*` 路由覆盖。
+ * @en Framework built-in 404 fallback. Modules may override it with their own `*` route.
+ */
+export declare function NotFound(): import("#node_modules/@types/react").JSX.Element;
+export default NotFound;

package/dist/components/page-error/index.d.ts

@@ -0,0 +1,2 @@
+import type { FallbackProps } from "react-error-boundary";
+export declare function PageError({ error, resetErrorBoundary }: FallbackProps): import("#node_modules/@types/react").JSX.Element;

package/dist/components/scrollbar/index.d.ts

@@ -0,0 +1,7 @@
+import type { Props as SimplebarProps } from "simplebar-react";
+/**
+ * @see https://github.com/Grsmto/simplebar/tree/master/packages/simplebar-react
+ */
+export declare function Scrollbar({ ref, children, ...other }: SimplebarProps & {
+    ref?: React.RefObject<HTMLElement | null>;
+}): import("#node_modules/@types/react").JSX.Element;

package/dist/components/unknown-component/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @zh 框架内置「路由无对应组件」兜底页，用于后端下发路由找不到前端组件时。
+ * @en Framework built-in fallback for backend routes whose frontend component is missing.
+ */
+export declare function UnknownComponent(): import("#node_modules/@types/react").JSX.Element;
+export default UnknownComponent;

package/dist/constants/options.d.ts

@@ -0,0 +1,9 @@
+import type { TFunction } from "i18next";
+export declare function getYesNoOptions(t: TFunction<"translation", undefined>): {
+    label: string;
+    value: number;
+}[];
+export declare function getBooleanOptions(t: TFunction<"translation", undefined>): {
+    label: string;
+    value: boolean;
+}[];

package/dist/contract/define-api.d.ts

@@ -0,0 +1,43 @@
+import type { z } from "zod";
+/**
+ * AC-D11/AC-D4：契约端点定义。
+ *
+ * route 一律相对 apiPrefix（无 oj 根绝对写法——前端受模块手册 D11 前缀收敛，
+ * 根绝对逃逸语义不放行）；参数段支持 oj matchit 同款 `{id}` 单段与
+ * `{*path}` catch-all，参数段内不得混字面（`{id}.json` 非法）。
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+export interface ApiDefinitionInput {
+    /** 模块 API 前缀（"/" 开头）；uni-dev 形态字面等于 oj 模块段名（AC-D9） */
+    apiPrefix: string;
+    /** 相对 apiPrefix 的路由（"/" 开头），支持 `{id}` / `{*path}` 参数段 */
+    route: string;
+    /** HTTP 方法，缺省 "GET"（IR 层归一） */
+    method?: HttpMethod;
+    /** 查询参数 schema（声明语义类型，URL 序列化由生成物负责） */
+    query?: z.ZodType;
+    /** 路径参数 schema（与 route 参数段一一对应） */
+    params?: z.ZodType;
+    /** 请求体 schema */
+    body?: z.ZodType;
+    /** 响应信封 data 部分的 schema；与 response:"raw" 互斥 */
+    data?: z.ZodType;
+    /** "raw" = 二进制/非信封逃生口：不解包、不校验、不进 mock 生成 */
+    response?: "raw";
+    /** true = 该端点不触发全局加载条（客户端表现层开关，非线协议，不进 OpenAPI） */
+    ignoreLoading?: boolean;
+    /** 接口描述（进 OpenAPI 文档） */
+    description?: string;
+}
+/**
+ * defineApi 产物的品牌标记（Symbol.for 跨模块实例稳定）。
+ * 非枚举属性——不影响 .route 等的可枚举性；codegen 据此可靠识别端点，
+ * 不与契约文件里导出的普通 schema/常量混淆。
+ *
+ * 注：旧标记 `Symbol.for("ram.api.def")` 不在本包公开——只有 cli 的 IR 识别
+ * 存量产物时才需要它，故由 `packages/cli/src/contract/ir.ts` 自行声明（避免把
+ * 兼容专用符号扩进公共出口，设计 §7 R3）。
+ */
+export declare const API_DEF: unique symbol;
+/** 定义一个契约端点：定义期校验后原样返回（描述符 .route 等可枚举，供 codegen/mock 遍历） */
+export declare function defineApi<D extends ApiDefinitionInput>(def: D): D;

package/dist/contract/define-api.js

@@ -0,0 +1,44 @@
+/** oj matchit 同款参数段：整段必须是 {name} 或 {*name}，不得混字面 */
+const PARAM_SEGMENT = /^\{\*?[a-z_]\w*\}$/i;
+function fail(route, reason) {
+    throw new Error(`[契约] 端点定义非法（route: ${route}）：${reason}`);
+}
+function validateDefinition(def) {
+    const { apiPrefix, route } = def;
+    if (!apiPrefix?.startsWith("/")) {
+        throw new Error(`[契约] apiPrefix 必须以 "/" 开头（收到: ${apiPrefix}）——如 "/order"；uni-dev 形态请与 oj 模块段名保持一致（AC-D9）。`);
+    }
+    if (!route?.startsWith("/"))
+        fail(route, `route 必须以 "/" 开头（收到: ${route}），且一律相对 apiPrefix——不支持 oj 的根绝对写法（模块手册 D11 前缀收敛）。`);
+    if (route.split("/").some(seg => seg === ".." || seg === "." || seg === "\\"))
+        fail(route, "route 含路径穿越段（.././\\），请改为正常静态段。");
+    for (const seg of route.split("/")) {
+        if (seg.includes("{") && !PARAM_SEGMENT.test(seg))
+            fail(route, `参数段 "${seg}" 混入字面量——matchit 约束：参数段必须整段为 {name} 或 {*name}，需要前缀/后缀字面时请拆成静态多段。`);
+    }
+    if (def.data && def.response === "raw")
+        fail(route, "data schema 与 response:\"raw\" 互斥——raw 端点不解包信封，不需要 data schema。");
+    if (def.response !== undefined && def.response !== "raw")
+        fail(route, `response 仅支持 "raw"（收到: ${String(def.response)}）。`);
+    // 评审 F9：方法面在定义期封顶，而不是延迟到 codegen 才炸
+    if (def.method === "OPTIONS")
+        fail(route, "OPTIONS 不在支持范围（ky/oj 均无对应方法）——预检请求由 fetch/CORS 层处理，契约不表达。");
+    if (def.method === "HEAD" && def.data)
+        fail(route, "HEAD 端点无响应体，不能声明 data schema——需要响应体请改用 GET。");
+}
+/**
+ * defineApi 产物的品牌标记（Symbol.for 跨模块实例稳定）。
+ * 非枚举属性——不影响 .route 等的可枚举性；codegen 据此可靠识别端点，
+ * 不与契约文件里导出的普通 schema/常量混淆。
+ *
+ * 注：旧标记 `Symbol.for("ram.api.def")` 不在本包公开——只有 cli 的 IR 识别
+ * 存量产物时才需要它，故由 `packages/cli/src/contract/ir.ts` 自行声明（避免把
+ * 兼容专用符号扩进公共出口，设计 §7 R3）。
+ */
+export const API_DEF = Symbol.for("ojm.api.def");
+/** 定义一个契约端点：定义期校验后原样返回（描述符 .route 等可枚举，供 codegen/mock 遍历） */
+export function defineApi(def) {
+    validateDefinition(def);
+    Object.defineProperty(def, API_DEF, { value: true, enumerable: false });
+    return def;
+}

package/dist/contract/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 契约制 client 的统一错误类型（AC-D5/§6.2）。
+ *
+ * 业务错误（非 2xx，oj json.fail(code,msg)）与契约违例（dev 校验失败，
+ * code=-1）都收敛为本类型，消费方可 `instanceof` 判别并取 code/msg。
+ *
+ * 本子路径出口（`@oj-module/runtime/contract/errors`）是**生成 client 在
+ * 浏览器侧的唯一入口**（评审 F3）：刻意 zod-free——zod 只随 runtime dist
+ * 走（AC-D15），不进共享资产。
+ */
+export declare class ContractApiError extends Error {
+    readonly code: number;
+    readonly msg: string;
+    constructor(code: number, msg: string);
+}
+export type { ScopedRequestLike } from "./scoped-request-like.ts";