diff --git a/README.md b/README.md new file mode 100644 index 0000000..5a6ed1a --- /dev/null +++ b/README.md @@ -0,0 +1,254 @@ +# 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()) +``` + +## 依赖 + +- Python 3.9+ +- baidubce (百度云 BCE SDK) +- aiohttp +- sqlor (数据库操作) +- appPublic +- ahserver + +## 百度短信文档 + +详细接口说明请参考:[百度短信服务文档](https://cloud.baidu.com/doc/SMS/s/zjwvxry6e) diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..32519d2 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,23 @@ +[build-system] +requires = ["setuptools>=61.0"] +build-backend = "setuptools.build_meta" + +[project] +name = "smssend" +version = "0.1.0" +description = "a module to build and run sms send" +authors = [ + { name="Your Name", email="you@example.com" } +] +readme = "README.md" +requires-python = ">=3.10" +dependencies = [ + "bce-python-sdk==0.9.35", + "ahserver", + "appPublic", + "sqlor" +] + +[tool.setuptools] +# 明确告诉它只包含 skillagent 目录 +packages = ["smssend"] diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 66e4e9f..0000000 Binary files a/requirements.txt and /dev/null differ