Finalize first Python release

README.md

@@ -1,43 +1,24 @@
 # Home Automation Backend
 
-这是当前 `home-automation` 项目的 Python 重构基础骨架。当前仓库仍保留 Go 版本作为事实基线，而这个 Python 部分的目标是为后续逐模块迁移提供稳定工程基础。
+这是当前 `home-automation` 项目的首个 Python 版本。
 
-为便于清理仓库，重构开始前就存在的 Go 实现和相关资产已经统一移动到 `legacy/go-backend/`。这样在 Python 重构完成后，可以按目录整体删除旧实现。
+当前系统已经包含：
 
-当前阶段只包含：
+- FastAPI Web 应用与服务端模板页面
+- SQLite + SQLAlchemy + Alembic 的三库结构
+- username/password + server-side session 鉴权
+- runtime config 页面与 app DB 持久化
+- location recorder
+- poo recorder
+- Home Assistant inbound / outbound integration
+- TickTick OAuth 与 action task 集成
+- pytest 测试与 OpenAPI 导出脚本
+- Docker / Compose 部署入口
 
-- FastAPI 基础应用骨架
-- 环境变量配置体系
-- SQLite + SQLAlchemy + Alembic 基础设施
-- username/password + server-side session 基础鉴权
-- 极简 server-side templates
-- location recorder 第一版迁移
-- poo recorder 第一版迁移
-- Home Assistant outbound integration layer
-- Home Assistant inbound gateway 第一版
-- pytest 测试基础
-- OpenAPI 导出脚本
-- Docker / Compose 基础骨架
+当前明确不包含：
 
-当前阶段明确不包含：
-
-- TickTick 业务逻辑迁移
 - Notion 模块
 
-当前 Home Assistant inbound gateway 仅接回第一版：
-
-- 已支持 `location_recorder / record`
-- 尚未接回 TickTick 路径
-- 尚未接回 poo recorder 路径
-
-Notion 在 Go 版本中仍然存在，但已被明确视为 legacy / removed scope，不进入新的 Python 系统目标。
-
-旧 Go 代码位置：
-
-- `legacy/go-backend/src/`
-- `legacy/go-backend/helper/`
-- `legacy/go-backend/.github/workflows/`
-
 ## 当前配置现实
 
 当前系统仍然是三个独立的 SQLite 数据库文件，而不是单一数据库：
@@ -68,14 +49,14 @@ Notion 在 Go 版本中仍然存在，但已被明确视为 legacy / removed sco
 
 ## 当前目录
 
-Python 骨架的主要目录如下：
+主要目录如下：
 
 - `app/`: FastAPI 应用代码
 - `alembic_app/`: App DB 的 Alembic migration 环境
 - `alembic_location/`: Location DB 的 Alembic migration 环境
 - `alembic_poo/`: Poo DB 的 Alembic migration 环境
 - `tests/`: pytest 测试
-- `docs/`: 架构说明与迁移文档
+- `docs/`: 当前系统说明文档
 - `scripts/`: 辅助脚本，例如 OpenAPI 导出
 
 ## 依赖管理
@@ -146,7 +127,7 @@ 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`
@@ -166,7 +147,7 @@ uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 
 ## 基础鉴权
 
-当前项目已经有一层小范围的基础鉴权，目标是先保护后续配置页面，而不是现在就做完整 admin system。
+当前项目提供一个单用户 admin 鉴权层，用于保护配置页面与管理能力。
 
 - 认证模型：`username/password`
 - 会话模型：server-side session + cookie
@@ -194,7 +175,7 @@ uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 
 首次登录后会被要求立即修改密码。这个 bootstrap 只用于首个用户落库，不是后续的完整配置管理方案。
 
-当前前端已经收敛为两条主路径：
+当前前端主要有两条页面路径：
 
 - `/login`
 - `/config`
@@ -203,7 +184,7 @@ uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 
 ## Config 持久化
 
-当前 config 页面已经不再把修改写回 `.env`。
+当前 config 页面不会把修改写回 `.env`。
 
 当前原则是：
 
@@ -219,6 +200,35 @@ uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 - token / secret 这类运行时必须可取回的配置，目前允许明文存储在 config 表中
 - 登录密码仍然单独使用 Argon2 哈希，不走 config 表明文存储
 
+## OpenAPI
+
+可使用下面的脚本重新导出当前 API 定义：
+
+```bash
+python scripts/export_openapi.py
+```
+
+导出结果会写入：
+
+- `openapi/openapi.json`
+- `openapi/openapi.yaml`
+
+## Docker Compose
+
+当前默认 Compose 服务名为 `app`，容器名固定为 `home-automation-app`。
+
+启动方式：
+
+```bash
+docker compose up -d --build
+```
+
+持续查看日志：
+
+```bash
+docker compose logs -f app
+```
+
 ## 运行测试
 
 ```bash