# MedHarness Console · UI 视觉与交互设计

> **状态**：DRAFT · 与 [console-product-design.md](console-product-design.md)（产品形态/IA）+ [product-requirements.md](product-requirements.md)（四目标 PRD）对齐。
> **本文职责**：把产品文档 §6 的视觉语言**形式化为设计 token + 组件规范 + 界面用语规范 + 交互态**，供**自建前端**（React 18 + Vite · 复用 new-api **后端**非前端 · 见 [系统设计 03](../system-design/03-frontend-design.md)）直接落地。
> **四目标**：安全 · 划算 · 审计 · 稳定。**2 角色**：研发负责人 / 系统管理员。

---

## 1. 设计基调：Clinical Trust（临床信任）

像一台医疗器械的控制台，不像开发者后台。克制、干净、可信，让非技术背景的研发负责人也敢看敢点。

| 原则 | 落地 |
|---|---|
| 可信优先 | 浅色为主、留白充足、状态明确；信任信号常驻（0 PHI 绿标、审计健康灯） |
| 客户视角措辞（§5） | 界面不写需求/原理/方法论；用客户懂的功能性措辞；技术值留 tooltip |
| 0 PHI 是视觉语言 | 永远只显占位符 `__NAME_a1__`/事件编号/聚合数；原文反查不在 Console 内 |
| 合规/安全分色 | 合规问题与安全问题处置不同，视觉一眼区分（沿用产品文档铁律 7） |
| 四目标可视 | 安全/划算/审计/稳定 总览一屏 |
| 少即是多 | ≤30 人无 SRE → 导航浅、动作少、默认值开箱即用 |

---

## 2. 设计 Token（沿用产品文档 §6 配色，formalize）

```
/* 主色（产品文档已定，沿用） */
--primary:#0B1F3A          /* 深蓝 · 信任/医疗 · 顶栏/标题/主按钮 */
--primary-600:#13315C  --primary-50:#EEF2F8

/* 类别色（铁律 7） */
--compliance:#0FB5A6       /* 合规 · 青绿 */   --compliance-bg:#E6FAF7
--security:#7C3AED         /* 安全 · 紫罗兰 */ --security-bg:#F2EBFE

/* 状态色 */
--ok:#22C55E  --ok-bg:#DCFCE7
--warn:#F59E0B --warn-bg:#FEF3C7
--bad:#EF4444  --bad-bg:#FEE2E2

/* 通道（数据分级路由） */
--lane-normal:#0FB5A6      /* 常规通道（低成本池）≈ 合规青绿 */
--lane-sensitive:#7C3AED   /* 敏感通道（私有不出境）≈ 安全紫 */

/* 成本（划算目标） */
--cost:#A16207  --cost-bg:#FEF9C3

/* 中性 */
--text:#0F172A --text-muted:#64748B --border:#E2E8F0 --bg:#F6F8FA --surface:#FFFFFF
```

- **健康分/四目标卡数字** = 唯一允许的超大字号（40–96px，圆环）。
- 字体：`-apple-system, "PingFang SC", "Microsoft YaHei", Inter`；占位符/哈希/编号用等宽。
- 间距 4/8/12/16/24/32；圆角 6/10/14；克制阴影。

---

## 3. 组件库（自建 · 可选 Semi Design）

顶栏 TopBar（品牌 MedHarness + 环境 + 0 PHI 绿标 + 角色切换）· 侧栏 SideNav · 四目标卡 · 闸门状态卡 · 双向桑基（VChart）· 双色事件流 · 数据表（Semi Table）· 详情抽屉（占位符 prompt）· DIFF 预览 · 审批弹窗（Steps）· 锁定标记 🔒 · 成本图（hbar/趋势）· 导出进度（监管应对包）。

---

## 4. 信息架构与角色（与产品文档 §4 一致）

**2 角色**：研发负责人（总览四目标 + 审批 + 导出）· 系统管理员（接入/渠道/令牌/系统 + 低危项）。工程师不进 Console。

**导航（按四目标）**：🏠 总览 ｜【安全】📊 流量监控 · 🔍 审计与报表 ｜【划算】💰 用量与成本 · 🔌 接入 ｜【治理/运维】⚙️ 策略 · 🛠 系统。（🚦 研发流水线为可选模块，默认关）

> 角色切换 → 即时重渲染落地页；越权动作灰显 + tooltip「需研发负责人」，不隐藏。

---

## 5. 界面用语规范（客户视角 · 去术语 / 去需求化）

> 两条铁律：①界面**不写需求/原理/方法论**（PRD 语言不上 UI），价值用**结果**说话；②用客户的词，工程术语留文档/tooltip。

