# 失物招领（管理）API 文档（超细化版）

更新时间：2025-11-07

## 概览
- 业务说明：管理端用于对用户发布的失物/招领信息进行全量检索、审核（通过/驳回）、运营（下架/恢复）、状态修正（已解决）、以及必要的增删改。配合门户端实现自助发布与平台治理。
- 角色与权限：全部接口受 `@PreAuthorize("@ss.hasPermi('manage:lostfound:*')")` 控制；不同操作使用细粒度权限点，见“权限矩阵”。
- 依赖表：`tb_lost_item`（主体）、`tb_lost_item_image`（图片）
- 基础信息：
  - baseURL：`http://localhost:8080`
  - 认证：`Authorization: Bearer <token>`（管理员/运营）

## 领域模型与状态流转（严格对齐 SQL）
- 实体主字段（简表）：
  - `id`(bigint) 主键
  - `type`(string) 取值 `lost|found`
  - `title`(string) 2~100 字
  - `content`(text) ≥5 字
  - `contactInfo`(string) ≤50 字
  - `location`(string) 可选
  - `lostTime`(datetime) 可选
  - `status`(int) 0草稿 1待审 2已发 3驳回 4下架
  - `solvedFlag`(int) 0/1 是否已解决
  - 审计：`create_by/create_time/update_by/update_time/del_flag`
## 状态规则（关键约束）
- 审核通过：`1(待審) -> 2(已发)`，写入 `publish_time`
- 审核驳回：`1(待審) -> 3(驳回)`，必填 `reject_reason`
- 下架：`2(已发) -> 4(下架)`，必填 `offline_reason`
- 恢复为待审：`3/4 -> 1`
- 编辑：门户端编辑提交后服务将 `status=1`
- 已解决：
  - 门户：`status=2 且 create_by=本人 且 solved_flag=0` → `solved_flag=1`
  - 管理：`status=2` 下可设置 `solved_flag=0/1`

## 权限矩阵（按钮级）
- 列表：`manage:lostfound:list` / `manage:lostfound:audit:list` / `manage:lostfound:recycle:list`
- 详情：`manage:lostfound:get`
- 新增：`manage:lostfound:add`
- 编辑：`manage:lostfound:edit`
- 审核通过：`manage:lostfound:audit:approve`
- 审核驳回：`manage:lostfound:audit:reject`
- 下架：`manage:lostfound:offline`
- 恢复：`manage:lostfound:restore`
- 设置解决状态：`manage:lostfound:solve`
- 删除：`manage:lostfound:remove`

## 查询/分页/过滤（默认排序）
- 通用分页：`pageNum`（默认1）、`pageSize`（默认10）
- 常用过滤：
  - 关键字：`keyword`（模糊匹配 title/content/contactInfo）
  - 类型：`type=lost|found`
  - 状态：`status`（支持单值）
  - 时间：`beginTime`/`endTime`（发生时间范围）
  - 已解决：`solvedFlag=0|1`
- 排序：默认 `publish_time desc, id desc`；如前端传入 `orderByColumn/isAsc`，将按通用规则应用

## 接口清单与示例

### 列表（已发布）
- 方法：GET
- 路径：/manage/lostfound/list
- 权限：`manage:lostfound:list`
- 请求参数（query，可选）：分页 + 过滤
- 返回示例：
```json
{
  "code": 200,
  "rows": [
    {
      "id": 1001,
      "type": "lost",
      "title": "校园卡丢失",
      "content": "9号楼前遗失，捡到请联系",
      "contactInfo": "微信:foo",
      "location": "9号楼",
      "lostTime": "2025-10-01 10:00:00",
      "status": 2,
      "solvedFlag": 0,
      "createBy": "u01",
      "createTime": "2025-10-01 10:05:00"
    }
  ],
  "total": 1
}
```

### 审核列表（待审）
- 方法：GET | 路径：/manage/lostfound/audit/list | 权限：`manage:lostfound:audit:list`

