Yo信

系统集成 #

同步 #

用户同步 #

public interface YoUserService {
    /**
     * 取得用户信息
     * @param userId 用户ID
     * @return
     */
    YoUserDto getUserDto(String userId) throws Exception;

    /**
     * 取得用户基本信息
     * @param username  用户唯一标识
     * @param category  username是那种类型： loginId or userId or phone or email
     * @return
     */
    YoUserBaseDto getUserBaseDto(String username, String category) throws Exception;

    /**
     * 更新用户性别
     * @param userId  用户ID
     * @param gender 性别 0 男 1 女 2 其他
     */
    void updateUserGender(String userId, Integer gender) throws Exception;

    /**
     * 更新用户手机号
     * @param userId  用户ID
     * @param phone   手机号
     */
    void updateUserPhone(String userId, String phone) throws Exception;

    /**
     * 更新用户邮箱
     * @param userId  用户ID
     * @param email   邮箱
     */
    void updateUserEmail(String userId, String email) throws Exception;

    /**
     * 更新用户密码
     * @param userId     用户ID
     * @param password   用户密码，base64加密
     */
    void updateUserPassword(String userId, String password) throws Exception;

    /**
     * 添加用户
     * @param baseDto 用户基本信息
     * @return 用户ID
     */
    String addUser(YoUserBaseDto baseDto) throws Exception;

    /**
     * 检查用户密码
     * @param userId    用户ID
     * @param password  密码，base64加密
     * @return true密码正确， false 密码错误
     */
    Boolean checkUserPassword(String userId, String password) throws Exception;

    /**
     * 分页同步用户，初期启动时使用
     * @param page   页码
     * @param count  每页条数
     * @return 分页用户同步信息
     */
    YoPageInfo<YoUserSyncDto> getUserSyncList(Integer page, Integer count) throws Exception;
}

组织同步 #

public interface YoOrgService {

    /**
     * 取得组织下成员
     * @param orgId      组织ID
     * @param page       页码
     * @param count      每页条数
     * @param hasSubOrg  是否包含子组织的成员
     * @param filter     搜索字段
     * @return
     */
    YoPageInfo<YoOrgMemberDto> getOrgMembers(String orgId, Integer page, Integer count,
                                             Boolean hasSubOrg, String filter) throws Exception;

    /**
     * 是否是组织成员
     * @param orgId      组织ID
     * @param memberId   用户ID
     * @return
     */
    Boolean isMemberInOrg(String orgId, String memberId) throws Exception;

    /**
     * 两个用户是否属于同一家公司
     * @param userId1  用户ID
     * @param userId2  用户ID
     * @return
     */
    Boolean isInSameCompany(String userId1, String userId2) throws Exception;

    /**
     * 取得客服
     * @param str json字符串，扩展信息，TBD.
     * @return
     */
    YoOrgMemberDto getCustomerServiceAgent(String str) throws Exception;

    /**
     * 取得组织所有上级组织
     * @param orgId       组织ID
     * @param companyId   公司ID
     * @return
     */
    List<String> parentOrgIds(String orgId, String companyId, Boolean containCompany) throws Exception;

    /**
     * 取得组织基本信息
     * @param orgId
     * @return
     */
    YoOrgBaseDto getOrgBase(String orgId) throws Exception;

    /**
     * 取得组织详情
     * @param orgId            组织ID
     * @param hasSubOrg        是否取得子组织
     * @param hasSubCompany    是否包含子公司(被集成系统支持集团版有效)
     * @param hasMemberNum     是否取得成员数
     * @return
     */
    YoOrgDto getOrg(String orgId, Boolean hasSubOrg, Boolean hasSubCompany, Boolean hasMemberNum) throws Exception;

    /**
     * 取得用户所在公司
     * @param userId 用户ID
     * @return
     */
    YoOrgBaseDto getUserCompany(String userId) throws Exception;

    /**
     * orgId是否是parentId的子组织
     * @param orgId      组织ID
     * @param parentId   父组织ID
     * @return
     */
    Boolean isSubOrg(String orgId, String parentId) throws Exception;

    /**
     * 用户在组织是否具有角色，即是否是主职，副职，管理员
     * @param orgId    组织ID
     * @param userId   用户ID
     * @return
     */
    Boolean isUserHasOrgRole(String orgId, String userId) throws Exception;
}

