Files

T

tliu93 2f634006d2 M1-T07: align docs to single-DB reality and re-export OpenAPI

Rewrite README (single app.db + one alembic_app chain, legacy data moved
once via scripts.migrate_legacy_data, accurate test list) and remove the
Grafana Provisioning section. Update architecture-overview to the unified
data layer (one Base, app-DB engine with WAL) and retire the
alembic_location / alembic_poo sections. Mark M1 done in the roadmap.
Re-export openapi/, which catches the spec up to the already-existing
/config/smtp/test and /public-ip/check endpoints (purely additive; M1's
DB-session dependency swap produced no schema change).

pytest 95 passed; ruff clean (pre-existing only); OpenAPI export idempotent.

2026-06-12 17:13:28 +02:00

2.6 KiB

Raw Blame History

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
- 统一数据层：一个 Base、一个绑定 app_database_url 的 cached engine（SQLite WAL）、get_engine / get_session_local / reset_db_caches / get_db_session
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 / config / public_ip / location / poo）共用同一个 Base，均落在单一 app.db 中
schemas/
- Pydantic schemas
services/
- 业务服务层
- 当前已迁入 config page 的 DB 持久化逻辑
- 当前已迁入 public IPv4 检查、状态持久化与变化通知逻辑
- 当前已迁入 SMTP 发信与测试发信逻辑
integrations/
- 外部系统适配层
- 当前已迁入 Home Assistant outbound adapter
templates/
- Jinja2 模板
static/
- 极简静态资源

`alembic_app/`

App DB 的唯一 Alembic migration 链，同时管理 location / poo_records 表。M1 将三个独立 DB 合并进 app.db 后，alembic_location/ 与 alembic_poo/ 已退役，全部由此链统一管理。

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

2.6 KiB Raw Blame History Unescape Escape