danyang-match/docs/v12/V1.2-状态机与接口契约.md

善缘丹阳 V1.2 状态机与接口契约

1. 账号登录与服务准入

主登录标识为已核验手机号，密码只保存哈希。账号发放后必须首次改密；初始密码不落库、不写日志。两份服务授权书分别确认，任一拒绝或撤回时，账号可以登录处理必要事项，但不得进入匹配、搜索、推荐、聊天、活动匹配、红娘推荐、咨询或预约等服务入口。

2. 资料版本与审核

认证完成后的个人资料变更必须在同一事务中：

1. 写入新的 profile_revision；
2. 将新版本标记为 pending_review；
3. 保留旧的 published_profile_revision；
4. 记录操作者、时间和变更摘要。

只有审核通过才能把新版本设为 published_profile_revision。审核等待、拒绝或要求补充期间，旧的已发布版本继续作为唯一对外资料；新版本不得被搜索、推荐、活动匹配、红娘推荐或其他用户查看。若没有可用的旧发布版本，则用户不进入这些业务流程。

3. 红娘分配

• V1.2 首版只支持人工分配。
• 普通红娘只能访问本人有效分配对象。
• 红娘组长只能访问和管理本组织范围。
• 管理员拥有平台范围权限。
• 无可用红娘时写入待分配队列，不阻塞用户注册。
• 分配前必须校验：资料已发布、手机号已核验、授权有效、账号正常、服务资格有效。

4. 关键接口约束

所有接口使用 /api/v1，统一响应 { success, code, message, data }。请求体中的 userId、matchmakerId、teamId、角色和范围字段不得决定权限；范围由服务端认证主体推导。关键写接口支持 Idempotency-Key。

场景	接口	关键约束
密码登录	POST /auth/password/login	仅已核验手机号；返回首次改密、授权和服务状态
首次改密	POST /auth/password/change-initial	成功后旧凭据和旧会话失效
服务授权	GET/POST /account/service-consent	两份文档分别确认并审计版本
资料修改	现有资料更新接口	认证后个人资料写入必须创建新版本并进入审核
审核通过	现有审核接口	原子推进发布版本，才恢复展示和匹配
红娘看板	GET /operator/matchmaker/workbench/dashboard	只返回主体权限范围内的六项指标

5. 审计与敏感数据

密码、验证码、完整手机号、身份证号和授权正文不得写入普通日志。账号发放、手机号核验、授权确认/撤回、资料版本审核、红娘分配和越权拒绝必须保留审计事件。