# 回收站功能设计方案

# 软件维护需求描述

## 1.1 开源软件维护新增功能描述

为了改善开源软件中现有功能/性能的不足，并结合实际问题，构思的开源软件新功能描述如表1-1所示。

表1-1 软件新增功能描述表

| **功能名称** | **功能描述**                                                 |
| ------------ | ------------------------------------------------------------ |
| 回收站功能 | 为便签应用添加回收站功能，提供更安全的便签管理体验。主要功能包括：<br>1. 删除的便签不直接销毁，而是移动到回收站<br>2. 支持从回收站恢复便签到原始文件夹<br>3. 支持彻底删除回收站中的便签<br>4. 支持自定义回收站自动清理时间间隔<br>5. 限制回收站容量，防止占用过多空间 |

## 1.2 开源软件维护需求

### 1.2.1 用例图

```
+------------------+       +------------------+
|                  |       |                  |
|      用户        +------>+  打开回收站      |
|                  |       |                  |
+------------------+       +-------+----------+
                                   |
              +--------------------+--------------------+
              |                    |                    |
              v                    v                    v
     +------------------+ +------------------+ +------------------+
     |                  | |                  | |                  |
     |   恢复便签       | |   彻底删除便签   | |   设置清理间隔   |
     |                  | |                  | |                  |
     +------------------+ +------------------+ +------------------+
              |                    |                    |
              v                    v                    v
     +------------------+ +------------------+ +------------------+
     |                  | |                  | |                  |
     | 返回原始文件夹   | |   清空回收站     | |   选择天数       |
     |                  | |                  | |                  |
     +------------------+ +------------------+ +------------------+
```

### 1.2.2 用例描述

**用例：回收站管理**

**用例名称:** 回收站管理

**功能:** 允许用户查看、恢复或彻底删除已删除的便签，并设置自动清理间隔

**执行者:** 用户

**触发条件:** 用户打开回收站界面

**前置条件:**
1. 用户已登录并具有编辑权限
2. 系统已安装并正常运行
3. 数据库中包含状态为"已删除"的便签记录

**基本交互动作过程:**
1. 用户点击回收站图标进入回收站界面
2. 系统显示所有已删除的便签列表，按删除时间排序
3. 用户可以选择：
   - 点击便签查看详细内容
   - 长按便签打开上下文菜单进行操作
   - 点击底部的清空回收站按钮
   - 点击清理设置按钮配置自动清理参数
4. 用户选择恢复便签
   - 系统将便签恢复到原始文件夹
   - 若原始文件夹不存在，则恢复到根目录
5. 用户选择彻底删除便签
   - 系统彻底删除便签数据
6. 用户设置自动清理间隔
   - 系统保存设置并安排定时清理任务

**扩展交互动作过程:**
1. 回收站为空
   - 系统显示空白视图和提示信息
2. 回收站容量达到上限
   - 系统按照先进先出原则自动删除最早的便签
3. 用户取消操作
   - 系统不执行任何删除或恢复操作
4. 用户选择全部清空
   - 系统提示确认操作
   - 用户确认后彻底删除所有回收站中的便签

**后置条件:**
1. 恢复的便签状态已更改为正常并从回收站移除
2. 彻底删除的便签已从数据库中移除
3. 自动清理设置已保存并生效

**业务规则:**
1. 回收站容量上限为50条便签
2. 默认自动清理间隔为30天
3. 清理间隔最小1天，最大365天
4. 恢复便签时应保留原有属性和内容

**非功能需求:**
1. 回收站列表加载时间不超过1秒
2. 恢复和删除操作响应时间不超过2秒
3. 自动清理任务执行时不影响用户操作的流畅性

# 一、软件维护需求分析

## 2.1 用例顺序图

**用例：回收站管理**

```
+------+          +----------+          +---------------+          +----------------+
|      |          |          |          |               |          |                |
| 用户 |          | 回收站UI |          | 数据管理器    |          | 数据库Provider |
|      |          |          |          |               |          |                |
+------+          +----------+          +---------------+          +----------------+
   |                   |                       |                         |
   | 打开回收站        |                       |                         |
   |------------------>|                       |                         |
   |                   |                       |                         |
   |                   | 请求已删除便签列表    |                         |
   |                   |---------------------->|                         |
   |                   |                       |                         |
   |                   |                       | 查询已删除便签          |
   |                   |                       |------------------------>|
   |                   |                       |                         |
   |                   |                       |<------------------------|
   |                   |                       | 返回便签列表            |
   |                   |                       |                         |
   |                   |<----------------------|                         |
   |                   | 显示便签列表          |                         |
   |                   |                       |                         |
   | 选择恢复便签      |                       |                         |
   |------------------>|                       |                         |
   |                   |                       |                         |
   |                   | 请求恢复便签          |                         |
   |                   |---------------------->|                         |
   |                   |                       |                         |
   |                   |                       | 恢复便签到原始文件夹    |
   |                   |                       |------------------------>|
   |                   |                       |                         |
   |                   |                       |<------------------------|
   |                   |                       | 确认恢复成功            |
   |                   |                       |                         |
   |                   |<----------------------|                         |
   |                   | 显示成功提示          |                         |
   |                   |                       |                         |
   |<------------------|                       |                         |
   | 更新后的列表      |                       |                         |
   |                   |                       |                         |
```

