Moving Helper

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

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

项目目标是小而稳、容易继续扩展。目前已经支持固定三层的数据结构、基础 CRUD、单图上传能力和全局搜索，但仍然没有加入 OCR、AI 识别或其他扩展功能。

当前数据模型

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

• Box
• Item
• SubItem

关系如下：

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

结构固定为：

Box
└── Item
    └── SubItem

当前已支持

目前已支持的基础能力：

• Box 列表、详情、新建、编辑、删除
• Item 新建、详情、编辑、删除
• SubItem 新建、编辑、删除
• Box / Item / SubItem 单张图片上传、替换、删除、展示
• Box / Item / SubItem 全局搜索
• / 重定向到 /boxes
• Jinja2 模板渲染
• 静态文件挂载
• SQLite 持久化
• Docker 长期运行
• 基础自动化测试

删除规则：

• 删除 Box 时，会级联删除其下全部 Item 和对应 SubItem
• 删除容器型 Item 时，会级联删除其下 SubItem

图片能力说明

这一阶段的图片系统保持简单直接：

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

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

图片处理方式

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

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

同时还会记录：

• image_mime_type
• image_width
• image_height

图片访问通过普通 HTTP 路由返回 JPEG 数据，例如：

• /boxes/{id}/image
• /items/{id}/image
• /subitems/{id}/image

全局搜索

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

• 路由：/search
• 使用 query parameter，例如：/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

项目结构

.
├── app
│   ├── __init__.py
│   ├── config.py
│   ├── db.py
│   ├── images.py
│   ├── main.py
│   ├── models.py
│   ├── static
│   │   └── style.css
│   └── templates
│       ├── base.html
│       ├── boxes
│       ├── items
│       └── subitems
├── data
├── tests
│   ├── conftest.py
│   └── test_app.py
├── docker-compose.yml
├── Dockerfile
├── pytest.ini
├── README.md
└── requirements.txt

轻量配置

项目通过环境变量支持以下配置项：

• DATABASE_URL
• HOST
• PORT

默认值：

• DATABASE_URL=sqlite:///./data/app.db
• HOST=0.0.0.0
• PORT=10000

本地开发模式

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

1. 创建虚拟环境

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

2. 安装依赖

pip install -r requirements.txt

3. 启动开发服务器

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

访问：

http://localhost:10000

本地默认数据库位置：

./data/app.db

Docker 部署模式

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

启动：

docker compose up --build

访问：

http://localhost:10000

说明：

• 默认暴露 10000 端口
• restart: unless-stopped
• 容器使用 1000:1000 运行
• SQLite 文件持久化到宿主机 ./data/app.db
• 容器重建不会丢失数据

备份时直接复制 SQLite 文件即可：

./data/app.db

测试

运行测试：

python -m pytest

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

当前测试覆盖包括：

• Box / Item / SubItem 基础 CRUD
• 404 返回
• 非容器 Item 不能创建 SubItem
• Box / Item 删除后的级联删除
• 图片上传、转换为 JPEG、缩放、读取、替换、删除
• 全局搜索 name / note，并展示对象类型与归属路径
• 无图片访问和非法图片上传等错误路径
• 关键 POST 请求后的重定向行为