---
name: frontend-design-ai-native
description: >-
  AI Native 前端设计原则：按钮矩阵与 AI 自动流转对齐、状态机驱动的
  动态 UI。涉及前端界面设计、按钮/操作设计、状态流转 UI 时触发。
---

# AI Native 前端设计

> 来源：从三国团队（庞统/司马懿/诸葛亮）~2GB 对话历史中蒸馏
> 卡片数：2（批次1卡片9 + 前端设计相关经验）

## 适用场景

- 设计任务状态流转的前端操作按钮时
- 设计 Agent 操作界面时
- 区分"用户操作"和"AI 自动操作"的 UI 边界时

## 经验清单

### 1. 按钮矩阵需与 AI Native 自动流转对齐（severity: medium）

**场景**：设计前端按钮时，Agent 倾向于保留传统 CRUD 风格的所有按钮，忽略了 AI 自动流转的核心理念。

**正确做法**：
1. **AI 自动流转的操作不需要按钮**：认领、开始、提审——这些由 AI 自动完成
2. **用户的通用权利需要按钮**：暂停、取消——所有非终态都有
3. **动态决策项**：特定状态下弹出的选项（如"升级"），不是常驻按钮
4. 按钮设计从"AI 做什么、人做什么"出发，而非从 CRUD 出发

**⚠️ 常见错误**：
- 为每个状态都设计完整操作按钮（认领、开始、提审、通过、打回），忽略 AI 自动认领和流转
- 把"升级"做成常驻按钮而非动态选项
- 没有区分"所有人都能做"和"特定角色才能做"

**关键细节**：
- [frag_0471] 用户说："认领不用，因为都是 AI 自动认领了...提审不要有，要么是 AI 审核...升级不是按钮吧，是动态出来的选项...其实就是暂停和取消"
- [frag_0472] "随时都可以暂停吧？和取消吧？"
- **AI Native = AI 做绝大部分操作，人类只做决策和干预**
- 暂停和取消是用户的通用权利，不限于特定状态
- 实际操作结果 = 暂停 + 取消 两个常驻按钮 + 动态决策项

> 来源：批次1卡片9（按钮设计，freq=2）

---

### 2. 状态机驱动的动态 UI 设计（severity: medium）

**场景**：前端操作按钮应根据当前任务状态动态显示/隐藏，而非静态写死所有按钮。

**正确做法**：
1. 前端维护本地 ACTION_GUARDS 映射表 + `isAllowed()` 函数
2. 按钮显示/隐藏由状态机驱动，不是硬编码
3. 前后端状态枚举必须一致（参见 code-review-quality 中的枚举一致性经验）

**⚠️ 常见错误**：
- 前端按钮条件和后端状态机不同步
- 新增状态后前端忘记更新按钮显示逻辑

**关键细节**：
- v2.7 状态机守卫设计：TASK_TRANSITIONS（自动流转）和 ACTION_GUARDS（用户动作）独立
- 前端 EdictBoard/TaskModal 使用本地 ACTION_GUARDS 映射
- 涉及 UI/API 对接的改动不管多小都走流程——"一个按钮"涉及前端→API→后端三层 [MEMORY.md L5]

> 来源：批次1卡片9 + MEMORY.md L5 + v2.7 状态机设计经验

---

## 检查清单（快速参考）

- [ ] 按钮：AI 自动做的操作（认领/开始/提审）→ 不需要按钮
- [ ] 按钮：用户的通用权利（暂停/取消）→ 所有非终态都显示
- [ ] 动态决策项 → 不是常驻按钮，是特定状态下弹出
- [ ] 前端 ACTION_GUARDS 和后端状态机是否一致？
- [ ] AI Native 原则：AI 做大部分操作，人只做决策和干预
- [ ] UI 改动不管多小都走三层层流程（前端→API→后端）
