# UI 提示系统重构计划

## 需求分析

用户要求重新设计并实现一个轻量 UI 提示系统，包含：

1. **Toast（右上角）** - 瞬时提示，无状态设计
2. **Task Center（右下角任务中心）** - 长任务状态系统，有状态

核心要求：
- 两者完全独立，不共享逻辑
- Task 必须通用化，不绑定具体业务类型
- 实现 UI Lock 机制
- 支持多语言国际化

---

## 架构设计

### 1. 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                     UI 提示系统                              │
├───────────────────────────┬─────────────────────────────────┤
│        Toast 系统         │         Task Center 系统         │
│  (右上角，无状态)          │      (右下角，有状态)             │
├───────────────────────────┼─────────────────────────────────┤
│ • 自动消失                │ • 手动关闭                      │
│ • 多条堆叠                │ • 单一实例                      │
│ • 类型：success/error/   │ • 生命周期独立                  │
│   info/warning           │ • 进度追踪                      │
└───────────────────────────┴─────────────────────────────────┘
```

### 2. Toast API

```js
showToast({
  title,        // 标题
  message,      // 消息内容
  type: "success | error | info | warning",
  duration      // 显示时长（毫秒）
});
```

### 3. Task API

```js
// 创建任务
startTask({
  id,           // 任务ID
  title,        // 任务标题（国际化key）
  total,        // 总数量
  current,      // 当前进度
  currentItem   // 当前处理项
});

// 更新任务
updateTask({
  id,           // 任务ID
  current,      // 当前进度
  currentItem   // 当前处理项
});

// 完成任务
finishTask({
  id,           // 任务ID
  total,        // 总数量
  success,      // 成功数量
  failed        // 失败数量
});

// 手动关闭
closeTask(id);
```

---

## 修改内容

### 1. 修改 CSS 文件 (`custom-file/index.css`)

**新增样式：**
- Toast 容器样式（右上角固定定位）
- Toast 单条样式（支持不同类型）
- Toast 动画（进入/退出）
- Task Center 容器样式（右下角固定定位）
- Task Center 进度条样式
- Task Center 结果展示样式
- UI Lock 样式

**删除旧样式：**
- 删除 `.task-dock` 相关样式（如仍存在）

### 2. 修改 JS 文件 (`custom-file/index.js`)

**新增方法：**

| 方法名 | 功能 |
|--------|------|
| `showToast` | 显示 Toast 提示 |
| `startTask` | 创建并启动任务 |
| `updateTask` | 更新任务进度 |
| `finishTask` | 完成任务 |
| `closeTask` | 关闭任务 UI |
| `lockUI` | 锁定 UI |
| `unlockUI` | 解锁 UI |
| `isUILocked` | 检查 UI 是否锁定 |

**修改方法：**
- `render` - 添加 Toast 和 Task Center 的 DOM 结构
- `internalDownloadBatch` - 使用新的 Task API

**删除方法：**
- `addTask`（旧版本）
- `updateTask`（旧版本）
- `finishTask`（旧版本）
- `clearTasks`（旧版本）
- `updateTaskStats`（旧版本）

### 3. 新增多语言配置

```js
languages: {
  "zh-CN": {
    // ... 现有配置
    toast: {
      success: "成功",
      error: "错误",
      info: "提示",
      warning: "警告"
    },
    task: {
      title: {
        processing: "处理中"
      },
      total: "总计",
      success: "成功",
      failed: "失败",
      currentItem: "当前项",
      close: "关闭"
    }
  },
  "en-US": {
    // ... 现有配置
    toast: {
      success: "Success",
      error: "Error",
      info: "Info",
      warning: "Warning"
    },
    task: {
      title: {
        processing: "Processing"
      },
      total: "Total",
      success: "Success",
      failed: "Failed",
      currentItem: "Current",
      close: "Close"
    }
  }
}
```

---

## 实施步骤

| 步骤 | 任务 | 文件 | 状态 |
|------|------|------|------|
| 1 | 添加 Toast 和 Task Center 的 CSS 样式 | `custom-file/index.css` | 待执行 |
| 2 | 更新多语言配置 | `custom-file/index.js` | 待执行 |
| 3 | 添加 Toast 相关方法 | `custom-file/index.js` | 待执行 |
| 4 | 添加 Task Center 相关方法 | `custom-file/index.js` | 待执行 |
| 5 | 添加 UI Lock 机制 | `custom-file/index.js` | 待执行 |
| 6 | 修改 render 方法添加 DOM 结构 | `custom-file/index.js` | 待执行 |
| 7 | 修改 internalDownloadBatch 使用新 API | `custom-file/index.js` | 待执行 |
| 8 | 删除旧的任务管理方法 | `custom-file/index.js` | 待执行 |

---

## 风险评估

| 风险项 | 风险等级 | 处理方式 |
|--------|----------|----------|
| Task 状态与 UI 不同步 | 中 | 确保 task 对象独立于 UI 存在 |
| Toast 堆叠过多 | 低 | 限制最大显示数量（如5条） |
| UI Lock 状态异常 | 中 | 在任务完成时强制解锁 |
| 多语言文案遗漏 | 低 | 统一使用 `this.language.xxx` 模式 |

---

## 兼容性

- 原有 API 调用保持兼容
- 新增 API 为可选参数
- 不影响现有文件管理功能

---

## 最终目标

实现一个 **"通用任务系统 + Toast 提示系统 + UI Lock + i18n"** 的轻量 UI 架构，支持未来扩展：
- 批量上传
- 批量下载
- 批量删除
- 任意异步任务

无需修改核心结构，仅通过 task 数据驱动。