149 lines
6.0 KiB
Markdown
149 lines
6.0 KiB
Markdown
# 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（公益婚恋咨询与婚前辅导）*
|