Codex
3244e02e7e
## 问题：同一能力存在三代路径，前端指向的是已废止的一代
按 mtime 排查后发现"最新"并非上一轮以为的 /relations/*，而是 2026-09-14 的 match 模块：
| 代际 | 位置 | 日期 | 路径 |
|---|---|---|---|
| canonical | platform.match: Like/Block/MatchController | 09-14 12:13~12:14 | /likes /blocks /matches |
| 二代 | platform.relationship: Relationship(Status)Controller | 09-10 10:59 | /relations/* /relationship/* |
| 一代(规范) | REST API 接口详细设计规范.md | 08-28 | /relationships/*（多一个 hips） |
| 前端 | miniapp/services/matchService.js | 08-29 | 混用二代 + 一代 |
后果：缘分三榜、黑名单页、成功牵手流程全部 404；另有两份重复 success 实现 + 一份桩实现。
## 裁决：采用 2026-09-14 最新路径，前端与二代让位（用户指令）
### 补齐 canonical 模块缺口（此前只有 javadoc 声明或服务方法，无控制器）
- RelationService.unlike() + LikeController `DELETE /likes/{targetUserId}`
- 新增 PassController `POST /passes`（RelationService.pass 在 09-14 模块内却无控制器，补齐与 /likes、/blocks 对称）
- BlockController `GET /blocks`（javadoc 早声明"我的 Block 列表"但未实现，mapper findBlockedByUser 已就绪）
- MatchController `POST /matches/{id}/success/request|confirm|decline`（javadoc 标"Phase 12 预留"），
委派真实实现 RelationshipStatusService；authorizedMatch 对"不存在"与"无权"统一回 404，避免探测他人 Match
- LikeResponse 对齐前端 LikeResult：{ relationStatus, mutualMatch, matchedConversationId, matchId }
Mutual 时调 ChatService.getOrCreateConversation 取会话 id → "双向喜欢→跳聊天"链路真正打通
- LikeController/PassController/BlockController 补 targetUserId 空值校验
### 移除被取代的路由与桩实现
- RelationshipController 移除 like/cancelLike/pass/block/unblock/matches/unmatch/success，仅保留 /fate/*
- RelationshipStatusController 移除 /success/*（已由 /matches/{id}/success/* 取代），保留关系状态生命周期
- RelationshipService 删除 requestSuccess/confirmSuccess 桩 ——
前者自述 "TODO: 查询 relationship_success_requests 表" 却返回硬编码 status="pending"，
等于绕过 AGENTS 硬规则 6「成功牵手必须双确认」
- 注意：RelationshipService.like/block/pass 被 P0FixVerificationTest /
RelationshipBlockPriorityPhase08Test 直接测试，方法体保留
### 列表信封统一
- CursorPage 从 chat.dto 提升到 shared.dto（消除 match 模块反向依赖 chat DTO）
- /relations/fate/mutual|liked|likers 与 GET /matches 改返回 { items, nextCursor }
### 前端对齐
- matchService.js 全部路径改到 canonical；补 declineSuccess
- matchStore 补 _decorateBlockedList，修复"模板渲染 blockedAtText 但全仓从未计算"的缺陷
（与上一轮 lastMessageAtText 同源，同类字段一律在 store 装饰一次）
### 文档
- docs/api/API_INVENTORY.md 关系/缘分/匹配三节重写为 canonical 路径；
顶部加 /me/* 路径族显式警告（小程序按规范写 /me/*，后端实为 /profile/*、/photos、/relationship/*，
约 15 个端点会 404，收敛方向未裁决，防止后续照抄踩坑）
- docs/STATUS.md：Backend 回归债务由「待清（277 tests 4F/8E）」更新为「已清偿（297 tests 全绿）」
## 验证
- 新增 CanonicalRouteContractTest（3 例）：用 RequestMappingHandlerMapping 断言
canonical 路径已注册、被取代的旧路径不再注册、关系状态生命周期保留 —— 路由再漂移即红
- 后端 297 tests, 0 failures, 0 errors, 3 skipped, BUILD SUCCESS
- 小程序 tsc --noEmit 通过
203 lines
7.1 KiB
Markdown
203 lines
7.1 KiB
Markdown
# API 接口清单
|
||
|
||
## 用户端 /api/v1/
|
||
|
||
> ⚠️ **待收敛：`/me/*` 系列**
|
||
>
|
||
> 本清单的 `/me/*` 个人资源路径（用户资料、照片、择偶条件、隐私设置、关系状态、我的活动/举报/申诉等）
|
||
> 与后端**已实现路径不一致**。后端实际前缀为：
|
||
> `/profile/me`、`/profile/preferences`、`/profile/privacy`、`/profile/interests`、
|
||
> `/photos`、`/relationship/status|pause|resume|getting-to-know|exit`、`/appeals`、`/reports`。
|
||
> 小程序 `services/*.js` 当前按本清单的 `/me/*` 编写，调用会 404。
|
||
>
|
||
> 关系 / 匹配 / 缘分 三个域已于 2026-09-15 按「采用 2026-09-14 最新路径」的裁决收敛完成（见下方「关系」「我的缘分」「匹配」）。
|
||
> `/me/*` 系列的收敛方向尚未裁决，**改动前请勿直接照抄本清单中的 `/me/*` 路径**。
|
||
> 路由裁决已被 `backend/.../contract/CanonicalRouteContractTest.java` 锁定。
|
||
|
||
### 认证
|
||
| 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 | 更新本人资料 |
|
||
| GET | /me/preferences | 获取择偶条件 |
|
||
| PUT | /me/preferences | 更新择偶条件 |
|
||
| GET | /me/photos | 获取照片列表 |
|
||
| POST | /me/photos/upload-token | 获取上传凭证 |
|
||
| GET | /me/privacy-settings | 获取隐私设置 |
|
||
| PUT | /me/privacy-settings | 更新隐私设置 |
|
||
| GET | /me/review-status | 获取审核状态 |
|
||
|
||
### 实名认证
|
||
| 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 | 提交活动反馈 |
|
||
| POST | /activities/{id}/interests | 提交活动互选 |
|
||
|
||
### 红娘
|
||
| 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 | 活动统计 |
|