应用鉴权 #

public interface YoAppService {
    /**
     * 把配置在工作台的集成系统应用，传给集成系统，集成系统做权限判断，返回用户可访问的应用
     * @param list 应用列表
     * @return 如果返回null表示集成系统没实现此方法，将把list全部返回给客户端
     */
    List<YoAppDto> getWorkbenchApps(List<YoAppDto> list) throws Exception;
}

接口对象 #

应用 #

@Setter
@Getter
@ToString
public class YoAppDto {
    /**
     * 应用唯一标识
     */
    private String appId;

    /**
     * 应用名
     */
    private String name;

    /**
     * 应用图标
     */
    private String icon;

    /**
     * 应用路由路径
     */
    private String path;

    /**
     * 应用描述
     */
    private String description;

    /**
     * 应用所属系统ID
     */
    private String sysId;

    /**
     * 应用类别
     */
    private String category;

    /**
     * 应用打开方式，tab，window，browser
     */
    private String openMode;
}

组织基本信息 #

@Setter
@Getter
@ToString
@Accessors(chain = true)
public class YoOrgBaseDto {
    /**
     * 组织ID
     */
    private String orgId;

    /**
     * 此组织的父组织ID
     */
    private String parentId;

    /**
     * 组织名
     */
    private String name;

    /**
     * 组织编码
     */
    private String code;

    /**
     * 组织是否是公司
     */
    private Boolean isCompany;
}

组织信息 #

@Setter
@Getter
@ToString(callSuper = true)
public class YoOrgDto extends YoOrgBaseDto {
    /**
     * 子组织数
     */
    private Integer subOrgNum;

    /**
     * 组织下成员数
     */
    private Long memberNum;

    /**
     * 子组织集合
     * 注意: subOrgs集合中OrgDto对象里的subOrgs属性为空(不要递归赋值)
     */
    private List<YoOrgDto> subOrgs;
}

组织成员 #

@Setter
@Getter
@ToString
@NoArgsConstructor
public class YoOrgMemberDto implements Serializable {
    /**
     * 用户ID
     */
    private String userId;
    
    /**
     * 用户名字
     */
    private String realName;
    
    /**
     * 组织ID
     */
    private String orgId;
}

分页 #

@Setter
@Getter
@ToString
public class YoPageInfo<T> {
    /**
     * 页码
     */
    private int pageNum;

    /**
     * 每页条数
     */
    private int pageSize;

    /**
     * 总数
     */
    private long total;

    /**
     * 是否有下一页
     */
    private boolean hasNextPage;

    /**
     * 数据列表
     */
    private List<T> list;
}

用户基本信息 #

@Setter
@Getter
@ToString
@Accessors(chain = true)
public class YoUserBaseDto {
    /**
     * 用户ID
     */
    private String userId;
    /**
     * 登录账号
     */
    private String loginId;
    /**
     * 手机号
     */
    private String phone;
    /**
     * 邮箱
     */
    private String email;

    /**
     * 真实姓名
     */
    private String realName;

    /**
     * 性别 0 男 1女
     */
    private Integer gender;

    /**
     * 座机
     */
    private String tel;

    /**
     * 是否可用
     */
    private Boolean isDisable;

    /**
     * 创建时间
     */
    private Date createTime;
}

用户信息 #

@Setter
@Getter
@ToString(callSuper = true)
@EqualsAndHashCode(callSuper = true)
@Accessors(chain = true)
public class YoUserDto extends YoUserBaseDto {

    /**
     * 公司ID
     */
    private String companyId;

    /**
     * 公司名
     */
    private String companyName;

    /**
     * 公司角色，主职，副职，管理员，普通员工
     * {@link com.cmcim.yoxin.integration.constant.YoOrgRole}
     */
    private Integer companyRole;

    /**
     * 部门，岗位
     */
    private List<YoUserDeptDto> depts;

    /**
     * 工号
     */
    private String jobNo;

用户部门信息 #

@Setter
@Getter
@ToString
@Accessors(chain = true)
public class YoUserDeptDto {
    /**
     * 部门ID
     */
    private String deptId;

    /**
     * 部门名
     */
    private String deptName;

