tliu93
2f634006d2
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.
89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
# 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 骨架中保留它。
|