数据权限与组织树接口对接文档

文档版本：v1.0
更新日期：2026-05-01
适用对象：前端开发人员

---

一、概述

本文档说明系统中数据权限相关的组织树接口和列表接口的对接规范，帮助前端正确调用接口并处理权限相关的交互。

---

二、组织树结构说明

系统存在两种组织树结构：

2.1 4级结构（新版）

公司
└── 厂处（部门）
    └── 班组
        └── 岗位

适用模块：三级安全教育、师带徒、实操考核、题库管理（新）

特殊规则：

• 岗位只属于班组，不能直接挂在厂处下
• 厂处下没有班组时，该厂处节点不返回岗位列表（保留空厂处节点）
• 班组下没有岗位时，该班组节点仍然返回（job_list 为空数组）

2.2 3级结构（旧版）

公司
└── 厂处（部门）
    └── 岗位

适用模块：题库管理（旧）、管理人员信息、教材库、汇总台账

---

三、接口对照表

3.1 4级结构模块（公司=>厂处=>班组=>岗位）

模块	左侧组织树接口(修改了题库管理)	右侧列表接口(未调整)	scope类型	接口文档地址
三级安全教育(这个好像没在用了)	/adminapi/v2.training_new.three_edu/getDeptWithJobs	/adminapi/v2.training_new.three_edu/lists	training_scope	获取组织树-带模板统计 GET /adminapi/v2.training_new.three_edu/getDeptWithJobs 接口ID：386590822 接口地址：https://app.apifox.com/link/project/6218103/apis/api-386590822
三级安全教育绑定	/adminapi/v2.training_new.three_edu/getDeptWithJobsBind	（同上）	training_scope	获取组织树-岗位是否设置模板 GET /adminapi/v2.training_new.three_edu/getDeptWithJobsBind 接口ID：387453577 接口地址：https://app.apifox.com/link/project/6218103/apis/api-387453577
师带徒	/adminapi/v2.training_new.teacher_student/getDeptWithJobProtocolSetting	/adminapi/v2.training_new.teacher_student/protocolList	training_scope	获取组织树（附岗位是否已设置协议） GET /adminapi/v2.training_new.teacher_student/getDeptWithJobProtocolSetting 接口ID：388677329 接口地址：https://app.apifox.com/link/project/6218103/apis/api-388677329
实操考核	/adminapi/v2.training_new.teacher_student_exam_tpl/getDeptWithJobExamSetting	/adminapi/v2.training_new.teacher_student_exam_tpl/list	training_scope	获取组织树-岗位是否已设置模板 GET /adminapi/v2.training_new.teacher_student_exam_tpl/getDeptWithJobExamSetting 接口ID：388759221 接口地址：https://app.apifox.com/link/project/6218103/apis/api-388759221
题库管理（新）, 旧的接口改为现在这个	/adminapi/dept.dept/getDeptWithJobsV2	/adminapi/v2.exam.question_cate/lists	exam_scope	获取组织树-通用-4级层级 GET /adminapi/dept.dept/getDeptWithJobsV2 接口ID：452234243 接口地址：https://app.apifox.com/link/project/6218103/apis/api-452234243

3.2 3级结构模块（公司=>厂处=>岗位）

模块	左侧组织树接口	右侧列表接口	scope类型	接口文档地址
管理人员信息	/adminapi/dept.dept/getDeptWittJobs	/adminapi/auth.admin/lists	ledger_scope	获取组织树-通用-3级结构 GET /adminapi/dept.dept/getDeptWittJobs 接口ID：357837963 接口地址：https://app.apifox.com/link/project/6218103/apis/api-357837963
教材库	/adminapi/dept.dept/getDeptWittJobs	/adminapi/file/lists	ledger_scope	同上
汇总台账-岗位	/adminapi/dept.jobs/all	/adminapi/v2.ledger.ledger/summary	ledger_scope	所有 GET /adminapi/dept.dept/all 接口ID：286524260 接口地址：https://app.apifox.com/link/project/6218103/apis/api-286524260

---

四、接口列表

4.1 4级结构模块接口

