#Admin API 前端对接文档（搜索接口 + WorkTask 列表筛选）

#1. 变更概览

本次后端变更包含：

1. 新增管理员搜索接口：
   • POST /api/admin_center/search/artists
   • POST /api/admin_center/search/users
2. 增强管理员工单列表接口：
   • POST /api/admin_center/work_task/list
   • 新增筛选参数：id、user_id、artist_id

#2. 通用约定

• 鉴权方式：auth:sanctum
• 角色权限：admin / super_admin
• 请求头：
  • Authorization: Bearer {token}
  • Content-Type: application/json
• 请求方法：均为 POST
• 参数校验失败时：返回 422（Laravel 默认校验错误结构）

#3. 搜索接口：艺术家

#3.1 接口信息

• 路径：POST /api/admin_center/search/artists
• 控制器：Api\\Admin\\SearchController@artists

#3.2 请求参数

#3.3 搜索规则

当传入 term 时，匹配以下任一条件：

• artists.id = term（精确）
• artists.name LIKE %term%
• artists.cname LIKE %term%
• 关联用户 users.email LIKE %term%

返回最多 20 条结果。

#3.4 响应结构

{
  "status": 0,
  "data": {
    "options": [
      {
        "value": 123,
        "label": "[123] artist_name (artist_cname) - user@example.com",
        "id": 123,
        "name": "artist_name",
        "cname": "artist_cname",
        "email": "user@example.com"
      }
    ]
  }
}

label 拼接规则：

• 基础：[id] name
• 有 cname 时追加： (cname)
• 有关联 email 时追加： - email

#3.5 请求示例

{
  "term": "alice"
}

#4. 搜索接口：用户

#4.1 接口信息

• 路径：POST /api/admin_center/search/users
• 控制器：Api\\Admin\\SearchController@users

#4.2 请求参数

#4.3 搜索规则

当传入 term 时，匹配以下任一条件：

• users.id = term（精确）
• users.name LIKE %term%
• users.cname LIKE %term%
• users.email LIKE %term%

返回最多 20 条结果。

#4.4 响应结构

{
  "status": 0,
  "data": {
    "options": [
      {
        "value": 456,
        "label": "[456] user_name (user_cname) - user@example.com",
        "id": 456,
        "name": "user_name",
        "cname": "user_cname",
        "email": "user@example.com"
      }
    ]
  }
}

label 拼接规则：

• 基础：[id] name
• 有 cname 时追加： (cname)
• 始终追加： - email

#4.5 请求示例

{
  "term": "example.com"
}

#5. WorkTask 列表接口新增筛选

#5.1 接口信息

• 路径：POST /api/admin_center/work_task/list
• 控制器：Api\\Admin\\WorkTaskController@list

#5.2 新增请求参数

#5.3 已有参数（保持不变）

• page：integer，最小 1
• size：integer，最小 1，最大 50
• filter_joined_group：boolean
• filter_request_admin_join：boolean
• status：array（元素 string）

#5.4 过滤逻辑说明

• 新增的 id / user_id / artist_id 都是精确匹配。
• 可与已有筛选条件同时使用，条件间为 AND 关系。
• 不传时不影响既有查询行为。

#5.5 请求示例

{
  "page": 1,
  "size": 20,
  "user_id": 1001,
  "artist_id": 2002,
  "status": ["working", "finished"]
}

#5.6 响应结构（保持不变）

{
  "data": [
    {
      "id": 999,
      "user_id": 1001,
      "artist_id": 2002,
      "status": "working"
    }
  ],
  "total": 1
}

#6. 前端对接建议

1. 搜索框建议加 300ms 防抖，输入变化时请求搜索接口。
2. 搜索接口成功标识为 status = 0。
3. 下拉选项建议使用：
   • value 作为提交值
   • label 作为展示文案
4. work_task/list 中若同时传多个筛选字段，注意是交集过滤。