admin/danyang-match
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
3244e02e7e7da5a74b283121eebf2d9427d4a6c4
danyang-match/docs/api/API_INVENTORY.md
T
Codex 3244e02e7e refactor(api): 关系/匹配域采用 2026-09-14 canonical 路径，消除三代并存 
## 问题：同一能力存在三代路径，前端指向的是已废止的一代

按 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 通过
2026-09-15 23:16:27 +08:00

7.1 KiB
Raw Blame History

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 活动统计
Reference in New Issue View Git Blame Copy Permalink