# 易普力用户服务SDKDemo
**Repository Path**: tech-expl/ExplUserServiceDemo
## Basic Information
- **Project Name**: 易普力用户服务SDKDemo
- **Description**: 易普力用户服务SDKDemo
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-10-21
- **Last Updated**: 2020-12-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
### 易普力组织结构接入文档
#### 一、说明
本文档仅限葛洲坝易普力及委托开发单位阅读，不可供给他人阅读。
- 本文建议在电脑上阅读。
- 当SDK功能不足以满足业务需求时，请联系科技发展中心徐建。
##### 1、基础架构
- 系统采用SpringCloud分布式微服务架构，本文提供的接口涉及service-admin、service-user服务。
- 注意：系统对子系统没有登录验证、访问限制的功能，相关处理应在子系统完成。
##### 2、名词说明
- 系统： 本文所描述“系统”指葛洲坝易普力科技发展中心开发的SpringCloud分布式微服务基础系统。
- 子系统： 指与系统进行对接的具体业务系统、服务。
- 密钥： 用来标记及判断访问来源合法性的32位小写字符串，测试时可使用9edda792b0fe582fdcc2aa14fbba8a64调试。
- 密码： 系统中不记录用户密码原文，从不同系统登录的用户传输的密码串是不一样的。
- uid： 指用户id，用户id分为主id，电子雷管用户id（会淘汰），爆破系统用户id（会淘汰）
- token： 用户登录后会得到一个token，不可直接使用，使用时需进行加密。
- 加密： 系统与子系统之间约定的加密算法，每个子系统的密钥不一样。
- SDK： 指系统提供给子系统的软件开发包。
- 服务： 每个子系统是一个服务，系统由多个服务组成。服务名(spring.application.name)由子系统定义，定义后保持不变。
##### 3、更新记录
# md
| 序号 | 文档版本 | 时间 | 编辑人 | 变更内容 |
|:--------:| -----: | :----: | :----: | :----: |
| 1 | v1.0.0 | 2020-10-20 | 徐建 |初始化|
| 2 | v1.0.1 | 2020-11-25 | 唐源 | 部门管理新增“独立运营”字段|
| 3 | v1.0.2 | 2020-12-03 | 唐源 |新增3个接口|
| 4 | v1.0.3 | 2020-12-04 | 唐源 |更新用户查询|
#### 二、加密方法
- 本加密方法适用于本系统与子系统之间的数据交互和访问鉴权。
- 对于每个子系统而言，SECRET_KEY（也叫SystemId）是一定的，但可修改
- 下述示例代码中，执行如下代码，可以获得对字符串进行加密后的结果
```java
String result = DesUtils.encryption("123456");
```
- 加密代码如下：
```java
import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.SecretKeyFactory;
import javax.crypto.spec.DESKeySpec;
import java.util.Base64;
public class DesUtils {
private static final String DES="DES";
private static final SecretKey getSecretKeyFactory(String systemId) throws Exception {
SecretKeyFactory des = SecretKeyFactory.getInstance(DES);
SecretKey secretKey = des.generateSecret(new DESKeySpec(systemId.getBytes()));
return secretKey;
}
public static final String encryption(String systemId,String param) throws Exception {
Cipher cipher = Cipher.getInstance(DES);
SecretKey secretKey = getSecretKeyFactory(systemId);
cipher.init(Cipher.ENCRYPT_MODE, secretKey);
byte[] bs = cipher.doFinal(param.toString().getBytes());
return new String(Base64.getEncoder().encode(bs));
}
}
```
#### 三、接入方式
##### 1、说明
- 子系统为Spring Cloud的一个子服务，才可与系统进行数据交互
- 子系统通过feign与系统进行数据对接
- 子系统与系统通过内网访问，子系统无需关注系统所在内外网IP
##### 2、SDK接入
- 通过Maven接入系统通过的SDK
- 开放仓库，请不要外泄
- 依赖：
```xml
cn.cggc.expl
admin
1.0.3-RELEASE
```
- 仓库：
```xml
public
Public Repositories
https://www.xujian.tech/mvn/
```
#### 四、接口描述
##### 1、SDK接入成功判断
- 调用如下代码会打印SDK相关信息
```java
Version.version();
```
##### 2、请求来源记录
- 系统会通过对加密的密码、token进行解密，能使用某子系统密钥解密成功则视为该子系统访问，并进行下一步操作。
##### 3、登录验证
- 登录接口用以验证用户的账户、密码，并返回用户信息、token等信息。
- 请参考demo
- 关于子系统密码传输的加密方式请自行决定
```java
String password = "123456";
password = DesUtils.encryption(explSysId,password);
return userService.login("xujian", password);
```
##### 4、使用token取得用户信息
- 请参考demo
```java
String token = "21e2bff0bee70ce2aca57540b679486f";
token = DesUtils.encryption(explSysId,token);
return userService.getUserInfoByToken(token);
```
##### 5、使用userId（主）获取用户信息
- 无需加密，请参考demo
```java
long uid = 138;
return userService.getUserInfoById(uid);
```
##### 5、token主动过期
- 即退出登录
```java
String token = "21e2bff0bee70ce2aca57540b679486f";
token = DesUtils.encryption(explSysId,token);
return userService.logout(token);
```
##### 6、取得组织架构树（整体）
- 取得整体（根据需求调用）
- root的id为-1
```java
String token = "906bc63d39a1462a497a8d04fba26ffc";
token = DesUtils.encryption(explSysId,token);
return userService.getOrgTotal(token);
```
##### 7、取得部门信息
- 获取用户所在部门信息
```java
String token = "906bc63d39a1462a497a8d04fba26ffc";
token = DesUtils.encryption(explSysId,token);
return userService.getDepartMine(token);
```
##### 8、取得用户所在组织树（根据需求调用）
- 单叶子树
- 根节点为非-1的深度最低节点
```java
String token = "906bc63d39a1462a497a8d04fba26ffc";
token = DesUtils.encryption(explSysId,token);
return userService.getOrgMine(token);
```
##### 9、取得某个部门的用户信息
- 返回用户数组
```java
String token = "906bc63d39a1462a497a8d04fba26ffc";
token = DesUtils.encryption(explSysId,token);
return userService.usersDepart(token,18l);
```
##### 10、取得用户所在部门的组织树（含用户信息）
```java
String token = "eeb10ac25f54ea5f464e254619a8ac6e";
token = DesUtils.encryption(explSysId,token);
return userService.getOrgMineByUser(token);
```
##### 11、取得指定部门的组织树（含用户信息）
```java
long deptId = -1;
//-1 or null表示取整体架构
return userService.getOrgByDeptId(deptId);
```
##### 12、用户修改密码
```java
String username = "xujian";
String oldPassword = "123456";
oldPassword = DesUtils.encryption(explSysId,oldPassword);
String newPassword = "123";
newPassword = DesUtils.encryption(explSysId,newPassword);
return userService.userChangePassword(username,oldPassword,newPassword);
```
##### 13、查询用户信息，提供用户信息的updated时间和created时间大于某个时间进行筛选
```java
//null or "" 表示全部查询
String gmtCreate = "2017-08-15 21:40:39";
String gmtModified = "";
return userService.getUserByTime(gmtCreate,gmtModified);
```
##### 14、查询所有用户,支持模糊搜索（手机号、部门、姓名、身份证号、邮箱）
```java
//null or "" 表示全部查询
String mobile = "17699999999";
String deptId = 0;
String idCard = "";
String email = "";
//分页,page 页，size 数量
int page=1;
int size=10;
return userService.getUserSelected(mobile,deptName,name,idCard,email,page,size);
```
- json示例
```json
:"操作成功",
"code":0,
"data":{
"offset":10, //偏移量，可以不管
"limit":10,
"total":1,
"params":{
"total":1, //总数据量
"size":10, //每页大小
"totalPage":1, //总页数
"page":1 //当前页
},
"param":"",
"rows":[
{
"userId":1,
"username":"admin",
"name":"超级管理员",
"password":"27bd386e70f280e24c2f4f2a549b82cf",
"deptId":6,
"deptName":"系统管理员",
"email":"admin@example.com",
"mobile":"17699999999",
"telephone":null,
"idCard":null,
"status":1,
"userIdCreate":1,
"gmtCreate":"2017-08-16 05:40:39",
"gmtModified":"2017-08-16 05:41:00",
"roleIds":null,
"sex":96,
"birth":"2017-12-14 08:00:00",
"picId":138,
"liveAddress":"ccc",
"hobby":"121;",
"province":"北京市",
"city":"北京市市辖区",
"district":"东城区",
"userIdEdfos":null,
"userIdBP":0,
"mainPost":null,
"deputyPost":null,
"parttimePost":null,
"position":null
}
]
}
}
```
##### 15、查询部门信息
```java
long deptId = 18;
return userService.getByDeptId(deptId);
```
#### 五、DEMO
- 见：
[易普力用户服务SDKDemo](https://gitee.com/tech-expl/ExplUserServiceDemo)
#### 六、数据结构解释
##### 1、用户
```java
//
private Long userId;
// 用户名
private String username;
// 用户真实姓名
private String name;
// 密码
private String password;
// 部门
private Long deptId;
private String deptName;
// 邮箱
private String email;
// 手机号
private String mobile;
//座机号
private String telephone;
// 用户身份证号码
private String idCard;
// 状态 0:禁用，1:正常
private Integer status;
// 创建用户id
private Long userIdCreate;
// 创建时间
private Date gmtCreate;
// 修改时间
private Date gmtModified;
//角色
private List roleIds;
//性别
private Long sex;
//出身日期
@DateTimeFormat(pattern = "yyyy-MM-dd")
private Date birth;
//图片ID
private Long picId;
//现居住地
private String liveAddress;
//爱好
private String hobby;
//省份
private String province;
//所在城市
private String city;
//所在地区
private String district;
//电子雷管系统UserId
private Long userIdEdfos;
//爆破系统UserId
private Long userIdBP;
//主岗
private String mainPost;
//副岗
private String deputyPost;
//兼职岗位
private String parttimePost;
//职务
private String position;
```
##### 2、部门
```java
//部门ID
private Long deptId;
//上级部门ID，一级部门为0
private Long parentId;
//部门名称
private String name;
//排序
private Integer orderNum;
//是否删除 -1：已删除 0：正常
private Integer delFlag;
//是否为独立运营的公司或机构
private boolean isIndependence;
```
##### 3、组织结构树
- 如下JSON并解释
- 组织结构树是一个多孩子节点数，使用parentId来标记父节点，使用children来记录子节点
- 单实体数据结构
```java
/**
* 节点ID，<=0表示根节点
*/
private String id;
/**
* 显示节点文本
*/
private String text;
/**
* 节点状态，open closed
*/
private Map state;
/**
* 节点是否被选中 true false
*/
private boolean checked = false;
/**
* 节点属性
*/
private Map attributes;
/**
* 节点的子节点
*/
private List> children = new ArrayList>();
/**
* 父ID
*/
private String parentId;
/**
* 是否有父节点
*/
private boolean hasParent = false;
/**
* 是否有子节点
*/
private boolean hasChildren = false;
/**
* 是否为独立运营
*/
private boolean isIndependence = false;
/**
* 子树携带的用户信息
*/
private List userDOList;
```
- 一个JSON示例
```json
{
"msg":"操作成功",
"code":0,
"data":{
"id":"-1", //部门id，-1表示根节点
"text":"易普力云平台", //部门名称
"state":{ //状态：未开放的建议不展开
"opened":true
},
"checked":true, //为前端冗余的字段，可不处理
"attributes":null, //可忽略
"children":[ //子节点数据
{
"id":"17",
"text":"测试外部单位1",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
],
"parentId":"0",
"hasParent":false,
"hasChildren":false,
"isIndependence":false,
"userDOList":[
]
},
{
"id":"16",
"text":"葛洲坝易普力公司",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
{
"id":"19",
"text":"新疆爆破公司",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
{
"id":"24",
"text":"准东分公司",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
],
"parentId":"19",
"hasParent":true,
"hasChildren":false,
"isIndependence":false,
"userDOList":[
]
}
],
"parentId":"16",
"hasParent":true,
"hasChildren":true,
"isIndependence":false,
"userDOList":[
]
},
{
"id":"18",
"text":"科技发展中心",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
{
"id":"23",
"text":"经理层",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
],
"parentId":"18",
"hasParent":true,
"hasChildren":false,
"isIndependence":false,
"userDOList":[
{
"userId":139,
"username":"zhangcj",
"name":"张成娇",
"password":"5a4e1d85b0ada18a957088d170bd70ae",
"deptId":23,
"deptName":null,
"email":"zhangcj@ypl.cn",
"mobile":null,
"telephone":null,
"idCard":"",
"status":1,
"userIdCreate":null,
"gmtCreate":null,
"gmtModified":null,
"roleIds":null,
"sex":null,
"birth":null,
"picId":null,
"liveAddress":null,
"hobby":null,
"province":null,
"city":null,
"district":null,
"userIdEdfos":null,
"userIdBP":0,
"mainPost":null,
"deputyPost":null,
"parttimePost":null,
"position":null
}
]
},
{
"id":"22",
"text":"装备组",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
],
"parentId":"18",
"hasParent":true,
"hasChildren":false,
"isIndependence":false,
"userDOList":[
]
},
{
"id":"21",
"text":"工艺组",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
],
"parentId":"18",
"hasParent":true,
"hasChildren":false,
"isIndependence":false,
"userDOList":[
]
},
{
"id":"20",
"text":"爆破组",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
],
"parentId":"18",
"hasParent":true,
"hasChildren":false,
"isIndependence":false,
"userDOList":[
{
"userId":141,
"username":"tiansl",
"name":"田水龙",
"password":"5c35b0b76a5edadb83797940c351f500",
"deptId":20,
"deptName":null,
"email":"tsl@xujian.tech",
"mobile":null,
"telephone":null,
"idCard":"",
"status":1,
"userIdCreate":null,
"gmtCreate":null,
"gmtModified":null,
"roleIds":null,
"sex":null,
"birth":null,
"picId":null,
"liveAddress":null,
"hobby":null,
"province":null,
"city":null,
"district":null,
"userIdEdfos":null,
"userIdBP":0,
"mainPost":null,
"deputyPost":null,
"parttimePost":null,
"position":null
},
{
"userId":138,
"username":"xujian",
"name":"徐建",
"password":"064b15991847bbee9f6bd8307540fbb4",
"deptId":20,
"deptName":null,
"email":"mail@xujian.tech",
"mobile":null,
"telephone":null,
"idCard":"500224202010225458",
"status":1,
"userIdCreate":null,
"gmtCreate":null,
"gmtModified":null,
"roleIds":null,
"sex":null,
"birth":null,
"picId":null,
"liveAddress":null,
"hobby":null,
"province":null,
"city":null,
"district":null,
"userIdEdfos":51,
"userIdBP":127,
"mainPost":null,
"deputyPost":null,
"parttimePost":null,
"position":null
}
]
}
],
"parentId":"16",
"hasParent":true,
"hasChildren":true,
"isIndependence":true,
"userDOList":[
]
}
],
"parentId":"0",
"hasParent":false,
"hasChildren":true,
"isIndependence":true,
"userDOList":[
]
},
{
"id":"6",
"text":"系统管理员",
"state":{
"opened":true
},
"checked":false,
"attributes":null,
"children":[
],
"parentId":"0",
"hasParent":false,
"hasChildren":false,
"isIndependence":true,
"userDOList":[
{
"userId":140,
"username":"sysadmin",
"name":"数据管理员",
"password":"66c08ad50406059e5a295328e815fa31",
"deptId":6,
"deptName":null,
"email":"sysadmin@xujian.tech",
"mobile":null,
"telephone":null,
"idCard":null,
"status":1,
"userIdCreate":null,
"gmtCreate":null,
"gmtModified":null,
"roleIds":null,
"sex":null,
"birth":null,
"picId":null,
"liveAddress":null,
"hobby":null,
"province":null,
"city":null,
"district":null,
"userIdEdfos":null,
"userIdBP":0,
"mainPost":null,
"deputyPost":null,
"parttimePost":null,
"position":null
},
{
"userId":1,
"username":"admin",
"name":"超级管理员",
"password":"27bd386e70f280e24c2f4f2a549b82cf",
"deptId":6,
"deptName":null,
"email":"admin@example.com",
"mobile":"17699999999",
"telephone":null,
"idCard":null,
"status":1,
"userIdCreate":1,
"gmtCreate":"2017-08-16 05:40:39",
"gmtModified":"2017-08-16 05:41:00",
"roleIds":null,
"sex":96,
"birth":"2017-12-14 08:00:00",
"picId":138,
"liveAddress":"ccc",
"hobby":"121;",
"province":"北京市",
"city":"北京市市辖区",
"district":"东城区",
"userIdEdfos":null,
"userIdBP":0,
"mainPost":null,
"deputyPost":null,
"parttimePost":null,
"position":null
}
]
}
],
"parentId":"", //父节点
"hasParent":false, //是否有父节点
"hasChildren":true, //是否有子节点
"isIndependence":false, //是否独立运营
"userDOList":null //用户信息
}
}
}
```
#### 七、测试、开发环境搭建
- admin服务是一个使用开源项目BootDo改造而成的服务。
[点击查看BootDo](https://gitee.com/lcg0124/bootdo/wikis/Home)
- 系统运行在Spring Cloud Alibaba 下，服务注册与发现中心为Nacos。
[点击查看Nacos文档](https://nacos.io/zh-cn/)
##### 1、资源下载
- 资源包涵：admin运行程序及配置文件、启动命令、sql文件（mysql）
[点击下载](http://7niucdn.xujian.tech/DevEnv20201204.zip)
##### 2、环境部署
- 本系统运行在Java环境，需安装nacos、redis及MySQL数据库（建议为5.7）
##### 4.启动admin程序
- 导入mysql数据
- 修改application.yml相关配置（端口、nacos地址、redis地址、mysql配置等）
- 执行startup.bat（windows）或startup.sh(linux)启动admin服务
- clone demo源码、修改配置并启动
- 检查nacos服务注册是否成功
- 访问http://{ip}:{port}/test/user/uid观察服务之间的交互是否成功：取得了用户信息即交互成功！
- admin服务可直接通过端口访问，账号：sysadmin，密码：123456。