# 智慧康养短信平台系统 模块规划

---

## 1. 模块定位

智慧康养短信平台系统是全平台的**消息基础设施**，为所有业务模块提供短信发送能力，包括业务通知短信（服务确认/审核结果/订单变更）、健康预警短信（体征异常推送家属）、系统告警短信（设备离线/SOS事件）以及模板管理、接口对接和发送统计等能力。

本系统是平台级基础能力，不面向终端用户直接提供界面，而是作为内部服务对其他模块暴露 API。

---

## 2. 建设目标

1. 提供统一的短信发送 API，所有业务模块通过统一入口发送短信，避免各模块各自对接运营商
2. 管理短信模板，支持变量占位符（老人姓名/服务时间/家属联系方式）
3. 实现健康预警短信的优先级发送（体征危急值 = 最高优先级）
4. 提供发送统计与失败重试机制
5. 支持多运营商/多通道切换，保障发送成功率

---

## 3. 核心功能范围

### 3.1 一级模块

- 短信发送服务
- 健康预警短信
- 告警自动发送
- 模板管理
- 运营商接口对接
- 发送统计
- 权限管理

### 3.2 二级模块

- **短信发送服务**：单发、群发、定时发送 API
- **健康预警**：健康管理系统（08）触发危急值短信，优先级队列
- **告警自动发送**：安全系统（09）SOS/跌倒/走失告警短信自动发送给家属/护工
- **模板管理**：内置系统模板 + 自定义模板，工信部报备管理
- **运营商对接**：阿里云短信/腾讯云短信/云之讯等多通道配置，自动故障切换
- **发送统计**：每日/月发送量、成功率、费用统计、模板使用排行
- **权限管理**：各模块调用限额、IP白名单、API密钥管理

### 3.3 核心功能说明

| 功能         | 描述                                                   | 技术要点                  |
| ------------ | ------------------------------------------------------ | ------------------------- |
| 统一短信API  | 内部HTTP API接口，接收目标号码+模板+变量，返回发送结果 | RESTful API + 异步回调    |
| 优先级队列   | SOS告警 > 健康危急 > 业务通知，高优先级跳过排队        | 分级消息队列（多个Queue） |
| 多通道切换   | 主通道失败→自动切换备用通道（<30s内）                  | 健康检查 + 故障转移逻辑   |
| 模板变量渲染 | 模板中 ${name}、${time} 占位符替换                     | 字符串模板引擎            |
| 失败重试     | 发送失败后按指数退避重试（最多3次）                    | 重试队列 + 退避算法       |

---

## 4. 与现有 mall 的关系

**契合度：C（低契合，架构可参考但不可直接复用）**

mall 自身集成了短信发送功能（注册验证码/订单通知），但：

| 能力             | mall 现状                 | 结论                             |
| ---------------- | ------------------------- | -------------------------------- |
| 短信发送基础能力 | 有（阿里云短信SDK集成）   | 可参考实现方式，但未做成独立服务 |
| 模板管理界面     | 无（模板硬编码在业务层）  | 须新建专项管理界面               |
| 优先级消息队列   | 无                        | 须新建                           |
| 多通道故障切换   | 无                        | 须新建                           |
| 健康预警短信业务 | 无（纯电商领域无此需求）  | 须新建                           |
| 多模块统一API    | 无（短信dispersed在各处） | 须统一接入点设计                 |

**建设路径：独立微服务（C→D，以独立为主）**

鉴于全平台27个模块都需要短信能力，建议将本系统建设为独立的基础设施微服务（类似短信网关），而非在 mall 中扩展。

---

## 5. 规划判断

**独立微服务（短信基础设施）**

- 无独立用户界面（仅有内部管理后台）
- 对内：提供HTTP/gRPC短信发送API
- 对外：对接阿里云/腾讯云短信平台
- 管理界面：轻量级Vue3 Web（模板管理+统计查看）

---

## 6. 需新增业务能力

