smssend/README.md

# SMS Send Module

短信发送模块，基于百度云短信服务实现验证码生成、校验和短信发送功能。

## 功能特性

- 百度短信发送
- 验证码生成与验证
- 配置从环境变量读取

## 环境配置

使用本模块前，需要配置以下环境变量：

| 环境变量 | 说明 |
|---------|------|
| `BAIDU_SMS_ACCESS_KEY` | 百度云 access key |
| `BAIDU_SMS_ACCESS_KEY_SECRET` | 百度云 access key secret |
| `BAIDU_SMS_HOST` | 百度短信服务 endpoint |
| `BAIDU_SMS_SIGNATURE_ID` | 短信签名 ID |

## 数据库创建

```mysql
CREATE TABLE `sms_template` (
  `id` varchar(32) NOT NULL COMMENT 'id',
  `name` varchar(32) DEFAULT NULL COMMENT '模板名称',
  `template_type` varchar(32) DEFAULT NULL COMMENT '模板类型',
  `code` varchar(32) DEFAULT NULL COMMENT '模板编码',
  `content` varchar(200) DEFAULT NULL COMMENT '模板内容',
  `description` varchar(100) DEFAULT NULL COMMENT '场景说明',
  `provider` varchar(100) DEFAULT NULL COMMENT '短信供应商名称',
  `del_flg` varchar(1) DEFAULT '0' COMMENT '删除标志',
  `create_at` timestamp NULL DEFAULT current_timestamp() COMMENT '创建时间戳',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3 COLLATE=utf8mb3_general_ci ROW_FORMAT=DYNAMIC COMMENT='短信模板表';

CREATE TABLE `validatecode` (
  `id` varchar(32) NOT NULL COMMENT 'id',
  `vcode` varchar(32) DEFAULT NULL COMMENT '验证码',
  `expire_time` timestamp NOT NULL DEFAULT current_timestamp() COMMENT '有效期',
  `del_flg` varchar(1) DEFAULT '0' COMMENT '删除标志',
  `create_at` timestamp NOT NULL DEFAULT current_timestamp() COMMENT '创建时间戳',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3 COLLATE=utf8mb3_general_ci ROW_FORMAT=DYNAMIC COMMENT='验证码表';

CREATE TABLE `sms_record` (
  `id` varchar(32) NOT NULL COMMENT 'id',
  `customerid` varchar(32) DEFAULT NULL COMMENT '客户id',
  `send_type` varchar(32) DEFAULT NULL COMMENT '发送类型',
  `mobile` varchar(15) DEFAULT NULL COMMENT '手机号',
  `email` varchar(32) DEFAULT NULL COMMENT '邮箱',
  `message` varchar(510) DEFAULT NULL COMMENT '发送内容',
  `send_time` varchar(32) DEFAULT NULL COMMENT '发送时间',
  `send_status` varchar(1) DEFAULT NULL COMMENT '发送状态',
  `task_status` varchar(2) DEFAULT NULL COMMENT '任务状态 1:待发送,2:待定时发送,11:发送MQ成功,12:MQ消费成功,21:请求成功,22:请求失败,31:取消发送',
  `remark` varchar(200) DEFAULT NULL COMMENT '发送失败备注信息',
  `del_flg` varchar(1) DEFAULT NULL COMMENT '删除标志',
  `create_at` timestamp NULL DEFAULT current_timestamp() COMMENT '创建时间戳',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb3 COLLATE=utf8mb3_general_ci ROW_FORMAT=DYNAMIC COMMENT='短信邮箱记录表';
```



## 核心接口

### 1. load_smssend()

初始化加载短信模块，将功能注册到 ServerEnv。

```python
from smssend import load_smssend

load_smssend()
```

### 2. send_sms(phone: str, stype: str)

发送短信（整合生成验证码和发送功能）。

**参数：**

- `phone`: 接收手机号
- `stype`: 短信模板类型

**返回值：**

```python
# 发送成功
{
    'status': 'ok',
    'data': {
        'codeid': 'xxx'  # 验证码ID
    }
}

# 发送失败
{
    'status': 'error',
    'data': {
        'message': '错误信息'
    }
}
```

**示例：**

```python
from smssend import send_sms

result = await send_sms(phone='13800138000', stype='用户注册登录验证')
if result.get('status') == 'ok':
    code_id = result['data']['codeid']
    print(f"发送成功，验证码ID: {code_id}")
```

### 3. check_sms_code(code_id: str, vcode: str)

校验短信验证码。

