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

**新建表：**
```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)
```

**扩展表：**
```sql
-- 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（公益婚恋咨询与婚前辅导）*