# Postman / Apifox 导入与测试

## 导入接口

1. 打开 Postman，点击左上角 **Import**。
2. 选择 **Files**，导入 `docs/openapi-0.6.12.json`。
3. 选择以 **Postman Collection** 方式导入并确认。
4. 在 Collection Variables 中将 `baseUrl` 设置为当前部署地址；本地开发使用 `http://127.0.0.1:8001`。

`super_like` 和新的位置请求已随 API 0.6.6 发布到正式环境，可以使用正式地址测试。

API 0.6.7 的帖子新字段已经完成正式数据库迁移和部署，可以在正式地址测试。

API 0.6.8 的 `GET /api/v1/users/{user_id}` 会在公开资料中返回 `interests` 和最近 20 条 `posts`；邮箱/手机号、喜欢列表和匹配记录不会返回。

API 0.6.8 的 `/api/v1/users/me/liked` 和 `/api/v1/users/me/likes` 不再分页，直接返回完整有效名单；旧请求中携带的 `limit`、`offset` 会被忽略。Apifox 更新接口定义时应删除这两个参数。API 0.6.8 已发布到正式环境。

本版 `GET /api/v1/auth/me` 和 `GET /api/v1/users/me` 还新增 `liked_users_count`、`liked_by_users_count`、`matches_count` 三个总数字段。它们不受响应中三个名单最多 20 条的限制，正式环境已经可用。

## API 0.6.12 本次更新（已发布）

正式环境已经执行 `sql/migrate_profile_details.sql`（`user_profiles` 增加 8 个可空资料字段）和 `sql/migrate_comment_interactions.sql`（`post_comments` 增加 `parent_comment_id`、新增 `comment_likes` 表），并完成 0.6.12 部署。两个脚本保留为幂等迁移，供新环境初始化使用。

导入 `docs/openapi-0.6.12.json` 后，核对以下变化：

- `PATCH /api/v1/users/me` 新增 `occupation`、`education`、`height_cm`（100-250）、`beliefs`、`smoking`、`drinking`、`pets`、`exercise`。
- `GET /api/v1/auth/me` 和 `GET /api/v1/users/me` 的 `profile` 会返回这 8 个字段，并新增根据 `birth_date` 计算的 `age`。
- `GET /api/v1/users/me/liked` 和 `/api/v1/users/me/likes` 会排除已经匹配成功的用户，`liked_users_count` / `liked_by_users_count` 同步扣除。
- 评论接口新增回复：`POST /api/v1/explore/posts/{post_id}/comments` 可带 `parent_comment_id`；CommentResponse 新增 `parent_comment_id`、`reply_count`、`like_count`、`liked_by_me`。
- 新增 `POST/DELETE /api/v1/explore/comments/{comment_id}/like` 点赞和取消点赞评论。
- 旧字段保持不变；此前 0.6.10/0.6.11 的编辑、混合媒体和匹配列表改动保持不变。

共享 Google 文档的完整可粘贴内容见 `docs/Google文档完整内容-0.6.12.txt`；本次没有直接编辑在线文档。

## 测试注册

打开 `POST /api/v1/auth/register`，Body 选择 `raw` 和 `JSON`：

```json
{
  "email_or_phone": "user@example.com",
  "password": "password123",
  "confirm_password": "password123",
  "relationship_goal": "serious_relationship",
  "full_name": "Test User",
  "city": "Shanghai",
  "country": "China"
}
```

也可以用同一个字段填写手机号：

```json
{
  "email_or_phone": "13800138000",
  "password": "password123",
  "confirm_password": "password123",
  "relationship_goal": "new_friends"
}
```

成功状态码是 `201`，响应只包含 `access_token`、`refresh_token` 和 `token_type`。两次密码必须一致，`confirm_password` 不会保存到数据库。`relationship_goal` 必须从 `serious_relationship`、`casual_dates`、`new_friends`、`marriage` 中单选一个。MVP 不需要请求或填写验证码。

