sx/map

Fork 0

houwei fbdfca18d0 修改api文档

2024-06-27 09:31:38 +08:00

24 KiB

Raw Blame History

概述

接口约定

系统中的所有接口均遵循以下约定。

除了与文件上传/下载相关的接口外，都是POST请求，请求报文使用JSON格式。
文件下载使用GET请求(此种类型，加解密再讨论下)。
文件上传使用POST请求，请求报文使用multipart/form-data格式。

加密/解密

请求报文，Header中需要添加参数

参数名称	说明	备注
token	令牌	需要鉴权的API 才需要添加此参数
V	加密向量	必须添加

加密采用AES/CBC/ZeroPadding加密方式，密钥长度为16位。，IV长度为16位（每次请求时随机生成）。

权限模块

API接口一览表

接口分类	接口描述	API接口
系统登录	1.1、获取验证码	/api/auth/captchaImage
系统登录	1.2、系统登录	/api/auth/login
系统登录	1.3、退出登录	/api/auth/logout
系统登录	1.4、修改密码	/api/auth/password/change
菜单管理	2.1、新增菜单	/api/menus/add
菜单管理	2.2、查询菜单	/api/menus/query
菜单管理	2.3、更新菜单	/api/menus/update
菜单管理	2.4、删除菜单	/api/menus/delete
公司机构	3.1、公司机构查询	/api/org/query
公司机构	3.2、添加机构信息	/api/org/add
公司机构	3.3、修改机构信息	/api/org/update
公司机构	3.4、删除指定机构	/api/org/delete
职员操作	4.1、职员查询	/api/user/query
职员操作	4.2、职员创建	/api/user/add
职员操作	4.3、职员修改	/api/user/update
职员操作	4.4、职员删除	/api/user/delete
系统角色	5.1、系统角色查询	/api/user/getSysRole
系统角色	5.2、系统角色删除	/api/user/deleteSysRole
系统角色	5.3、系统角色新增	/api/user/addSysRole
系统角色	5.4、角色权限查询	/api/user/getAuthorityById

1.1、验证码获取

/api/auth/captchaImage

入参示例

无入参

调用成功返回示例

{
  "code": 200,
  "msg": "操作成功",
  "success": true,
  "data": {
    "img": "",
    "key": "9007a0158f7c4635b4e6e577de7406e0"
  }
}

调用成功返回描述

变量名	变量类型	可为NULL	描述
img	String	No	图片base64编码
key	String	No	验证码唯一标志

1.2、系统登录

使用用户名和密码，验证码和验证码的唯一标识登录系统，POST请求

/api/auth/login

入参示例

{
  "userName":"xx",
  "password":"xxx",
  "code":"xxx",
  "key":"xxx"
}

入参描述

参数名	参数类型	可选	描述
userName	String	no	用户名
password	String	no	用户密码
code	String	no	验证码
key	String	no	唯一标志

调用成功返回示例

{
  "code": 200,
  "success": true,
  "data": {
    "sysUser": {
      "id": 1,
      "account": "admin",
      "userName": "admin"
    },
    "refreshToken": "6dfa2fe87b0d44538e26481c01c02d16",
    "token": "85487b052fd34c36a0482be56e8532f0"
  },
  "msg": "操作成功"
}

调用成功返回描述

变量名	变量类型	可为NULL	描述
token	String	No	令牌(未加密)

1.3、退出登录

注销令牌退出登录，POST请求

/api/auth/logout

无入参

调用成功返回示例

{
   "code":200,
   "data": null,
   "msg":"令牌已注销"
}

1.4、修改密码

修改登录密码，POST请求

/api/auth/password/change

入参示例

{
  "userName":"xx",
  "oldPassword":"xx",
  "newPassword":"xxx",
}

入参描述

参数名	参数类型	可选	描述
oldPassword	String	NO	旧密码
newPassword	String	NO	新密码
userName	String	NO	用户名

调用成功返回示例

{
  "code":200,
  "msg":"修改成功",
  "data":null
}

2、菜单管理

2.1、新增菜单

请求接口    /api/menus/add

入参定义


{
  "menuName": "菜单1",
  "menuOrder": 1,
  "menuIcon": "icon1",
  "funType": 1,
  "funParam": "param",
  "authorityId": "123",
  "parentMenuId": "0",
  "revision": 1,
  "createdBy": "aaa",
  "createdTime": 123456,
  "updatedBy": "aaa",
  "updatedTime": 12345
}

