docs: record future-ideas backlog and refine CLAUDE.md workflow rules

- Add docs/future-ideas.md: unscheduled backlog (more data sources/types,
  long-term storage, Home Assistant data persistence, MQTT client, near-term PWA).
- CLAUDE.md: codify M1 lessons — reviewer blind-review discipline,
  build-context integrity checks when deleting/moving files,
  fixup-vs-standalone-commit boundary, and a pre-release walkthrough
  (run app + docker build + manual smoke) before tagging.

CLAUDE.md

@@ -45,6 +45,14 @@
 - **Implementer**（便宜模型，用户指定）：一次一个任务，严格按任务卡，不扩范围。
 - **Reviewer**（强模型，用户指定）：实现完成后起 Reviewer sub-agent，按任务卡 `Acceptance criteria` + `Reviewer checklist` 复核、**独立重跑校验闸门**，驱动 implementer 返工直到本轮 PASS。
 
+#### Reviewer 盲审纪律（M1 教训）
+
+M1 里 review **从未触发过一次 rework**，根因是 orchestrator 把自己的结论 / 辩护喂给了 reviewer，造成 context bleed、review 沦为橡皮图章。所以：
+
+- reviewer 必须**冷启动（Clear-Agent）、最小化喂料**——spawn prompt 只给：① 任务卡（`Acceptance criteria` + `Reviewer checklist`）、② 对应的 `review-notes/<task>-impl|rework-<n>.md` 路径、③ 要审的 diff / commit 范围。
+- **不要**在 prompt 里塞 orchestrator 自己的判断、"我觉得没问题"、对实现选择的辩护，或上一轮 reviewer 的倾向性结论。让它**独立得出结论、独立重跑校验闸门**。
+- 事后另起的整库**独立盲审**（如对抗复审）同理：Clear-Agent、最小上下文，把它当"**外部审计**"而非"确认自己没错"。
+
 ### 校验闸门（每个任务结束都要全绿）
 
 根目录、激活 `.venv` 后：
@@ -56,6 +64,14 @@ python scripts/export_openapi.py && git diff --exit-code openapi/   # 改了路
 前端任务（M2）在 `frontend/` 下另跑 `npm run lint && npm run typecheck && npm run test && npm run build`（详见 m2 文档 §8）。
 **不过闸门就不算完成**，不得跳过、不得留红给下一轮。
 
+### 构建上下文完整性（M1 Dockerfile 教训）
+
+`docker build` **不在 pytest/ruff 闸门里**——M1 删了 `alembic_location/poo` 后忘了同步 `Dockerfile` 的 `COPY`，单元闸门全绿却把坏掉的镜像构建一路漏到 release tag。所以：
+
+- 任务**删除 / 移动 / 重命名文件或目录**时，必须 grep 构建清单是否还在引用它们：`Dockerfile`（尤其 `COPY` 源）、`docker/`、`*.ini`、CI workflow、`requirements*.txt` 等。
+- 已有回归测试 `tests/test_deployment.py::test_dockerfile_copy_sources_exist` 守"Dockerfile `COPY` 源必须存在于构建上下文"；新增 / 改动 `COPY` 时确保它仍覆盖得到。
+- Reviewer 审"删 / 移文件"类任务时，**必须顺带核对构建清单引用**，把它当 acceptance 的一部分。
+
 ## 每轮简报（`review-notes/`）
 
 每轮工作都要在 `review-notes/` 下产出**中文简报**。该目录**已在 `.gitignore` 忽略**，纯本地、不入库——它是 agent 之间和与人之间的交接载体，不是仓库产物。
@@ -97,12 +113,13 @@ python scripts/export_openapi.py && git diff --exit-code openapi/   # 改了路
 - 每次提交前**自检**：`git log -1 --format=%B` 的输出**不得包含** `Co-authored-by`（大小写不限）。若发现，立即 `git commit --amend` 去掉后再继续。
 
 ### Review 后返工
-- 返工产生的提交**一律用 fixup**，指向本轮对应的 base commit，**不写新的独立 message**：
+- **自动化 orchestration 模式内**的 review 返工：**一律用 fixup**，指向本轮对应的 base commit，**不写新的独立 message**：
   ```bash
   git add -A
   git commit --fixup=<base-commit-sha>
   ```
