# Todo List 使用指南

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 基本使用

#### 添加待办事项

```bash
python main.py add "买菜"
python main.py add "做饭"
python main.py add "写代码"
```

输出示例：
```
✓ 已添加: 买菜 (ID: 1)
```

#### 查看所有待办事项

```bash
python main.py list
```

输出示例：
```
所有待办事项:
--------------------------------------------------
[ ] 1. 买菜
    创建时间: 2024-02-08 10:30:00
[ ] 2. 做饭
    创建时间: 2024-02-08 10:31:00
[✓] 3. 写代码
    创建时间: 2024-02-08 10:32:00
--------------------------------------------------
总计: 3 | 已完成: 1 | 未完成: 2
```

#### 筛选查看

查看未完成的事项：
```bash
python main.py list --filter pending
```

查看已完成的事项：
```bash
python main.py list --filter completed
```

#### 标记完成

```bash
python main.py complete 1
```

输出示例：
```
✓ 已完成: 买菜
```

#### 取消完成标记

```bash
python main.py uncomplete 1
```

输出示例：
```
○ 已标记为未完成: 买菜
```

#### 删除待办事项

```bash
python main.py delete 1
```

输出示例：
```
✓ 已删除: 买菜
```

#### 清除所有已完成的事项

```bash
python main.py clear
```

输出示例：
```
✓ 已清除 2 个已完成的待办事项
```

## 高级用法

### 批量操作

使用shell脚本批量添加：

```bash
#!/bin/bash
tasks=(
    "买菜"
    "做饭"
    "洗衣服"
    "打扫卫生"
)

for task in "${tasks[@]}"; do
    python main.py add "$task"
done
```

### 数据备份

待办事项数据存储在 `todos.json` 文件中，可以直接备份：

```bash
# 备份
cp todos.json todos.json.backup

# 恢复
cp todos.json.backup todos.json
```

### 导出为文本

```bash
python main.py list > my_todos.txt
```

## 命令参考

| 命令 | 参数 | 说明 | 示例 |
|------|------|------|------|
| add | title | 添加待办事项 | `python main.py add "买菜"` |
| list | --filter [all\|pending\|completed] | 查看待办事项 | `python main.py list --filter pending` |
| complete | id | 标记为完成 | `python main.py complete 1` |
| uncomplete | id | 标记为未完成 | `python main.py uncomplete 1` |
| delete | id | 删除待办事项 | `python main.py delete 1` |
| clear | - | 清除所有已完成的事项 | `python main.py clear` |

## 数据格式

`todos.json` 文件格式：

```json
{
  "todos": [
    {
      "id": 1,
      "title": "买菜",
      "completed": false,
      "created_at": "2024-02-08 10:30:00"
    }
  ],
  "next_id": 2
}
```

## 常见问题

### Q: 如何重置所有数据？

A: 删除 `todos.json` 文件即可：
```bash
rm todos.json
```

### Q: 如何在不同设备间同步？

A: 可以将 `todos.json` 文件放在云盘同步目录中，或使用Git进行版本管理。

### Q: 支持中文吗？

A: 完全支持中文及其他Unicode字符。

### Q: 如何查看某个事项的详细信息？

A: 使用 `list` 命令会显示所有事项的详细信息，包括创建时间。

## 开发相关

### 运行测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行特定测试文件
pytest tests/test_todo.py -v

# 生成覆盖率报告
pytest tests/ --cov=todo --cov-report=html
```

### 项目结构

```
project/
├── todo/              # 核心模块
│   ├── __init__.py
│   ├── todo.py       # Todo业务逻辑
│   ├── storage.py    # 数据持久化
│   └── cli.py        # 命令行界面
├── tests/            # 测试用例
│   ├── test_todo.py
│   ├── test_storage.py
│   └── test_cli.py
├── main.py           # 程序入口
├── requirements.txt  # 依赖管理
├── README.md         # 项目说明
└── USAGE.md         # 使用指南
```

### 扩展开发

如果需要添加新功能，建议：

1. 在 `todo/todo.py` 中添加业务逻辑
2. 在 `todo/cli.py` 中添加命令行接口
3. 在 `tests/` 中添加相应的测试用例
4. 更新文档

## 技术支持

如有问题或建议，欢迎提交Issue或Pull Request。