JeecgBoot 系统主数据查询与管理
查询和管理 JeecgBoot 系统中的角色、用户、部门、字典等主数据。遵循"先查后建"原则：优先使用系统已有数据，没有才创建。
前置条件
用户必须提供以下信息（或由 AI 引导确认）：
- API 地址：JeecgBoot 后端地址（如
https://boot3.jeecg.com/jeecgboot）
- X-Access-Token：JWT 登录令牌（从浏览器 F12 获取）
如果用户未提供，提示：
请提供 JeecgBoot 后端地址和 X-Access-Token（从浏览器 F12 → Network → 任意请求的 Request Headers 中复制）。
核心原则：先查后建
在任何 skill（流程设计、表单设计、代码生成等）需要使用主数据时，必须先查询系统已有数据，确认不存在后才创建新数据。
| 数据类型 | 查询函数 | 创建函数 | 一站式函数 |
|---|
| 角色 | query_roles() / find_role() | create_role() | find_or_create_role() |
| 角色绑定用户 | — | add_users_to_role(role_id, user_ids) | — |
| 审批角色 | query_approval_roles() / find_approval_role() | create_approval_role_group() + create_approval_role() | find_or_create_approval_role() |
| 审批角色绑定用户 | — | add_users_to_approval_role(role_id, user_ids) | — |
| 用户 | query_users() / find_user() | — | — |
| 部门 | query_depts() / find_dept() | — | — |
| 岗位 | query_dept_positions() | — | — |
| 字典（普通） | query_dict() / search_dict() / find_dict() | create_dict() | find_or_create_dict() |
| 字典（SQL表） | query_sql_table_dict() | — | — |
使用方式
脚本位置
scripts/system_creator.py — 通用命令行脚本（推荐，无需生成临时 .py）scripts/system_utils.py — 工具库（供其他 skill 脚本 import）
方式一：通用脚本 + 命令行（推荐）
单项查询（直接命令行，无需配置文件）：
SCRIPT="<skill目录>/jeecg-system/scripts/system_creator.py"
API="<api_base>"
TOKEN="eyJ..."
# 查询角色列表
python "$SCRIPT" --api-base $API --token $TOKEN --action query-roles
python "$SCRIPT" --api-base $API --token $TOKEN --action query-roles --keyword 经理
# 查询用户列表
python "$SCRIPT" --api-base $API --token $TOKEN --action query-users --keyword 张
# 查询部门树
python "$SCRIPT" --api-base $API --token $TOKEN --action query-depts
python "$SCRIPT" --api-base $API --token $TOKEN --action query-depts --keyword 研发
# 查询字典列表
python "$SCRIPT" --api-base $API --token $TOKEN --action query-dicts --keyword 请假
# 查询字典项
python "$SCRIPT" --api-base $API --token $TOKEN --action query-dict --code sex
# 查询职务列表
python "$SCRIPT" --api-base $API --token $TOKEN --action query-positions
# 查询部门+岗位树
python "$SCRIPT" --api-base $API --token $TOKEN --action query-dept-positions
# 查询审批角色
python "$SCRIPT" --api-base $API --token $TOKEN --action query-approval-roles
# 查询租户列表
python "$SCRIPT" --api-base $API --token $TOKEN --action query-tenants
# 查询数据源
python "$SCRIPT" --api-base $API --token $TOKEN --action query-datasources
# 查询定时任务
python "$SCRIPT" --api-base $API --token $TOKEN --action query-quartz-jobs
# 查询分类字典
python "$SCRIPT" --api-base $API --token $TOKEN --action query-categories --code B01
# 输出结果到 JSON 文件
python "$SCRIPT" --api-base $API --token $TOKEN --action query-roles --output roles.json
批量查找/创建（JSON 配置文件）：
# 1. Write 工具写入 JSON 配置文件
# 2. 执行脚本
python "$SCRIPT" --api-base $API --token $TOKEN --config master_data.json
# 3. 删除临时 JSON 文件
JSON 配置格式：
{
"roles": [
{"roleName": "部门经理", "roleCode": "dept_manager"},
{"roleName": "HR专员", "roleCode": "hr"}
],
"dicts": [
{
"dictCode": "leave_type",
"dictName": "请假类型",
"items": [
{"value": "1", "text": "事假"},
{"value": "2", "text": "病假"},
{"value": "3", "text": "年假"}
]
}
],
"users": [
{"keyword": "admin"},
{"username": "zhangsan"}
],
"depts": [
{"keyword": "研发部"},
{"departName": "人力资源部"}
],
"positions": [
{"keyword": "总经理"}
]
}
脚本自动完成：
- 角色/字典：先查后建（已有则跳过，没有则创建）
- 用户/部门/职务：只查不建（返回查询结果）
- 汇总输出所有查找/创建结果
- 可通过
--output result.json 保存结果
方式二：在临时脚本中 import 工具库
import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'jeecg-system', 'scripts'))
# 或直接用绝对路径: sys.path.insert(0, r'<skill目录>/jeecg-system/scripts')
from system_utils import *
init_api('<api_base>', '<token>')
# ====== 角色 ======
# 查询所有角色
roles = query_roles()
# 按名称模糊查询
roles = query_roles(keyword='经理')
# 查找单个角色
role = find_role('manager') # 按编码或名称
# 查找或创建（推荐）
role_code = find_or_create_role('项目经理', 'project_manager')
# ====== 用户 ======
# 查询用户列表
users = query_users(keyword='张')
users = query_users(username='admin')
# 查找单个用户
user = find_user('admin') # 按用户名或姓名
# ====== 部门 ======
# 查询部门树
depts = query_depts()
depts = query_depts(keyword='研发')
# 查找单个部门
dept = find_dept('研发部')
# 查询部门+岗位树
positions = query_dept_positions()
# ====== 字典 ======
# 查询字典项（普通字典，通过 /sys/api/getDictItems）
items = query_dict('sex') # → [{'value': '1', 'text': '男'}, ...]
# 查询 SQL 表字典项（通过 /sys/dict/getDictItems/{dictCode}，需签名）
items_sql = query_sql_table_dict("sys_user,realname,id,username!='admin' order by create_time")
# 搜索字典（按名称/编码模糊匹配）
dicts = search_dict('请假')
# 查找字典（含字典项）
d = find_dict('sex') # → {'dictCode': 'sex', 'dictName': '性别', 'items': [...]}
# 查找或创建字典（推荐）
dict_code = find_or_create_dict('leave_type', '请假类型', [
{'value': '1', 'text': '事假'},
{'value': '2', 'text': '病假'},
{'value': '3', 'text': '年假'},
])
# ====== 系统角色绑定用户 ======
# 创建角色并自动绑定 admin（默认行为）
role_code = find_or_create_role('财务审核', 'finance_audit')
# 不绑定 admin
role_code = find_or_create_role('只读角色', 'readonly', add_admin=False)
# 手动绑定用户到角色
role = find_role('finance_audit')
add_users_to_role(role['id'], ['e9ca23d68d884d4ebb19d07889727dae'])
# ====== 审批角色 ======
# 一站式：查找或创建审批角色（自动创建分组 + 角色 + 绑定 admin）
role_id = find_or_create_approval_role('财务审批专员', group_name='财务分组')
# 分步创建
group_id = create_approval_role_group('HR分组')
role_id = create_approval_role('HR审批专员', group_id, add_admin=True)
# 查询审批角色
res = query_approval_roles('财务') # {'roles': [...], 'persons': [...]}
role = find_approval_role('财务审批') # 单个或 None
# ====== 便捷打印 ======
print_roles() # 打印角色列表
print_users(keyword='张') # 打印用户列表
print_depts() # 打印部门树
print_dict('sex') # 打印字典项
print_dicts('请假') # 搜索并打印字典列表
在其他 skill 脚本中使用
其他 skill 的脚本可以直接导入 system_utils（需先加载 jeecg-system skill，从 Base directory for this skill: <skill_base_dir> 取得路径）：
import sys
sys.path.insert(0, r'<skill_base_dir>\scripts')
from system_utils import init_api, find_or_create_role, find_or_create_dict, query_dict, query_sql_table_dict
init_api(API_BASE, TOKEN)
# 流程设计时查询角色编码
role_code = find_or_create_role('部门经理', 'dept_manager')
# 表单设计时查询普通字典
items = query_dict('sex')
# 查询 SQL 表字典（带签名）
items_sql = query_sql_table_dict("sys_user,realname,id,username!='admin' order by create_time")
# 创建字典
dict_code = find_or_create_dict('leave_type', '请假类型', [
{'value': '1', 'text': '事假'},
{'value': '2', 'text': '病假'},
])
典型场景
场景1：流程审批人配置角色
# 需要配置"部门经理"角色作为审批人
role_code = find_or_create_role('部门经理', 'dept_manager')
# → 系统已有则返回现有编码，没有则创建后返回
# 在 BPMN 中使用: candidateGroups="{role_code}", groupType="role"
场景2：表单下拉字段配置字典
# 需要"请假类型"字典
d = find_dict('leave_type')
if d:
print(f'已有字典: {d["dictCode"]}, {len(d["items"])} 项')
# 直接使用现有字典编码
else:
# 创建新字典
find_or_create_dict('leave_type', '请假类型', [
{'value': '1', 'text': '事假'},
{'value': '2', 'text': '病假'},
])
场景3：查询部门/用户信息
# 查找用户用于流程指定审批人
user = find_user('张三')
if user:
username = user['username'] # 用于 flowable:assignee
# 查找部门用于审批配置
dept = find_dept('人力资源部')
if dept:
dept_id = dept['id'] # 用于 candidateGroups, groupType="dept"
API 接口速查
完整接口文档见 references/api-reference.md
各模块基础路径
| 模块 | 基础路径 | Controller |
|---|
| 用户 | /sys/user | SysUserController |
| 角色 | /sys/role | SysRoleController |
| 部门（公司/子公司/岗位） | /sys/sysDepart | SysDepartController |
| 职务/职级 | /sys/position | SysPositionController |
| 字典 | /sys/dict | SysDictController |
| 字典项 | /sys/dictItem | SysDictItemController |
| 租户 | /sys/tenant | SysTenantController |
| 分类字典 | /sys/category | SysCategoryController |
| 数据源 | /sys/dataSource | SysDataSourceController |
| 定时任务 | /sys/quartzJob | QuartzJobController |
| 审批角色 | /sys/approvalRole | ApprovalRoleController |
| 用户组 | /sys/ugroup | SysUserGroupController |
| 菜单权限 | /sys/permission | SysPermissionController |
| 通知公告 | /sys/annountCement | SysAnnouncementController |
高频接口（system_utils.py 已封装）
| 接口 | 方法 | 说明 | 对应函数 |
|---|
/sys/role/list | GET | 角色列表（分页） | query_roles() |
/sys/role/add | POST | 创建系统角色 | create_role() |
/sys/user/addSysUserRole | POST | 角色绑定用户（body: {roleId, userIdList}） | add_users_to_role() |
/sys/approvalRole/search | GET | 搜索审批角色（需传 keyword=） | query_approval_roles() |
/sys/approvalRole/rootList | GET | 审批角色分组列表 | — |
/sys/approvalRole/childList | GET | 分组下审批角色列表（需传 pid=） | — |
/sys/approvalRole/group/add | POST | 创建审批角色分组（body: {name, pid:"0"}） | create_approval_role_group() |
/sys/approvalRole/role/add | POST | 创建审批角色（body: {name, pid:groupId}） | create_approval_role() |
/sys/approvalRoleUser/add | POST | 审批角色绑定用户（body: {approvalRoleId, userIds, bizScope, includeSub}） | add_users_to_approval_role() |
/sys/user/list | GET | 用户列表（分页） | query_users() |
/sys/sysDepart/queryTreeList | GET | 部门树 | query_depts() |
/sys/sysDepart/queryDepartAndPostTreeSync | GET | 部门+岗位树 | query_dept_positions() |
/sys/dict/list | GET | 字典列表（分页） | search_dict() |
/sys/dict/add | POST | 创建字典 | create_dict() |
/sys/api/getDictItems?dictCode= | GET | 查询字典项（普通字典） | query_dict() |
/sys/dict/getDictItems/{dictCode} | GET | 查询 SQL 表字典项（需签名） | query_sql_table_dict() |
/sys/dictItem/add | POST | 创建字典项 | create_dict() 内部调用 |
常用查询接口（尚未封装，可直接调 _request()）
| 接口 | 方法 | 说明 |
|---|
/sys/role/queryall | GET | 全部角色（租户隔离） |
/sys/role/queryallNoByTenant | GET | 全部角色（不做租户隔离） |
/sys/user/queryById | GET | 按ID查用户 |
/sys/user/queryByIds | GET | 按多ID批量查用户 |
/sys/user/queryUserRole | GET | 查用户拥有的角色 |
/sys/user/selectUserList | GET | 流程用户选择组件查询 |
/sys/sysDepart/searchBy | GET | 关键词搜索部门 |
/sys/sysDepart/queryDepartTreeSync | GET | 异步加载部门树节点 |
/sys/sysDepart/getDepartmentHead | GET | 部门负责人列表 |
/sys/position/list | GET | 职务列表 |
/sys/position/queryByCode | GET | 按code查职务 |
/sys/dict/getDictText/{code}/{key} | GET | 获取字典文本值 |
/sys/dict/loadDict/{code} | GET | 下拉搜索异步加载字典 |
/sys/category/loadTreeRoot | GET | 分类字典根节点列表（必须传 async=false&pcode=） |
/sys/category/loadAllData | GET | 指定节点的子节点列表（必须传 code=<节点code>） |
/sys/category/add | POST | 创建分类节点（body: {pid, name}，禁止传 code，后端自动生成） |
/sys/category/delete | DELETE | 删除分类节点（param: id=） |
/sys/tenant/list | GET | 租户列表 |
/sys/tenant/getCurrentUserTenant | GET | 当前用户所有租户 |
/sys/dataSource/list | GET | 数据源列表 |
/sys/quartzJob/list | GET | 定时任务列表 |
/sys/quartzJob/pause | GET | 暂停任务 |
/sys/quartzJob/resume | GET | 启动任务 |
/sys/quartzJob/execute | GET | 立即执行一次 |
/sys/permission/list | GET | 菜单列表 |
/sys/permission/queryRolePermission | GET | 查角色权限 |
/sys/approvalRole/search | GET | 搜索审批角色 |
主要数据结构
SysUser: id, username, realname, password, avatar, birthday, sex(1男/2女), email, phone, orgCode, status(0冻结/1正常), post(岗位ID), userIdentity(1普通/2上级)
SysRole: id, roleName, roleCode, description, tenantId
SysDepart: id, parentId, departName, orgCode, orgCategory(1公司/4子公司/2部门/3岗位), departOrder
SysPosition: id, code, name, postLevel(1高管/2中层/3基层/4实习)
SysDict: id, dictName, dictCode, description
SysDictItem: id, dictId, itemText, itemValue, itemColor, sortOrder, status(0禁用/1启用)
SysTenant: id, name, beginDate, endDate, status(0禁用/1正常)
SysCategory: id, pid, name, code（code 由后端自动生成，禁止在 add 请求中传入，根节点示例 B06，子节点示例 B06A01）
⚠️ 分类字典创建规则：
- 禁止传
code：/sys/category/add 的 body 只传 pid 和 name，不要传 code，后端会自动按层级规则生成（根节点 B06、子节点 B06A01...）。
- 获取生成的 code：
add 接口在新版本会在 result 中返回 code，但老版本不返回。如果响应 result 为 null 或不含 code，必须立即调用 loadTreeRoot（根节点）或 loadAllData（子节点）主动查询，拿到 code 后再继续创建子级，不可假设或跳过。
- 查询接口参数：
loadTreeRoot 必须传 async=false&pcode=（pcode 为空字符串表示根节点）；loadAllData 必须传 code=<父节点的code>。
- 删除用 DELETE 方法：
/sys/category/delete 需要 HTTP DELETE，传 param id=。
QuartzJob: id, jobClassName, cronExpression, parameter, description, status(0停用/-1删除/1运行)
源码位置
- 前端API：各模块下的
*.api.ts 文件（如 user/user.api.ts, role/role.api.ts）