状态:账号认证、物品与图片、举报、匹配通知、管理审计和校准接口均已实现;全部 migration 已在本地 MySQL 完成升级验证。
本地验证:2026-10-21;95 个默认测试、3 个 MySQL 集成测试,以及迁移的部分/完整回滚再升级通过。
后端采用 Python 3.12、FastAPI、SQLAlchemy 和 MySQL,并按照“接口层 → 服务层 → 数据访问层 → 数据模型层”组织。GET /api/v1/items 通过 Repository 查询 MySQL;内存 Repository 只用于不依赖数据库的快速测试。
完整的分层职责和依赖规则见 后端架构,数据库演进要求见 数据库与迁移。
- Python 3.12
- uv
- Docker Desktop,或兼容 MySQL 8.4 配置的本地 MySQL
依赖版本记录在 pyproject.toml 和 uv.lock。虚拟环境、缓存和 .env 不提交到 Git。
先在 backend/ 目录安装依赖并复制本地配置。
# Windows PowerShell
uv sync
Copy-Item .env.example .env# macOS 或 Linux
uv sync
cp .env.example .env然后在两种系统上执行相同命令:
docker compose up -d mysql
uv run alembic upgrade head
uv run python -m scripts.seed_items
uv run uvicorn app.main:app --reload启动后的默认地址:
- 健康检查:
http://127.0.0.1:8000/health - OpenAPI UI:
http://127.0.0.1:8000/docs - 物品列表:
http://127.0.0.1:8000/api/v1/items
compose.yaml 为 macOS 和 Windows 提供相同的 MySQL 8.4、UTF-8 和 UTC 配置。.env.example 中的账号仅供本地开发;生产环境必须替换为独立强密码。
如果系统已有 MySQL,可以不使用 Docker,但需要自行创建数据库和最小权限账号,并在 .env 中设置 DATABASE_URL。
在 backend/ 目录执行:
# 升级到最新结构
uv run alembic upgrade head
# 查看当前版本
uv run alembic current
# 查看迁移历史
uv run alembic history
# 回滚一个版本;执行前必须确认不会丢失有效数据
uv run alembic downgrade -1已经合并或在共享环境执行过的 migration 不得修改;结构变化必须创建新的 migration。
最新迁移为 20261021_0005,新增独立外键支撑索引,修复历史迁移回滚时 MySQL 报错 1553 的问题。降到 0004 时刻意保留兼容索引,继续回滚删除对应表/列时一并清除。完整回滚验证只允许在一次性测试库执行,步骤见测试策略。
uv run ruff check .
uv run pytest默认测试使用内存 Repository,不会连接个人数据库。数据库集成测试需要显式提供隔离的测试库:
$env:TEST_DATABASE_URL = $env:DATABASE_URL
uv run pytest -m mysql代码检查和测试均应以退出码 0 结束。2026-10-21 本地验证中,Ruff
检查通过,95 个默认测试及 3 个显式启用的 MySQL 集成测试通过。CI 统一检查名为 CI passed,本地复现步骤见测试策略。
返回服务名称、版本和运行环境,用于确认 FastAPI 已成功启动。
返回稳定排序的分页记录,支持以下查询参数:
| 参数 | 作用 |
|---|---|
keyword |
搜索标题、描述、类别和地点 |
type |
lost 或 found |
category |
精确匹配物品类别 |
campus |
东丽校区或宁河校区 |
area |
北区或南区 |
status |
记录状态;未提供时只返回 active |
days |
查询最近 1~365 天 |
page |
页码,从 1 开始 |
page_size |
每页数量,范围 1~100 |
示例:
GET /api/v1/items?keyword=耳机&type=found&campus=宁河校区&page=1&page_size=20
| 方法与路径 | 认证 | 作用 |
|---|---|---|
GET /api/v1/items/{id} |
否 | 读取单条记录的公开详情,不返回完整联系方式和发布者编号 |
POST /api/v1/items |
Bearer | 发布失物或拾物,所有者固定为当前用户 |
GET /api/v1/users/me/items |
Bearer | 按类型、状态和分页查询自己的记录 |
PATCH /api/v1/items/{id} |
Bearer | 发布者或管理员编辑仍在进行中的记录 |
PATCH /api/v1/items/{id}/status |
Bearer | 标记为已找回、已归还或已关闭,并写入状态审计 |
完整联系方式只在发布响应和“我的记录”等所有者视图中返回,公开列表与公开详情仅返回 contact_hint。失物只能进入 recovered 或 closed,拾物只能进入 returned 或 closed;第一阶段的终态不可重复修改。
图片通过 POST /api/v1/uploads/images 上传,支持 JPG、PNG 和 WebP,默认单张最多 5MB。发布或编辑请求最多传入三个属于当前用户的 image_ids;关联成功后公开物品响应通过 image_urls 返回读取地址。
| 模块 | 主要接口 |
|---|---|
| 举报 | POST /api/v1/items/{id}/reports、GET /api/v1/users/me/reports、GET/PATCH /api/v1/admin/reports |
| 匹配 | GET /api/v1/notifications、GET /api/v1/matches/{id}、已读和反馈接口 |
| 管理 | /api/v1/admin/overview、/api/v1/admin/users、/api/v1/admin/audit |
| 校准 | /api/v1/admin/calibration/tasks、/api/v1/admin/calibration/versions |
新物品发布后会与同校区、相反类型的进行中记录进行规则评分,并向双方所有者创建去重通知。匹配分数是候选排序信号,不表示找回概率。管理员处理举报、用户状态和校准版本时必须提供理由,服务端写入不可变审计日志。
文本维度由已配置的大模型比较标题与描述的语义,与图文分在同一次请求中返回。 模型未启用、失败或候选未进入比较批次时,文本显示“未评估”,不使用共同字符比例。
2026-10-08 地点规则接入离线校园距离表: 已定位点使用预计算的地图代表点直线距离,缺少坐标时显示未评估、不加地点分。 原有六个未定位业务地点已按用户要求填入模拟坐标并参与评分; 涉及它们的匹配依据明确标注模拟距离。测试占位地点仍不计地点分。
| 方法与路径 | 作用 |
|---|---|
POST /api/v1/auth/register |
使用校园账号和至少 8 位密码注册普通用户 |
POST /api/v1/auth/login |
登录并返回有有效期的 Bearer 会话令牌 |
POST /api/v1/auth/logout |
吊销当前 Bearer 会话 |
GET /api/v1/users/me |
返回当前用户、角色、状态和校园验证状态 |
除注册和登录外,受保护接口使用 Authorization: Bearer <access_token>。密码使用带随机盐的 scrypt 摘要保存;会话令牌只在登录响应中返回明文,数据库只保存 SHA-256 摘要。连续登录失败次数、临时锁定时间和会话有效期可以通过 .env 中的 AUTH_* 配置调整。
当前注册仅创建本地账号,campus_verified 默认为 false;校园统一身份供应商尚未确定,系统不会把本地注册误写为已完成校园认证。
app/api/v1/:版本化接口路由app/core/:配置、安全和通用基础设施app/models/:数据库模型app/schemas/:请求与响应数据结构app/repositories/:数据访问app/services/:业务编排alembic/:数据库迁移tests/:后端测试
当前匹配与校准规则位于 Service 和 Repository 分层中;app/integrations/
包含可选图文模型适配器,任务队列仍未接入。
2026-10-07 增加可选 OpenAI 兼容图文匹配适配器,可通过 MATCHING_AI_*
配置接入 DeepSeek 等支持图片输入的模型。默认关闭,配置方式、降级及第一版限制见
图文匹配接入说明。真实供应商联调仍待配置密钥后验证。
- 校园统一身份验证、密码重置、物品删除和完整认领核验
- 对象存储、异步匹配、站外通知和其他外部集成