@oj-module/cli 0.2.2 → 0.2.6

package/templates/web/src/access/locales/zh-CN.json

@@ -0,0 +1,46 @@
+{
+	"accessMode": {
+		"title": "后端访问权限可见",
+		"description": "当前页面仅支持通过后端接口获取路由可见"
+	},
+	"adminVisible": {
+		"title": "Admin 可见",
+		"description": "当前页面仅 Admin 账号可见"
+	},
+	"commonVisible": {
+		"title": "Common 可见",
+		"description": "当前页面仅 Common 账号可见"
+	},
+	"pageControl": {
+		"alertMessage": "前端页面访问权限演示",
+		"alertDescription": "切换不同的账号，观察左侧「权限演示」子菜单变化。",
+		"cardTitle": "权限模式",
+		"frontendControl": "前端权限控制",
+		"backendControl": "后端权限控制",
+		"switchToFrontend": "切换为前端权限模式",
+		"switchToBackend": "切换为后端权限模式",
+		"switchAdmin": "切换 Admin 用户",
+		"switchCommon": "切换 Common 用户",
+		"currentPermissionMode": "当前权限模式：",
+		"accountSwitching": "账号切换",
+		"warningMessage": "enableFrontendAceess 和 enableBackendAceess 相等时不允许切换路由模式。"
+	},
+	"buttonControl": {
+		"alertMessage": "前端按钮访问权限演示",
+		"alertDescription": "切换不同的账号，观察按钮变化。",
+		"currentRole": "当前角色",
+		"switchAdmin": "切换 Admin 用户",
+		"switchCommon": "切换 Common 用户",
+		"componentControlPermissionCodes": "组件形式控制 - 权限码",
+		"componentControlRoles": "组件形式控制 - 角色",
+		"functionControlPermissionCodes": "函数形式控制 - 权限码",
+		"functionControlRoles": "函数形式控制 - 角色"
+	},
+	"menu": {
+		"access": "权限演示",
+		"pageControl": "页面控制",
+		"buttonControl": "按钮控制",
+		"adminVisible": "Admin 可见",
+		"commonVisible": "Common 可见"
+	}
+}

package/templates/web/src/access/pages/access-mode/index.tsx

@@ -0,0 +1,16 @@
+import { CloudOutlined } from "@ant-design/icons";
+import { Result } from "antd";
+import { useTranslation } from "react-i18next";
+
+export default function AccessMode() {
+	const { t } = useTranslation();
+
+	return (
+		<Result
+			icon={<CloudOutlined />}
+			status="success"
+			title={t("access:accessMode.title")}
+			subTitle={t("access:accessMode.description")}
+		/>
+	);
+}

package/templates/web/src/access/pages/admin-visible/index.tsx

@@ -0,0 +1,16 @@
+import { SmileOutlined } from "@ant-design/icons";
+import { Result } from "antd";
+import { useTranslation } from "react-i18next";
+
+export default function AdminVisible() {
+	const { t } = useTranslation();
+
+	return (
+		<Result
+			icon={<SmileOutlined />}
+			status="success"
+			title={t("access:adminVisible.title")}
+			subTitle={t("access:adminVisible.description")}
+		/>
+	);
+}

package/templates/web/src/access/pages/button-control/index.tsx