-- 多轮返工就多个 `fixup!` 提交，都指向同一个 base commit。
+- 多轮返工就多个 `fixup!` 提交，都指向同一个 base commit；收尾时 auto-squash（见下）。
+- **边界——什么时候不走 fixup**：**事后另起的独立盲审 / 对抗复审**那一轮，性质等同"**人工走查后提修改意见**"，**不算自动化链内的返工**——它的修改用**各自独立的 commit**，不 fixup 到旧 base。判据：这轮返工是否在**同一条自动化 implement→review 链**里？是 → `fixup`；是事后另起的独立审计 → 独立 commit。
 
 ### 本轮 / feature 收尾（用户确认收尾后）
 - 用 **auto-squash** 把所有 `fixup!` 合并进各自目标，保证**一个 feature 一个干净 commit**：
@@ -115,6 +132,15 @@ python scripts/export_openapi.py && git diff --exit-code openapi/   # 改了路
 ### 一般约束
 - commit / push 只在用户要求时进行；push、force-push、开/改 PR 等对外操作先确认。
 
+## 发版前置走查（打 tag 前必做）
+
+单元闸门绿 ≠ 真的能跑、能构建、能用。M1 出过"绿了但 docker 构建坏了"的事故，所以**打版本 tag（触发镜像 CI）之前**，除了 `pytest` / `ruff` 全绿，还要：
+
+- **真起 app**：迁移（`python -m scripts.run_migrations`）→ `uvicorn app.main:app ...`，确认能正常启动、关键路由不 500。
+- **真跑镜像构建**：本地 `docker build`（多阶段就跑完整条），确认构建通过、`COPY` 源都在。
+- **关键功能人工瞄一眼**：尤其前端 / 可视化类（M2 的热力图、首页地图）——自动闸门判断不了"渲染对不对、UX 顺不顺"，这部分**靠看跑起来的 app，不靠读代码**。
+- 上述任一不过 → **不打 tag**。tag 一旦 push 会触发 docker 镜像 CI / 对外发布，属对外操作，**先确认**。
+
 ## 数据安全红线（不可违反）
 
 - 任何脚本 / migration **都不得删除或覆盖用户数据文件**（旧 `.db`、备份、volume）。删除只能是人工、事后、保留归档的独立步骤（见 `docs/design/m1-db-consolidation.md` §6 runbook）。

Dockerfile

@@ -11,10 +11,6 @@ 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 ./

docs/design/m2-frontend-v2.md

@@ -27,15 +27,16 @@
 ### 3.2 鉴权：复用 session cookie + SPA 版 CSRF
 
 - 继续用现有 **HttpOnly session cookie**（同源自动携带），M2 **不引入 token**（token 属 M3）。
-- CSRF：新增 `GET /api/session` 返回当前用户 + 该会话的 `csrf_token`；SPA 在所有写请求（POST/PUT/PATCH/DELETE）放 `X-CSRF-Token` header，后端校验其与 session 内 `csrf_token` 一致。等价于把现有表单 CSRF 平移到 header。
+- CSRF（已定·简化版）：依赖 `SameSite=Lax` 的 session cookie——跨站发起的写请求（POST/PUT/PATCH/DELETE）**不会自动携带 cookie**，经典 CSRF 主路已被堵；再要求所有写请求带一个**自定义 header**（跨站无 CORS 预检发不出，且本应用不对外站开放 CORS）作为纵深防御。**不做 per-session token 比对**（个人自用场景足够）。`GET /api/session` 仍保留，用途是返回当前登录用户、引导 SPA（不再以下发/校验 `csrf_token` 为目的）。
 - 浏览器面向的所有新端点一律 session 保护；**裸 ingestion 端点（设备调用的 `POST /location/record`、`POST /poo/record`）维持现状到 M3**。
 
 ### 3.3 前端工程
 
 - `frontend/`：**Vite + React + TypeScript**。
