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
• db.py
  • SQLAlchemy engine / session / Base
• dependencies.py
  • 通用依赖注入
• api/
  • HTTP routes
  • 当前已迁入 POST /homeassistant/publish 第一版入口
  • 当前已迁入 POST /poo/record 与 GET /poo/latest
• models/
  • SQLAlchemy models
  • 当前 location 与 poo 使用各自独立的数据库 base
• schemas/
  • Pydantic schemas
• services/
  • 业务服务层
• integrations/
  • 外部系统适配层
  • 当前已迁入 Home Assistant outbound adapter
• templates/
  • Jinja2 模板
• static/
  • 极简静态资源

alembic_location/

Location 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 骨架中保留它。