feat(python进阶): 新增进阶综合项目课程

02_python进阶/2_9_python进阶综合项目/README.md

@@ -0,0 +1,167 @@
+# 第 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 保存和读取的方向；
+- 能说明本项目中异常处理、推导式、生成器、装饰器和类型注解分别在哪里使用；
+- 能按题目完成三个练习模块；
+- 再次运行练习程序时，能够读取上次保存的任务；
+- 已完成第二阶段的综合项目，具备进入第三阶段“面向对象编程”的基础。