4.3 KiB
4.3 KiB
Home Automation Backend
这是当前 home-automation 项目的 Python 重构基础骨架。当前仓库仍保留 Go 版本作为事实基线，而这个 Python 部分的目标是为后续逐模块迁移提供稳定工程基础。
为便于清理仓库，重构开始前就存在的 Go 实现和相关资产已经统一移动到 legacy/go-backend/。这样在 Python 重构完成后，可以按目录整体删除旧实现。
当前阶段只包含：
- FastAPI 基础应用骨架
- 环境变量配置体系
- SQLite + SQLAlchemy + Alembic 基础设施
- 极简 server-side templates
- location recorder 第一版迁移
- pytest 测试基础
- OpenAPI 导出脚本
- Docker / Compose 基础骨架
当前阶段明确不包含：
- TickTick 业务逻辑迁移
- Home Assistant 业务逻辑迁移
- poo records 业务迁移
- Notion 模块
Notion 在 Go 版本中仍然存在，但已被明确视为 legacy / removed scope，不进入新的 Python 系统目标。
旧 Go 代码位置：
legacy/go-backend/src/legacy/go-backend/helper/legacy/go-backend/.github/workflows/
当前配置现实
当前系统仍然是两个独立的 SQLite 数据库文件，而不是单一数据库：
location模块使用自己的 DB 文件poo模块未来也将使用自己的 DB 文件
当前阶段明确不借这次重构把两个 DB 合并。配置层已经显式反映这一点：
LOCATION_DATABASE_URLPOO_DATABASE_URL
目前真正接入的是 location 对应的数据库；poo 先保留配置占位，等模块迁入时再接上。
当前目录
Python 骨架的主要目录如下：
app/: FastAPI 应用代码alembic/: Alembic migration 环境tests/: pytest 测试docs/: 架构说明与迁移文档scripts/: 辅助脚本，例如 OpenAPI 导出
依赖管理
项目现在采用 pip-tools 管理依赖：
- 生产依赖源文件：
requirements.in - 开发依赖源文件：
dev-requirements.in - 编译产物：
requirements.txtdev-requirements.txt
更新依赖时建议使用：
python -m venv .venv
source .venv/bin/activate
pip install pip-tools
pip-compile requirements.in
pip-compile dev-requirements.in
如果要升级某个依赖，可以用：
pip-compile --upgrade-package fastapi requirements.in
pip-compile dev-requirements.in
本地启动
建议使用 Python 3.11 或以上版本。
- 创建虚拟环境并安装依赖
python -m venv .venv
source .venv/bin/activate
pip install -r dev-requirements.txt
- 准备环境变量
cp .env.example .env
- 启动服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
启动后可访问：
- 应用首页：
http://localhost:8000/ - 健康检查：
http://localhost:8000/status - Swagger UI：
http://localhost:8000/docs - ReDoc：
http://localhost:8000/redoc
数据库与 Alembic
当前默认仍使用 SQLite，但要明确区分两个数据库文件：
- Location DB：
sqlite:///./data/locationRecorder.db - Poo DB：
sqlite:///./data/pooRecorder.db - 数据目录：
./data/
初始化 migration 环境后，可继续添加模型并生成迁移：
alembic revision --autogenerate -m "init tables"
alembic upgrade head
当前 Alembic 只接管 location 这条链路；poo 相关数据库与 migration 还没有迁入。
运行测试
pytest
当前测试包含：
- app 基本启动测试
/statusendpoint 测试
OpenAPI 导出
FastAPI 默认会暴露 OpenAPI。若需要导出静态 schema 文件，可运行：
python scripts/export_openapi.py
输出文件会写到：
openapi/openapi.jsonopenapi/openapi.yaml
容器启动
- 准备环境变量文件
cp .env.example .env
- 启动容器
docker compose up --build
默认端口：
8000:8000
SQLite 持久化目录：
- 本地
./data - 容器内
/app/data
后续迁移建议
后续可以在当前骨架上继续迁移这些模块：
- TickTick integration
- Home Assistant integration
- poo records
建议继续参考：