Jeecg System

JeecgBoot 系统主数据查询与管理

查询和管理 JeecgBoot 系统中的角色、用户、部门、字典等主数据。遵循"先查后建"原则：优先使用系统已有数据，没有才创建。

前置条件

用户必须提供以下信息（或由 AI 引导确认）：

1. API 地址：JeecgBoot 后端地址（如 https://boot3.jeecg.com/jeecgboot）
2. 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="/jeecg-system/scripts/system_creator.py"
API=""
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'/jeecg-system/scripts')
from system_utils import *

init_api('', '')

# ====== 角色 ======
# 查询所有角色
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: 取得路径）：

import sys
sys.path.insert(0, r'\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=） | | /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）

> ⚠️ 分类字典创建规则： > > 1. 禁止传 code：/sys/category/add 的 body 只传 pid 和 name，不要传 code，后端会自动按层级规则生成（根节点 B06、子节点 B06A01...）。 > 2. 获取生成的 code：add 接口在新版本会在 result 中返回 code，但老版本不返回。如果响应 result 为 null 或不含 code，必须立即调用 loadTreeRoot（根节点）或 loadAllData（子节点）主动查询，拿到 code 后再继续创建子级，不可假设或跳过。 > 3. 查询接口参数：loadTreeRoot 必须传 async=false&pcode=（pcode 为空字符串表示根节点）；loadAllData 必须传 code=。 > 4. 删除用 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）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jeecgboot
• Source: jeecgboot/skills
• License: Apache-2.0
• Homepage: https://jeecg.com

Install and usage instructions live in the source repository linked above.