# 客户标签功能 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
```

**请求参数**:
```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

**响应示例**:
```json
{
  "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`

**请求参数**:
```json
{
  "phones": ["13800138000", "13900139000"],
  "options": {
    "mask_identifier": true
  }
}
```

或使用逗号分隔的字符串：
```json
{
  "phones": "13800138000,13900139000"
}
```

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

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

**请求参数**:
```json
{
  "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
```

**请求参数**:
```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

**响应示例**:
```json
{
  "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
<?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认证
- 提供快捷查询方法