nodeskclaw / rules

---
description: Plan 必须包含前端表现层变化摘要，让用户无需阅读代码即可理解改动影响
alwaysApply: true
---

# Plan 前端表现变化摘要

## 规则

**每个 Plan 必须包含「前端表现变化」章节**，从用户可感知的黑盒视角描述 UI 层面会发生什么变化。

用户不应被迫阅读每一行代码改动才能理解 plan 做了什么。这个章节用最直白的语言告诉用户：哪个页面、哪个元素、从什么样变成什么样。

**此章节放在技术改动步骤之前**（让用户先建立直觉再看技术细节）。

## 描述结构

每条前端变化必须包含以下三层描述：

### 第一层：用户视角总结

一句话概括这块 UI 改了什么，用"原来 -> 现在"的格式。

```
**总结**: Working Plan 单选按钮从"只要 provider 支持就可选"改为"provider 支持 + 组织已配置 Key 才可选"
```

### 第二层：元素级变化清单

逐条列出增删改的 UI 元素，必须覆盖以下维度：

- **新增了什么**：按钮、输入框、文案、图标、Tab、Tooltip、卡片、弹窗等
- **删除了什么**：移除的元素
- **状态变化**：enabled -> disabled、visible -> hidden、展开 -> 折叠等
- **样式变化**：颜色、透明度、鼠标指针、字号等从什么变成什么
- **交互行为变化**：点击响应、hover 效果、默认选中状态、自动回退逻辑等

```
**元素级变化**:
- Working Plan radio button: 组织未配置该 provider Key 时 -> disabled 态，文字置灰（opacity-50），鼠标变为 not-allowed
- Working Plan radio hover tooltip: **新增**，禁用时 hover 显示"管理员未配置..."
- 个人 Key radio button: 当 Working Plan 不可用时 -> **自动选中**（之前默认选 Working Plan）
- Key 输入框区域: 因默认选中"个人 Key"而**立即展开**（之前隐藏）
```

### 第三层：UI 简图（条件触发）

用 ASCII art 画出改动前/后的 UI 示意图，让用户一眼看到布局和元素位置。

**必须画图的场景**：
- 新增或删除了可见区域（卡片、Tab、面板、弹窗）
- 布局重排（元素位置调整、分栏变化）
- 交互流程变化（新增步骤、状态切换）
- 元素状态对比（enabled vs disabled、展开 vs 折叠）
- 单靠文字描述不够直观的任何场景

**可以省略的场景**：
- 纯文案替换（如"取消"改为"关闭"）
- 颜色/字号微调且无布局影响

```
**改动前**（组织未配 Key，provider 为 minimax-openai）:
┌─ minimax-openai ──────────────────────────┐
│  (●) Working Plan    (○) 个人 Key          │
│  使用组织统一配置的 Key，无需自行输入          │
│  [Key 输入框隐藏]                           │
└────────────────────────────────────────────┘
-> 用户选了 Working Plan，后续使用时才报错

**改动后**:
┌─ minimax-openai ──────────────────────────┐
│  (○) Working Plan    (●) 个人 Key          │
│      ↑ disabled          ↑ 默认选中        │
│      ┌───────────────────────────────┐     │
│      │ 管理员未配置该 Provider 的      │     │
│      │ Working Plan，请联系管理员      │     │
│      └───────────────────────────────┘     │
│  ┌────────────────────────────────────┐    │
│  │  Key  请输入 API Key               │    │
│  └────────────────────────────────────┘    │
└────────────────────────────────────────────┘
```

## 完整示例

```
### 前端表现变化

#### 1. Portal 创建实例页 - LLM Key 来源选择器

**总结**: Working Plan 单选按钮从"只要 provider 支持就可选"改为"provider 支持 + 组织已配置 Key 才可选"

**元素级变化**:
- Working Plan radio button: 组织未配置该 provider Key 时 -> disabled 态，文字置灰（opacity-50），鼠标变为 not-allowed
- Working Plan radio hover tooltip: 新增，禁用时 hover 显示"管理员未配置该 Provider 的 Working Plan，请联系管理员"
- 个人 Key radio button: 当 Working Plan 不可用时 -> 自动选中（之前默认选 Working Plan）
- Key 输入框区域: 因默认选中"个人 Key"而立即展开

**改动前**（组织未配 Key）:
┌─ minimax-openai ──────────────────────┐
│  (●) Working Plan    (○) 个人 Key     │
│  使用组织统一配置的 Key，无需自行输入    │
└───────────────────────────────────────┘
-> 用户选了 Working Plan，后续使用时才报错

**改动后**:
┌─ minimax-openai ──────────────────────┐
│  (○) Working Plan    (●) 个人 Key     │
│      ↑ disabled          ↑ 默认选中   │
│      ┌────────────────────────────┐   │
│      │ 管理员未配置该 Provider 的   │   │
│      │ Working Plan，请联系管理员   │   │
│      └────────────────────────────┘   │
│  ┌──────────────────────────────────┐ │
│  │ Key  请输入 API Key              │ │
│  └──────────────────────────────────┘ │
└───────────────────────────────────────┘

#### 2. Admin 系统设置页

**总结**: 新增「SMTP 邮件配置」卡片

**元素级变化**:
- 「SMTP 邮件配置」卡片: **新增**，位于系统设置页底部
- 卡片内包含: 服务器地址输入框、端口输入框、发件人邮箱输入框、密码输入框、TLS 开关、测试发送按钮
- 测试发送按钮: 点击后发送测试邮件，成功/失败 toast 提示

**改动后**:
┌─ 系统设置 ────────────────────────────┐
│  ... 已有设置项 ...                    │
│                                       │
│  ┌─ SMTP 邮件配置 ──────────────────┐ │
│  │  服务器地址  [____________]       │ │
│  │  端口       [____]               │ │
│  │  发件人     [____________]       │ │
│  │  密码       [____________]       │ │
│  │  TLS       [开关]                │ │
│  │           [测试发送] [保存]       │ │
│  └──────────────────────────────────┘ │
└───────────────────────────────────────┘
```

## 适用范围

- 涉及前端改动的 plan：**必须写**，按上述三层结构逐条列出
- 纯后端/基础设施 plan（无任何前端变化）：写「本次改动无前端表现变化」，一行即可
- 修复类 plan（如消息发不出去）：描述修复前后的用户体验差异（如「Agent 发送消息后对方实际收不到 -> 修复后消息正常投递」），视情况画图

## 禁止

- 禁止用技术术语替代用户视角描述（写「登录页新增验证码 Tab」，不要写「LoginView.vue 新增 TabsTrigger 组件」）
- 禁止只写第一层总结就跳过元素级清单 -- 三层结构缺一不可（简图按条件触发除外）
- 禁止在元素级变化中只说"改了"但不说"从什么变成什么"
- 禁止省略此章节