---
schema: "hl-changelog/v2"
ticket: "8754"
title: "补发成团通知回执改为如实计数：recipientCount 只算实际可达户，新增 smsCount / inappCount / skippedCount / smsReady；成团通知加客户短信（按下单手机号直发）"
consumer: "admin"
author: "jw(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "mmg"
frontend_ref: "c5f4af3639f11a60c698145b15ee6c4b1163e792"
target_release: "v2.1"
verified_at: "2026-10-04"
status_note: "已合并 dev-v3（PR #8775，merge aac6a6a13）并部署 TEST（user-service aac6a6a13 + 迁移 20261003.8754；order-v3 9b72d23a3 含本单），自签 admin token 经网关按 #8754 AC-1~10 实测通过。补发回执 recipientCount 改为实际可达户数，新增 smsCount / inappCount / skippedCount / smsReady；成团（手动 / 自动）与补发按订单下单手机号发短信，模板号仍是哨兵、只记「模板未配置」不真发，运营过审后在通知配置后台填号即生效。前端待做：补发成功提示改用新字段（smsReady=false 时提示短信模板未配置），不要再用 recipientCount 当已通知户数。前端已交付(2026-10-04):补发成功提示改走 notifyFormedResultText(「已通知 N 户(短信 X、站内信 Y),Z 户未能通知」,smsReady=false 追加「短信模板未配置,本次仅发站内信」),提交 c5f4af363。"
updated_at: "2026-10-04"
base: "dev-v3"
---

# order-v3: 补发成团通知回执如实计数 + 成团通知加客户短信

**服务**: hl-order-service-v3（回执计数）、hl-user-service（通知配置）
**PR**: `#8775`（已合入 `dev-v3`，合并提交 `aac6a6a13`）
**Issue**: #8754

---

## ⚠️ 关键变化

🔴 **`recipientCount` 含义变了**：改前 = 团期活跃子订单户数（收不到的户也算进去）；改后 = **按当前通知配置实际可达的户数**。短信模板未配真实号期间，没有小程序账号的户收不到任何通知，`recipientCount` 会明显小于户数，这是如实反映，不是故障。

🟢 **回执新增 5 个字段**：`smsCount`、`inappCount`、`skippedCount`、`smsReady`（短信通道是否就绪）。入参、判权、冷却 300 秒、已有错误码均不变；589594 文案补了一种情形。

🟢 **成团通知加客户短信**：手动成团、自动成团与补发，每户按订单的下单手机号发短信（不依赖小程序账号），有小程序账号的户站内信照旧。短信模板号未配之前（当前状态）短信只记「模板未配置」不真发，运营拿到阿里云模板号后在通知配置后台填入即生效。

---

## 一、背景

成团通知原只开站内信、按小程序账号投递，而团期子订单绝大多数是后台代下单、没有小程序账号（09-27 TEST 实测 686 户里 683 户没有），客户实际收不到；补发按钮的回执还把这些户算进 `recipientCount`，运营会以为都通知到了。jw 2026-10-03 定：成团照常无条件通知（不加「不通知」开关）；客户侧改发短信，收件人用订单下单手机号；先开发、模板后补。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 补发成团通知 | POST | `/v3/admin/order/group-batch/{groupBatchId}/notify-formed` | 修改 | `recipientCount` 改为实际可达户数；新增 `smsCount` / `inappCount` / `skippedCount` / `smsReady`；589594 文案补「或各户既无合规手机号也无小程序账号」 |

成团 `POST /v3/admin/order/group-batch/{groupBatchId}/group` 的入参、出参、错误码一字未变，只是成团后发出的通知多了短信（见「六、边界行为」）。

---

## 三、接口详情

### 1. 补发成团通知 `POST /v3/admin/order/group-batch/{groupBatchId}/notify-formed`

**VO**: `Result<GroupBatchNotifyRespVO>`

#### 使用场景

团期详情「更多操作 → 补发成团通知」。对已成团团期，向全部在团户再发一次成团通知（短信 + 有小程序账号的户另发站内信），回执告诉运营这次实际能通知到几户、短信几户、站内信几户、跳过几户，以及短信通道是否就绪。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| groupBatchId | Path | Long | ✅ | 团期 ID | **不变** |

无请求体、无查询参数（不变）。

#### 出参

| 字段 | 类型 | 说明 |
|------|------|------|
| groupBatchId | String | 团期 ID（Long 序列化为字符串），**不变** |
| eventCode | String | 固定 `GROUP_BATCH_FORMED`，**不变** |
| recipientCount | Integer | 🔄 **改口径**：实际可达户数 = 短信可达户 ∪ 站内信可达户（一户两条通道都可达只算一户，不是 `smsCount + inappCount`） |
| smsCount | Integer | 🆕 短信可达户数：订单下单手机号为 11 位大陆手机号，且 `smsReady=true`。`smsReady=false` 时恒 0。按户计、不按号码去重 |
| inappCount | Integer | 🆕 站内信可达户数：订单有小程序账号，且站内信通道开启 |
| skippedCount | Integer | 🆕 跳过户数 = 在团户数 − `recipientCount`（无联系方式、通道未就绪或投递失败的户） |
| smsReady | Boolean | 🆕 短信通道是否就绪：短信开关开且已配真实模板号。`false` 表示模板号还没配（或短信被关），本次短信不会真发 |
| enqueued | Boolean | **不变**，恒 `true`（失败时接口直接返回错误码） |
| notifiedAt | String | **不变**，本次补发时间 |
| cooldownSeconds | Integer | **不变**，固定 300 |

