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