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/* 端点表
This commit is contained in:
Codex
2026-09-16 12:54:39 +08:00
parent ce172ffd4f
commit bc4531a734
11 changed files with 651 additions and 52 deletions
+27 -11
View File
@@ -2,17 +2,22 @@
## 用户端 /api/v1/
> ⚠️ **待收敛:`/me/*` 系列**
> ✅ **已收敛(2026-09-16):后端补齐 `/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。
> 小程序 `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 最新路径」的裁决收敛完成(见下方「关系」「我的缘分」「匹配」)。
> `/me/*` 系列的收敛方向尚未裁决,**改动前请勿直接照抄本清单中的 `/me/*` 路径**。
> 路由裁决已被 `backend/.../contract/CanonicalRouteContractTest.java` 锁定。
### 认证
| Method | Path | 描述 |
@@ -28,13 +33,24 @@
|---|---|---|
| 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 | 获取上传凭证 |
| GET | /me/privacy-settings | 获取隐私设置 |
| PUT | /me/privacy-settings | 更新隐私设置 |
| GET | /me/review-status | 获取审核状态 |
| 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 | 描述 |