-- API client：由后端 `openapi/openapi.json` **自动生成** TS 类型与请求函数（如 `openapi-typescript` + 轻量 fetch 封装，或同类工具）。生成物入库或在 build 时生成（见 T06 决策）。
+- 组件库：**Mantine**（已定；批电池齐、TS 优先、视觉中性，最贴近此前 Vue 侧 Naive UI 的用法）。
-- 可视化：地图 + 热力图（location 轨迹 / poo 点位）。建议 **MapLibre GL 或 Leaflet + heatmap 插件**（最终选型见 §5 决策）。
+- API client：由后端 `openapi/openapi.json` **自动生成** TS 类型与请求函数（如 `openapi-typescript` + 轻量 fetch 封装）。**生成物入库** + `npm run codegen` + CI 校验"生成物与 openapi 同步"（已定）。fetch 封装统一带 cookie、写请求注入自定义 CSRF header、401 跳登录。
-- 状态/数据请求：轻量即可（如 TanStack Query），不引入重型框架。
+- 可视化：**Leaflet**（已定）—— `react-leaflet` + `leaflet.heat`（热力图，**头号功能**）+ `leaflet.markercluster`（点多时聚合）+ OSM 栅格瓦片（零 key）。**地图封在一个自包含组件后面**（如 `<RecordsMap points mode onSelect>`，全应用只此处 import leaflet），数据获取/时间窗 state 在外面；这样将来若要换 **MapLibre GL** 是被隔离的局部重写，不波及其它。
+- 状态/数据请求：轻量即可（**TanStack Query**，已定），不引入重型框架。
 
 ### 3.4 构建与部署
 
@@ -65,14 +66,31 @@
 
 > 记录 CRUD 依赖现有 PK 作行标识（location PK=`person+datetime`，poo PK=`timestamp`）。路径参数需对 `datetime`/`timestamp` 做 URL 编码处理。
 
-## 5. 需先拍板的决策（Orchestrator 在派 T06 前确认）
+## 5. 已锁定决策（讨论后拍板）
 
-1. **地图/热力图库**：MapLibre GL（矢量、现代）vs Leaflet（简单、生态大）。推荐 Leaflet + `leaflet.heat`（试水门槛低）。
+> 以下为与项目所有者讨论后**已定**的选择。**线框图本里程碑不画**——按本节 + 各任务卡描述，由实现侧自行合理排版（含移动端布局）。
-2. **OpenAPI client 生成物**：入库（确定性、便于 review）vs build 时生成（仓库干净）。推荐**入库**，并加一个 `npm run codegen` + CI 校验"生成物与 openapi 同步"。
-3. **CSRF 落地**：header `X-CSRF-Token` + `GET /api/session` 下发（推荐）vs 双提交 cookie。
-4. **是否保留少量 Jinja**：建议 SPA 对齐后**全量移除** `templates/`，只留 SPA。
 
-> 这些可用 1 个轻量"决策任务"或直接由 Orchestrator 在本节记录选择，再开 T06。
+**技术选型**
+1. **组件库 = Mantine**。批电池齐、TS 优先、视觉中性、文档好，最贴近此前 Naive UI 的用法，利于 agent 产出一致 UI。
+2. **地图库 = Leaflet**（`react-leaflet` + `leaflet.heat` + `leaflet.markercluster`，OSM 栅格、零 key）。**封在自包含组件后**，预留将来迁 MapLibre 的接缝（见 §3.3）。
+3. **OpenAPI client = 生成物入库** + `npm run codegen` + CI 校验"与 openapi 同步"。
+4. **CSRF = 简化版**：`SameSite=Lax` cookie + 写请求带自定义 header，**不做 per-session token**（见 §3.2）。
+5. **前端栈**：Vite + React + TS + TanStack Query + Mantine。
+6. **Jinja**：SPA 功能对齐后**全量移除** `templates/` 与 `pages.py`。
+
+**信息架构 / UX**
+7. **首页主视图 = 地图（热力图为主）+ 时间范围选择器**。可视化优先级：**热力图（最重要）> 时间选择器（必须）> 散点点位/列表（辅助）**。
+8. **列表 = 辅助页面，分页**（默认页大小 ~100、有上限；前端换页取数，不拉全量）。
+9. **记录编辑/删除**：**location 靠点地图上的点**触发（不做 75k 行大列表）；**poo 靠列表 + 地图点位**。
+10. **配置入口**：config 作为普通页之一，由界面上一个**齿轮图标**进入。`/admin`、`/` 现状只是重定向到 `/config`，SPA **不需要单独 admin 页**；`/` 首页直接给地图主视图（概览 dashboard 列为**可选/后续**，非 M2 核心）。
+11. **响应式 = 要**（手机浏览器可用、合理移动端布局）。**PWA** 列为近期 backlog（见 `docs/future-ideas.md`），M2 设计即按移动端友好铺路。
+
+**范围边界**
+12. **CRUD = 改非主键字段 + 删单行**；主键（location=`person+datetime`、poo=`timestamp`）**不可改**；**不提供 UI 新建**（记录由设备 ingestion 产生）。
+13. **裸 ingestion 端点**（`POST /location/record`、`POST /poo/record`）**维持现状到 M3**，本里程碑不加保护、不改动。
+14. **trip / 轨迹连线**为**可选 / 后续**（5 分钟一点 + 手机记录较糙，先不做核心）。
+
+> 项目定位：个人自用、家庭特化、不开源——设计可按单用户场景简化，不为通用性过度抽象。
 
 ## 6. 任务依赖图
 
