# 通知系统实现文档

## 概述

本文档记录了将项目中的原生 `alert()` 和 `confirm()` 替换为自定义通知系统的实现过程。

## 实现日期

2026-01-31

## 架构设计

### 组件结构

```
frontend/
├── components/
│   ├── Toast.tsx                    # Toast 通知组件（已存在）
│   ├── ConfirmDialog.tsx            # 确认对话框组件（新建）
│   └── NotificationExample.tsx      # 使用示例（新建）
├── contexts/
│   └── NotificationContext.tsx      # 通知系统 Context 和 Hooks（新建）
├── App.tsx                          # 添加 NotificationProvider
└── utils/
    └── migrationGuide.md            # 迁移指南（新建）
```

### 核心组件

#### 1. ConfirmDialog 组件
- 模态对话框，用于替换 `confirm()`
- 支持自定义标题、消息、按钮文本
- 支持危险操作（红色按钮）和普通操作（蓝色按钮）
- 点击背景遮罩或 X 按钮可关闭

#### 2. NotificationContext
- 提供全局的通知管理
- 管理 Toast 和 ConfirmDialog 的状态
- 导出 `useToast` 和 `useConfirm` hooks

#### 3. useToast Hook
```typescript
const { showToast } = useToast();
showToast('操作成功', 'success');
showToast('操作失败', 'error');
```

#### 4. useConfirm Hook
```typescript
const { showConfirm } = useConfirm();
const confirmed = await showConfirm({
  title: '确认删除',
  message: '确定要删除这条记录吗？',
  confirmText: '删除',
  cancelText: '取消',
  danger: true
});
```

## 已完成的替换

### 1. CloningPanel.tsx（声音克隆）
- ✅ 替换 5 处 `alert()` 为 `showToast()`
- 涉及场景：
  - 输入验证错误
  - 音频文件验证错误
  - 创建成功/失败提示

### 2. SynthesisPanel.tsx（语音合成）
- ✅ 替换 3 处 `alert()` 为 `showToast()`
- ✅ 替换 1 处 `confirm()` 为 `showConfirm()`
- 涉及场景：
  - 输入验证错误
  - 合成失败提示
  - 删除音色确认

### 3. MultimodalTranslation.tsx（多模态翻译）
- ✅ 替换 1 处 `confirm()` 为 `showConfirm()`
- 涉及场景：
  - 删除翻译记录确认

## 待替换的文件

### 高优先级
- [x] `frontend/components/audio/SynthesisPanel.tsx` - 3 处 alert, 1 处 confirm
- [ ] `frontend/components/audio/LongTextPanel.tsx` - 2 处 alert
- [ ] `frontend/pages/ImageTranslation.tsx` - 2 处 alert, 2 处 confirm
- [ ] `frontend/pages/DataMining.tsx` - 9 处 alert, 4 处 confirm

### 中优先级
- [ ] `frontend/pages/InvoiceManagement.tsx` - 5 处 alert
- [ ] `frontend/pages/InvoiceApply.tsx` - 3 处 alert
- [ ] `frontend/pages/Billing.tsx` - 2 处 alert
- [ ] `frontend/pages/DeepResearch.tsx` - 1 处 confirm
- [ ] `frontend/pages/ResearchHistory.tsx` - 1 处 confirm

### 低优先级
- [ ] `frontend/components/ocr/ImageUploadZone.tsx` - 3 处 alert
- [ ] `frontend/components/HistoryTable.examples.tsx` - 1 处 confirm

## 使用指南

### 基本用法

1. **导入 Hooks**
```typescript
import { useToast } from '../contexts/NotificationContext';
import { useConfirm } from '../contexts/NotificationContext';
```

2. **在组件中使用**
```typescript
const MyComponent = () => {
  const { showToast } = useToast();
  const { showConfirm } = useConfirm();
  
  const handleSave = async () => {
    try {
      await saveData();
      showToast('保存成功', 'success');
    } catch (error) {
      showToast('保存失败', 'error');
    }
  };
  
  const handleDelete = async () => {
    const confirmed = await showConfirm({
      title: '确认删除',
      message: '确定要删除吗？',
      danger: true
    });
    
    if (confirmed) {
      await deleteData();
      showToast('删除成功', 'success');
    }
  };
};
```

### 替换模式

#### Alert → Toast
```typescript
// 旧代码
alert('操作成功');

// 新代码
showToast('操作成功', 'success');
```

#### Confirm → showConfirm
```typescript
// 旧代码
if (!confirm('确定删除吗？')) return;

// 新代码
const confirmed = await showConfirm({
  message: '确定删除吗？',
  danger: true
});
if (!confirmed) return;
```

## 优势

1. **更好的用户体验**
   - 美观的 UI 设计
   - 平滑的动画效果
   - 非阻塞式通知

2. **更灵活的配置**
   - 自定义标题、消息、按钮文本
   - 支持危险操作样式
   - 支持多行消息

3. **更好的可维护性**
   - 统一的通知管理
   - 类型安全
   - 易于测试

4. **更好的可访问性**
   - 支持键盘操作
   - 语义化的 HTML
   - ARIA 标签

## 技术细节

### Toast 自动消失
- 默认 2.5 秒后自动消失
- 可通过 `duration` 参数自定义
- 支持手动关闭

### Confirm 对话框
- 使用 Promise 返回用户选择
- 支持点击背景遮罩关闭
- 支持 ESC 键关闭（可扩展）

### 状态管理
- 使用 React Context 管理全局状态
- 避免 prop drilling
- 支持多个通知同时显示（可扩展）

## 后续优化建议

1. **支持多个 Toast 同时显示**
   - 当前只支持一个 Toast
   - 可以改为队列模式

2. **支持更多通知类型**
   - info（信息）
   - warning（警告）

3. **支持自定义位置**
   - 顶部、底部、左侧、右侧

4. **支持键盘快捷键**
   - ESC 关闭对话框
   - Enter 确认操作

5. **支持自定义动画**
   - 滑入、淡入、缩放等

## 测试建议

1. **功能测试**
   - Toast 正常显示和消失
   - Confirm 对话框正常弹出和关闭
   - 按钮点击正确返回结果

2. **边界测试**
   - 长文本消息显示
   - 快速连续触发
   - 组件卸载时的清理

3. **可访问性测试**
   - 键盘导航
   - 屏幕阅读器支持
   - 焦点管理

## 参考资料

- [Toast 组件源码](../frontend/components/Toast.tsx)
- [ConfirmDialog 组件源码](../frontend/components/ConfirmDialog.tsx)
- [NotificationContext 源码](../frontend/contexts/NotificationContext.tsx)
- [使用示例](../frontend/components/NotificationExample.tsx)
- [迁移指南](../frontend/utils/migrationGuide.md)