入参描述

参数名	参数类型	可选	描述
menuName	String	YES	菜单名称
menuOrder	Integer	YES	菜单排列顺序
menuIcon	String	YES	菜单图标名称
funType	Integer	YES	菜单操作类型
funParam	String	YES	菜单操作参数
authorityId	Long	YES	权限ID
parentMenuId	Long	YES	上级菜单ID
revision	Integer	YES	乐观锁

调用成功返回示例

{
	"code": 200,
	"msg": "操作成功",
    "success": true,
	"data": {
		"id": "123",
		"menuName": "菜单1",
		"menuOrder": 1,
		"menuIcon": "icon1",
		"funType": 1,
		"funParam": "param",
		"authorityId": "123",
		"parentMenuId": "0",
		"revision": 1,
		"createdBy": "aaa",
		"createdTime": 123456,
		"updatedBy": "aaa",
		"updatedTime": 12345
	}
}

2.2、查询菜单

请求接口   /api/menus/query

入参定义

{
  "parentMenuId": "0"
}

调用成功返回示例

{
	"code": 200,
	"msg": "操作成功",
    "success": true,
	"data": [
        {
		"id": "123",
		"menuName": "菜单1",
		"menuOrder": 1,
		"menuIcon": "icon1",
		"funType": 1,
		"funParam": "param",
		"authorityId": "123",
		"parentMenuId": "0",
		"revision": 1,
		"createdBy": "aaa",
		"createdTime": 123456,
		"updatedBy": "aaa",
		"updatedTime": 12345
	}
    ]
}

2.3、更新菜单

请求接口
/api/menus/update

入参定义

{
  "id": "123",
  "menuName": "菜单1",
  "menuOrder": 1,
  "menuIcon": "icon1",
  "funType": 1,
  "funParam": "param",
  "authorityId": "123",
  "parentMenuId": "0",
  "revision": 1
}

调用成功返回示例

{
"code":"200",
"msg":"更新成功",
"data":"null",
"success": true
}

2.4、删除菜单

请求接口    /api/menus/delete

入参定义

{  
  "id": ""
}

调用成功返回示例

{
"code":"200",
"msg":"成功",
"data":"null",
"success": true
}

2.5、获取所有菜单

请求接口   /api/menus/list

入参定义

{
  "parentMenuId": 0,
  "recursive": true
}

调用成功返回示例

{
	"code": 200,
	"msg": "操作成功",
    "success": true,
	"data": [
        {
		"id": "123",
		"menuName": "菜单1",
		"menuOrder": 1,
		"menuIcon": "icon1",
		"funType": 1,
		"funParam": "param",
		"authorityId": "123",
		"parentMenuId": "0",
		"revision": 1,
		"createdBy": "aaa",
		"createdTime": 123456,
		"updatedBy": "aaa",
		"updatedTime": 12345
	}
    ]
}

2.6、获取绑定菜单

请求接口   /api/menus/tree

入参定义

调用成功返回示例

{
  "code": 200,
  "success": true,
  "data": {
    "id": 73216735447089152,
    "menuName": "测试1",
    "menuOrder": 0,
    "menuIcon": "",
    "funType": 0,
    "funParam": "",
    "authorityId": 101,
    "parentMenuId": 0,
    "revision": 2,
    "createdTime": "2024-06-25 07:14:40",
    "updatedTime": "2024-06-25 07:14:40",
    "children": [
      {
        "id": 73216795998158848,
        "menuName": "测试2",
        "menuOrder": 0,
        "menuIcon": "",
        "funType": 1,
        "funParam": "2",
        "authorityId": 101,
        "parentMenuId": 73216735447089152,
        "revision": 1,
        "createdTime": "2024-06-25 07:18:31",
        "updatedTime": "2024-06-25 07:18:31",
        "children": [
          {
            "id": 73216799741313024,
            "menuName": "测试3",
            "menuOrder": 0,
            "menuIcon": "",
            "funType": 1,
            "funParam": "333",
            "authorityId": 101,
            "parentMenuId": 73216795998158848,
            "revision": 1,
            "createdTime": "2024-06-25 07:18:45",
            "updatedTime": "2024-06-25 07:18:45",
            "children": []
          }
        ]
      }
    ]
  },
  "msg": "操作成功"
}