## 2.2 分析类图

```
+---------------------+       +------------------------+
|  TrashListActivity  |       |  DataUtils             |
|---------------------|       |------------------------|
| -mListView          |<----->| +batchMoveToTrash()    |
| -mAdapter           |       | +batchRestoreFromTrash()|
| +loadTrashNotes()   |       | +batchPermanentlyDelete()|
| +restoreNote()      |       | +getTrashCleanInterval()|
| +deleteNote()       |       | +setTrashCleanInterval()|
+---------------------+       +------------------------+
         ^                              ^
         |                              |
         |                              |
+---------------------+       +------------------------+
| NotePreviewActivity |       | CleanupScheduler       |
|---------------------|       |------------------------|
| +showNote()         |<----->| +scheduleNextCleanup() |
| +restoreNote()      |       | +cleanupTrashNow()     |
| +deleteNote()       |       | +performCleanup()      |
+---------------------+       +------------------------+
         ^                              ^
         |                              |
+---------------------+                 |
| TrashAdapter        |                 |
|---------------------|                 |
| -mContext           |---------------->|
| -mCursor            |
| +getView()          |
+---------------------+
```

# 二、维护设计和实现方案

## 3.1 开源软件体系结构的设计及调整

1. 数据层调整
   - 修改数据库结构，添加记录便签状态和删除日期的字段
   - 扩展 `Notes` 类，添加便签状态常量和回收站相关设置
   - 升级数据库版本，确保结构更新

2. 业务逻辑层调整
   - 扩展 `DataUtils` 类，增加回收站相关操作方法
   - 添加 `CleanupScheduler` 服务，负责回收站自动清理
   - 修改便签删除逻辑，改为软删除

3. 界面层调整
   - 添加 `TrashListActivity` 展示回收站内容
   - 添加 `NotePreviewActivity` 查看已删除便签
   - 修改 `NotesListActivity` 增加回收站入口
   - 添加相关布局文件和资源

## 3.2 界面设计

### 3.2.1 新增需求界面

**回收站主界面**

```
+------------------------------------------+
|                                          |
|  回收站                            返回  |
|------------------------------------------+
|                                          |
|  [便签列表]                              |
|  +-------------------------------+       |
|  | 便签1标题        删除时间     |       |
|  +-------------------------------+       |
|                                          |
|  +-------------------------------+       |
|  | 便签2标题        删除时间     |       |
|  +-------------------------------+       |
|                                          |
|  +-------------------------------+       |
|  | 便签3标题        删除时间     |       |
|  +-------------------------------+       |
|                                          |
|  [空白提示文本]                          |
|------------------------------------------+
|                                          |
|  [清空回收站]        [清理设置]          |
|                                          |
+------------------------------------------+
```

**便签预览界面**

```
+------------------------------------------+
|                                          |
|  便签预览                          返回  |
|------------------------------------------+
|                                          |
|  [便签内容显示区域]                      |
|                                          |
|                                          |
|                                          |
|                                          |
|                                          |
|                                          |
|                                          |
|                                          |
|                                          |
|------------------------------------------+
|                                          |
|  [恢复便签]           [删除便签]         |
|                                          |
+------------------------------------------+
```

**清理设置对话框**

```
+------------------------------------------+
|                                          |
|  设置自动清理时间                        |
|------------------------------------------+
|                                          |
|  自动清理回收站中超过以下天数的便签：    |
|                                          |
|  +-------------+                         |
|  |     30      |                         |
|  +-------------+                         |
|                                          |
|                                          |
|  [取消]                      [确定]      |
|                                          |
+------------------------------------------+
```

### 3.2.2 设计界面类

**TrashListActivity 类**
- 便签列表视图 - `mListView`
- 便签适配器 - `mAdapter`
- 清空回收站按钮 - `mBtnEmptyTrash`
- 清理设置按钮 - `mBtnCleanupSettings`
- 空白提示文本 - `mEmptyView`

