🐝 WhatsApp 登录与 OTP 技术设计

flowchart LR
  U(["📱 用户 WhatsApp"]):::trunk
  META["☁️ Meta Cloud API
graph.facebook.com/v25.0"]:::meta

  subgraph CORE["core service · com.seahub.x.core.whatsapp"]
    direction TB
    WH["WhatsappWebhookController
GET 验签 · POST 入站"]:::issue
    DP["WhatsappInboundDispatcher
幂等 · 四层路由（同步）"]:::decision
    CA["WhatsappCloudApiClient
sendText / sendTemplate"]:::a
    OTP["WhatsappFirstPhoneOtpSender
WA 优先 + 短信兜底"]:::b
  end

  U -- "① 发消息" --> META -- "② webhook POST" --> WH --> DP
  DP -- "③ 即时回复" --> CA -- "出站" --> META -- "④ 推达" --> U
  OTP -- "OTP 认证模板" --> CA

  classDef trunk fill:#ffffff,stroke:#e8d9b8,color:#1a1410;
  classDef meta fill:#eff6ff,stroke:#3b82f6,color:#1e40af;
  classDef issue fill:#fff7e6,stroke:#f59e0b,color:#b45309;
  classDef decision fill:#fef3c7,stroke:#e07c00,color:#7a4f24,stroke-width:2px;
  classDef a fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6;
  classDef b fill:#fff7ed,stroke:#fb923c,color:#9a3412;

sequenceDiagram
  autonumber
  participant U as 用户
  participant H5 as BeeX H5/App
  participant WA as WhatsApp
  participant META as Meta Cloud API
  participant API as BeeX API
  participant DB as MySQL

  U->>H5: 点击“WhatsApp 登录”
  H5->>H5: 本地生成登录码 SX-XXXXXX
  H5->>WA: 打开 wa.me/{officialNumber}?text=LOGIN SX-XXXXXX
  U->>WA: 点击发送消息
  WA->>META: 消息进入 BeeX 官方号
  META->>API: POST /webhooks/whatsapp
  API->>DB: 保存入站消息，按 wa_message_id 幂等
  API->>DB: 查找/创建 login intent，状态置为 VERIFIED
  API->>WA: 回复“登录成功，请返回 BeeX”
  U->>H5: 从 WhatsApp 回到 App/H5
  H5->>API: POST /api/v1/auth/whatsapp/login-codes/consume
  API->>DB: 校验 code 已 VERIFIED、未过期、未消费
  API-->>H5: accessToken / refreshToken / userId / referralCode
  H5->>H5: 保存登录态，进入业务页面

flowchart TD
  IN["POST /webhooks/whatsapp"]:::issue --> PARSE["WhatsappWebhookPayloadParser
解析 entry[].changes[].value.messages[]"]:::trunk
  PARSE --> LOOP{{"逐条消息"}}:::decision
  LOOP --> DUP["① 幂等落库 wa_inbound_messages
INSERT IGNORE on wa_message_id"]:::trunk
  DUP -->|"已存在"| SKIP["重复推送 → duplicateCount++ 跳过"]:::b
  DUP -->|"新消息"| TXT{"② 是文本吗？"}:::decision
  TXT -->|"否（图片/语音…）"| NT["回「只读文本」双语提示"]:::a
  TXT -->|"是"| R1{"③ 登录码 SX-XXXXX?"}:::decision
  R1 -->|"命中"| L["verifyByInboundMessage
意图→VERIFIED · 回登录成功链接"]:::key
  R1 -->|"否"| R2{"④ 邀请码 JOIN BXxxxx?"}:::decision
  R2 -->|"命中"| J["joinByInboundMessage
建用户 + 绑定邀请人 · 回欢迎语"]:::key
  R2 -->|"否"| R3["⑤ WhatsappBotService.handleMessage
带货链接 / 通用命令"]:::a
  L --> REPLY["sendText 回复 + 落 wa_outbound_messages"]:::a
  J --> REPLY
  R3 --> REPLY

  classDef trunk fill:#ffffff,stroke:#e8d9b8,color:#1a1410;
  classDef issue fill:#fff7e6,stroke:#f59e0b,color:#b45309;
  classDef decision fill:#fef3c7,stroke:#e07c00,color:#7a4f24,stroke-width:2px;
  classDef a fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6;
  classDef b fill:#fff7ed,stroke:#fb923c,color:#9a3412;
  classDef key fill:#fff5f5,stroke:#dc2626,color:#991b1b,stroke-width:2px;

flowchart TD
  S([用户在 App / H5 登录页]):::trunk --> IN["输入手机号
选「用 WhatsApp 收验证码」"]:::trunk
  IN --> REQ["① POST /api/v1/auth/phone/otp-intents
phone + deviceId + purpose"]:::issue
  REQ --> GEN["② 生成 6 位码
codeHash(SHA-256) + TTL 5min + attempts=0
返回 otpIntentId + maskedPhone"]:::trunk
  GEN --> SEND{"③ WhatsappFirstPhoneOtpSender 选路"}:::decision
  SEND -->|"WA 优先（配齐+有模板）"| WA["WhatsappCloudApiClient
认证模板（含复制按钮）"]:::a
  SEND -->|"WA 失败/未配/ mock"| SMS["SmsGatewayService
短信兜底"]:::b
  WA --> RECV["④ 用户收到验证码"]:::a
  SMS --> RECV
  RECV --> TYPE["⑤ 读码 → 填回 App"]:::trunk
  TYPE --> VER["⑥ POST /api/v1/auth/phone/otp-intents/{id}/verify"]:::issue
  VER --> CHK{"⑦ codeHash 对? · 未过期? · attempts < 上限?"}:::decision
  CHK -->|"✅"| OK["⑧ 认/建账号（provider=PHONE，键=手机号）
🔐 签 token · 消费意图（一次性）"]:::key
  CHK -->|"❌ 码错"| RT["attempts+1 → 重填（到上限锁定）"]:::issue
  CHK -->|"⌛ 过期/超限"| EXP["意图失效 → 重新获取"]:::issue
  RT --> TYPE
  OK --> DONE(["✅ 登录成功 · 携裂变归因码 → 绑定上线"]):::money

  classDef trunk fill:#ffffff,stroke:#e8d9b8,color:#1a1410;
  classDef issue fill:#fff7e6,stroke:#f59e0b,color:#b45309;
  classDef decision fill:#fef3c7,stroke:#e07c00,color:#7a4f24,stroke-width:2px;
  classDef a fill:#f5f3ff,stroke:#8b5cf6,color:#5b21b6;
  classDef b fill:#fff7ed,stroke:#fb923c,color:#9a3412;
  classDef key fill:#fff5f5,stroke:#dc2626,color:#991b1b,stroke-width:2px;
  classDef money fill:#f0fdf4,stroke:#15803d,color:#15803d;