# 仓库简报 / Repository Brief — 2026 搬家助手 (Moving Helper)

> 面向「下一轮改动」前的快速理解文档。中英双语对照。
> A bilingual orientation doc to read before the next round of changes.
>
> 对应版本 / Snapshot: `main` @ `b9b6583`（撰写时 / at time of writing）

---

## 1. 一句话定位 / In One Sentence

**中文：** 一个轻量的、面向**可信家庭内网**的搬家装箱记录工具：记录「有哪些箱子、每个箱子里有什么物品、容器型物品里又装了什么」，支持单图、全局搜索，并以 Docker 长期运行。

**EN:** A lightweight, **trusted-home-LAN** moving inventory tool: track *which boxes exist, what items each box holds, and what sub-items sit inside container-type items*. Supports one image per record, global search, and runs long-term via Docker.

设计取向 / Design stance：小而稳、易于几个月后回来继续扩展；**不是**企业平台、**不**追求复杂运维。
Small, stable, easy to pick back up months later; **not** an enterprise platform.

---

## 2. 技术栈 / Tech Stack

| 层 / Layer | 选型 / Choice | 版本 / Version |
| --- | --- | --- |
| Web 框架 / Framework | FastAPI | 0.116.1 |
| ASGI 服务器 / Server | Uvicorn (`[standard]`) | 0.35.0 |
| 模板 / Templating | Jinja2（服务端渲染 SSR） | 3.1.6 |
| ORM | SQLAlchemy 2.x（`Mapped` / `mapped_column` 风格） | 2.0.43 |
| 数据库 / DB | SQLite（文件库 / file-based） | — |
| 表单 / Forms | python-multipart | 0.0.20 |
| 图片处理 / Images | Pillow（HEIC 时可选 `pillow_heif` / `sips` 兜底） | 11.2.1 |
| HTTP 客户端 / Client | requests（仅 Notion 导入用） | 2.32.3 |
| 测试 / Tests | pytest + Starlette `TestClient`(httpx) | 8.4.1 / 0.28.1 |
| 部署 / Deploy | Docker / Docker Compose + nginx 反代 | — |

**没有前端构建链 / No frontend build chain**：纯 SSR + 一个 `style.css` + `base.html` 里的少量原生 JS。无 npm / Node / 打包器。
Pure SSR + one `style.css` + a little vanilla JS inline in `base.html`. No npm/Node/bundler.

---

## 3. 目录结构 / Project Layout

```text
.
├── app/
│   ├── __init__.py
│   ├── config.py            # 环境变量配置 (Settings dataclass)
│   ├── db.py                # SQLAlchemy engine/session、init_db、SQLite 轻量迁移
│   ├── images.py            # 图片处理管线 (Pillow + HEIC 兜底)
│   ├── main.py              # 所有路由 + 应用工厂 create_app()  ← 核心
│   ├── models.py            # Box / Item / SubItem 三个 ORM 模型
│   ├── notion_import.py     # 一次性 Notion 导入的解析/写入逻辑
│   ├── static/              # style.css, manifest, service-worker.js, PWA 图标
│   └── templates/           # Jinja2 模板 (boxes/ items/ subitems/ search/ + base.html)
├── scripts/
│   ├── install.sh           # 一键安装：渲染 nginx/backup/compose + cron
│   ├── deploy.sh            # 仓库内的轻量更新脚本 (git pull + compose up)
│   ├── backup_db.sh         # 备份脚本模板 (占位符由 install.sh 渲染)
│   ├── import_notion.py     # Notion 导入 CLI 入口
│   └── nginx/moving-helper.nginx.template
├── tests/                   # pytest：test_app.py (~74) + test_notion_import.py (9)
├── data/                    # 运行期 SQLite (data/app.db)，已 gitignore
├── .github/workflows/       # test.yml (CI) + docker-image.yml (CD)
├── Dockerfile, docker-compose.yml, .dockerignore
├── .env.example             # 部署配置示例（被 shell 脚本 source）
├── pytest.ini, requirements.txt, README.md
└── docs/                    # ← 本文档所在
```

