M1-rework: rename leftover pk_cols param in reconciliation test stubs

Round-2 audit nit (review-notes/M1-full-review-2.md): two _always_fail
monkeypatch stubs still named their (ignored) third positional parameter
pk_cols after _reconcile switched to a full columns list. Rename to columns
for consistency. Test-only, no behavior change.

pytest 97 passed; ruff clean.

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.gitignore
+.pytest_cache
+.venv
+__pycache__
+*.pyc
+data
+openapi
+src
+

.env.example

@@ -0,0 +1,30 @@
+# Required: bootstrap and core app settings.
+# These values should be set before the container starts.
+APP_NAME=Home Automation Backend (Python)
+APP_ENV=production
+APP_HOSTNAME=home-automation.example.com
+APP_DATABASE_URL=sqlite:////app/data/app.db
+AUTH_BOOTSTRAP_USERNAME=admin
+AUTH_BOOTSTRAP_PASSWORD=change-me
+
+# Optional: runtime overrides.
+# Leave these commented out to use the application's built-in defaults.
+# APP_DEBUG=
+# AUTH_SESSION_COOKIE_NAME=
+# AUTH_SESSION_TTL_HOURS=
+# AUTH_COOKIE_SECURE_OVERRIDE=
+
+# Optional: Home Assistant integration.
+# Leave these empty when Home Assistant integration is not needed.
+HOME_ASSISTANT_BASE_URL=
+HOME_ASSISTANT_AUTH_TOKEN=
+POO_WEBHOOK_ID=
+POO_SENSOR_ENTITY_NAME=
+POO_SENSOR_FRIENDLY_NAME=
+
+# Optional: TickTick integration.
+# APP_HOSTNAME is used to derive the OAuth callback URI automatically.
+TICKTICK_CLIENT_ID=
+TICKTICK_CLIENT_SECRET=
+TICKTICK_TOKEN=
+HOME_ASSISTANT_ACTION_TASK_PROJECT_ID=

.github/workflows/docker-image.yml

@@ -0,0 +1,43 @@
+name: docker-image
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  REGISTRY_HOST: code.wanderingbadger.dev
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: amd64,arm64
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Gitea Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY_HOST }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Build and push multi-arch image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ${{ env.REGISTRY_HOST }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}
+            ${{ env.REGISTRY_HOST }}/${{ env.IMAGE_NAME }}:latest

.github/workflows/pytest.yml

@@ -0,0 +1,31 @@
+name: pytest
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            dev-requirements.txt
+
+      - name: Install dependencies
+        run: python -m pip install -r dev-requirements.txt
+
+      - name: Run pytest
+        run: python -m pytest

.github/workflows/short-tests.yml

@@ -1,20 +0,0 @@
-name: Run short tests
-
-on:
-  push:
-  pull_request:
-
-jobs:
-  run-tests:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Go
-      uses: actions/setup-go@v4
-      with:
-        go-version: '1.23'
-
-    - name: Test
-      working-directory: ./src
-      run: go test -v --short ./...

.gitignore

@@ -1,37 +1,8 @@
-# If you prefer the allow list template instead of the deny list, see community template:
-# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
-#
-# Binaries for programs and plugins
-*.exe
-*.exe~
-*.dll
-*.so
-*.dylib
-
-# Test binary, built with `go test -c`
-*.test
-
-# Output of the go coverage tool, specifically when used with LiteIDE
-*.out
-
-# Dependency directories (remove the comment below to include it)
-# vendor/
-
-# Go workspace file
-go.work
-go.work.sum
-
-# env file
+.codex
 .env
-
-temp_data/
-
-# py file for branch switching
-.venv
-__pycache__/
 .pytest_cache/
-config.yaml
-bin/
-*.db
-
-cover.html
+.venv/
+__pycache__/
+*.pyc
+data/
+review-notes/

.vscode/launch.json

