2026-moving-helper/README.md

# Moving Helper

这是一个面向可信家庭内网环境的小型搬家记录工具，当前采用轻量技术栈：

- FastAPI
- Jinja2 服务端渲染
- SQLAlchemy
- SQLite
- Pillow
- pytest / FastAPI TestClient
- Docker / Docker Compose

项目目标是小而稳、容易继续扩展。它不是企业平台，也不是复杂运维系统，重点是本地开发简单、容器部署稳定、数据持久化清楚、后续几个月后自己回来看也能快速接上。

## 当前已支持

- 固定 3 级结构：`Box -> Item -> SubItem`
- Box / Item / SubItem 基础 CRUD
- Box / Item / SubItem 单图上传、替换、删除、展示
- Box / Item / SubItem 全局搜索
- Docker / Compose 长期运行
- SQLite 数据持久化
- 基础自动化测试

## 当前数据模型

这个项目不是无限树结构，而是固定最多 3 级：

- `Box`
- `Item`
- `SubItem`

关系如下：

- 一个 `Box` 包含多个 `Item`
- 一个 `Item` 属于一个 `Box`
- `Item` 通过 `is_container` 区分是否为“小容器”
- 只有 `is_container = true` 的 `Item` 才允许拥有 `SubItem`
- `SubItem` 是最后一级，不允许继续向下嵌套

结构固定为：

```text
Box
└── Item
    └── SubItem
```

## 图片能力说明

图片系统保持简单直接：

- `Box` 最多支持 1 张图片
- `Item` 最多支持 1 张图片
- `SubItem` 最多支持 1 张图片
- 支持上传、替换、删除
- 不支持多图

图片主要用于帮助识别物品、提高浏览效率、方便手机拍照后直接附加到记录中。它不是原图归档系统。

上传图片后，系统会使用 Pillow 做统一处理：

- 读取上传图片
- 去除 EXIF 元数据
- 转换为 JPEG
- 按最长边缩放到不超过 `1600px`
- 使用约 `80` 质量保存
- 将处理后的 JPEG 二进制直接写入 SQLite `BLOB`

同时还会记录：

- `image_mime_type`
- `image_width`
- `image_height`

图片访问路由例如：

- `/boxes/{id}/image`
- `/items/{id}/image`
- `/subitems/{id}/image`

## 全局搜索

当前支持一个轻量的全局搜索页：

- 路由：`/search`
- 方式：`GET /search?q=关键词`

搜索范围包括：

- `Box.name`
- `Box.note`
- `Item.name`
- `Item.note`
- `SubItem.name`
- `SubItem.note`

当前使用 SQLite 上的简单模糊匹配，不引入外部搜索引擎或复杂全文系统。

搜索结果会显示：

- 对象类型：`Box / Item / SubItem`
- 名称和备注
- 归属路径
- 对 `Item` 展示所属 `Box`
- 对 `SubItem` 展示所属 `Item` 和 `Box`
- 如果对象已有图片，会显示一个小缩略图

## 当前未实现

这一阶段仍然没有实现以下内容：

- 多图上传
- OCR
- AI 识别物品
- 图片标签
- 图片分类
- 登录 / 鉴权
- 标签系统
- 前后端分离
- 复杂 UI

## 项目结构

```text
.
├── app
│   ├── __init__.py
│   ├── config.py
│   ├── db.py
│   ├── images.py
│   ├── main.py
│   ├── models.py
│   ├── static
│   │   └── style.css
│   └── templates
├── data
├── scripts
│   ├── backup_db.sh
│   └── deploy.sh
├── tests
├── .dockerignore
├── .env.example
├── docker-compose.yml
├── Dockerfile
├── pytest.ini
├── README.md
└── requirements.txt
```

## 轻量配置

项目通过环境变量支持以下部署时真正需要关心的配置：

- `HOST`
- `PORT`
- `DATABASE_URL`
- `DATA_DIR`
- `UID`
- `GID`

推荐从示例文件开始：

```bash
cp .env.example .env
```

默认值如下：

```env
HOST=0.0.0.0
PORT=10000
DATABASE_URL=sqlite:////app/data/app.db
DATA_DIR=./data
UID=1000
GID=1000
```

说明：

- 本地开发默认数据库仍然是 `./data/app.db`
- Docker 内建议继续使用 `sqlite:////app/data/app.db`
- `DATA_DIR` 控制宿主机上的持久化目录
- `UID/GID` 用来让容器内文件权限更贴近宿主机用户

## 本地开发模式

推荐使用本地 Python `venv` 开发和调试。

### 1. 创建虚拟环境