#### 请求示例

```http
POST /v3/admin/order/group-batch/{groupBatchId}/notify-formed HTTP/1.1
Authorization: Bearer <管理端 token>
```

#### 响应示例

TEST 实际返回（团 T26-1771，3 户：1 户有手机号且有小程序账号、1 户只有手机号、1 户都没有）。

短信模板号未配置（当前状态）：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2106359366087323650",
    "eventCode": "GROUP_BATCH_FORMED",
    "recipientCount": 1,
    "smsCount": 0,
    "inappCount": 1,
    "skippedCount": 2,
    "smsReady": false,
    "enqueued": true,
    "notifiedAt": "2026-10-03 20:29:03",
    "cooldownSeconds": 300
  },
  "success": true
}
```

模板号已配置（同一个团）：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2106359366087323650",
    "eventCode": "GROUP_BATCH_FORMED",
    "recipientCount": 2,
    "smsCount": 2,
    "inappCount": 1,
    "skippedCount": 1,
    "smsReady": true,
    "enqueued": true,
    "notifiedAt": "2026-10-03 20:43:59",
    "cooldownSeconds": 300
  },
  "success": true
}
```

#### 空数据 / 降级响应

- 短信模板号未配（当前状态）：`smsReady=false`、`smsCount=0`，没有小程序账号的户全部计入 `skippedCount`。接口仍返回成功，冷却照常开始。
- 通知中心没有该事件的配置：两条通道都不可达，`recipientCount=0`、`skippedCount`=在团户数，接口仍返回成功。

#### 错误响应

| code | 含义 | 变化 |
|---|---|---|
| 589507 | 无团期管理权限 | 不变 |
| 589500 | 团期不存在 | 不变 |
| 589552 | 团期未成团（招募中）或已流团 | 不变 |
| 589593 | 冷却期内重复补发，message 含剩余秒数 | 不变 |
| 589594 | 没有可通知的客户 | 🔄 文案改为「本团期没有可通知的客户（无有效子订单，或各户既无合规手机号也无小程序账号）」，新增后一种情形 |
| 589595 | 通知中心暂不可用 | 新增一种触发：读不到通知配置时也返回本码（冷却立即释放，可马上重试） |

```json
{
  "code": 589594,
  "message": "本团期没有可通知的客户（无有效子订单，或各户既无合规手机号也无小程序账号）",
  "data": null,
  "success": false
}
```

```json
{
  "code": 589593,
  "message": "成团通知补发过于频繁，请 287 秒后再试",
  "data": null,
  "success": false
}
```

#### 业务边界

- 回执的计数是「已发出且按当前通知配置能到达」，不是供应商回执的「已送达」；单条短信最终是否送达以通知发送日志为准。
- 下单手机号不是 11 位大陆手机号（如座机）的户不发短信；该户若有小程序账号，通知中心会按账号绑定的手机号补发短信，这种情况**不计入** `smsCount`（保守口径）。
- 同一手机号挂在多户上时每户各发一条，`smsCount` 按户计。
- 冷却 300 秒只挡补发：成团刚发完立刻点补发不受冷却限制，模板号配好后客户会收到第二条短信。

---

## 四、契约约束与正确调用方式

- 补发成功提示请用新字段，不要再用 `recipientCount` 当「已通知户数 / 总户数」：建议文案「已通知 {recipientCount} 户（短信 {smsCount}、站内信 {inappCount}），{skippedCount} 户未能通知」。
- `smsReady=false` 时提示「短信模板未配置，本次仅发站内信」，避免运营误以为故障。
- `recipientCount` 不等于 `smsCount + inappCount`，不要相加。

---

## 五、数据库行为

- order-v3：零 DDL、零写入；补发时多一次对 user-service 通知配置的只读调用。
- user-service：迁移 `V20261003_8754` 只改 `notification_event_config` 中 `GROUP_BATCH_FORMED` 一行——开短信、模板号写哨兵 `TODO_PLACEHOLDER`（已填真实号不覆盖）、短信变量映射 `productName` / `departureDate` / `batchNo`。
- 每次成团 / 补发在 `notification_send_log` 按户写短信行（模板未配时状态为「模板未配置」）与站内信行，收件手机号以掩码落库。

---

## 六、边界行为

- **成团（手动 / 自动）**：契约不变；成团后每户发短信（下单手机号）+ 站内信（有小程序账号的户），通知失败不影响成团结果。
- **下单手机号与小程序账号都没有的户**：不发，补发时计入 `skippedCount`。
- **模板号填入**：运营经通知配置后台填真实阿里云模板号即生效，不必发版；模板变量名须为 `productName`、`departureDate`、`batchNo`（后台改不了变量映射）。