@@ -0,0 +1,181 @@
+import type { LoginInfo } from "@oj-module/runtime";
+import { AccessControl, accessControlCodes, AccessControlRoles, BasicContent, useAccess, useAuthStore, useUserStore } from "@oj-module/runtime";
+
+import { Alert, Button, Card, Typography } from "antd";
+import { useTranslation } from "react-i18next";
+import { useNavigate } from "react-router";
+
+const accounts: Record<string, LoginInfo> = {
+	[AccessControlRoles.admin]: {
+		password: "123456789admin",
+		username: AccessControlRoles.admin,
+	},
+	[AccessControlRoles.common]: {
+		password: "123456789admin",
+		username: AccessControlRoles.common,
+	},
+};
+
+export default function ButtonControl() {
+	const { t } = useTranslation();
+	const navigate = useNavigate();
+	const { hasAccessByCodes, hasAccessByRoles } = useAccess();
+	const { roles: userRoles } = useUserStore();
+	const resetAllStores = useAuthStore(state => state.reset);
+	const authLogin = useAuthStore(state => state.login);
+
+	function roleButtonType(role: string) {
+		return userRoles.includes(role) ? "primary" : "default";
+	}
+
+	function changeAccount(role: string) {
+		if (userRoles.includes(role)) {
+			return;
+		}
+
+		const account = accounts[role];
+		resetAllStores();
+		if (account) {
+			authLogin(account).then(() => {
+				navigate(0);
+			});
+		}
+	}
+
+	return (
+		<BasicContent className="flex flex-col gap-4">
+			<Alert title={t("access:buttonControl.alertMessage")} description={t("access:buttonControl.alertDescription")}></Alert>
+			<Card
+				title={(
+					<>
+						{t("access:buttonControl.currentRole")}
+						&nbsp;&nbsp;
+						<Typography.Text mark code>{userRoles}</Typography.Text>
+					</>
+				)}
+			>
+				<div className="flex gap-4">
+					<Button type={roleButtonType(AccessControlRoles.admin)} onClick={() => changeAccount(AccessControlRoles.admin)}>
+						{t("access:buttonControl.switchAdmin")}
+					</Button>
+					<Button type={roleButtonType(AccessControlRoles.common)} onClick={() => changeAccount(AccessControlRoles.common)}>
+						{t("access:buttonControl.switchCommon")}
+					</Button>
+				</div>
+			</Card>
+			<Card title={t("access:buttonControl.componentControlPermissionCodes")}>
+				<div className="flex items-center gap-4">
+					<AccessControl codes={accessControlCodes.get}>
+						<Typography.Text code>
+							{accessControlCodes.get}
+						</Typography.Text>
+					</AccessControl>
+
+					<AccessControl codes={accessControlCodes.update}>
+						<Typography.Text code>
+							{accessControlCodes.update}
+						</Typography.Text>
+					</AccessControl>
+
+					<AccessControl codes={accessControlCodes.delete}>
+						<Typography.Text code>
+							{accessControlCodes.delete}
+						</Typography.Text>
+					</AccessControl>
+
+					<AccessControl codes={accessControlCodes.add}>
+						<Typography.Text code>
+							{accessControlCodes.add}
+						</Typography.Text>
+					</AccessControl>
+				</div>
+			</Card>
+			<Card title={t("access:buttonControl.componentControlRoles")}>
+				<div className="flex items-center gap-4">
+					<AccessControl type="role" codes={[AccessControlRoles.admin, AccessControlRoles.common]}>
+						<Typography.Text code>
+							{t("access:adminVisible.title")}
+							&nbsp;&&nbsp;
+							{t("access:commonVisible.title")}
+						</Typography.Text>
+					</AccessControl>
+
+					<AccessControl type="role" codes={AccessControlRoles.admin}>
+						<Typography.Text code>
+							{t("access:adminVisible.title")}
+						</Typography.Text>
+					</AccessControl>
+
+					<AccessControl type="role" codes={AccessControlRoles.common}>
+						<Typography.Text code>
+							{t("access:commonVisible.title")}
+						</Typography.Text>
+					</AccessControl>
+				</div>
+			</Card>
+			<Card title={t("access:buttonControl.functionControlPermissionCodes")}>
+				<div className="flex items-center gap-4">
+					{
+						hasAccessByCodes(accessControlCodes.get) && (
+							<Typography.Text code>
+								{accessControlCodes.get}
+							</Typography.Text>
+						)
+					}
+
+					{
+						hasAccessByCodes(accessControlCodes.update) && (
+							<Typography.Text code>
+								{accessControlCodes.update}
+							</Typography.Text>
+						)
+					}
+
+					{
+						hasAccessByCodes(accessControlCodes.delete) && (
+							<Typography.Text code>
+								{accessControlCodes.delete}
+							</Typography.Text>
+						)
+					}
+
+					{
+						hasAccessByCodes([accessControlCodes.add]) && (
+							<Typography.Text code>
+								{accessControlCodes.add}
+							</Typography.Text>
+						)
+					}
+
+				</div>
+			</Card>
+			<Card title={t("access:buttonControl.functionControlRoles")}>
+				<div className="flex items-center gap-4">
+					{
+						hasAccessByRoles([AccessControlRoles.admin, AccessControlRoles.common]) && (
+							<Typography.Text code>
+								{t("access:adminVisible.title")}
+								&nbsp;&&nbsp;
+								{t("access:commonVisible.title")}
+							</Typography.Text>
+						)
+					}
+					{
+						hasAccessByRoles([AccessControlRoles.admin]) && (
+							<Typography.Text code>
+								{t("access:adminVisible.title")}
+							</Typography.Text>
+						)
+					}
+					{
+						hasAccessByRoles(AccessControlRoles.common) && (
+							<Typography.Text code>
+								{t("access:commonVisible.title")}
+							</Typography.Text>
+						)
+					}
+				</div>
+			</Card>
+		</BasicContent>
+	);
+}

