# 第 2-9 课：Python 进阶综合项目——多文件任务管理程序

## 一、本课目标

完成本课后，你将能够把第二阶段所学内容组合成一个可运行的小程序：

1. 用多个 Python 文件组织程序；
2. 用 JSON 文件保存并恢复任务；
3. 用异常处理保护文件读取和用户输入；
4. 使用推导式、生成器、装饰器和类型注解；
5. 解释每个模块的职责，并完成第二阶段验收。

## 二、前置知识

需要完成或阅读过第二阶段第 1 至第 8 课。第 8 课虽然已跳过，但本项目不依赖第三方软件包，只使用 Python 标准库。

## 三、项目要解决什么问题

单个文件中的代码变多后，阅读和修改都会变困难。这个项目把任务管理功能拆分为三部分：

```text
main.py          程序入口：组织执行顺序、显示结果
task_service.py  业务功能：新增、完成、筛选和汇总任务
task_store.py    数据读写：把任务保存到 JSON 文件、再读回来
```

职责拆分的好处是：保存格式改变时主要修改 `task_store.py`；新增业务规则时主要修改 `task_service.py`；入口显示变化时主要修改 `main.py`。

## 四、什么是 JSON

JSON（JavaScript Object Notation）是一种常用的文本数据格式。它能保存列表、字典、字符串、数字和布尔值，适合本课保存任务数据。

Python 使用标准库 `json`：

```python
json.dumps(data)  # 把 Python 数据转换成 JSON 文本
json.loads(text)  # 把 JSON 文本转换成 Python 数据
```

本项目保存的单条任务类似：

```python
{
    "id": 1,
    "title": "整理本课学习笔记",
    "priority": "高",
    "completed": False,
}
```

## 五、完整示例

完整示例由 `main.py`、`task_service.py` 和 `task_store.py` 组成。请先逐个打开文件，再运行入口文件。

## 六、运行方法

在项目根目录执行：

```powershell
cd D:\Code\Python
python .\02_python进阶\2_9_python进阶综合项目\main.py
```

首次运行会自动创建：

```text
02_python进阶/2_9_python进阶综合项目/task_data/tasks.json
```

这是本地运行数据，已由 `.gitignore` 忽略。再次运行会继续读取已有任务，所以任务数量会增加，这是正常现象。

## 七、正常结果示例

第一次运行时，输出格式类似：

```text
读取到 0 条已有任务。
正在执行：add_task
正在执行：add_task
正在执行：complete_task

本次新增的任务：
[1] 整理本课学习笔记｜优先级：高｜状态：已完成
[2] 运行任务管理程序｜优先级：中｜状态：未完成

未完成任务：
[2] 运行任务管理程序｜优先级：中｜状态：未完成

任务汇总：
全部：2 条，已完成：1 条，未完成：1 条。
```

编号和总数量会因之前运行过的次数而不同。

## 八、关键代码解析

### 8.1 文件不存在时返回空列表

```python
if not data_file.exists():
    return []
```

第一次运行还没有任务文件，这不是错误。返回空列表后，程序就可以从第一条任务开始添加。

### 8.2 装饰器记录调用

`@log_call` 会在原函数执行前输出函数名，但不会改变原函数的参数和返回值。它适合为多个关键操作增加相同的提示。

### 8.3 生成器逐条提供未完成任务

```python
for task in tasks:
    if not task["completed"]:
        yield task
```

`yield` 让函数每找到一条未完成任务就交出一条，不需要先创建完整的新列表。

### 8.4 类型注解

例如 `list[dict[str, object]]` 表示“由任务字典组成的列表”。任务中的值既可能是编号、文字，也可能是布尔值，所以这里使用 `object`。

## 九、常见错误

### 9.1 直接运行 task_service.py

它是功能模块，不是入口程序。应运行 `main.py`。

### 9.2 JSON 文件内容损坏

手工编辑 `tasks.json` 时漏写逗号或引号，会导致 JSON 格式错误。示例会安全返回空列表；练习中应捕获 `json.JSONDecodeError` 并给出提示。

### 9.3 忘记保存

列表只在程序运行期间存在。调用 `add_task()` 或 `complete_task()` 后，要调用 `save_tasks()` 才能写入文件。

### 9.4 使用 `wrapper()` 代替 `wrapper`

装饰器最后应 `return wrapper`，不是 `return wrapper()`；后者会在装饰阶段提前执行函数。

## 十、课堂练习

打开 `practice.py`，按六部分要求自己创建 `practice_store.py`、`practice_service.py` 和 `practice_main.py`。练习文件保持题面说明形式，不包含预置函数骨架。

## 十一、参考答案

本课不提前写入参考答案。完成后把三个练习文件保留在本课目录，我会按模块职责、功能正确性、可读性和知识掌握情况进行验证。

## 十二、本课小结

- 模块让不同职责的代码分开放置；
- JSON 能把 Python 的任务数据保存为文本；
- `Path` 让路径处理更安全清晰；
- `try...except` 让预期的读取问题不至于让程序崩溃；
- 推导式适合快速生成汇总数据，生成器适合逐条提供结果；
- 装饰器可为多个函数增加共同功能；
- 类型注解让函数接收什么、返回什么更清楚。

## 十三、验收标准

- 能独立运行完整示例并说明三个模块的职责；
- 能解释 JSON 保存和读取的方向；
- 能说明本项目中异常处理、推导式、生成器、装饰器和类型注解分别在哪里使用；
- 能按题目完成三个练习模块；
- 再次运行练习程序时，能够读取上次保存的任务；
- 已完成第二阶段的综合项目，具备进入第三阶段“面向对象编程”的基础。