🎓 星塔校园 API 文档

College Personnel Management Platform API Documentation v1.0

1. 获取学校管理员信息

GET /api/base/info
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {admin_token}
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "user_id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "mobile": "13800138000",
    "avatar": "",
    "university_id": 1,
    "university_name": "某某大学",
    "status": 1
  }
}

2. 获取政工人员信息

GET /api/staff/info
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {staff_token}
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "person_id": 38,
    "person_type": 2,
    "name": "李四",
    "gender": 1,
    "mobile": "13900139000",
    "email": "lisi@example.com",
    "avatar": "",
    "status": 1,
    "staff_no": "S001",
    "university_id": 1,
    "university_name": "某某大学",
    "department_id": 5,
    "department_name": "学术委员会办公室",
    "college_id": null,
    "college_name": null,
    "faculty_id": null,
    "faculty_name": null,
    "managed_department_ids": [13, 20, 21, 46, 47, 48],
    "managed_person_ids": [38, 37]
  }
}
说明：managed_department_ids 包含政工人员管辖的所有部门ID（含子部门），managed_person_ids 包含直接管辖的人员ID。

3. 获取机构树（学校管理员）

GET /api/base/departments/tree
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {admin_token}
请求参数
参数名 类型 必填 说明
customer_id int 是 学校ID
请求示例
GET /api/base/departments/tree?customer_id=1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "parent_id": 0,
      "recommend_num": 555,
      "department_name": "某某大学",
      "department_type": 0,
      "tree_level": 1,
      "items": [
        {
          "id": 5,
          "parent_id": 1,
          "recommend_num": 44,
          "department_name": "学术委员会办公室",
          "department_type": 1,
          "tree_level": 3,
          "items": []
        },
        {
          "id": 10,
          "parent_id": 1,
          "recommend_num": 120,
          "department_name": "计算机科学与技术学院",
          "department_type": 2,
          "tree_level": 3,
          "items": [
            {
              "id": 11,
              "parent_id": 10,
              "recommend_num": 30,
              "department_name": "软件工程系",
              "department_type": 3,
              "tree_level": 4,
              "items": []
            }
          ]
        }
      ]
    }
  ]
}

4. 获取机构树（政工人员）

GET /api/staff/departments/tree
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {staff_token}
请求参数
参数名 类型 必填 说明
customer_id int 是 学校ID
权限说明：政工人员仅能查看被授权的机构及其子机构，返回结构与学校管理员相同，但数据已过滤。
请求示例
GET /api/staff/departments/tree?customer_id=1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "parent_id": 0,
      "recommend_num": 120,
      "department_name": "某某大学",
      "department_type": 0,
      "tree_level": 1,
      "items": [
        {
          "id": 10,
          "parent_id": 1,
          "recommend_num": 120,
          "department_name": "计算机科学与技术学院",
          "department_type": 2,
          "tree_level": 3,
          "items": []
        }
      ]
    }
  ]
}

5. 搜索机构列表（学校管理员）

GET /api/base/departments/list
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {admin_token}
请求参数
参数名 类型 必填 说明
customer_id int 是 学校ID
keyword string 否 机构名称关键词（模糊查询）
department_type int 否 机构类型：0=学校 1=行政机构 2=学院 3=系 4=专业 5=班级
请求示例
GET /api/base/departments/list?customer_id=1&keyword=学院&department_type=2
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 10,
      "parent_id": 1,
      "recommend_num": 120,
      "department_name": "计算机科学与技术学院",
      "department_type": 2,
      "tree_level": 3
    },
    {
      "id": 15,
      "parent_id": 1,
      "recommend_num": 80,
      "department_name": "经济管理学院",
      "department_type": 2,
      "tree_level": 3
    }
  ]
}

6. 搜索机构列表（政工人员）

GET /api/staff/departments/list
请求参数

参数与学校管理员接口相同

权限说明：政工人员仅能搜索被授权的机构，返回结构与学校管理员相同，但数据已过滤。
请求示例
GET /api/staff/departments/list?customer_id=1&keyword=计算机
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

7. 查询人员列表（学校管理员）

