# 短信引擎

**Repository Path**: xbcode-plugin/xbSms

## Basic Information

- **Project Name**: 短信引擎
- **Description**: 基于积木云框架的基础通用短信引擎
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-18
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 插件标题（短信引擎 xbSms）

xbSms 插件是“积木云”开发体系中的 **统一短信引擎**，负责对接各类短信通道插件（如阿里云 `xbSmsAliyun`、腾讯云 `xbSmsTencent`、短信宝 `xbSmsBao` 等），为业务系统提供标准化、可扩展的短信发送与验证码校验能力。

---

## 插件基本介绍

- **插件名称**：短信引擎 (xbSms)
- **功能定位**：统一管理短信通道、发送记录与模板配置的基础引擎插件
- **所属体系**：积木云插件化系统
- **版本信息**：v1.0.0（见 `plugins.json`）
- **开发作者**：积木云

xbSms 作为整个系统短信能力的基础设施插件，不直接绑定某一家短信服务商，而是通过“驱动式设计”把具体通道下沉到子插件中，业务侧始终通过同一套接口完成短信发送和验证码校验。

---

## 主要用途

**统一短信发送入口：**
- 业务模块（如用户注册、登录、找回密码、订单通知等）统一通过 `xbSms` 发起短信发送请求。
- 隐藏不同短信服务商的差异，对上只暴露统一的 API。

- **集中化配置与管理**：
  - 在后台“通用管理 → 短信管理”中统一配置默认短信引擎、通道参数以及模板内容。
  - 提供短信模板、发送记录等管理界面，便于运维和运营人员使用。

- **短信验证码场景支持**：
  - 内置验证码生成与校验逻辑，用于登录、注册、绑定手机、修改密码等常见场景。

- **多通道扩展与切换**：
  - 支持阿里云、腾讯云、短信宝等多种通道，通过配置即可切换默认通道。
  - 支持通过通道插件扩展新的短信服务商。

---

## 核心功能与特点

- **多引擎驱动体系**：
  - 抽象出统一的短信服务基类 `plugin\xbSms\service\Server`。
  - 具体短信通道插件（如 `xbSmsAliyun`、`xbSmsTencent`、`xbSmsBao`）实现各自的 `engine\Driver`，并继承该基类，实现发送逻辑。

- **统一配置中心**：
  - 通过 `plugin\xbCode\api\ConfigApi` 加载 `sms` 配置，对各通道参数进行集中管理。
  - 配合 `config/channels.php` 中的通道列表（如 `aliyun`、`qcloud`、`smsbao`），实现多通道标识管理与映射。

- **模板与场景管理**：
  - 使用短信模板模型与模板 API（如 `TemplateApi`），按“场景标识”管理模板内容与模板 ID。
  - 在发送前自动根据场景加载模板、替换变量，记录发送用到的模板和内容。

- **发送记录与追踪**：
  - 通过 `SmsRecordApi` 在数据库中记录每次发送的引擎、场景、手机号、验证码以及结果状态。
  - 支持在后台“短信记录”中查看历史发送记录、状态与返回结果，便于排查问题。

- **验证码生成与校验**：
  - `plugin\xbSms\api\SmsApi::send()` 内部自动生成验证码（如 4 位数字），并与模板、手机号一起写入记录。
  - `plugin\xbSms\api\SmsApi::check()` 提供验证码校验能力，验证发送状态、验证码是否匹配等。

- **业务解耦与可插拔设计**：
  - 业务方只依赖 `xbSms` 的统一接口，不直接依赖具体短信服务商 SDK。
  - 新增短信通道只需编写对应插件并实现驱动类，即可接入现有引擎与业务流程。

---

## 目录结构简述

xbSms 插件主要目录结构如下（节选）：

- **`api/`**：
  - `SmsApi.php`：统一短信发送与验证码校验的内部接口。
  - `SmsRecordApi.php`：短信发送记录操作封装。
  - `TemplateApi.php`：短信模板管理接口。
  - `EngineApi.php`：短信引擎配置与管理相关接口。
  - `Install.php`：插件安装与初始化逻辑（如注册引擎、初始化数据等）。

- **`app/`**：
  - `app/api/controller/SmsController.php`：对外开放的短信 API 控制器，提供无需登录和登录用户两类发送接口。
  - 其他 admin 控制器与模型，用于“短信配置”、“短信模板”、“短信记录”等后台管理页面。

