Cursor rule

1---
2description: Plan 必须包含前端表现层变化摘要，让用户无需阅读代码即可理解改动影响
3alwaysApply: true
4---
5 
6# Plan 前端表现变化摘要
7 
8## 规则
9 
10**每个 Plan 必须包含「前端表现变化」章节**，从用户可感知的黑盒视角描述 UI 层面会发生什么变化。
11 
12用户不应被迫阅读每一行代码改动才能理解 plan 做了什么。这个章节用最直白的语言告诉用户：哪个页面、哪个元素、从什么样变成什么样。
13 
14**此章节放在技术改动步骤之前**（让用户先建立直觉再看技术细节）。
15 
16## 描述结构
17 
18每条前端变化必须包含以下三层描述：
19 
20### 第一层：用户视角总结
21 
22一句话概括这块 UI 改了什么，用"原来 -> 现在"的格式。
23 
24```
25**总结**: Working Plan 单选按钮从"只要 provider 支持就可选"改为"provider 支持 + 组织已配置 Key 才可选"
26```
27 
28### 第二层：元素级变化清单
29 
30逐条列出增删改的 UI 元素，必须覆盖以下维度：
31 
32- **新增了什么**：按钮、输入框、文案、图标、Tab、Tooltip、卡片、弹窗等
33- **删除了什么**：移除的元素
34- **状态变化**：enabled -> disabled、visible -> hidden、展开 -> 折叠等
35- **样式变化**：颜色、透明度、鼠标指针、字号等从什么变成什么
36- **交互行为变化**：点击响应、hover 效果、默认选中状态、自动回退逻辑等
37 
38```
39**元素级变化**:
40- Working Plan radio button: 组织未配置该 provider Key 时 -> disabled 态，文字置灰（opacity-50），鼠标变为 not-allowed
41- Working Plan radio hover tooltip: **新增**，禁用时 hover 显示"管理员未配置..."
42- 个人 Key radio button: 当 Working Plan 不可用时 -> **自动选中**（之前默认选 Working Plan）
43- Key 输入框区域: 因默认选中"个人 Key"而**立即展开**（之前隐藏）
44```
45 
46### 第三层：UI 简图（条件触发）
47 
48用 ASCII art 画出改动前/后的 UI 示意图，让用户一眼看到布局和元素位置。
49 
50**必须画图的场景**：
51- 新增或删除了可见区域（卡片、Tab、面板、弹窗）
52- 布局重排（元素位置调整、分栏变化）
53- 交互流程变化（新增步骤、状态切换）
54- 元素状态对比（enabled vs disabled、展开 vs 折叠）
55- 单靠文字描述不够直观的任何场景
56 
57**可以省略的场景**：
58- 纯文案替换（如"取消"改为"关闭"）
59- 颜色/字号微调且无布局影响
60 
61```
62**改动前**（组织未配 Key，provider 为 minimax-openai）:
63┌─ minimax-openai ──────────────────────────┐
64│  (●) Working Plan    (○) 个人 Key          │
65│  使用组织统一配置的 Key，无需自行输入          │
66│  [Key 输入框隐藏]                           │
67└────────────────────────────────────────────┘
68-> 用户选了 Working Plan，后续使用时才报错
69 
70**改动后**:
71┌─ minimax-openai ──────────────────────────┐
72│  (○) Working Plan    (●) 个人 Key          │
73│      ↑ disabled          ↑ 默认选中        │
74│      ┌───────────────────────────────┐     │
75│      │ 管理员未配置该 Provider 的      │     │
76│      │ Working Plan，请联系管理员      │     │
77│      └───────────────────────────────┘     │
78│  ┌────────────────────────────────────┐    │
79│  │  Key  请输入 API Key               │    │
80│  └────────────────────────────────────┘    │
81└────────────────────────────────────────────┘
82```
83 
84## 完整示例
85 
86```
87### 前端表现变化
88 
89#### 1. Portal 创建实例页 - LLM Key 来源选择器
90 
91**总结**: Working Plan 单选按钮从"只要 provider 支持就可选"改为"provider 支持 + 组织已配置 Key 才可选"
92 
93**元素级变化**:
94- Working Plan radio button: 组织未配置该 provider Key 时 -> disabled 态，文字置灰（opacity-50），鼠标变为 not-allowed
95- Working Plan radio hover tooltip: 新增，禁用时 hover 显示"管理员未配置该 Provider 的 Working Plan，请联系管理员"
96- 个人 Key radio button: 当 Working Plan 不可用时 -> 自动选中（之前默认选 Working Plan）
97- Key 输入框区域: 因默认选中"个人 Key"而立即展开
98 
99**改动前**（组织未配 Key）:
100┌─ minimax-openai ──────────────────────┐
101│  (●) Working Plan    (○) 个人 Key     │
102│  使用组织统一配置的 Key，无需自行输入    │
103└───────────────────────────────────────┘
104-> 用户选了 Working Plan，后续使用时才报错
105 
106**改动后**:
107┌─ minimax-openai ──────────────────────┐
108│  (○) Working Plan    (●) 个人 Key     │
109│      ↑ disabled          ↑ 默认选中   │
110│      ┌────────────────────────────┐   │
111│      │ 管理员未配置该 Provider 的   │   │
112│      │ Working Plan，请联系管理员   │   │
113│      └────────────────────────────┘   │
114│  ┌──────────────────────────────────┐ │
115│  │ Key  请输入 API Key              │ │
116│  └──────────────────────────────────┘ │
117└───────────────────────────────────────┘
118 
119#### 2. Admin 系统设置页
120 
121**总结**: 新增「SMTP 邮件配置」卡片
122 
123**元素级变化**:
124- 「SMTP 邮件配置」卡片: **新增**，位于系统设置页底部
125- 卡片内包含: 服务器地址输入框、端口输入框、发件人邮箱输入框、密码输入框、TLS 开关、测试发送按钮
126- 测试发送按钮: 点击后发送测试邮件，成功/失败 toast 提示
127 
128**改动后**:
129┌─ 系统设置 ────────────────────────────┐
130│  ... 已有设置项 ...                    │
131│                                       │
132│  ┌─ SMTP 邮件配置 ──────────────────┐ │
133│  │  服务器地址  [____________]       │ │
134│  │  端口       [____]               │ │
135│  │  发件人     [____________]       │ │
136│  │  密码       [____________]       │ │
137│  │  TLS       [开关]                │ │
138│  │           [测试发送] [保存]       │ │
139│  └──────────────────────────────────┘ │
140└───────────────────────────────────────┘
141```
142 
143## 适用范围
144 
145- 涉及前端改动的 plan：**必须写**，按上述三层结构逐条列出
146- 纯后端/基础设施 plan（无任何前端变化）：写「本次改动无前端表现变化」，一行即可
147- 修复类 plan（如消息发不出去）：描述修复前后的用户体验差异（如「Agent 发送消息后对方实际收不到 -> 修复后消息正常投递」），视情况画图
148 
149## 禁止
150 
151- 禁止用技术术语替代用户视角描述（写「登录页新增验证码 Tab」，不要写「LoginView.vue 新增 TabsTrigger 组件」）
152- 禁止只写第一层总结就跳过元素级清单 -- 三层结构缺一不可（简图按条件触发除外）
153- 禁止在元素级变化中只说"改了"但不说"从什么变成什么"
154- 禁止省略此章节
155