@oj-module/cli 0.2.18 → 0.2.23

package/templates/src/oj-market/web/components/InstallDialog.tsx

@@ -0,0 +1,194 @@
+import type { IndexRow, TaskRecord } from "../types";
+import { Alert, Button, Modal, Progress, Space, Typography } from "antd";
+import React, { useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { useMarketClient } from "../api/context";
+import { useInstallTask } from "../hooks/useMarket";
+
+export interface InstallDialogProps {
+	row: IndexRow | null
+	open: boolean
+	onClose: () => void
+	onDone?: (record: TaskRecord) => void
+	/** 显式目标版本（回滚用）；缺省取 row.latest（安装/升级） */
+	version?: string | null
+	/** 动作模式：安装/升级/回滚（仅影响标题文案；回滚 = 对旧版降级安装） */
+	mode?: "install" | "upgrade" | "rollback"
+}
+
+const isTerminal = (r: TaskRecord | null) => r != null && r.status !== "running";
+
+/**
+ * 阶段失败指引（契约附录 A 的 `lifecycle.stage.*` key）→ 本模块文案。
+ * 附录 A 的这批 key 在模板 locales 里尚未落地，直接 t() 会把裸 key 显示给运维，
+ * 故此处显式映射；未收录的 key 保持原样（不吞信息）。
+ */
+const HINT_KEYS: Record<string, string> = {
+	"lifecycle.stage.smoke.hint": "oj-market:task:hintSmoke",
+	"lifecycle.stage.cancelled": "oj-market:task:hintCancelled",
+	"lifecycle.stage.reloading.hint": "oj-market:task:hintReloading",
+};
+
+/**
+ * 安装/升级/回滚对话框：触发 POST install → 800ms 轮询 TaskRecord 终态渲染（reason+retryable+hintKey 双语）。
+ *  回滚 = 对已装旧版降级安装（显式 version）；降版迁移差异校验（R12）的可读失败由终态 error 渲染。
+ */
+export function InstallDialog({ row, open, onClose, onDone, version, mode }: InstallDialogProps) {
+	const { t } = useTranslation();
+	const client = useMarketClient();
+	const [taskId, setTaskId] = useState<string | null>(null);
+	const [started, setStarted] = useState(false);
+	const [trusting, setTrusting] = useState(false);
+	const [trustError, setTrustError] = useState<string | null>(null);
+	const { record, done } = useInstallTask(taskId);
+	// onDone 对同一任务只通告一次：父级每次渲染都会换 onDone 身份，若只靠 deps 触发，
+	// 终态后 onDone → index.retry() → 父级重渲染 → onDone 身份变 → 再触发，会形成
+	// 无限请求循环（浏览器侧表现为 ERR_INSUFFICIENT_RESOURCES）。
+	const notifiedTaskIdRef = useRef<string | null>(null);
+
+	const targetVersion = version ?? row?.latest ?? null;
+	const title
+		= mode === "rollback"
+			? t("oj-market:rollback:running")
+			: row?.installed
+				? t("oj-market:card:upgrade")
+				: t("oj-market:task:installing");
+
+	// 打开即触发安装（version 缺省取 latest；已装视为升级；显式 version = 回滚降级安装）。
+	// 注：下面的同步 set 均为「弹窗打开/关闭生命周期」的有意重置与触发守卫；
+	// 曾尝试渲染期派生重置，但同组件 notifier effect 里的 onDone?.(record) 会触发
+	// eslint-react set-state-in-effect 的误判（prop 回调被解析回组件函数），故保留原结构。
+	useEffect(() => {
+		if (open && row && !started) {
+			// eslint-disable-next-line react/set-state-in-effect -- 有意：打开弹窗时置「已触发」守卫，保证安装只发起一次
+			setStarted(true);
+			client
+				.install({ name: row.name, version: targetVersion, source: "cdn" })
+				.then(res => setTaskId(res.task_id))
+				.catch(e => setTaskId(`__error__${e instanceof Error ? e.message : String(e)}`));
+		}
+		if (!open) {
+			// eslint-disable-next-line react/set-state-in-effect -- 有意：关闭弹窗时清空任务，下次打开是全新一次安装
+			setTaskId(null);
+			// eslint-disable-next-line react/set-state-in-effect -- 有意：关闭时复位触发守卫，配合上行清场
+			setStarted(false);
+			// eslint-disable-next-line react/set-state-in-effect -- 有意：关闭时清掉信任错误，避免残留到下次打开
+			setTrustError(null);
+			notifiedTaskIdRef.current = null;
+		}
+	}, [open, row, started, client, targetVersion]);
+
+	useEffect(() => {
+		if (!record || !isTerminal(record) || !done)
+			return;
+		if (notifiedTaskIdRef.current === record.id)
+			return;
+		notifiedTaskIdRef.current = record.id;
+		onDone?.(record);
+	}, [record, done, onDone]);
+
+	// TOFU 确认：确认入库后重试同一安装（服务端 staging 未清场，续跑不重下）
+	const handleTrustConfirm = async () => {
+		if (taskId === null || taskId.startsWith("__error__"))
+			return;
+		setTrusting(true);
+		setTrustError(null);
+		try {
+			await client.trust(taskId);
+			notifiedTaskIdRef.current = null;
+			setTaskId(null);
+			setStarted(false);
+		}
+		catch (e) {
+			setTrustError(e instanceof Error ? e.message : String(e));
+		}
+		finally {
+			setTrusting(false);
+		}
+	};
+
+	const terminal = isTerminal(record);
+	const needsTrust = record?.status === "needs_trust";
+	const succeeded = record?.status === "done";
+	const failed = record?.status === "failed" || record?.status === "partial";
+	const errorTask = typeof taskId === "string" && taskId.startsWith("__error__");
+
+	return (
+		<Modal
+			title={title}
+			open={open}
+			onCancel={onClose}
+			footer={terminal ? <Button onClick={onClose}>{t("oj-market:task:close")}</Button> : null}
+			data-testid="install-dialog"
+		>
+			{errorTask && <Alert type="error" message={taskId!.slice("__error__".length)} />}
+			{!errorTask && !record && (
+				<Typography.Text>
+					{t("oj-market:task:installing")}
+					…
+				</Typography.Text>
+			)}
+			{record && (
+				<>
+					<Progress percent={record.progress} status={terminal ? (succeeded ? "success" : "exception") : "active"} />
+					<div data-testid="install-stage">{record.stage ? t(`oj-market:task:stage.${record.stage}`, record.stage) : record.stage}</div>
+					<div data-testid="install-message">{record.message}</div>
+					{needsTrust && record?.trust && (
+						<Alert
+							style={{ marginTop: 12 }}
+							type="warning"
+							showIcon
+							message={t("oj-market:task:trustTitle")}
+							description={(
+								<Space direction="vertical" size={4}>
+									<span>{t("oj-market:task:trustBody", { keyId: record.trust.key_id })}</span>
+									<span data-testid="install-trust-fingerprint">
+										{t("oj-market:task:trustFingerprint")}
+										<Typography.Text code copyable={{ text: record.trust.fingerprint }}>
+											{record.trust.fingerprint}
+										</Typography.Text>
+									</span>
+									<span>{t("oj-market:task:trustHint")}</span>
+								</Space>
+							)}
+						/>
+					)}
+					{needsTrust && trustError && <Alert style={{ marginTop: 8 }} type="error" showIcon message={trustError} />}
+					{needsTrust && (
+						<Button type="primary" style={{ marginTop: 12 }} loading={trusting} onClick={handleTrustConfirm}>
+							{t("oj-market:task:trustConfirm")}
+						</Button>
+					)}
+					{failed && record.error && (
+						<Alert
+							type="error"
+							showIcon
+							message={record.error.reason}
+							description={(
+								<Space direction="vertical">
+									<span>{record.error.retryable ? t("oj-market:task:retryable") : t("oj-market:task:notRetryable")}</span>
+									{record.error.hintKey && (
+										<span data-testid="install-hint">
+											{t(HINT_KEYS[record.error.hintKey] ?? record.error.hintKey, record.error.hintKey)}
+										</span>
+									)}
+								</Space>
+							)}
+						/>
+					)}
+					{failed && (
+						<Button
+							style={{ marginTop: 12 }}
+							onClick={() => {
+								setTaskId(null);
+								setStarted(false);
+							}}
+						>
+							{t("oj-market:card:retry")}
+						</Button>
+					)}
+				</>
+			)}
+		</Modal>
+	);
+}

package/templates/{web/src/oj-market → src/oj-market/web}/components/RollbackDialog.tsx

@@ -1,6 +1,6 @@
 import type { IndexRow } from "../types";
 import { Alert, Modal, Radio, Space, Spin, Typography } from "antd";
-import React, { useEffect, useMemo, useState } from "react";
+import React, { useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useMarketHistory } from "../hooks/useMarket";
 import { compareVersions } from "../utils/semver";
@@ -34,9 +34,13 @@ export function RollbackDialog({ row, open, onClose, onRollback }: RollbackDialo
 		return [...versions].sort((a, b) => compareVersions(b, a)); // 较新的旧版在前
 	}, [row, status, data]);
 