@@ -1,35 +1,20 @@
 {
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "Launch Package",
-            "type": "go",
+            "name": "Launch Python App",
+            "type": "debugpy",
             "request": "launch",
-            "mode": "auto",
-            "program": "${workspaceFolder}"
-        },
-        {
-            "name": "Launch Poo Reverse",
-            "type": "go",
-            "request": "launch",
-            "mode": "auto",
-            "program": "${workspaceFolder}/src/helper/poo_recorder_helper/main.go",
+            "module": "uvicorn",
             "args": [
-                "reverse"
-            ]
-        },
-        {
-            "name": "Launch Home Automation",
-            "type": "go",
-            "request": "launch",
-            "mode": "auto",
-            "program": "${workspaceFolder}/src/main.go",
-            "args": [
-                "serve"
-            ]
+                "app.main:app",
+                "--reload",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "8000"
+            ],
+            "jinja": true
         }
     ]
-}
+}

CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md — Home Automation Backend
+
+本文件每次会话自动加载。它定义本项目的**工作流程、文档位置、commit 规范**。请在动手前先读完。
+
+## 项目速览
+
+- 个人用 home-automation 后端：**FastAPI + SQLite + SQLAlchemy + Alembic**，服务端模板（Jinja，M2 将换成 React SPA）。
+- 单 admin 鉴权（Argon2 + server-side session cookie），runtime config 落 `app_config` 表。
+- 模块：public IPv4 monitor、SMTP 通知、location recorder、poo recorder、Home Assistant in/out、TickTick OAuth。
+- 已发布 `v1.0.3`。下一阶段方向：**M1 单库化 → M2 React 前端 → M3 token/移动端（远期，M2 后再说）**。
+- **当前现实**：在 M1 完成前仍是**三个独立 SQLite 库**（app / location / poo），三套 DeclarativeBase、三条 Alembic 链。不要假设已经单库——以代码现状为准。
+- 明确不做：Notion 模块。
+
+## 文档地图与「开工前必读」
+
+文档都在 `docs/`：
+
+| 路径 | 作用 |
+| --- | --- |
+| `docs/roadmap.md` | 全局规划与里程碑总览 |
+| `docs/design/README.md` | **协作契约**：任务卡格式、原子任务定义、校验闸门、数据安全红线 |
+| `docs/design/m1-db-consolidation.md` | M1 原子任务（含真实代码现状盘点 + 人工 runbook） |
+| `docs/design/m2-frontend-v2.md` | M2 原子任务 + API 契约 + 前端校验闸门 |
+| `docs/design/m3-token-mobile.md` | M3（远期，暂缓） |
+| `docs/*.md`（auth / public-ip-monitor / location-recorder …） | 各模块说明，按需读 |
+
+**开工时读取顺序**：
+1. `docs/design/README.md`（每轮都读，它是流程与验收的共同契约）。
+2. 本轮对应的 milestone 文档（如 `docs/design/m1-db-consolidation.md`），定位要做的任务卡。
+3. 任务卡 `Files` 列出的源文件 + 该模块的 `docs/*.md`（按需）。
+4. `docs/roadmap.md` 仅在需要全局视角时读。
+
+## 工作流程
+
+### 实现模式（由用户的提示词决定）
+
+- **默认逐步**：给一个 milestone 文档，按其中原子任务**一步一步**实现。
+- **(a) 只实现一步**：用户说"只实现一步 / 这一个任务"时，**只做那一个任务卡**，跑完校验闸门后停下，等用户确认，不要顺手往下做。
+- **(b) 完成整个 milestone**：仅当用户在提示词里**显式要求启用 sub-agent 并指定模型**时，才用指定模型起 implementer sub-agent，按任务依赖顺序跑完整条链。
+- **Sub-agent 纪律**：只在用户显式要求时才 spawn sub-agent；单步/小改动在主线内联完成。起 sub-agent 时用用户**指定的模型**（Agent 工具的 `model` 覆盖）。
+
+### 角色（Orchestrator → Implementer → Reviewer）
+
+- 我（主线）= **Orchestrator**：挑依赖已满足的下一个任务、派发、转述结果、维护任务 `Status`。
+- **Implementer**（便宜模型，用户指定）：一次一个任务，严格按任务卡，不扩范围。
+- **Reviewer**（强模型，用户指定）：实现完成后起 Reviewer sub-agent，按任务卡 `Acceptance criteria` + `Reviewer checklist` 复核、**独立重跑校验闸门**，驱动 implementer 返工直到本轮 PASS。
+
+### 校验闸门（每个任务结束都要全绿）
+
+根目录、激活 `.venv` 后：
+```bash
+pytest                      # 权威闸门（CI 跑的就是它）
+ruff check .                # line-length=100
+python scripts/export_openapi.py && git diff --exit-code openapi/   # 改了路由/schema 才需要，且产物须入库
+```
+前端任务（M2）在 `frontend/` 下另跑 `npm run lint && npm run typecheck && npm run test && npm run build`（详见 m2 文档 §8）。
+**不过闸门就不算完成**，不得跳过、不得留红给下一轮。
+
+## 每轮简报（`review-notes/`）
+
+每轮工作都要在 `review-notes/` 下产出**中文简报**。该目录**已在 `.gitignore` 忽略**，纯本地、不入库——它是 agent 之间和与人之间的交接载体，不是仓库产物。
+
+- **实现 / 返工简报**：每轮实现完成后（无论首次实现还是返工），写一份。文件名建议 `<task-id>-impl-<n>.md` / `<task-id>-rework-<n>.md`（如 `M1-T03-impl-1.md`、`M1-T03-rework-1.md`）。至少包含：
+  1. **本轮修改的具体内容**（改了哪些文件、做了什么、为什么）。
+  2. **自动化测试结果**（`pytest` / `ruff` / 前端闸门的实际输出或结论，通过/失败逐项写清）。
+  3. **若需人工 walkthrough**：写明具体步骤（怎么启动、点哪里、预期看到什么）；若无需人工验证，明确写"无需人工 walkthrough"。
+- **review 简报**：每轮 review 后写一份，文件名建议 `<task-id>-review-<n>.md`（如 `M1-T03-review-1.md`）。至少包含：评审结论（`PASS` 或带编号的返工清单）、对照任务卡 `Acceptance criteria` + `Reviewer checklist` 的逐条核对、reviewer 独立重跑校验闸门的结果。
+
+**用途**：① reviewer 审核时参考对应的实现简报；② implementer 返工时参考对应的 review 简报；③ 人类（用户）通读这些简报确认有无问题。简报之间用文件名里的 `<task-id>` 与轮次 `<n>` 对应起来。
+
+### Orchestrator 派发契约（让简报真正被读到）
+
+**关键**：sub-agent 冷启动、不继承主线上下文，**不会因为本文件提到简报就自动去读**对应文件。简报能流转，靠的是 orchestrator（主线）在**每次 spawn 时把路径显式写进 prompt**，而不是被动约定。所以派发时必须做到：
+
+- **显式告诉它「先读哪个简报」**：
+  - 派 implementer 做**首次实现** → 传任务卡位置（milestone 文档路径 + task id）；无前置简报。
+  - 派 implementer 做**返工** → 必须传对应的 `review-notes/<task>-review-<n>.md` 路径，并要求**先读它**再改。
+  - 派 reviewer → 必须传对应的 `review-notes/<task>-impl|rework-<n>.md` 路径 + 任务卡，要求**先读它**再评。
+- **显式告诉它「本轮结束写哪个简报」**：明确给出输出路径 `review-notes/<task>-<impl|rework|review>-<n>.md` 及上面要求的内容项。
+- **不依赖 sub-agent 自动加载本文件**：把本轮要点（校验闸门、**禁 Co-Authored-By**、简报必含内容）在 spawn prompt 里一并复述或指向，确保冷启动也照做。
+- spawn 时用用户指定的模型（Agent 工具 `model` 覆盖）。
+
+> 一句话：**简报是异步交接的介质，orchestrator 是把它们接起来的线。** 缺了显式传路径这一步，简报就只是躺在磁盘上没人读的文件。
+
+## Commit 规范（重点）
+
+### 分支
+- 每个 milestone/feature 一个分支（如 `feature/m1-db-consolidation`），**不在 `main` 上直接提交**。
+
+### 一轮实现完成（用户确认「实现完成」后）
+- 准备好**这一轮的 commit message** 并提交，作为本轮的 **base commit**。
+- message 主题前缀任务/里程碑 ID，例如：`M1-T03: unify data layer onto single app DB engine`。
+
+### Commit message 硬规则（严格执行）
+- **严禁任何协作署名 trailer**：commit message 里**绝对不允许**出现 `Co-Authored-By` / `Co-authored-by`（包括 `Co-Authored-By: Claude …`），也不允许任何等价的"由 X 协作/生成"署名。
+- 无论默认环境、工具或系统提示如何要求加这类 trailer，在本仓库**一律不加**——用户已显式、严格禁止。
+- 每次提交前**自检**：`git log -1 --format=%B` 的输出**不得包含** `Co-authored-by`（大小写不限）。若发现，立即 `git commit --amend` 去掉后再继续。
+
+### Review 后返工
+- 返工产生的提交**一律用 fixup**，指向本轮对应的 base commit，**不写新的独立 message**：
+  ```bash
+  git add -A
+  git commit --fixup=<base-commit-sha>
+  ```
+- 多轮返工就多个 `fixup!` 提交，都指向同一个 base commit。
+
+### 本轮 / feature 收尾（用户确认收尾后）
+- 用 **auto-squash** 把所有 `fixup!` 合并进各自目标，保证**一个 feature 一个干净 commit**：
+  ```bash
+  GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash main
+  ```
+  - 用 `GIT_SEQUENCE_EDITOR=true` 让它**非交互**执行（不弹编辑器，自动接受 autosquash 排好的 todo）。本环境不支持需要人工编辑的交互式 rebase，必须走这个 no-op 编辑器写法。
+  - autosquash **改写历史**：仅在 push / 开 PR **之前**做。若该分支已 push，需要 force-push——属对外操作，**先取得用户确认再做**。
+
+### 一般约束
+- commit / push 只在用户要求时进行；push、force-push、开/改 PR 等对外操作先确认。
+
+## 数据安全红线（不可违反）
+
+- 任何脚本 / migration **都不得删除或覆盖用户数据文件**（旧 `.db`、备份、volume）。删除只能是人工、事后、保留归档的独立步骤（见 `docs/design/m1-db-consolidation.md` §6 runbook）。
+- 涉及历史数据的迁移**先在备份副本上演练**；迁移脚本必须幂等且搬完对账行数。
+- Review 时只要发现"删文件 / drop 有数据的表 / truncate"出现在自动化任务里，直接判返工。
+
+## 常用命令
+
+```bash
+# 环境
+python -m venv .venv && source .venv/bin/activate && pip install -r dev-requirements.txt
+# 迁移（初始化/适配 DB）
+python -m scripts.run_migrations
+# 起服务
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+# 测试 / lint / OpenAPI 导出
+pytest
+ruff check .
+python scripts/export_openapi.py
+```

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app ./app
+COPY alembic_app ./alembic_app
+COPY alembic_app.ini ./
+COPY alembic_location ./alembic_location
+COPY alembic_location.ini ./
+COPY alembic_poo ./alembic_poo
+COPY alembic_poo.ini ./
+COPY scripts ./scripts
+COPY docker ./docker
+COPY README.md ./
+RUN mkdir -p /app/data
+
+EXPOSE 8000
+
+ENTRYPOINT ["/app/docker/entrypoint.sh"]
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1 +1,401 @@
-Port 8881
+# Home Automation Backend
+
+这是当前 `home-automation` 项目的首个 Python 版本。
+
+当前系统已经包含：
+
+- FastAPI Web 应用与服务端模板页面
+- SQLite + SQLAlchemy + Alembic 的单库结构
+- username/password + server-side session 鉴权
+- runtime config 页面与 app DB 持久化
+- public IPv4 monitor、历史持久化与定时检查
+- SMTP 配置、测试发信与 public IPv4 changed 邮件通知
+- location recorder
+- poo recorder
+- Home Assistant inbound / outbound integration
+- TickTick OAuth 与 action task 集成
+- pytest 测试与 OpenAPI 导出脚本
+- Docker / Compose 部署入口
+
+当前明确不包含：
+
+- Notion 模块
+
+## 当前配置现实
+
+当前系统使用单一 SQLite 数据库文件（`app.db`），所有数据表都在其中：
+
+- auth（单个 admin 用户、server-side session）
+- runtime config 持久化（`app_config` 表）
+- public IPv4 当前状态与变化历史
+- location 记录（`location` 表）
+- poo 记录（`poo_records` 表）
+
+配置层只保留一个数据库环境变量：
+
+- `APP_DATABASE_URL`
+
+`app.db` 不会在应用启动时自动创建，需要先运行：
+
+```bash
+python -m scripts.run_migrations
+```
+
+该命令会通过 Alembic 将 `app.db` 初始化或升级到最新 head（含 `location` / `poo_records` 表）。
+
+## 当前目录
+
+主要目录如下：
+
+- `app/`: FastAPI 应用代码
+- `alembic_app/`: App DB 的 Alembic migration 环境（同时管理 `location` / `poo_records` 表）
+- `tests/`: pytest 测试
+- `docs/`: 当前系统说明文档
+- `scripts/`: 辅助脚本，例如 OpenAPI 导出
+
+## 依赖管理
+
+项目现在采用 `pip-tools` 管理依赖：
+
+- 生产依赖源文件：`requirements.in`
+- 开发依赖源文件：`dev-requirements.in`
+- 编译产物：
+  - `requirements.txt`
+  - `dev-requirements.txt`
+
+更新依赖时建议使用：
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install pip-tools
+pip-compile requirements.in
+pip-compile dev-requirements.in
+```
+
+如果要升级某个依赖，可以用：
+
+```bash
+pip-compile --upgrade-package fastapi requirements.in
+pip-compile dev-requirements.in
+```
+
+## 本地启动
+
+建议使用 Python 3.11 或以上版本。
+
+1. 创建虚拟环境并安装依赖
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r dev-requirements.txt
+```
+
+2. 准备环境变量
+
+```bash
+cp .env.example .env
+```
+
+3. 初始化数据库
+
+```bash
+python -m scripts.run_migrations
+```
+
+4. 启动服务
+
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+启动后可访问：
+
+- 应用首页：`http://localhost:8000/`
+- 健康检查：`http://localhost:8000/status`
+- Swagger UI：`http://localhost:8000/docs`
+- ReDoc：`http://localhost:8000/redoc`
+
+## 数据库与 Alembic
+
+当前使用单一 SQLite 数据库文件：
+
+- App DB：`sqlite:///./data/app.db`
+- 数据目录：`./data/`
+
+所有模型（auth / config / public_ip / location / poo）共用同一个 `Base`，均通过单一 Alembic 链管理：
+
+- Alembic 环境：`alembic_app.ini` + `alembic_app/`
+- 统一 migration job：`python -m scripts.run_migrations`
+- App DB 接管 / 初始化：`python scripts/app_db_adopt.py`
+
+历史 location / poo 数据（旧版本遗留的独立 DB 文件）已通过以下脚本一次性迁移至 `app.db`（幂等，不删除旧文件）：
+
+```bash
+python -m scripts.migrate_legacy_data
+```
+
+## 基础鉴权
+
+当前项目提供一个单用户 admin 鉴权层，用于保护配置页面与管理能力。
+
+- 认证模型：`username/password`
+- 会话模型：server-side session + cookie
+- 当前主要受保护页面：`/config`
+- 当前公开页面：`/login`
+- 当前公开 API：现有业务 API 暂未在这一轮统一收口到 auth 下
+
+安全实现的当前边界：
+
+- 密码使用 Argon2 做哈希存储
+- 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 只用于首个用户落库，不是后续的完整配置管理方案。
+
+当前前端主要有两条页面路径：
+
+- `/login`
+- `/config`
+
+无论是本地 `host:port` 还是反向代理后的域名访问，登录成功后都使用相对路径跳转到 `/config`。
+
+## Config 持久化
+
+当前 config 页面不会把修改写回 `.env`。
+
+当前原则是：
+
+- `.env` 只负责 bootstrap / fallback
+- app 启动先从 `.env` 读取数据库地址等基础配置
+- 请求期读取配置时，优先使用 app DB 中的 `app_config` 表
+- 如果数据库里没有对应值，再 fallback 到 `.env`
+
+这意味着：
+
+- app DB 地址（`APP_DATABASE_URL`）仍然属于 bootstrap 范畴
+- 运行时可编辑配置主要通过 `app_config` 表持久化
+- token / secret 这类运行时必须可取回的配置，目前允许明文存储在 config 表中
+- 登录密码仍然单独使用 Argon2 哈希，不走 config 表明文存储
+
+当前已经接入 config 页面的运行时配置包括：
+
+- 基础系统配置
+- auth cookie 相关配置
+- SMTP 基础配置
+- TickTick OAuth 配置
+- Home Assistant 配置
+
+其中 SMTP password 与其他 secret 字段一致：
+
+- 页面不明文回显
+- 留空提交时保留旧值
+- 用于测试发信与自动通知时不会写入响应
+
+## Public IPv4 Monitor
+
+当前系统已经提供最小可用的 public IPv4 monitor：
+
+- 使用单一 provider 检查当前公网 IPv4
+- 将状态与变化历史持久化到 app DB
+- 提供受保护的手动检查入口：`GET /public-ip/check`
+- 启动时注册 APScheduler job，默认每 4 小时检查一次
+
+当前 app DB 中与此功能相关的新表：
+
+- `public_ip_state`
+- `public_ip_history`
+
+状态语义如下：
+
+- `first_seen`：首次发现当前公网 IPv4
+- `unchanged`：与上次状态一致
+- `changed`：公网 IPv4 发生变化
+- `error`：provider 请求失败或返回无效值
+
+## SMTP 与邮件通知
+
+当前系统已经提供最小可用的 SMTP 能力：
+
+- SMTP 配置可在 `/config` 页面填写并保存到 `app_config`
+- 可通过 config 页面发送测试邮件
+- 邮件 `From` 头支持显示名，例如 `Home Automation <sender@example.com>`
+
+当前 SMTP 配置项包括：
+
+- `SMTP_ENABLED`
+- `SMTP_HOST`
+- `SMTP_PORT`
+- `SMTP_USERNAME`
+- `SMTP_PASSWORD`
+- `SMTP_FROM_NAME`
+- `SMTP_FROM_ADDRESS`
+- `SMTP_TO_ADDRESS`
+- `SMTP_USE_STARTTLS`
+
+当前 public IPv4 monitor 已与 SMTP sender 接通，但只处理一个很小的通知场景：
+
+- 当 public IPv4 check 结果为 `changed` 时，自动发送一封英文纯文本邮件
+
+以下情况不会发邮件：
+
+- `first_seen`
+- `unchanged`
+- `error`
+
+当前通知邮件内容固定，不提供模板系统，正文会包含：
+
+- previous IP
+- current IP
+- detected time
+
+手动测试时，如果需要再次模拟一次 IP 变化，可以临时修改 `public_ip_state.current_ipv4` 为一个保留测试地址，然后再次调用 `GET /public-ip/check`。
+
+## OpenAPI
+
+可使用下面的脚本重新导出当前 API 定义：
+
+```bash
+python scripts/export_openapi.py
+```
+
+导出结果会写入：
+
+- `openapi/openapi.json`
+- `openapi/openapi.yaml`
+
+## Docker Compose
+
+当前默认 Compose 服务名为 `app`，容器名固定为 `home-automation-app`。
+
+当前 Compose 分成两层：
+
+- `docker-compose.yml`：默认使用 registry image，适合部署 / 生产拉取
+- `docker-compose.override.yml`：仅为本地开发追加 `build: .`
+
+本地开发启动方式：
+
+```bash
+docker compose up -d --build
+```
+
+上面的命令会自动叠加 `docker-compose.override.yml`，因此本地仍然会按当前工作目录重新 build。
+
+如果要按生产方式直接从 registry 拉取并启动，显式只使用基础 compose 文件：
+
+```bash
+docker compose -f docker-compose.yml pull
+docker compose -f docker-compose.yml up -d
+```
+
+持续查看日志：
+
+```bash
+docker compose logs -f app
+```
+
+## Container Image CI
+
+项目提供了一个 release image workflow：
+
+- workflow 文件：`.github/workflows/docker-image.yml`
+- 触发条件：push 匹配 `v*` 的 tag，例如 `v1.0.0`
+- registry：`code.wanderingbadger.dev`
+- image：`code.wanderingbadger.dev/<owner>/<repo>`
+
+`docker-compose.yml` 中生产默认使用的 app image 当前为：
+
+- `code.wanderingbadger.dev/tliu93/home-automation:latest`
+
+当前 workflow 不再把 image name 硬编码到特定 user package 路径，而是直接使用当前仓库标识生成镜像路径：
+
+- `code.wanderingbadger.dev/${github.repository}:${tag}`
+
+在 Gitea 这里，package 更贴近 repo 归属的语义，主要体现在镜像命名路径本身，而不是额外的“绑定”动作。也就是说，当前发布方式是按仓库路径约定来对齐 repo/package 语义。
+
+这个 workflow 会构建并推送 multi-arch image：
+
+- `linux/amd64`
+- `linux/arm64`
+
+推送的 tag：
+
+- release tag 本身，例如 `v1.0.0`
+- `latest`
+
+workflow 依赖以下 secrets：
+
+- `REGISTRY_USERNAME`
+- `REGISTRY_TOKEN`
+
+CI 产出的 image 是给部署机直接 `docker pull` 使用的。部署机不需要 checkout 本仓库，也不需要本地执行 `docker build`。
+
+## 运行测试
+
+```bash
+pytest
+```
+
+当前测试包含：
+
+- app 启动与 `/status` 检查
+- 登录 / session / 鉴权流程
+- runtime config 读写
+- public IPv4 monitor
+- SMTP 配置与测试发信
+- location / poo recorder 端点
+- Home Assistant inbound 集成
+- TickTick OAuth
+- 部署与迁移（`run_migrations`）
+- legacy 数据迁移脚本（`migrate_legacy_data`）
+
+## OpenAPI 导出
+
+FastAPI 默认会暴露 OpenAPI。若需要导出静态 schema 文件，可运行：
+
+```bash
+python scripts/export_openapi.py
+```
+
+输出文件会写到：
+
+- `openapi/openapi.json`
+- `openapi/openapi.yaml`
+
+`openapi/` 当前纳入版本控制。接口发生变更时，应重新运行导出脚本并同步提交生成的 schema 文件。
+
+## 容器启动
+
+1. 准备环境变量文件
+
+```bash
+cp .env.example .env
+```
+
+2. 启动容器
+
+```bash
+docker compose up --build
+```
+
+默认端口：
+
+- `8000:8000`
+
+SQLite 持久化目录：
+
+- 本地 `./data`
+- 容器内 `/app/data`

alembic_app.ini

@@ -0,0 +1,37 @@
+[alembic]
+script_location = alembic_app
+prepend_sys_path = .
+path_separator = os
+sqlalchemy.url = sqlite:///./data/app.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s

alembic_app/env.py

@@ -0,0 +1,52 @@
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from app.config import get_settings
+from app.db import Base
+from app.models.config import AppConfigEntry  # noqa: F401
+from app.models.auth import AuthSession, AuthUser  # noqa: F401
+from app.models.public_ip import PublicIPHistory, PublicIPState  # noqa: F401
+from app.models.location import Location  # noqa: F401
+from app.models.poo import PooRecord  # noqa: F401
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+settings = get_settings()
+configured_url = config.get_main_option("sqlalchemy.url")
+if not configured_url or configured_url == "sqlite:///./data/app.db":
+    config.set_main_option("sqlalchemy.url", settings.app_database_url)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(url=url, target_metadata=target_metadata, literal_binds=True)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic_app/script.py.mako

@@ -0,0 +1,25 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}