统一用户认证

概述

用户有两种使用方式，都不需要在引擎单独注册：

方式1: 有小智设备
┌─────────────┐                    ┌─────────────┐
│   小智平台   │  ──  MCP调用  ──▶  │  米塞斯引擎  │
│  (设备自动)  │  device_id        │ (自动识别)   │
└─────────────┘                    └─────────────┘

方式2: 无设备，网页使用
┌─────────────┐                    ┌─────────────┐
│  网页/H5端  │  ──  手机号  ──▶   │  米塞斯引擎  │
│ (手机号登录) │  虚拟device_id    │ (自动创建)   │
└─────────────┘                    └─────────────┘

工作原理

1. 用户在小智注册：获得小智账号
2. 用户使用小智对话：小智调用引擎时携带 device_id
3. 引擎自动识别：首次调用自动创建本地用户关联
4. 订阅统一管理：通过设备ID或小智用户ID开通订阅

用户无感知

用户不需要知道"米塞斯引擎"的存在，只需：

• 在小智平台注册
• 与小智对话
• 联系客服付款升级

API 端点

🔍 查询用户（客服用）

# 通过手机号查询用户是否存在
GET /payment/xiaozhi/lookup?phone=13800138000

# 用户存在时返回
{
  "found": true,
  "user": {
    "xiaozhi_user_id": "xz_abc123",
    "phone": "13800138000",
    "plan": "free",
    "last_active": "2026-01-10T15:30:00"
  },
  "message": "✅ 找到用户，当前套餐: free"
}

# 用户不存在时返回
{
  "found": false,
  "message": "⚠️ 该用户尚未使用过引擎，但可以直接开通",
  "can_activate": true
}

✅ 开通订阅（客服用）

# 为用户开通（无论是否已存在）
POST /payment/xiaozhi/activate
Content-Type: application/json

{
  "identifier": "13800138000",  # 手机号/邮箱/设备ID/用户ID
  "plan": "pro",
  "months": 1
}

# 返回
{
  "success": true,
  "is_new_user": true,           # true=新创建, false=已有用户
  "xiaozhi_user_id": "manual_13800138000",
  "phone": "13800138000",
  "plan": "pro",
  "expires": "2026-02-11T00:00:00",
  "message": "🆕 已为用户开通 pro 套餐 1 个月"
}

📋 列出所有用户（管理员用）

GET /payment/xiaozhi/users

👤 查询单个用户详情

GET /payment/xiaozhi/user/{identifier}

📝 预注册用户（可选）

# 提前创建用户记录
POST /payment/xiaozhi/register
Content-Type: application/json

{
  "phone": "13800138000",
  "nickname": "张三"
}

🌐 网页端用户（无需小智设备）

网页注册

POST /payment/web/register
Content-Type: application/json

{
  "phone": "13800138000",
  "nickname": "张三"
}

# 返回
{
  "success": true,
  "xiaozhi_user_id": "web_13800138000",
  "device_id": "web_13800138000",  # 用于后续API调用
  "plan": "free"
}

网页登录

POST /payment/web/login
Content-Type: application/json

{
  "phone": "13800138000"
}

# 返回
{
  "success": true,
  "device_id": "web_13800138000",
  "plan": "pro",
  "expires": "2026-02-11T00:00:00"
}

使用 device_id 调用引擎

登录后获得 device_id，用于调用分析接口：

POST /h5/chat
Content-Type: application/json

{
  "content": "我最近很焦虑，不知道该不该跳槽",
  "device_id": "web_13800138000"
}

开通流程

方式1：客服开通（推荐）

用户联系客服，发送手机号
          │
          ▼
┌─────────────────────────────────────────┐
│  客服操作步骤：                           │
│                                         │
│  1️⃣ 查询用户是否存在：                    │
│     GET /payment/xiaozhi/lookup?phone=手机号 │
│                                         │
│  2️⃣ 确认收款后开通：                      │
│     POST /payment/xiaozhi/activate       │
│     {identifier: "手机号", plan: "pro"}  │
│                                         │
│  ✅ 无论用户是否存在，都能直接开通！        │
└─────────────────────────────────────────┘
          │
          ▼
    用户下次对话自动生效

客服查询结果说明

方式2：在线支付（自动）

用户 ──▶ 支付成功 ──▶ Webhook回调 ──▶ 自动开通

环境变量

# 启用统一认证（默认开启）
XIAOZHI_AUTH_ENABLED=true

# 新用户默认套餐
XIAOZHI_DEFAULT_PLAN=free

订阅套餐

常见问题

Q: 用户在小智换了设备怎么办？

A: 只要小智传递相同的 user_id，引擎会自动关联到同一用户。

Q: 如何知道用户是谁？

A: 用户向客服发送手机号后，管理员可以通过手机号查询和开通。

Q: 订阅什么时候生效？

A: 开通后立即生效，用户下次对话时自动使用新套餐。