-	useEffect(() => {
+	// 候选集变化（历史加载完成/切换方案）时默认选中最新旧版；
+	// 渲染期同步派生重置，替代 effect 内同步 set（react/set-state-in-effect）
+	const [prevCandidates, setPrevCandidates] = useState(candidates);
+	if (prevCandidates !== candidates) {
+		setPrevCandidates(candidates);
 		setSelected(candidates.length ? candidates[0] : null);
-	}, [candidates]);
+	}
 
 	const loading = status === "loading";
 

package/templates/{web/src/oj-market → src/oj-market/web}/components/UninstallConfirm.tsx

@@ -19,22 +19,33 @@ export function UninstallConfirm({ row, open, onClose, onConfirmed }: UninstallC
 	const { t } = useTranslation();
 	const client = useMarketClient();
 	const [impact, setImpact] = useState<UninstallImpact | null>(null);
-	const [loading, setLoading] = useState(false);
 	const [error, setError] = useState<string | null>(null);
 
+	// 打开（或切换方案）即清场上一轮结果；渲染期同步派生重置，替代 effect 内同步 set
+	const rowKey = open && row ? row.name : null;
+	const [prevRowKey, setPrevRowKey] = useState(rowKey);
+	if (prevRowKey !== rowKey) {
+		setPrevRowKey(rowKey);
+		setImpact(null);
+		setError(null);
+	}
+
 	useEffect(() => {
 		if (!open || !row)
 			return;
-		setLoading(true);
-		setError(null);
-		setImpact(null);
+		let active = true;
 		client
 			.uninstallImpact(row.name)
-			.then(setImpact)
-			.catch(e => setError(e instanceof Error ? e.message : String(e)))
-			.finally(() => setLoading(false));
+			.then(i => active && setImpact(i))
+			.catch(e => active && setError(e instanceof Error ? e.message : String(e)));
+		return () => {
+			active = false;
+		};
 	}, [open, row, client]);
 
+	// 加载态派生：已打开且尚无结果/错误即视为预检中（替代原 effect 同步 setLoading）
+	const loading = rowKey !== null && impact === null && error === null;
+
 	return (
 		<Modal
 			title={t("oj-market:confirm:uninstallTitle")}

package/templates/{web/src/oj-market → src/oj-market/web}/hooks/useMarket.ts

@@ -12,10 +12,12 @@ export type LoadState<T> = { status: "loading", data?: undefined } | { status: "
 export function useMarketIndex(): LoadState<IndexRow[]> & { retry: () => void } {
 	const client = useMarketClient();
 	const [state, setState] = useState<LoadState<IndexRow[]>>({ status: "loading" });
+	// 重试不复跑「先同步 set loading 再拉取」的加载函数（effect 内同步 set 触发
+	// react/set-state-in-effect），改为事件里置 loading + 递增 nonce 驱动 effect 重跑。
+	const [nonce, setNonce] = useState(0);
 
-	const load = useCallback(() => {
+	useEffect(() => {
 		let active = true;
-		setState({ status: "loading" });
 		client
 			.index()
 			.then(data => active && setState({ status: "ok", data }))
@@ -23,11 +25,14 @@ export function useMarketIndex(): LoadState<IndexRow[]> & { retry: () => void }
 		return () => {
 			active = false;
 		};
-	}, [client]);
+	}, [client, nonce]);
 
-	useEffect(() => load(), [load]);
+	const retry = useCallback(() => {
+		setState({ status: "loading" });
+		setNonce(n => n + 1);
+	}, []);
 
-	return { ...state, retry: load };
+	return { ...state, retry };
 }
 
 /** 任务轮询：给定 task_id，800ms 轮询至终态（done/failed/partial）；超时不抛，返回当前值 */
@@ -39,12 +44,20 @@ export function useInstallTask(taskId: string | null): {
 	const [record, setRecord] = useState<TaskRecord | null>(null);
 	const [done, setDone] = useState(false);
 
+	// 无任务 id / 切换任务 = 尚无任务：清空上一次任务的记录，避免「重新安装/信任后重试」时
+	// 旧终态（可能是 needs_trust）残留在弹窗里被误读成本次结果。
+	// （渲染期同步派生重置，替代 effect 内同步 set，规避 react/set-state-in-effect）
+	const [prevTaskId, setPrevTaskId] = useState(taskId);
+	if (prevTaskId !== taskId) {
+		setPrevTaskId(taskId);
+		setRecord(null);
+		setDone(false);
+	}
+
 	useEffect(() => {
 		if (!taskId)
 			return;
 		let active = true;
-		setRecord(null);
-		setDone(false);
 		poll(
 			() => client.task(taskId),
 			r => r.status !== "running",
@@ -75,10 +88,11 @@ export function useInstallTask(taskId: string | null): {
 export function useMarketHistory(): LoadState<MarketHistory[]> & { retry: () => void } {
 	const client = useMarketClient();
 	const [state, setState] = useState<LoadState<MarketHistory[]>>({ status: "loading" });
+	// 同 useMarketIndex：重试走 nonce 驱动，不在 effect 链路里同步 set
+	const [nonce, setNonce] = useState(0);
 
-	const load = useCallback(() => {
+	useEffect(() => {
 		let active = true;
-		setState({ status: "loading" });
 		client
 			.history()
 			.then(data => active && setState({ status: "ok", data }))
@@ -86,9 +100,12 @@ export function useMarketHistory(): LoadState<MarketHistory[]> & { retry: () =>
 		return () => {
 			active = false;
 		};
-	}, [client]);
+	}, [client, nonce]);
 
-	useEffect(() => load(), [load]);
+	const retry = useCallback(() => {
+		setState({ status: "loading" });
+		setNonce(n => n + 1);
+	}, []);
 
-	return { ...state, retry: load };
+	return { ...state, retry };
 }

package/templates/{web/src/oj-market → src/oj-market/web}/locales/en-US.json

@@ -49,12 +49,21 @@
 			"running": "Running",
 			"done": "Done",
 			"failed": "Failed",
-			"partial": "Partial"
+			"partial": "Partial",
+			"needs_trust": "Awaiting trust"
 		},
+		"trustTitle": "Trust confirmation required: publisher key not in host trust store",
+		"trustBody": "The signing key of publisher \"{{keyId}}\" is not trusted by this host yet (first-use TOFU).",
+		"trustFingerprint": "Key fingerprint: ",
+		"trustHint": "Compare this fingerprint with the one published by the vendor; confirm only if they match. Confirming retries this install automatically and reuses the staged files.",
+		"trustConfirm": "Fingerprint matches — trust and retry",
 		"reason": "Reason",
 		"retryable": "Retryable",
 		"notRetryable": "Not retryable",
 		"hint": "Hint",
+		"hintSmoke": "Smoke probe failures usually mean one of two things: (1) the anonymous endpoints added by this install (auth.anonymous_paths) are pending a restart — restart the host and retry; (2) in dev the host already ships a module with the same name, so the route belongs to the source module and the probe is not hitting the freshly installed package.",
+		"hintCancelled": "This install was cancelled: lock file, version directory and staging were restored to their pre-install state. You can retry directly.",
+		"hintReloading": "Config hot-reload was partial: hot-applicable sections (vars, ...) are applied, while the auth section (including anonymous endpoints) needs a host restart.",
 		"close": "Close",
 		"viewLog": "View log"
 	},

package/templates/{web/src/oj-market → src/oj-market/web}/locales/zh-CN.json

@@ -49,12 +49,21 @@
 			"running": "进行中",
 			"done": "完成",
 			"failed": "失败",
-			"partial": "部分完成"
+			"partial": "部分完成",
+			"needs_trust": "待信任确认"
 		},
+		"trustTitle": "待信任确认：发布方密钥不在宿主信任库",
+		"trustBody": "发布方「{{keyId}}」的签名密钥尚未被本宿主信任（首次信任 TOFU）。",
+		"trustFingerprint": "密钥指纹：",
+		"trustHint": "请与发布方公布的公钥指纹逐字核对，一致才确认。确认后会自动重试本次安装，已暂存的内容不会重新下载。",
+		"trustConfirm": "指纹一致，信任并重试",
 		"reason": "原因",
 		"retryable": "可重试",
 		"notRetryable": "不可重试",
 		"hint": "提示",
+		"hintSmoke": "冒烟探活失败常见于两类原因：① 本次安装新增的匿名端点（auth.anonymous_paths）属「待重启生效」，重启宿主后再点重试即可；② dev 形态下宿主已内置同名模块，该路由由源码模块占位，探活打到的不是刚装的包。",
+		"hintCancelled": "本次安装已被取消：锁、版本目录与 staging 均已回到发起前状态，可直接重试。",
+		"hintReloading": "配置热更未完全生效：可热改段（vars 等）已应用，auth 段（含匿名端点）需重启宿主后生效。",
 		"close": "关闭",
 		"viewLog": "查看日志"
 	},

package/templates/{web/src/oj-market → src/oj-market/web}/types.ts

@@ -5,8 +5,12 @@
 /** 安装阶段名（契约附录 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";
+/**
+ * 任务状态（§10.2 三态 + partial：锁后失败部分生效 + needs_trust：未知发布方 key 待人工
+ * TOFU 确认，staging 不清场，确认入库后重试同一安装即可续跑）。
+ * needs_trust 是非成功态：消费面不得按绿色成功渲染（真源 api/src/_platform/_lifecycle/types.ts:64）。
+ */
+export type TaskStatus = "running" | "done" | "failed" | "partial" | "needs_trust";
 
 /** 阶段明细日志（UI 详情日志区数据源） */
 export interface TaskStageLog {
@@ -22,6 +26,13 @@ export interface TaskError {
 	hintKey?: string
 }
 
+/** needs_trust 终态：待确认的发布方 key（指纹 = sha256(public_key) 十六进制，供人核对） */
+export interface TaskTrust {
+	key_id: string
+	public_key: string
+	fingerprint: string
+}
+
 /** 安装任务记录（§10.2 + stages 明细日志；落 .install-tasks/<id>.json，800ms 轮询消费面） */
 export interface TaskRecord {
 	id: string
@@ -34,6 +45,8 @@ export interface TaskRecord {
 	message: string
 	stages: TaskStageLog[]
 	error?: TaskError
+	/** needs_trust 终态才有：待确认的发布方 key（POST /market/trust {task_id} 消费） */
+	trust?: TaskTrust
 	startedAt: number
 	finishedAt?: number
 	appliedSeq?: number

package/templates/{api/src/system → src/system/api}/login-methods/api.ts

@@ -1,7 +1,7 @@
-import { respond } from "../../_platform/_shared/respond";
+import { respond } from "#/_platform/_shared/respond";
 // GET /api/system/login-methods —— 登录方式发现（C5/D2；匿名端点：登录前无 token，
 // 项目 config.yaml auth.anonymous_paths 必须列 /system/login-methods，漏列则握手 401 登录页必坏）。
-import { listLoginMethods } from "../../_platform/_shared/service/domain/settings";
+import { listLoginMethods } from "#/_platform/_shared/service/domain/settings";
 
 async function get() {
 	await respond(async () => {

package/templates/src/system/api/manifest.yaml

@@ -0,0 +1,6 @@
+name: system
+desc: 框架管理域端点（/api/system/*）：角色/权限点管理（assertSystemAdmin 判权，H2）
+version: 0.1.0
+deps: # 两处都用：roles/bindings/permissions 读写 _platform 的 sys_* 表（ownership_guard: deny）；
+  # 跨模块别名 `#/_platform/…` 的依赖门禁（oj build S008）
+  _platform: ^0.1.0

package/templates/{api/src/system → src/system/api}/oplog/api.ts

@@ -1,9 +1,9 @@
-import { respond } from "../../_platform/_shared/respond";
+import { respond } from "#/_platform/_shared/respond";
 // GET /api/system/oplog?action=&username=&module=&limit= —— 操作日志查询（AC1-29；D13 admin 可查）。
 // POST /api/system/oplog —— 操作日志写入（C3；登录态即可，解决方案模块记录自身操作）。
-import { assertSystemAdmin, currentAccess } from "../../_platform/_shared/service/infra/access";
-import { recordOp } from "../../_platform/_shared/service/infra/audit";
-import { searchOplog } from "../../_platform/_shared/service/infra/oplog";
+import { assertSystemAdmin, currentAccess } from "#/_platform/_shared/service/infra/access";
+import { recordOp } from "#/_platform/_shared/service/infra/audit";
+import { searchOplog } from "#/_platform/_shared/service/infra/oplog";
 
 async function get() {
 	await respond(async () => {

package/templates/{api/src/system → src/system/api}/permissions/api.ts

@@ -1,7 +1,7 @@
-import { respond } from "../../_platform/_shared/respond";
-import { listPermissions } from "../../_platform/_shared/service/domain/roles";
+import { respond } from "#/_platform/_shared/respond";
+import { listPermissions } from "#/_platform/_shared/service/domain/roles";
 // GET /api/system/permissions —— 权限点全量（C2 绑定编辑器数据源，deprecated 标灰）。
-import { assertSystemAdmin } from "../../_platform/_shared/service/infra/access";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
 
 async function get() {
 	await respond(async () => {

package/templates/{api/src/system → src/system/api}/roles/api.ts

@@ -1,8 +1,8 @@
-import { respond } from "../../_platform/_shared/respond";
-import { createRole, deleteRole, listRoles } from "../../_platform/_shared/service/domain/roles";
+import { respond } from "#/_platform/_shared/respond";
+import { createRole, deleteRole, listRoles } from "#/_platform/_shared/service/domain/roles";
 // 管理域端点 /api/system/roles（设计文档 D207：/api/system/* = 管理域，assertSystemAdmin 判权）。
 // handler 层只编排：守卫 → service → json 信封；name 走 query（wiki 先例：静态段 + http.query）。
-import { assertSystemAdmin } from "../../_platform/_shared/service/infra/access";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
 
 async function guard(): Promise<void> {
 	await assertSystemAdmin();

package/templates/{api/src/system → src/system/api}/roles/bindings/api.ts

@@ -1,9 +1,9 @@
-import { respond } from "../../../_platform/_shared/respond";
-import { updateBindings } from "../../../_platform/_shared/service/domain/roles";
+import { respond } from "#/_platform/_shared/respond";
+import { updateBindings } from "#/_platform/_shared/service/domain/roles";
 // PUT /api/system/roles/bindings?name=xxx —— 整集替换角色绑定。
 // AC1-18 声明角色绑定可调整；AC1-19 builtin 硬拒（service 层）；AC1-30 摘绑定 = 紧急吊销出口
 // （service 内写后按持有者失效判权缓存）。
-import { assertSystemAdmin } from "../../../_platform/_shared/service/infra/access";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
 
 async function put() {
 	await respond(async () => {

package/templates/{api/src/system → src/system/api}/settings/api.ts

@@ -1,7 +1,7 @@
-import { respond } from "../../_platform/_shared/respond";
-import { listSettings, updateSetting } from "../../_platform/_shared/service/domain/settings";
+import { respond } from "#/_platform/_shared/respond";
+import { listSettings, updateSetting } from "#/_platform/_shared/service/domain/settings";
 // /api/system/settings —— 系统设置（PRD §4.3）：GET 按组列出（secret 掩码），PUT 写值（写审计）。
-import { assertSystemAdmin } from "../../_platform/_shared/service/infra/access";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
 
 const settingItemSchema = {
 	type: "object",

package/templates/{api/src/system → src/system/api}/users/api.ts

@@ -1,9 +1,9 @@
-import { respond } from "../../_platform/_shared/respond";
-import { createUser, listUsers } from "../../_platform/_shared/service/domain/users";
+import { respond } from "#/_platform/_shared/respond";
+import { createUser, listUsers } from "#/_platform/_shared/service/domain/users";
 // 管理域端点组 /api/system/users（AC1-7~10）：handler 只编排——assertSystemAdmin 守卫 → service → json。
 // 保护红线在 service 层硬 enforcement：禁止操作自己、admin 不碰成员资格、最后 superadmin 兜底。
 // 子端点：roles/password/forbidden 各为独立目录（wiki per-endpoint 先例）。
-import { assertSystemAdmin } from "../../_platform/_shared/service/infra/access";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
 
 const bcryptDeps = { bcryptHash: (pw: string) => bcrypt.hash(pw) };
 

package/templates/{api/src/system → src/system/api}/users/forbidden/api.ts

@@ -1,7 +1,7 @@
-import { respond } from "../../../_platform/_shared/respond";
-import { setForbidden } from "../../../_platform/_shared/service/domain/users";
+import { respond } from "#/_platform/_shared/respond";
+import { setForbidden } from "#/_platform/_shared/service/domain/users";
 // PUT /api/system/users/forbidden?uid= —— 禁用/解禁（禁用即删 refresh，撤销即强退）。
-import { assertSystemAdmin } from "../../../_platform/_shared/service/infra/access";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
 
 async function put() {
 	await respond(async () => {

package/templates/{api/src/system → src/system/api}/users/password/api.ts

@@ -1,7 +1,7 @@
-import { respond } from "../../../_platform/_shared/respond";
-import { changePasswordByAdmin } from "../../../_platform/_shared/service/domain/users";
+import { respond } from "#/_platform/_shared/respond";
+import { changePasswordByAdmin } from "#/_platform/_shared/service/domain/users";
 // PUT /api/system/users/password?uid= —— 管理员重置口令（must_change=1 + 级联吊销 refresh）。
-import { assertSystemAdmin } from "../../../_platform/_shared/service/infra/access";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
 
 async function put() {
 	await respond(async () => {

package/templates/{api/src/system → src/system/api}/users/roles/api.ts

@@ -1,7 +1,7 @@
-import { respond } from "../../../_platform/_shared/respond";
-import { updateUserRoles } from "../../../_platform/_shared/service/domain/users";
+import { respond } from "#/_platform/_shared/respond";
+import { updateUserRoles } from "#/_platform/_shared/service/domain/users";
 // PUT /api/system/users/roles?uid= —— 整集替换用户角色（AC1-7；sys_user_role 权威源 + 写时失效）。
-import { assertSystemAdmin } from "../../../_platform/_shared/service/infra/access";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
 
 async function put() {
 	await respond(async () => {

package/templates/{web/src/system → src/system/web}/locales/en-US.json

@@ -30,7 +30,7 @@
 			"displayName": "Display Name",
 			"email": "Email",
 			"roles": "Roles",
-			"status": "Status",
+			"status": "Account status (forbidden / password change)",
 			"actions": "Actions"
 		}
 	},

package/templates/{web/src/system → src/system/web}/locales/zh-CN.json

@@ -30,7 +30,7 @@
 			"displayName": "显示名",
 			"email": "邮箱",
 			"roles": "角色",
-			"status": "状态",
+			"status": "账号状态（禁用/首登改密）",
 			"actions": "操作"
 		}
 	},

package/templates/src/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"extends": [
+		"../tsconfig.json",
+		"../tsconfig.paths.json"
+	],
+	"include": [
+		".",
+		"../global.d.ts",
+		"../env.d.ts",
+		"../types"
+	],
+	"exclude": [
+		"*/web",
+		"*/web/**"
+	]
+}

package/templates/{api/tests → tests}/auth-ldap.spec.ts

@@ -4,8 +4,8 @@
 /* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写 */
 import { afterEach, beforeAll, describe, expect, it } from "vitest";
 
-import { esc, firstAttr } from "../src/auth/_shared/ldap";
-import { createLdapLogin } from "../src/auth/_shared/ldap-login";
+import { esc, firstAttr } from "../src/auth/api/_shared/ldap";
+import { createLdapLogin } from "../src/auth/api/_shared/ldap-login";
 import { installDb } from "./fixture";
 
 let dbo: ReturnType<typeof installDb>;

package/templates/{api/tests → tests}/auth-session.spec.ts

@@ -1,11 +1,11 @@
 // BDD：登录链——B1 登录顺序（D14 统一 401）、B2 首登改密（AC1-27）、B3 refresh 轮换/reuse 检测（AC1-13）、B4 JWT 仅 sub。
 // deps 全注入（Node 侧 crypto 只读不可 stub，设计 §9.1）；fake bcrypt 以 `hashed:<pw>` 为口令哈希约定。
 /* eslint-disable test/prefer-lowercase-title -- AC 编号是验收锚点，保留大写 */
-import type { SessionDeps } from "../src/auth/_shared/session";
+import type { SessionDeps } from "../src/auth/api/_shared/session";
 
 import { afterEach, beforeAll, describe, expect, it } from "vitest";
-import { assertPermission } from "../src/_platform/_shared/service/infra/access";
-import { createSession } from "../src/auth/_shared/session";
+import { assertPermission } from "../src/_platform/api/_shared/service/infra/access";
+import { createSession } from "../src/auth/api/_shared/session";
 import { installDb } from "./fixture";
 
 let dbo: ReturnType<typeof installDb>;