GET /api/base/persons/list
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {admin_token}
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
person_type int 是 人员类型：1=学生 2=政工
page int 否 页码（默认1）
page_size int 否 每页数量（默认20，最大100）
with_extend bool 否 是否包含扩展信息（默认false）
基础字段搜索
name string 否 姓名模糊查询
mobile string 否 手机号
email string 否 邮箱
gender int 否 性别：1=男 2=女
status int 否 状态：1=正常 2=禁用
学生扩展字段搜索（person_type=1时可用）
student_no string 否 学号
grade string 否 年级
college_id int 否 学院ID
profession_id int 否 专业ID
class_id int 否 班级ID
政工扩展字段搜索（person_type=2时可用）
staff_no string 否 工号
department_id int 否 部门ID
请求示例 1：查询学生列表（不含扩展）
GET /api/base/persons/list?university_id=1&person_type=1&page=1&page_size=20
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
响应示例 1：不含扩展信息
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 10,
        "customer_id": 1,
        "person_type": 1,
        "name": "张三",
        "gender": 1,
        "mobile": "13800138000",
        "email": "zhangsan@example.com",
        "avatar": "https://example.com/avatar/10.jpg",
        "status": 1
      },
      {
        "id": 11,
        "customer_id": 1,
        "person_type": 1,
        "name": "李四",
        "gender": 2,
        "mobile": "13800138001",
        "email": "lisi@example.com",
        "avatar": "",
        "status": 1
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}
请求示例 2：查询学生列表（含扩展）
GET /api/base/persons/list?university_id=1&person_type=1&page=1&page_size=20&with_extend=true&grade=2023
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
响应示例 2：含学生扩展信息
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 10,
        "customer_id": 1,
        "person_type": 1,
        "name": "张三",
        "gender": 1,
        "mobile": "13800138000",
        "email": "zhangsan@example.com",
        "avatar": "https://example.com/avatar/10.jpg",
        "status": 1,
        "student_extend": {
          "person_id": 10,
          "area_id": 1,
          "student_no": "2023001",
          "grade": "2023",
          "education_level": "本科",
          "school_system": "4年",
          "id_card": "110101199001011234",
          "admission_no": "A2023001",
          "exam_no": "E2023001",
          "enrollment_status": 1,
          "is_enrolled": 1,
          "college_id": 10,
          "faculty_id": 11,
          "profession_id": 12,
          "class_id": 13
        }
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  }
}
请求示例 3：查询政工列表（含扩展）
GET /api/base/persons/list?university_id=1&person_type=2&with_extend=true&department_id=5
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
响应示例 3：含政工扩展信息
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 38,
        "customer_id": 1,
        "person_type": 2,
        "name": "王五",
        "gender": 1,
        "mobile": "13900139000",
        "email": "wangwu@example.com",
        "avatar": "",
        "status": 1,
        "staff_extend": {
          "person_id": 38,
          "staff_no": "S001",
          "department_id": 5,
          "college_id": 10,
          "faculty_id": null
        }
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 20
  }
}

8. 查询人员列表（政工人员）

GET /api/staff/persons/list
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {staff_token}
请求参数

参数与学校管理员接口完全相同

权限说明：政工人员仅能查看管辖权限下的人员
  • 人员ID在 managed_person_ids 中
  • 人员所属部门在 managed_department_ids 中（通过学生/政工扩展表关联）
请求示例
GET /api/staff/persons/list?university_id=1&person_type=1&page=1&page_size=20&with_extend=true
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 10,
        "customer_id": 1,
        "person_type": 1,
        "name": "张三",
        "gender": 1,
        "mobile": "13800138000",
        "email": "zhangsan@example.com",
        "avatar": "",
        "status": 1,
        "student_extend": {
          "person_id": 10,
          "area_id": 1,
          "student_no": "2023001",
          "grade": "2023",
          "education_level": "本科",
          "school_system": "4年",
          "id_card": "110101199001011234",
          "admission_no": "A2023001",
          "exam_no": "E2023001",
          "enrollment_status": 1,
          "is_enrolled": 1,
          "college_id": 10,
          "faculty_id": 11,
          "profession_id": 12,
          "class_id": 13
        }
      }
    ],
    "total": 30,
    "page": 1,
    "page_size": 20
  }
}
提示：返回的人员数量取决于政工人员的管辖权限，total 表示该政工人员可见的总人员数。
功能说明：获取腾讯云 COS 临时上传凭证，用于前端直传文件到对象存储。系统会自动生成存储路径，格式为：{学校code}/{应用code}/{自定义路径}/{日期}/{随机串}_{文件名}.{扩展名}

22. 获取上传凭证（学校管理员）

POST /api/base/upload-cos/credentials
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {admin_token}
请求参数
参数名 类型 必填 说明
filename string 是 原始文件名（含扩展名），如：avatar.jpg
app_code string 否 应用标识，默认为 common
custom_path string 否 自定义路径，如：avatars、documents 等
请求示例
POST /api/base/upload-cos/credentials
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/x-www-form-urlencoded

filename=avatar.jpg&app_code=user&custom_path=avatars
响应参数
参数名 类型 说明
credentials object 临时凭证信息
credentials.tmpSecretId string 临时密钥 ID
credentials.tmpSecretKey string 临时密钥 Key
credentials.sessionToken string 会话令牌
expiredTime int 凭证过期时间（Unix时间戳）
expiration string 凭证过期时间（ISO 8601格式）
startTime int 凭证生效时间（Unix时间戳）
cos_key string COS 存储路径（完整的对象键）
bucket string COS 存储桶名称
region string COS 地域
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "credentials": {
      "tmpSecretId": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "tmpSecretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "sessionToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "expiredTime": 1742899200,
    "expiration": "2026-03-22T10:00:00Z",
    "startTime": 1742895600,
    "cos_key": "hogwarts/user/avatars/20260322/a1b2c3d4_avatar.jpg",
    "bucket": "your-bucket-name",
    "region": "ap-guangzhou"
  }
}
使用说明：
  • 获取凭证后，使用 COS SDK 或 API 上传文件到指定的 cos_key 路径
  • 临时凭证有效期为 1 小时，过期后需重新获取
  • 存储路径自动包含学校标识、应用标识、日期和随机串，确保文件唯一性