- **`service/`**：
  - `Server.php`：短信服务抽象基类，封装模板加载、参数替换、配置注入等公共逻辑。
  - `Driver.php`：短信驱动调度类，从配置中解析当前引擎与插件，实例化具体通道插件的 `engine\Driver`。

- **`config/`**：
  - `menu.php`：在后台“通用管理 → 短信管理”中挂载短信配置、模板、记录等菜单。
  - `channels.php`：通道列表配置（如阿里云、腾讯云、短信宝等）。
  - 其他如 `app.php`、`tpl.php`、`translation.php` 等为插件运行与后台渲染提供基础配置。

- **`data/` / `enum/` / `setting/` / `public/`**：
  - 存放插件默认数据、枚举、可视化配置表单与前端资源，配合“积木云”后台动态表单与页面渲染使用。

---

## 对外接口与调用方式

### 1. PHP 内部调用

在业务代码或其他插件中，可以通过 `SmsApi` 统一发送短信：

```php
use plugin\xbSms\api\SmsApi;

// 发送短信验证码（示例：登录场景）
SmsApi::make()->send(
    name: 'login',          // 模板/场景标识
    mobile: '13800138000',  // 手机号码
    uid: 1,                 // 用户ID（可选）
    engine: null            // 短信引擎标识（可选，null 时使用默认引擎）
);

// 校验短信验证码
$isValid = SmsApi::make()->check(
    name: 'login',          // 模板/场景标识
    mobile: '13800138000',  // 手机号码
    code: 1234              // 用户输入的验证码
);
```

- **验证码生成**：由 `SmsApi::send()` 自动生成并写入记录。
- **引擎选择**：
  - 若未显式传入 `$engine`，则使用配置中设置的默认短信引擎。
  - 若传入具体引擎标识（如 `aliyun`、`qcloud`、`smsbao`），则优先使用指定通道。

### 2. HTTP API 接口

xbSms 提供了标准的 HTTP 接口，供前端或第三方应用调用。

#### 2.1 无需登录发送短信

- **接口地址**：`POST /api/sms/send`
- **说明**：适用于注册、登录等无需用户登录的场景。

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `scene` | string | 是 | 场景标识（如：`login`、`register` 等） |
| `mobile` | string | 是 | 手机号码 |
| `engine` | string | 否 | 短信引擎标识（为空时使用系统默认引擎） |

#### 2.2 用户发送短信（需要登录）

- **接口地址**：`POST /api/sms/userSend`
- **说明**：适用于需要登录后才能发送短信的场景（如绑定手机、修改手机等）。

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `scene` | string | 是 | 场景标识 |
| `mobile` | string | 是 | 手机号码 |
| `engine` | string | 否 | 短信引擎标识（为空时使用系统默认引擎） |

> 接口实现位于 `plugin\xbSms\app\api\controller\SmsController` 中，并通过 `SmsApi` 完成实际发送逻辑。

---

## 在系统中的作用与与其他模块的关系

- **与短信通道插件的关系**：
  - `xbSms` 作为“短信引擎”，负责加载配置、分发请求、记录日志和校验验证码。
  - `xbSmsAliyun`、`xbSmsTencent`、`xbSmsBao` 等插件作为“具体通道驱动”，只关注与各自平台的 API 通信。

- **与业务模块的关系**：
  - 业务模块（如 `xbUser`、订单、营销等）统一调用 `xbSms` 的接口发起短信请求。
  - 通过引擎与驱动分层，实现业务逻辑与具体短信服务商之间的完全解耦，方便后续替换或新增通道。

- **在“积木云”体系中的角色**：
  - 作为基础能力插件，为整个平台提供标准化的短信服务能力。
  - 配合动态表单渲染、菜单配置以及插件化管理机制，确保短信能力可视化配置、可插拔扩展、易于维护。

---

## 特点小结

- **统一入口**：一套 API 覆盖多家短信服务商，业务无需关心底层实现差异。
- **驱动式扩展**：通过插件与驱动机制扩展新通道，升级与维护成本低。
- **完善的管理后台**：内置短信配置、模板管理、发送记录查看等功能。
- **安全与可控**：支持验证码校验与发送记录追踪，便于风控与审计。
- **深度集成“积木云”体系**：与现有插件化框架、动态表单渲染、配置中心无缝结合。