step 2 with basic crud implemented

README.md

@@ -1,15 +1,71 @@
-# Moving Helper Scaffold
+# Moving Helper
 
-这是一个面向可信家庭内网环境的小型工具项目，目前阶段只完成了基础脚手架：
+这是一个面向可信家庭内网环境的小型搬家记录工具，当前采用轻量技术栈：
 
 - FastAPI
-- Jinja2
+- Jinja2 服务端渲染
 - SQLAlchemy
 - SQLite
 - pytest / FastAPI TestClient
 - Docker / Docker Compose
 
-当前还不是完整业务应用，现阶段重点是把运行方式、工程结构、配置和基础测试打稳，后续再继续补 CRUD、图片、搜索等能力。
+项目目标是小而稳、容易继续扩展。目前已经从“纯脚手架”进入第二阶段，支持固定三层的数据结构和基础 CRUD，但还没有开始做图片、搜索和复杂界面。
+
+## 当前数据模型
+
+这个项目不是无限树结构，而是固定最多 3 级：
+
+- `Box`
+- `Item`
+- `SubItem`
+
+关系如下：
+
+- 一个 `Box` 包含多个 `Item`
+- 一个 `Item` 属于一个 `Box`
+- `Item` 通过 `is_container` 区分是否为“小容器”
+- 只有 `is_container = true` 的 `Item` 才允许拥有 `SubItem`
+- `SubItem` 是最后一级，不允许继续向下嵌套
+
+换句话说，结构固定为：
+
+```text
+Box
+└── Item
+    └── SubItem
+```
+
+## 当前已支持
+
+目前已支持的基础能力：
+
+- Box 列表、详情、新建、编辑、删除
+- Item 新建、详情、编辑、删除
+- SubItem 新建、编辑、删除
+- `/` 重定向到 `/boxes`
+- Jinja2 模板渲染
+- 静态文件挂载
+- SQLite 持久化
+- Docker 长期运行
+- 基础自动化测试
+
+删除规则：
+
+- 删除 `Box` 时，会级联删除其下全部 `Item` 和对应 `SubItem`
+- 删除容器型 `Item` 时，会级联删除其下 `SubItem`
+
+## 当前未实现
+
+这一阶段仍然没有实现以下内容：
+
+- 图片上传
+- 图片字段
+- 图片处理
+- 搜索
+- 登录 / 鉴权
+- 标签系统
+- 前后端分离
+- 复杂 UI
 
 ## 项目结构
 
@@ -25,32 +81,23 @@
 │   │   └── style.css
 │   └── templates
 │       ├── base.html
-│       └── boxes.html
+│       ├── boxes
+│       ├── items
+│       └── subitems
 ├── data
 ├── tests
 │   ├── conftest.py
 │   └── test_app.py
 ├── docker-compose.yml
 ├── Dockerfile
+├── pytest.ini
 ├── README.md
-├── requirements.txt
-└── .gitignore
+└── requirements.txt
 ```
 
-## 当前已接好的基础能力
-
-- FastAPI 应用入口：`app/main.py`
-- Jinja2 模板渲染
-- 静态文件挂载：`/static`
-- `/` 自动重定向到 `/boxes`
-- SQLite 数据库连接
-- SQLAlchemy Base / Session
-- 启动时自动建表
-- 基础自动化测试
-
 ## 轻量配置
 
-项目通过环境变量支持下面几个配置项：
+项目通过环境变量支持以下配置项：
 
 - `DATABASE_URL`
 - `HOST`
@@ -62,8 +109,6 @@
 - `HOST=0.0.0.0`
 - `PORT=10000`
 
-本地开发和 Docker 运行都可以直接使用这些默认值，也可以按需覆盖。
-
 ## 本地开发模式
 
 推荐使用本地 Python `venv` 开发和调试。
@@ -93,23 +138,17 @@ uvicorn app.main:app --reload --host 0.0.0.0 --port 10000
 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
@@ -121,65 +160,34 @@ docker compose up --build
 http://localhost:10000
 ```
 
-### 运行说明
+说明：
 
 - 默认暴露 `10000` 端口
-- `restart: unless-stopped`，适合长期运行
-- 容器内应用以用户 `1000:1000` 运行
-- SQLite 数据文件保存在宿主机 `./data/app.db`
-- 容器重建不会丢失数据库数据
+- `restart: unless-stopped`
+- 容器使用 `1000:1000` 运行
+- SQLite 文件持久化到宿主机 `./data/app.db`
+- 容器重建不会丢失数据
 
-### 数据持久化与备份
-
-`docker-compose.yml` 会将宿主机目录：
-
-```text
-./data
-```
-
-挂载到容器内：
-
-```text
-/app/data
-```
-
-因此数据库文件通常位于：
+备份时直接复制 SQLite 文件即可：
 
 ```text
 ./data/app.db
 ```
 
-备份时直接复制这个 SQLite 文件即可。
-
 ## 测试
 
-这个项目已经接入了最基础的测试设施：
-
-- `pytest`
-- `FastAPI TestClient`
-
 运行测试：
 
 ```bash
-pytest
+python -m pytest
 ```
 
-测试会使用独立的测试数据库文件，不会污染本地开发使用的 `data/app.db`。
+测试使用独立测试数据库，不会污染真实开发数据。
 
-当前测试覆盖：
+当前测试覆盖包括：
 
-- 应用可正常启动
-- `/` 会重定向到 `/boxes`
-- `/boxes` 可正常返回 `200`
-- 测试数据库与真实开发数据库隔离
-
-## 当前阶段未实现
-
-这一轮仍然没有开始做完整业务功能，下面这些内容后续再补：
-
-- Box / Item 完整 CRUD
-- 图片上传与处理
-- 搜索
-- 登录 / 鉴权
-- 复杂前端样式
-- 前后端分离
+- Box / Item / SubItem 基础 CRUD
+- 404 返回
+- 非容器 Item 不能创建 SubItem
+- Box / Item 删除后的级联删除
+- 关键 POST 请求后的重定向行为