**关键入口 / Key entry point：** `app/main.py` 里的 `create_app()` 注册了**全部**路由。整个后端逻辑几乎都在这一个文件里。
Almost all backend logic lives in the single `create_app()` factory in `app/main.py`.

---

## 4. 数据模型 / Data Model

固定**三级层次**，不是无限树 / A fixed **3-level hierarchy**, not an arbitrary tree：

```text
Box  (顶层容器 / top container：纸箱、行李箱…)
└── Item  (箱子里的物品 / an item in the box)
    └── SubItem  (仅容器型 Item 才有 / only under container items)
```

定义于 `app/models.py`：

| 模型 / Model | 表 / Table | 关键字段 / Key fields | 关系 / Relations |
| --- | --- | --- | --- |
| `Box` | `boxes` | `name`, `note`, `room`, `status` + 图片字段 + 时间戳 | `items` → 多个 Item（`cascade="all, delete-orphan"`） |
| `Item` | `items` | `box_id`(FK), `name`, `note`, `quantity`, `is_container` + 图片字段 + 时间戳 | 属于一个 `Box`；`subitems` → 多个 SubItem（级联删除） |
| `SubItem` | `subitems` | `parent_item_id`(FK), `name`, `note`, `quantity` + 图片字段 + 时间戳 | 属于一个 `Item` |

**核心规则 / Core rules：**

- 只有 `Item.is_container == True` 的物品才允许拥有 `SubItem`；非容器去建子物品会返回 **400**（`_require_container_item`）。
  Only container items may hold sub-items; otherwise the API returns **400**.
- 在更新 Item 时，若取消勾选 `is_container`，会**清空其所有 SubItem**（`item.subitems.clear()`，`main.py:454`）。
  Un-checking `is_container` on update **clears all sub-items**.
- 删除级联：删 Box → 删其 Item → 删其 SubItem，由 ORM `cascade` + 外键 `ondelete="CASCADE"` 双重保障（SQLite 还启用了 `PRAGMA foreign_keys=ON`）。
  Delete cascades top-down, enforced both by ORM cascade and FK `ondelete`.

**图片字段（每个模型都有同一组）/ Image fields (same set on every model)：**
`image_blob` (BLOB)、`image_mime_type`、`image_width`、`image_height`。
→ 图片直接以二进制存进 SQLite，**不落地为文件**。Images are stored **inline as BLOBs in SQLite**, not as files.

时间戳 / Timestamps：`created_at`、`updated_at`（UTC，`updated_at` 带 `onupdate`）。

---

## 5. 路由总览 / Route Map

全部在 `app/main.py`。POST 后统一 **303 See Other** 重定向（避免重复提交）。
All in `app/main.py`. POSTs redirect with **303 See Other**.

| 方法 路径 / Method Path | 作用 / Purpose |
| --- | --- |
| `GET /` | 302 跳转到 `/boxes` |
| `GET /manifest.webmanifest`, `GET /service-worker.js` | PWA 资源（从根路径返回） |
| `GET /search?q=` | 全局搜索页 |
| `GET /boxes` | 箱子列表 + 概览统计 |
| `GET /boxes/new` · `POST /boxes` | 新建箱子表单 / 提交 |
| `GET /boxes/{id}` | 箱子详情（含其 Item 列表） |
| `GET /boxes/{id}/edit` · `POST /boxes/{id}/update` | 编辑 / 保存 |
| `POST /boxes/{id}/delete` | 删除箱子 |
| `GET /boxes/{id}/image` · `POST /boxes/{id}/image/delete` | 取图 / 删图 |
| `GET /boxes/{id}/items/new` · `POST /boxes/{id}/items` | 在箱子下新建物品 |
| `GET /items/{id}` | 物品详情（容器型则含 SubItem 列表） |
| `GET /items/{id}/edit` · `POST /items/{id}/update` · `POST /items/{id}/delete` | 编辑 / 保存 / 删除 |
| `GET /items/{id}/image` · `POST /items/{id}/image/delete` | 取图 / 删图 |
| `GET /items/{id}/subitems/new` · `POST /items/{id}/subitems` | 在容器型物品下新建子物品 |
| `GET /subitems/{id}/edit` · `POST /subitems/{id}/update` · `POST /subitems/{id}/delete` | 编辑 / 保存 / 删除 |
| `GET /subitems/{id}/image` · `POST /subitems/{id}/image/delete` | 取图 / 删图 |