4.1.1 三级安全教育

接口	方法	说明
/adminapi/v2.training_new.three_edu/getDeptWithJobs	GET	获取组织树（含模板数量统计）
/adminapi/v2.training_new.three_edu/getDeptWithJobsBind	GET	获取组织树（含模板绑定状态）
/adminapi/v2.training_new.three_edu/lists	GET	三级安全教育模板列表

组织树返回示例：

{
  "code": 1,
  "data": [
    {
      "id": 36,
      "name": "XX公司",
      "level": 1,
      "tpl_count": 10,
      "children": [
        {
          "id": 179,
          "name": "安全环保处",
          "level": 2,
          "tpl_count": 5,
          "children": [
            {
              "id": 180,
              "name": "安全管理班组",
              "level": 3,
              "job_list": [
                { "jobs_id": 120, "jobs_name": "安全管理员" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

列表接口参数：

参数	类型	必填	说明
page_no	int	是	页码
page_size	int	是	每页数量
name	string	否	模板名称（模糊搜索）
company_id	int	是	公司ID
dept_id	int	否	厂处ID
group_id	int	否	班组ID
job_id	int	否	岗位ID

---

4.1.2 师带徒

接口	方法	说明
/adminapi/v2.training_new.teacher_student/getDeptWithJobProtocolSetting	GET	获取组织树（含协议绑定状态）
/adminapi/v2.training_new.teacher_student/protocolList	GET	师带徒协议列表

列表接口参数：

参数	类型	必填	说明
page_no	int	是	页码
page_size	int	是	每页数量
name	string	否	协议名称（模糊搜索）
company_id	int	是	公司ID
dept_id	int	否	厂处ID
group_id	int	否	班组ID
job_id	int	否	岗位ID

---

4.1.3 实操考核

接口	方法	说明
/adminapi/v2.training_new.teacher_student_exam_tpl/getDeptWithJobExamSetting	GET	获取组织树（含考核模板绑定状态）
/adminapi/v2.training_new.teacher_student_exam_tpl/list	GET	实操考核模板列表

列表接口参数：

参数	类型	必填	说明
page_no	int	是	页码
page_size	int	是	每页数量
tpl_name	string	否	模板名称（模糊搜索）
company_id	int	是	公司ID
dept_id	int	否	厂处ID
group_id	int	否	班组ID
job_id	int	否	岗位ID

---

4.1.4 题库管理（新 - 4级结构）

接口	方法	说明
/adminapi/dept.dept/getDeptWithJobsV2	GET	通用4级组织树接口
/adminapi/v2.exam.question_cate/lists	GET	题库分类列表

组织树返回示例：

{
  "code": 1,
  "data": [
    {
      "id": 36,
      "name": "XX公司",
      "children": [
        {
          "id": 179,
          "name": "安全环保处",
          "children": [
            {
              "id": 180,
              "name": "安全管理班组",
              "job_list": [
                { "jobs_id": 120, "jobs_name": "安全管理员" }
              ]
            },
            {
              "id": 181,
              "name": "空班组（无岗位）",
              "job_list": []
            }
          ]
        },
        {
          "id": 182,
          "name": "无班组的厂处",
          "children": []
        }
      ]
    }
  ]
}

说明：

• 岗位只挂在班组下（job_list 在班组节点中）
• 厂处下没有班组时，children 为空数组，不返回岗位列表
• 班组下没有岗位时，job_list 为空数组

列表接口参数：

参数	类型	必填	说明
page_no	int	是	页码
page_size	int	是	每页数量
name	string	否	分类名称（模糊搜索）
is_show	string	否	显示状态（all/0/1）
company_id	int	是	公司ID
dept_id	int	否	厂处ID
group_id	int	否	班组ID
job_id	int	否	岗位ID
is_share	int	否	是否共享（0/1）

---

4.2 3级结构模块接口

4.2.1 题库管理（旧 - 3级结构）

接口	方法	说明
/adminapi/dept.dept/getDeptWittJobs	GET	3级组织树接口
/adminapi/v2.exam.question_cate/lists	GET	题库分类列表

组织树返回示例：

{
  "code": 1,
  "data": [
    {
      "id": 36,
      "name": "XX公司",
      "children": [
        {
          "id": 179,
          "name": "安全环保处",
          "job_list": [
            { "jobs_id": 120, "jobs_name": "安全管理员" }
          ]
        }
      ]
    }
  ]
}

---

4.2.2 管理人员信息

接口	方法	说明
/adminapi/dept.dept/getDeptWittJobs	GET	3级组织树接口
/adminapi/auth.admin/lists	GET	人员列表

列表接口参数：

参数	类型	必填	说明
page_no	int	是	页码
page_size	int	是	每页数量
account	string	否	账号（模糊搜索）
name	string	否	姓名（模糊搜索）
company_id	int	是	公司ID
dept_id	int	否	厂处ID
job_id	int	否	岗位ID
role_id	int	否	角色ID
is_working	int	否	是否在职

---

4.2.3 教材库

接口	方法	说明
/adminapi/dept.dept/getDeptWittJobs	GET	3级组织树接口
/adminapi/file/lists	GET	文件列表

列表接口参数：

参数	类型	必填	说明
page_no	int	是	页码
page_size	int	是	每页数量
name	string	否	文件名（模糊搜索）
type	int	否	文件类型
company_id	int	是	公司ID
dept_id	int	否	厂处ID
job_id	int	否	岗位ID
cid	int	否	分类ID
is_share	int	否	是否共享（0/1）

---

五、数据权限与越级校验

5.1 权限级别说明

权限级别	值	说明
全公司	1	可查看公司级及以下所有数据
本厂处	2	只能查看本厂处及以下数据
本班组	3	只能查看本班组及以下数据
仅本人	4	只能查看本人数据

5.2 越级查看拦截

当用户尝试查看超出其权限级别的数据时，接口将返回错误响应。

拦截返回格式：

5.4 参数传递规则

4级结构模块

• 点击公司节点：传 company_id，不传 dept_id、不传group_id、不传job_id
• 点击厂处节点：传 company_id + dept_id，不传 group_id、不传job_id
• 点击班组节点：传 company_id + dept_id + group_id，不传 job_id
• 点击岗位节点：传 company_id + dept_id + group_id + job_id

3级结构模块

• 点击公司节点：传 company_id，不传 dept_id、不传job_id
• 点击厂处节点：传 company_id + dept_id，不传 job_id
• 点击岗位节点：传 company_id + dept_id + job_id

5.5 越级拦截规则速查表

4级结构

用户权限	点击公司	点击厂处	点击班组	点击岗位
全公司(1)	✅	✅	✅	✅
本厂处(2)	❌	✅	✅	✅
本班组(3)	❌	❌	✅	✅
仅本人(4)	❌	❌	❌	❌

3级结构

用户权限	点击公司	点击厂处	点击岗位
全公司(1)	✅	✅	✅
本厂处(2)	❌	✅	✅
本班组(3)	❌	❌	✅*
仅本人(4)	❌	❌	❌

*注：3级结构中，班组级用户只能查看对应自己的 job_id 数据，必须传入 job_id 参数

---

六、组织树数据过滤

6.1 说明

组织树接口会根据用户的数据权限自动过滤，只返回用户有权限查看的节点。

---

---

七、常见问题

Q1: 为什么组织树返回空数组？

A: 当用户权限为"仅本人(4)"时，组织树接口会返回空数组，因为组织架构无本人维度意义。

Q2: 为什么列表接口返回"请到对应层级查看"？

A: 用户尝试查看超出其权限级别的数据。例如班组级用户点击了公司节点或厂处节点。

Q3: 4级结构和3级结构如何选择？

A:

• 新模块统一使用4级结构（/adminapi/dept.dept/getDeptWithJobsV2）
• 旧模块保持兼容，继续使用3级结构（/adminapi/dept.dept/getDeptWittJobs）

Q4: 如何判断当前用户的权限级别？

A: 权限级别由后端根据用户角色自动解析，前端无需关心。越级拦截时返回的 scope 和 scope_desc 可用于提示用户。

---