23. 获取上传凭证（政工人员）

POST /api/staff/upload-cos/credentials
请求头
参数名 类型 必填 说明
Authorization string 是 Bearer {staff_token}
请求参数
参数名 类型 必填 说明
filename string 是 原始文件名（含扩展名），如：document.pdf
app_code string 否 应用标识，默认为 common
custom_path string 否 自定义路径，如：reports、attachments 等
请求示例
POST /api/staff/upload-cos/credentials
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/x-www-form-urlencoded

filename=report.pdf&app_code=approval&custom_path=reports
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "credentials": {
      "tmpSecretId": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "tmpSecretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "sessionToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "expiredTime": 1742899200,
    "expiration": "2026-03-22T10:00:00Z",
    "startTime": 1742895600,
    "cos_key": "hogwarts/approval/reports/20260322/e5f6g7h8_report.pdf",
    "bucket": "your-bucket-name",
    "region": "ap-guangzhou"
  }
}
权限说明：政工人员需要通过 staff_token 认证，系统会自动获取其所属学校信息生成存储路径。

24. 获取上传凭证（开放接口）

POST /api/open/upload-cos/credentials
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
customer_id int 是 学校ID（开放接口必填）
filename string 是 原始文件名（含扩展名），如：photo.png
app_code string 否 应用标识，默认为 common
custom_path string 否 自定义路径，如：photos、files 等
请求示例
POST /api/open/upload-cos/credentials
Authorization: your_open_key_here
Content-Type: application/x-www-form-urlencoded

customer_id=17&filename=photo.png&app_code=gallery&custom_path=photos
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "credentials": {
      "tmpSecretId": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "tmpSecretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "sessionToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "expiredTime": 1742899200,
    "expiration": "2026-03-22T10:00:00Z",
    "startTime": 1742895600,
    "cos_key": "hogwarts/gallery/photos/20260322/i9j0k1l2_photo.png",
    "bucket": "your-bucket-name",
    "region": "ap-guangzhou"
  }
}
注意事项：
  • 开放接口不需要登录，但必须提供有效的 OPEN_KEY
  • customer_id 参数必填，用于确定学校标识和存储路径
  • 建议为不同的应用场景设置不同的 app_code，便于文件管理

前端上传示例

使用 COS JavaScript SDK
// 1. 获取上传凭证
const response = await fetch('/api/staff/upload-cos/credentials', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token_here',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: 'filename=test.jpg&app_code=user&custom_path=avatars'
});

const result = await response.json();
const { credentials, cos_key, bucket, region } = result.data;

// 2. 初始化 COS SDK
const cos = new COS({
  getAuthorization: function (options, callback) {
    callback({
      TmpSecretId: credentials.tmpSecretId,
      TmpSecretKey: credentials.tmpSecretKey,
      SecurityToken: credentials.sessionToken,
      StartTime: result.data.startTime,
      ExpiredTime: result.data.expiredTime
    });
  }
});

// 3. 上传文件
cos.putObject({
  Bucket: bucket,
  Region: region,
  Key: cos_key,
  Body: file, // File 对象
  onProgress: function (progressData) {
    console.log('上传进度:', progressData.percent);
  }
}, function (err, data) {
  if (err) {
    console.error('上传失败:', err);
  } else {
    console.log('上传成功:', data);
    // 文件访问地址: https://${bucket}.cos.${region}.myqcloud.com/${cos_key}
  }
});
存储路径说明
路径部分 说明 示例
学校code 从 admin_users.university_code 获取 hogwarts
应用code app_code 参数，默认 common user, approval, gallery
自定义路径 custom_path 参数，可为空 avatars, reports, photos
日期 格式 YYYYMMDD 20260322
文件名 随机串_原始文件名 a1b2c3d4_avatar.jpg
完整路径示例：
  • 有自定义路径：hogwarts/user/avatars/20260322/a1b2c3d4_avatar.jpg
  • 无自定义路径：hogwarts/common/20260322/e5f6g7h8_document.pdf
认证说明：开放接口使用秘钥认证，需要在请求头中携带 Authorization 参数，值为 [Bearer f92968afc12903b4e22dfb0d2a8d9823100da266]

9. 获取应用列表

GET /api/open/applications/list
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
customer_id int 是 学校ID
app_code string 否 应用编码
app_name string 否 应用名称（模糊查询）
short_intro string 否 简介（模糊查询）
data_type int 否 数据类型：1=可见所有人数据 2=管辖范围下数据
status int 否 状态：1=已启用 2=已停用
请求示例
GET /api/open/applications/list?customer_id=17
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 9,
      "customer_id": 17,
      "app_code": "leave",
      "app_name": "请销假",
      "app_url": "http://u.startower.online/#/applications/applications",
      "short_intro": "便捷签到，实时统计",
      "description": "签到晚点应用支持学生签到、晚点记录、统计分析等功能",
      "icon": "uploads/2026-01-05/attachments/e43cdfb92eaf9c9a226ade0d4cd29382.jpg",
      "data_type": 1,
      "status": 1,
      "created_at": 1770690212
    },
    {
      "id": 6,
      "customer_id": 17,
      "app_code": "repair",
      "app_name": "维修报修",
      "app_url": "repair/index",
      "short_intro": "快速报修，高效处理",
      "description": "公寓维修应用支持在线报修、工单管理、维修工分配、评价反馈等功能",
      "icon": "http://1.13.252.190:10087/uploads/2026-01-05/attachments/0a4623cb44683c10836ab198a12bae29.jpg",
      "data_type": 2,
      "status": 1,
      "created_at": 1770196086,
      "scope": {
        "id": 1,
        "customer_id": 17,
        "application_id": 6,
        "range_type": "4",
        "student_ids": "32,37,38,39,40,44",
        "staff_ids": "33,34,35,41,45,46,52",
        "role_ids": "38",
        "department_ids": "4103,4135,4104,4137,4138,4139,4174,4105,4107,..."
      }
    }
  ]
}

