简要说明本仓库中与 SMS 发送相关的使用、配置与开发说明（面向开发者）。

该项目是一个小型 Django 应用，包含一个可插拔的 SMS provider 抽象层（integrations/sms）和一个 gateway app，提供以下能力：

• 创建短信发送实例（持久化并返回 sms_id）
• 接收 provider 回调并根据 provider 的 SerialNo 更新发送状态
• 查询发送状态（按 sms_id）

• gateway/models.py — SMSSend 模型，保存发送记录。
• gateway/views.py — DRF 视图：创建发送、接收回调、查询发送状态。
• gateway/services.py — send_sms_via_provider：封装 provider，解析默认值并持久化。
• integrations/sms — provider 抽象及实现示例（mock.py, tencent.py）。
• smsplatform/settings.py — 项目设置，包括 SMS_PROVIDER 和 SMS_PROVIDERS 配置示例。
• gateway/tests.py — 单元测试，包含对默认值解析与完整流程（create -> callback -> status）的测试。

推荐在虚拟环境中运行。项目使用Django 与 Django REST Framework。

示例（PowerShell）：

# 激活虚拟环境（示例）
& .\.venv\Scripts\Activate.ps1

# 安装依赖（如果仓库含 requirements.txt，请优先使用）
python -m pip install -r requirements.txt

项目在 smsplatform/settings.py 中使用：

• SMS_PROVIDER：活动 provider 名称（可由环境变量覆盖）
• SMS_PROVIDERS：provider 配置字典（示例包含 tencent 与 mock）

将敏感信息通过环境变量提供，例如：

$env:TENCENTCLOUD_SECRET_ID = "your-secret-id"
$env:TENCENTCLOUD_SECRET_KEY = "your-secret-key"
$env:TENCENT_SMS_SDK_APP_ID = "1400000000"
$env:SMS_PROVIDER = "tencent"

基础路径：/gateway/

• 方法：POST

• URL：/gateway/sends/

• 请求 JSON 字段：

  • phone_numbers（必需）：字符串列表，例如 ["+8613711112222"]。
  • template_params（必需，可为空列表）：例如 [] 或 ["参数1","参数2"]。
  • template_id（可选）：若不提供，service 会解析 provider config 或 settings。
  • sign_name（可选）
  • sdk_app_id（可选）
  • provider（可选）：覆盖默认 provider 名称

• 返回 JSON 示例：

{ "sms_id": 1, "serial_no": "2025xxxx", "status": "CREATED", "provider_response": {...} }

• 方法：POST
• URL：/gateway/callback/<provider_name>/
• 接收：JSON 数组（每项为 provider 回调对象）
• 行为：根据回调中的 sid/SerialNo/serial_no 匹配 SMSSend.serial_no 更新状态为 SUCCESS 或 FAIL。
• 当回调表明失败（如 report_status == "FAIL"）时，系统会记录一条 WARNING 日志，使用 json.dumps(..., ensure_ascii=False) 保留非 ASCII 内容。

示例回调体：

[ {"mobile":"15802383994","report_status":"FAIL","description":"空号/停机/关机","sid":"99:1274..."} ]

• 方法：GET
• URL：/gateway/sends/<sms_id>/status/
• 返回示例：{ "sms_id": 1, "status": "CREATED|SUCCESS|FAIL" }

• Provider 模块（例如 integrations/sms/tencent.py）必须暴露一个 Provider 类。
• integrations.sms.get_provider(name) 会实例化该 provider，并把 settings.SMS_PROVIDERS.get(name, {}) 作为配置传入。
• provider 实例应保留 self.config，可在 __init__ 中用 self.config.setdefault(...) 提供默认 template_id / sign_name / sms_sdk_app_id。

service (gateway/services.py) 解析默认值的优先级为：

1. 请求显式参数（POST body）
2. provider 实例的 config
3. settings.SMS_PROVIDERS 中的配置

解析后的值会写入 SMSSend 记录，方便后续查询与审计。

项目包含单元测试，覆盖主要流程（创建 -> 回调 -> 查询）以及默认值解析。运行：

python manage.py test