# Apifox 指南｜失物招领（已拆分）

> 提示：本指南为合并版，现已拆分为：
> - 门户端：docs/apifox/失物招领-门户.md
> - 管理端：docs/apifox/失物招领-管理.md

- 环境：baseURL = `http://localhost:8080`
- 认证头：`Authorization: Bearer {{token}}`
- 建议在 Apifox 创建以下环境变量：
  - `{{baseURL}}` = http://localhost:8080
  - `{{token_user}}`（门户用户登录获得）
  - `{{token_admin}}`（管理员登录获得）
  - `{{itemId}}`（测试过程中赋值）

## 准备工作
- 数据库：已执行 book-mis.sql 中“失物招领”两表 DDL。
- 菜单与权限：按照 docs/ruoyi-opt/失物招领-菜单与权限.md 配置
  - 管理端按钮：`manage:lostfound:list/get/add/edit/remove/offline/restore`、`manage:lostfound:audit:list/audit:approve/audit:reject`、`manage:lostfound:solve`
  - 可选：`manage:upload:oss`（用于图片上传）

## 步骤 0：登录并设置变量
- 用户登录
```
POST /login
Body: {"username":"user","password":"user123"}
```
断言：code==200；提取 `data.token` → 变量 `token_user`

- 管理员登录
```
POST /login
Body: {"username":"admin","password":"admin123"}
```
断言：code==200；提取 `data.token` → 变量 `token_admin`

## 门户测试用例

### A1. 新增（进入待审）
```
POST /portal/lostfound
Headers: Authorization: Bearer {{token_user}}
Body(JSON): {
  "type":"lost",
  "title":"丢钥匙",
  "content":"教学楼附近丢失一串钥匙",
  "contactInfo":"188****0001",
  "location":"教学楼A座",
  "lostTime":"2025-11-05 18:30:00",
  "images":[{"url":"https://example.com/img1.jpg","sortNo":0}]
}
```
断言：code==200；提取 `data.id` → 变量 `itemId`

说明：如需上传图片获取 URL，可先用 `POST /manage/upload/oss`（需 manage:upload:oss）上传，取返回 `url`。

### A2. 我的发布列表
```
GET /portal/lostfound/my/list?pageNum=1&pageSize=10
Headers: Authorization: Bearer {{token_user}}
```
断言：code==200；`data.rows` 包含 `id == {{itemId}}`

### A3. 详情（待审时仅作者可看）
```
GET /portal/lostfound/{{itemId}}
Headers: Authorization: Bearer {{token_user}}
```
断言：code==200；`data.item.title == "丢钥匙"`；`data.images` 为数组

## 管理端测试用例（审核/发布/下架/回收）

### B1. 待审核列表
```
GET /manage/lostfound/audit/list?pageNum=1&pageSize=10
Headers: Authorization: Bearer {{token_admin}}
```
断言：code==200；列表包含 `id == {{itemId}}`

### B2. 审核通过（发布）
```
PUT /manage/lostfound/{{itemId}}/approve
Headers: Authorization: Bearer {{token_admin}}
```
断言：code==200

### B3. 已发布列表（前台可见）
```
GET /portal/lostfound/list?pageNum=1&pageSize=10
Headers: Authorization: Bearer {{token_user}}
```
断言：code==200；列表包含 `id == {{itemId}}`

### B4. 管理端设置“已解决/未解决”
```
PUT /manage/lostfound/{{itemId}}/solve
Headers: Authorization: Bearer {{token_admin}}
Body: {"solved": true}
```
断言：code==200；再次查询 `GET /manage/lostfound/list`，该记录 `solvedFlag == 1`

（可选）恢复为未解决：Body 改为 `{ "solved": false }`

### B5. 下架（必填原因）
```
PUT /manage/lostfound/{{itemId}}/offline
Headers: Authorization: Bearer {{token_admin}}
Body: {"reason":"违规内容或已解决归档"}
```
断言：code==200；`GET /manage/lostfound/recycle/list` 能检索到该记录，且 `status==4`，`offlineReason` 非空

### B6. 回收站恢复为待审
```
PUT /manage/lostfound/{{itemId}}/restore
Headers: Authorization: Bearer {{token_admin}}
```
断言：code==200；`GET /manage/lostfound/audit/list` 能检索到该记录，`status==1`

### B7. 审核驳回（必填原因）
```
PUT /manage/lostfound/{{itemId}}/reject
Headers: Authorization: Bearer {{token_admin}}
Body: {"reason":"信息不完整"}
```
断言：code==200；`GET /manage/lostfound/recycle/list` 检索到，`status==3`，`rejectReason` 非空

### B8. 回收站删除
```
DELETE /manage/lostfound/{{itemId}}
Headers: Authorization: Bearer {{token_admin}}
```
断言：code==200；再次在回收站/任何列表检索不到

## 门户端编辑与解决

### C1. 编辑（未解决可编辑；提交后回到待审）
```
PUT /portal/lostfound/{{itemId}}
Headers: Authorization: Bearer {{token_user}}
Body: {"title":"丢钥匙-补充描述","images":[]}
```
断言：code==200；`GET /manage/lostfound/audit/list` 可见
注意：若该条目已解决，接口将返回错误（文案：已解决的条目不可编辑）。

### C2. 作者标记已解决
```
PUT /portal/lostfound/{{itemId}}/solve
Headers: Authorization: Bearer {{token_user}}
```
断言：code==200；`GET /portal/lostfound/list` 默认不显示；加 `solvedFlag=1` 可筛选显示

## 详情返回结构示例
```
GET /portal/lostfound/{id}
响应：
{
  "code":200,
  "data":{
    "item":{
      "id":123,
      "type":"lost",
      "title":"丢钥匙",
      "content":"...",
      "contactInfo":"188****0001",
      "location":"教学楼A座",
      "lostTime":"2025-11-05 18:30:00",
      "status":2,
      "solvedFlag":0,
      "publishTime":"2025-11-06 10:00:00"
    },
    "images":[{"id":1,"url":"https://...","sortNo":0}]
  }
}
```

## 常见失败与定位
- 409 冲突：
  - 非待审执行审核 approve/reject
  - 非已发布执行下架/设置已解决
  - 非作者或状态不允许的“标记已解决”（门户）
- 400 参数错误：
  - 图片数量>9；标题<2字或正文<5字；contactInfo>50字
- 403 权限不足：
  - 管理端按钮权限未勾选或 v-hasPermi 与后端不一致
- 401 未登录/过期：
  - token 为空或过期（Apifox 建议全局 Header 使用 `Authorization: Bearer {{token_*}}`）

## Apifox 组织建议
- 目录结构：
  - 门户（Portal）
    - list、get、add、update、remove、solve、my/list
  - 管理（Manage）
    - list（已发布）、audit/list、recycle/list、get、approve、reject、offline、restore、remove、solve
  - 通用：manage/upload/oss（可选）
- 环境变量：`baseURL`、`token_user`、`token_admin`、`itemId`