@oj-module/cli 0.2.2 → 0.2.5

package/templates/web/src/oj-market/pages/MarketApp.tsx

@@ -0,0 +1,136 @@
+import type { IndexRow, TaskRecord } from "../types";
+import { Typography } from "antd";
+import React, { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { useMarketClient } from "../api/context";
+import { CardGrid } from "../components/CardGrid";
+import { DetailDrawer } from "../components/DetailDrawer";
+import { HistoryDrawer } from "../components/HistoryDrawer";
+import { InstallDialog } from "../components/InstallDialog";
+import { RollbackDialog } from "../components/RollbackDialog";
+import { UninstallConfirm } from "../components/UninstallConfirm";
+import { useMarketIndex } from "../hooks/useMarket";
+
+/** 市场应用主页面：组装卡片网格 + 详情/安装/卸载/回滚/历史交互面（单一容器，DRY 编排） */
+export default function MarketApp() {
+	const { t } = useTranslation();
+	const client = useMarketClient();
+	const index = useMarketIndex();
+
+	const [detailRow, setDetailRow] = useState<IndexRow | null>(null);
+	const [installRow, setInstallRow] = useState<IndexRow | null>(null);
+	const [installVersion, setInstallVersion] = useState<string | null>(null);
+	const [installMode, setInstallMode] = useState<"install" | "upgrade" | "rollback">("install");
+	const [uninstallRow, setUninstallRow] = useState<IndexRow | null>(null);
+	const [rollbackRow, setRollbackRow] = useState<IndexRow | null>(null);
+	const [historyRow, setHistoryRow] = useState<IndexRow | null>(null);
+	const [busyName, setBusyName] = useState<string | null>(null);
+
+	const rows = index.status === "ok" ? index.data : [];
+
+	// 安装/升级：目标版本缺省（取 latest）；已装视为升级
+	const handleInstall = (row: IndexRow) => {
+		setDetailRow(null);
+		setInstallRow(row);
+		setInstallVersion(null);
+		setInstallMode(row.installed != null ? "upgrade" : "install");
+	};
+
+	// 回滚：先开版本选择抽屉，选中旧版后转安装（降级安装，显式 version）
+	const handleRollback = (row: IndexRow) => {
+		setDetailRow(null);
+		setRollbackRow(row);
+	};
+
+	const handleRollbackChosen = (row: IndexRow, version: string) => {
+		setRollbackRow(null);
+		setInstallRow(row);
+		setInstallVersion(version);
+		setInstallMode("rollback");
+	};
+
+	const handleEnableToggle = async (row: IndexRow) => {
+		setBusyName(row.name);
+		try {
+			await client.enable({ name: row.name, enabled: row.enabled !== true });
+			index.retry();
+		}
+		finally {
+			setBusyName(null);
+		}
+	};
+
+	const handleUninstallConfirmed = async (row: IndexRow) => {
+		setBusyName(row.name);
+		try {
+			await client.uninstall(row.name);
+			setUninstallRow(null);
+			index.retry();
+		}
+		finally {
+			setBusyName(null);
+		}
+	};
+
+	const handleInstallDone = (_rec: TaskRecord) => {
+		index.retry();
+	};
+
+	return (
+		<div style={{ padding: 24 }} data-testid="market-app">
+			<Typography.Title level={4}>{t("oj-market:card:title")}</Typography.Title>
+			<Typography.Paragraph type="secondary">{t("oj-market:card:subtitle")}</Typography.Paragraph>
+
+			<CardGrid
+				loading={index.status === "loading"}
+				error={index.status === "error" ? index.error : null}
+				rows={rows}
+				busyName={busyName}
+				onInstall={handleInstall}
+				onEnableToggle={handleEnableToggle}
+				onDetails={r => setDetailRow(r)}
+				onHistory={r => setHistoryRow(r)}
+				onUninstall={r => setUninstallRow(r)}
+				onRollback={handleRollback}
+				onRetry={index.retry}
+			/>
+
+			<DetailDrawer
+				row={detailRow}
+				open={detailRow != null}
+				onClose={() => setDetailRow(null)}
+				onInstall={handleInstall}
+				onHistory={(r) => {
+					setDetailRow(null);
+					setHistoryRow(r);
+				}}
+				onRollback={handleRollback}
+			/>
+
+			<InstallDialog
+				row={installRow}
+				open={installRow != null}
+				onClose={() => setInstallRow(null)}
+				onDone={handleInstallDone}
+				version={installVersion}
+				mode={installMode}
+			/>
+
+			<UninstallConfirm
+				row={uninstallRow}
+				open={uninstallRow != null}
+				onClose={() => setUninstallRow(null)}
+				onConfirmed={handleUninstallConfirmed}
+			/>
+
+			<RollbackDialog
+				row={rollbackRow}
+				open={rollbackRow != null}
+				onClose={() => setRollbackRow(null)}
+				onRollback={handleRollbackChosen}
+			/>
+
+			<HistoryDrawer row={historyRow} open={historyRow != null} onClose={() => setHistoryRow(null)} />
+		</div>
+	);
+}

package/templates/web/src/oj-market/types.ts

@@ -0,0 +1,84 @@
+// 市场领域类型（形状对齐宿主 _platform 编排面真源 + 本仓 market_history 表）。
+// 真源：templates/api/src/_platform/_lifecycle/types.ts:47 (TaskRecord) 与 market/api.ts:IndexRow。
+// 任何形状漂移以 templates 源码为准——实现前已核对（2026-10-17）。
+
+/** 安装阶段名（契约附录 A 十阶段逐字 + lock_commit/audit/done 终态） */
+export type InstallStage = "preflight" | "downloading" | "verifying" | "extracting" | "migrating" | "lock_commit" | "registering" | "deploying_web" | "reloading" | "smoke" | "audit" | "done";
+
+/** 任务状态（§10.2 三态 + partial：锁后失败部分生效） */
+export type TaskStatus = "running" | "done" | "failed" | "partial";
+
+/** 阶段明细日志（UI 详情日志区数据源） */
+export interface TaskStageLog {
+	stage: InstallStage
+	ok: boolean
+	message: string
+}
+
+/** 失败/partial 终态：reason + retryable + 指引文案 key（契约附录 A） */
+export interface TaskError {
+	reason: string
+	retryable: boolean
+	hintKey?: string
+}
+
+/** 安装任务记录（§10.2 + stages 明细日志；落 .install-tasks/<id>.json，800ms 轮询消费面） */
+export interface TaskRecord {
+	id: string
+	name: string
+	version: string
+	status: TaskStatus
+	stage: InstallStage | null
+	/** 0-100 整体进度 */
+	progress: number
+	message: string
+	stages: TaskStageLog[]
+	error?: TaskError
+	startedAt: number
+	finishedAt?: number
+	appliedSeq?: number
+}
+
+/** 卡片数据源行（GET /_platform/market/index）：CDN bundles.yaml ⊕ 本地 sidecar state */
+export interface IndexRow {
+	name: string
+	latest: string | null
+	installed: string | null
+	enabled: boolean | null
+	upgradable: boolean
+}
+
+/** 安装输入（POST /_platform/market/install） */
+export interface InstallInput {
+	name: string
+	version?: string | null
+	source?: "cdn" | "file"
+}
+
+/** 启用/停用输入（POST /_platform/market/enable） */
+export interface EnableInput {
+	name: string
+	enabled: boolean
+}
+
+/** 市场操作历史动作 */
+export type HistoryAction = "install" | "uninstall" | "enable" | "disable" | "upgrade" | "rollback";
+
+/** 市场操作历史记录（本仓 market_history 表，只读消费） */
+export interface MarketHistory {
+	id: number
+	solution: string
+	version: string
+	action: HistoryAction
+	status: string
+	operator: string | null
+	message: string | null
+	created_at: number
+}
+
+/** 卸载影响面预检（P3 U1 语义；服务端返回供前端二次确认） */
+export interface UninstallImpact {
+	name: string
+	affectedRoles: number
+	affectedUsers: number
+}

package/templates/web/src/oj-market/utils/poll.ts

@@ -0,0 +1,36 @@
+// 通用轮询工具（§10.2：市场任务 800ms 轮询、退避上限 5s、超时 30min 由调用方配置）。
+// 纯函数、无副作用、可独立单测。
+
+export interface PollOptions {
+	/** 轮询间隔（默认 800ms） */
+	intervalMs?: number
+	/** 整体超时（默认 30min） */
+	timeoutMs?: number
+	/** 中断信号 */
+	signal?: AbortSignal
+}
+
+/**
+ * 反复执行 fn，直到 isDone(value) 为真或超时。
+ * 超时返回最近一次取值（由调用方标记超时态），不抛错——避免轮询中断业务。
+ */
+export async function poll<T>(
+	fn: () => Promise<T>,
+	isDone: (value: T) => boolean,
+	opts: PollOptions = {},
+): Promise<T> {
+	const interval = opts.intervalMs ?? 800;
+	const timeout = opts.timeoutMs ?? 30 * 60 * 1000;
+	const start = Date.now();
+	// 轮询循环：每轮先取最新值，终态即返回，超时则返回当前值
+	for (;;) {
+		if (opts.signal?.aborted)
+			throw new DOMException("aborted", "AbortError");
+		const value = await fn();
+		if (isDone(value))
+			return value;
+		if (Date.now() - start > timeout)
+			return value;
+		await new Promise<void>(resolve => setTimeout(resolve, interval));
+	}
+}

package/templates/web/src/oj-market/utils/semver.ts

@@ -0,0 +1,14 @@
+// 版本比较（镜像 oj-module _lifecycle/semver 的最小口径，前端本地副本——宿主 semver 在
+// 服务端隔离层，前端不可 import；点分/连字符预发布字段逐段数值比）。返回 <0 / 0 / >0。
+// 用途：双版本卡片 upgradable 对比展示 + 回滚候选过滤（候选 = 版本 < 已装版本）。
+export function compareVersions(a: string, b: string): number {
+	const pa = String(a).split(/[.\-]/).map(x => Number.parseInt(x, 10) || 0);
+	const pb = String(b).split(/[.\-]/).map(x => Number.parseInt(x, 10) || 0);
+	const n = Math.max(pa.length, pb.length);
+	for (let i = 0; i < n; i++) {
+		const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+		if (d !== 0)
+			return d < 0 ? -1 : 1;
+	}
+	return 0;
+}

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

@@ -0,0 +1,80 @@
+import type { AppRouteRecordRaw, ModuleDefinition } from "@oj-module/runtime";
+import { AntDesignOutlined, ContainerOutlined } from "@ant-design/icons";
+
+import { EmbeddedIcon, ExternalIcon, Iframe, OutsidePageIcon, RiReactjsLine } from "@oj-module/runtime";
+import { createElement } from "react";
+import { Outlet } from "react-router";
+
+const routes: AppRouteRecordRaw[] = [
+	{
+		path: "/outside",
+		handle: {
+			layout: "container",
+			icon: createElement(OutsidePageIcon),
+			title: "outside:menu.outside",
+			order: 40,
+		},
+		children: [
+			{
+				path: "/outside/embedded",
+				Component: Outlet,
+				handle: {
+					icon: createElement(EmbeddedIcon),
+					title: "outside:menu.embedded",
+				},
+				children: [
+					{
+						path: "/outside/embedded/ant-design",
+						Component: Iframe,
+						handle: {
+							icon: createElement(AntDesignOutlined),
+							title: "outside:menu.antd",
+							iframeLink: "https://ant.design/",
+						},
+					},
+					{
+						path: "/outside/embedded/project-docs",
+						Component: Iframe,
+						handle: {
+							icon: createElement(ContainerOutlined),
+							title: "outside:menu.projectDocs",
+							iframeLink: "https://condorheroblog.github.io/react-antd-admin/docs/",
+						},
+					},
+				],
+			},
+			{
+				path: "/outside/external-link",
+				Component: Outlet,
+				handle: {
+					icon: createElement(ExternalIcon),
+					title: "outside:menu.externalLink",
+				},
+				children: [
+					{
+						path: "/outside/external-link/react-docs",
+						Component: Iframe,
+						handle: {
+							icon: createElement(RiReactjsLine),
+							title: "outside:menu.reactDocs",
+							externalLink: "https://react.dev/",
+						},
+					},
+				],
+			},
+		],
+	},
+];
+
+const mod: ModuleDefinition = {
+	name: "outside",
+	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/outside/locales/en-US.json

@@ -0,0 +1,10 @@
+{
+	"menu": {
+		"outside": "External Page",
+		"embedded": "Embedded",
+		"externalLink": "External Link",
+		"antd": "Ant Design",
+		"projectDocs": "Project Docs",
+		"reactDocs": "React Docs"
+	}
+}

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

@@ -0,0 +1,10 @@
+{
+	"menu": {
+		"outside": "外部页面",
+		"embedded": "内嵌",
+		"externalLink": "外链",
+		"antd": "Ant Design",
+		"projectDocs": "项目文档",
+		"reactDocs": "React 文档"
+	}
+}

package/templates/web/src/personal-center/entry.ts

@@ -1,10 +1,9 @@
 import type { AppRouteRecordRaw, ModuleDefinition, UploadApiProvider } from "@oj-module/runtime";
-import { ProfileCardIcon, RiAccountCircleLine, RiUserSettingsLine, useAuthStore } from "@oj-module/runtime";
+import { ProfileCardIcon, RiAccountCircleLine, useAuthStore } from "@oj-module/runtime";
 
 import { createElement, lazy } from "react";
 
 const MyProfile = lazy(() => import("./pages/my-profile"));
-const Settings = lazy(() => import("./pages/settings"));
 
 const routes: AppRouteRecordRaw[] = [
 	{
@@ -24,14 +23,6 @@ const routes: AppRouteRecordRaw[] = [
 					icon: createElement(ProfileCardIcon),
 				},
 			},
-			{
-				path: "/personal-center/settings",
-				Component: Settings,
-				handle: {
-					title: "personal-center:menu.settings",
-					icon: createElement(RiUserSettingsLine),
-				},
-			},
 		],
 	},
 ];