注册介绍内容为文字简介或介绍视频二选一。选择文字时在注册 JSON 中提交非空 `bio`，此时调用 `GET /api/v1/auth/me` 会看到 `profile.video_url: null`。选择视频时省略 `bio`，注册成功后用 access token 调用视频上传接口；上传后再次获取个人资料，`profile.bio` 为 `null`，生产环境的 `profile.video_url` 为一小时有效的完整 OSS 签名 URL。`profile.profile_image_url` 采用相同规则。前端可以直接加载这些 URL，不需要再次携带 Bearer Token；过期后重新请求资料即可。以后提交非空 `bio` 会删除介绍视频，重新上传视频会清空 `bio`。

## 测试登录

打开 `POST /api/v1/auth/login`：

```json
{
  "email_or_phone": "user@example.com",
  "password": "password123"
}
```

成功状态码是 `200`。

## 测试需要登录的接口

1. 从注册或登录响应中复制 `access_token`。
2. 打开需要登录的请求，在 **Authorization** 中选择 **Bearer Token**。
3. 把 `access_token` 粘贴到 Token 输入框，然后发送请求。

旧版的 `/api/v1/auth/request-code` 和 `/api/v1/auth/verify` 已移除，不要再测试这两个接口。

## Apifox 更新及图片/视频上传

Apifox 项目如果注册请求没有必填的 `relationship_goal`，滑动请求不接受 `super_like`，位置请求没有 `city`、`county`，帖子请求没有 `content_format`、`feeling`、`location`，或者公开用户资料没有 `interests`、`posts`，说明接口定义早于 0.6.8 版本。先备份项目中的手工编辑内容，再将 `docs/openapi-0.6.12.json` 作为 OpenAPI 导入并核对差异；不要仅凭旧接口列表测试。正式 Base URL 使用 `https://melove.youthome.com.cn`，请求路径已经包含 `/api/v1`，不要在 Base URL 再重复拼接此前缀。线上 `/health` 和 `/docs` 目前不由 nginx 代理，不能用它们判断业务接口是否可用。

导入 `docs/openapi-0.6.12.json` 后，核对创建帖子请求中的 `content_format`、`feeling`、`location`，以及公开用户资料响应中的 `interests`、`posts` 和公开用户帖子响应中的同名字段。

注册返回 `201` 后，复制响应的 `access_token`（不是 `refresh_token`）；上传接口在 Auth 中选择 Bearer Token。Body 选择 `form-data`，字段类型选择 **File**，并选择真实文件。不要用 JSON、raw、Binary 或文本形式的文件路径发送，也不要手动设置 `Content-Type: application/json` 或固定 multipart boundary；由 Apifox 自动生成 `multipart/form-data; boundary=...`。

| 接口 | form-data 文件字段 | 支持类型 | 单文件上限 |
| --- | --- | --- | --- |
| `POST /api/v1/users/me/image` | `image` | JPEG、PNG、WebP | 10 MB |
| `POST /api/v1/users/me/video` | `video` | MP4、MOV、WebM | 100 MB |
| `POST /api/v1/users/me/identity` | `document` | JPEG、PNG、PDF | 10 MB |

头像和视频成功时返回 `200`，响应含 `id`、`media_type`、`review_status`。`401` 表示缺失/过期的 access token；`422` 常见于文件字段名不对或没有实际选择文件；`415` 表示文件 MIME 类型不支持；`413` 表示文件过大；`503` 表示后端存储服务故障。若出现 `413` 且没有后端 JSON 响应，还应检查 nginx 的请求体大小限制。排查时请提供状态码和响应正文，勿发送 token 或个人文件。

同一用户再次上传头像或介绍视频时，后端会自动替换对应的旧记录和旧文件，每种只保留最新一份；前端不需要先删除，也不需要再次提交注册资料。若新文件存储失败，旧头像或旧视频保持不变。身份证/护照上传仍按原逻辑保存，不受此替换规则影响。