package/templates/web/src/access/pages/common-visible/index.tsx

@@ -0,0 +1,16 @@
+import { SmileOutlined } from "@ant-design/icons";
+import { Result } from "antd";
+import { useTranslation } from "react-i18next";
+
+export default function CommonVisible() {
+	const { t } = useTranslation();
+
+	return (
+		<Result
+			icon={<SmileOutlined />}
+			status="success"
+			title={t("access:commonVisible.title")}
+			subTitle={t("access:commonVisible.description")}
+		/>
+	);
+}

package/templates/web/src/access/pages/page-control/index.tsx

@@ -0,0 +1,142 @@
+import type { LoginInfo } from "@oj-module/runtime";
+import { AccessControlRoles, BasicContent, useAuthStore, usePreferences, useUserStore } from "@oj-module/runtime";
+
+import { Alert, Button, Card, Typography } from "antd";
+import { clsx } from "clsx";
+import { useTranslation } from "react-i18next";
+import { useNavigate } from "react-router";
+
+const accounts: Record<string, LoginInfo> = {
+	[AccessControlRoles.admin]: {
+		password: "123456789admin",
+		username: AccessControlRoles.admin,
+	},
+	[AccessControlRoles.common]: {
+		password: "123456789admin",
+		username: AccessControlRoles.common,
+	},
+};
+
+export default function PageControl() {
+	const { t } = useTranslation();
+	const navigate = useNavigate();
+	const { enableFrontendAceess, enableBackendAccess, setPreferences } = usePreferences();
+	const { roles: userRoles } = useUserStore();
+	const resetAllStores = useAuthStore(state => state.reset);
+	const authLogin = useAuthStore(state => state.login);
+
+	function roleButtonType(role: string) {
+		return userRoles.includes(role) ? "primary" : "default";
+	}
+
+	function changeAccount(role: string) {
+		if (userRoles.includes(role)) {
+			return;
+		}
+
+		const account = accounts[role];
+		resetAllStores();
+		if (account) {
+			authLogin(account).then(() => {
+				navigate(0);
+			});
+		}
+	}
+
+	async function toggleAccessMode() {
+		if (enableFrontendAceess && !enableBackendAccess) {
+			setPreferences({
+				enableFrontendAceess: false,
+				enableBackendAccess: true,
+			});
+			resetAllStores();
+			authLogin(accounts.admin).then(() => {
+				setTimeout(() => {
+					navigate(0);
+				}, 150);
+			});
+			return;
+		}
+		if (enableBackendAccess && !enableFrontendAceess) {
+			setPreferences({
+				enableFrontendAceess: true,
+				enableBackendAccess: false,
+			});
+			resetAllStores();
+			authLogin(accounts.admin).then(() => {
+				setTimeout(() => {
+					navigate(0);
+				}, 150);
+			});
+			return;
+		}
+		window.$message?.warning(t("access:pageControl.warningMessage"));
+	}
+
+	return (
+		<BasicContent className="flex flex-col gap-4">
+			<Alert type="info" title={t("access:pageControl.alertMessage")} description={t("access:pageControl.alertDescription")}></Alert>
+			<Card title={t("access:pageControl.cardTitle")}>
+				<Alert
+					type="warning"
+					className={clsx(
+						"mb-4",
+						{ hidden: enableFrontendAceess !== enableBackendAccess },
+					)}
+					description={t("access:pageControl.warningMessage")}
+				/>
+				<div className="flex items-center gap-4">
+					{t("access:pageControl.currentPermissionMode")}
+					{enableFrontendAceess
+						? (
+							<Typography.Text code>{t("access:pageControl.frontendControl")}</Typography.Text>
+						)
+						: (
+							""
+						)}
+
+					{enableBackendAccess
+						? (
+							<Typography.Text code>{t("access:pageControl.backendControl")}</Typography.Text>
+						)
+						: (
+							""
+						)}
+
+					{enableBackendAccess
+						? (
+							<Button
+								disabled={enableFrontendAceess === enableBackendAccess}
+								type="primary"
+								onClick={() => toggleAccessMode()}
+							>
+								{t("access:pageControl.switchToFrontend")}
+							</Button>
+						)
+						: null}
+					{enableFrontendAceess
+						? (
+							<Button
+								disabled={enableFrontendAceess === enableBackendAccess}
+								type="primary"
+								onClick={() => toggleAccessMode()}
+							>
+								{t("access:pageControl.switchToBackend")}
+							</Button>
+						)
+						: null}
+				</div>
+			</Card>
+			<Card title={t("access:pageControl.accountSwitching")}>
+				<div className="flex gap-4">
+					<Button type={roleButtonType(AccessControlRoles.admin)} onClick={() => changeAccount(AccessControlRoles.admin)}>
+						{t("access:pageControl.switchAdmin")}
+					</Button>
+					<Button type={roleButtonType(AccessControlRoles.common)} onClick={() => changeAccount(AccessControlRoles.common)}>
+						{t("access:pageControl.switchCommon")}
+					</Button>
+				</div>
+			</Card>
+		</BasicContent>
+	);
+}