### 回收列表（驳回/下架）
- 方法：GET | 路径：/manage/lostfound/recycle/list | 权限：`manage:lostfound:recycle:list`

### 详情（含图片聚合）
- 方法：GET
- 路径：/manage/lostfound/{id}
- 权限：`manage:lostfound:get`
- 返回示例：
```json
{
  "code": 200,
  "data": {
    "item": { "id": 1001, "title": "校园卡丢失", "status": 2, "solvedFlag": 0 },
    "images": [ { "id": 11, "url": "https://.../1.png" } ]
  }
}
```

### 新增
- 方法：POST
- 路径：/manage/lostfound
- 权限：`manage:lostfound:add`
- 请求体：
```json
{
  "type": "lost",
  "title": "钥匙丢失",
  "content": "一串黑色钥匙",
  "contactInfo": "电话: 138xxxx",
  "images": [ { "url": "https://.../k1.png" } ]
}
```
- 返回：`{ "code":200, "data": { "id": 1002 } }`

### 编辑
- 方法：PUT
- 路径：/manage/lostfound
- 权限：`manage:lostfound:edit`
- 请求体：包含 `id` 及需修改字段

### 审核通过
- 方法：PUT | 路径：/manage/lostfound/{id}/approve | 权限：`manage:lostfound:audit:approve`
- 规则：仅“待审(1)”可通过，否则返回冲突。

### 审核驳回
- 方法：PUT | 路径：/manage/lostfound/{id}/reject | 权限：`manage:lostfound:audit:reject`
- 请求体：`{ "reason": "图片不清晰" }`（必填）
- 规则：仅“待审(1)”可驳回。

### 下架
- 方法：PUT | 路径：/manage/lostfound/{id}/offline | 权限：`manage:lostfound:offline`
- 请求体：`{ "reason": "违规信息" }`（必填）
- 规则：仅“已发(2)”可下架。

### 恢复为待审
- 方法：PUT | 路径：/manage/lostfound/{id}/restore | 权限：`manage:lostfound:restore`
- 规则：仅“驳回/下架(3/4)”可恢复为“待审(1)”。

### 设置解决状态（运营修正）
- 方法：PUT | 路径：/manage/lostfound/{id}/solve | 权限：`manage:lostfound:solve`
- 请求体：`{ "solved": true }`
- 规则：仅“已发(2)”允许调整 `solvedFlag`。

### 删除（软删）
- 方法：DELETE | 路径：/manage/lostfound/{ids}
- 权限：`manage:lostfound:remove`
- 说明：置 `del_flag=2`，不可见于列表。

## 参数校验与错误码（语义清晰）
- 标题：2~100 字；正文：≥5 字；联系方式 ≤50 字；图片 ≤9 张（门户与管理端一致）。
- 常见错误码：
  - 401 未授权：未携带/过期 token
  - 403 权限不足：缺少对应 `manage:lostfound:*`
  - 404 不存在：记录不存在或已删除
  - 409 状态冲突：违反状态流转规则（如“仅待审可通过/驳回”、“仅已发可下架/设解决状态”）

## 上传与图片规范（管理端）
- 统一上传：`POST /manage/upload/oss`（`manage:upload:oss`）→ 返回 `data.url`
- 备用：`POST /portal/upload/oss`，`scene=lostfound.image`（图片 ≤2MB）

## Apifox 导入建议
- 分组：失物招领-管理；环境 `local`；变量：`Authorization`
- 用例建议：
  1) 待审 → 审核通过 → 已发布列表可见
  2) 已发布 → 下架（必填 reason）→ 回收站 → 恢复为待审
  3) 已发布 → 设置解决状态（true/false）
  - 500 其他业务错误：参数非法、服务异常（返回明确 msg）

## 兼容性与变更
- 与门户端完全分离：门户仅支持作者自主管理，“审核/运营”仅在管理端进行。
- 响应结构遵循 RuoYi 统一格式：`{ code, msg, data | rows, total }`。