10. 获取可见应用

GET /api/open/applications/visible
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
customer_id int 是 学校ID
person_id int 否 人员ID
person_type int 否 人员类型：1=学生 2=政工
role_ids string 否 角色ID列表（逗号分隔）
department_ids string 否 部门ID列表（逗号分隔）
可见性判断逻辑：
  • range_type=1：全部人员可见
  • range_type=2：学生可见（person_type=1）
  • range_type=3：政工可见（person_type=2）
  • range_type=4：指定角色可见（role_ids 有交集）
  • range_type=5：指定部门可见（department_ids 有交集）
请求示例
GET /api/open/applications/visible?customer_id=17
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 9,
      "customer_id": 17,
      "app_code": "leave",
      "app_name": "请销假",
      "app_url": "http://u.startower.online/#/applications/applications",
      "short_intro": "便捷签到，实时统计",
      "description": "签到晚点应用支持学生签到、晚点记录、统计分析等功能",
      "icon": "uploads/2026-01-05/attachments/e43cdfb92eaf9c9a226ade0d4cd29382.jpg",
      "data_type": 1,
      "status": 1,
      "created_at": 1770690212
    }
  ]
}

11. 查询政工列表

GET /api/open/staff/list
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
person_id string 否 人员ID（支持逗号分隔多个）
name string 否 姓名（支持逗号分隔多个，模糊查询）
staff_no string 否 工号（支持逗号分隔多个）
department_id int 否 部门ID
department_ids string 否 部门ID列表（逗号分隔，与department_id二选一）
college_id int 否 学院ID
college_ids string 否 学院ID列表（逗号分隔，与college_id二选一）
faculty_id int 否 系ID
faculty_ids string 否 系ID列表（逗号分隔，与faculty_id二选一）
with_contact int 否 是否显示联系方式：1=显示手机、邮箱、性别、状态
page int 否 页码（默认1）
page_size int 否 每页数量（默认20，最大1000）
请求示例
GET /api/open/staff/list?university_id=17&page=1&page_size=20
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "person_id": 33,
        "name": "斯内普",
        "staff_no": "0001",
        "department_id": 4104,
        "college_id": 4106,
        "faculty_id": null
      },
      {
        "person_id": 34,
        "name": "Albus Dumbledore",
        "staff_no": "0002",
        "department_id": 4139,
        "college_id": null,
        "faculty_id": null
      },
      {
        "person_id": 35,
        "name": "格拉普兰",
        "staff_no": "0003",
        "department_id": 4104,
        "college_id": 4108,
        "faculty_id": null
      }
    ],
    "total": 8,
    "page": 1,
    "page_size": 20
  }
}

12. 查询学生列表

GET /api/open/students/list
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
person_id string 否 人员ID（支持逗号分隔多个）
name string 否 姓名（支持逗号分隔多个，模糊查询）
student_no string 否 学号（支持逗号分隔多个）
area_id int 否 校区ID
grade string 否 年级
education_level string 否 教育层次
school_system string 否 学制
id_card string 否 身份证号
admission_no string 否 录取编号
exam_no string 否 准考证号
enrollment_status int 否 学籍状态：1=在读 2=休学 3=毕业 4=退学 5=停学 6=复学 7=未报到 8=结业 9=肄业 10=转学 11=死亡 12=开除 13=参军 14=保留学籍 15=其他
is_enrolled int 否 报到状态：1=已报到 2=未报到
college_id int 否 学院ID
college_ids string 否 学院ID列表（逗号分隔，与college_id二选一）
faculty_id int 否 系ID
faculty_ids string 否 系ID列表（逗号分隔，与faculty_id二选一）
profession_id int 否 专业ID
profession_ids string 否 专业ID列表（逗号分隔，与profession_id二选一）
class_id int 否 班级ID
class_ids string 否 班级ID列表（逗号分隔，与class_id二选一）
with_contact int 否 是否显示联系方式：1=显示手机、邮箱、性别、状态
page int 否 页码（默认1）
page_size int 否 每页数量（默认20，最大1000）
请求示例
GET /api/open/students/list?university_id=17&page=1&page_size=20
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "person_id": 32,
        "name": "哈利波特大",
        "student_no": "8989",
        "area_id": null,
        "grade": "2025",
        "education_level": "博士研究生",
        "school_system": "4",
        "id_card": "",
        "admission_no": "",
        "exam_no": "",
        "enrollment_status": 1,
        "is_enrolled": 1,
        "college_id": 4106,
        "faculty_id": 4165,
        "profession_id": 4114,
        "class_id": 4121
      },
      {
        "person_id": 37,
        "name": "罗恩",
        "student_no": "0001",
        "area_id": null,
        "grade": "2025",
        "education_level": "本科",
        "school_system": "4",
        "id_card": "",
        "admission_no": "",
        "exam_no": "",
        "enrollment_status": 1,
        "is_enrolled": 1,
        "college_id": 4106,
        "faculty_id": 4165,
        "profession_id": 4114,
        "class_id": 4121
      },
      {
        "person_id": 38,
        "name": "赫敏",
        "student_no": "0002",
        "area_id": null,
        "grade": "2025",
        "education_level": "专科",
        "school_system": "4",
        "id_card": "",
        "admission_no": "",
        "exam_no": "",
        "enrollment_status": 1,
        "is_enrolled": 1,
        "college_id": 4109,
        "faculty_id": null,
        "profession_id": 4124,
        "class_id": 4129
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 20
  }
}

