🎓 星塔校园 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 表示该政工人员可见的总人员数。
认证说明：开放接口使用秘钥认证，需要在请求头中携带 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/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
    }
  ]
}