# 系统管理对外API接口文档

## 概述

本文档描述了系统管理平台提供给外部系统（如用户管理）调用的API接口。通过这些接口，外部系统可以：

1. 根据角色标识查询可用用户列表

## 认证方式

所有API请求需要在HTTP Header中携带管理员Token进行身份验证：

```
Authorization: Bearer <admin_token>
```

**注意**：Token由系统登录后提供，具有长期有效性。

## 基础URL

```
生产环境: https://your-domain.com/external/api
开发环境: http://localhost:8000/external/api
```

## 接口列表

### 1. 根据角色标识查询用户列表

根据角色标识查询用户列表

**请求**

```
GET /system/role/user_list/{role_code}
```

**请求头**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Authorization | string | 是 | Bearer Token |
| Content-Type | string | 是 | application/json |

**请求体**

  无

**请求参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 角色标识编码，如：label_admin 标注管理员 , labeler 标注员 |


**响应**

```json
{
  "code": "错误码",
  "message": "错误消息",
  "data": [{
    "user_id":"用户ID",
    "user_name":"用户名",
    "email": "用户邮箱",
    "phone":"用户电话号码",
    "role_code": "角色标识",
    "role_name": "角色名称"
  }]
}
```

**响应参数说明**

| 参数 | 类型 | 说明 |
|------|------|------|
| code | string | **错误码** |
| message | string | 错误消息 |
| data | Array | 响应数据 |
| user_id | string | 用户ID |
| user_name | string | 用户名 |
| email | string | 用户邮箱 |
| phone | string | 用户电话号码 |
| role_code | string | 角色标识 |
| role_name | string | 角色名称 |





---


## 通用错误码定义
        错误码	含义	    HTTP状态码
        000000	成功	200
        100001	参数错误	400
        100002	认证失败	401
        100003	权限不足	403
        100004	资源不存在	404
        100005	请求方法不允许	405
        100006	请求过于频繁	429
        200001	用户名或密码错误	401
        200002	令牌失效	401
        200003	令牌过期	401
        200004	验证码错误	400
        300001	应用不存在	404
        300002	应用密钥错误	401
        300003	回调URL不匹配	400
        400001	用户已存在	409
        400002	用户被禁用	403
        500001	服务器内部错误	500
        500002	服务暂时不可用	503
        500003	数据库错误	500



## API开发规范
  - API 定义目录 src/app/api/v1
    - api_router.py API 路由定义
    - system_api_view.py 系统管理提供的API 接口定义 view（包括： 参数验证、token认证）
      - 根据角色标识查询可用用户列表
    
  - service 业务逻辑实现目录（包括：数据库查询SQL） src/app/service
    - system_service.py