```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 启动开发服务器

```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 10000
```

访问：

```text
http://localhost:10000
```

本地默认数据库位置：

```text
./data/app.db
```

## Docker 运行方式

Docker / Compose 是这个项目面向长期运行环境的方式。

### 首次准备

```bash
cp .env.example .env
mkdir -p data
```

### 启动 / 更新

```bash
docker compose up -d --build
```

### 查看状态

```bash
docker compose ps
```

### 查看日志

```bash
docker compose logs -f web
```

访问：

```text
http://localhost:10000
```

### Compose 配置说明

当前 `docker-compose.yml` 保持尽量简单：

- 默认暴露 `10000` 端口
- `restart: unless-stopped`
- 容器用户来自 `UID:GID`
- 宿主机 `DATA_DIR` 挂载到容器内 `/app/data`
- SQLite 默认写入 `/app/data/app.db`

## 自动化部署

这个项目没有复杂 CI/CD，只提供一个适合家用项目的轻量部署脚本：

```bash
./scripts/deploy.sh
```

它会按顺序执行：

1. 检查 `.env`
2. 准备数据目录
3. 如果当前目录是 git 仓库，执行 `git pull --ff-only`
4. 执行 `docker compose up -d --build`
5. 输出容器状态
6. 输出最近日志

这个脚本的目标不是做平台化发布，而是让“更新代码并刷新容器”变成一个稳定、可重复执行的动作。

如果你不想自动拉代码，也可以直接手动运行：

```bash
docker compose up -d --build
```

## 数据持久化

当前 SQLite 文件默认会保存在：

- 宿主机：`./data/app.db`
- 容器内：`/app/data/app.db`

这是因为 `docker-compose.yml` 把：

```text
${DATA_DIR:-./data}
```

挂载到了容器内：

```text
/app/data
```

因此：

- 容器重建不会删除宿主机上的数据库文件
- 更新镜像不会导致 SQLite 数据丢失
- 只要保留 `DATA_DIR` 目录，数据就还在

## 备份与恢复

### 最简单的备份方式

直接复制 SQLite 文件即可：

```bash
cp data/app.db backups/app.db
```

或者使用附带脚本：

```bash
./scripts/backup_db.sh
```

它会在 `backups/` 目录下生成一个带时间戳的副本。

### 最简单的恢复方式

停止容器后，把备份文件覆盖回去：

```bash
docker compose stop
cp backups/app-YYYYMMDD-HHMMSS.db data/app.db
docker compose up -d
```

## 常见排查

### 1. 查看容器日志

```bash
docker compose logs -f web
```

### 2. 确认服务是否已启动

```bash
docker compose ps
```

如果状态是 `Up`，通常说明容器已经跑起来了。

### 3. 确认端口映射

```bash
docker compose port web 10000
```

### 4. 确认数据库文件还在

```bash
ls -lh data
```

如果看到 `app.db`，说明宿主机持久化文件还在。

### 5. 容器更新后数据为什么没丢

因为数据库不放在镜像里，而是放在宿主机挂载目录 `DATA_DIR` 中。  
镜像更新只会替换应用代码和运行环境，不会覆盖这个宿主机目录。

## 测试

运行测试：

```bash
python -m pytest
```

测试使用独立测试数据库，不会污染真实开发数据。

当前测试覆盖包括：

- Box / Item / SubItem 基础 CRUD
- 图片上传、替换、删除与错误路径
- 全局搜索 name / note
- 创建后的重定向行为
- 关键页面结构和 UX 文案

## 一次性 Notion 导入

项目内附带了一个一次性迁移脚本：

```bash
python scripts/import_notion.py --dry-run
python scripts/import_notion.py --apply
```

说明：

- 这是一次性 migration / import 工具，不是长期同步功能
- 运行时会交互要求输入：
  - Notion API token
  - Notion 页面完整 URL
- `--dry-run` 只读取和解析，不写数据库
- `--apply` 会真正写入当前 SQLite 数据库
- 建议导入前先备份 `data/app.db`

### 当前支持的 Notion 结构映射

- `heading_2` -> `Box`
- 某个 `heading_2` 下的一级 bullet -> `Item`
- 如果一级 bullet 下还有二级 bullet：
  - 一级 bullet -> 容器型 `Item`
  - 二级 bullet -> `SubItem`

当前最大只处理到这个层级：

```text
heading_2
└── 一级 bullet
    └── 二级 bullet
```

更深层级会在日志中提示，但不会继续扩展成无限树。

### 这一版不导入图片

这一版导入脚本：

- 不下载图片
- 不导入图片
- 遇到图片或其他媒体 block 时会提示已跳过

图片后续可以在应用里手动补录。