13. 按组织机构查询政工（OR条件）

GET /api/open/staff/by-org
与 /api/open/staff/list 的区别：本接口的组织机构条件为 OR 关系，即满足 department_ids、college_ids、faculty_ids 中任意一个条件即可匹配。适用于查询"属于部门A 或 学院B 或 系C"的政工人员。
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
department_ids string 否* 部门ID列表（逗号分隔，如：1,2,3）
college_ids string 否* 学院ID列表（逗号分隔，如：4,5）
faculty_ids string 否* 系ID列表（逗号分隔，如：6,7,8）
with_contact int 否 是否显示联系方式：1=显示手机、邮箱、性别、状态
page int 否 页码（默认1）
page_size int 否 每页数量（默认20，最大1000）
*注意：department_ids、college_ids、faculty_ids 三个参数至少需要填写一个。
SQL逻辑
SELECT * FROM staff 
WHERE university_id = ? 
  AND (department_id IN (1,2,3) OR college_id IN (4,5) OR faculty_id IN (6,7,8))
请求示例
GET /api/open/staff/by-org?university_id=17&department_ids=4104,4139&college_ids=4106,4108
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "person_id": 33,
        "name": "斯内普",
        "staff_no": "0001",
        "department_id": 4104,
        "college_id": 4106,
        "faculty_id": null
      },
      {
        "person_id": 34,
        "name": "Albus Dumbledore",
        "staff_no": "0002",
        "department_id": 4139,
        "college_id": null,
        "faculty_id": null
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }
}

14. 按组织机构查询学生（OR条件）

GET /api/open/students/by-org
与 /api/open/students/list 的区别：本接口的组织机构条件为 OR 关系，即满足 college_ids、faculty_ids、profession_ids、class_ids 中任意一个条件即可匹配。适用于查询"属于学院A 或 系B 或 专业C 或 班级D"的学生。
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
college_ids string 否* 学院ID列表（逗号分隔，如：1,2）
faculty_ids string 否* 系ID列表（逗号分隔，如：3,4）
profession_ids string 否* 专业ID列表（逗号分隔，如：5,6,7）
class_ids string 否* 班级ID列表（逗号分隔，如：8,9）
with_contact int 否 是否显示联系方式：1=显示手机、邮箱、性别、状态
page int 否 页码（默认1）
page_size int 否 每页数量（默认20，最大1000）
*注意：college_ids、faculty_ids、profession_ids、class_ids 四个参数至少需要填写一个。
SQL逻辑
SELECT * FROM students 
WHERE university_id = ? 
  AND (college_id IN (1,2) OR faculty_id IN (3,4) OR profession_id IN (5,6,7) OR class_id IN (8,9))
请求示例
GET /api/open/students/by-org?university_id=17&college_ids=4106,4109&profession_ids=4114,4124
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "person_id": 32,
        "name": "哈利波特大",
        "student_no": "8989",
        "area_id": null,
        "grade": "2025",
        "education_level": "博士研究生",
        "school_system": "4",
        "id_card": "",
        "admission_no": "",
        "exam_no": "",
        "enrollment_status": 1,
        "is_enrolled": 1,
        "college_id": 4106,
        "faculty_id": 4165,
        "profession_id": 4114,
        "class_id": 4121
      },
      {
        "person_id": 38,
        "name": "赫敏",
        "student_no": "0002",
        "area_id": null,
        "grade": "2025",
        "education_level": "专科",
        "school_system": "4",
        "id_card": "",
        "admission_no": "",
        "exam_no": "",
        "enrollment_status": 1,
        "is_enrolled": 1,
        "college_id": 4109,
        "faculty_id": null,
        "profession_id": 4124,
        "class_id": 4129
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }
}

15. 查询角色列表