package/templates/web/src/personal-center/locales/en-US.json

@@ -1,10 +1,6 @@
 {
-	"accountSecurity": "Account Security",
-	"generalSettings": "General Settings",
-	"notificationSettings": "Notification Settings",
 	"menu": {
 		"personalCenter": "Personal Center",
-		"profile": "My Profile",
-		"settings": "Settings"
+		"profile": "My Profile"
 	}
 }

package/templates/web/src/personal-center/locales/zh-CN.json

@@ -1,10 +1,6 @@
 {
-	"accountSecurity": "账户安全",
-	"generalSettings": "通用设置",
-	"notificationSettings": "通知设置",
 	"menu": {
 		"personalCenter": "个人中心",
-		"profile": "我的资料",
-		"settings": "设置"
+		"profile": "我的资料"
 	}
 }

package/templates/web/src/route-nest/entry.ts

@@ -0,0 +1,73 @@
+import type { AppRouteRecordRaw, ModuleDefinition } from "@oj-module/runtime";
+
+import {
+	NodeExpandOutlined,
+	SisternodeOutlined,
+	SubnodeOutlined,
+} from "@ant-design/icons";
+import { createElement, lazy } from "react";
+
+const Menu1And1 = lazy(() => import("./pages/menu1/menu1-1"));
+const Menu1And2 = lazy(() => import("./pages/menu1/menu1-2"));
+const Menu2 = lazy(() => import("./pages/menu2"));
+
+const routes: AppRouteRecordRaw[] = [
+	{
+		path: "/route-nest",
+		handle: {
+			order: 20,
+			title: "route-nest:menu.nestMenus",
+			icon: createElement(NodeExpandOutlined),
+			layout: "container",
+		},
+		children: [
+			{
+				path: "/route-nest/menu1",
+				handle: {
+					title: "route-nest:menu.menu1",
+					icon: createElement(SisternodeOutlined),
+					layout: "parent",
+				},
+				children: [
+					{
+						path: "/route-nest/menu1/menu1-1",
+						Component: Menu1And1,
+						handle: {
+							title: "route-nest:menu.menu1-1",
+							icon: createElement(SubnodeOutlined),
+						},
+					},
+					{
+						path: "/route-nest/menu1/menu1-2",
+						Component: Menu1And2,
+						handle: {
+							title: "route-nest:menu.menu1-2",
+							icon: createElement(SubnodeOutlined),
+						},
+					},
+				],
+			},
+			{
+				path: "/route-nest/menu2",
+				Component: Menu2,
+				handle: {
+					title: "route-nest:menu.menu2",
+					icon: createElement(SubnodeOutlined),
+				},
+			},
+		],
+	},
+];
+
+const mod: ModuleDefinition = {
+	name: "route-nest",
+	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/route-nest/locales/en-US.json

@@ -0,0 +1,9 @@
+{
+	"menu": {
+		"nestMenus": "Nest Menus",
+		"menu1": "Menu1",
+		"menu1-1": "Menu1-1",
+		"menu1-2": "Menu1-2",
+		"menu2": "Menu2"
+	}
+}

package/templates/web/src/route-nest/locales/zh-CN.json

@@ -0,0 +1,9 @@
+{
+	"menu": {
+		"nestMenus": "嵌套菜单",
+		"menu1": "菜单 1",
+		"menu1-1": "菜单 1-1",
+		"menu1-2": "菜单 1-2",
+		"menu2": "菜单 2"
+	}
+}

package/templates/web/src/route-nest/pages/menu1/menu1-1/index.tsx

@@ -0,0 +1,5 @@
+import { BasicContent } from "@oj-module/runtime";
+
+export default function Menu1And1() {
+	return <BasicContent>menu1-1</BasicContent>;
+}

package/templates/web/src/route-nest/pages/menu1/menu1-2/index.tsx

@@ -0,0 +1,5 @@
+import { BasicContent } from "@oj-module/runtime";
+
+export default function Menu1And2() {
+	return <BasicContent>menu1-2</BasicContent>;
+}

package/templates/web/src/route-nest/pages/menu2/index.tsx

@@ -0,0 +1,5 @@
+import { BasicContent } from "@oj-module/runtime";
+
+export default function Menu2() {
+	return <BasicContent>menu2</BasicContent>;
+}

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

@@ -31,6 +31,18 @@ export const schemas = {
 })),
 	"total": z.number(),
 	"truncated": z.boolean()