!> 下面的文档有待确认

3、公司机构

组织机构模块提供的API包括机构查询、添加、修改等功能。

公司机构查询

提供获取所有机构信息的功能，POST方式

/api/org/query

入参示例

{
  "name":"12",
  "parentOrgId":"xx",
  "province":"xx",
  "city":"xxx",
  "county":"xxx"
}

入参描述

参数名	参数类型	可选	描述
name	String	YES	机构名称，当名称为空时查询所有机构数据
parentOrgId	String	YES	上级机构ID
province	String	YES	省
city	String	YES	城市
county	String	YES	区县

调用成功返回示例

{
   "code":"200",
   "data": [
    {
      "id": "xxx",
      "mrid": "xxx",
      "name": "xxx",
      "aliasName":"xxx",
      "province": "xxx",
      "city": "xxx",
      "county": "xxx",
      "address": "xxx",
      "contactPhone":"xxx",
      "remarks":"xxx",
      "parentOrgId":"xxxx"
   },
    {
        ...
    }
  ],
  "msg":"调用成功",
  "success": true
}

调用成功返回描述

变量名	变量类型	可为NULL	描述
id	Integer	No	id
mrid	String	No	编码
name	String	No	名称
aliasName	String	No	简称/别名
province	String	No	省
city	String	No	城市
county	String	No	区县
address	String	No	详细地址
contactPhone	String	No	联系电话
remarks	String	No	备注
parentOrgId	Long	No	上级机构ID

添加机构信息

根据添加的机构信息创建机构，POST方式

/api/org/add

入参示例

 {
        /** 机构名称 */
        private String name ;
        /** 机构编码 */
        private String mrid ;
        /** 省份 */
        private String province ;
        /** 城市 */
        private String city ;
        /** 区县 */
        private String county ;
        /** 详细地址 */
        private String address ;
        /** 联系电话 */
        private String contactPhone ;
        /** 备注 */
        private String remarks ;
        /** 上级机构id */
        private Long parentOrgId ;
        /** 乐观锁 */
        private Integer revision ;
        /** 创建人 */
        private String createdBy ;
        /** 创建时间 */
        private Date createdTime ;
        /** 更新人 */
        private String updatedBy ;
        /** 更新时间 */
        private Date updatedTime ;
   }

入参描述

变量名	变量类型	可为NULL	描述
mrid	String	No	编码
name	String	No	名称
aliasName	String	No	简称/别名
province	String	No	省
city	String	No	城市
county	String	No	区县
address	String	No	详细地址
contactPhone	String	No	联系电话
remarks	String	No	备注
parentOrgId	Long	No	上级机构ID
token	String	NO	token

调用成功返回示例

{
"code":"200",
"msg":"添加成功",
"data":"null",
"success": true
}

修改机构信息

根据提供的机构ID,修改机构信息，POST方式

/api/org/update

入参示例

 {
      "id":"xxx",
      "mrid": "xxx",
      "name": "xxx",
      "aliasName":"xxx",
      "province": "xxx",
      "city": "xxx",
      "county": "xxx",
      "address": "xxx",
      "contactPhone":"xxx",
      "remarks":"xxx",
      "parentOrgId":"xxxx"
   }

入参描述

变量名	变量类型	可为NULL	描述
id	BIGINT	No	机构ID
mrid	String	No	编码
name	String	No	名称
aliasName	String	No	简称/别名
province	String	No	省
city	String	No	城市
county	String	No	区县
address	String	No	详细地址
contactPhone	String	No	联系电话
remarks	String	No	备注
parentOrgId	Long	No	上级机构ID

调用成功返回示例

{
"code":"200",
"msg":"修改成功",
"data":"null",
"success": true
}

#机构信息对象)

删除指定机构

根据提供的机构ID,删除机构信息，POST方式

/api/org/delete

入参示例

{
       "id":"111"
}

入参描述

参数名	参数类型	可选	描述
id	Long	No	要删除的机构主键

调用成功返回示例

{
"code":"200",
"msg":"修改成功",
"data":"null",
"success": true
}

获取机构列表

根据获取机构列表，POST方式

/api/org/list

入参示例

{
       "parentOrgId":111,
  "recursive": true
}

入参描述

参数名	参数类型	可选	描述
parentOrgId	Long	No	机构id
recursive	boolean	No	是否是根节点

调用成功返回示例