GET /api/open/roles/list
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
请求示例
GET /api/open/roles/list?university_id=17
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 38,
      "parent_id": 0,
      "name": "辅导员",
      "permissions": "[30,31,37,43,49,55,56,65]"
    },
    {
      "id": 42,
      "parent_id": 0,
      "name": "魔法教授",
      "permissions": "[55,56,65]"
    },
    {
      "id": 43,
      "parent_id": 0,
      "name": "校长",
      "permissions": "[105,111,112,118,119,126,133,136,139,140,146,30,31,37,43,49,55,56,65,73,74,81,87,93,99]"
    },
    {
      "id": 45,
      "parent_id": 38,
      "name": "班长",
      "permissions": "[30,31,37,43,49,55,56,65]"
    },
    {
      "id": 55,
      "parent_id": 0,
      "name": "副校长",
      "permissions": ""
    }
  ]
}
说明：permissions 字段为逗号分隔的菜单ID列表，表示该角色拥有的菜单权限。

16. 查询管辖某人员的管理者

GET /api/open/persons/managers
接口说明
功能：根据人员ID，查询所有管辖该人员的管理者列表。返回每个管理者的基本信息、所持角色及角色对应的管辖机构。

查询逻辑：根据目标人员所属的机构（学生取学院/系/专业/班级，政工取部门/学院/系），在 persons_has_department 表中匹配管辖了这些机构的人员。
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
person_id int 是 被管辖的人员ID
请求示例
GET /api/open/persons/managers?university_id=17&person_id=35
Authorization: your_open_key_here
响应参数
参数名 类型 说明
manage_persons array 管辖该人员的管理者列表
manage_persons[].person_id int 管理者人员ID
manage_persons[].person_name string 管理者姓名
manage_persons[].roles array 管理者持有的角色列表
manage_persons[].roles[].role_id int 角色ID
manage_persons[].roles[].role_name string 角色名称
manage_persons[].roles[].departments array 该角色管辖的机构列表
manage_persons[].roles[].departments[].department_id int 机构ID
manage_persons[].roles[].departments[].department_name string 机构名称
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "manage_persons": [
      {
        "person_id": 45,
        "person_name": "亚瑟",
        "roles": [
          {
            "role_id": 38,
            "role_name": "辅导员",
            "departments": [
              {
                "department_id": 4108,
                "department_name": "赫奇帕奇"
              }
            ]
          }
        ]
      },
      {
        "person_id": 52,
        "person_name": "伏地魔",
        "roles": [
          {
            "role_id": 38,
            "role_name": "辅导员",
            "departments": [
              {
                "department_id": 4104,
                "department_name": "行政机构"
              },
              {
                "department_id": 4108,
                "department_name": "赫奇帕奇"
              }
            ]
          }
        ]
      }
    ]
  }
}
注意：
  • 返回结果不包含被查询人员自身（即使该人员也有管辖角色）
  • departments 仅返回与被查询人员所属机构匹配的管辖机构，不是管理者的全部管辖机构
  • 如果人员不存在或未关联任何机构，返回空的 manage_persons 数组

17. 查询学校列表

GET /api/open/colleges/list
接口说明
功能：查询所有学校（高校）列表，数据来源于 admin_users 表中 creator_id=0 的记录。支持按用户名、手机号、状态筛选，支持分页。
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
username string 否 学校名称（模糊查询）
mobile string 否 手机号
status int 否 状态：1=启用 2=停用
page int 否 页码（默认1）
page_size int 否 每页数量（默认20，最大1000）
请求示例
GET /api/open/colleges/list
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "university_id": 17,
        "username": "霍格沃茨魔法学校",
        "mobile": "13800000001",
        "status": 1
      },
      {
        "university_id": 18,
        "username": "布斯巴顿魔法学院",
        "mobile": "13800000002",
        "status": 1
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20
  }
}

18. 查询校区列表

GET /api/open/campus-areas/list
接口说明
功能：根据学校ID查询校区列表，返回 campus_areas 表中 level<=1 且未删除的记录。
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
请求示例
GET /api/open/campus-areas/list?university_id=35
Authorization: your_open_key_here
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 93,
      "area_name": "应用测试大学"
    }
  ]
}

19. 根据角色查询人员列表

GET /api/open/roles/persons
接口说明
功能：根据角色ID或角色名称查询该角色下的人员详情列表。支持多角色查询（逗号分隔），返回人员基本信息及学生/政工扩展信息（含组织机构名称）。
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
role_ids string 否* 角色ID列表（逗号分隔，如 68,63）
role_name string 否* 角色名称（与 role_ids 二选一）
page int 否 页码（默认1）
page_size int 否 每页数量（默认20，最大1000）
注意：role_ids 和 role_name 至少需要提供一个参数。
请求示例
GET /api/open/roles/persons?university_id=17&role_ids=38,42&page=1&page_size=20
Authorization: your_open_key_here
响应参数
参数名 类型 说明
items[].person_id int 人员ID
items[].person_type int 人员类型：1=学生 2=政工
items[].name string 姓名
items[].mobile string 手机号
items[].status int 状态
items[].student_no string 学号（仅学生）
items[].staff_no string 工号（仅政工）
items[].college_id int 学院ID
items[].college_name string 学院名称
items[].faculty_id int 系ID
items[].faculty_name string 系名称
items[].department_id int 部门ID（仅政工）
items[].department_name string 部门名称（仅政工）
items[].profession_id int 专业ID（仅学生）
items[].profession_name string 专业名称（仅学生）
items[].class_id int 班级ID（仅学生）
items[].class_name string 班级名称（仅学生）
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "person_id": 33,
        "person_type": 2,
        "name": "斯内普",
        "mobile": "13900000001",
        "status": 1,
        "staff_no": "0001",
        "department_id": 4104,
        "department_name": "行政机构",
        "college_id": 4106,
        "college_name": "格兰芬多学院"
      },
      {
        "person_id": 37,
        "person_type": 1,
        "name": "罗恩",
        "mobile": "13900000002",
        "status": 1,
        "student_no": "0001",
        "college_id": 4106,
        "college_name": "格兰芬多学院",
        "faculty_id": 4165,
        "faculty_name": "魔药学系",
        "profession_id": 4114,
        "profession_name": "魔药学",
        "class_id": 4121,
        "class_name": "魔药学2025级1班"
      }
    ],
    "total": 5,
    "page": 1,
    "page_size": 20
  }
}
说明：
  • person_type=1 为学生，返回 student_no、college、faculty、profession、class 等学生扩展字段
  • person_type!=1 为政工，返回 staff_no、department、college、faculty 等政工扩展字段
  • 所有组织机构ID同时返回对应的名称字段（如 college_id 对应 college_name）