| 内部 / 工程术语 | 界面用语 |
|---|---|
| 合规安全网关 | 品牌 **MedHarness · 医疗大模型流量网关** |
| 安全闭环 / 成本闭环 | 不出现；导航按四目标分组 |
| 入站闸门 / 出站闸门 | 安全检查（请求）/ 安全检查（响应） |
| clean lane / PHI lane | 常规通道 / 敏感通道 |
| PHI（首次） | 患者隐私信息（PHI） |
| 脱敏 + KMS | 脱敏加密 |
| 模型路由 allowlist | 模型准入（白名单） |
| fail-closed | 默认从严拦截（不直写术语） |
| 哈希链 / WORM | 防篡改 · 不可删改 |
| AUDIT_BUNDLE | 监管应对包 |
| right-sizing | 按需选模型 · 省钱建议 |
| 桑基图 | 不写图表名；标题「流量监控/调用流向」 |
| TTFT / p95 / p99 | 首字延迟 / 响应延迟（技术值放 tooltip） |

**微文案（坏 → 好）**：
- ❌「核心叙事：脱敏把 PHI 剥掉后…合规闸门顺手就是成本闸门。」→ ✅ 删除；成本卡底一行「敏感数据走专属通道，不出境」。
- ❌「桑基图上你永远看不到张三——这是设计不是疏漏。」→ ✅「仅显示脱敏后的占位符与统计，不含原始信息。」

---

## 6. 逐屏要点（四目标对应）

- **🔐 登录**（入口）：全屏深色**科技感**（深蓝渐变 + 动态网格/光晕/上升粒子，沿用品牌青绿/紫）。左 hero＝MedHarness 品牌 + 四目标 + 0 PHI/合规徽章；右玻璃拟态登录卡＝**仅 OIDC 企业 SSO + passkey**，无自助注册/社交登录（认证收敛 PRD FR-F4）。登录后按角色落不同首屏；**工程师不登录**（仅 base_url + 令牌）。注：入口允许比 in-app 更有张力，进入后即回到 §1「临床信任」的克制基调。
- **🏠 总览**（研发负责人）：**四目标卡**（① 安全综合分/100 ② 划算：本月成本/省比/缓存 ③ 审计：链完整/可重放 ④ 稳定：网关延迟/provider 健康/审计 fallback）+ 6 闸门状态 + 风险横幅 + **本月小结**（结果：拦截 N 次/省 ¥X/留痕 K 条）。
- **📊 流量监控**（安全）：双向桑基（请求/响应）+ 双色事件流（合规青绿/安全紫）；只显占位符。
- **🔍 审计与报表**（安全/审计）：事件流 + 检索表 + 行抽屉（占位符 prompt）+「导出监管应对包」。
- **💰 用量与成本**（划算）：成本 KPI + 按通道/模型构成 + 渠道比价择优 + 成本护栏 + 省钱建议。
- **🔌 接入**（系统管理员）：上游 / 渠道（多路·权重·单价·健康）/ 令牌（配额+数据等级）/ **用户与分组管理（复用 new-api 用户体系 · OIDC/passkey · 区分 Console 2 角色与仅用令牌的工程师/服务）**。**无任何转售/支付/注册入口**。
- **⚙️ 策略**：合规 / 安全 / 成本护栏 / 治理审批；改动出 DIFF + 按风险走审批（2 角色矩阵）。
- **🛠 系统**：部署健康（含 ClickHouse/Redis/KMS）+ 备份/升级（稳定运维面）。

---

## 7. 交互态
Loading 骨架屏 · Empty 友好指引 · Healthy 绿「一切正常」· Warning 琥珀 banner+「查看处置」· Blocked 红（结构化文案，不显原文/栈）· Locked 🔒（灰+会签提示）· Planned 🚧（预览态不可保存）。

---

## 8. 与 new-api 的关系（前端自建 · 复用其后端）
**前端自建**（已确认 · 见 [系统设计 03](../system-design/03-frontend-design.md) §1）：Console 是自建 **React 18 + Vite** 应用（**非 fork new-api 前端**）——因 0-PHI 守卫 `Sanitized<T>` 必须在我们代码里。**复用的是 new-api 后端**（网关/渠道/用户/计费 API）。合规/观测屏（总览/流量/审计/策略）自建；**管理面（接入：渠道/令牌/用户）调 new-api 原生管理 API**，UI 在我们壳内重画。图表用 VChart，配色用本文 token。**移除转售相关页（注册/支付/订阅/兑换/充值/钱包/社交登录）**（见 [console-product-design.md §11](console-product-design.md)）。

---

## 9. 配套原型
[prototype/console-demo.html](../../prototype/console-demo.html)（高保真可交互，全合成 0 PHI），实现本规范的四目标 IA、2 角色、双向桑基、用量成本、策略 DIFF+审批，并移除转售 UI。
