Add auth foundation and app DB management

README.md

@@ -9,6 +9,7 @@
 - FastAPI 基础应用骨架
 - 环境变量配置体系
 - SQLite + SQLAlchemy + Alembic 基础设施
+- username/password + server-side session 基础鉴权
 - 极简 server-side templates
 - location recorder 第一版迁移
 - poo recorder 第一版迁移
@@ -39,23 +40,37 @@ Notion 在 Go 版本中仍然存在，但已被明确视为 legacy / removed sco
 
 ## 当前配置现实
 
-当前系统仍然是两个独立的 SQLite 数据库文件，而不是单一数据库：
+当前系统仍然是三个独立的 SQLite 数据库文件，而不是单一数据库：
 
+- `app` 级共享数据使用自己的 DB 文件
 - `location` 模块使用自己的 DB 文件
 - `poo` 模块使用自己的 DB 文件
 
-当前阶段明确不借这次重构把两个 DB 合并。配置层已经显式反映这一点：
+当前阶段明确不借这次重构把这些 DB 合并。配置层已经显式反映这一点：
 
+- `APP_DATABASE_URL`
 - `LOCATION_DATABASE_URL`
 - `POO_DATABASE_URL`
 
-目前 `location` 和 `poo` 都已经接到各自独立的数据库文件。
+目前 auth、`location` 和 `poo` 都已经接到各自独立的数据库文件。
+
+其中 `app` 级共享 DB 当前主要用于：
+
+- 单个 admin 用户
+- server-side session
+
+这部分现在也使用 Alembic 管理：
+
+- `app db` 不会在应用启动时自动创建
+- 需要先运行 `python scripts/app_db_adopt.py`
+- 这个脚本会创建新 DB 并建好 schema
 
 ## 当前目录
 
 Python 骨架的主要目录如下：
 
 - `app/`: FastAPI 应用代码
+- `alembic_app/`: App DB 的 Alembic migration 环境
 - `alembic_location/`: Location DB 的 Alembic migration 环境
 - `alembic_poo/`: Poo DB 的 Alembic migration 环境
 - `tests/`: pytest 测试
@@ -107,7 +122,15 @@ pip install -r dev-requirements.txt
 cp .env.example .env
 ```
 
-3. 启动服务
+3. 初始化数据库
+
+```bash
+python scripts/app_db_adopt.py
+python scripts/location_db_adopt.py
+python scripts/poo_db_adopt.py
+```
+
+4. 启动服务
 
 ```bash
 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
@@ -122,21 +145,54 @@ uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 
 ## 数据库与 Alembic
 
-当前默认仍使用 SQLite，但要明确区分两个数据库文件：
+当前默认仍使用 SQLite，但要明确区分三个数据库文件：
 
+- App DB：`sqlite:///./data/app.db`
 - Location DB：`sqlite:///./data/locationRecorder.db`
 - Poo DB：`sqlite:///./data/pooRecorder.db`
 - 数据目录：`./data/`
 
 初始化 migration 环境后，可继续添加模型并生成迁移：
 
-当前 `location` 和 `poo` 都已经有各自独立的 Alembic baseline / 接管链路。
+当前 `app`、`location` 和 `poo` 都已经有各自独立的 Alembic 链路。
 
+- App Alembic 环境：`alembic_app.ini` + `alembic_app/`
 - Location Alembic 环境：`alembic_location.ini` + `alembic_location/`
 - Poo Alembic 环境：`alembic_poo.ini` + `alembic_poo/`
+- App DB 初始化：`python scripts/app_db_adopt.py`
 - Location DB 接管 / 初始化：`python scripts/location_db_adopt.py`
 - Poo DB 接管 / 初始化：`python scripts/poo_db_adopt.py`
 
+## 基础鉴权
+
+当前项目已经有一层小范围的基础鉴权，目标是先保护后续配置页面，而不是现在就做完整 admin system。
+
+- 认证模型：`username/password`
+- 会话模型：server-side session + cookie
+- 当前受保护页面：`/admin`
+- 当前公开页面：`/`、`/login`
+- 当前公开 API：现有业务 API 暂未在这一轮统一收口到 auth 下
+
+安全实现的当前边界：
+
+- 密码使用 scrypt 做哈希存储
+- session cookie 使用 `HttpOnly`
+- `Secure` 默认随 `APP_ENV` 切换：非 development 时默认开启
+- `SameSite=Lax`
+- 登录表单和登出表单都有基础 CSRF 防护
+
+首次启动时，如果 `APP_DATABASE_URL` 对应的 auth DB 里还没有用户，应用会使用：
+
+- `AUTH_BOOTSTRAP_USERNAME`
+- `AUTH_BOOTSTRAP_PASSWORD`
+
+创建初始 admin 用户。当前默认就是：
+
+- username: `admin`
+- password: `admin`
+
+首次登录后会被要求立即修改密码。这个 bootstrap 只用于首个用户落库，不是后续的完整配置管理方案。
+
 ## 运行测试
 
 ```bash
@@ -147,6 +203,7 @@ pytest
 
 - app 基本启动测试
 - `/status` endpoint 测试
+- 登录 / session 基础流程测试
 
 ## OpenAPI 导出
 
@@ -200,3 +257,4 @@ SQLite 持久化目录：
 - [Python 重构方案](docs/python-rewrite-plan.md)
 - [迁移风险清单](docs/migration-risks.md)
 - [Location Recorder 接管说明](docs/location-recorder.md)
+- [基础鉴权说明](docs/auth.md)