261 lines
6.6 KiB
Markdown
261 lines
6.6 KiB
Markdown
# Home Automation Backend
|
||
|
||
这是当前 `home-automation` 项目的 Python 重构基础骨架。当前仓库仍保留 Go 版本作为事实基线，而这个 Python 部分的目标是为后续逐模块迁移提供稳定工程基础。
|
||
|
||
为便于清理仓库，重构开始前就存在的 Go 实现和相关资产已经统一移动到 `legacy/go-backend/`。这样在 Python 重构完成后，可以按目录整体删除旧实现。
|
||
|
||
当前阶段只包含：
|
||
|
||
- FastAPI 基础应用骨架
|
||
- 环境变量配置体系
|
||
- SQLite + SQLAlchemy + Alembic 基础设施
|
||
- username/password + server-side session 基础鉴权
|
||
- 极简 server-side templates
|
||
- location recorder 第一版迁移
|
||
- poo recorder 第一版迁移
|
||
- Home Assistant outbound integration layer
|
||
- Home Assistant inbound gateway 第一版
|
||
- pytest 测试基础
|
||
- OpenAPI 导出脚本
|
||
- Docker / Compose 基础骨架
|
||
|
||
当前阶段明确不包含：
|
||
|
||
- TickTick 业务逻辑迁移
|
||
- Notion 模块
|
||
|
||
当前 Home Assistant inbound gateway 仅接回第一版：
|
||
|
||
- 已支持 `location_recorder / record`
|
||
- 尚未接回 TickTick 路径
|
||
- 尚未接回 poo recorder 路径
|
||
|
||
Notion 在 Go 版本中仍然存在，但已被明确视为 legacy / removed scope，不进入新的 Python 系统目标。
|
||
|
||
旧 Go 代码位置：
|
||
|
||
- `legacy/go-backend/src/`
|
||
- `legacy/go-backend/helper/`
|
||
- `legacy/go-backend/.github/workflows/`
|
||
|
||
## 当前配置现实
|
||
|
||
当前系统仍然是三个独立的 SQLite 数据库文件，而不是单一数据库：
|
||
|
||
- `app` 级共享数据使用自己的 DB 文件
|
||
- `location` 模块使用自己的 DB 文件
|
||
- `poo` 模块使用自己的 DB 文件
|
||
|
||
当前阶段明确不借这次重构把这些 DB 合并。配置层已经显式反映这一点：
|
||
|
||
- `APP_DATABASE_URL`
|
||
- `LOCATION_DATABASE_URL`
|
||
- `POO_DATABASE_URL`
|
||
|
||
目前 auth、`location` 和 `poo` 都已经接到各自独立的数据库文件。
|
||
|
||
其中 `app` 级共享 DB 当前主要用于：
|
||
|
||
- 单个 admin 用户
|
||
- server-side session
|
||
|
||
这部分现在也使用 Alembic 管理：
|
||
|
||
- `app db` 不会在应用启动时自动创建
|
||
- 需要先运行 `python scripts/app_db_adopt.py`
|
||
- 这个脚本会创建新 DB 并建好 schema
|
||
|
||
## 当前目录
|
||
|
||
Python 骨架的主要目录如下：
|
||
|
||
- `app/`: FastAPI 应用代码
|
||
- `alembic_app/`: App DB 的 Alembic migration 环境
|
||
- `alembic_location/`: Location DB 的 Alembic migration 环境
|
||
- `alembic_poo/`: Poo DB 的 Alembic migration 环境
|
||
- `tests/`: pytest 测试
|
||
- `docs/`: 架构说明与迁移文档
|
||
- `scripts/`: 辅助脚本，例如 OpenAPI 导出
|
||
|
||
## 依赖管理
|
||
|
||
项目现在采用 `pip-tools` 管理依赖：
|
||
|
||
- 生产依赖源文件：`requirements.in`
|
||
- 开发依赖源文件：`dev-requirements.in`
|
||
- 编译产物：
|
||
- `requirements.txt`
|
||
- `dev-requirements.txt`
|
||
|
||
更新依赖时建议使用：
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install pip-tools
|
||
pip-compile requirements.in
|
||
pip-compile dev-requirements.in
|
||
```
|
||
|
||
如果要升级某个依赖，可以用：
|
||
|
||
```bash
|
||
pip-compile --upgrade-package fastapi requirements.in
|
||
pip-compile dev-requirements.in
|
||
```
|
||
|
||
## 本地启动
|
||
|
||
建议使用 Python 3.11 或以上版本。
|
||
|
||
1. 创建虚拟环境并安装依赖
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r dev-requirements.txt
|
||
```
|
||
|
||
2. 准备环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. 初始化数据库
|
||
|
||
```bash
|
||
python scripts/app_db_adopt.py
|
||
python scripts/location_db_adopt.py
|
||
python scripts/poo_db_adopt.py
|
||
```
|
||
|
||
4. 启动服务
|
||
|
||
```bash
|
||
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，但要明确区分三个数据库文件：
|
||
|
||
- App DB：`sqlite:///./data/app.db`
|
||
- Location DB：`sqlite:///./data/locationRecorder.db`
|
||
- Poo DB：`sqlite:///./data/pooRecorder.db`
|
||
- 数据目录：`./data/`
|
||
|
||
初始化 migration 环境后，可继续添加模型并生成迁移：
|
||
|
||
当前 `app`、`location` 和 `poo` 都已经有各自独立的 Alembic 链路。
|
||
|
||
- App Alembic 环境：`alembic_app.ini` + `alembic_app/`
|
||
- Location Alembic 环境：`alembic_location.ini` + `alembic_location/`
|
||
- Poo Alembic 环境：`alembic_poo.ini` + `alembic_poo/`
|
||
- App DB 初始化：`python scripts/app_db_adopt.py`
|
||
- Location DB 接管 / 初始化：`python scripts/location_db_adopt.py`
|
||
- Poo DB 接管 / 初始化：`python scripts/poo_db_adopt.py`
|
||
|
||
## 基础鉴权
|
||
|
||
当前项目已经有一层小范围的基础鉴权，目标是先保护后续配置页面，而不是现在就做完整 admin system。
|
||
|
||
- 认证模型：`username/password`
|
||
- 会话模型：server-side session + cookie
|
||
- 当前受保护页面：`/admin`
|
||
- 当前公开页面：`/`、`/login`
|
||
- 当前公开 API：现有业务 API 暂未在这一轮统一收口到 auth 下
|
||
|
||
安全实现的当前边界：
|
||
|
||
- 密码使用 scrypt 做哈希存储
|
||
- session cookie 使用 `HttpOnly`
|
||
- `Secure` 默认随 `APP_ENV` 切换：非 development 时默认开启
|
||
- `SameSite=Lax`
|
||
- 登录表单和登出表单都有基础 CSRF 防护
|
||
|
||
首次启动时，如果 `APP_DATABASE_URL` 对应的 auth DB 里还没有用户，应用会使用：
|
||
|
||
- `AUTH_BOOTSTRAP_USERNAME`
|
||
- `AUTH_BOOTSTRAP_PASSWORD`
|
||
|
||
创建初始 admin 用户。当前默认就是：
|
||
|
||
- username: `admin`
|
||
- password: `admin`
|
||
|
||
首次登录后会被要求立即修改密码。这个 bootstrap 只用于首个用户落库，不是后续的完整配置管理方案。
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
pytest
|
||
```
|
||
|
||
当前测试包含：
|
||
|
||
- app 基本启动测试
|
||
- `/status` endpoint 测试
|
||
- 登录 / session 基础流程测试
|
||
|
||
## OpenAPI 导出
|
||
|
||
FastAPI 默认会暴露 OpenAPI。若需要导出静态 schema 文件，可运行：
|
||
|
||
```bash
|
||
python scripts/export_openapi.py
|
||
```
|
||
|
||
输出文件会写到：
|
||
|
||
- `openapi/openapi.json`
|
||
- `openapi/openapi.yaml`
|
||
|
||
`openapi/` 当前纳入版本控制。接口发生变更时，应重新运行导出脚本并同步提交生成的 schema 文件。
|
||
|
||
## 容器启动
|
||
|
||
1. 准备环境变量文件
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. 启动容器
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
默认端口：
|
||
|
||
- `8000:8000`
|
||
|
||
SQLite 持久化目录：
|
||
|
||
- 本地 `./data`
|
||
- 容器内 `/app/data`
|
||
|
||
## 后续迁移建议
|
||
|
||
后续可以在当前骨架上继续迁移这些模块：
|
||
|
||
- TickTick integration
|
||
- Home Assistant integration
|
||
- poo records
|
||
|
||
建议继续参考：
|
||
|
||
- [当前系统盘点](docs/current-system-inventory.md)
|
||
- [Python 重构方案](docs/python-rewrite-plan.md)
|
||
- [迁移风险清单](docs/migration-risks.md)
|
||
- [Location Recorder 接管说明](docs/location-recorder.md)
|
||
- [基础鉴权说明](docs/auth.md)
|