Mimingguang和Claude Opus 4.8
8b56ce67c6
changelog-filename-gate / validate (push) Failing after 2s
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
291 行
14 KiB
Markdown
291 行
14 KiB
Markdown
---
|
||
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
|