# Moving Helper Scaffold

这是一个面向可信家庭内网环境的小型工具项目，目前阶段只完成了基础脚手架：

- FastAPI
- Jinja2
- SQLAlchemy
- SQLite
- pytest / FastAPI TestClient
- Docker / Docker Compose

当前还不是完整业务应用，现阶段重点是把运行方式、工程结构、配置和基础测试打稳，后续再继续补 CRUD、图片、搜索等能力。

## 项目结构

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

## 当前已接好的基础能力

- FastAPI 应用入口：`app/main.py`
- Jinja2 模板渲染
- 静态文件挂载：`/static`
- `/` 自动重定向到 `/boxes`
- SQLite 数据库连接
- SQLAlchemy Base / Session
- 启动时自动建表
- 基础自动化测试

## 轻量配置

项目通过环境变量支持下面几个配置项：

- `DATABASE_URL`
- `HOST`
- `PORT`

默认值：

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

本地开发和 Docker 运行都可以直接使用这些默认值，也可以按需覆盖。

## 本地开发模式

推荐使用本地 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
```

如果你想临时改端口或数据库路径，也可以这样运行：

```bash
PORT=10000 DATABASE_URL=sqlite:///./data/app.db uvicorn app.main:app --reload --host 0.0.0.0 --port 10000
```

## Docker 部署模式

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

### 启动

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

访问：

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

### 运行说明

- 默认暴露 `10000` 端口
- `restart: unless-stopped`，适合长期运行
- 容器内应用以用户 `1000:1000` 运行
- SQLite 数据文件保存在宿主机 `./data/app.db`
- 容器重建不会丢失数据库数据

### 数据持久化与备份

`docker-compose.yml` 会将宿主机目录：

```text
./data
```

挂载到容器内：

```text
/app/data
```

因此数据库文件通常位于：

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

备份时直接复制这个 SQLite 文件即可。

## 测试

这个项目已经接入了最基础的测试设施：

- `pytest`
- `FastAPI TestClient`

运行测试：

```bash
pytest
```

测试会使用独立的测试数据库文件，不会污染本地开发使用的 `data/app.db`。

当前测试覆盖：

- 应用可正常启动
- `/` 会重定向到 `/boxes`
- `/boxes` 可正常返回 `200`
- 测试数据库与真实开发数据库隔离

## 当前阶段未实现

这一轮仍然没有开始做完整业务功能，下面这些内容后续再补：

- Box / Item 完整 CRUD
- 图片上传与处理
- 搜索
- 登录 / 鉴权
- 复杂前端样式
- 前后端分离