home-automation/docs/architecture-overview.md

# Python 骨架架构概览

本文档说明当前 Python skeleton 的职责边界与目录组织。它描述的是“后续迁移承载体”，不是完整业务实现。

## 当前目标

这一轮的目标是提供一个稳定、轻量、可持续扩展的基础工程，使后续可以逐步迁移：

- TickTick integration
- Home Assistant integration
- poo records
- location / life trajectory

## 目录设计

### `app/`

应用核心代码目录。

- `main.py`
  - FastAPI app factory
  - lifespan
  - 基础路由注册
- `config.py`
  - 环境变量驱动的 settings
- `auth_db.py`
  - app 级共享 auth 数据库
- `db.py`
  - SQLAlchemy engine / session / Base
- `dependencies.py`
  - 通用依赖注入
- `api/`
  - HTTP routes
  - 当前已迁入 `/login`、`/logout`、`/admin`
  - 当前已迁入 `GET /public-ip/check`
  - 当前已迁入 `POST /homeassistant/publish` 第一版入口
  - 当前已迁入 `POST /poo/record` 与 `GET /poo/latest`
- `models/`
  - SQLAlchemy models
  - 当前 `auth`、`location` 与 `poo` 使用各自独立的数据库 base
- `schemas/`
  - Pydantic schemas
- `services/`
  - 业务服务层
  - 当前已迁入 config page 的 DB 持久化逻辑
  - 当前已迁入 public IPv4 检查、状态持久化与变化通知逻辑
  - 当前已迁入 SMTP 发信与测试发信逻辑
- `integrations/`
  - 外部系统适配层
  - 当前已迁入 Home Assistant outbound adapter
- `templates/`
  - Jinja2 模板
- `static/`
  - 极简静态资源

### `alembic_location/`

Location DB 的 migration 基础设施。

### `alembic_app/`

App DB 的 migration 基础设施。

### `alembic_poo/`

Poo DB 的 migration 基础设施。

### `tests/`

pytest 测试目录。后续可以在这里自然扩展：

- unit tests
- mock tests
- integration tests

### `scripts/`

辅助脚本目录。当前包含 OpenAPI 导出脚本。

## 当前约束

- 当前只搭骨架，不迁业务逻辑
- 当前数据库继续使用 SQLite
- 当前不引入前后端分离
- 当前不设计 Notion 模块
- 当前通知能力仍保持极小范围，不引入独立通知中心或多渠道抽象

## 关于 Notion

Notion 在 Go 版本中仍是现状模块，但在 Python 重构中已经明确属于 removed scope。

因此当前 Python skeleton：

- 不提供 Notion integration 模块
- 不提供 Notion schema
- 不预留 Notion 相关业务流

如果未来需要回顾其历史作用，应继续参考 Go 版本和现有迁移盘点文档，而不是在 Python 骨架中保留它。