1. **统一短信网关API**：标准化短信发送接口（单发/批量发/定时发）
2. **模板管理与工信部报备**：短信模板的创建、审核状态管理、报备流程追踪
3. **多通道编排**：配置主备通道，自动健康检查和故障切换
4. **优先级队列**：至少三级优先级（紧急/普通/营销）
5. **发送限流**：按调用方（模块）设置每小时/每日发送上限，防止异常刷量
6. **号码黑名单**：支持用户退订（短信STOP指令处理），合规管理

---

## 7. 需新增数据模型

| 模型                 | 关键字段                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `sms_template`       | id, code, name, content, variables(array), channel_template_ids(JSONB), status, registered_at |
| `sms_send_record`    | id, template_id, receiver, variables(JSONB), channel, priority, status, sent_at, fail_reason  |
| `sms_channel_config` | id, provider(aliyun/tencent), access_key, priority_level, is_active, health_status            |
| `sms_quota_config`   | caller_module, hour_limit, day_limit, current_hour_count, current_day_count                   |
| `sms_blacklist`      | phone_no, reason, added_at, added_by                                                          |

---

## 8. 需新增技术栈 / 第三方能力 / 中间件

| 类别       | 技术选型                         | 用途                     |
| ---------- | -------------------------------- | ------------------------ |
| 短信服务商 | 阿里云SMS（主）+ 腾讯云SMS（备） | 短信发送通道             |
| 消息队列   | RabbitMQ（多级优先级队列）       | 异步发送、优先级管理     |
| 缓存       | Redis                            | 限流计数器、号码频率控制 |
| 监控       | Prometheus指标暴露               | 发送成功率、队列深度监控 |

---

## 9. 外部系统对接关系

| 对接方（调用方） | 典型短信场景                    |
| ---------------- | ------------------------------- |
| 健康管理（08）   | 体征危急值告警 → 家属           |
| 安全系统（09）   | SOS/跌倒/走失 → 家属+紧急联系人 |
| 长护险（18）     | 服务完成确认 → 老人/监察员      |
| 审批系统（04）   | 补贴审核结果 → 申请人           |
| 居家养老（10）   | 服务预约确认 → 老人             |
| 医养商城（19）   | 订单发货/物流更新 → 消费者      |
| 系统管理（05）   | 账号注册/密码重置验证码         |

---

## 10. 风险与边界

| 风险              | 说明                                                     | 应对                        |
| ----------------- | -------------------------------------------------------- | --------------------------- |
| 工信部模板审核    | 短信模板需报备审核，周期1-3天                            | 提前规划模板，预留报备时间  |
| 短信费用失控      | 告警类短信量大，费用可能超预期                           | 限流配置 + 每日用量预警     |
| 号码归属地屏蔽    | 某些运营商拦截短信                                       | 多通道备份 + 短信到达率监控 |
| 边界：不含APP推送 | APP推送由各业务模块自行集成极光/腾讯推送，本系统仅做短信 | 明确能力范围                |

---

## 11. 实施优先级与分期建议

**优先级：P1（基础设施，其他模块依赖）**

| 分期             | 内容                                        | 说明                            |
| ---------------- | ------------------------------------------- | ------------------------------- |
| 第一期（P1同步） | 基础短信发送API + 验证码模板 + 阿里云单通道 | 所有P1模块的账号/通知依赖此能力 |
| 第二期           | 模板管理界面 + 优先级队列 + 多通道切换      | —                               |
| 第三期           | 用量统计報表 + 限流控制 + 黑名单管理        | —                               |

---

## 12. 结论

短信平台是全平台级基础设施，须在P1阶段早期完成基础能力建设，支撑其他模块的通知依赖。

mall 现有分散的短信代码可作为起点参考，但须重新设计为**独立微服务架构**，提供统一API入口，实现多通道管理、优先级调度和合规管控，避免27个模块各自维护短信代码的维护灾难。