# 失物招领 API 文档（MVP，已拆分）

> 重要说明：本文为早期总览版，现已拆分为两份文档，请优先参考：
> - 门户端：docs/api/失物招领-门户.md
> - 管理端：docs/api/失物招领-管理.md


概览：
- 业务：“丢失/捡到”信息的发布、审核、展示、解决标记。
- 角色：门户用户（登录）、管理员。
- 依赖表：tb_lost_item、tb_lost_item_image。
- 统一响应结构：与 RuoYi 对齐（code/msg/data）。分页沿用 Page（pageNum/pageSize）。

## 门户端（/portal/lostfound）

### 列表
- 方法：GET
- 路径：/portal/lostfound/list
- 请求参数（query）：
  - pageNum, pageSize 必填
  - keyword 可选（匹配标题/内容/联系方式）
  - type 可选（lost/found）
  - solved 可选（0/1，默认 0）
  - beginTime/endTime 可选（发生时间范围）
- 说明：仅返回 status=2（已发布），默认不返回 solved=1。
- 返回示例：
```json
{
  "code":200,
  "data":{"total":2,"rows":[{"id":1,"type":"found","title":"拾到校园卡一张","solvedFlag":"0","publishTime":"2025-11-06 09:00:00"}]}
}
```

### 详情
- 方法：GET
- 路径：/portal/lostfound/{id}
- 返回：主体 + 图片数组 images

### 新增
- 方法：POST
- 路径：/portal/lostfound
- 权限：登录态
- 请求体：
```json
{
  "type":"lost",
  "title":"标题",
  "content":"正文",
  "contactInfo":"电话：188****0001（可选，≤50字）",
  "location":"地点（可选）",
  "lostTime":"2025-11-05 18:30:00",
  "images":[{"url":"https://...","sortNo":0}]
}
```
- 响应：`{ code:200, data:{ id: 123 } }`；新增后进入“待审核”。

### 编辑（仅作者，未解决）
- 方法：PUT
- 路径：/portal/lostfound/{id}
- 行为：更新主体与图片；提交后回到“待审核”。

### 删除（仅作者）
- 方法：DELETE
- 路径：/portal/lostfound/{id}
- 行为：逻辑删除（del_flag=2）。

### 标记已解决（不可回退）
- 方法：PUT
- 路径：/portal/lostfound/{id}/solve
- 行为：solved_flag=1；若已是 1，幂等成功。

### 我的发布
- 方法：GET
- 路径：/portal/lostfound/my/list
- 说明：返回本人发布，支持按 solved/status 过滤。

## 管理端（/manage/lostfound）

### 已发布列表
- 方法：GET
- 路径：/manage/lostfound/list
- 权限：manage:lostfound:list
- 说明：status=2；支持筛选 type/keyword/时间。

### 待审核列表
- 方法：GET
- 路径：/manage/lostfound/audit/list
- 权限：manage:lostfound:audit:list
- 说明：status=1。

### 回收站列表
- 方法：GET
- 路径：/manage/lostfound/recycle/list
- 权限：manage:lostfound:recycle:list
- 说明：status in (3,4)。

### 详情
- 方法：GET
- 路径：/manage/lostfound/{id}
- 权限：manage:lostfound:get

### 新增/编辑（管理端）
- 方法：POST/PUT
- 路径：/manage/lostfound
- 权限：manage:lostfound:add / manage:lostfound:edit

### 审核通过
- 方法：PUT
- 路径：/manage/lostfound/{id}/approve
- 权限：manage:lostfound:audit:approve
- 行为：status: 1->2，写入 publish_time；否则返回 409。

### 审核驳回（必填原因）
- 方法：PUT
- 路径：/manage/lostfound/{id}/reject
- 权限：manage:lostfound:audit:reject
- 请求体：`{ "reason": "..." }`
- 行为：status:1->3，写入 reject_reason；否则 409。

### 下架（必填原因）
- 方法：PUT
- 路径：/manage/lostfound/{id}/offline
- 权限：manage:lostfound:offline
- 请求体：`{ "reason": "..." }`
- 行为：status:2->4，写入 offline_reason；否则 409。

### 恢复为待审（回收站）
- 方法：PUT
- 路径：/manage/lostfound/{id}/restore
- 权限：manage:lostfound:restore
- 行为：status:3/4 -> 1。

### 删除（回收站内）
- 方法：DELETE
- 路径：/manage/lostfound/{ids}
- 权限：manage:lostfound:remove
- 行为：逻辑删除（del_flag=2）。

## 错误码约定
- 400 参数错误（图片数量>9、标题过长等）
- 401 未登录
- 403 权限不足
- 404 资源不存在/无权访问
- 409 状态冲突（非待审不能审核、非已发布不能下架、已解决不可编辑等）

## 示例
### 门户新增
请求：
```http
POST /portal/lostfound
Authorization: Bearer <token>
Content-Type: application/json

{"type":"lost","title":"丢了钥匙","content":"...","images":[]}
```
响应：
```json
{"code":200,"data":{"id":101}}
```