admin/danyang-match
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
c607e87b45db43ed7ea11be6868ca84bdadea0ef
danyang-match/docs/api/API_INVENTORY.md
T
Codex bc4531a734 feat(api): 补齐 /me/* 命名空间，恢复 17 个 404 调用 + 修 /me/status 过期桩 
背景：小程序 services/*.js 按 REST 规范（§16 / §22-§40 / §80 / §83-§84）统一调用
/me/*，但后端从未注册 /me 基路径，个人资料、照片、择偶条件、隐私设置、关系状态、
我的举报/申诉等约 17 个调用全部 404。

后端
- 新增 me/controller/MeController：把既有 service 能力暴露到规范路径（纯委托，不复制
  业务规则，AGENTS.md #26）。旧路径（/profile/*、/photos、/relationship/*、
  /account/privacy-settings、/risk/reports/my、/appeals/my）全部保留。
- 响应形状按小程序 JSDoc 适配（小程序被 86 页引用，是权威契约）：
  · /me/relationship-status 返回 status（旧 /relationship/status 返回 relationshipStatus，
    字段名不同，前端读的是 result.status）
  · /me/profile/review-status 返回 {status, items, submittedAt, reviewedAt}，时间统一 epoch 毫秒
  · /me/profile/submit-review 返回 {reviewStatus, submittedAt}
- 小程序三条历史写法一并兼容：/me/privacy-settings、/me/photos/{id}/main、/me/appeals

修复
- AuthService.getMeStatus：verified / profileStatus / reviewStatus 三项写死为
  false / not_started / not_submitted，注释标注"Phase 03/04/05 填充"，但那三个 Phase
  早已交付，导致 /me/status 长期返回错误的实名与审核状态。改为 capabilityService
  + userProfileMapper + reviewTaskMapper 的真实来源（与首页聚合同一判定）。
- PhotoController.deletePhoto：原用 ((Map<?,?>) p).get("id") 强转 UserPhoto 实体，
  必然抛 ClassCastException，删除照片恒定 500。改用实体主键比对。
- PhotoService.setMainAvatar（新增）：数据模型以 photo_type='avatar' 标识头像（见
  UserPhotoMapper#findAvatar），无 is_main 字段，故"设主图"= 换类型并保证至多一张。
  注意：插入该方法时曾把 deletePhoto 原有的 @Transactional 挤到新方法上，导致
  "Transactional is not a repeatable annotation" 并引发 Lombok 全面停摆（满屏
  找不到 getter/setter），已修正注解归属。

验证
- 后端全量：299 tests / 0 failures / 0 errors / 3 skipped / BUILD SUCCESS（+2 为新增契约测试）
- 新增 MeRouteContractTest（2 例）：同时断言 HTTP 方法，锁定 21 条 /me/* 与 13 条旧路径
- 小程序 tsc --noEmit 通过；UI 契约门禁 13/13

文档
- STATUS.md：/me/* 从"待裁决"改为"已完成"；核心待清债务 1 项 → 0 项
- API_INVENTORY.md：顶部"待收敛"警告改为"已收敛"，补全 /me/* 端点表
2026-09-16 12:54:39 +08:00

219 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 | 提交活动反馈 |
| 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