# 丹阳公益婚恋服务平台 # V1.0 REST API 接口详细设计规范 版本：V1.0 协议：HTTPS + REST 实时通信：WebSocket 基础路径：`/api/v1` 适用范围：微信小程序用户端、公益红娘工作台、运营管理后台 --- # 第一章 API设计目标 本规范用于统一： - REST路径 - HTTP方法 - 请求参数 - 响应结构 - 分页规范 - 错误码 - 权限校验 - 幂等机制 - 用户状态限制 - 数据脱敏 - 后台操作审计 目标是做到： > 前端知道怎么调用。 > 后端知道怎么实现。 > 测试知道怎么验收。 > 后续升级不会因为接口随意变化造成大量返工。 --- # 第二章 基础URL 生产环境示例： ```text https://api.example.com/api/v1 ``` 实际正式域名在部署阶段确定。 用户API： ```text /api/v1/* ``` 红娘工作台： ```text /api/v1/operator/* ``` 管理后台： ```text /api/v1/admin/* ``` --- # 第三章 HTTPS要求 所有生产API： > 必须HTTPS。 禁止： - HTTP明文登录 - HTTP上传敏感信息 - 在URL Query中传Token - 在URL中传身份证、手机号等敏感数据 --- # 第四章 HTTP方法规范 统一： ```text GET 查询 POST 创建/业务动作 PUT 整体修改 PATCH 局部修改 DELETE 删除/撤销 ``` V1实际业务中优先： ```text GET POST PATCH DELETE ``` --- # 第五章 API统一响应结构 成功： ```json { "success": true, "code": "OK", "message": "success", "data": {} } ``` 错误： ```json { "success": false, "code": "PROFILE_NOT_APPROVED", "message": "当前资料尚未通过审核", "data": null } ``` --- # 第六章 Trace ID 每个响应建议返回： ```text X-Request-Id ``` 错误响应也可包含： ```json { "requestId": "req_xxx" } ``` 方便排查问题。 --- # 第七章 Authentication Header 用户： ```text Authorization: Bearer ``` 工作人员同样： ```text Authorization: Bearer ``` 两类Token不可混用。 --- # 第八章 Idempotency Key 以下接口必须支持： ```text Idempotency-Key ``` 例如： ```text Idempotency-Key: 8f52... ``` 适用： - 提交审核 - 喜欢 - 活动报名 - 红娘申请 - 举报 - 签到 - 成功牵手请求 --- # 第九章 分页规范 后台列表： ```text ?page=1&pageSize=20 ``` 响应： ```json { "items": [], "page": 1, "pageSize": 20, "total": 128 } ``` 聊天、推荐等动态列表： > Cursor分页。 例如： ```text ?cursor=xxx&limit=20 ``` 返回： ```json { "items": [], "nextCursor": "xxx", "hasMore": true } ``` --- # 第十章 用户认证接口总览 ```text POST /auth/wechat/login POST /auth/phone/bind POST /auth/refresh POST /auth/logout GET /me/status ``` --- # 第十一章 POST /auth/wechat/login 用途： > 微信小程序登录。 请求： ```json { "code": "wx_login_code" } ``` 响应： ```json { "accessToken": "xxx", "refreshToken": "xxx", "expiresIn": 7200, "user": { "id": "usr_xxx", "phoneBound": false, "verified": false, "profileCompletionStatus": "not_started", "reviewStatus": "not_submitted", "accountStatus": "normal", "relationshipStatus": "searching" } } ``` --- # 第十二章 登录错误码 ```text WECHAT_LOGIN_FAILED ACCOUNT_BANNED ACCOUNT_CLOSED AUTH_PROVIDER_ERROR ``` --- # 第十三章 POST /auth/phone/bind 请求： 优先微信手机号授权： ```json { "phoneCode": "wx_phone_code" } ``` 备用验证码模式： ```json { "phone": "13800000000", "smsCode": "123456" } ``` 响应： ```json { "phoneBound": true, "phoneMasked": "138****0000" } ``` 错误： ```text PHONE_ALREADY_BOUND PHONE_INVALID SMS_CODE_INVALID ``` --- # 第十四章 POST /auth/refresh 请求： ```json { "refreshToken": "xxx" } ``` 响应： ```json { "accessToken": "new_token", "refreshToken": "new_refresh_token", "expiresIn": 7200 } ``` --- # 第十五章 POST /auth/logout 登录用户。 请求体： ```json {} ``` 响应： ```json { "loggedOut": true } ``` 服务端同时撤销当前会话。 --- # 第十六章 GET /me/status 这是前端路由守卫核心接口。 响应： ```json { "id": "usr_xxx", "phoneBound": true, "realNameVerified": true, "profileCompletionStatus": "completed", "reviewStatus": "approved", "accountStatus": "normal", "relationshipStatus": "searching", "recommendationEnabled": true, "visibleInSearch": true } ``` --- # 第十七章 实名认证接口总览 ```text GET /verification/status POST /verification/real-name ``` --- # 第十八章 GET /verification/status 响应： ```json { "status": "verified", "verifiedAt": "2026-08-28T10:00:00+08:00" } ``` 不能返回： - 完整姓名 - 身份证号码 --- # 第十九章 POST /verification/real-name 请求： ```json { "realName": "张三", "idNumber": "320xxxxxxxxxxxxx" } ``` 响应成功： ```json { "status": "verified", "adult": true, "gender": "male", "birthDate": "1990-05-12" } ``` --- # 第二十章 实名错误码 ```text REAL_NAME_MISMATCH ID_NUMBER_INVALID UNDER_18 VERIFICATION_FAILED VERIFICATION_RATE_LIMITED ALREADY_VERIFIED ``` --- # 第二十一章 用户资料接口总览 ```text GET /me/profile PATCH /me/profile/basic PATCH /me/profile/lifestyle PATCH /me/profile/relationship-intent PATCH /me/profile/self-intro GET /me/interests PUT /me/interests GET /me/photos POST /me/photos/upload-token POST /me/photos PATCH /me/photos/{photoId} DELETE /me/photos/{photoId} GET /me/profile/completion ``` --- # 第二十二章 GET /me/profile 响应： ```json { "displayName": "张先生", "gender": "male", "age": 36, "birthDate": "1990-05-12", "heightCm": 175, "region": { "code": "321181", "name": "丹阳" }, "maritalStatus": "never_married", "childrenStatus": "none", "educationCode": "bachelor", "occupationCode": "enterprise_employee", "workRegionCode": "321181", "smokingStatus": "no", "drinkingStatus": "occasional", "longTermDanyang": "yes", "futureDanyang": "yes", "relationshipGoal": "marriage", "marriagePlan": "within_1_2_years", "selfIntro": "……", "profileCompletion": 85, "reviewStatus": "approved" } ``` --- # 第二十三章 PATCH /me/profile/basic 请求： ```json { "heightCm": 175, "regionCode": "321181", "maritalStatus": "never_married", "childrenStatus": "none", "educationCode": "bachelor", "occupationCode": "enterprise_employee" } ``` 规则： - gender不可直接改 - birthDate不可直接改 - maritalStatus重要变更可能触发重新审核 --- # 第二十四章 PATCH /me/profile/lifestyle 请求： ```json { "workRegionCode": "321181", "smokingStatus": "no", "drinkingStatus": "occasional", "longTermDanyang": "yes", "futureDanyang": "yes" } ``` --- # 第二十五章 PATCH /me/profile/relationship-intent 请求： ```json { "relationshipGoal": "marriage", "marriagePlan": "within_1_2_years", "acceptMatchmakerRecommendation": true, "acceptActivityRecommendation": true } ``` --- # 第二十六章 PATCH /me/profile/self-intro 请求： ```json { "selfIntro": "性格开朗，平时喜欢运动和旅行……" } ``` 限制： - 长度50～500 - 禁止联系方式 - 禁止二维码文本 - 禁止广告 - 禁止明显违规内容 修改后： > 进入重新审核。 响应： ```json { "saved": true, "reviewRequired": true } ``` --- # 第二十七章 GET /me/interests 响应： ```json { "selected": [ "travel", "sports", "reading" ], "available": [ { "code": "travel", "name": "旅行" } ] } ``` --- # 第二十八章 PUT /me/interests 请求： ```json { "interestCodes": [ "travel", "sports", "reading" ] } ``` 限制： > 最多8项。 --- # 第二十九章 POST /me/photos/upload-token 请求： ```json { "fileType": "image/jpeg", "purpose": "profile_photo" } ``` 响应： ```json { "uploadUrl": "...", "fileKey": "users/usr_xxx/xxx.jpg", "expiresIn": 600 } ``` --- # 第三十章 POST /me/photos 图片上传对象存储后登记。 请求： ```json { "fileKey": "users/usr_xxx/xxx.jpg", "photoType": "avatar" } ``` 响应： ```json { "photoId": "pho_xxx", "reviewStatus": "pending" } ``` --- # 第三十一章 PATCH /me/photos/{photoId} 用于： - 排序 - 设主头像 示例： ```json { "sortOrder": 1 } ``` --- # 第三十二章 DELETE /me/photos/{photoId} 限制： 如果删除当前唯一主头像： > 拒绝或要求先上传新头像。 错误： ```text PRIMARY_AVATAR_REQUIRED ``` --- # 第三十三章 择偶条件接口 ```text GET /me/preferences PUT /me/preferences ``` --- # 第三十四章 GET /me/preferences 响应： ```json { "age": { "min": 28, "max": 35, "priority": "required" }, "height": { "min": 160, "max": 175, "priority": "preferred" }, "regions": [ "321181" ], "regionPriority": "required", "maritalStatuses": [ "never_married", "divorced" ], "maritalPriority": "preferred", "minEducationCode": "college", "educationPriority": "preferred", "childrenAcceptance": "case_by_case", "childrenPriority": "preferred" } ``` --- # 第三十五章 PUT /me/preferences 请求结构与GET基本一致。 服务端校验： - 年龄区间合法 - 身高区间合法 - priority只能required/preferred - 字典值有效 --- # 第三十六章 资料提交审核接口 ```text POST /me/profile/submit-review GET /me/profile/review-status ``` --- # 第三十七章 POST /me/profile/submit-review Header： ```text Idempotency-Key ``` 请求： ```json {} ``` 服务端校验： - 已实名 - 基础资料完整 - 有主头像 - 择偶条件完成 - 个人介绍合法 响应： ```json { "reviewTaskId": "rev_xxx", "status": "pending" } ``` --- # 第三十八章 提交审核错误码 ```text PROFILE_INCOMPLETE REAL_NAME_REQUIRED AVATAR_REQUIRED PREFERENCE_INCOMPLETE REVIEW_ALREADY_PENDING ACCOUNT_LIMITED ``` --- # 第三十九章 GET /me/profile/review-status 响应： ```json { "status": "need_edit", "items": [ { "itemType": "avatar", "status": "need_edit", "reasonCode": "AVATAR_NOT_CLEAR", "reasonText": "当前照片无法清楚确认本人" }, { "itemType": "self_intro", "status": "approved" } ] } ``` --- # 第四十章 首页推荐接口 ```text GET /recommendations/today POST /recommendations/{targetUserId}/pass ``` 喜欢不放推荐模块，统一走relation模块。 --- # 第四十一章 GET /recommendations/today 请求： ```text ?cursor=xxx&limit=6 ``` 响应： ```json { "items": [ { "user": { "id": "usr_2", "displayName": "王女士", "age": 32, "heightCm": 165, "regionName": "丹阳", "educationName": "本科", "occupationName": "教师", "maritalStatusName": "未婚", "avatarUrl": "signed-url", "verified": true, "reviewed": true }, "level": "high", "reasons": [ "年龄符合双方要求", "都希望长期在丹阳生活", "婚恋计划比较一致" ], "relationStatus": "neutral" } ], "dailyLimit": 6, "todayViewed": 2, "nextCursor": "xxx", "hasMore": true } ``` --- # 第四十二章 推荐访问限制 如果： ```text PROFILE_NOT_APPROVED ACCOUNT_LIMITED RELATIONSHIP_PAUSED ``` 返回对应错误。 --- # 第四十三章 找对象接口 ```text GET /discover/users ``` Query： ```text minAge maxAge minHeight maxHeight regionCode maritalStatus educationCode childrenAcceptance cursor limit ``` --- # 第四十四章 GET /discover/users 响应： ```json { "items": [ { "id": "usr_xxx", "displayName": "王女士", "age": 32, "heightCm": 165, "regionName": "丹阳", "educationName": "本科", "occupationName": "教师", "maritalStatusName": "未婚", "avatarUrl": "...", "verified": true } ], "nextCursor": "xxx", "hasMore": true } ``` --- # 第四十五章 用户公开详情接口 ```text GET /users/{userId}/profile ``` 仅返回： > PublicUserProfileDTO 不能返回： - 手机号 - 身份证 - 完整姓名 - 精确住址 - 完整单位 --- # 第四十六章 用户详情响应 ```json { "id": "usr_xxx", "displayName": "王女士", "age": 32, "heightCm": 165, "regionName": "丹阳", "educationName": "本科", "occupationName": "教师", "maritalStatusName": "未婚", "childrenStatusName": "无", "smokingStatusName": "不吸烟", "drinkingStatusName": "偶尔", "selfIntro": "……", "interests": [ "旅行", "阅读", "运动" ], "photos": [], "relationshipGoalName": "以结婚为目的的稳定关系", "marriagePlanName": "1～2年内", "verified": true, "reviewed": true, "recommendReasons": [], "relationStatus": "neutral", "canChat": false } ``` --- # 第四十七章 Relationship接口总览 ```text POST /relationships/{targetUserId}/like DELETE /relationships/{targetUserId}/like POST /relationships/{targetUserId}/pass POST /relationships/{targetUserId}/block DELETE /relationships/{targetUserId}/block GET /relationships/mutual GET /relationships/liked-by-me GET /relationships/liked-me ``` --- # 第四十八章 POST /relationships/{targetUserId}/like Header： ```text Idempotency-Key ``` 响应非双向： ```json { "relationStatus": "liked", "mutualMatch": false } ``` 响应双向： ```json { "relationStatus": "mutual_match", "mutualMatch": true, "matchId": "mat_xxx", "conversationId": "con_xxx" } ``` --- # 第四十九章 Like错误码 ```text CANNOT_LIKE_SELF TARGET_UNAVAILABLE ALREADY_BLOCKED BLOCKED_BY_TARGET PROFILE_NOT_APPROVED RELATIONSHIP_NOT_SEARCHABLE ACCOUNT_LIMITED ``` --- # 第五十章 DELETE /relationships/{targetUserId}/like 用途： > 取消单向喜欢。 如果已经双向匹配： > 不允许通过此接口直接解除。 错误： ```text MUTUAL_MATCH_EXISTS ``` 应使用： > 解除匹配接口。 --- # 第五十一章 POST /relationships/{targetUserId}/pass 响应： ```json { "passed": true } ``` --- # 第五十二章 POST /relationships/{targetUserId}/block 响应： ```json { "blocked": true, "conversationClosed": true } ``` --- # 第五十三章 DELETE /relationships/{targetUserId}/block 响应： ```json { "blocked": false } ``` 不会自动恢复原match。 --- # 第五十四章 GET /relationships/mutual Cursor分页。 响应： ```json { "items": [ { "matchId": "mat_xxx", "user": {}, "matchedAt": "2026-08-28T10:00:00+08:00", "conversationId": "con_xxx" } ] } ``` --- # 第五十五章 Match管理接口 用户侧： ```text GET /matches/{matchId} POST /matches/{matchId}/unmatch POST /matches/{matchId}/getting-to-know POST /matches/{matchId}/success-request POST /matches/{matchId}/success-confirm POST /matches/{matchId}/success-decline ``` --- # 第五十六章 POST /matches/{matchId}/unmatch 请求： ```json { "reasonCode": "not_suitable" } ``` 响应： ```json { "matchStatus": "unmatched" } ``` --- # 第五十七章 POST /matches/{matchId}/getting-to-know 请求： ```json { "pauseOtherRecommendations": true } ``` 响应： ```json { "matchStatus": "getting_to_know", "relationshipStatus": "getting_to_know", "recommendationEnabled": false } ``` --- # 第五十八章 POST /matches/{matchId}/success-request 请求： ```json {} ``` 响应： ```json { "requestId": "succ_xxx", "status": "pending" } ``` --- # 第五十九章 POST /matches/{matchId}/success-confirm 只有对方可确认。 响应： ```json { "matchStatus": "successful", "relationshipStatus": "matched_successfully" } ``` --- # 第六十章 聊天接口总览 REST： ```text GET /conversations GET /conversations/{conversationId} GET /conversations/{conversationId}/messages POST /conversations/{conversationId}/messages POST /conversations/{conversationId}/read ``` 实时： > WebSocket --- # 第六十一章 GET /conversations 响应： ```json { "items": [ { "conversationId": "con_xxx", "targetUser": { "id": "usr_xxx", "displayName": "王女士", "avatarUrl": "..." }, "lastMessage": "周末有时间吗？", "lastMessageAt": "2026-08-28T10:32:00+08:00", "unreadCount": 2, "canSend": true } ] } ``` --- # 第六十二章 GET /conversations/{id}/messages Query： ```text ?cursor=xxx&limit=30 ``` 响应： ```json { "items": [ { "id": "msg_xxx", "senderId": "usr_xxx", "type": "text", "content": "你好", "createdAt": "2026-08-28T10:31:00+08:00", "status": "sent" } ], "nextCursor": "xxx", "hasMore": true } ``` --- # 第六十三章 POST /conversations/{id}/messages 请求文字： ```json { "clientMessageId": "client_xxx", "type": "text", "content": "你好，很高兴认识你" } ``` 图片： ```json { "clientMessageId": "client_xxx", "type": "image", "fileId": "file_xxx" } ``` --- # 第六十四章 聊天发送错误码 ```text MATCH_REQUIRED CONVERSATION_CLOSED BLOCKED_RELATION ACCOUNT_LIMITED TARGET_UNAVAILABLE MESSAGE_TOO_FREQUENT MESSAGE_CONTENT_INVALID ``` --- # 第六十五章 POST /conversations/{id}/read 请求： ```json { "lastReadMessageId": "msg_xxx" } ``` 响应： ```json { "unreadCount": 0 } ``` --- # 第六十六章 未读数量接口 ```text GET /messages/unread-summary ``` 响应： ```json { "chatUnread": 3, "systemUnread": 2, "totalUnread": 5 } ``` --- # 第六十七章 系统通知接口 ```text GET /notifications POST /notifications/{id}/read POST /notifications/read-all ``` --- # 第六十八章 活动用户接口 ```text GET /activities GET /activities/{activityId} POST /activities/{activityId}/registrations GET /me/activity-registrations GET /activities/{activityId}/checkin-token POST /activities/{activityId}/feedback ``` --- # 第六十九章 GET /activities Query： ```text status=upcoming cursor limit ``` 响应： ```json { "items": [ { "id": "act_xxx", "title": "丹阳青年公益相亲会", "coverUrl": "...", "startAt": "2026-09-20T14:00:00+08:00", "locationName": "丹阳××活动中心", "feeType": "free", "registrationStatus": "not_applied" } ] } ``` --- # 第七十章 GET /activities/{id} 响应： ```json { "id": "act_xxx", "title": "丹阳青年公益相亲会", "description": "……", "organizerName": "××单位", "startAt": "2026-09-20T14:00:00+08:00", "endAt": "2026-09-20T17:00:00+08:00", "locationName": "丹阳××活动中心", "locationAddress": "……", "minAge": 25, "maxAge": 40, "needReview": true, "status": "registration_open", "registrationStatus": "not_applied" } ``` --- # 第七十一章 POST /activities/{id}/registrations Header： ```text Idempotency-Key ``` 请求： ```json { "agreeRules": true, "emergencyContact": { "name": "张某", "phone": "13800000000" } } ``` 紧急联系人是否必填： > 由活动配置决定。 响应： ```json { "registrationId": "reg_xxx", "status": "pending" } ``` --- # 第七十二章 报名错误码 ```text ACTIVITY_NOT_OPEN ACTIVITY_FULL GENDER_QUOTA_FULL AGE_NOT_ELIGIBLE ALREADY_APPLIED PROFILE_NOT_APPROVED ACCOUNT_LIMITED ``` --- # 第七十三章 GET /me/activity-registrations 响应： ```json { "items": [ { "registrationId": "reg_xxx", "activity": {}, "status": "approved", "checkinStatus": "not_checked_in" } ] } ``` --- # 第七十四章 GET /activities/{id}/checkin-token 仅： > 报名已通过用户。 响应： ```json { "token": "signed_token", "expiresAt": "2026-09-20T15:00:00+08:00" } ``` --- # 第七十五章 POST /activities/{id}/feedback 请求： ```json { "satisfaction": 5, "joinAgain": "yes", "interestedUserId": "usr_xxx", "comment": "活动组织很好" } ``` interestedUserId： > 可为空。 --- # 第七十六章 公益红娘用户接口 ```text POST /matchmaker/services GET /matchmaker/services GET /matchmaker/services/{serviceId} GET /matchmaker/recommendations GET /matchmaker/recommendations/{recommendationId} POST /matchmaker/services/{serviceId}/supplement ``` --- # 第七十七章 POST /matchmaker/services 请求： ```json { "serviceType": "recommend_partner", "description": "希望帮我推荐一些年龄30～35岁的丹阳本地对象" } ``` 响应： ```json { "serviceId": "mms_xxx", "status": "submitted" } ``` --- # 第七十八章 GET /matchmaker/services/{id} 响应： ```json { "id": "mms_xxx", "serviceType": "recommend_partner", "status": "in_service", "assignedMatchmaker": { "displayName": "张老师", "organizationName": "××公益服务中心" }, "followups": [ { "time": "2026-08-28T10:00:00+08:00", "summary": "正在帮助筛选合适对象" } ] } ``` --- # 第七十九章 GET /matchmaker/recommendations 响应： ```json { "items": [ { "id": "mmr_xxx", "targetUser": {}, "reason": "年龄、地区和婚恋计划比较符合", "status": "pending_view", "createdAt": "..." } ] } ``` --- # 第八十章 举报接口 ```text POST /reports GET /me/reports POST /appeals ``` --- # 第八十一章 POST /reports 请求： ```json { "targetUserId": "usr_xxx", "reportType": "fraud", "description": "对方引导我投资", "evidenceFileIds": [ "file_xxx" ] } ``` 响应： ```json { "reportId": "rep_xxx", "status": "pending" } ``` --- # 第八十二章 举报错误码 ```text CANNOT_REPORT_SELF REPORT_DUPLICATE TARGET_NOT_FOUND REPORT_TYPE_INVALID EVIDENCE_INVALID ``` --- # 第八十三章 婚恋状态接口 ```text GET /me/relationship-status PATCH /me/relationship-status ``` --- # 第八十四章 PATCH /me/relationship-status 请求暂停： ```json { "status": "paused" } ``` 响应： ```json { "status": "paused", "recommendationEnabled": false } ``` 成功牵手不能通过此接口直接设置。 错误： ```text SUCCESS_CONFIRMATION_REQUIRED ``` --- # 第八十五章 隐私设置接口 ```text GET /me/privacy PATCH /me/privacy ``` 请求： ```json { "visibleInRecommendations": true, "visibleInSearch": false, "showOccupation": true, "showLifestylePhotos": true, "receiveActivityRecommendations": true, "acceptMatchmakerRecommendations": true } ``` --- # 第八十六章 黑名单接口 ```text GET /me/blacklist ``` 拉黑/解除拉黑统一走Relationship接口。 --- # 第八十七章 意见反馈 ```text POST /feedback ``` 请求： ```json { "type": "feature", "description": "希望优化筛选功能", "fileIds": [], "contactPhone": "13800000000" } ``` --- # 第八十八章 红娘工作人员认证接口 ```text POST /operator/auth/login POST /operator/auth/logout GET /operator/me ``` --- # 第八十九章 POST /operator/auth/login 请求： ```json { "username": "zhang", "password": "******" } ``` 响应： ```json { "accessToken": "...", "operator": { "id": "opr_xxx", "name": "张老师", "organization": { "id": "org_xxx", "name": "××公益服务中心" }, "roles": [ "matchmaker" ], "permissions": [ "matchmaker.service", "matchmaker.user.view" ] } } ``` --- # 第九十章 红娘端服务接口 ```text GET /operator/matchmaker/services GET /operator/matchmaker/services/{id} POST /operator/matchmaker/services/{id}/claim POST /operator/matchmaker/services/{id}/followups GET /operator/matchmaker/services/{id}/candidates POST /operator/matchmaker/services/{id}/recommendations POST /operator/matchmaker/services/{id}/complete ``` --- # 第九十一章 GET /operator/matchmaker/services Query： ```text status page pageSize ``` 响应： ```json { "items": [ { "id": "mms_xxx", "user": { "id": "usr_xxx", "displayName": "张先生", "age": 36, "regionName": "丹阳" }, "serviceType": "recommend_partner", "status": "submitted", "createdAt": "..." } ], "total": 28 } ``` --- # 第九十二章 POST /operator/matchmaker/services/{id}/claim 权限： ```text matchmaker.service ``` 响应： ```json { "claimed": true, "status": "assigned" } ``` 并发失败： ```text SERVICE_ALREADY_CLAIMED ``` --- # 第九十三章 GET /operator/matchmaker/services/{id}/candidates 响应： ```json { "items": [ { "user": {}, "matchLevel": "high", "reasons": [ "年龄符合双方要求", "地区符合" ] } ] } ``` --- # 第九十四章 POST /operator/matchmaker/services/{id}/recommendations 请求： ```json { "targetUserId": "usr_xxx", "reason": "年龄、地区和婚恋计划比较符合" } ``` 服务端必须验证： - target仍可推荐 - 未拉黑 - 审核正常 - 不违反双方required条件 --- # 第九十五章 管理后台认证 可复用： ```text /operator/auth/* ``` 通过权限区分红娘与管理员。 也可以保持： ```text /admin/auth/login ``` 但不建议维护两套完全不同的账号体系。 推荐： > 一个Operator账号系统，多角色、多权限。 --- # 第九十六章 管理后台工作台 ```text GET /admin/dashboard ``` 响应： ```json { "pendingReviews": 12, "pendingReports": 2, "pendingMatchmakerAssignments": 5, "pendingActivityRegistrations": 16, "newUsersToday": 18, "mutualMatchesToday": 7 } ``` --- # 第九十七章 后台用户管理 ```text GET /admin/users GET /admin/users/{userId} PATCH /admin/users/{userId}/status GET /admin/users/{userId}/sensitive-identity ``` --- # 第九十八章 GET /admin/users Query： ```text keyword gender regionCode verificationStatus reviewStatus relationshipStatus accountStatus riskLevel page pageSize ``` --- # 第九十九章 GET /admin/users/{id} 根据权限返回： > AdminUserDTO 不自动包含敏感实名。 --- # 第一百章 GET /admin/users/{id}/sensitive-identity 权限： ```text user.sensitive.view ``` 请求Header可要求： ```text X-Access-Reason: 审核身份异常 ``` 响应： ```json { "realName": "张三", "idNumberMasked": "320***********1234" } ``` 如果业务确实需要完整身份证： > 建议单独更高权限接口。 每次访问写： > sensitive_access_logs。 --- # 第一百零一章 审核后台接口 ```text GET /admin/reviews GET /admin/reviews/{reviewId} POST /admin/reviews/{reviewId}/claim POST /admin/reviews/{reviewId}/approve POST /admin/reviews/{reviewId}/need-edit POST /admin/reviews/{reviewId}/reject ``` --- # 第一百零二章 POST /admin/reviews/{id}/claim 权限： ```text review.process ``` 响应： ```json { "status": "processing", "assignedOperatorId": "opr_xxx" } ``` --- # 第一百零三章 POST /admin/reviews/{id}/approve 请求： ```json { "items": [ { "itemType": "avatar", "status": "approved" } ], "comment": "资料正常" } ``` 服务端： - 完成审核 - 更新Profile审核状态 - 触发ProfileApproved事件 - 发送通知 --- # 第一百零四章 POST /admin/reviews/{id}/need-edit 请求： ```json { "items": [ { "itemType": "avatar", "status": "need_edit", "reasonCode": "AVATAR_NOT_CLEAR", "comment": "请上传清晰正面照片" } ] } ``` --- # 第一百零五章 匹配管理后台 ```text GET /admin/matches/stats GET /admin/matches GET /admin/match-rules POST /admin/match-rules POST /admin/match-rules/{id}/activate ``` --- # 第一百零六章 GET /admin/match-rules 响应： ```json { "activeVersion": 3, "rules": [ { "version": 3, "status": "active", "weights": { "age": 15, "region": 15, "marital": 10 }, "minimumScore": 60 } ] } ``` --- # 第一百零七章 POST /admin/match-rules 权限： ```text match.rule.manage ``` 请求： ```json { "weights": { "age": 15, "region": 15, "marital": 10, "children": 10, "education": 5, "height": 5, "marriagePlan": 15, "settlement": 10, "lifestyle": 10, "interest": 5 }, "minimumScore": 60 } ``` 必须校验总分： > 100。 --- # 第一百零八章 活动后台接口 ```text GET /admin/activities POST /admin/activities GET /admin/activities/{id} PATCH /admin/activities/{id} POST /admin/activities/{id}/publish POST /admin/activities/{id}/cancel GET /admin/activities/{id}/registrations POST /admin/activity-registrations/{registrationId}/approve POST /admin/activity-registrations/{registrationId}/reject POST /admin/activities/{id}/checkin GET /admin/activities/{id}/feedback ``` --- # 第一百零九章 POST /admin/activities 请求： ```json { "title": "丹阳青年公益相亲会", "coverFileId": "file_xxx", "description": "……", "organizerOrgId": "org_xxx", "startAt": "2026-09-20T14:00:00+08:00", "endAt": "2026-09-20T17:00:00+08:00", "locationName": "丹阳××活动中心", "locationAddress": "……", "maleLimit": 50, "femaleLimit": 50, "totalLimit": 100, "minAge": 25, "maxAge": 40, "registrationStartAt": "...", "registrationEndAt": "...", "needReview": true } ``` --- # 第一百一十章 报名审核接口 批准： ```text POST /admin/activity-registrations/{id}/approve ``` 响应： ```json { "status": "approved" } ``` 如果名额已满： ```text ACTIVITY_FULL ``` 必须事务控制。 --- # 第一百一十一章 活动签到后台 ```text POST /admin/activities/{id}/checkin ``` 请求： ```json { "checkinToken": "signed-token" } ``` 响应： ```json { "user": { "displayName": "张先生", "phoneMasked": "138****1234" }, "status": "checked_in", "checkinAt": "..." } ``` 重复签到： ```text ALREADY_CHECKED_IN ``` --- # 第一百一十二章 红娘后台管理 ```text GET /admin/matchmaker/services POST /admin/matchmaker/services/{id}/assign GET /admin/matchmakers PATCH /admin/matchmakers/{id}/status ``` --- # 第一百一十三章 POST /admin/matchmaker/services/{id}/assign 请求： ```json { "operatorId": "opr_xxx" } ``` 权限： ```text matchmaker.assign ``` --- # 第一百一十四章 举报风控后台接口 ```text GET /admin/reports GET /admin/reports/{id} POST /admin/reports/{id}/resolve GET /admin/risk/users/{userId} POST /admin/risk/users/{userId}/actions POST /admin/risk/actions/{actionId}/revoke GET /admin/appeals POST /admin/appeals/{id}/resolve ``` --- # 第一百一十五章 POST /admin/reports/{id}/resolve 请求： ```json { "resultCode": "confirmed_fraud", "action": "temporary_suspend", "comment": "经核实存在诱导投资行为" } ``` 服务端： - 更新Report - 创建RiskEvent - 创建RiskAction - 更新User状态 - 写AuditLog - 必要时关闭聊天与推荐 --- # 第一百一十六章 风控处理权限 ```text risk.report.process risk.user.limit risk.user.suspend risk.user.ban ``` 不同操作应可拆权限。 --- # 第一百一十七章 组织管理接口 ```text GET /admin/organizations POST /admin/organizations GET /admin/organizations/{id} PATCH /admin/organizations/{id} ``` --- # 第一百一十八章 工作人员管理接口 ```text GET /admin/operators POST /admin/operators GET /admin/operators/{id} PATCH /admin/operators/{id} POST /admin/operators/{id}/reset-password POST /admin/operators/{id}/roles ``` --- # 第一百一十九章 权限管理接口 ```text GET /admin/roles POST /admin/roles GET /admin/permissions PUT /admin/roles/{roleId}/permissions ``` --- # 第一百二十章 数据统计接口 ```text GET /admin/analytics/overview GET /admin/analytics/users GET /admin/analytics/matches GET /admin/analytics/activities GET /admin/analytics/matchmaker GET /admin/analytics/risk ``` --- # 第一百二十一章 数据统计时间参数 统一： ```text startDate endDate ``` 例如： ```text ?startDate=2026-08-01&endDate=2026-08-31 ``` --- # 第一百二十二章 配置接口 ```text GET /admin/configs PATCH /admin/configs/{key} ``` 普通前端可读取公开配置： ```text GET /app/config ``` 响应： ```json { "dailyRecommendationLimit": 6, "maxProfilePhotos": 6, "maxInterestTags": 8, "activityEnabled": true, "matchmakerEnabled": true, "chatImageEnabled": true } ``` --- # 第一百二十三章 文件通用接口 建议： ```text POST /files/upload-token GET /files/{fileId}/access-url ``` 不能让用户通过fileId任意获取别人隐私文件。 必须验证业务权限。 --- # 第一百二十四章 WebSocket连接 建议路径： ```text /wss/chat ``` 或： ```text /ws ``` 建立连接后认证。 消息事件： ```text message.new message.read conversation.closed match.created notification.new account.status_changed ``` --- # 第一百二十五章 WebSocket message.new示例 ```json { "event": "message.new", "data": { "conversationId": "con_xxx", "message": { "id": "msg_xxx", "senderId": "usr_xxx", "type": "text", "content": "你好", "createdAt": "..." } } } ``` --- # 第一百二十六章 WebSocket安全原则 必须： - Token认证 - 连接绑定userId - 服务端决定订阅权限 - 不允许客户端自行订阅任意conversationId - account limited后主动断开或限制 --- # 第一百二十七章 统一错误码分类 建议前缀： ```text AUTH_ USER_ VERIFY_ PROFILE_ REVIEW_ MATCH_ RELATION_ MESSAGE_ ACTIVITY_ MATCHMAKER_ RISK_ PERMISSION_ SYSTEM_ ``` --- # 第一百二十八章 通用错误码 ```text OK INVALID_ARGUMENT UNAUTHORIZED FORBIDDEN RESOURCE_NOT_FOUND RATE_LIMITED DUPLICATE_ACTION CONFLICT INTERNAL_ERROR SERVICE_UNAVAILABLE MAINTENANCE ``` --- # 第一百二十九章 用户状态错误 ```text ACCOUNT_LIMITED ACCOUNT_SUSPENDED ACCOUNT_BANNED ACCOUNT_CLOSED ``` --- # 第一百三十章 资料错误 ```text REAL_NAME_REQUIRED PROFILE_INCOMPLETE PROFILE_NOT_APPROVED PROFILE_REVIEW_PENDING AVATAR_REQUIRED PREFERENCE_INCOMPLETE ``` --- # 第一百三十一章 匹配错误 ```text TARGET_UNAVAILABLE CANNOT_LIKE_SELF ALREADY_LIKED MUTUAL_MATCH_EXISTS MATCH_NOT_FOUND MATCH_NOT_ACTIVE ``` --- # 第一百三十二章 消息错误 ```text MATCH_REQUIRED CONVERSATION_NOT_FOUND CONVERSATION_CLOSED MESSAGE_TOO_FREQUENT MESSAGE_CONTENT_INVALID ``` --- # 第一百三十三章 活动错误 ```text ACTIVITY_NOT_FOUND ACTIVITY_NOT_OPEN ACTIVITY_FULL GENDER_QUOTA_FULL AGE_NOT_ELIGIBLE ALREADY_APPLIED REGISTRATION_NOT_APPROVED ALREADY_CHECKED_IN ``` --- # 第一百三十四章 权限错误 ```text PERMISSION_DENIED ORGANIZATION_SCOPE_DENIED SENSITIVE_ACCESS_DENIED ``` --- # 第一百三十五章 运营后台组织范围 机构管理员只能查看： > 本机构授权范围。 API层不能只靠前端传： ```text organizationId ``` 服务端从operator上下文判断。 --- # 第一百三十六章 请求参数校验 统一校验： - 字符长度 - Enum - ID格式 - 日期范围 - 上传文件类型 - 分页上限 - 文本内容 - 用户状态 不能依赖数据库报错给用户。 --- # 第一百三十七章 pageSize上限 后台： ```text max pageSize = 100 ``` 用户动态列表： ```text max limit = 50 ``` 避免恶意一次请求全库。 --- # 第一百三十八章 API日志 记录： - method - path - status - requestId - operator/user匿名ID - duration 不能记录： - 密码 - Token - 身份证 - 聊天正文 - 举报完整内容 --- # 第一百三十九章 敏感接口审计 这些接口必须额外审计： ```text /admin/users/{id}/sensitive-identity /admin/reports/{id} /admin/risk/users/{id}/actions /admin/roles/{id}/permissions /admin/operators/* ``` --- # 第一百四十章 API版本策略 V1统一： ```text /api/v1 ``` 未来重大破坏性变更： ```text /api/v2 ``` 不要： > 一个接口字段今天叫status，明天直接改成state。 优先保持向后兼容。 --- # 第一百四十一章 删除接口原则 婚恋核心数据不提供普通物理删除API。 例如： 不设计： ```text DELETE /admin/users/{id} ``` 而是： ```text PATCH /admin/users/{id}/status ``` 改为： > closed / banned。 --- # 第一百四十二章 API DTO原则 严禁Controller直接返回数据库Entity。 必须使用： ```text Request DTO Response DTO ``` 例如： ```text PublicUserProfileResponse SelfProfileResponse AdminUserResponse MatchmakerUserResponse ``` --- # 第一百四十三章 前后台DTO绝不能复用敏感全集 错误： ```text UserDTO ``` 所有地方都返回。 正确： ```text UserSummaryResponse PublicProfileResponse SelfProfileResponse AdminProfileResponse SensitiveIdentityResponse ``` --- # 第一百四十四章 推荐理由归属 推荐理由由： > Match Service生成。 接口返回结构化信息。 前端不自己算。 红娘推荐也应尽量复用同一匹配服务理由。 --- # 第一百四十五章 REST动作接口命名 纯CRUD优先资源式。 业务动作可以使用： ```text /approve /reject /claim /publish /checkin ``` 不要为了“REST纯洁性”把业务动作设计得难懂。 清晰优先。 --- # 第一百四十六章 接口幂等验收 必须测试： 1. 连续点击两次喜欢 2. 连续两次提交报名 3. 同一举报重复提交 4. 双击资料提交审核 5. 签到码扫码两次 6. 弱网消息重发 最终不能生成重复核心数据。 --- # 第一百四十七章 权限验收 必须测试： - 普通用户访问admin接口 - 红娘查看完整身份证 - 活动管理员封禁用户 - 审核员修改角色权限 - 不属于该机构的数据访问 - 手工构造他人conversationId 必须返回： > 401 / 403 / 业务权限错误。 --- # 第一百四十八章 状态验收 必须测试： ### 审核中用户 访问： ```text /recommendations/today ``` 返回： ```text PROFILE_NOT_APPROVED ``` ### 被封禁用户 发送聊天： ```text ACCOUNT_BANNED ``` ### 已拉黑 发送聊天： ```text BLOCKED_RELATION ``` --- # 第一百四十九章 推荐API性能目标 建议： ```text GET /recommendations/today P95 < 1.5s ``` 普通GET： ```text P95 < 500ms ``` 后台复杂统计： ```text P95 < 2s ``` 初期足够。 --- # 第一百五十章 API开发顺序 第一阶段： ```text Auth Verification Profile Preferences Review ``` 第二阶段： ```text Recommendations Relationships Matches Messaging ``` 第三阶段： ```text Activities Matchmaker Risk Notifications ``` 第四阶段： ```text Admin Analytics Config ``` --- # 第一百五十一章 最核心的端到端接口链 用户第一次使用： ```text POST /auth/wechat/login ↓ POST /auth/phone/bind ↓ POST /verification/real-name ↓ PATCH /me/profile/basic ↓ PATCH /me/profile/lifestyle ↓ POST /me/photos ↓ PATCH /me/profile/relationship-intent ↓ PUT /me/preferences ↓ POST /me/profile/submit-review ``` 审核员： ```text GET /admin/reviews ↓ POST /admin/reviews/{id}/claim ↓ POST /admin/reviews/{id}/approve ``` 用户： ```text GET /recommendations/today ↓ GET /users/{id}/profile ↓ POST /relationships/{id}/like ↓ Mutual Match ↓ GET /conversations ↓ POST /conversations/{id}/messages ``` 这就是V1.0最核心的API闭环。 --- # 第一百五十二章 API最终设计原则 整个REST API必须坚持： > **接口语义稳定。** > **用户状态由服务端判断。** > **敏感字段绝不进入普通DTO。** > **所有关键动作必须幂等。** > **所有后台敏感操作必须鉴权和审计。** > **前端不能靠猜测接口结果推进关键状态。** > **核心业务错误使用明确错误码。** > **API围绕用户任务设计，不围绕数据库表机械暴露。** V1.0最终要求达到： > 微信小程序、公益红娘工作台和运营管理后台都可以基于同一套稳定、清晰、安全的服务端接口完成完整业务闭环，同时为后续升级保留足够扩展空间。