makemd/docs/ARCHIVE/03_Frontend/04_Interaction_Guidelines.md

# 统一交互规范

> **Crawlful Hub 前端交互设计标准**

---

## 🎯 核心原则

### 1. 所有操作必须有反馈

```text
loading → success / error
```

**实现方式**：
- 使用 `BusinessLoading` 组件显示加载状态
- 使用 `BusinessMessage` 组件显示操作结果
- 操作按钮在加载期间应显示 loading 状态

### 2. 所有“影响钱”的操作必须有提示

**实现方式**：
- 修改价格时显示 ROI 变化
- 批量操作前显示确认对话框
- 重要操作后显示详细的结果反馈

### 3. 所有列表必须支持

```text
分页 / 筛选 / 排序
```

**实现方式**：
- 使用 `BusinessTable` 组件，默认支持分页
- 为表格添加排序功能
- 在页面顶部添加筛选栏

### 4. 所有弹窗统一

- **宽度**：600px（默认）
- **按钮位置**：底部右侧，确认按钮在左，取消按钮在右
- **提交流程**：loading → success / error → 关闭弹窗

---

## 📦 组件交互规范

### BusinessButton

**使用场景**：
- 页面级操作（创建、导入、导出）
- 行级操作（编辑、删除、查看）
- 批量操作（批量修改、批量删除）

**交互规范**：
- 点击按钮后显示 loading 状态
- 操作完成后显示 success/error 消息
- 禁用状态时应显示相应样式

### BusinessCard

**使用场景**：
- 数据展示
- 功能模块分组
- 信息汇总

**交互规范**：
- 卡片应有明确的标题
- 可添加额外操作按钮
- 卡片内容应布局合理

### BusinessTable

**使用场景**：
- 商品列表
- 订单列表
- 广告列表

**交互规范**：
- 支持分页（默认每页10条）
- 支持列排序
- 支持行选择
- 支持行操作按钮

### BusinessModal

**使用场景**：
- 编辑表单
- 确认操作
- 详细信息展示

**交互规范**：
- 标题应明确操作目的
- 内容区域应布局合理
- 底部按钮应符合统一位置
- 提交时显示 loading 状态

### BusinessForm

**使用场景**：
- 商品创建/编辑
- 订单处理
- 广告配置

**交互规范**：
- 表单验证应实时反馈
- 提交按钮应显示 loading 状态
- 错误信息应清晰可见

### BusinessMessage

**使用场景**：
- 操作结果反馈
- 错误提示
- 成功提示

**交互规范**：
- 消息应自动消失（默认3秒）
- 错误消息应使用红色
- 成功消息应使用绿色
- 警告消息应使用黄色

### BusinessLoading

**使用场景**：
- API请求
- 数据加载
- 复杂计算

**交互规范**：
- 应显示加载动画
- 可添加加载提示文本
- 应覆盖在操作区域

---

## 📱 页面交互规范

### Product 页面

**核心交互**：
- 修改价格时实时计算 ROI
- AI定价时显示 loading 状态和建议价格
- 上下架操作应显示确认对话框
- 批量操作应显示操作结果

### Orders 页面

**核心交互**：
- 订单状态更新时显示 loading 状态
- 发货操作应要求输入物流信息
- 退款操作应显示确认对话框
- 批量操作应显示操作结果

### Dashboard 页面

**核心交互**：
- 时间范围选择时更新所有数据
- 点击 KPI 卡片跳转到详情页面
- 图表应支持时间范围筛选

### Ad 页面

**核心交互**：
- 广告启停操作应显示确认对话框
- AI优化时显示 loading 状态和优化建议
- 批量操作应显示操作结果

### Finance 页面

**核心交互**：
- 账单详情查看应显示详细的收支明细
- 导出操作应显示操作结果
- 筛选条件变化时更新数据

---

## 🎨 视觉交互规范

### 颜色系统

- **主色**：#1890ff
- **成功**：#52c41a
- **警告**：#faad14
- **错误**：#f5222d
- **信息**：#1890ff

### 字体系统

- **标题**：16px / 20px
- **正文**：14px
- **小文本**：12px

### 间距系统

- **页面边距**：16px
- **卡片间距**：16px
- **按钮间距**：8px
- **输入框高度**：32px

### 动画效果

- **按钮点击**：轻微缩放
- **弹窗出现**：淡入效果
- **加载状态**：旋转动画
- **消息提示**：滑入效果

---

## 🔧 技术实现规范

### 状态管理

- 使用 React Context API 或 Redux 管理全局状态
- 组件内部状态使用 useState
- 异步操作使用 useEffect

### 数据请求

- 使用 axios 进行 API 请求
- 统一处理请求错误
- 添加请求超时处理

### 错误处理

- 全局错误边界
- 组件级错误处理
- 用户友好的错误提示

### 性能优化

- 组件懒加载
- 数据缓存
- 防抖和节流

## 5. 用户体验优化

### 5.1 界面优化

- **响应式设计**：适配不同设备屏幕
- **操作流程简化**：减少用户操作步骤
- **批量操作界面**：支持多选和批量操作
- **拖拽排序**：部门和用户的拖拽排序

### 5.2 通知与提醒

- **系统通知**：重要操作的系统通知
- **邮件提醒**：权限变更、邀请等邮件提醒
- **站内信**：系统内部消息通知
- **操作确认**：重要操作的二次确认

---

## 📋 验收标准

### 页面交互验收

- [ ] 所有操作都有 loading 状态
- [ ] 所有操作都有 success/error 反馈
- [ ] 所有列表都支持分页、筛选、排序
- [ ] 所有弹窗都符合统一规范
- [ ] 所有“影响钱”的操作都有提示

### 组件交互验收

- [ ] BusinessButton 符合交互规范
- [ ] BusinessCard 符合交互规范
- [ ] BusinessTable 符合交互规范
- [ ] BusinessModal 符合交互规范
- [ ] BusinessForm 符合交互规范
- [ ] BusinessMessage 符合交互规范
- [ ] BusinessLoading 符合交互规范

### 视觉交互验收

- [ ] 颜色使用符合规范
- [ ] 字体使用符合规范
- [ ] 间距使用符合规范
- [ ] 动画效果符合规范

---

## 🚀 实施计划

### 第一阶段：组件规范
- 实现统一的组件库
- 定义组件交互规范
- 编写组件使用文档

### 第二阶段：页面规范
- 应用组件库到所有页面
- 实现页面级交互规范
- 测试页面交互效果

### 第三阶段：系统规范
- 统一全局交互行为
- 优化用户体验
- 编写系统交互文档

---

> **统一交互规范是确保系统一致性和用户体验的关键**
> **所有前端开发必须严格遵循本规范**