package/templates/web/src/demo/__client/api.schemas.ts

@@ -0,0 +1,20 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+// AC-D15：仅供 DEV 校验动态 import，生产构建不进产物
+import { z } from "@oj-module/runtime";
+
+export const schemas = {
+	"demoTodosGet": {
+		query: z.object({
+	"keyword": z.string().optional()
+}),
+		data: z.object({
+	"list": z.array(z.object({
+	"id": z.number(),
+	"title": z.string(),
+	"done": z.boolean()
+})),
+	"total": z.number()
+}),
+	},
+};

package/templates/web/src/demo/__client/api.ts

@@ -0,0 +1,89 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+import { ContractApiError } from "@oj-module/runtime/contract/errors";
+import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
+import type { ModuleContext } from "@oj-module/runtime";
+import type { z } from "@oj-module/runtime";
+import type { schemas } from "./api.schemas";
+
+/** oj 信封（AC-D16）：code=0 成功；非 0 时 HTTP status=code，由 toApiError 归一为 ContractApiError */
+interface OjEnvelope<T> { code: number, msg?: string, data?: T }
+
+let req: ScopedRequestLike | undefined;
+
+/** 线上 API 前缀（ojm api 从契约抽取，唯一真源，勿手改）：请求基址 + 前缀登记用 */
+export const API_PREFIX = "/demo";
+
+/** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
+export const MODULE_PREFIX = "/demo";
+
+/**
+ * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
+ * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
+ * 重复构造幂等安全（前缀重复登记同值、request 重绑同值）。
+ */
+export function createDemoClient(ctx: ModuleContext) {
+	// 跨模块认领护栏（DEV）：工厂知道自己该属于谁（MODULE_PREFIX = 契约 apiPrefix），
+	// ctx 又带 module.name——名实不符说明别的模块在替本模块创建 client，会共享 request
+	// 单槽、卸载互相耦合；跨模块需求应由本模块创建后经 provider 暴露。
+	// 注意对比基准是 MODULE_PREFIX（目录名）而非 API_PREFIX——D-M8 映射时线上前缀
+	// 属于别的命名空间，认领身份仍按目录名。
+	if (import.meta.env.DEV && ctx.module.name !== MODULE_PREFIX.slice(1)) {
+		console.warn(`[ojm-api] 模块 "${ctx.module.name}" 正在认领 ${MODULE_PREFIX} 的 client——跨模块认领会共享 request 单槽、卸载互相耦合；应由 "${MODULE_PREFIX.slice(1)}" 模块在自身 onInit 创建，跨模块需求经 provider 暴露。`);
+	}
+	ctx.register.apiPrefix(API_PREFIX);
+	bindRequest(ctx.utils.request);
+	return { demoTodosGet };
+}
+
+/**
+ * @deprecated 请改用 createDemoClient(ctx)——工厂构造即完成
+ * 前缀登记 + request 绑定，不会出现「登记了前缀没绑 request」的半接线状态。
+ */
+export function bindRequest(r: ScopedRequestLike): void {
+	req = r;
+}
+
+function ensureReq(): ScopedRequestLike {
+	if (!req)
+		throw new ContractApiError(-1, "[ojm-api] 请求未绑定——请在模块 entry.ts 的 onInit 里调用 createDemoClient(ctx)（或 bindRequest(ctx.utils.request)）。");
+	return req;
+}
+
+/** ky HTTPError → ContractApiError（错误体为信封时取 code/msg）；契约违例与原错误原样透传 */
+async function toApiError(e: unknown): Promise<unknown> {
+	if (e instanceof ContractApiError)
+		return e;
+	// ky 2.x 构造 HTTPError 时已用 getReader() 消费掉原 response 体（res.clone().json() 按规范抛 TypeError，
+	// 体方法一律失效），解析好的错误体在公开字段 error.data——故读 error.data，勿改回 clone().json()。
+	const err = e as { data?: { code?: unknown, msg?: string }, response?: Response } | null;
+	const res = err?.response;
+	const d = err?.data;
+	if (res instanceof Response && d && typeof d.code === "number")
+		return new ContractApiError(d.code, d.msg ?? res.statusText);
+	return e;
+}
+
+export type DemoTodosGetQuery = z.input<(typeof schemas)["demoTodosGet"]["query"]>;
+export type DemoTodosGetData = z.infer<(typeof schemas)["demoTodosGet"]["data"]>;
+
+export async function demoTodosGet(query: DemoTodosGetQuery): Promise<DemoTodosGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`demo/todos`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<DemoTodosGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as DemoTodosGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["demoTodosGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] demoTodosGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}

package/templates/web/src/exception/entry.ts

@@ -0,0 +1,80 @@
+import type { AppRouteRecordRaw, ModuleDefinition } from "@oj-module/runtime";
+import {
+	AppstoreOutlined,
+	IssuesCloseOutlined,
+	MinusSquareOutlined,
+	StopOutlined,
+} from "@ant-design/icons";
+
+import { ServerErrorIcon } from "@oj-module/runtime";
+import { createElement, lazy } from "react";
+
+const exceptionPath = "/exception";
+const exception403Path = "/exception/403";
+const exception404Path = "/exception/404";
+const exception500Path = "/exception/500";
+const exceptionUnknownComponentPath = "/exception/not-found-component";
+
+const Exception403 = lazy(() => import("./pages/403"));
+const Exception404 = lazy(() => import("./pages/404"));
+const Exception500 = lazy(() => import("./pages/500"));
+const ExceptionUnknownComponent = lazy(() => import("./pages/unknown-component"));
+
+const routes: AppRouteRecordRaw[] = [
+	{
+		path: exceptionPath,
+		handle: {
+			layout: "container",
+			order: 90,
+			title: "exception:menu.exception",
+			icon: createElement(IssuesCloseOutlined),
+		},
+		children: [
+			{
+				path: exception403Path,
+				Component: Exception403,
+				handle: {
+					title: "exception:menu.exception_403",
+					icon: createElement(StopOutlined),
+				},
+			},
+			{
+				path: exception404Path,
+				Component: Exception404,
+				handle: {
+					title: "exception:menu.exception_404",
+					icon: createElement(MinusSquareOutlined),
+				},
+			},
+			{
+				path: exception500Path,
+				Component: Exception500,
+				handle: {
+					title: "exception:menu.exception_500",
+					icon: createElement(ServerErrorIcon),
+				},
+			},
+			{
+				path: exceptionUnknownComponentPath,
+				Component: ExceptionUnknownComponent,
+				handle: {
+					title: "exception:menu.exceptionUnknownComponent",
+					icon: createElement(AppstoreOutlined),
+				},
+			},
+		],
+	},
+];
+
+const mod: ModuleDefinition = {
+	name: "exception",
+	description: "异常页面模块",
+	version: "1.0.0",
+	routes,
+	i18n: {
+		"zh-CN": () => import("./locales/zh-CN.json"),
+		"en-US": () => import("./locales/en-US.json"),
+	},
+};
+
+export default mod;

package/templates/web/src/exception/locales/en-US.json

@@ -0,0 +1,13 @@
+{
+	"404SubTitle": "Sorry, the page you visited does not exist.",
+	"403SubTitle": "Sorry, you are not authorized to access this page.",
+	"500SubTitle": "Sorry, the server is reporting an error.",
+	"unknownComponentSubTitle": "Sorry, the current route has no corresponding component, please contact the developer.",
+	"menu": {
+		"exception": "Exception Page",
+		"exception_403": "403",
+		"exception_404": "404",
+		"exception_500": "500",
+		"exceptionUnknownComponent": "Unknown Component"
+	}
+}

package/templates/web/src/exception/locales/zh-CN.json

@@ -0,0 +1,13 @@
+{
+	"404SubTitle": "抱歉，您访问的页面不存在。",
+	"403SubTitle": "抱歉，您没有权限访问这个页面。",
+	"500SubTitle": "抱歉，服务器出错了。",
+	"unknownComponentSubTitle": "抱歉，当前路由没有对应的组件，请联系开发人员。",
+	"menu": {
+		"exception": "异常页面",
+		"exception_403": "403",
+		"exception_404": "404",
+		"exception_500": "500",
+		"exceptionUnknownComponent": "未知组件"
+	}
+}

package/templates/web/src/exception/pages/403/index.tsx

@@ -0,0 +1,30 @@
+import { ArrowLeftOutlined } from "@ant-design/icons";
+import { Button, Result } from "antd";
+import { useTranslation } from "react-i18next";
+import { useNavigate } from "react-router";
+
+export default function Exception403() {
+	const { t } = useTranslation();
+	const navigate = useNavigate();
+
+	const Result403 = (
+		<Result
+			status="403"
+			title="403"
+			subTitle={t("exception:403SubTitle")}
+			extra={(
+				<Button
+					icon={<ArrowLeftOutlined />}
+					type="primary"
+					onClick={() => {
+						navigate(import.meta.env.VITE_BASE_HOME_PATH);
+					}}
+				>
+					{t("common.backHome")}
+				</Button>
+			)}
+		/>
+	);
+
+	return Result403;
+}