（十八）完整项目的检查与构建

1. 把常用检查串成一个入口

# 项目文件：quality_project/tools/check.py
# 每项检查使用当前解释器；失败就立即返回该项退出状态。
from pathlib import Path
import subprocess
import sys

root = Path(__file__).resolve().parents[1]
commands = [
    ["ruff", "check", "src", "tests"],
    ["ruff", "format", "--check", "src", "tests"],
    ["mypy"],
    ["pytest"],
]
for command in commands:
    print("执行", " ".join(command), flush=True)
    result = subprocess.run([sys.executable, "-m", *command], cwd=root)
    if result.returncode:
        raise SystemExit(result.returncode)
print("所有检查通过")

parents[1] 从 tools/check.py 回到项目根目录，工具因此不依赖调用者当前在哪一层。flush=True 先把步骤名称送出，随后子进程的报告会跟在对应名称之后。

# 第一次使用配套项目：同步环境并运行完整检查。
uv sync --locked
uv run python tools/check.py
# 查看已安装的两种入口，二者指向相同业务。
uv run python -m readingapp --help
uv run reading-log --help

执行顺序是规则检查、排版检查、类型检查与全部测试。定位某次失败时可以单独运行对应工具；确认修正后再回到这个完整入口。

2. 检查构建后的包

可编辑安装读的是工作目录中的源码；交付给其他环境时，还要检查实际生成的分发文件：

# 构建 wheel 与源码分发包，结果写入 dist；不会上传到包索引。
uv run python -m build
# Windows：另建环境，安装生成的 wheel，然后从该环境启动命令。
py -3.12 -m venv .venv-wheel
.\.venv-wheel\Scripts\python.exe -m pip install dist/reading_log_notes-0.1.0-py3-none-any.whl
.\.venv-wheel\Scripts\python.exe -m readingapp --help
.\.venv-wheel\Scripts\reading-log.exe --help

wheel 包含安装所需的业务文件；源码分发包保存构建来源。新环境中的导入位置应该在它自己的 site-packages，不再是工作目录里的 src。若源码运行正常而 wheel 缺少模块，回到包发现配置与构建结果检查。前面的 .venv*/ 同时忽略 .venv 与 .venv-wheel。构建分发文件

3. 用一轮完整操作核对持久化

配套 quality_project/data_sample.py 生成书目，接着执行：

# 项目文件：quality_project/data_sample.py
# 使用第五章的格式写入器，创建可供导入的两本书。
from pathlib import Path

from bookdata.json_io import write_json
from bookdata.models import Book

write_json(Path("data/books.json"), [Book("Python", False, ["基础", "语法"]), Book("NumPy")])
print("已生成 data/books.json")

# 每条命令都会启动新的进程，通过相同数据库文件衔接。
uv run python data_sample.py
uv run reading-log import-json data/books.json
uv run reading-log log Python 2026-10-19 20
uv run reading-log log Python 2026-10-20 35
uv run reading-log finish Python
uv run reading-log list --tag 基础
uv run reading-log export-csv data/export.csv

查询得到 1 Python 已读 55分钟，导出的 CSV 保存书名、完成状态与标签；日志仍由数据库保存。查看 logs/reading.log 可以找到完成导入的记录。把导入文件改坏后重跑，终端显示简短错误，文件日志保存调用信息，之后完整检查应继续通过。