**重定向行为细节 / Redirect nuances**（`main.py` 创建逻辑）：

- 创建物品时，若点「保存并添加下一个」(`submit_action=save_and_add_next`) → 回到新建表单；若是容器型 → 跳到物品详情；否则 → 回箱子详情。
  On create: *save & add next* → back to new form; container → item detail; else → box detail.
- 子物品的「保存并添加下一个」同理回到子物品新建表单。
  Sub-item *save & add next* returns to its new-form too.

> 没有 JSON API / no JSON API：全部返回 HTML（图片路由返回二进制）。FastAPI 的自动 `/docs` 仍可用，但业务路由均是表单驱动的 SSR。

---

## 6. 图片处理管线 / Image Pipeline (`app/images.py`)

每次上传都会经过 `process_upload()` → `_prepare_image()` 统一处理：
Every upload is normalized through `process_upload()` → `_prepare_image()`:

1. 读取字节，空内容 → 400；非法图片 → 400。Read bytes; empty/invalid → 400.
2. **按 EXIF 方向矫正**（`ImageOps.exif_transpose`），再处理。Apply EXIF orientation first.
3. 去元数据并转 RGB（`RGBA/LA` 贴白底、`P` 转 RGB）。Strip metadata, flatten to RGB.
4. **最长边缩放到 ≤ 1600px**（`thumbnail`）。Downscale longest side to ≤ 1600px.
5. 存为 **JPEG，质量 80，`optimize=True`**。Save as JPEG q80.
6. 写入 `image_blob` + 记录 mime / 宽 / 高。Store blob + dimensions.

**HEIC/HEIF 兜底 / fallback：** 先尝试 `pillow_heif`（若已安装）；否则在 macOS 上用 `sips` 转 JPEG；都不行则返回中文错误提示让用户先转格式。
Tries `pillow_heif`, then macOS `sips`, else a clear error asking to convert first.

> 注意 / Note：`pillow_heif` **不在** `requirements.txt` 里，所以默认环境 HEIC 依赖系统 `sips`（仅 macOS）。Linux 容器里上传 HEIC 会得到「请先转换」的提示。

每个对象**最多一张图**，支持上传 / 替换 / 删除，不支持多图。
One image per object; upload/replace/delete; no multi-image.

---

## 7. 全局搜索 / Global Search (`_build_search_results`, `main.py`)

- `GET /search?q=关键词`，对 `Box / Item / SubItem` 的 `name` 和 `note` 做 **SQLite `LOWER(...) LIKE %q%`** 模糊匹配（大小写不敏感）。
  Case-insensitive `LIKE` over `name` + `note` across all three types.
- 结果带：类型标签、归属路径（Item 显示所属 Box，SubItem 显示所属 Item + Box）、若有图则带缩略图链接。
  Results include type, location path, and a thumbnail link if an image exists.
- 无外部搜索引擎、无全文索引。No external search engine / full-text index.

`/boxes` 概览页另有统计（`_build_boxes_overview_summary`）：箱子数、物品数（含/不含子物品）、每箱平均物品数、每容器型 Item 平均子物品数。

---

## 8. PWA 支持 / PWA Support

最小可安装 PWA，**不改 SSR 结构** / minimal installable PWA without changing SSR：

- 根路径提供 `manifest.webmanifest`（正确 mime）和 `service-worker.js`。
- `base.html` 注入 theme-color、apple-touch-icon、安装相关 meta，并注册 service worker。
- 图标：180（apple-touch）、192、512、512-maskable，位于 `app/static/icons/`。

**当前 service worker 仅做 `skipWaiting` + `clients.claim()`，没有任何缓存/离线能力。**
The service worker only claims clients — **no caching, no offline** yet.

`base.html` 里的原生 JS 还实现了：可点击卡片（`.clickable-card[data-href]`，含键盘 Enter/Space 支持）、表单内回车跳到下一个字段。

---

## 9. 配置与环境变量 / Configuration

**应用运行时 / App runtime**（`app/config.py`，`Settings` dataclass）：