20. 根据角色查询人员及管辖机构

GET /api/open/roles/persons-departments
接口说明
功能：根据角色ID列表查询该角色下的人员及其管辖的机构列表。返回每个角色下的人员信息，以及每个人员在该角色下管辖的所有机构。
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
role_ids string 是 角色ID列表（逗号分隔，如 38,42）
请求示例
GET /api/open/roles/persons-departments?university_id=17&role_ids=38,42
Authorization: your_open_key_here
响应参数
参数名 类型 说明
items[].role_id int 角色ID
items[].role_name string 角色名称
items[].person_id int 人员ID
items[].person_name string 人员姓名
items[].departments array 该人员在此角色下管辖的机构列表
items[].departments[].department_id int 机构ID
items[].departments[].department_name string 机构名称
items[].departments[].department_type int 机构类型：0=学校 1=行政机构 2=学院 3=系 4=专业 5=班级
响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "role_id": 38,
        "role_name": "学院管理员",
        "person_id": 33,
        "person_name": "张三",
        "departments": [
          {
            "department_id": 4106,
            "department_name": "格兰芬多学院",
            "department_type": 2
          },
          {
            "department_id": 4165,
            "department_name": "魔药学系",
            "department_type": 3
          }
        ]
      },
      {
        "role_id": 38,
        "role_name": "学院管理员",
        "person_id": 37,
        "person_name": "李四",
        "departments": [
          {
            "department_id": 4107,
            "department_name": "斯莱特林学院",
            "department_type": 2
          }
        ]
      },
      {
        "role_id": 42,
        "role_name": "系主任",
        "person_id": 33,
        "person_name": "张三",
        "departments": [
          {
            "department_id": 4165,
            "department_name": "魔药学系",
            "department_type": 3
          },
          {
            "department_id": 4114,
            "department_name": "魔药学专业",
            "department_type": 4
          }
        ]
      }
    ]
  }
}
说明：
  • 返回结果按 role_id、person_id 排序
  • 同一个人员可能在多个角色下，会返回多条记录
  • 每条记录的 departments 数组包含该人员在该角色下管辖的所有机构
  • 如果某人员在某角色下没有管辖任何机构，departments 为空数组
  • 数据来源：persons_has_roles（角色-人员关系）+ persons_has_department（人员-角色-机构关系）

21. 查询部门列表

GET /api/open/departments/list
接口说明
功能：根据学校ID查询该校所有部门列表，返回部门ID、父级ID、部门名称和部门类型。
请求头
参数名 类型 必填 说明
Authorization string 是 OPEN_KEY 秘钥
请求参数
参数名 类型 必填 说明
university_id int 是 学校ID
请求示例
GET /api/open/departments/list?university_id=35
Authorization: your_open_key_here
响应参数
参数名 类型 说明
id int 部门ID
parent_id int 父级部门ID（0表示顶级）
department_name string 部门名称
department_type int 机构类型：0=学校 1=行政机构 2=学院 3=系 4=专业 5=班级
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 24759,
      "parent_id": 0,
      "department_name": "应用测试大学",
      "department_type": 0
    },
    {
      "id": 24760,
      "parent_id": 24759,
      "department_name": "行政机构",
      "department_type": 1
    },
    {
      "id": 24788,
      "parent_id": 24760,
      "department_name": "行政服务中心",
      "department_type": 1
    },
    {
      "id": 24789,
      "parent_id": 24788,
      "department_name": "校领导办公室",
      "department_type": 1
    },
    {
      "id": 24761,
      "parent_id": 24759,
      "department_name": "组织机构",
      "department_type": 2
    },
    {
      "id": 24773,
      "parent_id": 24761,
      "department_name": "教务处",
      "department_type": 2
    },
    {
      "id": 24774,
      "parent_id": 24761,
      "department_name": "计算机学院",
      "department_type": 2
    },
    {
      "id": 24775,
      "parent_id": 24774,
      "department_name": "web方向",
      "department_type": 4
    },
    {
      "id": 24776,
      "parent_id": 24775,
      "department_name": "1班",
      "department_type": 5
    },
    {
      "id": 24790,
      "parent_id": 24761,
      "department_name": "计算机科学与技术学院",
      "department_type": 2
    },
    {
      "id": 24791,
      "parent_id": 24790,
      "department_name": "软件工程",
      "department_type": 4
    },
    {
      "id": 24792,
      "parent_id": 24791,
      "department_name": "软工一班",
      "department_type": 5
    },
    {
      "id": 24793,
      "parent_id": 24761,
      "department_name": "物理与信息工程学院",
      "department_type": 2
    },
    {
      "id": 24794,
      "parent_id": 24793,
      "department_name": "太空",
      "department_type": 3
    },
    {
      "id": 24795,
      "parent_id": 24794,
      "department_name": "量子力学",
      "department_type": 4
    },
    {
      "id": 24796,
      "parent_id": 24795,
      "department_name": "三年六班",
      "department_type": 5
    },
    {
      "id": 24797,
      "parent_id": 24761,
      "department_name": "花果山",
      "department_type": 3
    },
    {
      "id": 24798,
      "parent_id": 24797,
      "department_name": "选桃",
      "department_type": 4
    }
  ]
}