**NotePreviewActivity 类**
- 便签内容视图 - `mNoteContent`
- 恢复按钮 - `mBtnRestore`
- 删除按钮 - `mBtnDelete`

**TrashAdapter 类**
- 上下文 - `mContext`
- 数据游标 - `mCursor`
- 视图持有器 - `ViewHolder`
  - 标题文本 - `title`
  - 删除时间文本 - `deleteDate`
  - 便签图标 - `icon`

### 3.2.3 界面间的跳转顺序图

```
+----------------+    +------------------+    +-------------------+
|                |    |                  |    |                   |
| 主界面         |    | 回收站界面       |    | 便签预览界面      |
|                |    |                  |    |                   |
+----------------+    +------------------+    +-------------------+
        |                      |                        |
        | 1. 点击回收站图标    |                        |
        |--------------------->|                        |
        |                      |                        |
        |                      | 2. 点击便签项          |
        |                      |----------------------->|
        |                      |                        |
        |                      |                        | 3. 点击恢复/删除
        |                      |                        |----+
        |                      |                        |    |
        |                      |<-----------------------|    |
        |                      | 4. 返回回收站界面      |    |
        |                      |                        |<---+
        |                      |                        | 5. 关闭预览界面
        |                      |                        |
        |<---------------------|                        |
        | 6. 返回主界面        |                        |
        |                      |                        |
```

### 3.2.4 界面间的跳转类图

```
+---------------------+       +--------------------+       +----------------------+
|                     |       |                    |       |                      |
| NotesListActivity   +------>+ TrashListActivity  +------>+ NotePreviewActivity  |
|                     |       |                    |       |                      |
|                     |<------+                    |<------+                      |
+---------------------+       +--------------------+       +----------------------+
                                        |
                                        v
                              +--------------------+
                              |                    |
                              | CleanupSettingDialog |
                              |                    |
                              +--------------------+
```

## 3.3 详细设计

### 3.3.1 用例设计

**用例：回收站管理**

**参与者**：用户

**先决条件**：
- 应用已安装并正常运行
- 数据库中存在已删除的便签

**主要流程**：
1. 用户点击主界面右上角的回收站图标
2. 系统显示回收站界面，包含已删除便签的列表
3. 用户可以选择：
   - 点击便签查看详细内容
   - 通过上下文菜单恢复或彻底删除便签
   - 点击底部按钮清空回收站或设置自动清理参数
4. 用户恢复便签时，系统将便签恢复到原始文件夹
5. 用户彻底删除便签时，系统从数据库中移除便签数据
6. 用户设置自动清理参数时，系统保存设置并更新定时任务

**替代流程**：
1. 如果回收站为空，系统显示空白提示
2. 如果清空回收站，系统提示确认后删除所有已删除便签
3. 如果回收站达到容量上限，系统自动删除最早删除的便签

### 3.3.2 类设计

**DataUtils 类扩展**

```java
/**
 * 数据工具类
 * 提供回收站相关的数据操作方法
 */
public class DataUtils {
    // 已有方法...
    
    /**
     * 将便签批量移动到回收站
     * @param resolver ContentResolver
     * @param ids 便签ID集合
     * @return 操作是否成功
     */
    public static boolean batchMoveToTrash(ContentResolver resolver, HashSet<Long> ids);
    
    /**
     * 从回收站批量恢复便签
     * @param resolver ContentResolver
     * @param ids 便签ID集合
     * @return 操作是否成功
     */
    public static boolean batchRestoreFromTrash(ContentResolver resolver, HashSet<Long> ids);
    
    /**
     * 批量彻底删除便签
     * @param resolver ContentResolver
     * @param ids 便签ID集合
     * @return 操作是否成功
     */
    public static boolean batchPermanentlyDeleteNotes(ContentResolver resolver, HashSet<Long> ids);
    
    /**
     * 设置回收站自动清理时间间隔
     * @param context 上下文
     * @param days 天数
     * @return 操作是否成功
     */
    public static boolean setTrashCleanInterval(Context context, int days);
    
    /**
     * 获取回收站自动清理时间间隔
     * @param context 上下文
     * @return 天数
     */
    public static int getTrashCleanInterval(Context context);
    
    /**
     * 清理过期的回收站便签
     * @param context 上下文
     * @return 清理的便签数量
     */
    public static int cleanExpiredTrashNotes(Context context);
    
    /**
     * 检查回收站是否已满
     * @param resolver ContentResolver
     * @return 是否已满
     */
    public static boolean isTrashFull(ContentResolver resolver);
}
```