{
  "code": 200,
  "success": true,
  "data": [
    {
      "id": "2",
      "name": "测试子公司",
      "mrid": "456",
      "province": "江苏",
      "city": "南京",
      "county": "玄武",
      "address": "测试地址1",
      "contactPhone": "555889",
      "remarks": "测试",
      "parentOrgId": 1,
      "revision": 1
    }
  ],
  "msg": "操作成功"
}

4、职员用户

职员模块提供的API包括职员查询、添加、修改等功能。

职员查询

提供对职员信息的基本查询功能,POST方式。

/api/user/query

入参示例

{
"userName":"xx",
"orgId":"xxx"
}

入参描述

参数名	参数类型	可选	描述
userName	String	Yes	模糊查询职员名称，当职员名称为空时查询所有职员信息
orgId	BIGINT	Yes	所属机构ID

调用成功返回示例

{
  "total": 1,
  "rows": [
    {
      "id": 73238484643741696,
      "account": "test1",
      "userName": "测试1",
      "revision": 1,
      "phone": "1231212",
      "email": "测试",
      "orgId": 1,
      "roleList": [
        {
          "id": 73220290639036416,
          "roleCode": "1212",
          "roleName": "测试角色1",
          "revision": 1
        },
        {
          "id": 73212978522226688,
          "roleCode": "0011",
          "roleName": "测试角色",
          "revision": 1
        }
      ]
    }
  ],
  "code": 200,
  "msg": "查询成功"
}

变量名	变量类型	可为NULL	描述
id	BIGINT	No	主键(雪花算法生成)
account	String	No	登录账号
userName	String	No	职员名称
email	String	No	职员邮箱
phone	String	No	职员联系电话
orgId	BIGINT	No	所属机构ID
roleList	List	No	角色集合

职员创建

根据提供的职员信息创建职员，POST方式。

/api/user/add

入参示例

{
      "account": "xxx",
      "password": "xxx",
      "userName": "xxx",
      "email":"xxx",
      "phone":"xxx",
      "orgId":"xxx",
      "roleList":[73220290639036416,73212978522226688]
}

入参描述

变量名	变量类型	可为NULL	描述
account	String	No	登录账号
password	String	No	加密后的密码
userName	String	No	职员名称
email	String	No	职员邮箱
phone	String	No	职员联系电话
orgId	BIGINT	No	所属机构ID
roleList	List	No	角色id集合

调用成功返回示例

{
  "code": 200,
  "success": true,
  "data": {
    "account": "test1",
    "roleList": [
      73220290639036416,
      73212978522226688
    ]
  },
  "msg": "操作成功"
}

职员修改

根据提供的职员id,修改职员信息，POST方式。

/api/user/update

{
      "id":"xxx",
      "account": "xxx",
      "userName": "xxx",
      "email":"xxx",
      "phone":"xxx",
      "orgId":"xxx",
  "roleList":[73220290639036416,73212978522226688]
}

入参描述

变量名	变量类型	可为NULL	描述
id	BIGINT	No	主键(雪花算法生成)
account	String	No	登录账号
userName	String	No	职员名称
email	String	No	职员邮箱
phone	String	No	职员联系电话
orgId	BIGINT	No	所属机构ID
roleList	List	No	角色id集合

调用成功返回示例

{
  "code": 200,
  "success": true,
  "msg": "操作成功"
}

职员删除

根据提供的职员id,删除职员信息，POST方式。

/api/user/delete

入参示例

{
       "id":"123"
}

入参描述

参数名	参数类型	可选	描述
id	BIGINT	No	要删除的职员Id

调用成功返回示例

{
  "code": 200,
  "success": true,
  "msg": "操作成功"
}

5、角色维护

系统权限查询

提供获取所有系统权限的功能，POST方式

/api/user/getSysAuthoritys

入参示例

{
       "authorityName":"xxx",
       "token":"xxx"
}

入参描述

参数名	参数类型	可选	描述
authorityName	String	yes	权限名称为空时查询所有系统角色
token	String	NO	token

调用成功返回示例

{
    "code":"200",
    "msg":"调用成功",
    "data":[
    {
      "id": "xxxx",
      "authorityCode": "xxx",
      "authorityName": "xxx",
     
   },
    {
        ...
    }
  ]
}

变量名	变量类型	可为NULL	描述
id	BIGINT	NO	主键id
authorityCode	string	NO	权限编码
authorityName	string	NO	权限名称