@@ -177,10 +195,10 @@
 - **Status**: `todo` · **Depends**: M2-T06
 - **Acceptance**: 能读/存所有现有配置 section；secret 不回显、留空保留；SMTP 测试按钮反映三态；前端闸门全绿。
 
-### M2-T09 — 数据可视化 UI（地图 + 热力图）
+### M2-T09 — 数据可视化 UI（热力图为主的地图）
 - **Status**: `todo` · **Depends**: M2-T06（数据来自 T03）
-- **Context**: 接管 Grafana 原职责：location 轨迹/热力图、poo 点位。
+- **Context**: 接管 Grafana 原职责，且**首页主视图就是这张地图**。优先级：**① 热力图（最重要）② 时间范围选择器（必须）③ 散点点位（辅助，主要服务编辑/删除）**。location：去过哪的密度；poo：狗最爱在哪拉。
-- **Acceptance**: 地图渲染 location/poo 点；热力图层可切换；时间范围筛选生效；前端闸门全绿。
+- **Acceptance**: 首页渲染热力图（location / poo）；**时间范围选择器生效、只取窗口内数据**（不拉全量）；散点层可切换、点选某点可进入编辑/删除（接 T10/T04）；location 点多时聚合；响应式（手机浏览器可用）；前端闸门全绿。
 
 ### M2-T10 — 记录管理 UI（按需展示 + 增删改）
 - **Status**: `todo` · **Depends**: M2-T06（CRUD 来自 T04）

docs/future-ideas.md

@@ -0,0 +1,20 @@
+# Future Ideas / Backlog（暂无 Milestone）
+
+记录尚未排期的想法。等某条成形、值得集中推进时，再升级为 `docs/roadmap.md` 里的 milestone 并展开成 `docs/design/` 任务卡。**这里只是备忘，不是承诺。**
+
+> 项目定位：**个人自用、针对自家场景特化，不开源**。因此设计可按单用户 / 自家需求简化，不必为通用性、多租户、对外发布做过度抽象。
+
+## 数据与存储
+- 增加更多数据类型 / 来源（持续扩展）。
+- 针对**需要长期保存**的数据，考虑更合适的存储方案（当前全 SQLite；长期 / 大量数据可能需要更强的数据库）。
+- 把 **Home Assistant 接收到的数据**纳入本系统做持久化 / 展示。
+
+## 集成
+- **MQTT**：让后端作为一个 MQTT client，双向收发数据。
+
+## 前端 / 移动端
+- **PWA**（**近期、可能并入 M2 或单独小里程碑**）：在 React Native（M3）之前，用 PWA 把 web SPA 包装成"准手机 App"——可安装到桌面、响应式、离线壳。
+  - 影响当下设计：**M2 的 UI 从一开始就按移动端布局考虑**（响应式 + 合理的参数显示），为之后加 PWA 铺路。
+
+## 备注
+- 以上为临时记录（讨论 M2 范围时随手想到），后续可增删、重排优先级。

tests/test_deployment.py

@@ -64,6 +64,24 @@ def test_image_defaults_to_uvicorn_only() -> None:
     assert "poo_db_adopt" not in entrypoint
 
 
+def test_dockerfile_copy_sources_exist() -> None:
+    """Every path the Dockerfile COPYs from the build context must exist in the
+    repo, so the image build cannot break on a stale COPY of a removed path
+    (e.g. the retired alembic_location / alembic_poo chains)."""
+    dockerfile = (PROJECT_ROOT / "Dockerfile").read_text()
+    for raw_line in dockerfile.splitlines():
+        line = raw_line.strip()
+        if not line.startswith("COPY "):
+            continue
+        # Drop the "COPY" keyword and any flags (e.g. --from=, --chown=).
+        tokens = [t for t in line.split()[1:] if not t.startswith("--")]
+        # COPY <src...> <dest>: the last token is the destination.
+        for src in tokens[:-1]:
+            assert (PROJECT_ROOT / src).exists(), (
+                f"Dockerfile COPY source does not exist in the build context: {src}"
+            )
+
+
 def test_migration_runner_initializes_and_is_idempotent(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None: