CKB-Interface/TAG_ENGINE_API.md

客户标签功能 API 文档

功能概述

已完成对接外部标签引擎系统，提供两个核心功能：

1. 通过标识（手机号、微信号、身份证、QQ号）查询用户标签
2. 通过标签条件查询用户列表

配置信息

• 外部API地址: http://192.168.1.134:3000
• API Key: 69aebe46b03d334f1796ef88808d3042d5851d0fd91d728bcba6ad6be436acf6
• 服务类: app\common\service\TagEngineService

接口列表

1. 通过标识查询标签

1.1 通用接口

接口地址: POST /v1/tag/query-by-identifiers

请求头:

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

请求参数:

{
  "identifiers": [
    {
      "type": "phone",
      "value": "13800138000"
    },
    {
      "type": "wechat",
      "value": "wx_test_001"
    }
  ],
  "options": {
    "include_tags": ["user.trade.total_amount", "user.profile.gender"],
    "mask_identifier": true
  }
}

参数说明:

• identifiers: 标识列表（必填，最多100个）
  • type: 标识类型，支持 phone、wechat、id_card、qq
  • value: 标识值
• options: 查询选项（可选）
  • include_tags: 包含指定标签代码列表
  • exclude_tags: 排除指定标签代码列表
  • tag_category: 按分类筛选标签
  • mask_identifier: 是否脱敏，默认 true

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "identifier": {
        "type": "phone",
        "value": "138****8000"
      },
      "user_id": "user_12345",
      "found": true,
      "tag_count": 15,
      "tags": [
        {
          "tag_code": "user.trade.total_amount",
          "tag_name": "累计消费金额",
          "tag_value": "15680.50",
          "tag_type": "numeric",
          "category": "交易标签",
          "updated_at": "2026-01-27 10:30:00"
        }
      ]
    }
  ]
}

1.2 快捷接口 - 通过手机号查询

接口地址: POST /v1/tag/query-by-phone

请求参数:

{
  "phones": ["13800138000", "13900139000"],
  "options": {
    "mask_identifier": true
  }
}

或使用逗号分隔的字符串：

{
  "phones": "13800138000,13900139000"
}

1.3 快捷接口 - 通过微信号查询

接口地址: POST /v1/tag/query-by-wechat

请求参数:

{
  "wechats": ["wx_test_001", "wx_test_002"],
  "options": {
    "mask_identifier": true
  }
}

---

2. 通过标签查询用户

2.1 通用接口

接口地址: POST /v1/tag/query-users-by-tags

请求头:

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

请求参数:

{
  "tag_conditions": [
    {
      "tag_code": "user.trade.total_amount",
      "operator": ">=",
      "value": "5000"
    },
    {
      "tag_code": "user.profile.gender",
      "operator": "=",
      "value": "男"
    }
  ],
  "logic": "AND",
  "include_sensitive": false,
  "page": 1,
  "page_size": 20
}

参数说明:

• tag_conditions: 标签条件列表（必填，最多10个）
  • tag_code: 标签代码
  • operator: 操作符，支持 =、!=、>、>=、<、<=、in、not_in
  • value: 标签值（使用 in/not_in 时为数组）
• logic: 逻辑关系，AND 或 OR，默认 AND
• include_sensitive: 是否返回敏感信息（QQ号、身份证），默认 false
• page: 页码，默认 1
• page_size: 每页数量，默认 20，最大 100

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "list": [
      {
        "user_id": "user_12345",
        "name": "张**",
        "phone": "138****8000",
        "wechat": "wx_****_001",
        "qq": null,
        "id_card": null,
        "matched_tags": [
          {
            "tag_code": "user.trade.total_amount",
            "tag_name": "累计消费金额",
            "tag_value": "15680.50"
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 156,
      "total_pages": 8
    }
  }
}

2.2 快捷接口 - 查询高价值用户

接口地址: GET /v1/tag/high-value-users

请求参数:

• page: 页码，默认 1
• page_size: 每页数量，默认 20
• min_amount: 最低消费金额，默认 5000

示例: /v1/tag/high-value-users?page=1&page_size=20&min_amount=10000

2.3 快捷接口 - 查询VIP用户

接口地址: GET /v1/tag/vip-users

请求参数:

• page: 页码，默认 1
• page_size: 每页数量，默认 20
• levels: 用户等级列表，默认 ['VIP', 'SVIP', '金卡会员']

示例: /v1/tag/vip-users?page=1&page_size=20&levels=VIP,SVIP

---

内部调用示例

PHP 代码示例

<?php
use app\common\service\TagEngineService;

// 创建服务实例
$service = new TagEngineService();

// 示例1：通过手机号查询标签
$result = $service->queryByPhone('13800138000');
if ($result && isset($result['data'])) {
    // 处理结果
    foreach ($result['data'] as $item) {
        echo "用户ID: " . $item['user_id'] . "\n";
        echo "标签数量: " . $item['tag_count'] . "\n";
    }
}

// 示例2：通过微信号查询标签
$result = $service->queryByWechat(['wx_test_001', 'wx_test_002']);

// 示例3：通过标签查询用户
$tagConditions = [
    [
        'tag_code' => 'user.trade.total_amount',
        'operator' => '>=',
        'value' => '5000'
    ]
];
$result = $service->queryUsersByTags($tagConditions, 'AND', false, 1, 20);

// 示例4：自定义API配置
$service->setBaseUrl('http://192.168.1.134:3000')
        ->setApiKey('your_custom_api_key');

---

错误码说明

错误码	说明	处理建议
400	请求参数错误	检查请求参数格式和内容
401	未授权访问	检查 JWT Token 是否有效
403	无权限访问	检查 API Key 权限配置
429	请求过于频繁	降低请求频率，稍后重试
500	服务器内部错误	联系技术支持

---

注意事项

1. 批量限制:

   • 通过标识查询：单次最多 100 个标识
   • 通过标签查询：单次最多 10 个标签条件
   • 查询结果：单页最多 100 条记录

2. 数据脱敏:

   • 默认对敏感信息进行脱敏
   • 手机号：138****8000
   • 身份证：110101********1234
   • 微信号：wx_****_001

3. 标识类型:

   • phone: 手机号（11位数字）
   • id_card: 身份证号（18位）
   • wechat: 微信号
   • qq: QQ号

4. 操作符说明:

   • =: 等于
   • !=: 不等于
   • >: 大于
   • >=: 大于等于
   • <: 小于
   • <=: 小于等于
   • in: 在列表中（value 必须是数组）
   • not_in: 不在列表中（value 必须是数组）

5. 权限要求:

   • 所有接口都需要 JWT 认证
   • 查询敏感信息需要额外权限（tag:query:sensitive）

---

文件结构

application/
├── common/
│   └── service/
│       └── TagEngineService.php          # 标签引擎服务类
└── cunkebao/
    ├── config/
    │   └── route.php                     # 路由配置
    └── controller/
        └── tag/
            ├── QueryTagsByIdentifiersController.php    # 通过标识查询标签控制器
            └── QueryUsersByTagsController.php          # 通过标签查询用户控制器

---

更新日志

v1.0.0 (2026-01-30)

• 初始版本发布
• 实现标签引擎服务类
• 实现两个核心控制器
• 配置路由和JWT认证
• 提供快捷查询方法