Moving Helper

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

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

项目目标是小而稳、容易继续扩展。目前已经从“纯脚手架”进入第二阶段，支持固定三层的数据结构和基础 CRUD，但还没有开始做图片、搜索和复杂界面。

当前数据模型

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

• Box
• Item
• SubItem

关系如下：

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

换句话说，结构固定为：

Box
└── Item
    └── SubItem

当前已支持

目前已支持的基础能力：

• Box 列表、详情、新建、编辑、删除
• Item 新建、详情、编辑、删除
• SubItem 新建、编辑、删除
• / 重定向到 /boxes
• Jinja2 模板渲染
• 静态文件挂载
• SQLite 持久化
• Docker 长期运行
• 基础自动化测试

删除规则：

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

当前未实现

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

• 图片上传
• 图片字段
• 图片处理
• 搜索
• 登录 / 鉴权
• 标签系统
• 前后端分离
• 复杂 UI

项目结构

.
├── app
│   ├── __init__.py
│   ├── config.py
│   ├── db.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 删除后的级联删除
• 关键 POST 请求后的重定向行为