hl-api-changelog/changelogs-v2/2026-10/04_8754_补发成团通知回执如实计数与成团短信-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8754	补发成团通知回执改为如实计数：recipientCount 只算实际可达户，新增 smsCount / inappCount / skippedCount / smsReady；成团通知加客户短信（按下单手机号直发）	admin	jw(GIT)	修改接口	deployed	verified	implemented	mmg	c5f4af3639f11a60c698145b15ee6c4b1163e792	v2.1	2026-10-04	已合并 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。	2026-10-04	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

请求示例

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

响应示例

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

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

{
  "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
}

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

{
  "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	通知中心暂不可用	新增一种触发：读不到通知配置时也返回本码（冷却立即释放，可马上重试）

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

{
  "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
• PR: #8775
• Merge commit: aac6a6a13

联系人

• 后端负责人: @jw