add image flow

README.md

@@ -6,10 +6,11 @@
 - Jinja2 服务端渲染
 - SQLAlchemy
 - SQLite
+- Pillow
 - pytest / FastAPI TestClient
 - Docker / Docker Compose
 
-项目目标是小而稳、容易继续扩展。目前已经从“纯脚手架”进入第二阶段，支持固定三层的数据结构和基础 CRUD，但还没有开始做图片、搜索和复杂界面。
+项目目标是小而稳、容易继续扩展。目前已经支持固定三层的数据结构、基础 CRUD，以及单图上传能力，但仍然没有加入搜索、OCR、AI 识别或其他扩展功能。
 
 ## 当前数据模型
 
@@ -27,7 +28,7 @@
 - 只有 `is_container = true` 的 `Item` 才允许拥有 `SubItem`
 - `SubItem` 是最后一级，不允许继续向下嵌套
 
-换句话说，结构固定为：
+结构固定为：
 
 ```text
 Box
@@ -42,6 +43,7 @@ Box
 - Box 列表、详情、新建、编辑、删除
 - Item 新建、详情、编辑、删除
 - SubItem 新建、编辑、删除
+- Box / Item / SubItem 单张图片上传、替换、删除、展示
 - `/` 重定向到 `/boxes`
 - Jinja2 模板渲染
 - 静态文件挂载
@@ -54,14 +56,52 @@ Box
 - 删除 `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`
+
 ## 当前未实现
 
 这一阶段仍然没有实现以下内容：
 
-- 图片上传
-- 图片字段
-- 图片处理
 - 搜索
+- 多图上传
+- OCR
+- AI 识别物品
+- 图片标签
+- 图片分类
 - 登录 / 鉴权
 - 标签系统
 - 前后端分离
@@ -75,6 +115,7 @@ Box
 │   ├── __init__.py
 │   ├── config.py
 │   ├── db.py
+│   ├── images.py
 │   ├── main.py
 │   ├── models.py
 │   ├── static
@@ -190,4 +231,6 @@ python -m pytest
 - 404 返回
 - 非容器 Item 不能创建 SubItem
 - Box / Item 删除后的级联删除
+- 图片上传、转换为 JPEG、缩放、读取、替换、删除
+- 无图片访问和非法图片上传等错误路径
 - 关键 POST 请求后的重定向行为