    /**
     * 岗位ID
     */
    private Integer postId;

    /**
     * 岗位名称
     */
    private String postName;

    /**
     * 组织群ID
     */
    private String groupId;

    /**
     * 组织角色
     */
    private Integer orgRole;
}

用户同步信息 #

@Setter
@Getter
@ToString
public class YoUserSyncDto {
    /**
     * 用户ID
     */
    private String userId;
    /**
     * 用户名
     */
    private String name;
    /**
     * 用户创建时间
     */
    private Long createTime;
}

常量 #

组织角色 #

public class YoOrgRole {
    /**
     * 普通成员
     */
    public static final int NORMAL = 0;

    /**
     * 副职
     */
    public static final int DEPUTY = 9;

    /**
     * 主职
     */
    public static final int PRINCIPAL = 10;

    /**
     * 管理员
     */
    public static final int ADMIN = 11;
}

API #

由集成系统调用Yo信的Restful API

共同 #

说明与约定 #

  • 默认前缀/yoxin/v1/api，下面每个请求的地址都需要拼接前缀
  • 请求参数中自定义类型，在类定义中查询
  • Content-Type: application/json
  • 鉴权，在请求头中添加，key:app_secret，value:upushSecret，upushSecret是UPush的AppSecret参照 (opens new window)

应答 #

应答格式，code为0时请求成功，msg为错误信息，data为应答内容，下面的接口只描述data内容，不再赘述。

{
  code: 0,
  msg: "",
  data: {} 
}

参数位置 #

参数位置几种类型举例：

  • 路径参数
    例如：/group/{groupId}/user/{userId}/notification/type/{notifyType}
axios({
  url:"/group/myGroupId/user/myUserId/notification/type/1"
})
  • URL参数
    例如：/group?&groupId=myGroupId&userId=myUserId&type=1
axios({
  url:"/group",
  params: {
    groupId: myGroupId,
    userId: myUserId,
    type: 1
  }
})
  • Body参数
    例如：/group
axios({
  url:"/group",
  data: {
    groupId: myGroupId,
    userId: userId,
    type: 1
  }
})

类定义 #

@Setter
@Getter
@ToString
public class AppMessageBtnDto {
    // 标题
    @NotBlank
    private String title;

    // 当action, params都为空时，点击按钮等同于直接点击消息

    // 点击动作，可以是http链接，chat://userId 跳转到聊天项，为空时跳转到应用页面并拼接params作为url参数
    private String action;

    // 点击参数，url参数，拼接到应用的路径后面
    private Map<String, String> params;

    // 打开方式 window or browser，默认window
    private String openMode;
}

群组 #

创建组织群 #

POST /group
参数名 参数类型 参数位置 必需 描述
orgId String Body 是 组织ID
isContainSubOrg Boolean Body 是 是否包含子组织成员
masterId String Body 否 群主用户ID，可选，为空时组织主职做为群主

返回结果:

{
  "groupId": "g_08acba64ade6a4142dd0ca20e511c554"
}

解散组织群 #

DELETE /group/{groupId}
参数名 参数类型 参数位置 必需 描述
groupId String 路径 是 群组ID

消息 #

发送应用消息 #

POST /message/app/{appId}
参数名 参数类型 参数位置 必需 描述
appId String 路径 是 应用ID
content String Body 是 消息内容
userIds String[] Body 是 消息接收用户ID
title String Body 否 消息标题
sendTime Long Body 否 发送时间戳，值为空，0，小于当前时间时立即发送
params Object Body 否 参数, url参数，拼接到应用的路径后面
cover String Body 否 封面，两种格式1 http, 2 文件ID,先把图片上传到IM服务器返回的文件ID
coverPosition String Body 否 封面位置，top在正文上面，bottom在正文下面，small显示小图在消息侧面
openMode String Body 否 打开方式 window or browser，默认window
buttons AppMessageBtnDto[] Body 否 消息按钮，建按钮数小于等于3

上传应用消息图片 #

POST /message/app/{appId}/image
参数名 参数类型 参数位置 必需 描述
appId String 路径 是 应用ID
file File RequestPart 是 图片

返回结果:

{
  "fileId": "1708485903402_ea7da3df0346b0df80f21ab35604120e"
}