Files

T

tliu93 bd09523e94 M2-T13: docs wrap-up + retire frontend constraints + dependency cleanup

- README: add 前端 v2 (React SPA) section (dev/build/codegen/hosting/gates),
  update directory listing, drop stale Jinja descriptions
- architecture-overview: retire '不引入前后端分离' constraint; reflect SPA + JSON API
- roadmap: mark M2 done
- remove orphaned jinja2 dependency (recompile requirements*.txt; no other churn)
- delete empty tests/test_auth.py stub; drop dead _extract_csrf_token in test_api_data
- verified image still builds and app imports with the slimmer deps

2026-06-13 15:20:50 +02:00

3.3 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
- api/routes/api/：JSON API（/api/* 前缀），供 React SPA 调用：会话/鉴权、配置读写、数据查询、记录 CRUD
- 裸 ingestion 端点：GET /public-ip/check、POST /homeassistant/publish、POST /poo/record、GET /poo/latest、TickTick OAuth 等
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
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

`frontend/`

React SPA 前端（M2 引入）。Vite + React + TypeScript + Mantine，由 FastAPI 同源托管。

src/：React 源码
src/api/：由 openapi/openapi.json 生成的类型化 client（schema.d.ts）+ fetch 封装
dist/：npm run build 产物，由 FastAPI 的 SPA_DIST_DIR 挂载并对非 /api 路径做 fallback

`scripts/`

辅助脚本目录。当前包含 OpenAPI 导出脚本（export_openapi.py）与数据层辅助脚本。

`openapi/`

OpenAPI schema 静态产物（openapi.json / openapi.yaml），由 python scripts/export_openapi.py 生成，纳入版本控制。前端 codegen 以此为契约源。

当前约束

当前数据库继续使用 SQLite
~~当前不引入前后端分离~~ 已退役（M2）：现为 React SPA + JSON /api 层，由 FastAPI 同源托管
当前不设计 Notion 模块
当前通知能力仍保持极小范围，不引入独立通知中心或多渠道抽象

关于 Notion

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

因此当前 Python skeleton：

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

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

3.3 KiB Raw Blame History Unescape Escape

Python 骨架架构概览

当前目标

目录设计

app/

alembic_app/

tests/

frontend/

scripts/

openapi/