# 失物招领（门户）API 文档（超细化版）

更新时间：2025-11-07

## 概览
- 业务说明：用户在门户端自助发布、编辑、删除自己的失物/招领信息；浏览页仅展示“已发布”，默认隐藏“已解决”。“我的列表”用于查看与管理个人发布，编辑后进入“待审”。
- 角色与权限：登录（`isAuthenticated()`）。写操作均在服务层校验“仅作者可操作”。
- 依赖表：`tb_lost_item`、`tb_lost_item_image`
- baseURL：`http://localhost:8080`
- 认证：`Authorization: Bearer <token>`

## 数据模型与规则
- LostItem
  - `id` bigint 主键
  - `type` string 取值：`lost`（丢失启事）| `found`（招领启事）
  - `title` string 标题（2~100 字）
  - `content` string 正文（≥5 字）
  - `contactInfo` string 联系方式（≤50 字，可选）
  - `location` string 发生地点（可选）；`lostTime` datetime 发生时间（可选）
  - `status` int 0草稿 1待审 2已发 3驳回 4下架
  - `solvedFlag` int 0/1 是否已解决
  - `publishTime` datetime 首次发布/上架时间（仅在发布后存在）
  - 审计：`create_by/create_time/update_by/update_time/del_flag`
- LostItemImage（仅详情返回并在新增/编辑时提交）
  - `url` string 图片 URL（建议通过上传网关获取）
  - `sortNo` int 排序（从 0 递增；缺省时按提交顺序）
- 约束与说明
  - 门户新增/编辑：图片最多 9 张；仅图片类型，大小 ≤2MB；上传走 `scene=lostfound.image`
  - 编辑行为会将 `status` 重置为 1（待审）；作者不可编辑“已解决”记录
  - 详情：非“已发(2)”仅作者可见

## 分页/过滤/排序
- 列表默认：仅 `status in (2)`；若未传 `solvedFlag`，服务默认补 `solvedFlag=0`
- 通用分页：`pageNum/pageSize`（默认 1/10）
- 过滤字段：
  - `keyword`（匹配 title/content/contactInfo）
  - `type` `lost|found`
  - `solvedFlag` 0/1
  - `location`（模糊）、`beginTime`、`endTime`（发生时间范围）
- 排序：默认 `publish_time desc, id desc`；遵循 RuoYi 的 `orderByColumn/isAsc` 扩展（如已启用）

## 接口定义

### 列表（公开资源）
- 方法：GET | 路径：/portal/lostfound/list | 权限：登录
- 示例：`GET /portal/lostfound/list?pageNum=1&pageSize=10&keyword=书包`
- 返回：RuoYi 分页（`rows/total`）

### 详情（公开资源）
- 方法：GET | 路径：/portal/lostfound/{id} | 权限：登录
- 说明：若记录非“已发(2)”，仅作者本人可见（用于“我的列表→编辑”）。
- 返回示例：
```json
{
  "code": 200,
  "data": {
    "item": { "id": 1001, "title": "校园卡丢失", "status": 2, "solvedFlag": 0 },
    "images": [ { "id": 11, "url": "https://.../1.png" } ]
  }
}
```

### 新增（进入待审）
- 方法：POST | 路径：/portal/lostfound | 权限：登录
- 校验：`title(2~100)`、`content(≥5)`、`contactInfo(≤50)`、`images(≤9)`
- 请求体示例：
```json
{
  "type": "lost",
  "title": "钱包丢失",
  "content": "黑色钱包，内有校园卡",
  "contactInfo": "手机: 138****8888",
  "images": [ { "url": "https://.../p1.png" } ]
}
```
- 返回：`{ "code":200, "data": { "id": 1003 } }`

### 编辑（仅作者；编辑后回待审）
- 方法：PUT | 路径：/portal/lostfound/{id} | 权限：登录
- 规则：仅作者；若 `solvedFlag==1` 不可编辑；提交后 `status=1(待审)`。

### 删除（仅作者；软删）
- 方法：DELETE | 路径：/portal/lostfound/{id} | 权限：登录
- 说明：软删后门户与管理列表均不可见。

### 标记已解决（仅作者且已发布）
- 方法：PUT | 路径：/portal/lostfound/{id}/solve | 权限：登录
- 规则：仅当 `status=2(已发)` 才能设置；再次调用可视实现为幂等或提示冲突（后端返回 409 时包含明确 msg）。

### 我的列表（全状态）
- 方法：GET | 路径：/portal/lostfound/my/list | 权限：登录
- 说明：返回本人发布的全状态记录（含草稿/待审/驳回/下架）。

## 上传与图片规范
- 上传网关：`POST /portal/upload/oss`
  - 场景：`scene=lostfound.image`
  - 类型：`jpg/jpeg/png/webp`；大小 ≤2MB；返回 `data.url`
  - 目录策略：未传 `scene` 时仍按兼容策略走 `lostfound` 目录与图片校验

## 错误码与提示（与后端实现对齐）
- 401 未授权：未携带/过期 token
- 403 越权：非作者进行写操作
- 404 不存在：记录不存在或被删除
- 409 冲突：状态不允许当前操作（如“已解决不可编辑”、“仅已发可标记解决”）
- 500 业务失败：参数校验失败等（返回明确 msg）

## Apifox 导入建议
- 分组：失物招领-门户；环境 `local`；变量：`Authorization`
- 用例建议：
  1) 上传图片 → 取 `data.url`
  2) 新增 → 提取 `id` → 详情应返回 images
  3) 编辑（补图）→ 状态应变为待审（1）
  4) 管理端审核通过后 → 列表可见且支持 solve 操作