Add auth foundation and app DB management

docs/architecture-overview.md

@@ -23,17 +23,20 @@
   - 基础路由注册
 - `config.py`
   - 环境变量驱动的 settings
+- `auth_db.py`
+  - app 级共享 auth 数据库
 - `db.py`
   - SQLAlchemy engine / session / Base
 - `dependencies.py`
   - 通用依赖注入
 - `api/`
   - HTTP routes
+  - 当前已迁入 `/login`、`/logout`、`/admin`
   - 当前已迁入 `POST /homeassistant/publish` 第一版入口
   - 当前已迁入 `POST /poo/record` 与 `GET /poo/latest`
 - `models/`
   - SQLAlchemy models
-  - 当前 `location` 与 `poo` 使用各自独立的数据库 base
+  - 当前 `auth`、`location` 与 `poo` 使用各自独立的数据库 base
 - `schemas/`
   - Pydantic schemas
 - `services/`
@@ -50,6 +53,10 @@
 
 Location DB 的 migration 基础设施。
 
+### `alembic_app/`
+
+App DB 的 migration 基础设施。
+
 ### `alembic_poo/`
 
 Poo DB 的 migration 基础设施。

docs/auth.md

@@ -0,0 +1,110 @@
+# 基础鉴权说明
+
+本文档说明当前 Python 重构项目里已经落地的第一版鉴权基座。
+
+这一轮只解决：
+
+- 登录页
+- 登录 / 登出流程
+- server-side session
+- 一个最小受保护页面
+
+这一轮明确不解决：
+
+- 完整 config persistence
+- 完整 config CRUD
+- 多用户权限系统
+- OAuth / SSO / RBAC
+
+## 当前 auth 模型
+
+- 认证方式：`username/password`
+- 会话方式：server-side session
+- 客户端凭据：session cookie
+- 页面形态：Jinja server-side template
+
+## 当前持久化
+
+当前新增一个共享 App DB：
+
+- `APP_DATABASE_URL`
+- 默认值：`sqlite:///./data/app.db`
+
+当前 auth 相关数据存放在这个 DB 中：
+
+- `auth_users`
+- `auth_sessions`
+
+当前没有把 auth 数据和 `location` / `poo` DB 混放。
+
+当前这部分现在也走 Alembic 管理：
+
+- Alembic 环境：`alembic_app.ini` + `alembic_app/`
+- 初始化脚本：`python scripts/app_db_adopt.py`
+
+当前没有 legacy app DB，所以这一版脚本只负责初始化新库，不负责 legacy adoption。
+
+## 首次启动与 bootstrap
+
+如果 auth DB 中还没有任何用户，应用启动时会要求：
+
+- `AUTH_BOOTSTRAP_USERNAME`
+- `AUTH_BOOTSTRAP_PASSWORD`
+
+并创建首个 admin 用户。
+
+当前默认 bootstrap 值就是：
+
+- username: `admin`
+- password: `admin`
+
+首次登录后，系统会强制要求修改密码。
+
+如果你希望在首次启动前就覆盖默认值，可以直接设置环境变量：
+
+- `AUTH_BOOTSTRAP_USERNAME`
+- `AUTH_BOOTSTRAP_PASSWORD`
+
+建议流程是：
+
+1. 配好 `.env`
+2. 运行 `python scripts/app_db_adopt.py`
+3. 启动应用
+4. 用 `admin / admin` 首次登录
+5. 立即修改密码
+
+## 安全设计
+
+当前这版已经落实的基础安全点：
+
+- 密码不明文存储，使用 scrypt 哈希
+- session cookie 为 `HttpOnly`
+- cookie 使用 `SameSite=Lax`
+- `Secure` cookie 在非 `development` 环境默认开启
+- 登录表单与登出表单都有基础 CSRF 校验
+- session token 为随机生成，服务端只持久化 token hash
+- session 有过期时间与显式失效机制
+
+## 当前受保护范围
+
+当前这轮只保护了页面入口：
+
+- `GET /admin`
+- `POST /admin/change-password`
+- `POST /logout`
+
+相关流程：
+
+- `GET /login`
+- `POST /login`
+
+未登录访问 `/admin` 时会被重定向到 `/login`。
+
+## 下一步不在本轮内
+
+后续可以在这个基座上继续做：
+
+- 配置页面接入
+- config persistence
+- 更细的受保护路由范围
+- 用户初始化 / 密码轮换的更正式 runbook