系统角色查询

提供获取所有系统角色的功能，POST方式

/api/role/query

入参示例

{
       "roleName":"xxx"
}

入参描述

参数名	参数类型	可选	描述
roleName	String	YES	系统角色为空时查询所有系统角色

调用成功返回示例

{
  "total": 1,
  "rows": [
    {
      "createdTime": "2024-06-25 11:15:48",
      "updatedTime": "2024-06-25 11:15:48",
      "id": "73212978522226688",
      "roleCode": "001",
      "roleName": "测试角色",
      "revision": 1
    }
  ],
  "code": 200,
  "msg": "查询成功"
}

变量名	变量类型	可为NULL	描述
id	BIGINT	No	主键id
roleCode	string	No	角色编码
roleName	string	No	角色名称

系统角色删除

根据提供的ID,删除系统角色，POST方式

/api/role/delete

入参示例

{
       "id":"xxx"

入参描述

参数名	参数类型	可选	描述
id	BIGINT	NO	系统角色id

调用成功返回示例

{
  "code": 200,
  "success": true,
  "msg": "操作成功"
}

系统角色新增

根据添加的信息创建系统角色，POST方式

/api/role/add

入参示例

{
    "roleName":"测试角色",
    "roleCode":"001",
    "authList":[101,102,103]
}

入参描述

参数名	参数类型	可选	描述
roleCode	String	no	角色编码
roleName	String	no	角色名称
authList	List	yes	角色的权限id

调用成功返回示例

{
  "code": 200,
  "success": true,
  "data": {
    "roleName": "测试角色",
    "roleCode": "001",
    "authList": [
      101,
      102,
      103
    ]
  },
  "msg": "操作成功"
}

所有权限查询

提供获取所有权限权限的功能，POST方式 /api/authority/query

入参示例

无入参

调用成功返回示例

{
"code": 200,
"success": true,
"data": [
{
"id": "101",
"authorityCode": "systemMgr",
"authorityName": "系统管理权限",
"revision": 1
},
{
"id": "102",
"authorityCode": "equipmentLedgerManagement",
"authorityName": "设备台账维护权限",
"revision": 1
},
{
"id": "103",
"authorityCode": "equipmentLedgerView",
"authorityName": "设备台账浏览权限",
"revision": 1
}
],
"msg": "操作成功"
}

调用成功返回

变量名	变量类型	可为NULL	描述
id	BIGINT	No	主键id
authorityCode	string	No	权限编码
authorityName	string	No	权限名称

角色权限查询

提供获取所有角色权限的功能，POST方式

/api/role/queryAuthorityById

入参示例

{
       "id":"xxx"
}

入参描述

参数名	参数类型	可选	描述
id	BIGINT	NO	系统角色id

调用成功返回示例

{
    "code":"200",
    "msg":"调用成功",
    "data":[
    {
      "authorityCode": "xxxx",
      "authorityName": "xxx",
      "id": "xxx",
   },{
       
   }
  ]
}

变量名	变量类型	可为NULL	描述
id	BIGINT	No	权限ID
authorityCode	string	No	权限编码
authorityName	string	No	权限名称

角色权限编辑

根据提供的ID,修改角色权限，POST方式

/api/role/update

入参示例

{
"id":"xxx",
"roleName":"XX",
"authList":[12,13]
}

入参描述

参数名	参数类型	可选	描述
id	BIGINT	no	系统角色id
roleName	String	no	角色名称
authList	List	yes	角色的权限id

调用成功返回示例

{
"code":"200",
"msg":"编辑成功",
"data":"null"
}

24 KiB Raw Blame History Unescape Escape

概述

接口约定

加密/解密

权限模块

API接口一览表

1.1、验证码获取

1.2、系统登录

1.3、退出登录

1.4、修改密码

2、菜单管理

2.1、新增菜单

2.2、查询菜单

2.3、更新菜单

2.4、删除菜单

2.5、获取所有菜单

2.6、获取绑定菜单

3、公司机构

公司机构查询

添加机构信息

修改机构信息

删除指定机构

获取机构列表

4、职员用户

职员查询

职员创建

职员修改

职员删除

5、角色维护

系统权限查询

系统角色查询

系统角色删除

系统角色新增

所有权限查询

角色权限查询

角色权限编辑

24 KiB

Raw Blame History