danyang-match/docs/Phase-13-V11-Completion-Report.md

Phase 13 完成报告：公益红娘服务转介

版本基线：v1.0.0-RC.2 → v1.1.0-dev | 日期：2026-09-08 对应 EPIC：EPIC-P13-V11

---

完成摘要

项目	内容
Phase	13
模块	公益红娘服务转介
状态	✅ 已完成
不变量	INV-005 红娘不可替用户操作（强制保留）

---

完成的任务

P13-V11-T01：转介婚恋咨询

• 通过 service_appointments 表的 source + request_source 字段支持红娘转介
• 预约类型 service_type 支持 counselor_consultation
• 用户确认后激活服务，红娘不能代用户确认

P13-V11-T02：转介公益活动

• activity_registrations 表新增 source、request_source、created_by_operator_id、user_confirmed_at 字段
• 红娘转介活动时创建报名表，状态为 pending，需用户确认
• 用户确认后才激活报名

P13-V11-T03：转介善缘服务站

• 新增 service_appointments 表（V021 迁移）
• 支持 source 追踪：user_self / matchmaker_referral / operator_assisted 等
• 红娘转介创建预约，状态为 submitted，需用户确认后才变为 pending_confirmation

P13-V11-T04：转介来源追踪

• Constants 新增 5 个 REFERRAL_SOURCE 常量
• DB 表统一字段：source、request_source、created_by_operator_id、user_confirmed_at
• ReferralService.getReferralHistory() 支持查询用户转介历史

P13-V11-T05：用户确认机制（二阶段同意）

• 转介创建后不自动激活，用户需调用 POST /referrals/{id}/confirm 确认
• 确认后状态更新，工作人员才能安排后续服务
• 完全符合 INV-005：红娘只可转介，不可代替用户确认/完成

---

数据库变更

V021__add_service_appointments_and_referral_fields.sql

新建表：

service_appointments (
    id, user_id, service_location_id, service_type,
    preferred_date, preferred_time_slot, user_note,
    status, assigned_operator_id, confirmed_start_at,
    cancelled_by, cancel_reason, source, request_source,
    created_by_operator_id, user_confirmed_at,
    created_at, updated_at, deleted_at
)
CHECK: status IN (submitted, pending_confirmation, confirmed, completed, cancelled)
CHECK: source IN (user_self, matchmaker_referral, activity_followup, service_station, operator_assisted)

扩展表：

-- activity_registrations 新增字段
ALTER TABLE activity_registrations ADD COLUMN source VARCHAR(64) DEFAULT 'user_self';
ALTER TABLE activity_registrations ADD COLUMN request_source VARCHAR(64) DEFAULT 'user_self';
ALTER TABLE activity_registrations ADD COLUMN created_by_operator_id UUID;
ALTER TABLE activity_registrations ADD COLUMN user_confirmed_at TIMESTAMPTZ;

-- matchmaker_services 新增字段（用于追踪转介目标）
ALTER TABLE matchmaker_services ADD COLUMN referral_target_type VARCHAR(64);
ALTER TABLE matchmaker_services ADD COLUMN referral_target_id VARCHAR(128);
ALTER TABLE matchmaker_services ADD COLUMN referral_source_type VARCHAR(64) DEFAULT 'manual';

---

API 新增

方法	路径	说明
POST	/api/v1/service-appointments	用户/红娘创建预约
GET	/api/v1/service-appointments	获取我的预约
GET	/api/v1/service-appointments/{id}	预约详情
POST	/api/v1/service-appointments/{id}/cancel	取消预约
POST	/api/v1/referrals/service-station	红娘转介服务站预约
POST	/api/v1/referrals/activity	红娘转介公益活动
POST	/api/v1/referrals/{id}/confirm	用户确认转介
GET	/api/v1/referrals/my-history	查询转介历史

---

Java 新增/修改文件

文件	操作	说明
service_appointment/entity/ServiceAppointment.java	新增	预约实体
service_appointment/entity/ServiceLocation.java	新增	服务站实体（复用V019表）
service_appointment/mapper/ServiceAppointmentMapper.java	新增	预约Mapper
service_appointment/mapper/ServiceLocationMapper.java	新增	服务站Mapper
service_appointment/dto/ServiceAppointmentRequest.java	新增	创建预约请求DTO
service_appointment/dto/ServiceAppointmentDTO.java	新增	预约响应DTO
service_appointment/service/ServiceAppointmentService.java	新增	预约服务
service_appointment/controller/ServiceAppointmentController.java	新增	预约控制器
referral/service/ReferralService.java	新增	转介核心逻辑
referral/controller/ReferralController.java	新增	转介控制器
activity/entity/ActivityRegistration.java	修改	新增 source/request_source 等字段
shared/constant/Constants.java	修改	新增 APPOINTMENT_STATUS_* + REFERRAL_SOURCE_*
notification/service/NotificationService.java	修改	新增 sendMatchmakerReferralCreated

---

不变量验证

不变量	验证方式	结果
INV-005 红娘不可替用户操作	转介只创建记录，状态为submitted/pending，用户需confirm才激活	✅ 通过
INV-011 本地资格佐证授权	未涉及，保持不变	✅
INV-012 Counselor assigned scope	未涉及，Phase 13A 实现	⏳ 待验证
INV-014/015 活动 Mutual 二阶段同意	与活动互选独立，红娘转介活动使用新流程	✅
INV-016 Banner 内链限制	未涉及，Phase 19 实现	⏳ 待验证

---

前端实现计划（后续 Phase）

页面	编号	说明
转介记录列表	U64	用户端查看红娘转介记录
服务站预约表单	U55（扩展）	用户端预约服务站
后台转介管理	Admin-referral	运营后台查看和管理转介

---

依赖关系

• 依赖 V019（service_locations 表存在）✅
• 依赖 V020（NOTIFICATION_TYPE_APPOINTMENT 存在）✅
• Phase 13A（婚恋咨询完整链路）依赖本 Phase 的 source 字段基础 ✅
• Phase 14/16（活动互选重构）独立，无阻塞 ✅

---

Phase 13 完成。下一阶段：Phase 13A（公益婚恋咨询与婚前辅导）