update

2026-03-19 18:28:51 +08:00 · 2026-03-19 18:28:51 +08:00 · 9780d81b0c
commit 9780d81b0c
parent 7d127c873c
3 changed files with 277 additions and 0 deletions
--- a/README.md
+++ 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)
--- a/pyproject.toml
+++ 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"]
--- a/requirements.txt
+++ b/requirements.txt