（二）项目目录与第一条运行命令

两个项目都位于综合项目与交付。它们有各自的 .venv 和锁定文件。先进入 catalog_project，后面的书目命令都在这个目录运行。

综合项目与交付/
├── catalog_project/
│   ├── pyproject.toml、uv.lock、pip-requirements.txt
│   ├── src/cataloghub/
│   │   ├── cleaning.py、collecting.py、pipeline.py
│   │   ├── storage.py、backup.py、config.py、telemetry.py
│   │   ├── web.py、source.py、cli.py、__main__.py
│   │   └── fixtures/、templates/、static/
│   ├── tests/、tools/
│   ├── Dockerfile、compose.yaml、.env.example
│   └── instance/                 运行后生成数据库与原始快照
├── model_project/
│   ├── src/modeldelivery/、data/、tests/、tools/
│   ├── pyproject.toml、uv.lock、pip-requirements.txt
│   ├── Dockerfile、compose.yaml、.env.example
│   └── models/                   运行后生成完整模型版本
└── .github/workflows/check.yml

先同步环境，启动本地来源。另开终端后执行采集和查询；最后打开 http://127.0.0.1:8781。

# 终端一：在 catalog_project 中安装锁定依赖，提供三页练习目录。
uv sync --locked
uv run catalog source

# 终端二：仍在 catalog_project 中，先完成采集，再启动查询页面。
uv run catalog collect
uv run catalog serve

这一轮已经经过了 HTTP、清洗、事务和页面。下面拆开每一步，弄清它们分别读写哪些状态。完整命令入口见 cli.py，它使用第三章的 argparse 将命令交给对应函数。

# 项目文件：catalog_project/pyproject.toml
# 采集、HTML 清洗、查询页面和命令行在同一独立项目中组合。
[build-system]
requires = ["setuptools>=80,<83"]
build-backend = "setuptools.build_meta"

[project]
name = "reading-catalog-delivery"
version = "0.1.0"
requires-python = ">=3.12,<3.13"
dependencies = ["httpx>=0.28,<1", "beautifulsoup4>=4.13,<5", "fastapi>=0.115,<1", "uvicorn>=0.34,<1", "jinja2>=3.1,<4"]

[project.scripts]
catalog = "cataloghub.cli:main"

[dependency-groups]
dev = ["pytest>=9.1,<10"]

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools.package-data]
cataloghub = ["templates/*.html", "static/*.css", "fixtures/*.html"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra --import-mode=importlib"

[project.scripts] 把 catalog 接到 main()；package-data 列出随包安装的模板、样式和练习网页。否则从源码运行时能找到的文件，打成安装包后可能就找不到了。pip-requirements.txt 从随附锁定文件导出，后面会实际重建另一套环境。