## 六.6、修改前后对比

| 场景 | 改前 | 改后 |
|---|---|---|
| 683 户无小程序账号、3 户有的团，补发 | `recipientCount=686`，实际只有 3 户收到站内信 | 模板未配：`recipientCount=3`、`smsCount=0`、`inappCount=3`、`skippedCount=683`、`smsReady=false`；模板配好后 `smsCount=686`、`recipientCount=686` |
| 成团后客户收到什么 | 只有有小程序账号的户收到站内信 | 每户按下单手机号收短信（模板配好后），有账号的户另收站内信 |
| 各户都没有任何联系方式 | 返回成功、`recipientCount`=户数 | 589594 |

## 六.7、影响评估

- **是否破坏向后兼容**：字段结构向后兼容（纯新增）；`recipientCount` 的数值语义变了，前端若用它展示「已通知 N 户」，模板未配期间数字会变小。
- **前端是否必须同步上线**：否，但建议尽快把提示语换成新字段，否则模板未配期间会显示「已通知 0 户」之类让人误会的数字。
- **回滚**：revert PR #8775 后重新部署 order-v3 与 user-service；或只在通知配置后台关掉该事件的短信开关。

---

## 七、不影响范围

- 成团接口 `POST /v3/admin/order/group-batch/{groupBatchId}/group` 的入参、出参、错误码。
- 补发的判权、冷却 300 秒、状态门。
- 流团通知（#8247 另做）、其他通知事件。
- 小程序端接口：无变化（站内信照旧）。

---

## 八、测试环境已验证

**环境**：TEST（`https://api.test.1814.love`）　**验证时间**：2026-10-03 20:25~20:50
**构建身份**：user-service `dev-v3 @ aac6a6a13`（迁移 `20261003.8754` 已执行）；order-v3 `9b72d23a3`，已确认包含 `aac6a6a13`。探针：补发回执出现 `smsCount` / `skippedCount` / `smsReady` 字段。
**身份**：自签 admin token 经网关调用。

### 8.1 成团发出的通知

| 场景 | 结果 |
|---|---|
| 手动成团（团 A，3 户） | 有手机号的 2 户各一条短信记录（收件号码掩码，状态「模板未配置」），有小程序账号的那户另有一条站内信；两者都没有的户无记录，服务日志留了跳过行（只写「订单手机号=空」） |
| 自动成团（团 B，2 户，定时任务 20:25 触发） | 两户各一条短信记录（状态「模板未配置」） |

### 8.2 补发回执逐户对账

| 场景 | 回执 | 发送记录 |
|---|---|---|
| 模板未配（团 A） | `recipientCount=1, smsCount=0, inappCount=1, skippedCount=2, smsReady=false` | 新增 2 条短信（模板未配置）+ 1 条站内信（成功），逐户对得上；1 + 2 = 3 户 |
| 临时填假模板号（团 A） | `recipientCount=2, smsCount=2, inappCount=1, skippedCount=1, smsReady=true` | 两条短信到达阿里云后被拒（`isv.SMS_TEMPLATE_ILLEGAL`），不再是「模板未配置」；改完到生效 3 秒，无需发版 |
| 还原哨兵后再补发 | `smsReady=false, smsCount=0` | 短信回到「模板未配置」 |

### 8.3 反例

| 操作 | 结果 |
|---|---|
| 冷却期内再补发 | `589593「成团通知补发过于频繁，请 269 秒后再试」`，无新增发送记录 |
| 不带 token | `code 401「缺少有效的 Authorization 头」` |
| 对招募中团期补发 | `589552「团期尚未成团，请先完成成团后再操作」` |

### 8.4 脱敏

回执不含手机号；发送记录的短信收件号码全为掩码；造数手机号明文在 order-v3、user-service 日志里出现 0 次。

### 本地证据

| 项 | 读数 |
|---|---|
| order-v3 全量（有 Docker，两半） | A 10992 / B 4935 例；1144 个可执行类全部有报告；红类 3 个均在基底 `f8f553860` 逐条复现，本单引入 0 |
| user-service 全量 | 4211 例 0 失败 |
| 评审修正后定向 | order-v3 187 例（含全部架构门禁）+ user-service 143 例全绿；迁移 MySQL 测试 5 + 4 例通过 |

---

## 十、相关文档

- Issue `#8754`；PR `#8775`
- 前置：#7534（补发端点）、#8404（成团通知只开站内信）、#3713（按手机号直发短信通道）

## 关联 / 联系人

### 链接

- **Issue**: [#8754](https://git.1814.love/wx/HL/issues/8754)
- **PR**: [#8775](https://git.1814.love/wx/HL/pulls/8775)
- **Merge commit**: [aac6a6a13](https://git.1814.love/wx/HL/commit/aac6a6a13)

### 联系人

- **后端负责人**: @jw