| 变量 / Var | 默认 / Default | 说明 |
| --- | --- | --- |
| `DATABASE_URL` | `sqlite:///./data/app.db` | 数据库连接串 |
| `HOST` | `0.0.0.0` | （定义了但 uvicorn 在 CMD 里写死） |
| `PORT` | `10000` | 同上 |

**部署时 / Deploy-time**（`.env`，被 shell 脚本 `source`，**非**应用直接读取）：
`HOST_DOMAIN`、`SSL_PATH`、`APP_DIR`、`BACKUP_DIR`、`BACKUP_REMOTE`、`APP_PORT`、`DATA_DIR`、`DATABASE_URL`、`COMPOSE_PROJECT_NAME`。详见 `.env.example`。

约定 / Conventions：容器内固定监听 `0.0.0.0:10000`；`APP_PORT` 只控制宿主机暴露端口；SQLite 固定写 `/app/data/app.db`（容器内）。

---

## 10. 数据库初始化与迁移 / DB Init & Migrations (`app/migrate.py` + `app/db.py`)

- **Alembic 接管 schema**：迁移系统由 Alembic 管理（`alembic.ini` + `migrations/`），V1 baseline 等于当前三表 schema。
  Alembic owns schema creation and changes (`alembic.ini` + `migrations/`); V1 baseline equals the current three-table schema.
- **迁移与启动分离 / Migrations separated from startup**：
  - `init_db()`（`app/db.py`）在 FastAPI lifespan 启动时调用 `verify_schema_is_current()`，只做**只读校验**——检查 DB 是否在 `head`，不一致则 **fail-close**（拒绝启动、不执行任何 DDL）。
    `init_db()` calls `verify_schema_is_current()` at startup — read-only check, fails closed on mismatch, no DDL.
  - 实际迁移由独立幂等命令 `python -m app.migrate`（`app/migrate.py`）执行：空库建表、老库认领（stamp V1 → upgrade head）、已在 head 则空操作。老库 schema 不匹配则 fail-close 不改动。
    Actual migration via standalone idempotent command `python -m app.migrate`: fresh DB → create, matching existing → adopt, already-at-head → no-op, mismatch → fail closed.
- SQLite 连接开启 `PRAGMA foreign_keys=ON`。
- 手写列同步 `_sync_sqlite_image_columns()` 已退休删除。
  The hand-rolled `_sync_sqlite_image_columns()` has been retired and removed.

---

## 11. 部署 / Deployment

**Docker**（`Dockerfile`）：`python:3.12-slim` → 装依赖 → 拷贝 `app/` → `uvicorn app.main:app --host 0.0.0.0 --port 10000`。

**Compose**（`docker-compose.yml`）：
- 镜像固定 `code.wanderingbadger.dev/tliu93/2026-moving-helper:latest`，同时保留 `build:` 用于本地构建。
- `user: "1000:1000"`，仅 `127.0.0.1:${APP_PORT}:10000` 暴露，`${DATA_DIR}:/app/data` 持久化，`restart: unless-stopped`。

**一键安装**（`scripts/install.sh`，需 root/sudo 写 nginx）：读 `.env` → 拷 compose/.env/渲染后的 backup 脚本到 `APP_DIR` → 渲染并启用 nginx 站点 → `nginx -t` + reload → `docker compose pull && up -d` → 写每日 `02:10` 备份 cron。无 `.env` 直接退出。

**轻量更新**（`scripts/deploy.sh`）：`git pull --ff-only` → `docker compose pull web` → `up -d` → 打印状态/日志。

**nginx 模板**（`scripts/nginx/...`）：80→443 跳转、443 启用 SSL、反代到 `127.0.0.1:${APP_PORT}`、`client_max_body_size 0`。证书由用户自备于 `SSL_PATH`（`fullchain.pem` / `privkey.key`）。

**备份**（`scripts/backup_db.sh`，模板带占位符由 install 渲染）：用 `sqlite3 .backup` 取事务一致快照（不停容器），文件名带时间戳，**最多保留 5 个**，`BACKUP_REMOTE` 非空时 `rclone sync` 到远端。

---

## 12. CI / CD（`.github/workflows/`）

