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
This commit is contained in:
@@ -4,7 +4,7 @@
|
||||
|
||||
当前系统已经包含：
|
||||
|
||||
- FastAPI Web 应用与服务端模板页面
|
||||
- FastAPI Web 应用（React SPA 前端 + JSON API）
|
||||
- SQLite + SQLAlchemy + Alembic 的单库结构
|
||||
- username/password + server-side session 鉴权
|
||||
- runtime config 页面与 app DB 持久化
|
||||
@@ -47,11 +47,13 @@ python -m scripts.run_migrations
|
||||
|
||||
主要目录如下：
|
||||
|
||||
- `app/`: FastAPI 应用代码
|
||||
- `app/`: FastAPI 应用代码（包含 JSON API、业务服务、数据模型）
|
||||
- `frontend/`: React SPA 前端（Vite + React + TypeScript + Mantine）
|
||||
- `alembic_app/`: App DB 的 Alembic migration 环境（同时管理 `location` / `poo_records` 表）
|
||||
- `tests/`: pytest 测试
|
||||
- `docs/`: 当前系统说明文档
|
||||
- `scripts/`: 辅助脚本，例如 OpenAPI 导出
|
||||
- `openapi/`: OpenAPI schema 静态产物（`openapi.json` / `openapi.yaml`），纳入版本控制
|
||||
|
||||
## 依赖管理
|
||||
|
||||
@@ -112,11 +114,62 @@ uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
|
||||
启动后可访问：
|
||||
|
||||
- 应用首页：`http://localhost:8000/`
|
||||
- 应用首页（React SPA）：`http://localhost:8000/`
|
||||
- 健康检查：`http://localhost:8000/status`
|
||||
- Swagger UI：`http://localhost:8000/docs`
|
||||
- ReDoc：`http://localhost:8000/redoc`
|
||||
|
||||
## 前端 v2（React SPA）
|
||||
|
||||
M2 用 React SPA 取代了原有 Jinja 服务端模板，由 FastAPI 同源托管（同一容器、同一 origin）。
|
||||
|
||||
### 技术栈
|
||||
|
||||
- **Vite + React + TypeScript + Mantine**（组件库）
|
||||
- **TanStack Query**（数据请求/缓存）
|
||||
- **Leaflet / react-leaflet**（地图与热力图）
|
||||
- **openapi-typescript + openapi-fetch**（类型化 API client，由 `openapi/openapi.json` 生成）
|
||||
|
||||
### 本地开发（前端）
|
||||
|
||||
前端开发服务器会把 `/api`、`/location`、`/poo`、`/public-ip`、`/homeassistant`、`/ticktick`、`/status` 等路径代理到后端 FastAPI（`:8000`）。
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev # 启动 Vite dev server（默认 :5173），代理后端
|
||||
```
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build # 产出 frontend/dist
|
||||
```
|
||||
|
||||
FastAPI 启动时若 `frontend/dist/index.html` 存在，则自动挂载该目录，并对非 `/api` 路径做 SPA fallback（返回 `index.html`）。该路径可通过环境变量 `SPA_DIST_DIR` 覆盖（默认值为 `frontend/dist`，与多阶段 Dockerfile 中 `COPY` 到 `/app/frontend/dist` 一致）。
|
||||
|
||||
### 类型化 API Client
|
||||
|
||||
前端 API client 由后端 OpenAPI schema 自动生成：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run codegen # 从 ../openapi/openapi.json 生成 src/api/schema.d.ts
|
||||
```
|
||||
|
||||
生成物（`src/api/schema.d.ts`）已提交入库，CI 会校验它与 `openapi/openapi.json` 保持同步。
|
||||
|
||||
### 前端校验闸门
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run lint # ESLint
|
||||
npm run typecheck # TypeScript 类型检查
|
||||
npm run test # Vitest 单元测试
|
||||
npm run build # 构建，确认产出 dist
|
||||
```
|
||||
|
||||
## 数据库与 Alembic
|
||||
|
||||
当前使用单一 SQLite 数据库文件：
|
||||
@@ -142,9 +195,9 @@ python -m scripts.migrate_legacy_data
|
||||
|
||||
- 认证模型：`username/password`
|
||||
- 会话模型：server-side session + cookie
|
||||
- 当前主要受保护页面：`/config`
|
||||
- 当前公开页面：`/login`
|
||||
- 当前公开 API：现有业务 API 暂未在这一轮统一收口到 auth 下
|
||||
- 当前受保护入口：React SPA（`/` 等客户端路由）调用 `/api/*` JSON 端点
|
||||
- 当前公开页面：`/login`（SPA 登录页）
|
||||
- 当前公开 API：裸 ingestion 端点（`/location/record`、`/poo/record` 等设备调用端点）暂未收口到 session 保护（M3 再做）
|
||||
|
||||
安全实现的当前边界：
|
||||
|
||||
@@ -152,7 +205,7 @@ python -m scripts.migrate_legacy_data
|
||||
- session cookie 使用 `HttpOnly`
|
||||
- `Secure` 默认随 `APP_ENV` 切换：非 development 时默认开启
|
||||
- `SameSite=Lax`
|
||||
- 登录表单和登出表单都有基础 CSRF 防护
|
||||
- 写请求（POST/PUT/PATCH/DELETE）需携带 `X-CSRF-Token` header（SameSite=Lax + 自定义 header 纵深防御，无需 per-session token 值比对）
|
||||
|
||||
首次启动时，如果 `APP_DATABASE_URL` 对应的 auth DB 里还没有用户，应用会使用：
|
||||
|
||||
@@ -166,12 +219,14 @@ python -m scripts.migrate_legacy_data
|
||||
|
||||
首次登录后会被要求立即修改密码。这个 bootstrap 只用于首个用户落库，不是后续的完整配置管理方案。
|
||||
|
||||
当前前端主要有两条页面路径：
|
||||
React SPA 主要页面路由（客户端路由，均由 FastAPI fallback 到 `index.html`）：
|
||||
|
||||
- `/login`
|
||||
- `/config`
|
||||
- `/login`：登录页
|
||||
- `/`：首页（地图热力图主视图）
|
||||
- `/config`：配置页（取代原 Jinja `/config`）
|
||||
- `/records`：记录管理列表页
|
||||
|
||||
无论是本地 `host:port` 还是反向代理后的域名访问，登录成功后都使用相对路径跳转到 `/config`。
|
||||
无论是本地 `host:port` 还是反向代理后的域名访问，登录成功后进入 SPA 首页（`/`）。
|
||||
|
||||
## Config 持久化
|
||||
|
||||
@@ -230,8 +285,8 @@ python -m scripts.migrate_legacy_data
|
||||
|
||||
当前系统已经提供最小可用的 SMTP 能力：
|
||||
|
||||
- SMTP 配置可在 `/config` 页面填写并保存到 `app_config`
|
||||
- 可通过 config 页面发送测试邮件
|
||||
- SMTP 配置可在 React SPA `/config` 页面填写并保存到 `app_config`（通过 `PUT /api/config`）
|
||||
- 可通过 config 页面发送测试邮件（`POST /api/config/smtp/test`）
|
||||
- 邮件 `From` 头支持显示名，例如 `Home Automation <sender@example.com>`
|
||||
|
||||
当前 SMTP 配置项包括：
|
||||
|
||||
Reference in New Issue
Block a user