**CleanupScheduler 类**

```java
/**
 * 回收站清理调度服务
 * 负责定时清理回收站中过期的便签
 */
public class CleanupScheduler extends Service {
    private static final String ACTION_CLEANUP_TRASH = "net.micode.notes.CLEANUP_TRASH";
    private static final String ACTION_SCHEDULE_CLEANUP = "net.micode.notes.SCHEDULE_CLEANUP";
    
    /**
     * 启动服务
     * @param context 上下文
     */
    public static void startService(Context context);
    
    /**
     * 安排下一次清理
     * @param context 上下文
     */
    public static void scheduleNextCleanup(Context context);
    
    /**
     * 立即清理回收站
     * @param context 上下文
     */
    public static void cleanupTrashImmediately(Context context);
    
    /**
     * 执行清理操作
     * @param context 上下文
     */
    private void performCleanup(Context context);
    
    @Override
    public void onCreate();
    
    @Override
    public int onStartCommand(Intent intent, int flags, int startId);
    
    @Override
    public void onDestroy();
    
    @Override
    public IBinder onBind(Intent intent);
}
```

**TrashListActivity 类**

```java
/**
 * 回收站列表界面
 * 显示已删除的便签并提供恢复和删除操作
 */
public class TrashListActivity extends Activity implements OnClickListener, OnItemClickListener {
    private ListView mListView;
    private TrashAdapter mAdapter;
    private ContentResolver mContentResolver;
    private Cursor mCursor;
    private Button mBtnEmptyTrash;
    private Button mBtnCleanupSettings;
    private TextView mEmptyView;
    
    @Override
    protected void onCreate(Bundle savedInstanceState);
    
    @Override
    protected void onResume();
    
    @Override
    protected void onDestroy();
    
    /**
     * 加载回收站中的便签
     */
    private void loadTrashNotes();
    
    /**
     * 更新空视图状态
     */
    private void updateEmptyView();
    
    /**
     * 刷新列表
     */
    private void refreshList();
    
    @Override
    public void onClick(View v);
    
    @Override
    public void onItemClick(AdapterView<?> parent, View view, int position, long id);
    
    @Override
    public void onCreateContextMenu(ContextMenu menu, View v, ContextMenuInfo menuInfo);
    
    @Override
    public boolean onContextItemSelected(MenuItem item);
    
    /**
     * 创建自动清理设置对话框
     */
    private Dialog createCleanupIntervalDialog();
    
    /**
     * 创建删除确认对话框
     */
    private Dialog createDeleteConfirmDialog();
    
    /**
     * 恢复选中的便签
     */
    private void restoreSelectedNote(int position);
    
    /**
     * 彻底删除选中的便签
     */
    private void deleteSelectedNote(int position);
    
    /**
     * 清空回收站
     */
    private void emptyTrash();
    
    /**
     * 回收站列表适配器
     */
    private class TrashAdapter extends BaseAdapter {
        // 适配器相关方法
    }
}
```

## 3.4 数据库设计

### 3.4.1 数据库表设计

**Notes表扩展**

新增字段：
- `STATUS` - 便签状态（0-正常，1-已删除）
- `DELETE_DATE` - 删除时间（毫秒时间戳）
- `EXPIRE_STATUS` - 过期状态（0-未过期，1-已过期）

### 3.4.2 数据库版本升级

从版本4升级到版本5，添加回收站相关字段：

```sql
ALTER TABLE note ADD COLUMN status INTEGER NOT NULL DEFAULT 0;
ALTER TABLE note ADD COLUMN delete_date INTEGER NOT NULL DEFAULT 0;
ALTER TABLE note ADD COLUMN expire_status INTEGER NOT NULL DEFAULT 0;
CREATE INDEX IF NOT EXISTS idx_delete_date ON note(delete_date);
CREATE INDEX IF NOT EXISTS idx_status ON note(status);
```

## 3.5 测试方案

### 3.5.1 单元测试

1. `DataUtils` 类的回收站相关方法测试
2. `CleanupScheduler` 服务定时调度测试

### 3.5.2 界面测试

1. 回收站操作流程测试
2. 恢复便签到原始文件夹测试
3. 自动清理功能测试

### 3.5.3 系统性能测试

1. 回收站容量上限测试
2. 数据库操作性能测试
3. 自动清理性能测试

## 3.6 实现计划

1. 数据库结构修改
2. 业务逻辑层实现
3. 界面实现
4. 集成测试
5. 功能发布 