+}),
+	},
+	"systemOplogPost": {
+		body: z.object({
+	"action": z.string().min(1),
+	"module": z.string().min(1),
+	"version": z.string().optional(),
+	"target": z.string().optional(),
+	"level": z.number().optional()
+}),
+		data: z.object({
+	"ok": z.boolean()
 }),
 	},
 	"systemPermissionsGet": {

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

@@ -33,7 +33,7 @@ export function createSystemClient(ctx: ModuleContext) {
 	}
 	ctx.register.apiPrefix(API_PREFIX);
 	bindRequest(ctx.utils.request);
-	return { systemLoginMethodsGet, systemOplogGet, systemPermissionsGet, systemRolesGet, systemRolesPost, systemRolesDelete, systemRolesBindingsPut, systemSettingsGet, systemSettingsPut, systemUsersGet, systemUsersPost, systemUsersForbiddenPut, systemUsersPasswordPut, systemUsersRolesPut };
+	return { systemLoginMethodsGet, systemOplogGet, systemOplogPost, systemPermissionsGet, systemRolesGet, systemRolesPost, systemRolesDelete, systemRolesBindingsPut, systemSettingsGet, systemSettingsPut, systemUsersGet, systemUsersPost, systemUsersForbiddenPut, systemUsersPasswordPut, systemUsersRolesPut };
 }
 
 /**
@@ -111,6 +111,30 @@ export async function systemOplogGet(query: SystemOplogGetQuery): Promise<System
 	}
 }
 
+export type SystemOplogPostBody = z.input<(typeof schemas)["systemOplogPost"]["body"]>;
+export type SystemOplogPostData = z.infer<(typeof schemas)["systemOplogPost"]["data"]>;
+
+export async function systemOplogPost(body: SystemOplogPostBody): Promise<SystemOplogPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`system/oplog`, { json: body }).json<OjEnvelope<SystemOplogPostData>>();
+		// 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 SystemOplogPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemOplogPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemOplogPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
 export type SystemPermissionsGetData = z.infer<(typeof schemas)["systemPermissionsGet"]["data"]>;
 
 export async function systemPermissionsGet(): Promise<SystemPermissionsGetData> {

package/templates/web/src/system/pages/oplog/index.tsx

@@ -47,7 +47,7 @@ export default function OplogPage() {
 	];
 
 	return (
-		<Space direction="vertical" style={{ width: "100%" }}>
+		<Space direction="vertical" style={{ width: "100%", paddingTop: 16 }}>
 			<Form
 				layout="inline"
 				onFinish={values => setFilters({

package/templates/web/src/system/pages/roles/index.tsx

@@ -67,6 +67,7 @@ export default function RolesPage() {
 
 	return (
 		<Tabs
+			style={{ paddingTop: 16 }}
 			items={[
 				{
 					key: "roles",

package/templates/web/src/system/pages/settings/index.tsx

@@ -91,7 +91,7 @@ export default function SettingsPage() {
 		.filter(g => g.items.length > 0);
 
 	return (
-		<Space direction="vertical" style={{ width: "100%" }}>
+		<Space direction="vertical" style={{ width: "100%", paddingTop: 16 }}>
 			{groups.map(g => (
 				<Card key={g.group} title={g.group}>
 					<Space direction="vertical" style={{ width: "100%" }}>

package/templates/web/src/system/pages/users/index.tsx

@@ -115,7 +115,7 @@ export default function UsersPage() {
 	];
 
 	return (
-		<Space direction="vertical" style={{ width: "100%" }}>
+		<Space direction="vertical" style={{ width: "100%", paddingTop: 16 }}>
 			<Button type="primary" icon={<PlusOutlined />} onClick={() => setCreateOpen(true)}>
 				{t("system:users.create")}
 			</Button>