# 善缘丹阳红娘 Web 与小程序端整合设计

**状态：已获用户确认，作为实施基线**
**日期：2026-10-12**

## 1. 目标

在保留现有 V1.1 权限和隐私规则的前提下，打通红娘管理端 Web、红娘工作台小程序与普通用户端之间的服务闭环：

```text
Web 分配服务对象 → 小程序查看任务 → 小程序记录服务 → Web 查看最新结果
```

本设计不新建独立红娘小程序，不重建已有红娘后端模块，不改变用户自主 Like/Pass、活动互选和聊天确认规则。

## 2. 已确认的业务边界

- 普通红娘只能访问本人有效分配的服务对象。
- 服务对象由平台授权人员或红娘组长分配，普通红娘不能认领或转分配。
- 联系用户以平台内通知、服务申请和用户主动渠道为默认方式。
- 电话、线下联系和完整联系方式必须经过独立授权；未确认审批岗位和期限前保持默认拒绝。
- 红娘不能代替用户 Like、Pass、接受活动意向、确认开启聊天或修改关键择偶条件。
- 红娘服务记录只记录公益服务所需信息，修改和受控更正必须留痕。
- PostgreSQL 是业务事实来源，前端缓存和 Redis 不能覆盖业务状态。

## 3. 端职责

### 3.1 管理端 Web

负责服务申请队列、红娘分配/转分配/结束、联系授权审批、活动与转介任务管理、脱敏统计和审计查看。Web 不提供代用户交友操作和普通红娘全站用户检索。

### 3.2 红娘端小程序

负责工作台待办、本人服务对象、授权资料、服务历史、服务记录、候选建议、获授权活动任务、联系授权申请、风险转介和脱敏个人统计。小程序不提供全站搜索、分配管理、敏感资料下载或私人聊天全文。

## 4. 统一业务模型与事实来源

复用现有对象：

- `matchmaker_assignments`：服务范围和当前分配关系事实来源；
- `matchmaker_services`：服务任务；
- `matchmaker_followups`：跟进记录；
- `matchmaker_recommendations`：候选建议；
- 联系授权表：申请、审批、用户确认、撤销和到期；
- 统一通知和审计表：跨端提醒与操作留痕。

所有端点都由后端基于当前身份、权限、有效分配、字段策略和服务目的重新授权。客户端传入的 `userId`、`matchmakerId`、角色名和状态不能作为授权事实。

## 5. 第一阶段范围

第一阶段只实现最小可验证闭环：

1. Web 创建或调整服务分配；
2. 小程序工作台显示本人有效分配；
3. 小程序进入服务对象详情；
4. 小程序查看服务历史并新增服务记录；
5. Web 重新加载后查看服务记录和最新服务状态；
6. 分配结束、撤销、转交或红娘停用后，小程序不能继续访问旧对象；
7. 写操作成功后两端从服务端刷新，不依赖本地状态猜测。

第一阶段不包含实时 WebSocket、移动端分配管理、绩效排行榜、AI 自动决策和新的联系方式开放。

## 6. API 约定

继续使用 `/api/v1` 和统一响应 `{ success, code, message, data }`。第一阶段复用现有接口，必要时补充：

```text
GET  /operator/matchmaker/dashboard
GET  /operator/matchmaker/assignments/my
GET  /operator/matchmaker/services/{id}
GET  /operator/matchmaker/services/{id}/history
POST /operator/matchmaker/services/{id}/followup
GET  /operator/matchmaker/recommendations
```

资源不属于当前红娘有效服务范围时，服务端按项目统一错误规范拒绝，并写入必要的越权审计；响应不得泄露对象是否存在。

## 7. 状态与联动

服务任务沿用现有状态枚举，语义覆盖待分配、已分配、服务中、等待用户、待下一次跟进、已完成、已撤销、已转分配和已过期。两端不各自定义状态，也不在前端拼接业务状态。

P0 采用 `onShow`、页面切换和写操作后的重新拉取实现可靠联动；通知统一记录未读状态。实时通知作为后续 P1，只用于提醒，不能替代 API 刷新。

## 8. 安全、隐私和错误处理

- 列表、详情、历史、统计、文件和批量接口执行相同数据范围校验。
- 普通红娘默认不能看到完整手机号、微信号、精确地址、完整身份证和原始证明。
- 权限失效时清理对象缓存，提示服务权限已变更并返回工作台。
- 重复提交服务记录必须幂等或被明确拒绝。
- 网络失败时保留未提交表单内容。
- 应用日志和审计日志不得写入令牌、密码、完整身份证号、完整联系方式、原始证明、完整聊天正文或咨询全文。

## 9. 验收标准

- 未授权用户不能进入红娘工作台。
- 普通红娘只能看到本人有效分配对象。
- 修改 URL、`userId`、分页参数不能越权。
- Web 新建分配后小程序刷新可看到对象。
- Web 撤销、结束或转分配后原红娘不能继续查看对象。
- 小程序新增服务记录后 Web 可查看，记录含操作者和时间。
- 推荐不会直接创建 Match 或 Conversation。
- 联系授权未完成审批和用户确认前不返回完整联系方式。
- 关键越权、权限回收、重复提交和敏感字段场景有自动化测试。

## 10. 后续阶段

第一阶段通过后，再实施服务申请回应、候选建议、活动任务、风险转介、未读通知和实时推送。每个阶段单独验收，不自动放宽权限边界。