## 测试兴趣

需要登录的情况下，打开 `PUT /api/v1/users/me/interests`，Body 选择 `raw` 和 `JSON`：

```json
{
  "interests": [
    "Photography",
    "Dogs",
    "Travel",
    "我的自定义兴趣"
  ]
}
```

兴趣至少提交 2 个，但没有最多 4 个的限制。`Other` 不需要特殊接口，直接把用户输入的内容作为数组中的一项提交即可。查询使用 `GET /api/v1/users/me/interests`。

## 测试推荐和国家搜索

注册多个具有 `city`、`country` 和 `interests` 的用户后，使用：

```text
GET /api/v1/meet?limit=20
GET /api/v1/search?city=Shanghai&country=China&limit=20
```

响应中的公开用户包含 `country` 和 `compatibility_percentage`。有效的 Super Like 用户最优先；其余按同城、同国家、其他国家排序，同一组内匹配度高的用户优先。

## 测试超级喜欢与取消

使用账号 A 的 Bearer token 发送：

```text
POST /api/v1/meet/swipes
```

```json
{"target_user_id": 2, "direction": "super_like"}
```

账号 B 尚未滑过账号 A 时，使用账号 B 的 token 调用 `GET /api/v1/meet?limit=20`，账号 A 应排在最前面。账号 B 对 A 使用 `like` 或 `super_like` 时会形成匹配。取消键用账号 A 的 token 发送 `DELETE /api/v1/meet/swipes/{账号B的用户ID}`，响应中的 `previous_direction` 为 `super_like`；随后账号 A 在账号 B 的 Meet 中不再享有优先级，已形成的匹配会解除。`pass` 和 `like` 也使用同一个 DELETE 接口撤销。

## 测试定位更新

使用 Bearer token 发送 `PUT /api/v1/users/me/location`，Body 选择 raw JSON：

```json
{"latitude": 31.2304, "longitude": 121.4737, "city": "上海市", "county": "黄浦区"}
```

成功返回 `200`，响应包含这四个字段和 `updated_at`。再调用 `GET /api/v1/auth/me`，确认 `profile.city`、`profile.county` 已更新；`profile.country` 是国家，不会被区县覆盖。缺少城市或区县、提交空白名称或非法坐标返回 `422`。

## 测试创建帖子、探索列表和公开用户帖子

用作者的 Bearer token 调用 `POST /api/v1/explore/posts`，发送 JSON：

```json
{
  "content": "Feeling **happy** and *relaxed* today",
  "post_type": "text",
  "content_format": "markdown",
  "feeling": "happy",
  "location": {"name": "Blue Bottle Coffee, Soho NYC", "latitude": 40.723, "longitude": -73.998}
}
```

成功返回 `201` 和帖子 `id`。`feeling` 为可选的 1-50 字符标签，`location.name` 为选定的地点，坐标可同时省略；文字帖至少要有文字、心情或地点之一。粗体/斜体用 Markdown `**bold**`、`*italic*` 表示，设置 `content_format: "markdown"`；旧客户端不提交该字段时仍为 `plain`。后端返回原始 Markdown，不返回 HTML。音乐字段暂不支持。

图片/视频帖先把 `post_type` 设为 `image` 或 `video` 创建帖子，记下返回的 `id`，然后调用 `POST /api/v1/explore/posts/{post_id}/media`。Body 选 `form-data`，文件字段必须叫 `media`；一条帖子最多 9 张图片或 1 个视频，不能混用。上传成功后再获取帖子列表。

使用另一个账号的 Bearer token 调用 `GET /api/v1/explore/feed?limit=20&offset=0` 和 `GET /api/v1/users/{作者用户ID}/posts?limit=20&offset=0`。两者返回的该帖子都应包含相同的 `content_format`、`feeling`、`location` 和 `media[]`；公开用户资料中的 `media[]` 是头像/介绍视频，与帖子媒体不同。