add project structure

README.md

@@ -0,0 +1,185 @@
+# 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
+- 图片上传与处理
+- 搜索
+- 登录 / 鉴权
+- 复杂前端样式
+- 前后端分离