danyang-match/docs/api/API_INVENTORY.md

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	活动统计