WorkBuddy
2766e53fe2
新增 docs/幂等键检修报告-2026-09-18.md：记录双向断裂（后端零处读取该头、
前端 Date.now 每次生成新键）、五处审计发现、机制设计与五个取舍
（先占位后执行 / 重放 / 失败释放占位 / 孤儿占位接管 / 作用域含 actor_id）、
列类型不变量扫描、E2E 与守门证据、三处同形状问题的连带修复。
同轮勘误：
- docs/HTTP语义检修报告-2026-09-18.md：其中「Idempotency-Key 已支持」一句
在写下时不成立（后端当时零处读取），已显式标注勘误并保留原文，
以免「结论先于核实」被当作既成事实继续引用。
- docs/api/API_INVENTORY.md：原记载 POST /activities/{id}/interests
「提交活动互选」，后端从未实现（Phase 16 已并入 /feedback 的
interestTargetUserIds），按真实端点重列并附勘误说明。
docs/STATUS.md：迁移范围更新为 V001~V046；回归行更新为 669 / 0 / 0 / 3；
新增「幂等键检修」章节；补登 HTTP 语义检修章节在两份文档中的缺失条目。
docs/JIRA_BACKLOG.md：补登 HTTP 语义检修与幂等键检修两行
（此前均未登记）。
225 lines
9.0 KiB
Markdown
225 lines
9.0 KiB
Markdown
# API 接口清单
|
||
|
||
## 用户端 /api/v1/
|
||
|
||
> ✅ **已收敛（2026-09-16）：后端补齐 `/me/*` 命名空间**
|
||
>
|
||
> 小程序 `services/*.js` 按 `REST API 接口详细设计规范.md`（§16 / §22-§40 / §80 / §83-§84）
|
||
> 统一调用 `/me/*`，但后端此前**没有 `/me` 基路径**，个人资料、照片、择偶条件、隐私设置、
|
||
> 关系状态、我的举报/申诉等约 17 个调用全部 404。
|
||
>
|
||
> 现由 `MeController`（`backend/src/main/java/com/danyang/match/platform/me/controller/MeController.java`）
|
||
> 把既有 service 能力暴露到规范路径（纯委托，不复制业务规则），本清单的 `/me/*` 路径现已可用。
|
||
> 旧路径（`/profile/me`、`/profile/preferences`、`/profile/privacy`、`/photos`、
|
||
> `/relationship/*`、`/account/privacy-settings`、`/risk/reports/my`、`/appeals/my`）**全部保留**，
|
||
> 管理端与既有测试不受影响。
|
||
> 小程序历史上自行发明的三条路径（`/me/privacy-settings`、`/me/photos/{id}/main`、`/me/appeals`）
|
||
> 也一并提供，使前端零改动可用。
|
||
> 路由由 `backend/.../contract/MeRouteContractTest.java` 锁定。
|
||
>
|
||
> 关系 / 匹配 / 缘分 三个域已于 2026-09-15 按「采用 2026-09-14 最新路径」的裁决收敛完成（见下方「关系」「我的缘分」「匹配」）。
|
||
|
||
### 认证
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| POST | /auth/wechat/login | 微信登录 |
|
||
| POST | /auth/phone/bind | 绑定手机号 |
|
||
| POST | /auth/refresh | 刷新 Token |
|
||
| POST | /auth/logout | 登出 |
|
||
| GET | /me/status | 获取当前用户状态 |
|
||
|
||
### 用户资料
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /me/profile | 获取本人资料 |
|
||
| PUT | /me/profile | 更新本人资料 |
|
||
| PATCH | /me/profile/basic | 更新基础资料（分节写） |
|
||
| GET | /me/profile/completion | 获取资料完整度 |
|
||
| GET | /me/preferences | 获取择偶条件 |
|
||
| PUT | /me/preferences | 更新择偶条件 |
|
||
| GET | /me/photos | 获取照片列表 |
|
||
| POST | /me/photos/upload-token | 获取上传凭证 |
|
||
| DELETE | /me/photos/{photoId} | 删除照片 |
|
||
| PUT | /me/photos/{photoId}/main | 设为主头像（小程序约定，规范未定义此路径） |
|
||
| GET | /me/privacy | 获取隐私设置（规范路径） |
|
||
| PATCH | /me/privacy | 更新隐私设置（规范路径） |
|
||
| GET | /me/privacy-settings | 获取隐私设置（小程序写法，兼容保留） |
|
||
| PUT | /me/privacy-settings | 更新隐私设置（小程序写法，兼容保留） |
|
||
| GET | /me/profile/review-status | 获取审核状态（别名 `/me/review-status`） |
|
||
| POST | /me/profile/submit-review | 提交资料审核 |
|
||
| GET | /me/relationship-status | 获取婚恋关系状态（返回 `status`，非 `relationshipStatus`） |
|
||
| PATCH | /me/relationship-status | 更新婚恋关系状态（`{status: paused\|searching\|getting_to_know}`） |
|
||
| GET | /me/reports | 我的举报列表 |
|
||
| GET | /me/appeals | 我的申诉列表（规范只定义 `POST /appeals`） |
|
||
|
||
### 实名认证
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| POST | /verification/submit | 提交实名认证 |
|
||
| GET | /verification/status | 查询认证状态 |
|
||
|
||
### 推荐
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /recommendations | 获取今日推荐 |
|
||
| GET | /recommendations/{id} | 获取推荐详情 |
|
||
|
||
### 搜索
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /discover | 搜索用户 |
|
||
| GET | /users/{id} | 查看用户详情 |
|
||
|
||
### 关系（Like / Pass / Block）
|
||
> 基线：2026-09-14 canonical 路径。旧的 `/relations/{userId}/like|pass|block` 已废止。
|
||
> 列表接口统一返回 `{ items, nextCursor }`。
|
||
|
||
| Method | Path | 描述 | 请求体 |
|
||
|---|---|---|---|
|
||
| POST | /likes | 表达喜欢 | `{ targetUserId }` |
|
||
| DELETE | /likes/{targetUserId} | 取消喜欢（已 Mutual 需先 Unmatch） | — |
|
||
| POST | /passes | 表示不合适（单向保密，不通知对方） | `{ targetUserId }` |
|
||
| POST | /blocks | 拉黑用户（Block 优先级最高） | `{ targetUserId }` |
|
||
| DELETE | /blocks/{targetUserId} | 解除拉黑 | — |
|
||
| GET | /blocks | 我的黑名单列表（黑名单页） | — |
|
||
|
||
`POST /likes` 响应：`{ relationStatus, mutualMatch, matchedConversationId, matchId }`
|
||
（对齐 `miniapp/types/index.d.ts#LikeResult`；Mutual 时 `matchedConversationId` 可直接用于跳转聊天）
|
||
|
||
### 我的缘分（只读）
|
||
> `FateItemDTO` 字段：userId / displayName / age / heightCm / regionName / educationCode /
|
||
> occupationCode / maritalStatus / photos / verified / reviewed / relationType / relationTime
|
||
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /relations/fate/mutual | 互相喜欢 |
|
||
| GET | /relations/fate/liked | 我喜欢的 |
|
||
| GET | /relations/fate/likers | 喜欢我的（仅脱敏字段，不泄露明示身份） |
|
||
|
||
### 匹配
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /matches | 获取我的匹配列表 |
|
||
| GET | /matches/{id} | 匹配详情 |
|
||
| POST | /matches/{id}/unmatch | 解除匹配 |
|
||
| POST | /matches/{id}/success/request | 发起成功牵手请求 |
|
||
| POST | /matches/{id}/success/confirm | 确认成功牵手（双确认第二步） |
|
||
| POST | /matches/{id}/success/decline | 拒绝成功牵手 |
|
||
|
||
### 关系状态
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| PUT | /me/relationship/pause | 暂停寻找 |
|
||
| PUT | /me/relationship/resume | 恢复寻找 |
|
||
| PUT | /me/relationship/getting-to-know | 设置为正在了解 |
|
||
|
||
### 聊天
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /conversations | 获取会话列表 |
|
||
| GET | /conversations/{id} | 获取会话详情 |
|
||
| POST | /conversations/{id}/messages | 发送消息 |
|
||
| GET | /conversations/{id}/messages | 获取消息历史 |
|
||
| GET | /conversations/{id}/unread | 获取未读数 |
|
||
|
||
### 通知
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /notifications | 获取通知列表 |
|
||
| PUT | /notifications/{id}/read | 标记已读 |
|
||
| PUT | /notifications/read-all | 全部已读 |
|
||
| GET | /notifications/unread-count | 未读数 |
|
||
|
||
### 活动
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /activities | 活动列表 |
|
||
| GET | /activities/{id} | 活动详情 |
|
||
| POST | /activities/{id}/register | 报名活动 |
|
||
| GET | /my-activities | 我的活动 |
|
||
| POST | /activities/{id}/feedback | 提交活动反馈（含 `interestTargetUserIds`：表达互选意向） |
|
||
| POST | /activities/{id}/interests/confirm | 双方确认开启沟通（Phase 16） |
|
||
| GET | /activities/{id}/interests/mutual | 查看已双向匹配的人（单向意向保密） |
|
||
|
||
> **勘误（2026-09-18 幂等键检修）**：本表原有 `POST /activities/{id}/interests`「提交活动互选」，
|
||
> **后端从未实现该端点**（Phase 16 把表达意向合并进 `POST /activities/{id}/feedback` 的
|
||
> `interestTargetUserIds`，确认环节走 `/interests/confirm`）。前端 `activityService.submitInterests`
|
||
> 按旧设计实现并调用它，必然 404；全仓确认无页面调用方，已随本轮一并删除。上表按真实端点更正。
|
||
|
||
### 红娘
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| POST | /matchmaker/services | 申请红娘服务 |
|
||
| GET | /matchmaker/services | 我的服务列表 |
|
||
| GET | /matchmaker/services/{id} | 服务详情 |
|
||
| GET | /matchmaker/recommendations | 红娘推荐列表 |
|
||
|
||
### 举报
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| POST | /reports | 提交举报 |
|
||
| GET | /my-reports | 我的举报 |
|
||
|
||
---
|
||
|
||
## 后台 /api/v1/operator/
|
||
|
||
### 审核
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /reviews/pending | 待审核列表 |
|
||
| POST | /reviews/{id}/claim | 领取审核任务 |
|
||
| POST | /reviews/{id}/approve | 审核通过 |
|
||
| POST | /reviews/{id}/need-edit | 需修改 |
|
||
| POST | /reviews/{id}/reject | 拒绝 |
|
||
|
||
### 用户管理
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /users | 用户列表 |
|
||
| GET | /users/{id} | 用户详情 |
|
||
| GET | /users/{id}/sensitive-identity | 查看敏感身份（需权限）|
|
||
| PUT | /users/{id}/status | 修改用户状态 |
|
||
|
||
### 活动管理
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /activities | 活动列表 |
|
||
| POST | /activities | 创建活动 |
|
||
| PUT | /activities/{id} | 更新活动 |
|
||
| DELETE | /activities/{id} | 取消活动 |
|
||
| GET | /activities/{id}/registrations | 报名列表 |
|
||
| POST | /activities/{id}/registrations/{rid}/review | 审核报名 |
|
||
|
||
### 红娘管理
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /matchmaker/services | 服务列表 |
|
||
| POST | /matchmaker/services/{id}/assign | 分配红娘 |
|
||
| GET | /matchmaker/services/{id} | 服务详情 |
|
||
|
||
### 举报管理
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /reports | 举报列表 |
|
||
| GET | /reports/{id} | 举报详情 |
|
||
| POST | /reports/{id}/process | 处理举报 |
|
||
|
||
### 权限管理
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /operators | 操作员列表 |
|
||
| POST | /operators | 创建操作员 |
|
||
| PUT | /operators/{id} | 更新操作员 |
|
||
| GET | /roles | 角色列表 |
|
||
| POST | /roles | 创建角色 |
|
||
| GET | /permissions | 权限列表 |
|
||
|
||
### 统计
|
||
| Method | Path | 描述 |
|
||
|---|---|---|
|
||
| GET | /analytics/dashboard | 工作台数据 |
|
||
| GET | /analytics/users | 用户统计 |
|
||
| GET | /analytics/matches | 匹配统计 |
|
||
| GET | /analytics/activities | 活动统计 |
|