- **`test.yml`（CI）**：任意分支 `push` 触发 → Python 3.12 → 装依赖 → `pytest`。无需外部服务/DB。
- **`docker-image.yml`（CD）**：`v*` tag 触发；**先校验该 tag 提交可从 `origin/main` 到达**，再 buildx 构建 `linux/amd64` + `linux/arm64`，推 `:${tag}` 和 `:latest`。
- 需在仓库 Secrets 配 `REGISTRY_USERNAME` / `REGISTRY_TOKEN`（Gitea container registry）。

发布流程 / Release：`git tag vX.Y.Z && git push origin main --tags`。

---

## 13. 测试 / Tests

- `tests/conftest.py`：每个测试用 `tmp_path` 建独立 SQLite，`configure_database(...)` 切换，再 `create_app()` —— **不污染** `data/app.db`，无需 Docker。
  Each test gets an isolated tmp SQLite; never touches dev data.
- `tests/test_app.py`（约 74 个）：Box/Item/SubItem CRUD、级联删除、404、图片上传/替换/删除/错误路径、EXIF 矫正、图片路由、搜索（name/note/路径/缩略图）、重定向行为、页面结构与 UX 文案、概览统计。
- `tests/test_notion_import.py`（9 个）：page id 提取、heading/bullet 解析、容器判定、超层级警告、媒体跳过、dry-run 不写库、apply 写库结构。

运行 / Run：`python -m pytest`。

---

## 14. Notion 一次性导入 / One-time Notion Import

`app/notion_import.py` + `scripts/import_notion.py`（交互式 CLI，`--dry-run` / `--apply`）。

结构映射 / Mapping：`heading_2` → `Box`；其下一级 bullet → `Item`；二级 bullet → `SubItem`（此时父 bullet 自动判为容器型）。更深层级只警告不导入；**不导入任何图片/媒体**。

定位 / Positioning：**一次性 migration 工具，非长期同步**；建议导入前先备份 `data/app.db`。`NOTION_VERSION = "2026-03-11"`。

---

## 15. 已知约束 & 下一轮改动建议 / Constraints & Notes for the Next Round

**当前明确「未实现」/ Explicitly out of scope（见 README）：** 离线缓存/同步、多图、OCR、AI 识别、图片标签/分类、登录鉴权、标签系统、前后端分离、复杂 UI。

**改动前值得注意的点 / Things to watch before changing things：**

1. **无鉴权 / No auth.** 设计前提是「可信内网 + nginx HTTPS」。任何要暴露到公网的改动都需先加访问控制。
2. **迁移机制薄弱 / Weak migrations（§10）.** 加新字段到已有库不会自动建列。建议：要么扩展 `_sync_sqlite_image_columns` 思路（改成更通用的列同步），要么正式引入 Alembic。
3. **图片存在 SQLite 里 / Images live in the DB.** 好处是备份/迁移只需一个文件；代价是库体积随图增长、备份成本上升。若要支持多图或大图归档，应考虑改为对象存储/文件系统 + 路径引用。
4. **逻辑高度集中在 `main.py` / Logic concentrated in `main.py`.** 路由、表单解析、查询、统计、搜索都在一个文件。新增大功能时可考虑拆分 router/service 模块，但要保留 `create_app()` 工厂以维持测试隔离。
5. **Service Worker 是空壳 / SW is a stub.** README 写的「PWA」目前不含离线能力；要做离线需真正实现缓存策略。
6. **固定 3 级层次 / Fixed 3 levels.** `Box → Item → SubItem` 写死在模型、路由、模板、Notion 解析多处；若要变成可嵌套树，是一次跨层改动。
7. **HEIC 在 Linux 容器里不可用 / HEIC fails in Linux containers**（`pillow_heif` 未列入依赖，`sips` 仅 macOS）。若用户多用 iPhone 原图，考虑把 `pillow_heif` 加进 `requirements.txt`。
8. **UI 全中文、SSR、单 `style.css`.** 前端改动直接编辑 `app/templates/*` 与 `app/static/style.css`，无构建步骤。

---

## 16. 本地快速启动 / Quick Local Start

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 10000
# 打开 / open http://localhost:10000  (默认数据库 / default DB: ./data/app.db)
python -m pytest        # 跑测试 / run tests
```