Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 unknown
|
6706f76645 |
+2
-28
@@ -81,38 +81,12 @@ HEARTBEAT_TIMEOUT_MINUTES=60
|
||||
HEARTBEAT_SCAN_INTERVAL_SEC=60
|
||||
|
||||
# ===== 短信 (mock 模式) =====
|
||||
# mock = true 时,任意 6 位数字均通过,且 /sms/send 不真发短信(只 log)。生产改 false。
|
||||
# mock = true 时,任意 6 位数字均通过,且 /sms/send 不真发短信(只 log)。
|
||||
# 后续接阿里云/腾讯云短信时,改成 false 并填供应商相关 key。
|
||||
SMS_MOCK=true
|
||||
SMS_CODE_TTL_SEC=300
|
||||
SMS_SEND_INTERVAL_SEC=60
|
||||
|
||||
# ===== 短信提供商(可切换:jiguang 默认 / aliyun 阿里云号码认证 / chuanglan 创蓝云智)=====
|
||||
# jiguang :本服务生成验证码,极光 REST 只负责下发,本地内存校验(复用上面极光 JG_* 凭证)。
|
||||
# aliyun :阿里云 dypns 号码认证,阿里云生成+下发+校验(Mode A,核验免费);缺凭证时 /sms/* 返 503。
|
||||
# 需在阿里云号码认证控制台开通「融合认证」,并使用系统赠送签名 + 赠送模板。
|
||||
# chuanglan:创蓝云智(253)模板短信,本服务生成码、创蓝只下发、本地校验(Mode B,与极光同);缺凭证 503。
|
||||
# 用 YZM 前缀验证码账号;服务器出网 IP 需在创蓝控制台加白名单(否则 117)。见 docs/integrations/chuanglan/tpl-send.md。
|
||||
SMS_PROVIDER=jiguang
|
||||
ALIYUN_SMS_ACCESS_KEY_ID=
|
||||
ALIYUN_SMS_ACCESS_KEY_SECRET=
|
||||
ALIYUN_SMS_SIGN_NAME=
|
||||
ALIYUN_SMS_TEMPLATE_CODE=
|
||||
# 方案名:留空=默认方案;若填,发码与校验须一致(本服务已共用同一配置项,不会不匹配)。
|
||||
ALIYUN_SMS_SCHEME_NAME=
|
||||
ALIYUN_SMS_ENDPOINT=dypnsapi.aliyuncs.com
|
||||
ALIYUN_SMS_CODE_LENGTH=6
|
||||
ALIYUN_SMS_VALID_TIME_SEC=300
|
||||
ALIYUN_SMS_INTERVAL_SEC=60
|
||||
ALIYUN_SMS_TIMEOUT_SEC=15
|
||||
# --- 创蓝云智(253)---
|
||||
CHUANGLAN_SMS_ACCOUNT=
|
||||
CHUANGLAN_SMS_PASSWORD=
|
||||
CHUANGLAN_SMS_TEMPLATE_ID=1022457679
|
||||
# 短信签名文案【品牌】;模板已关联签名则留空。
|
||||
CHUANGLAN_SMS_SIGNATURE=
|
||||
CHUANGLAN_SMS_ENDPOINT=https://smssh.253.com/msg/sms/v2/tpl/send
|
||||
CHUANGLAN_SMS_TIMEOUT_SEC=10
|
||||
|
||||
# ===== 测试账号(release 包全流程联调用)=====
|
||||
# 配一个固定测试手机号,专供无 SIM 卡 / 不走一键登录时打通全流程:该号登录【免短信验证码】
|
||||
# (real 模式下也跳过校验)、每次登录【都重走新手引导】,并有【每日登录上限】防被人猜到号后脚本刷。
|
||||
|
||||
@@ -9,7 +9,7 @@ from datetime import date, datetime, time, timedelta, timezone
|
||||
from decimal import ROUND_HALF_UP, Decimal
|
||||
from zoneinfo import ZoneInfo
|
||||
|
||||
from sqlalchemy import Select, asc, case, desc, func, or_, select
|
||||
from sqlalchemy import Select, and_, asc, case, desc, func, or_, select
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.core import rewards
|
||||
@@ -45,6 +45,72 @@ _FEED_SCENE_LABEL = {
|
||||
}
|
||||
|
||||
|
||||
_DEVICE_MARKETING_NAMES = {
|
||||
"23078RKD5C": "Redmi K60 至尊版",
|
||||
"M2012K11AC": "Redmi K40",
|
||||
"PJA110": "一加 Ace 2 Pro",
|
||||
"PPG-AN00": "荣耀 GT Pro",
|
||||
"V2166BA": "vivo Y77e",
|
||||
"V2309A": "vivo X100",
|
||||
}
|
||||
|
||||
|
||||
def _device_marketing_name(model: str | None) -> str | None:
|
||||
"""把线上已知 Build.MODEL 编码转成用户可识别的商品名。"""
|
||||
if not model:
|
||||
return None
|
||||
return _DEVICE_MARKETING_NAMES.get(model.strip().upper())
|
||||
|
||||
|
||||
def _attach_feedback_device_details(db: Session, feedbacks: list[Feedback]) -> None:
|
||||
"""按同一用户、同一设备编码及提交时间补齐厂商和 ROM 大版本。"""
|
||||
candidates = [
|
||||
item for item in feedbacks if item.device_model and item.device_model.strip()
|
||||
]
|
||||
for item in candidates:
|
||||
item.device_model_name = _device_marketing_name(item.device_model)
|
||||
item.device_manufacturer = None
|
||||
item.rom_version = None
|
||||
if not candidates:
|
||||
return
|
||||
|
||||
ranked = (
|
||||
select(
|
||||
Feedback.id.label("feedback_id"),
|
||||
ComparisonRecord.device_manufacturer.label("device_manufacturer"),
|
||||
ComparisonRecord.rom_version.label("rom_version"),
|
||||
func.row_number()
|
||||
.over(
|
||||
partition_by=Feedback.id,
|
||||
order_by=(
|
||||
ComparisonRecord.created_at.desc(),
|
||||
ComparisonRecord.id.desc(),
|
||||
),
|
||||
)
|
||||
.label("row_num"),
|
||||
)
|
||||
.join(
|
||||
ComparisonRecord,
|
||||
and_(
|
||||
ComparisonRecord.user_id == Feedback.user_id,
|
||||
ComparisonRecord.device_model == Feedback.device_model,
|
||||
ComparisonRecord.created_at <= Feedback.created_at,
|
||||
),
|
||||
)
|
||||
.where(Feedback.id.in_([item.id for item in candidates]))
|
||||
.subquery()
|
||||
)
|
||||
details = {
|
||||
row.feedback_id: row
|
||||
for row in db.execute(select(ranked).where(ranked.c.row_num == 1)).all()
|
||||
}
|
||||
|
||||
for item in candidates:
|
||||
detail = details.get(item.id)
|
||||
item.device_manufacturer = detail.device_manufacturer if detail else None
|
||||
item.rom_version = detail.rom_version if detail else None
|
||||
|
||||
|
||||
def cursor_paginate(
|
||||
db: Session, stmt: Select, id_col, *, limit: int, cursor: int | None
|
||||
) -> tuple[list, int | None]:
|
||||
@@ -817,6 +883,7 @@ def list_feedbacks(
|
||||
db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor
|
||||
)
|
||||
_attach_user_info(db, items) # 列表展示完整手机号(点手机号查该用户全部反馈)
|
||||
_attach_feedback_device_details(db, items)
|
||||
return items, next_cursor, total
|
||||
|
||||
|
||||
|
||||
@@ -32,7 +32,10 @@ class FeedbackOut(BaseModel):
|
||||
# 提交端环境快照(feedback 表列):提交版本号 / 机型OS版本;改版前的历史反馈为 None
|
||||
app_version: str | None = None
|
||||
device_model: str | None = None
|
||||
device_model_name: str | None = None
|
||||
device_manufacturer: str | None = None
|
||||
rom_name: str | None = None
|
||||
rom_version: int | None = None
|
||||
android_version: str | None = None
|
||||
# 联表瞬态字段(queries._attach_user_info 挂):列表展示完整手机号,点手机号查该用户全部反馈
|
||||
phone: str | None = None
|
||||
|
||||
+2
-11
@@ -292,12 +292,7 @@ def sms_login(req: SmsLoginRequest, request: Request, db: DbSession) -> TokenWit
|
||||
detail="登录尝试过于频繁,请稍后再试",
|
||||
)
|
||||
|
||||
try:
|
||||
ok = verify_code(req.phone, req.code)
|
||||
except SmsError as e: # provider 校验降级(如阿里云接口异常)→ 原样透出其状态码(503),别误报「验证码错误」
|
||||
raise HTTPException(status_code=e.status_code, detail=str(e)) from e
|
||||
if not ok:
|
||||
# 校验码错误才记风控失败事件(provider 降级 503 已在上面提前 raise,不算「验证失败」)
|
||||
if not verify_code(req.phone, req.code):
|
||||
risk_repo.record_behavior_event(
|
||||
db,
|
||||
event_type=risk_repo.EVENT_SMS_LOGIN,
|
||||
@@ -461,11 +456,7 @@ def wechat_bind_phone_sms(
|
||||
detail="登录尝试过于频繁,请稍后再试",
|
||||
)
|
||||
|
||||
try:
|
||||
ok = verify_code(req.phone, req.code)
|
||||
except SmsError as e: # provider 校验降级(如阿里云接口异常)→ 原样透出其状态码(503),别误报「验证码错误」
|
||||
raise HTTPException(status_code=e.status_code, detail=str(e)) from e
|
||||
if not ok:
|
||||
if not verify_code(req.phone, req.code):
|
||||
raise HTTPException(status_code=400, detail="invalid sms code")
|
||||
|
||||
return _finish_wechat_bind(
|
||||
|
||||
@@ -141,49 +141,6 @@ class Settings(BaseSettings):
|
||||
SMS_DAILY_LIMIT_PER_PHONE: int = 10 # 单手机号每日发送上限(防刷 + 控费)
|
||||
SMS_MAX_VERIFY_ATTEMPTS: int = 5 # 单个验证码最多校验失败次数,超过即作废(防爆破)
|
||||
|
||||
# ===== 短信提供商(可切换:极光 / 阿里云号码认证 / 创蓝云智)=====
|
||||
# jiguang(默认):本服务生成验证码,极光只负责下发,本地内存校验(自管码,现状不变)。
|
||||
# aliyun:阿里云 dypns 号码认证,阿里云生成+下发+校验(Mode A);缺凭证时 /sms/* 返 503(优雅降级)。
|
||||
# chuanglan:创蓝云智(253)模板短信,本服务生成码、创蓝只下发、本地校验(Mode B,与极光同);缺凭证 503。
|
||||
SMS_PROVIDER: Literal["jiguang", "aliyun", "chuanglan"] = "jiguang"
|
||||
ALIYUN_SMS_ACCESS_KEY_ID: str = ""
|
||||
ALIYUN_SMS_ACCESS_KEY_SECRET: str = ""
|
||||
ALIYUN_SMS_SIGN_NAME: str = "" # 系统赠送签名(自定义签名下发易失败)
|
||||
ALIYUN_SMS_TEMPLATE_CODE: str = "" # 赠送模板 CODE(须与赠送签名搭配)
|
||||
ALIYUN_SMS_SCHEME_NAME: str = "" # 方案名(可空=默认方案);send/check 共用避免不匹配
|
||||
ALIYUN_SMS_ENDPOINT: str = "dypnsapi.aliyuncs.com"
|
||||
ALIYUN_SMS_CODE_LENGTH: int = 6 # 验证码位数(CodeLength 4~8)
|
||||
ALIYUN_SMS_VALID_TIME_SEC: int = 300 # 验证码有效期秒(ValidTime);短信内 min 文案 = //60
|
||||
ALIYUN_SMS_INTERVAL_SEC: int = 60 # 单号发送频控秒(Interval);核验免费
|
||||
ALIYUN_SMS_TIMEOUT_SEC: int = 15 # 阿里云 API 读/连超时秒
|
||||
|
||||
# --- 创蓝云智(253)模板短信,Mode B 自管码,httpx 直连 + HMAC 签名(见 docs/integrations/chuanglan/tpl-send.md)---
|
||||
CHUANGLAN_SMS_ACCOUNT: str = "" # YZM 前缀验证码账号
|
||||
CHUANGLAN_SMS_PASSWORD: str = "" # API 密码(仅用于本地算 HMAC 签名,不随请求上行)
|
||||
CHUANGLAN_SMS_TEMPLATE_ID: str = "" # 模板 ID(控制台创建)
|
||||
CHUANGLAN_SMS_SIGNATURE: str = "" # 短信签名文案【品牌】;模板已关联签名则留空
|
||||
CHUANGLAN_SMS_ENDPOINT: str = "https://smssh.253.com/msg/sms/v2/tpl/send"
|
||||
CHUANGLAN_SMS_TIMEOUT_SEC: int = 10 # httpx 读/连超时秒
|
||||
|
||||
@property
|
||||
def aliyun_sms_configured(self) -> bool:
|
||||
"""阿里云短信凭证齐全(缺则 SMS_PROVIDER=aliyun 时 /sms/* 返 503,而非启动崩)。"""
|
||||
return bool(
|
||||
self.ALIYUN_SMS_ACCESS_KEY_ID
|
||||
and self.ALIYUN_SMS_ACCESS_KEY_SECRET
|
||||
and self.ALIYUN_SMS_SIGN_NAME
|
||||
and self.ALIYUN_SMS_TEMPLATE_CODE
|
||||
)
|
||||
|
||||
@property
|
||||
def chuanglan_sms_configured(self) -> bool:
|
||||
"""创蓝短信凭证齐全(缺则 SMS_PROVIDER=chuanglan 时 /sms/send 返 503,而非启动崩)。"""
|
||||
return bool(
|
||||
self.CHUANGLAN_SMS_ACCOUNT
|
||||
and self.CHUANGLAN_SMS_PASSWORD
|
||||
and self.CHUANGLAN_SMS_TEMPLATE_ID
|
||||
)
|
||||
|
||||
# ===== 测试账号(release 包全流程联调用)=====
|
||||
# 配一个固定测试手机号,专供无 SIM 卡 / 不走一键登录时打通全流程:该号登录【免短信验证码】
|
||||
# (real 模式下也跳过校验)、每次登录【强制重走新手引导】,并设【每日使用次数上限】防被人
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
"""极光短信 provider(自管码 Mode B)。
|
||||
"""短信验证码服务。
|
||||
|
||||
两种运行模式由 `SMS_MOCK` 切换:
|
||||
- **mock**(开发/测试,默认):不真发短信,验证码打到日志;校验**放行任意 N 位数字**
|
||||
(测试/开发便利)。真实校验逻辑(比对存码 / 一次性 / 防爆破)由 real 分支 + 单测覆盖。
|
||||
- **real**(生产 `SMS_MOCK=false` 且 `SMS_PROVIDER=jiguang`):本服务生成 N 位验证码 → 调极光
|
||||
短信 REST `/v1/messages` 发送(自定义验证码模式,极光只负责发,code 由本服务生成/保管/
|
||||
- **real**(生产 `SMS_MOCK=false`):本服务生成 N 位验证码 → 调极光短信 REST
|
||||
`/v1/messages` 发送(自定义验证码模式,极光只负责发,code 由本服务生成/保管/
|
||||
校验)→ 鉴权复用极光一键登录的 `JG_APP_KEY`/`JG_MASTER_SECRET`(同一极光应用)。
|
||||
|
||||
验证码存储:**进程内存**(单 worker uvicorn 够用)。重启丢失(用户重发即可)。多
|
||||
worker / 多机时内存不共享 → 冷却、校验都会失效,届时迁移到 DB/Redis(或改用 aliyun provider,
|
||||
其验证码由阿里云托管、无本地存码)。见 docs/待办与技术债.md。
|
||||
worker / 多机时内存不共享 → 冷却、校验都会失效,届时迁移到 DB/Redis。
|
||||
见 docs/待办与技术债.md。
|
||||
|
||||
防刷两层(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权):
|
||||
1. 单号 `SMS_SEND_INTERVAL_SEC` 冷却(本文件)
|
||||
@@ -34,9 +34,17 @@ import httpx
|
||||
|
||||
from app.core.config import settings
|
||||
|
||||
from .base import SmsError, mock_verify
|
||||
logger = logging.getLogger("shagua.sms")
|
||||
|
||||
logger = logging.getLogger("shagua.sms.jiguang")
|
||||
|
||||
class SmsError(Exception):
|
||||
"""业务异常。`status_code` 决定 api 层翻成哪个 HTTP 码:
|
||||
过频/每日超限 = 429(客户端等会再来),供应商不可用 = 503,手机号无效 = 400。
|
||||
"""
|
||||
|
||||
def __init__(self, message: str, status_code: int = 429) -> None:
|
||||
super().__init__(message)
|
||||
self.status_code = status_code
|
||||
|
||||
|
||||
@dataclass
|
||||
@@ -118,7 +126,7 @@ def verify_code(phone: str, code: str) -> bool:
|
||||
- **real 模式**:比对本服务存的码,匹配即作废(一次性);失败累计到上限也作废(防爆破)。
|
||||
"""
|
||||
if settings.SMS_MOCK:
|
||||
ok = mock_verify(code)
|
||||
ok = len(code) == settings.SMS_CODE_LENGTH and code.isdigit()
|
||||
logger.info("[SMS-MOCK] verify %s for %s****", "ok" if ok else "fail", phone[:3])
|
||||
return ok
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
"""短信验证码服务 —— provider 分派入口。
|
||||
|
||||
对外只暴露 `send_code` / `verify_code` / `SmsError`,api 层无需关心用哪个 provider。
|
||||
provider 由 `settings.SMS_PROVIDER` 选择(**每次调用读取**,支持运行时切换 + 灰度回退):
|
||||
- `jiguang`(默认):自管码(本服务生成、内存存/校验,极光只发)。见 [jiguang.py](jiguang.py)。
|
||||
- `aliyun`:阿里云号码认证(阿里云生成+下发+校验,Mode A)。见 [aliyun.py](aliyun.py)。
|
||||
- `chuanglan`:创蓝云智(253)模板短信,自管码 Mode B(本服务生成、内存存/校验,创蓝只发)。见 [chuanglan.py](chuanglan.py)。
|
||||
|
||||
mock(`SMS_MOCK=true`)与各 provider 的行为差异都封在 provider 内部;本层只做路由。
|
||||
拆包前本模块是单文件 `sms.py`;拆包后极光逻辑迁入 `jiguang` 子模块,行为零改动。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from app.core.config import settings
|
||||
|
||||
from . import aliyun, chuanglan, jiguang
|
||||
from .base import SmsError
|
||||
|
||||
__all__ = ["SmsError", "send_code", "verify_code"]
|
||||
|
||||
# provider 名 -> 模块;未知/缺省值回退 jiguang(默认兜底,防误配把登录打挂)。
|
||||
_PROVIDERS = {"aliyun": aliyun, "chuanglan": chuanglan}
|
||||
|
||||
|
||||
def _provider():
|
||||
"""按配置选 provider 模块(每次调用读 settings,支持运行时切换 / 测试注入)。"""
|
||||
return _PROVIDERS.get(settings.SMS_PROVIDER, jiguang)
|
||||
|
||||
|
||||
def send_code(phone: str) -> int:
|
||||
"""发送验证码,返回距下次可发的冷却秒数;失败抛 SmsError。委托给当前 provider。"""
|
||||
return _provider().send_code(phone)
|
||||
|
||||
|
||||
def verify_code(phone: str, code: str) -> bool:
|
||||
"""校验验证码,返回是否通过;provider 异常降级抛 SmsError。委托给当前 provider。"""
|
||||
return _provider().verify_code(phone, code)
|
||||
@@ -1,193 +0,0 @@
|
||||
"""阿里云号码认证(dypns)短信 provider —— Mode A(阿里云托管验证码)。
|
||||
|
||||
与极光(自管码)最大不同:**本服务不生成/不存储验证码**,验证码由阿里云生成+存储+下发+校验。
|
||||
- 发码:调 SendSmsVerifyCode,TemplateParam 用 `{"code":"##code##","min":...}` 占位,阿里云生成。
|
||||
- 校验:调 CheckSmsVerifyCode,阿里云返回 PASS / UNKNOWN。核验免费。
|
||||
→ 天然消除极光路径「内存存码、多 worker 不共享」的技术债(发码/校验可落不同 worker,阿里云统一裁决)。
|
||||
|
||||
**唯一本地态**:per-phone 连续失败计数(`_verify_attempts`),用于复刻极光「单码失败
|
||||
`SMS_MAX_VERIFY_ATTEMPTS` 次即作废」的防爆破语义 —— 刻意与极光一致,避免两 provider 行为不同
|
||||
导致排查困惑。其多 worker 降级特性与极光现状同级;另有 API 层登录频控(设备+IP)做硬兜底。
|
||||
|
||||
单号发送频控(冷却)交给阿里云 `Interval` 参数(命中→FREQUENCY_FAIL→429),本地不再维护冷却。
|
||||
|
||||
SDK 交互隔离在 `_call_send` / `_call_check` 两个薄封装(惰性 import + 惰性建 client,仿 wxpay
|
||||
惰性加载),单测 monkeypatch 这两个即可,不触真 SDK / 网络。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import time
|
||||
from threading import Lock
|
||||
|
||||
from app.core.config import settings
|
||||
|
||||
from .base import SmsError, mock_verify
|
||||
|
||||
logger = logging.getLogger("shagua.sms.aliyun")
|
||||
|
||||
# 阿里云路径唯一本地态:per-phone 连续失败次数(与极光同语义,防爆破)。
|
||||
_verify_attempts: dict[str, int] = {} # phone -> 连续失败次数
|
||||
_verify_seen: dict[str, float] = {} # phone -> 最近触碰 epoch(仅供 GC 老化)
|
||||
_lock = Lock()
|
||||
_GC_THRESHOLD = 10000 # 超此阈值,send 时顺手清老于验证码有效期的计数(仿极光 _gc)
|
||||
|
||||
# 发码错误码 → (HTTP 码, 用户提示)。未列出的一律 503(供应商不可用)。
|
||||
_SEND_ERRORS: dict[str, tuple[int, str]] = {
|
||||
"MOBILE_NUMBER_ILLEGAL": (400, "手机号无效"),
|
||||
"BUSINESS_LIMIT_CONTROL": (429, "今日发送次数过多,请明天再试"),
|
||||
"FREQUENCY_FAIL": (429, "发送过于频繁,请稍后再试"),
|
||||
}
|
||||
# 需运维介入的配置/开通类错误:打 critical 日志(融合认证未开通 / 参数非法)。
|
||||
_SEND_CRITICAL_CODES = frozenset({"FUNCTION_NOT_OPENED", "INVALID_PARAMETERS"})
|
||||
|
||||
_client = None # 惰性构建的 SDK client(模块级缓存)
|
||||
|
||||
|
||||
# ============================ 对外:发码 / 校验 ============================
|
||||
|
||||
def send_code(phone: str) -> int:
|
||||
"""发送验证码(阿里云生成+下发)。
|
||||
|
||||
Returns: 距下次可发的秒数(= ALIYUN_SMS_INTERVAL_SEC,冷却由阿里云 Interval 侧执行)。
|
||||
Raises: SmsError(手机号无效 400 / 过频·天级流控 429 / 未配置·未开通·其他 503)。
|
||||
"""
|
||||
if settings.SMS_MOCK:
|
||||
logger.info("[SMS-aliyun-MOCK] to %s**** (不真发)", phone[:3])
|
||||
return settings.ALIYUN_SMS_INTERVAL_SEC
|
||||
if not settings.aliyun_sms_configured:
|
||||
raise SmsError("短信服务未配置(缺阿里云凭证)", status_code=503)
|
||||
|
||||
result = _call_send(phone) # 传输/SDK 异常在内部抛 SmsError(503)
|
||||
|
||||
if result["success"] and result["code"] == "OK":
|
||||
now = time.time()
|
||||
with _lock:
|
||||
_gc(now) # 顺手清老计数(超阈值才扫)
|
||||
_verify_attempts.pop(phone, None) # 新码 = 新失败预算
|
||||
_verify_seen.pop(phone, None)
|
||||
logger.info("[SMS-aliyun] sent to %s****", phone[:3])
|
||||
return settings.ALIYUN_SMS_INTERVAL_SEC
|
||||
|
||||
code = result["code"]
|
||||
logger.error("[SMS-aliyun] send failed code=%s msg=%s", code, result["message"])
|
||||
if code in _SEND_CRITICAL_CODES:
|
||||
logger.critical("[SMS-aliyun] %s —— 需运维处理(融合认证未开通 / 参数非法)", code)
|
||||
status, msg = _SEND_ERRORS.get(code, (503, "短信服务暂不可用,请稍后重试"))
|
||||
raise SmsError(msg, status_code=status)
|
||||
|
||||
|
||||
def verify_code(phone: str, code: str) -> bool:
|
||||
"""校验验证码(阿里云裁决)。
|
||||
|
||||
- **mock**:放行任意 N 位数字(provider 无关,同极光)。
|
||||
- **real**:先查本地失败计数(达上限即本地作废,不调阿里云,与极光一致)→ 调 CheckSmsVerifyCode:
|
||||
PASS 清计数返 True(一次性);UNKNOWN 计数 +1 返 False;接口异常抛 SmsError(503)。
|
||||
"""
|
||||
if settings.SMS_MOCK:
|
||||
ok = mock_verify(code)
|
||||
logger.info("[SMS-aliyun-MOCK] verify %s for %s****", "ok" if ok else "fail", phone[:3])
|
||||
return ok
|
||||
|
||||
# 失败计数是 best-effort:网络调用不持锁(不能锁跨 IO),故并发下同号可能多放行个位数次。
|
||||
# 无碍——API 层登录频控(设备+IP 5/时)是硬上限,阿里云码有效期 + DuplicatePolicy 亦兜底。
|
||||
with _lock:
|
||||
if _verify_attempts.get(phone, 0) >= settings.SMS_MAX_VERIFY_ATTEMPTS:
|
||||
return False # 已作废:保持计数(直到 send_code 重置),与极光「达上限即作废」一致
|
||||
|
||||
result = _call_check(phone, code) # 传输/SDK 异常在内部抛 SmsError(503)
|
||||
|
||||
if not (result["success"] and result["code"] == "OK"):
|
||||
# 接口层失败(非码错):降级 503,别误报「验证码错误」(400),便于区分排查。
|
||||
logger.error("[SMS-aliyun] check failed code=%s msg=%s", result["code"], result["message"])
|
||||
raise SmsError("短信服务暂不可用,请稍后重试", status_code=503)
|
||||
|
||||
if result["verify_result"] == "PASS":
|
||||
with _lock:
|
||||
_verify_attempts.pop(phone, None) # 验过即清(一次性)
|
||||
_verify_seen.pop(phone, None)
|
||||
return True
|
||||
|
||||
# UNKNOWN:码错 / 过期 → 失败计数 +1(累计到上限即作废)
|
||||
with _lock:
|
||||
_verify_attempts[phone] = _verify_attempts.get(phone, 0) + 1
|
||||
_verify_seen[phone] = time.time()
|
||||
return False
|
||||
|
||||
|
||||
def _gc(now: float) -> None:
|
||||
"""超阈值时清理老于验证码有效期的失败计数(码早已在阿里云侧失效,计数无意义)。仅持锁调用。"""
|
||||
if len(_verify_attempts) <= _GC_THRESHOLD:
|
||||
return
|
||||
cutoff = now - settings.ALIYUN_SMS_VALID_TIME_SEC
|
||||
for p in [p for p, ts in _verify_seen.items() if ts < cutoff]:
|
||||
_verify_attempts.pop(p, None)
|
||||
_verify_seen.pop(p, None)
|
||||
|
||||
|
||||
# ============================ SDK 接缝(单测 monkeypatch 这两个)============================
|
||||
|
||||
def _get_client():
|
||||
"""惰性构建 dypns SDK client(仿 wxpay 惰性加载:jiguang-only 部署不加载 alibabacloud)。"""
|
||||
global _client
|
||||
if _client is None:
|
||||
from alibabacloud_dypnsapi20170525.client import Client
|
||||
from alibabacloud_tea_openapi import models as open_api_models
|
||||
|
||||
cfg = open_api_models.Config(
|
||||
access_key_id=settings.ALIYUN_SMS_ACCESS_KEY_ID,
|
||||
access_key_secret=settings.ALIYUN_SMS_ACCESS_KEY_SECRET,
|
||||
read_timeout=settings.ALIYUN_SMS_TIMEOUT_SEC * 1000, # SDK 单位 ms
|
||||
connect_timeout=settings.ALIYUN_SMS_TIMEOUT_SEC * 1000,
|
||||
)
|
||||
cfg.endpoint = settings.ALIYUN_SMS_ENDPOINT
|
||||
_client = Client(cfg)
|
||||
return _client
|
||||
|
||||
|
||||
def _call_send(phone: str) -> dict:
|
||||
"""调 SendSmsVerifyCode。返回归一化 {success, code, message};import/建 client/调用 任一失败抛 SmsError(503)。"""
|
||||
valid_min = max(1, settings.ALIYUN_SMS_VALID_TIME_SEC // 60)
|
||||
template_param = json.dumps({"code": "##code##", "min": str(valid_min)}, ensure_ascii=False)
|
||||
try:
|
||||
# import + 建 req + 调用 全在 try 内:任一 provider 侧失败都归一成 503(保「provider 出问题→503」不变式)
|
||||
from alibabacloud_dypnsapi20170525 import models as dypns_models
|
||||
req = dypns_models.SendSmsVerifyCodeRequest(
|
||||
phone_number=phone,
|
||||
sign_name=settings.ALIYUN_SMS_SIGN_NAME,
|
||||
template_code=settings.ALIYUN_SMS_TEMPLATE_CODE,
|
||||
template_param=template_param,
|
||||
code_length=settings.ALIYUN_SMS_CODE_LENGTH,
|
||||
valid_time=settings.ALIYUN_SMS_VALID_TIME_SEC,
|
||||
interval=settings.ALIYUN_SMS_INTERVAL_SEC,
|
||||
scheme_name=settings.ALIYUN_SMS_SCHEME_NAME or None,
|
||||
)
|
||||
body = _get_client().send_sms_verify_code(req).body
|
||||
except Exception as e:
|
||||
logger.exception("[SMS-aliyun] send_sms_verify_code 调用异常 phone=%s****", phone[:3])
|
||||
raise SmsError("短信服务暂不可用,请稍后重试", status_code=503) from e
|
||||
return {"success": bool(body.success), "code": body.code, "message": body.message}
|
||||
|
||||
|
||||
def _call_check(phone: str, code: str) -> dict:
|
||||
"""调 CheckSmsVerifyCode。返回归一化 {success, code, message, verify_result};import/建 client/调用 任一失败抛 SmsError(503)。"""
|
||||
try:
|
||||
# import + 建 req + 调用 全在 try 内:任一 provider 侧失败都归一成 503(保「provider 出问题→503」不变式)
|
||||
from alibabacloud_dypnsapi20170525 import models as dypns_models
|
||||
req = dypns_models.CheckSmsVerifyCodeRequest(
|
||||
phone_number=phone,
|
||||
verify_code=code,
|
||||
scheme_name=settings.ALIYUN_SMS_SCHEME_NAME or None,
|
||||
)
|
||||
body = _get_client().check_sms_verify_code(req).body
|
||||
except Exception as e:
|
||||
logger.exception("[SMS-aliyun] check_sms_verify_code 调用异常 phone=%s****", phone[:3])
|
||||
raise SmsError("短信服务暂不可用,请稍后重试", status_code=503) from e
|
||||
verify_result = getattr(body.model, "verify_result", None) if body.model else None
|
||||
return {
|
||||
"success": bool(body.success),
|
||||
"code": body.code,
|
||||
"message": body.message,
|
||||
"verify_result": verify_result,
|
||||
}
|
||||
@@ -1,23 +0,0 @@
|
||||
"""短信 provider 共享基座:业务异常 + provider 无关的 mock 校验。
|
||||
|
||||
各 provider(jiguang / aliyun)都 `from .base import SmsError`,api 层也从包入口拿到同一个
|
||||
`SmsError` —— 保证无论用哪个 provider,异常类型与 HTTP 码映射语义一致。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from app.core.config import settings
|
||||
|
||||
|
||||
class SmsError(Exception):
|
||||
"""业务异常。`status_code` 决定 api 层翻成哪个 HTTP 码:
|
||||
过频/每日超限 = 429(客户端等会再来),供应商不可用 = 503,手机号无效 = 400。
|
||||
"""
|
||||
|
||||
def __init__(self, message: str, status_code: int = 429) -> None:
|
||||
super().__init__(message)
|
||||
self.status_code = status_code
|
||||
|
||||
|
||||
def mock_verify(code: str) -> bool:
|
||||
"""mock 模式校验:放行任意 SMS_CODE_LENGTH 位数字(provider 无关,测试/开发便利,不真校验)。"""
|
||||
return len(code) == settings.SMS_CODE_LENGTH and code.isdigit()
|
||||
@@ -1,224 +0,0 @@
|
||||
"""创蓝云智(253)短信 provider(自管码 Mode B)。
|
||||
|
||||
创蓝 `tpl/send` v2 是**纯发送网关**(本服务生成码 → 放入 templateParamJson → 创蓝只下发,
|
||||
无校验接口),故与极光同为 **Mode B**:本服务生成/存储/校验验证码,创蓝只负责发。
|
||||
|
||||
**本模块的存码/冷却/一次性/防爆破/GC 机器与 [jiguang.py](jiguang.py) 是刻意的隔离复制**
|
||||
(设计见 docs/superpowers/specs/2026-07-26-chuanglan-sms-verify-design.md):极光文件一行不动、
|
||||
零回归风险于登录关键路径的默认 provider;代价是两处 Mode B 并发逻辑重复,改动需同步。唯一新逻辑
|
||||
是 `_send_via_chuanglan`(HMAC-SHA256 签名 + httpx POST + 错误码映射)。
|
||||
|
||||
两种运行模式由 `SMS_MOCK` 切换:
|
||||
- **mock**(开发/测试,默认):不真发,验证码打日志;校验放行任意 N 位数字。
|
||||
- **real**(`SMS_MOCK=false` 且 `SMS_PROVIDER=chuanglan`):`secrets` 生成码 → 调创蓝 `tpl/send`
|
||||
下发(HMAC 签名,password 仅本地算签不上行)→ 校验比对本地存码(一次性 / 过期 / 防爆破)。
|
||||
|
||||
验证码存储:**进程内存**(单 worker 够用,多 worker 不共享,与极光同级技术债)。防刷同极光:
|
||||
单号 `SMS_SEND_INTERVAL_SEC` 冷却(本文件)+ 单设备/IP 频控(api 层)+ 单码失败 `SMS_MAX_VERIFY_ATTEMPTS`
|
||||
次即作废。运维侧另需在创蓝控制台配 **IP 白名单**(否则 117)。接口调研见 docs/integrations/chuanglan/tpl-send.md。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import hmac
|
||||
import json
|
||||
import logging
|
||||
import secrets
|
||||
import time
|
||||
from dataclasses import dataclass
|
||||
from threading import Lock
|
||||
|
||||
import httpx
|
||||
|
||||
from app.core.config import settings
|
||||
|
||||
from .base import SmsError, mock_verify
|
||||
|
||||
logger = logging.getLogger("shagua.sms.chuanglan")
|
||||
|
||||
|
||||
@dataclass
|
||||
class _CodeRecord:
|
||||
code: str
|
||||
expires_at: float
|
||||
attempts: int = 0
|
||||
|
||||
|
||||
# 进程内存(单 worker 有效;多 worker 不共享,见模块 docstring)。与极光同结构。
|
||||
_codes: dict[str, _CodeRecord] = {} # phone -> 当前有效验证码
|
||||
_last_sent: dict[str, float] = {} # phone -> 上次发送 epoch(冷却)
|
||||
_lock = Lock()
|
||||
_GC_THRESHOLD = 10000 # 任一内存 dict 超此阈值,send 时顺手清过期项(防无限增长)
|
||||
|
||||
# 发码错误码(创蓝 `code`)→ (HTTP 码, 用户提示)。未列出的一律 503(供应商不可用)。
|
||||
_SEND_ERRORS: dict[str, tuple[int, str]] = {
|
||||
"103": (429, "发送过于频繁，请稍后再试"), # 提交速度过快
|
||||
"107": (400, "手机号无效"), # 手机号码错误
|
||||
}
|
||||
# 需运维介入的配置/开通/余额类错误:打 critical 日志(仍归 503)。
|
||||
_SEND_CRITICAL_CODES = frozenset({
|
||||
"109", # 无发送量/余额不足
|
||||
"117", # IP 未加白名单
|
||||
"102", # 密码错误
|
||||
"116", # 签名不合法
|
||||
"124", # 模板内容不匹配
|
||||
"152", # 模板不存在
|
||||
"101", # 账号不存在
|
||||
"118", # 无发送权限
|
||||
})
|
||||
|
||||
|
||||
def _gen_code() -> str:
|
||||
"""生成 N 位数字验证码(用 secrets 而非 random;允许前导 0)。"""
|
||||
return "".join(secrets.choice("0123456789") for _ in range(settings.SMS_CODE_LENGTH))
|
||||
|
||||
|
||||
def _gc(now: float) -> None:
|
||||
"""顺手清理过期内存项,防两个 dict 无限增长。仅在持锁时调用,且某 dict 超阈值才扫它。"""
|
||||
if len(_codes) > _GC_THRESHOLD:
|
||||
for p in [p for p, r in _codes.items() if now > r.expires_at]:
|
||||
_codes.pop(p, None)
|
||||
if len(_last_sent) > _GC_THRESHOLD:
|
||||
cutoff = now - settings.SMS_SEND_INTERVAL_SEC
|
||||
for p in [p for p, ts in _last_sent.items() if ts < cutoff]:
|
||||
_last_sent.pop(p, None)
|
||||
|
||||
|
||||
def send_code(phone: str) -> int:
|
||||
"""发送验证码。
|
||||
|
||||
Returns: 距下次可发的秒数(= SMS_SEND_INTERVAL_SEC)
|
||||
Raises: SmsError(过频 429 / 手机号无效 400 / 供应商失败 503)
|
||||
"""
|
||||
now = time.time()
|
||||
|
||||
# --- lock 内:防刷检查 + 预占(防并发重复发烧钱)---
|
||||
with _lock:
|
||||
_gc(now) # 顺手清过期内存(超阈值才扫)
|
||||
elapsed = now - _last_sent.get(phone, 0.0)
|
||||
if elapsed < settings.SMS_SEND_INTERVAL_SEC:
|
||||
remain = int(settings.SMS_SEND_INTERVAL_SEC - elapsed)
|
||||
raise SmsError(f"发送过于频繁,请 {remain}s 后再试")
|
||||
|
||||
code = _gen_code()
|
||||
# 预占:先记冷却/存码,释放锁后再发网络(发失败保留冷却,见下)
|
||||
_last_sent[phone] = now
|
||||
_codes[phone] = _CodeRecord(code=code, expires_at=now + settings.SMS_CODE_TTL_SEC)
|
||||
|
||||
# --- lock 外:真正发送(网络 IO 不持锁)---
|
||||
try:
|
||||
if settings.SMS_MOCK:
|
||||
logger.info("[SMS-chuanglan-MOCK] to %s**** code=%s (不真发)", phone[:3], code)
|
||||
else:
|
||||
_send_via_chuanglan(phone, code)
|
||||
logger.info("[SMS-chuanglan] sent to %s****", phone[:3])
|
||||
except Exception as e:
|
||||
# 发送失败:**保留冷却**(失败也限速,挡住余额不足/签名失效时前端重试狂打),
|
||||
# 只清掉没发出去的码(用户收不到,留着无意义且占内存)。
|
||||
with _lock:
|
||||
_codes.pop(phone, None)
|
||||
if isinstance(e, SmsError):
|
||||
raise
|
||||
logger.exception("[SMS-chuanglan] send failed phone=%s****", phone[:3])
|
||||
raise SmsError("验证码发送失败,请稍后重试", status_code=503) from e
|
||||
|
||||
return settings.SMS_SEND_INTERVAL_SEC
|
||||
|
||||
|
||||
def verify_code(phone: str, code: str) -> bool:
|
||||
"""校验验证码。
|
||||
|
||||
- **mock 模式**:放行任意 N 位数字(测试/开发便利,不真校验)。
|
||||
- **real 模式**:比对本服务存的码,匹配即作废(一次性);失败累计到上限也作废(防爆破)。
|
||||
"""
|
||||
if settings.SMS_MOCK:
|
||||
ok = mock_verify(code)
|
||||
logger.info("[SMS-chuanglan-MOCK] verify %s for %s****", "ok" if ok else "fail", phone[:3])
|
||||
return ok
|
||||
|
||||
with _lock:
|
||||
rec = _codes.get(phone)
|
||||
if rec is None:
|
||||
return False
|
||||
if time.time() > rec.expires_at:
|
||||
_codes.pop(phone, None)
|
||||
return False
|
||||
if rec.attempts >= settings.SMS_MAX_VERIFY_ATTEMPTS:
|
||||
_codes.pop(phone, None) # 试错过多,作废
|
||||
return False
|
||||
if secrets.compare_digest(code.encode("utf-8"), rec.code.encode("utf-8")):
|
||||
_codes.pop(phone, None) # 验过即作废
|
||||
return True
|
||||
rec.attempts += 1
|
||||
return False
|
||||
|
||||
|
||||
# ============================ 发送接缝(单测 monkeypatch 这两个 / httpx.post)============================
|
||||
|
||||
def _sign(password: str, timestamp: str, nonce: str) -> str:
|
||||
"""创蓝 HMAC-SHA256 签名:key=md5(password),msg=sorted([md5pwd,ts,nonce]) 拼接去空白,输出小写 hex。"""
|
||||
md5pwd = hashlib.md5(password.encode()).hexdigest() # 32 位小写 hex
|
||||
raw = "".join(sorted([md5pwd, timestamp, nonce])) # 字典序升序,无分隔符拼接
|
||||
raw = "".join(raw.split()) # 去所有空白(faithful;三段本无空白)
|
||||
return hmac.new(md5pwd.encode(), raw.encode(), hashlib.sha256).hexdigest()
|
||||
|
||||
|
||||
def _call_chuanglan(phone: str, code: str) -> dict:
|
||||
"""组装 + 签名 + POST 创蓝 tpl/send,返回解析后的响应 dict。
|
||||
|
||||
传输错误 / HTTP≠200 / 响应非 JSON 一律抛 SmsError(503)(保「provider 出问题→503」不变式);
|
||||
业务码(含 000000)由调用方 `_send_via_chuanglan` 判读。password 只用于算签,不入 body。
|
||||
"""
|
||||
timestamp = str(int(time.time()))
|
||||
nonce = secrets.token_hex(16) # 32 位 hex
|
||||
body = {
|
||||
"account": settings.CHUANGLAN_SMS_ACCOUNT,
|
||||
"timestamp": timestamp,
|
||||
"nonce": nonce,
|
||||
"phoneNumbers": phone,
|
||||
"templateId": settings.CHUANGLAN_SMS_TEMPLATE_ID,
|
||||
"templateParamJson": json.dumps([{"param1": code}]),
|
||||
}
|
||||
if settings.CHUANGLAN_SMS_SIGNATURE:
|
||||
body["signature"] = settings.CHUANGLAN_SMS_SIGNATURE
|
||||
headers = {
|
||||
"Content-Type": "application/json",
|
||||
"X-QA-Hmac-Signature": _sign(settings.CHUANGLAN_SMS_PASSWORD, timestamp, nonce),
|
||||
}
|
||||
try:
|
||||
resp = httpx.post(
|
||||
settings.CHUANGLAN_SMS_ENDPOINT,
|
||||
json=body,
|
||||
headers=headers,
|
||||
timeout=settings.CHUANGLAN_SMS_TIMEOUT_SEC,
|
||||
)
|
||||
except httpx.HTTPError as e:
|
||||
logger.exception("[SMS-chuanglan] 网络错误 phone=%s****", phone[:3])
|
||||
raise SmsError("短信服务暂不可用,请稍后重试", status_code=503) from e
|
||||
|
||||
if resp.status_code != 200:
|
||||
logger.error("[SMS-chuanglan] http=%s body=%s", resp.status_code, resp.text[:200])
|
||||
raise SmsError("短信服务暂不可用,请稍后重试", status_code=503)
|
||||
try:
|
||||
return resp.json()
|
||||
except Exception as e:
|
||||
logger.error("[SMS-chuanglan] 响应非 JSON: %s", resp.text[:200])
|
||||
raise SmsError("短信服务暂不可用,请稍后重试", status_code=503) from e
|
||||
|
||||
|
||||
def _send_via_chuanglan(phone: str, code: str) -> None:
|
||||
"""调创蓝 tpl/send 发送。成功静默返回;失败按错误码映射抛 SmsError。"""
|
||||
if not settings.chuanglan_sms_configured:
|
||||
raise SmsError("短信服务未配置(缺创蓝 account/password/templateId)", status_code=503)
|
||||
|
||||
result = _call_chuanglan(phone, code) # 传输/非200/解析异常在内部抛 SmsError(503)
|
||||
rcode = str(result.get("code"))
|
||||
if rcode == "000000":
|
||||
return
|
||||
|
||||
emsg = result.get("errorMsg") or ""
|
||||
logger.error("[SMS-chuanglan] send failed code=%s msg=%s", rcode, emsg)
|
||||
if rcode in _SEND_CRITICAL_CODES:
|
||||
logger.critical("[SMS-chuanglan] %s —— 需运维处理(余额/IP白名单/密码/签名/模板/账号)", rcode)
|
||||
status, msg = _SEND_ERRORS.get(rcode, (503, "短信服务暂不可用,请稍后重试"))
|
||||
raise SmsError(msg, status_code=status)
|
||||
@@ -1,224 +0,0 @@
|
||||
CheckSmsVerifyCode - 核验验证码
|
||||
更新时间：2026年3月19日 20:02:53
|
||||
核验短信验证码并返回核验是否成功的结果。
|
||||
|
||||
调试
|
||||
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
|
||||
|
||||
调试
|
||||
授权信息
|
||||
下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：
|
||||
|
||||
操作：是指具体的权限点。
|
||||
|
||||
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
|
||||
|
||||
资源类型：是指操作中支持授权的资源类型。具体说明如下：
|
||||
|
||||
对于必选的资源类型，用前面加 * 表示。
|
||||
|
||||
对于不支持资源级授权的操作，用全部资源表示。
|
||||
|
||||
条件关键字：是指云产品自身定义的条件关键字。
|
||||
|
||||
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
|
||||
|
||||
放大查看
|
||||
操作
|
||||
|
||||
访问级别
|
||||
|
||||
资源类型
|
||||
|
||||
条件关键字
|
||||
|
||||
关联操作
|
||||
|
||||
dypns:CheckSmsVerifyCode
|
||||
|
||||
none
|
||||
|
||||
*全部资源
|
||||
|
||||
*
|
||||
|
||||
无 无
|
||||
请求参数
|
||||
放大查看
|
||||
名称
|
||||
|
||||
类型
|
||||
|
||||
必填
|
||||
|
||||
描述
|
||||
|
||||
示例值
|
||||
|
||||
SchemeName
|
||||
string
|
||||
|
||||
否
|
||||
|
||||
方案名称，如果不填则为“默认方案”。最多不超过 20 个字符。
|
||||
|
||||
重要 如果发送接口的方案名称不为空，请确保该参数不为空且与发送接口的方案名称参数一致
|
||||
测试方案
|
||||
|
||||
CountryCode
|
||||
string
|
||||
|
||||
否
|
||||
|
||||
号码国家编码，默认为 86。
|
||||
|
||||
86
|
||||
|
||||
PhoneNumber
|
||||
string
|
||||
|
||||
是
|
||||
|
||||
手机号。
|
||||
|
||||
186****0000
|
||||
|
||||
OutId
|
||||
string
|
||||
|
||||
否
|
||||
|
||||
外部流水号。
|
||||
|
||||
12123231
|
||||
|
||||
VerifyCode
|
||||
string
|
||||
|
||||
是
|
||||
|
||||
验证码。
|
||||
|
||||
说明
|
||||
SendSmsVerifyCode 接口的字段 TemplateParam，配置方式有 2 种：
|
||||
|
||||
{"code":"##code##","min":"5"}
|
||||
|
||||
{"code":"123456","min":"5"}
|
||||
|
||||
{"code":"##code##","min":"5"}验证码是 api 动态生成的，阿里云接口可以完成校验。
|
||||
|
||||
{"code":"123456","min":"5"}验证码是用户配置的不是 api 动态生成，阿里云接口无法校验。
|
||||
|
||||
请您按照实际情况传入对应的验证码。
|
||||
|
||||
1231
|
||||
|
||||
CaseAuthPolicy
|
||||
integer
|
||||
|
||||
否
|
||||
|
||||
验证码大小写字母核验策略。取值：
|
||||
|
||||
1：不区分大小写。
|
||||
|
||||
2：区分大小写。
|
||||
|
||||
1
|
||||
|
||||
返回参数
|
||||
放大查看
|
||||
名称
|
||||
|
||||
类型
|
||||
|
||||
描述
|
||||
|
||||
示例值
|
||||
|
||||
object
|
||||
|
||||
AccessDeniedDetail
|
||||
string
|
||||
|
||||
访问被拒绝详细信息。
|
||||
|
||||
无
|
||||
|
||||
Message
|
||||
string
|
||||
|
||||
状态码的描述。
|
||||
|
||||
成功
|
||||
|
||||
Model
|
||||
object
|
||||
|
||||
请求结果数据。
|
||||
|
||||
OutId
|
||||
string
|
||||
|
||||
外部流水号。
|
||||
|
||||
1212312
|
||||
|
||||
VerifyResult
|
||||
string
|
||||
|
||||
短信验证码核验结果。取值：
|
||||
|
||||
PASS：短信验证码核验成功。
|
||||
|
||||
UNKNOWN：短信验证码核验失败。
|
||||
|
||||
PASS
|
||||
|
||||
Code
|
||||
string
|
||||
|
||||
接口请求状态码。
|
||||
|
||||
返回 OK 代表请求成功。
|
||||
|
||||
其他错误码，请参见返回码。
|
||||
|
||||
重要 接口请求成功不代表短信验证码核验成功，短信验证码核验结果仅以Model.VerifyResult参数返回值为准。
|
||||
OK
|
||||
|
||||
Success
|
||||
boolean
|
||||
|
||||
接口调用是否成功。取值：
|
||||
|
||||
true：接口调用成功。
|
||||
|
||||
false：接口调用失败。
|
||||
|
||||
重要 接口调用成功不代表短信验证码核验成功，短信验证码核验结果仅以Model.VerifyResult参数返回值为准。
|
||||
true
|
||||
|
||||
RequestId
|
||||
string
|
||||
|
||||
CF8854E5-DB21-3E5D-A9B1-DDC752FD7384
|
||||
|
||||
示例
|
||||
正常返回示例
|
||||
|
||||
JSON格式
|
||||
|
||||
放大查看复制代码
|
||||
{
|
||||
"AccessDeniedDetail": "无",
|
||||
"Message": "成功",
|
||||
"Model": {
|
||||
"OutId": "1212312",
|
||||
"VerifyResult": "PASS"
|
||||
},
|
||||
"Code": "OK",
|
||||
"Success": true,
|
||||
"RequestId": "CF8854E5-DB21-3E5D-A9B1-DDC752FD7384"
|
||||
}
|
||||
@@ -1,396 +0,0 @@
|
||||
SendSmsVerifyCode - 发送短信验证码
|
||||
更新时间：2026年7月3日 09:54:53
|
||||
发送短信验证码。
|
||||
|
||||
接口说明
|
||||
由于运营商近期加强对短信签名的管控。您自定义的签名面临下发失败问题，推荐您使用号码认证控制台赠送的短信签名和模板进行短信认证。系统赠送签名必须搭配系统赠送模板使用。
|
||||
|
||||
请确保在使用该接口前，已充分了解号码认证服务产品的收费方式和价格，短信认证服务仅收取短信发送费用（按运营商回执状态计费，短信提交成功但运营商回执失败时不计费），核验服务免费。
|
||||
|
||||
调试
|
||||
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
|
||||
|
||||
调试
|
||||
授权信息
|
||||
下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：
|
||||
|
||||
操作：是指具体的权限点。
|
||||
|
||||
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
|
||||
|
||||
资源类型：是指操作中支持授权的资源类型。具体说明如下：
|
||||
|
||||
对于必选的资源类型，用前面加 * 表示。
|
||||
|
||||
对于不支持资源级授权的操作，用全部资源表示。
|
||||
|
||||
条件关键字：是指云产品自身定义的条件关键字。
|
||||
|
||||
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
|
||||
|
||||
放大查看
|
||||
操作
|
||||
|
||||
访问级别
|
||||
|
||||
资源类型
|
||||
|
||||
条件关键字
|
||||
|
||||
关联操作
|
||||
|
||||
dypns:SendSmsVerifyCode
|
||||
|
||||
create
|
||||
|
||||
*全部资源
|
||||
|
||||
*
|
||||
|
||||
无 无
|
||||
请求参数
|
||||
放大查看
|
||||
名称
|
||||
|
||||
类型
|
||||
|
||||
必填
|
||||
|
||||
描述
|
||||
|
||||
示例值
|
||||
|
||||
SchemeName
|
||||
string
|
||||
|
||||
否
|
||||
|
||||
方案名称，如果不填则为“默认方案”。最多不超过 20 个字符。
|
||||
|
||||
测试方案
|
||||
|
||||
CountryCode
|
||||
string
|
||||
|
||||
否
|
||||
|
||||
号码国家编码。默认为 86，目前也仅支持国内号码发送。
|
||||
|
||||
86
|
||||
|
||||
PhoneNumber
|
||||
string
|
||||
|
||||
是
|
||||
|
||||
短信接收方手机号。
|
||||
|
||||
130****0000
|
||||
|
||||
SignName
|
||||
string
|
||||
|
||||
是
|
||||
|
||||
签名名称。暂不支持使用自定义签名，请使用系统赠送的签名，您可在赠送签名配置页面选择需要下发的签名。
|
||||
|
||||
恒创联众
|
||||
|
||||
TemplateCode
|
||||
string
|
||||
|
||||
是
|
||||
|
||||
短信模板 CODE。参数SignName选择赠送签名时，必须搭配赠送模板下发短信。您可在赠送模板配置页面选择适用您业务场景的模板。
|
||||
|
||||
100001
|
||||
|
||||
TemplateParam
|
||||
string
|
||||
|
||||
是
|
||||
|
||||
短信模板参数。验证码位置有两种传值方式：
|
||||
|
||||
可使用"##code##"替代，由参数 CodeType 指定验证码生成规则；
|
||||
|
||||
也可直接传入具体的验证码值，直接下发至接收方。
|
||||
|
||||
示例：如模板内容为：“您的验证码是${code}，有效期${min}分钟，请勿告诉他人。”。
|
||||
|
||||
重要 上文中的 code 请替换成您实际申请的验证码模板中的参数名称
|
||||
该字段可传入{"code":"##code##","min":"5"}由系统根据规则生成验证码；
|
||||
|
||||
或直接传入指定的验证码值{"code":"123456","min":"5"}。
|
||||
|
||||
说明
|
||||
{"code":"##code##","min":"5"}验证码是 api 动态生成的，阿里云接口可以完成校验。
|
||||
|
||||
{"code":"123456","min":"5"}验证码是用户配置的不是 api 动态生成，阿里云接口无法校验。
|
||||
|
||||
说明
|
||||
如果 JSON 中需要带换行符，请参照标准的 JSON 协议处理。
|
||||
|
||||
模板变量规范，请参见短信模板规范。
|
||||
|
||||
{"code":"##code##","min":"5"}
|
||||
|
||||
SmsUpExtendCode
|
||||
string
|
||||
|
||||
否
|
||||
|
||||
上行短信扩展码。上行短信指发送给通信服务提供商的短信，用于定制某种服务、完成查询，或是办理某种业务等，需要收费，按运营商普通短信资费进行扣费。
|
||||
|
||||
说明
|
||||
扩展码是生成签名时系统自动默认生成的，不支持自行传入。无特殊需要此字段的用户请忽略此字段。如需使用，请联系您的商务经理。
|
||||
|
||||
1213123
|
||||
|
||||
OutId
|
||||
string
|
||||
|
||||
否
|
||||
|
||||
外部流水号。
|
||||
|
||||
外部流水号（透传）
|
||||
|
||||
CodeLength
|
||||
integer
|
||||
|
||||
否
|
||||
|
||||
验证码长度支持 4～8 位长度，默认是 4 位。
|
||||
|
||||
4
|
||||
|
||||
ValidTime
|
||||
integer
|
||||
|
||||
否
|
||||
|
||||
验证码有效时长，单位秒，默认为 300 秒。
|
||||
|
||||
300
|
||||
|
||||
DuplicatePolicy
|
||||
integer
|
||||
|
||||
否
|
||||
|
||||
核验规则，当有效时间内对同场景内的同号码重复发送验证码时，旧验证码如何处理。
|
||||
|
||||
1：覆盖处理（默认），即旧验证码会失效掉。
|
||||
|
||||
2：保留，即多个验证码都是在有效期内都可以校验通过。
|
||||
|
||||
枚举值：
|
||||
|
||||
1 :
|
||||
覆盖
|
||||
|
||||
2 :
|
||||
保留
|
||||
|
||||
1
|
||||
|
||||
Interval
|
||||
integer
|
||||
|
||||
否
|
||||
|
||||
时间间隔，单位：秒。即多久间隔可以发送一次验证码，用于频控，默认 60 秒。
|
||||
|
||||
60
|
||||
|
||||
CodeType
|
||||
integer
|
||||
|
||||
否
|
||||
|
||||
生成的验证码类型。当参数 TemplateParam 传入占位符时，此参数必填，将由系统根据指定的规则生成验证码。取值：
|
||||
|
||||
1：纯数字（默认）。
|
||||
|
||||
2：纯大写字母。
|
||||
|
||||
3：纯小写字母。
|
||||
|
||||
4：大小字母混合。
|
||||
|
||||
5：数字+大写字母混合。
|
||||
|
||||
6：数字+小写字母混合。
|
||||
|
||||
7：数字+大小写字母混合。
|
||||
|
||||
枚举值：
|
||||
|
||||
1 :
|
||||
纯数字
|
||||
|
||||
2 :
|
||||
纯大写字母
|
||||
|
||||
3 :
|
||||
纯小写字母
|
||||
|
||||
4 :
|
||||
大小字母混合
|
||||
|
||||
5 :
|
||||
数字+大写字母混合
|
||||
|
||||
6 :
|
||||
数字+小写字母混合
|
||||
|
||||
7 :
|
||||
数字+大小写字母混合
|
||||
|
||||
1
|
||||
|
||||
ReturnVerifyCode
|
||||
boolean
|
||||
|
||||
否
|
||||
|
||||
是否返回验证码。取值：
|
||||
|
||||
true：返回。
|
||||
|
||||
false：不返回。
|
||||
|
||||
true
|
||||
|
||||
AutoRetry
|
||||
integer
|
||||
|
||||
否
|
||||
|
||||
是否自动替换签名重试（默认开启），可取值：
|
||||
|
||||
1 开启自动重试功能，开启后，在验证码有效期内，当运营商返回明确的失败状态时，允许阿里云尽可能的尝试使用其他方式发送验证码，以提升发送成功率。其他方式包括且不限于：通过其他运营商重试、更换签名重试等
|
||||
|
||||
0 不开启自动重试
|
||||
|
||||
是否自动重试
|
||||
|
||||
返回参数
|
||||
放大查看
|
||||
名称
|
||||
|
||||
类型
|
||||
|
||||
描述
|
||||
|
||||
示例值
|
||||
|
||||
object
|
||||
|
||||
AccessDeniedDetail
|
||||
string
|
||||
|
||||
访问被拒绝详细信息。
|
||||
|
||||
无
|
||||
|
||||
Message
|
||||
string
|
||||
|
||||
状态码的描述。
|
||||
|
||||
成功
|
||||
|
||||
RequestId
|
||||
string
|
||||
|
||||
请求 ID。
|
||||
|
||||
CC3BB6D2-2FDF-4321-9DCE-B38165CE4C47
|
||||
|
||||
Model
|
||||
object
|
||||
|
||||
请求结果数据。
|
||||
|
||||
VerifyCode
|
||||
string
|
||||
|
||||
验证码。
|
||||
|
||||
4232
|
||||
|
||||
RequestId
|
||||
string
|
||||
|
||||
请求 ID。
|
||||
|
||||
a3671ccf-0102-4c8e-8797-a3678e091d09
|
||||
|
||||
OutId
|
||||
string
|
||||
|
||||
外部流水号。
|
||||
|
||||
1231231313
|
||||
|
||||
BizId
|
||||
string
|
||||
|
||||
业务 ID。
|
||||
|
||||
112231421412414124123^4
|
||||
|
||||
Code
|
||||
string
|
||||
|
||||
请求状态码。返回 OK 代表请求成功。其他错误码，请参见返回码列表。
|
||||
|
||||
OK
|
||||
|
||||
Success
|
||||
boolean
|
||||
|
||||
请求是否成功。
|
||||
|
||||
true：请求成功。
|
||||
|
||||
false：请求失败。
|
||||
|
||||
true
|
||||
|
||||
示例
|
||||
正常返回示例
|
||||
|
||||
JSON格式
|
||||
|
||||
放大查看复制代码
|
||||
{
|
||||
"AccessDeniedDetail": "无",
|
||||
"Message": "成功 ",
|
||||
"RequestId": "CC3BB6D2-2FDF-4321-9DCE-B38165CE4C47",
|
||||
"Model": {
|
||||
"VerifyCode": "4232",
|
||||
"RequestId": "a3671ccf-0102-4c8e-8797-a3678e091d09",
|
||||
"OutId": "1231231313",
|
||||
"BizId": "112231421412414124123^4"
|
||||
},
|
||||
"Code": "OK",
|
||||
"Success": true
|
||||
}
|
||||
错误码
|
||||
放大查看
|
||||
HTTP status code
|
||||
|
||||
错误码
|
||||
|
||||
错误信息
|
||||
|
||||
描述
|
||||
|
||||
400 MOBILE_NUMBER_ILLEGAL The mobile number is illegal. 手机号码格式错误
|
||||
400 BUSINESS_LIMIT_CONTROL The number has exceeded the limit for the day. 触发号码天级流控
|
||||
400 FREQUENCY_FAIL Check frequency fail. 频控校验未通过
|
||||
400 INVALID_PARAMETERS parameter is not valid. 非法参数
|
||||
400 FUNCTION_NOT_OPENED You have not opened this function. 没有开通融合认证功能
|
||||
@@ -1,117 +0,0 @@
|
||||
# 创蓝云智（253/蓝创云智）模板短信 v2 发送接口
|
||||
|
||||
> 官方文档：<https://doc.chuanglan.com/document/HAQYSZKH9HT5Z50L>
|
||||
> 用途：手机号 + 验证码登录的**验证码短信下发**（本服务生成码 → 创蓝只负责发送，属自管码 Mode B，与极光同模式）。
|
||||
> 本文件为**接口调研摘要**，供 `app/integrations/sms/chuanglan.py` 实现对照。以线上文档为准。
|
||||
|
||||
## 接口概览
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 请求地址 | `POST https://smssh.253.com/msg/sms/v2/tpl/send` |
|
||||
| Content-Type | `application/json`（UTF-8） |
|
||||
| 协议 | HTTPS |
|
||||
| 鉴权 | HMAC-SHA256 签名头 `X-QA-Hmac-Signature`（推荐）**或** body 明文 `password`（二选一） |
|
||||
|
||||
## 鉴权：两种方式（二选一，不可并用）
|
||||
|
||||
1. **HMAC 签名头（推荐，密码不上行）**：请求头带 `X-QA-Hmac-Signature`，body **不放** `password`。
|
||||
2. **明文密码**：body 放 `password`，不带签名头。
|
||||
|
||||
### HMAC-SHA256 签名算法
|
||||
|
||||
1. `md5Password = MD5(password)` —— 32 位**小写十六进制**。
|
||||
2. 取三个值 `[md5Password, timestamp, nonce]`，**按字典序升序排序**，**无分隔符拼接**，再 `replaceAll("\\s+", "")` 去除所有空白。
|
||||
3. `signature = HmacSHA256(key = md5Password, message = 上一步拼接串)` —— 输出**小写十六进制**。
|
||||
4. 放入请求头：`X-QA-Hmac-Signature: <signature>`。
|
||||
|
||||
> 注意 `key` 就是 `md5Password` 本身（32 位 hex 字符串），不是原始 password。`timestamp` / `nonce` 同时也是 body 字段，必须与签名里用的一致。
|
||||
|
||||
## 请求参数（body，JSON）
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `account` | String | 是 | API 账号；验证码短信用 **`YZM` 前缀**账号（如 `YZM0000001`） |
|
||||
| `timestamp` | String | 是 | Unix 秒级时间戳；**60 秒**内有效，过期报 139 |
|
||||
| `nonce` | String | 是 | 32 位随机串（防重放） |
|
||||
| `phoneNumbers` | String | 是 | 手机号，逗号分隔最多 1000 个；**YZM 验证码账号不支持批量，只能单号** |
|
||||
| `templateId` | String | 是 | 模板 ID（控制台创建 / 模板接口查询） |
|
||||
| `templateParamJson` | String | 条件 | 模板变量，JSON 字符串；模板有 `{s}` 占位符时必填（见下） |
|
||||
| `password` | String | 条件 | 仅在**不使用**签名头时放 body |
|
||||
| `signature` | String | 条件 | **短信签名文案**（如 `【创蓝云智】`）；模板未关联签名时必填。**注意与鉴权头 `X-QA-Hmac-Signature` 是两回事** |
|
||||
| `report` | String | 否 | `"true"` 时接收状态回执 |
|
||||
| `callbackUrl` | String | 否 | 回执回调完整 URL |
|
||||
| `uid` | String | 否 | 自定义标识（≤256 字符），回执原样返回 |
|
||||
| `extend` | String | 否 | 数字扩展码（≤5 位），用于上行匹配 |
|
||||
|
||||
### `templateParamJson` 格式与 `{s}` 占位
|
||||
|
||||
- 模板内容用 `{s}` 作占位符，例：`您正在申请手机注册，验证码为：{s}，5分钟内有效！`
|
||||
- `templateParamJson` 是 **JSON 数组，元素为对象**，键按 `param1`、`param2`…递增；第 1 个 `{s}` ← `param1`，第 2 个 ← `param2`。
|
||||
- 单条验证码（一个 `{s}` = 验证码）示例：`"[{\"param1\":\"123456\"}]"`
|
||||
|
||||
## 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "000000",
|
||||
"msgId": "25071018345400902898000000000001",
|
||||
"time": "20250710183454",
|
||||
"successNum": "1",
|
||||
"failNum": "0",
|
||||
"errorMsg": ""
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| `code` | 状态码，`"000000"` = 成功 |
|
||||
| `msgId` | 消息 ID（32 位） |
|
||||
| `time` | 响应时间戳 |
|
||||
| `successNum` / `failNum` | 提交成功 / 失败条数 |
|
||||
| `errorMsg` | 错误描述（成功为空） |
|
||||
|
||||
## 响应 / 错误码（节选）
|
||||
|
||||
| code | 含义 | 归属 |
|
||||
|---|---|---|
|
||||
| `000000` | 成功 | — |
|
||||
| `101` | 账号不存在 | 客服 |
|
||||
| `102` | 密码错误 | 客服 |
|
||||
| `103` | 提交速度过快（超频） | 客服 |
|
||||
| `107` | 手机号码错误 | 客服 |
|
||||
| `109` | 无发送量（余额/套餐不足） | 销售 |
|
||||
| `110` | 不在发送时段 | 销售 |
|
||||
| `116` | 签名不合法 / 未带签名 | 服务 |
|
||||
| `117` | IP 未加白名单 | 服务 |
|
||||
| `118` | 账号无发送权限 | 服务 |
|
||||
| `124` | 模板内容不匹配 | 服务 |
|
||||
| `129` | JSON 格式错误 | 客服 |
|
||||
| `135` | 相同手机号内容重复 | 客服 |
|
||||
| `139` | 时间戳过期 | 客服 |
|
||||
| `152` | 模板不存在 | 服务 |
|
||||
| `158` | 退订文案不合规 | 客服 |
|
||||
|
||||
## 完整请求示例（单条验证码，明文密码方式省略 password 用签名头）
|
||||
|
||||
```json
|
||||
{
|
||||
"account": "YZM0000001",
|
||||
"timestamp": "1752143733",
|
||||
"nonce": "x4zfk0y5foqwx6cbnw3bfmimy98abqs1",
|
||||
"phoneNumbers": "17601337176",
|
||||
"templateId": "1021143438",
|
||||
"templateParamJson": "[{\"param1\":\"123456\"}]",
|
||||
"report": "true"
|
||||
}
|
||||
```
|
||||
|
||||
（HMAC 方式：另加请求头 `X-QA-Hmac-Signature: <算法输出>`，body 不含 `password`。）
|
||||
|
||||
## 接入要点
|
||||
|
||||
- **IP 白名单**：服务器出网 IP 必须在控制台加白，否则 117。
|
||||
- **验证码账号（YZM）**：无发送时段限制；单号发送、不支持批量。
|
||||
- **时间戳 60s**：`timestamp` 与本地时钟偏差过大会 139，注意服务器时间同步。
|
||||
- **退订文案**：仅支持 `拒收请回复R`，且必须在短信末尾（验证码短信一般无需）。
|
||||
- **签名 vs 鉴权头**：`signature`（body）= 短信开头的 `【品牌】` 文案；`X-QA-Hmac-Signature`（header）= 请求鉴权。二者含义完全不同，勿混。
|
||||
@@ -1,26 +1,9 @@
|
||||
# 短信验证码（sms）
|
||||
|
||||
> 文件:`app/integrations/sms/`(分派器 `__init__` + `jiguang` / `aliyun` provider + `base`) | 关联接口:[auth-sms-send](../api/auth-sms-send.md) · [auth-sms-login](../api/auth-sms-login.md) | [← 集成索引](./README.md)
|
||||
> 文件:`app/integrations/sms.py` | 关联接口:[auth-sms-send](../api/auth-sms-send.md) · [auth-sms-login](../api/auth-sms-login.md) | [← 集成索引](./README.md)
|
||||
|
||||
## 作用
|
||||
手机号 + 验证码登录的验证码发送 / 校验。支持**可切换 provider**(`SMS_PROVIDER`):`jiguang`(默认,极光自管码)/ `aliyun`(阿里云号码认证托管码)/ `chuanglan`(创蓝云智模板短信,自管码)。`SMS_MOCK` 另切 mock / real。
|
||||
|
||||
## 短信提供商(`SMS_PROVIDER`,可切换 + 灰度回退)
|
||||
| | `jiguang`(默认) | `aliyun` | `chuanglan` |
|
||||
|---|---|---|---|
|
||||
| 验证码模式 | 自管码 Mode B | 托管码 Mode A | 自管码 Mode B(与极光同) |
|
||||
| 验证码 | **本服务生成**、极光只下发、**本地内存校验** | **阿里云生成 + 下发 + 校验**(dypns 号码认证,核验免费) | **本服务生成**、创蓝只下发、**本地内存校验** |
|
||||
| 发码 | 极光 `/v1/messages` | `SendSmsVerifyCode`(`##code##` 占位) | 创蓝 `tpl/send` v2(HMAC 签名头,password 不上行) |
|
||||
| 校验 | 比对本地存码 | `CheckSmsVerifyCode` → `PASS` / `UNKNOWN` | 比对本地存码 |
|
||||
| 多 worker | ⚠️ 内存存码不共享(见已知局限) | ✅ 阿里云托管,天然共享 | ⚠️ 内存存码不共享(与极光同级债) |
|
||||
| 防爆破 | 单码失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废 | **同语义**(本地 per-phone 失败计数) | **同语义**(复制自极光) |
|
||||
| 单号冷却 | 本地 `SMS_SEND_INTERVAL_SEC` | 交给阿里云 `Interval` | 本地 `SMS_SEND_INTERVAL_SEC` |
|
||||
| 依赖 | `httpx`(复用) | SDK `alibabacloud_dypnsapi20170525` | `httpx` + 标准库 `hashlib`/`hmac`(**无新依赖**) |
|
||||
|
||||
- `aliyun` 需在**号码认证控制台开通「融合认证」**,用系统赠送签名 + 赠送模板;配置见 `.env.example` 的 `ALIYUN_SMS_*`,SDK 为 `alibabacloud_dypnsapi20170525`。
|
||||
- `chuanglan` 用 **YZM 前缀验证码账号**,服务器出网 IP 须在创蓝控制台**加白名单**(否则 117);Mode B 存码/冷却/校验逻辑是**从极光隔离复制**(极光文件不动),仅发送走 HMAC 签名。配置见 `.env.example` 的 `CHUANGLAN_SMS_*`,接口调研见 [chuanglan/tpl-send.md](chuanglan/tpl-send.md),设计见 [spec](../superpowers/specs/2026-07-26-chuanglan-sms-verify-design.md)。
|
||||
|
||||
**以下章节描述 `jiguang` provider(自管码)细节**(`chuanglan` 的存码/冷却/校验语义与之相同)。
|
||||
手机号 + 验证码登录的验证码发送 / 校验。**已接极光短信 REST**,由 `SMS_MOCK` 切 mock / real。
|
||||
|
||||
| | mock(`SMS_MOCK=true`,默认 / 开发测试) | real(`SMS_MOCK=false`,生产) |
|
||||
|---|---|---|
|
||||
|
||||
@@ -1,182 +0,0 @@
|
||||
# 阿里云短信验证服务 — 设计方案
|
||||
|
||||
- 日期：2026-07-25
|
||||
- 状态：已定稿，待实现
|
||||
- 范围：新增阿里云 dypns（号码认证服务）短信验证码 provider，与现有极光短信可切换
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
现有短信验证码服务 `app/integrations/sms.py`：本服务**本地生成**验证码、存**进程内存**、极光 REST 仅负责下发；`verify_code()` 比对本地内存（一次性 + 单码失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废）。docstring 已标注"内存存码、多 worker 不共享"为技术债。
|
||||
|
||||
阿里云文档（`docs/integrations/aliyun/`）为 **号码认证服务 dypns** 的 `SendSmsVerifyCode` + `CheckSmsVerifyCode`：该产品由**阿里云生成并校验**验证码（`{"code":"##code##"}` 模式），核验免费。
|
||||
|
||||
目标：接入阿里云该套接口作为一个新的短信 provider，可与极光切换。
|
||||
|
||||
## 2. 关键决策（已确认）
|
||||
|
||||
1. **验证码模式 = Mode A（阿里云托管码）**：发码用 `SendSmsVerifyCode` + `##code##` 占位符，阿里云生成/存储/下发；校验用 `CheckSmsVerifyCode`，阿里云返回 `PASS/UNKNOWN`。本服务不再本地生成/存储验证码。
|
||||
2. **可切换 Provider**：新增 `SMS_PROVIDER=jiguang|aliyun` 开关，`send_code/verify_code` 按 provider 分派；保留极光作回退（短信=花钱+登录关键路径，灰度上线/融合认证未开通时可秒切回极光）。
|
||||
3. **官方 SDK**：调阿里云 dypns 用 `alibabacloud_dypnsapi20170525`，签名/加签由 SDK 处理。
|
||||
4. **防爆破与极光一致**（排查一致性）：阿里云路径**保留**与极光相同的"单码失败 N 次即作废"本地计数，而非改用 API 层频控，避免两 provider 行为不一致导致排查困惑。
|
||||
|
||||
## 3. 模块结构（`sms.py` 单文件升级为 provider 包）
|
||||
|
||||
```
|
||||
app/integrations/sms/
|
||||
__init__.py # 公开 API + 分派器:send_code / verify_code / SmsError
|
||||
# - SMS_MOCK=true 短路(不碰任何 provider)
|
||||
# - 按 settings.SMS_PROVIDER 选 jiguang / aliyun
|
||||
base.py # SmsError(沿用现定义)+ Provider 协议(send_code/verify_code 签名约定)
|
||||
jiguang.py # 现有自管码逻辑原样迁入(内存存码/冷却/一次性/防爆破 全保留,行为零改动)
|
||||
aliyun.py # 新增:SendSmsVerifyCode 发码 + CheckSmsVerifyCode 校验 + 本地失败计数
|
||||
```
|
||||
|
||||
- `__init__.py` 继续 re-export `SmsError / send_code / verify_code`，故 `app/api/v1/auth.py:37` 的
|
||||
`from app.integrations.sms import SmsError, send_code, verify_code` **导入不变**。
|
||||
- 纯增量重构：极光逻辑整体迁入 `jiguang.py`，对外行为零变化。
|
||||
|
||||
## 4. 数据流 — 阿里云 provider（Mode A）
|
||||
|
||||
### 4.1 发码 `aliyun.send_code(phone) -> int`
|
||||
1. 校验 `settings.aliyun_sms_configured`（缺 AK/SignName/TemplateCode → `SmsError(503)`）。
|
||||
2. 调 `SendSmsVerifyCode`：
|
||||
- `PhoneNumber=phone`
|
||||
- `SignName=ALIYUN_SMS_SIGN_NAME`、`TemplateCode=ALIYUN_SMS_TEMPLATE_CODE`
|
||||
- `TemplateParam = json({"code":"##code##","min": str(ALIYUN_SMS_VALID_TIME_SEC//60)})`
|
||||
- `CodeLength=ALIYUN_SMS_CODE_LENGTH`、`ValidTime=ALIYUN_SMS_VALID_TIME_SEC`、`Interval=ALIYUN_SMS_INTERVAL_SEC`
|
||||
- `SchemeName=ALIYUN_SMS_SCHEME_NAME`(可空)
|
||||
3. 成功（`body.Success and body.Code=="OK"`）→ **清本地失败计数**（新码=新预算）→ 返回 `ALIYUN_SMS_INTERVAL_SEC` 作客户端冷却秒数。
|
||||
4. 失败 → 按 §6 错误码映射抛 `SmsError`。
|
||||
|
||||
### 4.2 校验 `aliyun.verify_code(phone, code) -> bool`
|
||||
1. **本地失败计数**：`attempts >= SMS_MAX_VERIFY_ATTEMPTS` → 直接 `False`（码已作废，不调阿里云）。
|
||||
2. 调 `CheckSmsVerifyCode(PhoneNumber, VerifyCode=code, SchemeName)`。
|
||||
3. `body.Model.VerifyResult`：
|
||||
- `"PASS"` → 清计数，返回 `True`（一次性）。
|
||||
- `"UNKNOWN"` → `attempts += 1`，返回 `False`（码错/过期）。
|
||||
4. 网络错误 / 接口非 `OK` → 抛 `SmsError(503)`（**不静默返回 False**，区分"阿里云挂了"与"码错了"；网络错误不计入 attempts）。
|
||||
|
||||
本服务**不存验证码**，仅存一个 per-phone 失败计数（见 §7）。
|
||||
|
||||
## 5. 分派器 & mock（`__init__.py`）
|
||||
|
||||
```
|
||||
send_code(phone):
|
||||
if settings.SMS_MOCK: # 短路:不碰 provider(测试/开发)
|
||||
log placeholder code; return cooldown
|
||||
return _provider().send_code(phone)
|
||||
|
||||
verify_code(phone, code):
|
||||
if settings.SMS_MOCK: # 放行任意 N 位数字(沿用现 mock 语义)
|
||||
return len(code)==SMS_CODE_LENGTH and code.isdigit()
|
||||
return _provider().verify_code(phone, code)
|
||||
|
||||
_provider(): jiguang if settings.SMS_PROVIDER=="jiguang" else aliyun
|
||||
```
|
||||
|
||||
- mock 语义提到分派层、provider 无关 → 现有 28 个测试文件（conftest 设 `SMS_MOCK=true`）全部零改动通过。
|
||||
|
||||
## 6. 错误映射
|
||||
|
||||
### 发码（阿里云错误码 → SmsError.status_code）
|
||||
| 阿里云码 | HTTP | 说明 |
|
||||
|---|---|---|
|
||||
| `MOBILE_NUMBER_ILLEGAL` | 400 | 手机号格式错误 |
|
||||
| `BUSINESS_LIMIT_CONTROL` | 429 | 号码天级流控 |
|
||||
| `FREQUENCY_FAIL` | 429 | 频控（`Interval` 命中） |
|
||||
| `FUNCTION_NOT_OPENED` | 503 | 融合认证未开通（**critical 日志**，需运维开通） |
|
||||
| `INVALID_PARAMETERS` | 503 | 参数错误（配置/模板问题，**critical 日志**） |
|
||||
| 其他非 OK / `Success=false` / 网络错误 | 503 | 供应商不可用 |
|
||||
|
||||
### 校验
|
||||
- `PASS` → True；`UNKNOWN` → False；接口异常/网络错误 → `SmsError(503)`。
|
||||
|
||||
## 7. 防爆破 / 频控分工
|
||||
|
||||
| 机制 | 极光（Mode B） | 阿里云（Mode A） |
|
||||
|---|---|---|
|
||||
| 验证码存储 | 本地内存 | **阿里云托管**（消除多 worker 存码债） |
|
||||
| 单号发送冷却 | 本地 `_last_sent` 60s | **交给阿里云 `Interval`**（无本地状态），命中→429 |
|
||||
| 单设备+IP 频控 | API 层 5/时、20/天 | 同左，**不变** |
|
||||
| **防爆破（单码失败 N 次即作废）** | 本地 `_CodeRecord.attempts` | **本地 per-phone 计数**，与极光同语义（§4.2） |
|
||||
|
||||
- 阿里云路径的**唯一本地状态** = per-phone 失败计数 `dict[phone,int]` + `Lock` + GC（仿极光 `_gc`）。
|
||||
- 多 worker 降级：失败计数按 worker 各计，effective 上限 = N×workers；与极光现状**同级**（属刻意保留的一致性），且 API 层登录频控（`sms-login-device` 设备+IP 5/时）提供硬兜底。
|
||||
- 计数复位：`send_code` 成功清计数、`verify` PASS 清计数（新码/验过即新预算）。
|
||||
- API 层设备频控与测试账号短路（`app/core/test_account.py`）**完全不动**。
|
||||
|
||||
## 8. 配置项（`app/core/config.py` 新增）
|
||||
|
||||
```python
|
||||
SMS_PROVIDER: str = "jiguang" # jiguang | aliyun;默认极光(保持现状,上线后切 aliyun)
|
||||
# --- 阿里云 dypns 号码认证 ---
|
||||
ALIYUN_SMS_ACCESS_KEY_ID: str = ""
|
||||
ALIYUN_SMS_ACCESS_KEY_SECRET: str = ""
|
||||
ALIYUN_SMS_SIGN_NAME: str = "" # 系统赠送签名(自定义签名下发易失败)
|
||||
ALIYUN_SMS_TEMPLATE_CODE: str = "" # 赠送模板 CODE(须与赠送签名搭配)
|
||||
ALIYUN_SMS_SCHEME_NAME: str = "" # 方案名(可空=默认方案);send/check 必须一致 → 单一来源
|
||||
ALIYUN_SMS_ENDPOINT: str = "dypnsapi.aliyuncs.com"
|
||||
ALIYUN_SMS_CODE_LENGTH: int = 6 # CodeLength 4~8
|
||||
ALIYUN_SMS_VALID_TIME_SEC: int = 300 # ValidTime;短信内 min 文案 = //60
|
||||
ALIYUN_SMS_INTERVAL_SEC: int = 60 # Interval 单号发送频控
|
||||
```
|
||||
|
||||
- 新增属性 `aliyun_sms_configured`（仿 `mt_cps_configured`）：AK_ID/AK_SECRET/SignName/TemplateCode 齐全才为真；`SMS_PROVIDER=aliyun` 但未配 → `send_code` 抛 `SmsError(503)`。
|
||||
- 复用现有 `SMS_MOCK`、`SMS_CODE_LENGTH`（mock 校验位数）、`SMS_MAX_VERIFY_ATTEMPTS`（防爆破上限，两 provider 共用）。
|
||||
|
||||
### 配置敏感点
|
||||
- `TemplateParam` 变量名（`code`/`min`）须与控制台所选**赠送模板**一致。融合认证验证码模板通常即 `code`+`min`，按此硬编码并加注释；若模板变量名不同，改 `aliyun.py` 该处即可。
|
||||
- `SchemeName` 在 send 与 check 必须一致，故用**单一** `ALIYUN_SMS_SCHEME_NAME` 供两处，避免不匹配（CheckSmsVerifyCode 文档明确警告）。
|
||||
|
||||
## 9. auth.py 改动（最小）
|
||||
|
||||
`verify_code` 现在可能抛 `SmsError`（阿里云降级 503）。两处调用点各包一层 `try/except SmsError → HTTPException(e.status_code)`，与 `send_code` 现有写法一致：
|
||||
- `app/api/v1/auth.py` `sms_login`（约 L185）
|
||||
- `app/api/v1/auth.py` `wechat_bind_phone_sms`（约 L325）
|
||||
|
||||
`send_code` 调用点已 try/except `SmsError`，无需改。
|
||||
|
||||
## 10. 依赖 & SDK
|
||||
|
||||
- `pyproject.toml` 增 `alibabacloud_dypnsapi20170525`（连带 `alibabacloud-tea-openapi` 等）。
|
||||
- SDK 同步阻塞调用 → 与现有 sync 端点 + sync httpx 风格一致（FastAPI 跑 threadpool，无碍）。
|
||||
- `aliyun.py` 内**惰性 import SDK + 惰性建 client**（仿 `wxpay` 惰性加载证书）：`SMS_PROVIDER=jiguang` 时不加载 alibabacloud，启动保持精简。
|
||||
- SDK 调用形态（实现时按实际包名/字段核对）：
|
||||
```python
|
||||
from alibabacloud_dypnsapi20170525.client import Client
|
||||
from alibabacloud_dypnsapi20170525 import models as dypns_models
|
||||
from alibabacloud_tea_openapi import models as open_api_models
|
||||
cfg = open_api_models.Config(access_key_id=..., access_key_secret=...)
|
||||
cfg.endpoint = settings.ALIYUN_SMS_ENDPOINT
|
||||
client = Client(cfg)
|
||||
resp = client.send_sms_verify_code(dypns_models.SendSmsVerifyCodeRequest(...))
|
||||
# resp.body.code / resp.body.success / resp.body.model.verify_code
|
||||
resp = client.check_sms_verify_code(dypns_models.CheckSmsVerifyCodeRequest(...))
|
||||
# resp.body.model.verify_result == "PASS"
|
||||
```
|
||||
|
||||
## 11. 测试
|
||||
|
||||
- 现有测试：`SMS_MOCK=true` → 分派器短路，全绿不变。
|
||||
- 新增 `tests/test_sms_aliyun.py`（monkeypatch SDK client，不发真网络）：
|
||||
1. 发码成功 → 返回 cooldown、清计数。
|
||||
2. 各错误码 → 对应 `SmsError.status_code`（400/429/503）。
|
||||
3. 校验 `PASS`→True（清计数）/ `UNKNOWN`→False（计数 +1）/ 接口异常→`SmsError(503)`。
|
||||
4. 失败计数达 `SMS_MAX_VERIFY_ATTEMPTS` → 直接 False，不再调阿里云。
|
||||
5. `send_code` 成功复位计数。
|
||||
- 新增分派测试：`SMS_PROVIDER` 切换选中正确 provider；`SMS_MOCK` 优先于 provider。
|
||||
|
||||
## 12. YAGNI（明确不做）
|
||||
|
||||
- ❌ 不做 Redis/DB 存码（Mode A 无需；极光路径内存债维持现状，非本次范围）。
|
||||
- ❌ 不改极光任何行为、不动 API 层频控/测试账号逻辑。
|
||||
- ❌ 不做多签名/多模板轮换（单签名单模板足够）。
|
||||
- ❌ 不把失败计数持久化/跨进程（刻意保留与极光同级的本地态）。
|
||||
|
||||
## 13. 验收标准
|
||||
|
||||
- `SMS_PROVIDER=aliyun` 且配置齐全时：`/sms/send` 走 `SendSmsVerifyCode`、`/sms/login` 走 `CheckSmsVerifyCode`，真机可收码并登录。
|
||||
- `SMS_PROVIDER=jiguang`（默认）：行为与当前完全一致。
|
||||
- `SMS_MOCK=true`：任意 N 位数字通过，不发真短信。
|
||||
- 阿里云接口异常时：`/sms/login` 返回 503（非 400），日志可区分。
|
||||
- `ruff check .` 通过；新增/现有 `pytest` 全绿。
|
||||
@@ -1,143 +0,0 @@
|
||||
# 创蓝云智(253)短信验证服务 — 设计方案
|
||||
|
||||
- 日期：2026-07-26
|
||||
- 状态：已定稿，待实现
|
||||
- 范围：新增创蓝云智（253/蓝创云智）模板短信 provider，与现有极光 / 阿里云可切换
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
短信验证码服务已是**可切换 provider** 架构（`app/integrations/sms/`：`__init__` 分派 + `jiguang` / `aliyun` + `base`）。本次接入第三家 **创蓝云智** 作为新 provider。
|
||||
|
||||
创蓝 `tpl/send` v2 接口（调研见 `docs/integrations/chuanglan/tpl-send.md`）是**纯发送网关**：本服务生成验证码、放入 `templateParamJson`，创蓝只负责下发，**无校验接口**。故属 **Mode B（自管码）**，与极光同模式（本地生成/存储/校验），仅"发送调用"不同。
|
||||
|
||||
目标：接入创蓝作为可切换 provider；默认仍极光，opt-in 切换，灰度可秒回退。
|
||||
|
||||
## 2. 关键决策（已确认）
|
||||
|
||||
1. **Mode B 自管码**：本服务 `secrets` 生成 N 位码 → 存进程内存 → 创蓝 REST 只下发；`verify_code` 比对本地存码（一次性 + 失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废）。与极光同语义。
|
||||
2. **代码组织 = 隔离复制（不重构极光）**：`chuanglan.py` **自带一份**存码/冷却/校验机器（从 `jiguang.py` 复制适配），**极光文件一行不动**。契合阿里云先例的 provider 隔离哲学，零回归风险于登录关键路径的默认 provider。代价：Mode B 并发逻辑在 jiguang / chuanglan 两处重复，日后改动需同步（YAGNI 权衡，已接受）。
|
||||
3. **鉴权 = HMAC 签名头**（`X-QA-Hmac-Signature`）：password 仅用于本地算签、**不上行**。不做明文密码 body 模式。
|
||||
4. **无新依赖**：创蓝是普通 HTTPS POST，复用现有 `httpx` + 标准库 `hashlib`/`hmac`（对比阿里云需 SDK）。
|
||||
5. **可切换 + 回退**：`SMS_PROVIDER` 增 `chuanglan`；默认仍 `jiguang`；误配/未知值一律回退 `jiguang`（保持 `test_unknown_provider_falls_back_to_jiguang` 语义）。
|
||||
|
||||
## 3. 模块结构
|
||||
|
||||
```
|
||||
app/integrations/sms/
|
||||
__init__.py # 分派器: {"aliyun":aliyun,"chuanglan":chuanglan}.get(SMS_PROVIDER, jiguang)
|
||||
base.py # 不动(SmsError / mock_verify 复用)
|
||||
jiguang.py # 不动
|
||||
aliyun.py # 不动
|
||||
chuanglan.py # 新增(本设计)
|
||||
```
|
||||
|
||||
- `__init__.py` 继续 re-export `SmsError / send_code / verify_code`，`app/api/v1/auth.py` 导入不变。
|
||||
- 纯增量：只新增 `chuanglan.py` + 扩分派 dict + 加配置；不改极光/阿里云行为。
|
||||
|
||||
## 4. 数据流 — chuanglan provider（Mode B，复制自 jiguang）
|
||||
|
||||
### 4.1 发码 `chuanglan.send_code(phone) -> int`
|
||||
结构与 `jiguang.send_code` 一致：
|
||||
1. `_lock` 内：`_gc` → 单号冷却检查（`_last_sent`，`SMS_SEND_INTERVAL_SEC`，命中→`SmsError(429)`）→ `_gen_code()` 生成 N 位 → **预占**（写 `_last_sent` + `_codes[phone]=_CodeRecord(code, expires_at=now+SMS_CODE_TTL_SEC)`）。
|
||||
2. `_lock` 外：`SMS_MOCK` → 打日志不真发；否则 `_send_via_chuanglan(phone, code)`。
|
||||
3. 失败：**保留冷却**（失败也限速）、`_codes.pop(phone)`（没发出去的码删掉）；`SmsError` 原样抛，其他异常 → `SmsError(503)`。
|
||||
4. 返回 `SMS_SEND_INTERVAL_SEC` 作客户端冷却秒数。
|
||||
|
||||
### 4.2 校验 `chuanglan.verify_code(phone, code) -> bool`
|
||||
与 `jiguang.verify_code` 一致：
|
||||
- `SMS_MOCK` → `mock_verify`（放行任意 N 位数字）。
|
||||
- real：`_lock` 内查 `_codes[phone]`；不存在/过期→False（并清）；`attempts >= SMS_MAX_VERIFY_ATTEMPTS`→清+False（防爆破）；`secrets.compare_digest` 匹配→清+True（一次性）；否则 `attempts += 1` 返 False。
|
||||
|
||||
### 4.3 发送 `_send_via_chuanglan(phone, code)`（唯一新逻辑）
|
||||
1. 配置校验 `settings.chuanglan_sms_configured`（缺 account/password/templateId → `SmsError(503)`）。
|
||||
2. 组装：
|
||||
- `timestamp = str(int(time.time()))`、`nonce = secrets.token_hex(16)`（32 hex）
|
||||
- `body = {account, timestamp, nonce, phoneNumbers=phone, templateId, templateParamJson=json.dumps([{"param1": code}])}`；`CHUANGLAN_SMS_SIGNATURE` 非空则加 `signature` 字段。**HMAC 方式 body 不含 password。**
|
||||
3. 签名 `_sign(password, timestamp, nonce)`：
|
||||
```
|
||||
md5pwd = md5(password).hexdigest() # 32 位小写 hex
|
||||
s = "".join(sorted([md5pwd, timestamp, nonce])) # 字典序升序拼接
|
||||
s = "".join(s.split()) # 去空白(faithful，本例无空白)
|
||||
sig = hmac_sha256(key=md5pwd.encode(), msg=s.encode()).hexdigest() # 小写 hex
|
||||
```
|
||||
置请求头 `X-QA-Hmac-Signature: sig`、`Content-Type: application/json`。
|
||||
4. `httpx.post(CHUANGLAN_SMS_ENDPOINT, json=body, headers=..., timeout=CHUANGLAN_SMS_TIMEOUT_SEC)`；网络异常 → `SmsError(503)`。
|
||||
5. 解析 `resp.json()`：`code == "000000"` → 成功返回；否则按 §5 映射抛 `SmsError`。HTTP≠200 或 JSON 解析失败 → `SmsError(503)`。
|
||||
|
||||
## 5. 错误码映射（创蓝 `code` → SmsError.status_code）
|
||||
|
||||
| 创蓝 code | HTTP | 处理 |
|
||||
|---|---|---|
|
||||
| `000000` | — | 成功 return |
|
||||
| `103` | 429 | 超频，"发送过于频繁，请稍后再试" |
|
||||
| `107` | 400 | 手机号错误，"手机号无效" |
|
||||
| `109` | 503 | 无发送量/余额 → **critical 日志**（需充值） |
|
||||
| `117` | 503 | IP 未白名单 → **critical 日志**（需运维加白） |
|
||||
| `102` / `116` / `124` / `152` / `101` / `118` | 503 | 密码/签名/模板/账号/权限配置错 → **critical 日志** |
|
||||
| 其他 / `Success` 非 000000 / HTTP≠200 / 网络错 | 503 | "短信服务暂不可用，请稍后重试" |
|
||||
|
||||
- 映射用 `_SEND_ERRORS: dict[str,(int,str)]` + `_SEND_CRITICAL_CODES: frozenset`（仿 aliyun 写法）。
|
||||
|
||||
## 6. 防爆破 / 频控分工（与极光同级）
|
||||
|
||||
| 机制 | 实现 |
|
||||
|---|---|
|
||||
| 验证码存储 | 本地进程内存 `_codes`（与极光同，多 worker 不共享的技术债同级） |
|
||||
| 单号发送冷却 | 本地 `_last_sent`，`SMS_SEND_INTERVAL_SEC` |
|
||||
| 单设备+IP 频控 | API 层（`app/api/v1/auth.py`），**不变** |
|
||||
| 防爆破（单码失败 N 次作废）| 本地 `_CodeRecord.attempts`，`SMS_MAX_VERIFY_ATTEMPTS` |
|
||||
|
||||
- 创蓝控制台侧另建议叠加：**IP 白名单**（否则 117）+ 发送频控。
|
||||
|
||||
## 7. 配置项（`app/core/config.py` 新增）
|
||||
|
||||
```python
|
||||
SMS_PROVIDER: Literal["jiguang", "aliyun", "chuanglan"] = "jiguang"
|
||||
# --- 创蓝云智(253)模板短信,Mode B 自管码,httpx 直连 + HMAC 签名 ---
|
||||
CHUANGLAN_SMS_ACCOUNT: str = "" # YZM 前缀验证码账号
|
||||
CHUANGLAN_SMS_PASSWORD: str = "" # API 密码(仅本地算签,不上行)
|
||||
CHUANGLAN_SMS_TEMPLATE_ID: str = "" # 模板 ID
|
||||
CHUANGLAN_SMS_SIGNATURE: str = "" # 短信签名文案【品牌】;模板已带签名则留空
|
||||
CHUANGLAN_SMS_ENDPOINT: str = "https://smssh.253.com/msg/sms/v2/tpl/send"
|
||||
CHUANGLAN_SMS_TIMEOUT_SEC: int = 10 # httpx 读/连超时
|
||||
```
|
||||
|
||||
- 新增属性 `chuanglan_sms_configured`（仿 `aliyun_sms_configured`）：account/password/templateId 齐全才为真。
|
||||
- 复用 `SMS_MOCK` / `SMS_CODE_LENGTH` / `SMS_CODE_TTL_SEC` / `SMS_SEND_INTERVAL_SEC` / `SMS_MAX_VERIFY_ATTEMPTS`（provider 无关的 Mode B 旋钮）。
|
||||
- `.env.example` 增 `CHUANGLAN_SMS_*` 块 + 注释。
|
||||
|
||||
### 模板变量敏感点
|
||||
- 默认按**单占位** `templateParamJson=[{"param1": code}]`（模板形如「您的验证码 {s}，5分钟内有效」）。
|
||||
- 若控制台模板把「有效分钟」也做成第二个 `{s}`，实现时在此加 `param2`（改 `chuanglan.py` 一处）。
|
||||
|
||||
## 8. auth.py 改动
|
||||
|
||||
无。`send_code` / `verify_code` 签名与返回不变，分派层内部路由；两调用点现有 `try/except SmsError` 已覆盖 chuanglan 的 429/400/503。
|
||||
|
||||
## 9. 测试
|
||||
|
||||
- 现有测试：`SMS_MOCK=true` → 分派器短路，全绿不变。
|
||||
- 新增 `tests/test_sms_chuanglan.py`（monkeypatch `_send_via_chuanglan` 内 httpx 接缝，不发真网络）：
|
||||
1. 发码成功（`code=000000`）→ 返回 cooldown、码入内存。
|
||||
2. 各错误码 → 对应 `SmsError.status_code`（103→429 / 107→400 / 109/117/其他→503）。
|
||||
3. HTTP≠200 / 网络异常 → `SmsError(503)`。
|
||||
4. 校验：匹配→True 且作废（一次性）；过期→False；失败累计达上限→作废 False；不匹配→attempts+1 False。
|
||||
5. 冷却：`SMS_SEND_INTERVAL_SEC` 内二次发 → `SmsError(429)`。
|
||||
6. `_sign` 签名算法：对固定 (password, ts, nonce) 断言 HMAC 输出（独立复算比对）。
|
||||
- 扩 `tests/test_sms_dispatch.py`：`SMS_PROVIDER=chuanglan` 路由命中 chuanglan；未知值回退 jiguang。
|
||||
|
||||
## 10. YAGNI（明确不做）
|
||||
|
||||
- ❌ 不重构极光 / 不动阿里云。
|
||||
- ❌ 不做明文密码 body 模式（只 HMAC）。
|
||||
- ❌ 不做状态回执 `report` / `callbackUrl`。
|
||||
- ❌ 不做批量发送（验证码单号）。
|
||||
- ❌ 不做 DB/Redis 存码（与极光同级内存态，多 worker 债维持现状）。
|
||||
|
||||
## 11. 验收标准
|
||||
|
||||
- `SMS_PROVIDER=chuanglan` 且配置齐全时：`/sms/send` 走创蓝 `tpl/send`、`/sms/login` 本地校验，真机可收码并登录。
|
||||
- `SMS_PROVIDER=jiguang`（默认）/ `aliyun`：行为与当前完全一致。
|
||||
- `SMS_MOCK=true`：任意 N 位数字通过，不真发。
|
||||
- 创蓝接口异常时：`/sms/send` 返回对应码（429/400/503），日志可区分（余额/白名单打 critical）。
|
||||
- `ruff check .` 通过；新增/现有 `pytest` 全绿。
|
||||
@@ -29,9 +29,6 @@ dependencies = [
|
||||
# HTTP 客户端 (调极光 REST)
|
||||
"httpx>=0.27.0",
|
||||
|
||||
# 阿里云号码认证(dypns)短信验证码 provider(SMS_PROVIDER=aliyun 时用;签名由 SDK 处理)
|
||||
"alibabacloud_dypnsapi20170525>=2.0.0",
|
||||
|
||||
# multipart form (FastAPI 表单上传依赖)
|
||||
"python-multipart>=0.0.9",
|
||||
|
||||
|
||||
@@ -175,22 +175,22 @@ def seed(db) -> list[Feedback]:
|
||||
# 普通反馈 · 新端(带环境快照)· 无图
|
||||
fb("13255550001", "签到金币到账有时候会延迟一两分钟,能不能做成实时到账?",
|
||||
source="profile",
|
||||
app_version="2.3.1", device_model="PJA110", rom_name="ColorOS", android_version="14",
|
||||
app_version="2.3.1", device_model="PJA110", rom_name="ColorOS 14", android_version="14",
|
||||
created=ago(minutes=6)),
|
||||
# 比价反馈 · scene=优惠不对 · 新端 · 2 图
|
||||
fb("13255550002", "这家店京东外卖的到手价比你们算出来的最低价还低,截图为证,麻烦核实。",
|
||||
source="comparison", scene="优惠不对", images=[imgs[0], imgs[1]],
|
||||
app_version="2.3.1", device_model="M2012K11AC", rom_name="MIUI", android_version="13",
|
||||
app_version="2.3.1", device_model="M2012K11AC", rom_name="MIUI 14", android_version="13",
|
||||
created=ago(minutes=22)),
|
||||
# 比价反馈 · scene=找错商品 · 新端 · 无图
|
||||
fb("13255550002", "比价结果里的商品跟我搜的不是同一个规格,数量对不上。",
|
||||
source="comparison", scene="找错商品",
|
||||
app_version="2.3.0", device_model="V2309A", rom_name="OriginOS", android_version="14",
|
||||
app_version="2.3.0", device_model="V2309A", rom_name="OriginOS 4", android_version="14",
|
||||
created=ago(hours=1)),
|
||||
# 普通反馈 · 新端 · 1 图(表扬 + 小问题)
|
||||
fb("13255550003", "提现秒到账,好评!顺手反馈个小 bug:金币记录页偶尔白屏,要退出去重进。",
|
||||
source="profile", images=[imgs[2]],
|
||||
app_version="2.3.1", device_model="23078RKD5C", rom_name="MIUI", android_version="14",
|
||||
app_version="2.3.1", device_model="23078RKD5C", rom_name="MIUI 14", android_version="14",
|
||||
created=ago(hours=3)),
|
||||
# 比价反馈 · scene=比价太慢 · 历史数据(env 全 NULL、contact 有值)
|
||||
fb("13255550004", "比价转圈太久了,经常要等十几秒才出结果,体验不太好。",
|
||||
@@ -206,7 +206,7 @@ def seed(db) -> list[Feedback]:
|
||||
source="profile", images=[imgs[3]],
|
||||
status="adopted", reward_coins=2000,
|
||||
review_note="有效产品建议,已排期到 2.4.0", admin_reply="感谢反馈!该功能已在规划中,金币奖励已发放~",
|
||||
app_version="2.2.8", device_model="PJA110", rom_name="ColorOS", android_version="13",
|
||||
app_version="2.2.8", device_model="PJA110", rom_name="ColorOS 13", android_version="13",
|
||||
created=ago(days=2)),
|
||||
|
||||
# ===== 未采纳 rejected(带原因 + 回复)=====
|
||||
@@ -214,7 +214,7 @@ def seed(db) -> list[Feedback]:
|
||||
source="comparison", scene="价格不准",
|
||||
status="rejected", reject_reason="截图价格为限时活动价且已过期,不满足「长期可复现更低价」条件,暂不采纳。",
|
||||
admin_reply="感谢参与,本次未通过,欢迎继续上报有效更低价~",
|
||||
app_version="2.3.0", device_model="M2012K11AC", rom_name="MIUI", android_version="13",
|
||||
app_version="2.3.0", device_model="M2012K11AC", rom_name="MIUI 14", android_version="13",
|
||||
created=ago(days=3)),
|
||||
]
|
||||
db.add_all(feedbacks)
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
from datetime import datetime, timedelta, timezone
|
||||
|
||||
from app.admin.repositories import queries
|
||||
from app.db.session import SessionLocal
|
||||
from app.models.comparison import ComparisonRecord
|
||||
from app.models.feedback import Feedback
|
||||
from app.repositories import user as user_repo
|
||||
|
||||
|
||||
def test_feedback_device_details_use_same_user_and_model() -> None:
|
||||
with SessionLocal() as db:
|
||||
submitted_at = datetime.now(timezone.utc)
|
||||
user = user_repo.upsert_user_for_login(
|
||||
db,
|
||||
phone="13800009876",
|
||||
register_channel="sms",
|
||||
)
|
||||
db.add_all(
|
||||
[
|
||||
ComparisonRecord(
|
||||
user_id=user.id,
|
||||
trace_id="feedback-device-v2166ba",
|
||||
device_model="V2166BA",
|
||||
device_manufacturer="vivo",
|
||||
rom_name="OriginOS",
|
||||
rom_version=13,
|
||||
created_at=submitted_at - timedelta(minutes=5),
|
||||
),
|
||||
ComparisonRecord(
|
||||
user_id=user.id,
|
||||
trace_id="feedback-device-other",
|
||||
device_model="OTHER-CODE",
|
||||
device_manufacturer="Other",
|
||||
rom_name="OtherOS",
|
||||
rom_version=99,
|
||||
created_at=submitted_at - timedelta(minutes=5),
|
||||
),
|
||||
ComparisonRecord(
|
||||
user_id=user.id,
|
||||
trace_id="feedback-device-future-upgrade",
|
||||
device_model="V2166BA",
|
||||
device_manufacturer="vivo-new",
|
||||
rom_name="OriginOS",
|
||||
rom_version=99,
|
||||
created_at=submitted_at + timedelta(minutes=5),
|
||||
),
|
||||
Feedback(
|
||||
user_id=user.id,
|
||||
content="设备信息补全测试",
|
||||
contact="",
|
||||
status="pending",
|
||||
device_model="V2166BA",
|
||||
rom_name="OriginOS",
|
||||
android_version="13",
|
||||
created_at=submitted_at,
|
||||
),
|
||||
]
|
||||
)
|
||||
db.commit()
|
||||
|
||||
items, _next_cursor, total = queries.list_feedbacks(
|
||||
db,
|
||||
user_id=user.id,
|
||||
limit=20,
|
||||
)
|
||||
|
||||
assert total == 1
|
||||
assert items[0].device_model == "V2166BA"
|
||||
assert items[0].device_model_name == "vivo Y77e"
|
||||
assert items[0].device_manufacturer == "vivo"
|
||||
assert items[0].rom_version == 13
|
||||
+39
-40
@@ -11,13 +11,12 @@ import time
|
||||
import pytest
|
||||
|
||||
from app.integrations import sms
|
||||
from app.integrations.sms import jiguang
|
||||
|
||||
|
||||
def _reset(phone: str) -> None:
|
||||
"""清该号的进程内存状态,隔离 real 模式用例。"""
|
||||
jiguang._codes.pop(phone, None)
|
||||
jiguang._last_sent.pop(phone, None)
|
||||
sms._codes.pop(phone, None)
|
||||
sms._last_sent.pop(phone, None)
|
||||
|
||||
|
||||
class _OkResp:
|
||||
@@ -228,16 +227,16 @@ def test_sms_real_send_calls_jiguang(monkeypatch) -> None:
|
||||
captured.update(url=url, body=json, auth=headers.get("Authorization", ""))
|
||||
return _OkResp()
|
||||
|
||||
monkeypatch.setattr(jiguang.settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(jiguang.httpx, "post", _fake_post)
|
||||
monkeypatch.setattr(sms.settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(sms.httpx, "post", _fake_post)
|
||||
|
||||
jiguang.send_code(phone)
|
||||
sms.send_code(phone)
|
||||
|
||||
assert captured["url"] == jiguang.settings.SMS_SEND_ENDPOINT
|
||||
assert captured["url"] == sms.settings.SMS_SEND_ENDPOINT
|
||||
assert captured["body"]["mobile"] == phone
|
||||
assert captured["body"]["sign_id"] == jiguang.settings.SMS_SIGN_ID
|
||||
assert captured["body"]["temp_id"] == jiguang.settings.SMS_TEMPLATE_ID
|
||||
assert captured["body"]["temp_para"]["code"] == jiguang._codes[phone].code
|
||||
assert captured["body"]["sign_id"] == sms.settings.SMS_SIGN_ID
|
||||
assert captured["body"]["temp_id"] == sms.settings.SMS_TEMPLATE_ID
|
||||
assert captured["body"]["temp_para"]["code"] == sms._codes[phone].code
|
||||
assert captured["auth"].startswith("Basic ")
|
||||
|
||||
|
||||
@@ -245,33 +244,33 @@ def test_sms_real_verify_one_time_and_wrong(monkeypatch) -> None:
|
||||
"""real 校验:错误码拒(不消费)→ 正确码成功 → 验过即作废。"""
|
||||
phone = "13455134000"
|
||||
_reset(phone)
|
||||
monkeypatch.setattr(jiguang.settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(jiguang.httpx, "post", lambda *a, **k: _OkResp())
|
||||
monkeypatch.setattr(sms.settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(sms.httpx, "post", lambda *a, **k: _OkResp())
|
||||
|
||||
jiguang.send_code(phone)
|
||||
code = jiguang._codes[phone].code
|
||||
sms.send_code(phone)
|
||||
code = sms._codes[phone].code
|
||||
wrong = "000000" if code != "000000" else "111111"
|
||||
|
||||
assert jiguang.verify_code(phone, wrong) is False
|
||||
assert jiguang.verify_code(phone, code) is True
|
||||
assert jiguang.verify_code(phone, code) is False # 已作废
|
||||
assert sms.verify_code(phone, wrong) is False
|
||||
assert sms.verify_code(phone, code) is True
|
||||
assert sms.verify_code(phone, code) is False # 已作废
|
||||
|
||||
|
||||
def test_sms_real_verify_attempts_exhausted(monkeypatch) -> None:
|
||||
"""real 校验:错误次数到上限即作废,正确码也不再通过(防爆破)。"""
|
||||
phone = "13466134000"
|
||||
_reset(phone)
|
||||
monkeypatch.setattr(jiguang.settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(jiguang.settings, "SMS_MAX_VERIFY_ATTEMPTS", 3)
|
||||
monkeypatch.setattr(jiguang.httpx, "post", lambda *a, **k: _OkResp())
|
||||
monkeypatch.setattr(sms.settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(sms.settings, "SMS_MAX_VERIFY_ATTEMPTS", 3)
|
||||
monkeypatch.setattr(sms.httpx, "post", lambda *a, **k: _OkResp())
|
||||
|
||||
jiguang.send_code(phone)
|
||||
code = jiguang._codes[phone].code
|
||||
sms.send_code(phone)
|
||||
code = sms._codes[phone].code
|
||||
wrong = "000000" if code != "000000" else "111111"
|
||||
|
||||
for _ in range(3):
|
||||
assert jiguang.verify_code(phone, wrong) is False
|
||||
assert jiguang.verify_code(phone, code) is False # 超限作废
|
||||
assert sms.verify_code(phone, wrong) is False
|
||||
assert sms.verify_code(phone, code) is False # 超限作废
|
||||
|
||||
|
||||
def test_sms_real_balance_error_keeps_cooldown(monkeypatch) -> None:
|
||||
@@ -285,36 +284,36 @@ def test_sms_real_balance_error_keeps_cooldown(monkeypatch) -> None:
|
||||
def json(self):
|
||||
return {"error": {"code": 50014, "message": "no money"}}
|
||||
|
||||
monkeypatch.setattr(jiguang.settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(jiguang.httpx, "post", lambda *a, **k: _ErrResp())
|
||||
monkeypatch.setattr(sms.settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(sms.httpx, "post", lambda *a, **k: _ErrResp())
|
||||
|
||||
with pytest.raises(sms.SmsError) as ei:
|
||||
jiguang.send_code(phone)
|
||||
sms.send_code(phone)
|
||||
assert ei.value.status_code == 503
|
||||
assert phone not in jiguang._codes # 没发出去的码已清
|
||||
assert phone in jiguang._last_sent # 冷却保留:失败也限速
|
||||
assert phone not in sms._codes # 没发出去的码已清
|
||||
assert phone in sms._last_sent # 冷却保留:失败也限速
|
||||
|
||||
# 立即重试 → 被冷却挡下(429),不会再打极光
|
||||
with pytest.raises(sms.SmsError) as ei2:
|
||||
jiguang.send_code(phone)
|
||||
sms.send_code(phone)
|
||||
assert ei2.value.status_code == 429
|
||||
|
||||
|
||||
def test_sms_gc_purges_stale_only(monkeypatch) -> None:
|
||||
"""GC 清过期码 / 旧冷却,但不动今天有效的(阈值设 0 强制每次扫)。"""
|
||||
monkeypatch.setattr(jiguang, "_GC_THRESHOLD", 0)
|
||||
jiguang._codes.clear()
|
||||
jiguang._last_sent.clear()
|
||||
monkeypatch.setattr(sms, "_GC_THRESHOLD", 0)
|
||||
sms._codes.clear()
|
||||
sms._last_sent.clear()
|
||||
now = time.time()
|
||||
jiguang._codes["stale"] = jiguang._CodeRecord(code="111111", expires_at=now - 1)
|
||||
jiguang._codes["fresh"] = jiguang._CodeRecord(code="222222", expires_at=now + 999)
|
||||
jiguang._last_sent["old"] = now - 99999
|
||||
jiguang._last_sent["recent"] = now
|
||||
sms._codes["stale"] = sms._CodeRecord(code="111111", expires_at=now - 1)
|
||||
sms._codes["fresh"] = sms._CodeRecord(code="222222", expires_at=now + 999)
|
||||
sms._last_sent["old"] = now - 99999
|
||||
sms._last_sent["recent"] = now
|
||||
|
||||
jiguang._gc(now)
|
||||
sms._gc(now)
|
||||
|
||||
assert "stale" not in jiguang._codes and "fresh" in jiguang._codes
|
||||
assert "old" not in jiguang._last_sent and "recent" in jiguang._last_sent
|
||||
assert "stale" not in sms._codes and "fresh" in sms._codes
|
||||
assert "old" not in sms._last_sent and "recent" in sms._last_sent
|
||||
|
||||
|
||||
# ============================ 用户名 / 默认昵称 ============================
|
||||
|
||||
@@ -1,185 +0,0 @@
|
||||
"""阿里云短信 provider(Mode A)单元测试。
|
||||
|
||||
SDK 交互隔离在 aliyun._call_send / aliyun._call_check 两个薄封装,本文件全程 monkeypatch
|
||||
它们(返回归一化结果 dict 或抛 SmsError)→ 不触真 SDK、不发网络。测的是 provider 的可映射逻辑:
|
||||
错误码→HTTP 码、PASS/UNKNOWN 解释、本地失败计数(与极光同语义)、mock 短路。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
|
||||
from app.core.config import settings
|
||||
from app.integrations.sms import aliyun
|
||||
from app.integrations.sms.base import SmsError
|
||||
|
||||
PHONE = "13800138000"
|
||||
|
||||
|
||||
def _configure(monkeypatch, *, mock: bool = False) -> None:
|
||||
"""配齐阿里云凭证 + 设 SMS_MOCK;清本地失败计数隔离用例。"""
|
||||
monkeypatch.setattr(settings, "SMS_MOCK", mock)
|
||||
monkeypatch.setattr(settings, "ALIYUN_SMS_ACCESS_KEY_ID", "ak")
|
||||
monkeypatch.setattr(settings, "ALIYUN_SMS_ACCESS_KEY_SECRET", "sk")
|
||||
monkeypatch.setattr(settings, "ALIYUN_SMS_SIGN_NAME", "恒创联众")
|
||||
monkeypatch.setattr(settings, "ALIYUN_SMS_TEMPLATE_CODE", "SMS_100001")
|
||||
aliyun._verify_attempts.clear()
|
||||
|
||||
|
||||
def _send_ok(phone):
|
||||
return {"success": True, "code": "OK", "message": "成功", "verify_code": "1234"}
|
||||
|
||||
|
||||
def _check(result):
|
||||
def _f(phone, code):
|
||||
return {"success": True, "code": "OK", "message": "成功", "verify_result": result}
|
||||
return _f
|
||||
|
||||
|
||||
# ============================ 发码 ============================
|
||||
|
||||
def test_send_success_returns_interval_and_resets_attempts(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
aliyun._verify_attempts[PHONE] = 3 # 旧失败计数
|
||||
monkeypatch.setattr(aliyun, "_call_send", _send_ok)
|
||||
|
||||
assert aliyun.send_code(PHONE) == settings.ALIYUN_SMS_INTERVAL_SEC
|
||||
assert PHONE not in aliyun._verify_attempts # 新码 = 新预算
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"code,expected",
|
||||
[
|
||||
("MOBILE_NUMBER_ILLEGAL", 400),
|
||||
("BUSINESS_LIMIT_CONTROL", 429),
|
||||
("FREQUENCY_FAIL", 429),
|
||||
("FUNCTION_NOT_OPENED", 503),
|
||||
("INVALID_PARAMETERS", 503),
|
||||
("SOME_UNEXPECTED_CODE", 503),
|
||||
],
|
||||
)
|
||||
def test_send_maps_error_codes(monkeypatch, code, expected) -> None:
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(
|
||||
aliyun, "_call_send",
|
||||
lambda phone: {"success": False, "code": code, "message": code, "verify_code": None},
|
||||
)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
aliyun.send_code(PHONE)
|
||||
assert ei.value.status_code == expected
|
||||
|
||||
|
||||
def test_send_not_configured_raises_503_without_calling_aliyun(monkeypatch) -> None:
|
||||
monkeypatch.setattr(settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(settings, "ALIYUN_SMS_ACCESS_KEY_ID", "") # 凭证缺
|
||||
|
||||
def _boom(phone):
|
||||
raise AssertionError("未配置时不应调用阿里云")
|
||||
|
||||
monkeypatch.setattr(aliyun, "_call_send", _boom)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
aliyun.send_code(PHONE)
|
||||
assert ei.value.status_code == 503
|
||||
|
||||
|
||||
def test_send_transport_error_propagates_503(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
|
||||
def _boom(phone):
|
||||
raise SmsError("network down", status_code=503)
|
||||
|
||||
monkeypatch.setattr(aliyun, "_call_send", _boom)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
aliyun.send_code(PHONE)
|
||||
assert ei.value.status_code == 503
|
||||
|
||||
|
||||
def test_send_mock_returns_interval_no_network(monkeypatch) -> None:
|
||||
_configure(monkeypatch, mock=True)
|
||||
|
||||
def _boom(phone):
|
||||
raise AssertionError("mock 不应调用阿里云")
|
||||
|
||||
monkeypatch.setattr(aliyun, "_call_send", _boom)
|
||||
assert aliyun.send_code(PHONE) == settings.ALIYUN_SMS_INTERVAL_SEC
|
||||
|
||||
|
||||
# ============================ 校验 ============================
|
||||
|
||||
def test_verify_pass_true_and_clears_attempts(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
aliyun._verify_attempts[PHONE] = 2
|
||||
monkeypatch.setattr(aliyun, "_call_check", _check("PASS"))
|
||||
|
||||
assert aliyun.verify_code(PHONE, "1234") is True
|
||||
assert PHONE not in aliyun._verify_attempts # 验过即清
|
||||
|
||||
|
||||
def test_verify_unknown_false_and_increments(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(aliyun, "_call_check", _check("UNKNOWN"))
|
||||
|
||||
assert aliyun.verify_code(PHONE, "0000") is False
|
||||
assert aliyun._verify_attempts[PHONE] == 1
|
||||
assert aliyun.verify_code(PHONE, "0000") is False
|
||||
assert aliyun._verify_attempts[PHONE] == 2
|
||||
|
||||
|
||||
def test_verify_attempts_cap_short_circuits(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
aliyun._verify_attempts[PHONE] = settings.SMS_MAX_VERIFY_ATTEMPTS
|
||||
|
||||
def _boom(phone, code):
|
||||
raise AssertionError("达失败上限后不应再调阿里云")
|
||||
|
||||
monkeypatch.setattr(aliyun, "_call_check", _boom)
|
||||
assert aliyun.verify_code(PHONE, "1234") is False # 本地作废
|
||||
|
||||
|
||||
def test_verify_api_error_raises_503(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(
|
||||
aliyun, "_call_check",
|
||||
lambda phone, code: {"success": False, "code": "SYSTEM_ERROR",
|
||||
"message": "err", "verify_result": None},
|
||||
)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
aliyun.verify_code(PHONE, "1234")
|
||||
assert ei.value.status_code == 503
|
||||
|
||||
|
||||
def test_verify_transport_error_raises_503(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
|
||||
def _boom(phone, code):
|
||||
raise SmsError("network down", status_code=503)
|
||||
|
||||
monkeypatch.setattr(aliyun, "_call_check", _boom)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
aliyun.verify_code(PHONE, "1234")
|
||||
assert ei.value.status_code == 503
|
||||
|
||||
|
||||
def test_verify_mock_passes_any_ndigit(monkeypatch) -> None:
|
||||
_configure(monkeypatch, mock=True)
|
||||
|
||||
def _boom(phone, code):
|
||||
raise AssertionError("mock 不应调用阿里云")
|
||||
|
||||
monkeypatch.setattr(aliyun, "_call_check", _boom)
|
||||
assert aliyun.verify_code(PHONE, "123456") is True # 6 位数字放行
|
||||
assert aliyun.verify_code(PHONE, "12345") is False # 位数不对
|
||||
|
||||
|
||||
# ============================ 端点:阿里云降级 → 503(auth.py 包 try/except)============================
|
||||
|
||||
def test_sms_login_aliyun_outage_returns_503(client, monkeypatch) -> None:
|
||||
"""SMS_PROVIDER=aliyun 且校验时阿里云异常 → /sms/login 返 503(而非 400/500),便于区分排查。"""
|
||||
_configure(monkeypatch) # 配齐凭证 + SMS_MOCK=False + 清计数
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "aliyun")
|
||||
|
||||
def _boom(phone, code):
|
||||
raise SmsError("aliyun down", status_code=503)
|
||||
|
||||
monkeypatch.setattr(aliyun, "_call_check", _boom)
|
||||
r = client.post("/api/v1/auth/sms/login", json={"phone": "13812345678", "code": "1234"})
|
||||
assert r.status_code == 503, r.text
|
||||
@@ -1,286 +0,0 @@
|
||||
"""创蓝云智(253)短信 provider(Mode B 自管码)单元测试。
|
||||
|
||||
HTTP 交互隔离在 chuanglan._call_chuanglan(薄封装:签名 + httpx POST + 解析),映射逻辑在
|
||||
chuanglan._send_via_chuanglan。本文件 monkeypatch 这两个接缝(或更底层 httpx.post)→ 不发真网络。
|
||||
测的是:HMAC 签名算法、请求体不上行 password、错误码→HTTP 码、自管码存/校验(与极光同语义)、mock 短路。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import hmac
|
||||
import json
|
||||
import time
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from app.core.config import settings
|
||||
from app.integrations.sms import chuanglan
|
||||
from app.integrations.sms.base import SmsError
|
||||
|
||||
PHONE = "13800138000"
|
||||
|
||||
|
||||
class _FakeResp:
|
||||
"""极简 httpx.Response 替身:只暴露 status_code / json() / text。"""
|
||||
|
||||
def __init__(self, status_code: int = 200, payload: dict | None = None, text: str = "") -> None:
|
||||
self.status_code = status_code
|
||||
self._payload = payload if payload is not None else {}
|
||||
self.text = text or json.dumps(self._payload)
|
||||
|
||||
def json(self) -> dict:
|
||||
return self._payload
|
||||
|
||||
|
||||
def _configure(monkeypatch, *, mock: bool = False) -> None:
|
||||
"""配齐创蓝凭证 + 设 SMS_MOCK;清本地存码/冷却隔离用例。"""
|
||||
monkeypatch.setattr(settings, "SMS_MOCK", mock)
|
||||
monkeypatch.setattr(settings, "CHUANGLAN_SMS_ACCOUNT", "YZM0000001")
|
||||
monkeypatch.setattr(settings, "CHUANGLAN_SMS_PASSWORD", "secret")
|
||||
monkeypatch.setattr(settings, "CHUANGLAN_SMS_TEMPLATE_ID", "1021143438")
|
||||
monkeypatch.setattr(settings, "CHUANGLAN_SMS_SIGNATURE", "【创蓝云智】")
|
||||
chuanglan._codes.clear()
|
||||
chuanglan._last_sent.clear()
|
||||
|
||||
|
||||
def _ok_payload(**over) -> dict:
|
||||
p = {
|
||||
"code": "000000",
|
||||
"msgId": "25071018345400902898000000000001",
|
||||
"time": "20250710183454",
|
||||
"successNum": "1",
|
||||
"failNum": "0",
|
||||
"errorMsg": "",
|
||||
}
|
||||
p.update(over)
|
||||
return p
|
||||
|
||||
|
||||
# ============================ 签名算法 ============================
|
||||
|
||||
def test_sign_implements_documented_hmac() -> None:
|
||||
"""_sign = HmacSHA256(key=md5(password), msg=sorted([md5pwd,ts,nonce]) 拼接),小写 hex。"""
|
||||
password, ts, nonce = "secret", "1752143733", "0123456789abcdef0123456789abcdef"
|
||||
md5pwd = hashlib.md5(password.encode()).hexdigest()
|
||||
expected = hmac.new(
|
||||
md5pwd.encode(),
|
||||
"".join(sorted([md5pwd, ts, nonce])).encode(),
|
||||
hashlib.sha256,
|
||||
).hexdigest()
|
||||
|
||||
sig = chuanglan._sign(password, ts, nonce)
|
||||
assert sig == expected
|
||||
assert len(sig) == 64 and sig == sig.lower()
|
||||
|
||||
|
||||
def test_sign_changes_with_nonce() -> None:
|
||||
assert chuanglan._sign("p", "1", "nonceA") != chuanglan._sign("p", "1", "nonceB")
|
||||
|
||||
|
||||
# ============================ _call_chuanglan(HTTP 接缝)============================
|
||||
|
||||
def test_call_chuanglan_builds_signed_request_without_password(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
captured: dict = {}
|
||||
|
||||
def fake_post(url, **kw):
|
||||
captured.update(url=url, body=kw.get("json"), headers=kw.get("headers"), timeout=kw.get("timeout"))
|
||||
return _FakeResp(200, _ok_payload())
|
||||
|
||||
monkeypatch.setattr(httpx, "post", fake_post)
|
||||
|
||||
result = chuanglan._call_chuanglan(PHONE, "123456")
|
||||
|
||||
assert result["code"] == "000000"
|
||||
assert captured["url"] == settings.CHUANGLAN_SMS_ENDPOINT
|
||||
body = captured["body"]
|
||||
assert body["account"] == "YZM0000001"
|
||||
assert body["phoneNumbers"] == PHONE
|
||||
assert body["templateId"] == "1021143438"
|
||||
assert body["templateParamJson"] == json.dumps([{"param1": "123456"}])
|
||||
assert body["signature"] == "【创蓝云智】"
|
||||
assert "password" not in body # HMAC 方式:密码只用于算签,不上行
|
||||
assert len(body["nonce"]) == 32
|
||||
assert captured["headers"]["X-QA-Hmac-Signature"] == chuanglan._sign(
|
||||
"secret", body["timestamp"], body["nonce"]
|
||||
)
|
||||
assert captured["timeout"] == settings.CHUANGLAN_SMS_TIMEOUT_SEC
|
||||
|
||||
|
||||
def test_call_chuanglan_omits_signature_when_blank(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(settings, "CHUANGLAN_SMS_SIGNATURE", "")
|
||||
captured: dict = {}
|
||||
monkeypatch.setattr(httpx, "post", lambda url, **kw: captured.update(body=kw.get("json")) or _FakeResp(200, _ok_payload()))
|
||||
|
||||
chuanglan._call_chuanglan(PHONE, "123456")
|
||||
assert "signature" not in captured["body"] # 模板自带签名时不传
|
||||
|
||||
|
||||
def test_call_chuanglan_http_non_200_raises_503(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(httpx, "post", lambda url, **kw: _FakeResp(500, {}, "oops"))
|
||||
with pytest.raises(SmsError) as ei:
|
||||
chuanglan._call_chuanglan(PHONE, "123456")
|
||||
assert ei.value.status_code == 503
|
||||
|
||||
|
||||
def test_call_chuanglan_network_error_raises_503(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
|
||||
def boom(url, **kw):
|
||||
raise httpx.ConnectError("down")
|
||||
|
||||
monkeypatch.setattr(httpx, "post", boom)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
chuanglan._call_chuanglan(PHONE, "123456")
|
||||
assert ei.value.status_code == 503
|
||||
|
||||
|
||||
# ============================ _send_via_chuanglan(错误码映射)============================
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"code,expected",
|
||||
[
|
||||
("000000", None), # 成功不抛
|
||||
("103", 429), # 超频
|
||||
("107", 400), # 手机号错误
|
||||
("109", 503), # 无发送量/余额
|
||||
("117", 503), # IP 未白名单
|
||||
("102", 503), # 密码错误
|
||||
("116", 503), # 签名不合法
|
||||
("124", 503), # 模板内容不匹配
|
||||
("152", 503), # 模板不存在
|
||||
("999999", 503), # 未知码兜底
|
||||
],
|
||||
)
|
||||
def test_send_via_chuanglan_maps_codes(monkeypatch, code, expected) -> None:
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(chuanglan, "_call_chuanglan", lambda phone, c: _ok_payload(code=code, errorMsg=code))
|
||||
if expected is None:
|
||||
assert chuanglan._send_via_chuanglan(PHONE, "123456") is None
|
||||
else:
|
||||
with pytest.raises(SmsError) as ei:
|
||||
chuanglan._send_via_chuanglan(PHONE, "123456")
|
||||
assert ei.value.status_code == expected
|
||||
|
||||
|
||||
def test_send_via_chuanglan_not_configured_raises_503_without_calling(monkeypatch) -> None:
|
||||
monkeypatch.setattr(settings, "SMS_MOCK", False)
|
||||
monkeypatch.setattr(settings, "CHUANGLAN_SMS_ACCOUNT", "") # 凭证缺
|
||||
|
||||
def _boom(phone, c):
|
||||
raise AssertionError("未配置时不应发起请求")
|
||||
|
||||
monkeypatch.setattr(chuanglan, "_call_chuanglan", _boom)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
chuanglan._send_via_chuanglan(PHONE, "123456")
|
||||
assert ei.value.status_code == 503
|
||||
|
||||
|
||||
# ============================ send_code(自管码,复制自极光)============================
|
||||
|
||||
def test_send_code_success_stores_and_returns_cooldown(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(chuanglan, "_send_via_chuanglan", lambda p, c: None)
|
||||
|
||||
assert chuanglan.send_code(PHONE) == settings.SMS_SEND_INTERVAL_SEC
|
||||
assert PHONE in chuanglan._codes
|
||||
assert len(chuanglan._codes[PHONE].code) == settings.SMS_CODE_LENGTH
|
||||
|
||||
|
||||
def test_send_code_cooldown_raises_429(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(chuanglan, "_send_via_chuanglan", lambda p, c: None)
|
||||
chuanglan.send_code(PHONE)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
chuanglan.send_code(PHONE)
|
||||
assert ei.value.status_code == 429
|
||||
|
||||
|
||||
def test_send_code_failure_keeps_cooldown_drops_code(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
|
||||
def boom(p, c):
|
||||
raise SmsError("no balance", status_code=503)
|
||||
|
||||
monkeypatch.setattr(chuanglan, "_send_via_chuanglan", boom)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
chuanglan.send_code(PHONE)
|
||||
assert ei.value.status_code == 503
|
||||
assert PHONE not in chuanglan._codes # 没发出去的码删掉
|
||||
assert PHONE in chuanglan._last_sent # 冷却保留:失败也限速
|
||||
|
||||
|
||||
def test_send_code_unexpected_error_wrapped_503(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
|
||||
def boom(p, c):
|
||||
raise RuntimeError("boom")
|
||||
|
||||
monkeypatch.setattr(chuanglan, "_send_via_chuanglan", boom)
|
||||
with pytest.raises(SmsError) as ei:
|
||||
chuanglan.send_code(PHONE)
|
||||
assert ei.value.status_code == 503
|
||||
|
||||
|
||||
def test_send_code_mock_short_circuits_no_network(monkeypatch) -> None:
|
||||
_configure(monkeypatch, mock=True)
|
||||
|
||||
def boom(p, c):
|
||||
raise AssertionError("mock 不应发网络")
|
||||
|
||||
monkeypatch.setattr(chuanglan, "_send_via_chuanglan", boom)
|
||||
assert chuanglan.send_code(PHONE) == settings.SMS_SEND_INTERVAL_SEC
|
||||
|
||||
|
||||
# ============================ verify_code(自管码,复制自极光)============================
|
||||
|
||||
def test_verify_code_success_is_one_time(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
chuanglan._codes[PHONE] = chuanglan._CodeRecord(code="123456", expires_at=time.time() + 300)
|
||||
assert chuanglan.verify_code(PHONE, "123456") is True
|
||||
assert chuanglan.verify_code(PHONE, "123456") is False # 验过即作废
|
||||
|
||||
|
||||
def test_verify_code_wrong_caps_then_invalidates(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
chuanglan._codes[PHONE] = chuanglan._CodeRecord(code="123456", expires_at=time.time() + 300)
|
||||
for _ in range(settings.SMS_MAX_VERIFY_ATTEMPTS):
|
||||
assert chuanglan.verify_code(PHONE, "000000") is False
|
||||
# 达失败上限即作废:即便随后给对的码也 False
|
||||
assert chuanglan.verify_code(PHONE, "123456") is False
|
||||
|
||||
|
||||
def test_verify_code_expired_false_and_cleared(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
chuanglan._codes[PHONE] = chuanglan._CodeRecord(code="123456", expires_at=time.time() - 1)
|
||||
assert chuanglan.verify_code(PHONE, "123456") is False
|
||||
assert PHONE not in chuanglan._codes
|
||||
|
||||
|
||||
def test_verify_code_no_record_false(monkeypatch) -> None:
|
||||
_configure(monkeypatch)
|
||||
assert chuanglan.verify_code(PHONE, "123456") is False
|
||||
|
||||
|
||||
def test_verify_code_mock_passes_any_ndigit(monkeypatch) -> None:
|
||||
_configure(monkeypatch, mock=True)
|
||||
assert chuanglan.verify_code(PHONE, "123456") is True # 6 位数字放行
|
||||
assert chuanglan.verify_code(PHONE, "12345") is False # 位数不对
|
||||
|
||||
|
||||
# ============================ 端点:SMS_PROVIDER=chuanglan 端到端路由 ============================
|
||||
|
||||
def test_sms_send_chuanglan_outage_returns_503(client, monkeypatch) -> None:
|
||||
"""SMS_PROVIDER=chuanglan 且发送时创蓝异常 → /sms/send 返 503(auth.py 现有 try/except 覆盖)。"""
|
||||
_configure(monkeypatch)
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "chuanglan")
|
||||
|
||||
def boom(p, c):
|
||||
raise SmsError("chuanglan down", status_code=503)
|
||||
|
||||
monkeypatch.setattr(chuanglan, "_send_via_chuanglan", boom)
|
||||
r = client.post("/api/v1/auth/sms/send", json={"phone": "13812345678"})
|
||||
assert r.status_code == 503, r.text
|
||||
@@ -1,53 +0,0 @@
|
||||
"""SMS 分派器:按 settings.SMS_PROVIDER 路由到正确 provider。
|
||||
|
||||
契约:send_code / verify_code **每次调用**读 settings.SMS_PROVIDER 选 provider(支持运行时切换 /
|
||||
灰度回退);默认 jiguang。此处 monkeypatch 两 provider 的实现为标记函数,断言路由命中 + 可秒切。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from app.core.config import settings
|
||||
from app.integrations import sms
|
||||
from app.integrations.sms import aliyun, chuanglan, jiguang
|
||||
|
||||
|
||||
def test_send_code_routes_by_provider_and_switches_per_call(monkeypatch) -> None:
|
||||
calls: list[str] = []
|
||||
monkeypatch.setattr(jiguang, "send_code", lambda phone: (calls.append("jiguang"), 60)[1])
|
||||
monkeypatch.setattr(aliyun, "send_code", lambda phone: (calls.append("aliyun"), 60)[1])
|
||||
monkeypatch.setattr(chuanglan, "send_code", lambda phone: (calls.append("chuanglan"), 60)[1])
|
||||
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "jiguang")
|
||||
assert sms.send_code("13800138000") == 60
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "aliyun")
|
||||
assert sms.send_code("13800138000") == 60
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "chuanglan")
|
||||
assert sms.send_code("13800138000") == 60
|
||||
|
||||
assert calls == ["jiguang", "aliyun", "chuanglan"] # 每次按当前 provider 路由,运行时可切
|
||||
|
||||
|
||||
def test_verify_code_routes_by_provider(monkeypatch) -> None:
|
||||
calls: list[str] = []
|
||||
monkeypatch.setattr(jiguang, "verify_code", lambda phone, code: (calls.append("jiguang"), True)[1])
|
||||
monkeypatch.setattr(aliyun, "verify_code", lambda phone, code: (calls.append("aliyun"), True)[1])
|
||||
monkeypatch.setattr(chuanglan, "verify_code", lambda phone, code: (calls.append("chuanglan"), True)[1])
|
||||
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "jiguang")
|
||||
assert sms.verify_code("13800138000", "123456") is True
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "aliyun")
|
||||
assert sms.verify_code("13800138000", "123456") is True
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "chuanglan")
|
||||
assert sms.verify_code("13800138000", "123456") is True
|
||||
|
||||
assert calls == ["jiguang", "aliyun", "chuanglan"]
|
||||
|
||||
|
||||
def test_unknown_provider_falls_back_to_jiguang(monkeypatch) -> None:
|
||||
"""SMS_PROVIDER 非 aliyun 一律走 jiguang(默认兜底,防误配把登录打挂)。"""
|
||||
calls: list[str] = []
|
||||
monkeypatch.setattr(jiguang, "send_code", lambda phone: (calls.append("jiguang"), 60)[1])
|
||||
monkeypatch.setattr(aliyun, "send_code", lambda phone: (calls.append("aliyun"), 60)[1])
|
||||
monkeypatch.setattr(settings, "SMS_PROVIDER", "jiguang")
|
||||
|
||||
sms.send_code("13800138000")
|
||||
assert calls == ["jiguang"]
|
||||
Reference in New Issue
Block a user