20. 批量查询人员信息

POST /api/open/persons/batch
接口说明
功能：批量查询人员信息，包含人员基础信息、组织机构信息、角色列表及每个角色管辖的机构列表、管理该人员的上级ID列表。支持一次查询最多30个人员。
请求头
参数名 类型 必填 说明
Content-Type string 是 application/json 或 application/x-www-form-urlencoded
Authorization string 是 OPEN_KEY 秘钥
请求参数
支持三种格式：
  • JSON格式（推荐）：{"person_ids": [1, 2, 3]}
  • form-data逗号分隔：person_ids=1,2,3
  • form-data数组：person_ids[]=1&person_ids[]=2
参数名 类型 必填 说明
person_ids array[int] 或 string 是 人员ID列表，最少1个，最多30个
请求示例
POST /api/open/persons/batch
Authorization: your_open_key_here
Content-Type: application/json

{
  "person_ids": [184, 186]
}
或使用 form-data 格式
POST /api/open/persons/batch
Authorization: your_open_key_here
Content-Type: application/x-www-form-urlencoded

person_ids=184,186
响应示例
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "person_id": 184,
      "name": "张三",
      "person_type": 2,
      "gender": 1,
      "mobile": "13800138000",
      "email": "zhangsan@example.com",
      "avatar": "https://example.com/avatar.jpg",
      "status": 1,
      "organization": {
        "staff_no": "S001",
        "department_id": 10,
        "department_name": "行政部",
        "college_id": 5,
        "college_name": "计算机学院",
        "faculty_id": 8,
        "faculty_name": "软件工程系"
      },
      "roles": [
        {
          "role_id": 100,
          "role_name": "部门主管",
          "parent_id": 99,
          "parent_name": "管理层",
          "managed_depts": [
            {
              "id": 10,
              "parent_id": 5,
              "department_name": "行政部",
              "department_type": 1,
              "status": 1
            }
          ]
        }
      ],
      "manager_ids": [50, 51]
    },
    {
      "person_id": 186,
      "name": "李四",
      "person_type": 1,
      "gender": 2,
      "mobile": "13900139000",
      "email": "lisi@example.com",
      "avatar": "",
      "status": 1,
      "organization": {
        "student_no": "2024001",
        "college_id": 5,
        "college_name": "计算机学院",
        "faculty_id": 8,
        "faculty_name": "软件工程系",
        "profession_id": 20,
        "profession_name": "软件工程",
        "class_id": 30,
        "class_name": "软件2401班"
      },
      "roles": [
        {
          "role_id": 200,
          "role_name": "班长",
          "parent_id": 199,
          "parent_name": "学生干部",
          "managed_depts": [
            {
              "id": 30,
              "parent_id": 20,
              "department_name": "软件2401班",
              "department_type": 4,
              "status": 1
            }
          ]
        }
      ],
      "manager_ids": [45, 46, 47]
    }
  ]
}
响应字段说明
字段名 类型 说明
person_id int 人员ID
name string 姓名
person_type int 人员类型：1=学生, 2=政工, 3=维修工
gender int 性别：1=男, 2=女
organization object 组织机构信息（学生和政工返回不同字段）
roles array 角色列表
roles[].role_id int 角色ID
roles[].role_name string 角色名称
roles[].managed_depts array 该角色管辖的机构列表
manager_ids array[int] 管理该人员的上级ID列表（根据人员所在组织机构查询管辖这些机构的人员）
注意事项：
  • 一次最多查询30个人员ID
  • 如果某个人员ID不存在，不会返回该人员的信息，也不会报错
  • 返回结果的顺序与请求的person_ids顺序一致
  • 如果人员没有角色，roles字段为空数组
  • 如果角色没有管辖机构，managed_depts字段为空数组
  • organization字段根据person_type返回不同的结构（学生或政工）
  • manager_ids 自动排除自己，不会把自己列为自己的管理者