danyang-match/docs/superpowers/plans/2026-10-12-matchmaker-dual-client-integration.md

# 红娘双端最小联动闭环实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 打通红娘 Web 分配、小程序服务对象详情与服务记录、Web 查看结果的第一阶段闭环。

**Architecture:** 复用现有 Spring Boot 红娘模块、Vue 管理端和微信小程序原生页面。以 `matchmaker_assignments` 作为数据范围事实来源，以服务端 API 作为状态事实来源，前端只负责展示和提交操作。

**Tech Stack:** Java 21、Spring Boot 3.x、PostgreSQL、MyBatis-Plus、Vue 3、TypeScript、微信小程序原生 JavaScript/WXML/WXSS。

**Spec:** `docs/superpowers/specs/2026-10-12-matchmaker-dual-client-integration-design.md`

## Global Constraints

- 普通红娘只能访问本人有效分配对象。
- 红娘不能代替用户 Like、Pass、接受活动意向或确认开启聊天。
- PostgreSQL 是 Source of Truth，前端缓存不能覆盖服务端状态。
- 联系方式默认拒绝，未完成授权不得返回完整手机号、微信号和详细地址。
- 不增加依赖，不新建微服务，不改动无关领域。
- 所有新增业务逻辑先写失败测试，再写最小实现。

### Task 1: 固化端点和数据范围测试

**Files:**
- Modify: `backend/src/test/java/com/danyang/match/platform/matchmaker/*` 现有红娘测试
- Create: `backend/src/test/java/com/danyang/match/platform/matchmaker/MatchmakerServiceDetailScopeTest.java`
- Create: `backend/src/test/java/com/danyang/match/platform/matchmaker/MatchmakerFollowupScopeTest.java`

**Interfaces:**
- Consumes: `ServiceAssignmentPolicy`、`MatchmakerServiceService`、现有 `MatchmakerAssignment` 测试夹具。
- Produces: 可证明“本人有效分配允许、其他红娘/失效分配拒绝”的测试契约。

- [ ] Step 1: 写测试：同一服务对象在有效分配给当前红娘时详情和跟进允许；换成其他红娘、撤销或过期时拒绝。
- [ ] Step 2: 运行单测，确认因现有服务详情/跟进调用路径缺少或未覆盖断言而失败。
- [ ] Step 3: 仅补齐服务层调用现有 `ServiceAssignmentPolicy` 的最小授权检查和统一错误映射。
- [ ] Step 4: 重新运行新增测试及现有 `MatchmakerReferralPhase13Test`、`MatchmakerAssignmentPermissionTest`。
- [ ] Step 5: 记录端点和数据范围结论到阶段报告。

### Task 2: 补齐小程序服务对象详情页面

**Files:**
- Create: `miniapp/pages/matchmaker-service-detail/matchmaker-service-detail.js`
- Create: `miniapp/pages/matchmaker-service-detail/matchmaker-service-detail.wxml`
- Create: `miniapp/pages/matchmaker-service-detail/matchmaker-service-detail.wxss`
- Create: `miniapp/pages/matchmaker-service-detail/matchmaker-service-detail.json`
- Modify: `miniapp/app.json`
- Modify: `miniapp/pages/matchmaker-workbench/matchmaker-workbench.js`

**Interfaces:**
- Consumes: `GET /operator/matchmaker/services/{id}`、`GET /operator/matchmaker/services/{id}/history`、`POST /operator/matchmaker/services/{id}/followup`。
- Produces: 从工作台分配卡片进入详情、查看授权字段、查看历史和提交服务记录。

- [ ] Step 1: 写页面契约测试或静态守卫，验证页面已注册、请求只使用服务 ID、没有联系方式和代操作按钮。
- [ ] Step 2: 运行守卫确认当前页面目录缺失导致失败。
- [ ] Step 3: 实现最小详情页：加载、空状态、失败、无权限、历史列表和记录表单。
- [ ] Step 4: 记录提交成功后重新拉取详情和历史；失败保留表单输入；重复提交由提交锁阻止。
- [ ] Step 5: 运行小程序现有页面守卫和 WXML/WXSS 编译检查。

### Task 3: 统一 Web 服务详情和跟进查看

**Files:**
- Modify: `admin-web/src/modules/matchmaker/MatchmakerManagementView.vue`
- Create or modify: `admin-web/src/api/*` only if现有 `get/post` 无法复用
- Modify: `backend/src/main/java/com/danyang/match/platform/matchmaker/controller/MatchmakerOperatorController.java` only when Task 1 proves endpoint缺失

**Interfaces:**
- Consumes: Task 1 的详情、历史和范围契约。
- Produces: Web 在本人授权范围内查看服务记录和最新服务状态。

- [ ] Step 1: 写前端行为测试/契约守卫，验证列表点击详情时只传服务 ID，范围错误显示统一提示。
- [ ] Step 2: 运行测试确认当前管理页没有服务详情和跟进查看入口。
- [ ] Step 3: 增加最小抽屉或弹窗，显示服务状态、最近跟进和必要摘要。
- [ ] Step 4: 分配、转交、撤销、结束后刷新当前 Tab，不保留旧对象状态。
- [ ] Step 5: 运行 `admin-web` 类型检查和构建。

### Task 4: 跨端刷新和权限失效处理

**Files:**
- Modify: `miniapp/pages/matchmaker-workbench/matchmaker-workbench.js`
- Modify: `miniapp/pages/matchmaker-service-detail/matchmaker-service-detail.js`
- Modify: `miniapp/utils/api.js`
- Modify: `admin-web/src/api/client.ts` only if现有错误处理不能统一

**Interfaces:**
- Consumes: Task 1-3 的端点和错误契约。
- Produces: 页面显示始终以最新服务端状态为准，权限失效时清理敏感缓存并返回工作台。

- [ ] Step 1: 写请求层测试，验证 401/403/资源失效不会静默吞掉，并能被页面识别。
- [ ] Step 2: 运行测试确认当前请求层行为不足。
- [ ] Step 3: 增加最小的刷新、提交锁、权限失效跳转和非敏感缓存清理。
- [ ] Step 4: 验证 Web 与小程序写操作后都重新读取服务端数据。
- [ ] Step 5: 运行小程序请求层测试和 Web 构建。

### Task 5: 第一阶段验收与文档

**Files:**
- Create: `docs/Phase-matchmaker-dual-client-Completion-Report-2026-10-12.md`
- Modify: `docs/STATUS.md` only for已验证状态
- Modify: `docs/governance/open-questions.md` only for未确认联系授权细节

- [ ] Step 1: 运行后端红娘相关测试、前端构建和小程序静态/编译守卫。
- [ ] Step 2: 以两个红娘账号和一个普通用户账号执行分配、查看、记录、撤销和越权场景。
- [ ] Step 3: 将每项结果标记为 `PASS`、`PARTIAL`、`FAIL` 或 `NOT_VERIFIED`。
- [ ] Step 4: 只有所有 P0 场景通过才将第一阶段标为 `PASS`，否则保留 `PARTIAL` 或 `FAIL`。
- [ ] Step 5: 输出剩余风险和第二阶段依赖，不自动进入下一阶段。