**参数：**
- `code_id`: 验证码的唯一标识
- `vcode`: 用户输入的验证码

**返回值：**
- 验证成功返回 `True`，验证失败返回 `False`
- 验证码正确且未过期时验证通过，验证后自动标记为已使用

**示例：**
```python
from smssend import check_sms_code

is_valid = await check_sms_code(code_id='xxx', vcode='123456')
if is_valid:
    print("验证通过")
else:
    print("验证失败")
```

### 6. get_sms_engine()

获取 SMSEngine 单例实例。

**返回值：**
- 返回 `SMSEngine` 对象

**示例：**
```python
from smssend import get_sms_engine

engine = get_sms_engine()
```

## SMSEngine 类

核心引擎类，提供底层短信操作能力。

### 方法

| 方法 | 说明 |
|------|------|
| `send(stype, template_id, phone, params)` | 发送短信 |
| `send_vcode(phone, stype, vcode)` | 发送验证码短信 |
| `generate_sms_code(length, expire_minutes)` | 生成验证码 |
| `check_sms_code(code_id, vcode)` | 校验验证码 |
| `send_sms(phone, stype)` | 发送短信（整合功能） |

## 数据模型

### sms_template - 短信模板表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | str | 主键 |
| name | str | 模板名称 |
| template_type | str | 模板类型 |
| code | str | 模板CODE（百度云模板ID） |
| content | str | 模板内容 |
| description | str | 描述 |
| provider | str | 供应商 |
| del_flg | str | 删除标志 |
| create_at | timestamp | 创建时间 |

### validatecode - 验证码表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | str | 主键（code_id） |
| vcode | str | 验证码 |
| expire_time | timestamp | 过期时间 |
| del_flg | str | 删除标志（0:未使用, 1:已使用） |
| create_at | timestamp | 创建时间 |

### sms_record - 短信记录表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | str | 主键 |
| customerid | str | 客户ID |
| send_type | str | 发送类型 |
| mobile | str | 手机号 |
| email | str | 邮箱 |
| message | str | 消息内容 |
| send_time | str | 发送时间 |
| send_status | str | 发送状态（0:失败, 1:成功） |
| task_status | str | 任务状态 |
| remark | str | 备注 |
| del_flg | str | 删除标志 |
| create_at | timestamp | 创建时间 |

## 使用示例

```python
import asyncio
from smssend import load_smssend, send_sms, check_sms_code

async def main():
    # 1. 初始化模块
    load_smssend()
    
    # 2. 发送短信
    result = await send_sms(phone='13800138000', stype='注册登录')
    
    if result.get('status') == 'ok':
        code_id = result['data']['codeid']
        print(f"验证码已发送到手机，验证码ID: {code_id}")
        
        # 3. 假设用户输入了验证码 '123456'
        is_valid = await check_sms_code(code_id=code_id, vcode='123456')
        
        if is_valid:
            print("验证码校验通过")
        else:
            print("验证码错误或已过期")
    else:
        print(f"发送失败: {result.get('data', {}).get('message')}")

if __name__ == '__main__':
    asyncio.run(main())
```

## 初始化种子数据（sms_template 模板）

模块自带模板种子脚本，**部署到新环境后必须执行**（否则 `sms_template` 为空，
发送验证码时写流水 `remark='未找到模板类型: xxx'` 并返回失败）：

```bash
cd <宿主应用根目录> && py3/bin/python pkgs/smssend/scripts/import_init_smssend.py
```

- 幂等：`INSERT IGNORE` 按主键 id，可重复执行；表不存在时自动按 DDL 建表。
- 内容：10 条有效模板（del_flg='0'），源自 sage 平台老库，含注册验证码模板
  「用户注册登录验证」(`sms-tmpl-QENKGX81807`，模板变量 `${SMSvCode}`)、
  欠费/续费/余额不足等业务通知模板、百度 kafka 透传模板。
- 模板 `code` 是百度云 template_id，**与百度短信账号绑定**——更换短信账号或签名后
  须在百度云重建模板并同步更新脚本中的 code。
- 数据库连接取自宿主 `conf/config.json` 的 `databases.pipeline`（密码 AES 解密），
  与宿主应用其余模块一致。

## 依赖

- Python 3.9+
- baidubce (百度云 BCE SDK)
- aiohttp
- sqlor (数据库操作)
- appPublic
- ahserver

## 百度短信文档

详细接口说明请参考：[百度短信服务文档](https://cloud.baidu.com/doc/SMS/s/zjwvxry6e)