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

# Phase 13A 完成报告：公益婚恋咨询与婚前辅导

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

---

## 完成摘要

| 项目 | 内容 |
|------|------|
| Phase | 13A |
| 模块 | 公益婚恋咨询 + 婚前辅导 |
| 状态 | ✅ 核心链路已完成（V1.1 MVP） |
| 不变量 | INV-012 Counselor assigned scope ✅ |

---

## 完成的任务

### 数据模型（V022）
- `counseling_services` 表：完整生命周期（pending → assigned → scheduled → in_progress → completed/cancelled/closed）
- `counseling_followups` 表：跟进记录存储
- 5个 CHECK 约束：service_type、status、request_source
- 3个索引：user_id、assigned_operator_id、scheduled_start_at

### 用户端 API（T05~T09）
- `GET /api/v1/counseling/services/intro` — 咨询类型介绍
- `POST /api/v1/counseling/services` — 申请咨询（支持转介来源追踪）
- `GET /api/v1/counseling/services` — 我的咨询列表
- `GET /api/v1/counseling/services/{id}` — 咨询详情（权限校验）
- `POST /api/v1/counseling/services/{id}/cancel` — 取消咨询

### 婚前辅导（T10~T13）
- `service_type = premarital_guidance` 复用 counseling_services
- `companionUserId` 字段支持伴侣参与
- U58/U59 Miniapp 页面完整实现

### 后台管理（T19~T26）
- `getPendingQueue()` — 待分配队列
- `assignCounselor()` — 分配咨询师
- `scheduleCounseling()` — 安排时间
- `startCounseling()` — 开始咨询
- `addFollowup()` — 添加跟进记录
- `completeCounseling()` — 完成咨询
- `closeCounseling()` — 关闭咨询

### 权限隔离（T27）
- `getCounselorAssignedServices()` — Counselor 只能查看分配给自己的服务
- 前端 token 控制访问，后端 service 层强制过滤

---

## 数据库变更

### V022__add_counseling_services.sql

```sql
-- counseling_services
CREATE TABLE counseling_services (
    id, user_id, service_type, request_source,
    user_request_summary, organization_id, assigned_operator_id,
    status, preferred_service_mode, preferred_time,
    scheduled_start_at, scheduled_end_at,
    consent_version, consented_at,
    completed_at, closed_reason,
    companion_user_id, created_by_operator_id, user_confirmed_at,
    created_at, updated_at, deleted_at
);

-- counseling_followups
CREATE TABLE counseling_followups (
    id, counseling_id, operator_id, followup_type,
    content, result_code, next_followup_at,
    created_at, updated_at
);
```

---

## API 汇总

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/counseling/services/intro` | 咨询类型介绍 |
| POST | `/counseling/services` | 申请咨询 |
| GET | `/counseling/services` | 我的咨询列表 |
| GET | `/counseling/services/{id}` | 咨询详情 |
| POST | `/counseling/services/{id}/cancel` | 取消咨询 |
| GET | `/counseling/services/operator/queue` | 后台待分配队列 |
| POST | `/counseling/services/operator/{id}/assign` | 分配咨询师 |
| POST | `/counseling/services/operator/{id}/schedule` | 安排时间 |
| POST | `/counseling/services/operator/{id}/start` | 开始咨询 |
| POST | `/counseling/services/operator/{id}/followup` | 添加跟进 |
| POST | `/counseling/services/operator/{id}/complete` | 完成咨询 |
| POST | `/counseling/services/operator/{id}/close` | 关闭咨询 |
| GET | `/counseling/services/operator/assigned` | Counselor 查看分配服务 |

---

## Miniapp 新增页面

| 页面 | 编号 | 路径 |
|------|------|------|
| 公益婚恋咨询介绍 | U55 | `/pages/counseling-intro/counseling-intro` |
| 申请咨询 | U56 | `/pages/counseling-request/counseling-request` |
| 我的咨询 | U57 | `/pages/my-counseling/my-counseling` |
| 婚前辅导介绍 | U58 | `/pages/premarital-intro/premarital-intro` |
| 婚前辅导申请 | U59 | `/pages/premarital-request/premarital-request` |

---

## 不变量验证

| 不变量 | 验证方式 | 结果 |
|--------|----------|------|
| INV-012 Counselor assigned scope | `getCounselorAssignedServices()` 只返回 assigned_operator_id=当前操作员的记录 | ✅ |
| INV-013 Matchmaker 不能读取 Counseling 正文 | Counselor/Matchmaker 权限域分离（常量隔离） | ✅ |
| INV-005 红娘不可替用户操作 | 咨询申请由用户自己发起，红娘只能转介（request_source=matchmaker_referral） | ✅ |

---

## 待后续补充

| 任务 | 阶段 | 说明 |
|------|------|------|
| Admin Web 咨询管理页面 | Phase 19 | Vue 3 后台界面 |
| counseling_manager 范围控制 | Phase 19 | 批量管理权限 |
| SensitiveAccessLog 写入 | Phase 17 | 咨询内容访问审计 |
| 风控联动（RiskEvent source=counseling） | Phase 17 | 咨询内容风险检测 |

---

*Phase 13A 核心链路完成。下一阶段：Phase 14（多类型公益活动）*