deploy --env staging --tag v2.4.0AI审阅与决策
ApprovalCard
@mox-hub/patterns · AI · 审阅与决策 · canonical
approval-card@mox-hub/patternsSemanticcanonicalsrc/components/approval-card.tsx变体演示approval-card
中风险Ordo Agent
批准执行 staging 部署
将写入 3 张表,预计 12s;失败会自动回滚。
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title* | string | — | — |
| requester* | ReactNode | — | — |
| riskSignal* | ConfidenceSignal | — | — |
| riskLabel* | ReactNode | — | — |
| riskNote* | ReactNode | — | — |
| preview* | ReactNode | — | — |
| busy* | boolean | false | — |
| disabled* | boolean | false | — |
| onResolve* | (action: "approve" | "reject") => void | Promise<void> | — | — |
| onDismiss* | () => void | — | — |
| resolved* | ApprovalResolvedState | — | — |
| resolvedLabel* | ReactNode | — | — |
| labels* | Partial<ApprovalCardLabels> | — | — |
| className* | string | — | — |
源码
/**
* ApprovalCard - [AI] 审批操作统一件(组件规划账本 B2 · 宪法 §22.1 等人一等状态律 / §22.4 审阅收场仪式)
*
* 「Agent 行动前请示」的统一操作面:风险档 + 行动预览 + 单键批准/拒绝 + 决后收场。
* - §22.1:待人裁决是一等状态——左侧 3px warning 色条 + 风险档胶囊恒显(不随状态降级为灰);
* 风险档复用 ConfidenceSignal 四档枚举但按**风险方向**渲染(3=红 / 2=黄 / 1=蓝 / 0=灰,
* 与置信方向相反——高风险必须红,消费方只折算枚举,配色内置于本件)。
* - §22.4 收场仪式:裁决后不得无声消失——先确认覆盖层(约 1s,决定图标 + 文案,
* 参考 decision-card-shell confirm 模式),再折叠为凭证行(决定 + 时间)。
* - 双模(宪法 §10.7):`resolved` 传 undefined = 非受控,仪式由本件自管;
* 传 null / 'approve' / 'reject' / 'neutral' = 受控,终态由父级数据驱动,本件只发 onResolve 回调。
* - `onResolve` 返回 Promise 时本件等待落定再进确认态;Promise reject 视为「未落定」回滚待决态
* (错误呈现归消费方,见 run-approvals-section 的 toast 先例)。
*/
import { useEffect, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
import {
Check,
Minus,
PauseCircle,
SignalHigh,
SignalLow,
SignalMedium,
SignalZero,
X,
} from 'lucide-react';
import type { LucideIcon } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';
import { Kbd } from '@mox-hub/ui/components/kbd';
import { formatRelativeTime } from '../lib/date-format';
import { normalizeConfidenceSignal, type ConfidenceSignal } from './ai-verdict-pill';
import { usePatternLabels } from '../lib/i18n';
/** 确认覆盖层停留时长(§22.4 第 1 拍「约 1s」) */
const CONFIRM_MS = 1000;
/** 卡面文案缺省(中文常量,宪法 §16;消费方经 labels 覆写接入 i18n) */
export interface ApprovalCardLabels {
/** 批准键(动词开头) */
approve: string;
/** 拒绝键(破坏性,具体动词) */
reject: string;
/** 跳过键(onDismiss 传入才渲染) */
dismiss: string;
/** busy 暂停语境提示(AI 链路进行中) */
busyNote: string;
/** 确认覆盖层文案(批准) */
confirmApprove: string;
/** 确认覆盖层文案(拒绝) */
confirmReject: string;
/** 凭证行文案(批准) */
receiptApprove: string;
/** 凭证行文案(拒绝) */
receiptReject: string;
/** 凭证行缺省文案(neutral 系统处置;消费方应按处置语义覆写 resolvedLabel) */
receiptNeutral: string;
/** 风险档文案(0-3 缺省档名;可用 riskLabel 整体覆写) */
riskUnknown: string;
riskLow: string;
riskMedium: string;
riskHigh: string;
}
const DEFAULT_LABELS: ApprovalCardLabels = {
approve: '批准',
reject: '拒绝',
dismiss: '跳过',
busyNote: '等待 AI 完成当前步',
confirmApprove: '已批准',
confirmReject: '已拒绝',
receiptApprove: '已批准',
receiptReject: '已拒绝',
receiptNeutral: '已关闭',
riskUnknown: '风险未知',
riskLow: '低风险',
riskMedium: '中风险',
riskHigh: '高风险',
};
/**
* 风险档 → 胶囊视觉(**风险方向**,§5.3 语义色表状态:高=红 · 中=黄 · 低=蓝 · 未知=中性灰)。
* 注意与 ai-verdict-pill 的置信方向相反:这里是档越高越危险,故 3 用红而非绿。
*/
const RISK_TIER_VISUALS: Record<ConfidenceSignal, string> = {
0: 'border-border bg-muted/40 text-content-text-muted',
1: 'border-accent-blue/30 bg-accent-blue-light/40 text-accent-blue',
2: 'border-accent-yellow/30 bg-accent-yellow-light/40 text-accent-yellow',
3: 'border-accent-red/30 bg-accent-red-light/40 text-accent-red',
};
/** 档位图标(§8.5 第 4 条:风险档不得只靠颜色传达——信号格数即档位) */
const RISK_TIER_ICON: Record<ConfidenceSignal, LucideIcon> = {
0: SignalZero,
1: SignalLow,
2: SignalMedium,
3: SignalHigh,
};
/** 凭证行决定 → 图标 + 色调(§22.4 第 2 拍:决定可视可辨,不靠颜色单通道——图标即决定) */
const RECEIPT_VISUALS: Record<'approve' | 'reject' | 'neutral', { icon: LucideIcon; chip: string; text: string }> = {
approve: { icon: Check, chip: 'bg-accent-green-light text-accent-green', text: 'text-accent-green' },
reject: { icon: X, chip: 'bg-accent-red-light text-accent-red', text: 'text-accent-red' },
neutral: { icon: Minus, chip: 'bg-muted text-content-text-muted', text: 'text-content-text-secondary' },
};
export type ApprovalResolvedState = 'approve' | 'reject' | 'neutral';
export interface ApprovalCardProps {
/** 请求标题(做什么:如「批准执行 X 的步骤 Y」) */
title: string;
/** 请求者(AI 成员名 / 头像等任意节点;缺省不渲染) */
requester?: ReactNode;
/** 风险档四档(复用 ConfidenceSignal 枚举,风险方向渲染内置;非法值防御归一)。
* null/undefined 折算为 0(「风险未知」灰档)——风险位恒显,不缺席(§22.1)。 */
riskSignal?: ConfidenceSignal | null;
/** 风险档文案覆写(如 i18n 的「只读/写操作/高风险」;缺省用内置中文档名) */
riskLabel?: ReactNode;
/** AI 附注 / 风险说明(aiJudge advisory 徽注、自报偏差提示等,原样渲染) */
riskNote?: ReactNode;
/** 行动预览区(会做什么:命令 / 文件 / 差异摘要) */
preview?: ReactNode;
/** AI 链路进行中:显示暂停语境提示 + aria-busy,不阻塞操作(消费方可叠加 disabled) */
busy?: boolean;
/** 消费方整体禁用(禁两键、跳过与快捷键) */
disabled?: boolean;
/** 审批裁决回调:approve=批准 / reject=拒绝。返回 Promise 时等待落定再进确认态,
* reject 视为未决回滚待决态(错误呈现归消费方)。 */
onResolve?: (action: 'approve' | 'reject') => void | Promise<void>;
/** 跳过(可选;不传不渲染跳过键) */
onDismiss?: () => void;
/** 受控已决态:undefined=非受控(本件自管收场仪式);null=受控待决;
* 'approve'/'reject'=受控已决凭证;'neutral'=系统处置收场(过期/取消等非人决)。 */
resolved?: ApprovalResolvedState | null;
/** 受控凭证文案覆写(如「已自动通过」「已过期」;缺省按决定给默认文案) */
resolvedLabel?: ReactNode;
/** 文案覆写(缺省中文常量) */
labels?: Partial<ApprovalCardLabels>;
className?: string;
}
/** 非受控内部状态机:待决 → 提交中(Promise 落定前)→ 确认覆盖层(1s)→ 凭证行 */
type InternalPhase = 'pending' | 'submitting' | 'confirm' | 'done';
/**
* ApprovalCard —— 审批操作统一件(账本 B2 销账即登记,登记材料见
* apps/frontend/.roadmap-handoff/approval-card-handoff.md)。
*/
export function ApprovalCard({
title,
requester,
riskSignal,
riskLabel,
riskNote,
preview,
busy = false,
disabled = false,
onResolve,
onDismiss,
resolved,
resolvedLabel,
labels,
className,
}: ApprovalCardProps) {
const D = usePatternLabels('approvalCard', DEFAULT_LABELS);
const L: ApprovalCardLabels = { ...D, ...labels };
const tier = normalizeConfidenceSignal(riskSignal ?? 0);
const RiskIcon = RISK_TIER_ICON[tier];
const tierLabel = riskLabel ?? [L.riskUnknown, L.riskLow, L.riskMedium, L.riskHigh][tier];
const controlled = resolved !== undefined;
const [phase, setPhase] = useState<InternalPhase>('pending');
const [decided, setDecided] = useState<'approve' | 'reject' | null>(null);
const [decidedAt, setDecidedAt] = useState<Date | null>(null);
const confirmTimer = useRef<number | null>(null);
useEffect(
() => () => {
if (confirmTimer.current !== null) window.clearTimeout(confirmTimer.current);
},
[],
);
const runResolve = (action: 'approve' | 'reject') => {
// 受控模式:本件只发回调,终态由父级 resolved 数据驱动(§10.7 禁内部缓存受控值)
if (controlled) {
void onResolve?.(action);
return;
}
if (phase !== 'pending') return;
const finish = () => {
setDecided(action);
setDecidedAt(new Date());
setPhase('confirm');
confirmTimer.current = window.setTimeout(() => setPhase('done'), CONFIRM_MS);
};
const result = onResolve?.(action);
if (result && typeof (result as Promise<void>).then === 'function') {
// Promise 落定前禁双击;reject = 未落定,回滚待决(错误呈现归消费方)
setPhase('submitting');
void (result as Promise<void>).then(finish, () => setPhase('pending'));
} else {
finish();
}
};
const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
if (disabled) return;
const pending = controlled ? resolved === null : phase === 'pending';
if (!pending) return;
// 快捷键不干扰输入框焦点(§8.5):焦点在输入类控件内时不接管
const target = event.target as HTMLElement | null;
if (
target &&
(target.isContentEditable ||
target.tagName === 'INPUT' ||
target.tagName === 'TEXTAREA' ||
target.tagName === 'SELECT')
) {
return;
}
if (event.key === 'Enter' && (event.ctrlKey || event.metaKey)) {
event.preventDefault();
runResolve('approve');
} else if (event.key === 'Escape') {
// 卡内 Esc = 拒绝并拦截外层浮层关闭——焦点在卡内时「收场」优先于「离开」
event.preventDefault();
event.stopPropagation();
runResolve('reject');
}
};
/* ── 终态:已决凭证行(§22.4 第 2 拍:决定 + 时间一行凭证,不再可操作)── */
const receiptAction: ApprovalResolvedState | null = controlled
? (resolved ?? null)
: phase === 'done'
? decided
: null;
if (receiptAction !== null) {
const visual = RECEIPT_VISUALS[receiptAction];
const Icon = visual.icon;
const text =
resolvedLabel ??
(receiptAction === 'approve'
? L.receiptApprove
: receiptAction === 'reject'
? L.receiptReject
: L.receiptNeutral);
return (
<div
data-approval-card=""
data-approval-state={receiptAction}
data-risk-tier={tier}
className={cn(
'flex items-center gap-2 rounded-md border border-border/60 bg-card px-2.5 py-1.5 text-xs',
className,
)}
>
<span
aria-hidden="true"
className={cn('flex size-5 shrink-0 items-center justify-center rounded-full', visual.chip)}
>
<Icon className="size-3" />
</span>
<span className={cn('shrink-0 font-medium', visual.text)}>{text}</span>
{/* 非受控仪式知道决定时刻;受控数据缺决定时间则不伪造(§9 数据真实性) */}
{!controlled && decidedAt && (
<span className="shrink-0 font-mono text-xs text-content-text-muted">
{formatRelativeTime(decidedAt)}
</span>
)}
{riskSignal !== null && riskSignal !== undefined && (
<span
data-risk-pill=""
className={cn(
'inline-flex shrink-0 items-center gap-1 rounded-full border px-1.5 py-0.5 text-xs font-medium',
RISK_TIER_VISUALS[tier],
)}
>
<RiskIcon aria-hidden="true" className="size-2.5" />
{tierLabel}
</span>
)}
<span className="min-w-0 truncate text-content-text-muted">{title}</span>
</div>
);
}
const actionBlocked = disabled || phase === 'submitting';
return (
<div
role="group"
aria-label={title}
aria-busy={(busy || phase === 'submitting') || undefined}
data-approval-card=""
data-approval-state={phase}
data-risk-tier={tier}
onKeyDown={handleKeyDown}
className={cn(
// AI 内联卡统一 rounded-lg(与 RunLine / StreamError / ApplyDiff 同档)
'relative overflow-hidden rounded-lg border border-border/60 bg-card text-xs',
className,
)}
>
{/* §22.1 等人一等状态:左侧 2px(w-0.5 唯一合法半档)warning 色条——本卡整体就是「等人」件,警示不降级 */}
<span aria-hidden="true" className="absolute inset-y-0 start-0 w-0.5 bg-accent-yellow" />
<div className="flex flex-col gap-1.5 py-2 pe-2.5 ps-3.5">
{/* 行 1:风险档(恒显)+ 请求者 + busy 暂停语境 */}
<div className="flex items-center gap-1.5">
<span
data-risk-pill=""
className={cn(
'inline-flex shrink-0 items-center gap-1 rounded-full border px-1.5 py-0.5 text-xs font-medium',
RISK_TIER_VISUALS[tier],
)}
>
<RiskIcon aria-hidden="true" className="size-2.5" />
{tierLabel}
</span>
{requester && (
<span className="min-w-0 truncate text-xs text-content-text-muted">{requester}</span>
)}
{busy && (
<span className="ms-auto inline-flex shrink-0 items-center gap-1 text-xs text-accent-yellow">
<PauseCircle aria-hidden="true" className="size-3" />
{L.busyNote}
</span>
)}
</div>
{/* 行 2:标题 */}
<p className="break-words font-medium text-content-text">{title}</p>
{/* 行 3:行动预览(会做什么) */}
{preview && (
<div className="rounded-sm bg-muted/40 px-2 py-1.5 text-xs break-words text-content-text-secondary">
{preview}
</div>
)}
{/* 行 4:AI 附注 / 风险说明(advisory 徽注、自报偏差提示等) */}
{riskNote && (
<div className="flex flex-wrap items-center gap-1 text-xs text-content-text-muted">
{riskNote}
</div>
)}
{/* 行 5:操作区(单键批准/拒绝 + 快捷键提示 + 可选跳过)
主操作统一右下;快捷键提示用 me-auto 恒居左,不再随 dismiss 有无切换布局 */}
<div className="mt-0.5 flex items-center gap-1.5 border-t border-border/40 pt-2">
{/* 快捷键提示:纯视觉记忆辅助,不向读屏重复播报(按钮自身已可达) */}
<span
aria-hidden="true"
className="me-auto inline-flex items-center gap-1 text-xs text-content-text-muted"
>
<Kbd>Ctrl</Kbd>
<Kbd>↵</Kbd>
<span>{L.approve}</span>
<Kbd className="ms-1">Esc</Kbd>
<span>{L.reject}</span>
</span>
{onDismiss && (
<Button
type="button"
variant="quiet"
size="xs"
disabled={actionBlocked}
onClick={onDismiss}
data-ai-action="approval-card.dismiss"
>
{L.dismiss}
</Button>
)}
<Button
type="button"
variant="destructive"
size="xs"
disabled={actionBlocked}
onClick={() => runResolve('reject')}
data-ai-action="approval-card.reject"
>
<X aria-hidden="true" />
{L.reject}
</Button>
<Button
type="button"
size="xs"
disabled={actionBlocked}
onClick={() => runResolve('approve')}
data-ai-action="approval-card.approve"
>
<Check aria-hidden="true" />
{L.approve}
</Button>
</div>
</div>
{/* ── 决后确认覆盖层(§22.4 第 1 拍):拦截交互防连点,role="status" 播报决定 ── */}
{phase === 'confirm' && decided !== null && (
<div
role="status"
data-approval-confirm={decided}
className={cn(
'absolute inset-0 z-overlay flex flex-col items-center justify-center gap-2 rounded-lg bg-background/85 backdrop-blur-sm duration-normal',
'motion-safe:animate-in motion-safe:fade-in motion-safe:zoom-in-95',
decided === 'approve' ? 'text-accent-green' : 'text-accent-red',
)}
>
<span
aria-hidden="true"
className={cn(
'flex size-9 items-center justify-center rounded-full shadow-xs',
decided === 'approve'
? 'bg-accent-green-light text-accent-green'
: 'bg-accent-red-light text-accent-red',
)}
>
{decided === 'approve' ? <Check className="size-5" /> : <X className="size-5" />}
</span>
<span className="font-semibold">
{decided === 'approve' ? L.confirmApprove : L.confirmReject}
</span>
</div>
)}
</div>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
AI 审批统一件:风险档 + 行动预览 + 单键批准/拒绝 + 决后收场;resolved 受控/非受控双模,onResolve 可返回 Promise;风险方向与置信方向相反。多门堆叠用 approval-gates 组合本件,不要另写一张卡。