UserAPIController（用户管理 API）¶

用户中心模块的用户域 CRUD/查询控制器，提供用户的创建、更新、查找、删除、按多种维度（域、部门、角色、登录名、电话、邮箱、首字母、模糊、钉钉/飞书 ID 等）查询，以及锁定状态维护、批量创建、知识管理角色关系维护等能力。该控制器由 obpm-runtime、obpm-manager、obpm-kms 等宿主服务以 Feign 方式内部调用（UserAPI 接口），属于后端服务间数据面接口。

控制器全限定名：cn.myapps.usercenter.controller.UserAPIController
接口（Feign 契约）：cn.myapps.usercenter.controller.UserAPI
Tag：用户管理API
类级 @RequestMapping：${myapps.context-path.usercenter:}/user
基址：<host>/usercenter/user
独立部署（obpm-usercenter-war/obpm-usercenter-consul）：server.servlet.context-path=/usercenter，占位符 ${myapps.context-path.usercenter:} 缺省为空，故实际基址为 <host>:<port>/usercenter/user（war 端口 8080，consul 端口 8088）。
统一部署（obpm-lite）：server.servlet.context-path=/，yml 显式配置 myapps.context-path.usercenter=/usercenter，故实际基址同样为 <host>:8888/usercenter/user。
接口类型：REST 资源

公共说明¶

鉴权¶

（据源码）usercenter 模块本身**不定义**任何安全过滤器或鉴权拦截器，仅注册 PersistenceHandlerInterceptor（用于 DAO 资源清理——事务提交与 Hibernate Session 关闭，不做权限判断）。本控制器 /user/** 路径下所有端点**不做用户级身份校验**——既不读取 accessToken，也不读取 adminToken/designerToken，控制器方法内也不调用任何 getUser() 之类方法。

usercenter 作为共享库被宿主服务加载后，会继承 obpm-common 提供的 CommonSecurityFilter（由 CommWebMvcConfig 以 @Bean 注册，URL 模式 /*，order=-1，详见 index.md「鉴权说明」），对 /user/** 的影响仅限：

HTTP 方法限制：未携带合法 systemToken 请求头时，仅允许 GET/POST/HEAD/OPTIONS 方法；直接发起 PUT/DELETE/PATCH 等请求会被 CommonSecurityFilter 以 HTTP 405（HTML 错误页，无 JSON 体）拒绝。
systemToken 放行：携带合法 systemToken 请求头（系统间 Feign 调用，JWT 内 username 固定为 systemToken）的请求被标记 pass=true 并绕过上述方法限制——这是本控制器 PUT /update、PUT /updateUserLockFlag、DELETE /remove/{id} 在生产中正常工作的前提。

结论：本控制器的真实访问控制依赖**网络层隔离**（仅由可信的内部服务经 Feign 调用，附 systemToken 请求头），并非用户令牌。终端用户不应直接访问这些端点。

响应结构¶

本控制器不使用统一 Resource 结构（与 ../index.md「统一响应结构」不同）。响应遵循以下规则：

情形	HTTP 状态	响应体
返回值为 `void` 的方法（创建/更新/删除/批量创建/锁定/创建知识管理角色）成功	200	空响应体
返回值为领域对象/集合/包装类型的方法成功	200	直接序列化的对象 JSON（如 `UserPO`、`Collection<UserPO>`、`DataPackage<UserPO>`、`int`、`Collection<String>`、`List<String>`、`Collection<UserDepartmentRoleSet>`），不包裹 `errcode`/`errmsg`/`data`/`errors`
业务/系统异常	500	`{"errcode":500,"errmsg":"<异常信息>"}`（由 obpm-common 的 `CommonsExceptionResolver` 全局异常处理器渲染，仅含 `errcode`/`errmsg` 两字段，无 `data`/`errors`）
HTTP 方法不被允许（无 `systemToken` 的 `PUT`/`DELETE`）	405	HTML 错误页（由 `CommonSecurityFilter` 直接返回）
系统启动中	500	HTML 错误页（由 `CommonSecurityFilter` 直接返回）

OBPMValidateException：DELETE /remove/{id} 在用户被引用导致 Hibernate/Persistence 异常时显式抛出 OBPMValidateException("{*[core.superuser.referenced]*}")，由 CommonsExceptionResolver 渲染为 HTTP 500，errmsg 取 getValidateMessage()（即上述占位符串）。

数据模型：`UserPO`¶

返回的 UserPO 继承自 AuthtimeValueObject（实现 IFrontEndUser/IBaseUser），主要字段包括：id、level（等级）、remarks（备注）、manageDepartments（管理部门）、interfaceDepartments（接口部门）、useIM（是否使用即时通信）、departmentUser（是否部门管理员）、orderByNo（排序号）、account（关联账户 AccountPO：含 loginno 登录名、email、loginpwd、telephone、telephone2、isFirstLogin）、field1~field12（业务/系统扩展字段）、userDepartmentRoleSets（用户-部门-角色关系集）等，以及来自父类的 domain（域）、superior（上级）、name、loginno、status 等通用字段。

分页结构：`DataPackage<UserPO>`¶

queryByDomain/queryDataByParamsTable/queryByDomainAndLikeName/queryByDepartment/queryByRoleAndDomain/queryBySuperior/queryByDomainAndContanctsIdAndUsers/queryByDoaminAndStatusAndPermissionType 等方法返回 cn.myapps.common.data.DataPackage<UserPO>，其标准字段为 datas（当前页数据集合）、rowCount（总行数）、pageNo（当前页码）、linesPerPage（每页行数）等。

1. 创建用户¶

创建新的用户信息；若同登录名（loginno）的账户不存在则一并创建 AccountPO，否则更新该账户。事务保护：失败回滚。

接口类型：REST 资源
请求方式：POST
请求路径：/create（完整：<host>/usercenter/user/create）
鉴权：内部（建议经 systemToken 的 Feign 调用；直接调用因 POST 方法不被 CommonSecurityFilter 拦截故技术上无需 token，但本控制器为内部数据面接口）
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
body	body	`UserPO`	是	用户信息，至少包含 `loginno`；可携带 `email`、`loginpwd`、`telephone`、`telephone2`、`isFirstLogin` 等账户字段（写入关联 `AccountPO`）

请求示例¶

POST /usercenter/user/create HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{
  "loginno": "zhangsan",
  "name": "张三",
  "loginpwd": "<密码>",
  "email": "zhangsan@example.com",
  "telephone": "13800000000",
  "domain": "<域ID>"
}

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

2. 更新用户¶

更新现有用户信息；按 po.getLoginno() 查找关联 AccountPO 后更新账户字段（邮箱、密码、电话、二次电话、首登标志），再更新用户。事务保护：失败回滚。

接口类型：REST 资源
请求方式：PUT
请求路径：/update（完整：<host>/usercenter/user/update）
鉴权：内部（PUT 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
body	body	`UserPO`	是	待更新用户（须含主键 `id` 与 `loginno`），可携带需更新的 `email`/`loginpwd`/`telephone`/`telephone2`/`isFirstLogin` 字段

请求示例¶

PUT /usercenter/user/update HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{
  "id": "__v2yGm0001",
  "loginno": "zhangsan",
  "name": "张三-new",
  "email": "zhangsan-new@example.com",
  "loginpwd": "<新密码>",
  "telephone": "13800000001"
}

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

3. 查找用户¶

根据用户 ID 查找单个用户。

接口类型：REST 资源
请求方式：GET
请求路径：/find/{id}（完整：<host>/usercenter/user/find/{id}）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
id	path	string	是	用户 ID

请求示例¶

GET /usercenter/user/find/__v2yGm0001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 UserPO 对象 JSON（不包裹 Resource）；未找到时由 DAO 行为决定（通常返回 null 或抛异常进入 CommonsExceptionResolver）。

成功示例：

{
  "id": "__v2yGm0001",
  "name": "张三",
  "loginno": "zhangsan",
  "domain": "<域ID>",
  "status": 1,
  "level": 0,
  "account": { "loginno": "zhangsan", "email": "zhangsan@example.com", "telephone": "13800000000" }
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

4. 删除用户¶

根据用户 ID 删除用户；若同登录名已无其他用户，则一并删除关联账户。事务保护：失败回滚。用户被其他实体引用导致删除失败时显式抛 OBPMValidateException（{*[core.superuser.referenced]*}）。

接口类型：REST 资源
请求方式：DELETE
请求路径：/remove/{id}（完整：<host>/usercenter/user/remove/{id}）
鉴权：内部（DELETE 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
id	path	string	是	用户 ID

请求示例¶

DELETE /usercenter/user/remove/__v2yGm0001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为**空响应体**（返回类型 void）；被引用时 errmsg 为 {*[core.superuser.referenced]*}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "{*[core.superuser.referenced]*}" }

5. 按域查询用户¶

根据域 ID 分页查询用户。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByDomain（完整：<host>/usercenter/user/queryByDomain）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
domainId	query	string	是	企业域 ID
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

GET /usercenter/user/queryByDomain?domainId=__DMN001&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<UserPO> 对象 JSON（不包裹 Resource），含 datas（当前页用户集合）、rowCount、pageNo、linesPerPage 等字段。

成功示例：

{
  "datas": [
    { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

6. 根据登录名查找用户¶

根据登录名和域 ID 查找用户。

接口类型：REST 资源
请求方式：GET
请求路径：/findByLoginno（完整：<host>/usercenter/user/findByLoginno）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
loginNo	query	string	是	登录名
domainId	query	string	否	企业域 ID（缺省时跨域匹配）

请求示例¶

GET /usercenter/user/findByLoginno?loginNo=zhangsan&domainId=__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 UserPO 对象 JSON（不包裹 Resource）。

成功示例：

{ "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan", "domain": "__DMN001" }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

7. 根据电话查找用户¶

根据电话号码和域 ID 查找用户。

接口类型：REST 资源
请求方式：GET
请求路径：/findByTelephone（完整：<host>/usercenter/user/findByTelephone）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
telephone	query	string	是	电话号码
domainId	query	string	是	企业域 ID

请求示例¶

GET /usercenter/user/findByTelephone?telephone=13800000000&domainId=__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 UserPO 对象 JSON（不包裹 Resource）。

成功示例：

{ "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan", "account": { "telephone": "13800000000" } }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

8. 根据邮箱查找用户¶

根据邮箱和域 ID 查找用户。

接口类型：REST 资源
请求方式：GET
请求路径：/findByEmail（完整：<host>/usercenter/user/findByEmail）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
email	query	string	是	邮箱
domainId	query	string	是	企业域 ID

请求示例¶

GET /usercenter/user/findByEmail?email=zhangsan@example.com&domainId=__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 UserPO 对象 JSON（不包裹 Resource）。

成功示例：

{ "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan", "account": { "email": "zhangsan@example.com" } }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

9. 查询代理用户¶

根据代理用户 ID 查询相关用户集合。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByProxyUserId（完整：<host>/usercenter/user/queryByProxyUserId）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
proxyid	query	string	是	代理用户 ID

请求示例¶

GET /usercenter/user/queryByProxyUserId?proxyid=__v2yGm0001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 Collection<UserPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "id": "__v2yGm0002", "name": "李四", "loginno": "lisi" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

10. 更新用户锁定状态¶

更新指定登录名用户的锁定标志（如登录失败锁定/解锁）。事务保护：失败回滚。

接口类型：REST 资源
请求方式：PUT
请求路径：/updateUserLockFlag（完整：<host>/usercenter/user/updateUserLockFlag）
鉴权：内部（PUT 方法需携带合法 systemToken 请求头，否则被 CommonSecurityFilter 以 HTTP 405 拒绝）
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
loginNo	query	string	是	登录名
lockFlag	query	int	是	锁定标志值（具体语义由业务侧定义）

请求示例¶

PUT /usercenter/user/updateUserLockFlag?loginNo=zhangsan&lockFlag=1 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。若未带 systemToken，HTTP 405（HTML 错误页）。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

11. 批量创建用户¶

批量创建多个用户。事务保护：失败回滚。

接口类型：REST 资源
请求方式：POST
请求路径：/batchCreate（完整：<host>/usercenter/user/batchCreate）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
body	body	`Collection<UserPO>`	是	用户列表

请求示例¶

POST /usercenter/user/batchCreate HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

[
  { "loginno": "u001", "name": "用户甲", "domain": "__DMN001" },
  { "loginno": "u002", "name": "用户乙", "domain": "__DMN001" }
]

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

12. 统计部门用户数¶

统计指定部门下的用户数量。

接口类型：REST 资源
请求方式：GET
请求路径：/countByDepartment（完整：<host>/usercenter/user/countByDepartment）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
deptId	query	string	是	部门 ID

请求示例¶

GET /usercenter/user/countByDepartment?deptId=__DEPT001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 int（裸数字，不包裹 Resource）。

成功示例：

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

13. 统计角色域用户数¶

统计指定角色且在指定企业域下的用户数量。

接口类型：REST 资源
请求方式：GET
请求路径：/countByRoleAndDomain（完整：<host>/usercenter/user/countByRoleAndDomain）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
roleId	query	string	是	角色 ID
domainId	query	string	是	企业域 ID

请求示例¶

GET /usercenter/user/countByRoleAndDomain?roleId=__ROLE001&domainId=__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 int（裸数字，不包裹 Resource）。

成功示例：

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

14. 查询用户角色¶

查询指定用户的全部角色 ID。

接口类型：REST 资源
请求方式：GET
请求路径：/queryRoleIdsByUserId（完整：<host>/usercenter/user/queryRoleIdsByUserId）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
userId	query	string	是	用户 ID

请求示例¶

GET /usercenter/user/queryRoleIdsByUserId?userId=__v2yGm0001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 Collection<String> JSON 数组（角色 ID 集合，不包裹 Resource）。

成功示例：

["__ROLE001", "__ROLE002"]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

15. 高级查询用户¶

按多个参数条件（域、部门、角色、搜索关键词、状态、排序）分页查询用户。搜索逻辑由 DAO 层 queryDataByParamsTable 实现。

接口类型：REST 资源
请求方式：POST
请求路径：/queryDataByParamsTable（完整：<host>/usercenter/user/queryDataByParamsTable）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
body	body	`Map<String, Object>`	是	附加查询参数映射（透传至 DAO）
domainId	query	string	是	企业域 ID
departmentId	query	string	是	部门 ID
roleId	query	string	是	角色 ID
searchWord	query	string	是	搜索关键词
status	query	Integer	否	状态（如 1=在职，0=离职，缺省不限）
order	query	string	是	排序方式
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

POST /usercenter/user/queryDataByParamsTable?domainId=__DMN001&departmentId=__DEPT001&roleId=__ROLE001&searchWord=张&order=asc&page=1&lines=20 HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{ "extraKey": "extraValue" }

响应¶

结构：成功为 DataPackage<UserPO> 对象 JSON（不包裹 Resource）。

成功示例：

{
  "datas": [
    { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

16. 按首字母查询¶

根据关键字（首字母）和域 ID 查询用户集合。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByFirstLetter（完整：<host>/usercenter/user/queryByFirstLetter）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
keyword	query	string	是	关键字（首字母）
domainId	query	string	是	企业域 ID

请求示例¶

GET /usercenter/user/queryByFirstLetter?keyword=Z&domainId=__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 Collection<UserPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

17. 模糊查询¶

根据关键字（用户名首字母/手机号/登录名）和域 ID 模糊查询用户集合。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByFuzzy（完整：<host>/usercenter/user/queryByFuzzy）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
keyword	query	string	是	关键字（匹配首字母/手机号/登录名）
domainId	query	string	是	企业域 ID

请求示例¶

GET /usercenter/user/queryByFuzzy?keyword=zhang&domainId=__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 Collection<UserPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

18. 批量查询用户¶

根据用户 ID 数组和域 ID 批量查询用户。

接口类型：REST 资源
请求方式：POST
请求路径：/queryByUserIds（完整：<host>/usercenter/user/queryByUserIds）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
body	body	`String[]`	是	用户 ID 数组
domainId	query	string	是	企业域 ID

请求示例¶

POST /usercenter/user/queryByUserIds?domainId=__DMN001 HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

["__v2yGm0001", "__v2yGm0002"]

响应¶

结构：成功为 Collection<UserPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" },
  { "id": "__v2yGm0002", "name": "李四", "loginno": "lisi" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

19. 按名称模糊查询¶

根据域 ID 和用户名称模糊查询用户，分页返回。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByDomainAndLikeName（完整：<host>/usercenter/user/queryByDomainAndLikeName）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
domainId	query	string	是	企业域 ID
name	query	string	是	用户名（模糊匹配）
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

GET /usercenter/user/queryByDomainAndLikeName?domainId=__DMN001&name=张&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<UserPO> 对象 JSON（不包裹 Resource）。

成功示例：

{
  "datas": [
    { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

20. 查询钉钉用户¶

根据钉钉用户 ID 和企业域名称查询用户。

接口类型：REST 资源
请求方式：GET
请求路径：/getUserByDdUserIdAndDoaminName（完整：<host>/usercenter/user/getUserByDdUserIdAndDoaminName）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
ddUserId	query	string	是	钉钉用户 ID
domainName	query	string	是	企业域名称

请求示例¶

GET /usercenter/user/getUserByDdUserIdAndDoaminName?ddUserId=dd123&domainName=obpm HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 UserPO 对象 JSON（不包裹 Resource）。

成功示例：

{ "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

21. 查询飞书用户¶

根据飞书用户 ID 和企业域名称查询用户。

接口类型：REST 资源
请求方式：GET
请求路径：/getUserByFsUserIdAndDoaminName（完整：<host>/usercenter/user/getUserByFsUserIdAndDoaminName）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
fsUserId	query	string	是	飞书用户 ID
domainName	query	string	是	企业域名称

请求示例¶

GET /usercenter/user/getUserByFsUserIdAndDoaminName?fsUserId=fs123&domainName=obpm HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 UserPO 对象 JSON（不包裹 Resource）。

成功示例：

{ "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

22. 按登录名模糊查询¶

根据企业域名称和用户名（登录名）模糊查询用户，分页返回。

接口类型：REST 资源
请求方式：GET
请求路径：/getUserByLoginnoLikeAndDoaminName（完整：<host>/usercenter/user/getUserByLoginnoLikeAndDoaminName）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
domainName	query	string	是	企业域名称
userName	query	string	否	用户名（模糊匹配，缺省不限）
page	query	int	是	页码（1 起）
line	query	int	是	每页行数

请求示例¶

GET /usercenter/user/getUserByLoginnoLikeAndDoaminName?domainName=obpm&userName=zhang&page=1&line=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 Collection<UserPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

23. 按部门和角色查询¶

根据部门 ID 和角色 ID 列表查询用户集合。

接口类型：REST 资源
请求方式：POST
请求路径：/queryByDepartmentAndRole（完整：<host>/usercenter/user/queryByDepartmentAndRole）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
deptId	query	string	是	部门 ID
body	body	`List<String>`	是	角色 ID 列表

请求示例¶

POST /usercenter/user/queryByDepartmentAndRole?deptId=__DEPT001 HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

["__ROLE001", "__ROLE002"]

响应¶

结构：成功为 Collection<UserPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

24. 按部门查询¶

根据部门 ID 分页查询用户；可通过 onlyUserinfoPublic 控制仅返回公开信息用户。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByDepartment（完整：<host>/usercenter/user/queryByDepartment）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
deptId	query	string	是	部门 ID
onlyUserinfoPublic	query	boolean	是	是否仅返回公开信息用户（`true` 仅公开，`false` 全部）
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

GET /usercenter/user/queryByDepartment?deptId=__DEPT001&onlyUserinfoPublic=false&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<UserPO> 对象 JSON（不包裹 Resource）。

成功示例：

{
  "datas": [
    { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

25. 按角色和域查询¶

根据角色 ID 和域 ID 分页查询用户。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByRoleAndDomain（完整：<host>/usercenter/user/queryByRoleAndDomain）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
roleId	query	string	是	角色 ID
domainId	query	string	是	企业域 ID
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

GET /usercenter/user/queryByRoleAndDomain?roleId=__ROLE001&domainId=__DMN001&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<UserPO> 对象 JSON（不包裹 Resource）。

成功示例：

{
  "datas": [
    { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

26. 按上级查询¶

根据上级用户 ID 分页查询下属用户。

接口类型：REST 资源
请求方式：GET
请求路径：/queryBySuperior（完整：<host>/usercenter/user/queryBySuperior）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
superiorId	query	string	是	上级用户 ID
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

GET /usercenter/user/queryBySuperior?superiorId=__v2yGm0001&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<UserPO> 对象 JSON（不包裹 Resource）。

成功示例：

{
  "datas": [
    { "id": "__v2yGm0002", "name": "李四", "loginno": "lisi" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

27. 按域和联系人查询¶

根据域 ID、联系人（用户组）ID 分页查询用户；可附加 userName 模糊过滤。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByDomainAndContanctsIdAndUsers（完整：<host>/usercenter/user/queryByDomainAndContanctsIdAndUsers）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
domainId	query	string	是	企业域 ID
contanctId	query	string	是	联系人/用户组 ID
userName	query	string	否	用户名（模糊过滤，缺省不限）
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

GET /usercenter/user/queryByDomainAndContanctsIdAndUsers?domainId=__DMN001&contanctId=__GRP001&userName=张&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<UserPO> 对象 JSON（不包裹 Resource）。

成功示例：

{
  "datas": [
    { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

28. 按域状态和权限类型查询¶

根据域 ID、权限类型和状态分页查询用户。

接口类型：REST 资源
请求方式：GET
请求路径：/queryByDoaminAndStatusAndPermissionType（完整：<host>/usercenter/user/queryByDoaminAndStatusAndPermissionType）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
domainId	query	string	是	企业域 ID
permissionType	query	string	是	权限类型（如 `private`/`public`）
status	query	int	是	状态（如 1=在职，0=离职）
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

GET /usercenter/user/queryByDoaminAndStatusAndPermissionType?domainId=__DMN001&permissionType=public&status=1&page=1&lines=20 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DataPackage<UserPO> 对象 JSON（不包裹 Resource）。

成功示例：

{
  "datas": [
    { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

29. 创建知识管理用户角色¶

为知识管理（KMS）创建用户-角色-部门关系。请求体映射键固定为 roleIds/userIds/deptIds，值分别为对应 ID 列表。事务保护：失败回滚。

接口类型：REST 资源
请求方式：POST
请求路径：/createKmUseRole（完整：<host>/usercenter/user/createKmUseRole）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
body	body	`Map<String, List<String>>`	是	含键 `roleIds`、`userIds`、`deptIds`（任一可空数组），分别对应角色、用户、部门 ID 列表

请求示例¶

POST /usercenter/user/createKmUseRole HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{
  "roleIds": ["__ROLE_KM_001"],
  "userIds": ["__v2yGm0001", "__v2yGm0002"],
  "deptIds": ["__DEPT001"]
}

响应¶

结构：成功为**空响应体**（返回类型 void）；失败为 {"errcode":500,"errmsg":"<异常信息>"}，HTTP 500。

成功示例：（HTTP 200，空响应体）

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

30. 查询知识管理角色¶

查询指定用户的全部知识管理（KMS）相关角色 ID。

接口类型：REST 资源
请求方式：GET
请求路径：/queryKmRoleIdsByUserId（完整：<host>/usercenter/user/queryKmRoleIdsByUserId）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
userId	query	string	是	用户 ID

请求示例¶

GET /usercenter/user/queryKmRoleIdsByUserId?userId=__v2yGm0001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 List<String> JSON 数组（KMS 角色 ID，不包裹 Resource）。

成功示例：

["__ROLE_KM_001"]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

31. 查询用户部门角色集¶

根据角色 ID 查询「用户-部门-角色」关系集合（UserDepartmentRoleSet）。

接口类型：REST 资源
请求方式：GET
请求路径：/queryUserDeptRoleSetsByRoleId（完整：<host>/usercenter/user/queryUserDeptRoleSetsByRoleId）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
roleId	query	string	是	角色 ID

请求示例¶

GET /usercenter/user/queryUserDeptRoleSetsByRoleId?roleId=__ROLE001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 Collection<UserDepartmentRoleSet> JSON 数组（不包裹 Resource）。元素含 userId/deptId/roleId 等关系字段（具体字段以 UserDepartmentRoleSet 模型为准）。

成功示例：

[
  { "userId": "__v2yGm0001", "deptId": "__DEPT001", "roleId": "__ROLE001" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

32. 按登录名查询用户¶

根据登录名查询所有关联的用户（跨企业域）。与 findByLoginno（返回单条/可按域过滤）不同，本端点返回该登录名下的全部用户实体集合。

接口类型：REST 资源
请求方式：GET
请求路径：/queryUsersByLoginno（完整：<host>/usercenter/user/queryUsersByLoginno）
鉴权：内部
Tag：用户管理API

请求参数¶

参数名	位置	类型	必填	说明
loginNo	query	string	是	登录名

请求示例¶

GET /usercenter/user/queryUsersByLoginno?loginNo=zhangsan HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 Collection<UserPO> JSON 数组（不包裹 Resource）。

成功示例：

[
  { "id": "__v2yGm0001", "name": "张三", "loginno": "zhangsan", "domain": "__DMN001" }
]

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>" }

UserAPIController（用户管理 API）¶

公共说明¶

鉴权¶

响应结构¶

数据模型：UserPO¶

分页结构：DataPackage<UserPO>¶

1. 创建用户¶

请求参数¶

请求示例¶

响应¶

2. 更新用户¶

请求参数¶

请求示例¶

响应¶

3. 查找用户¶

请求参数¶

请求示例¶

响应¶

4. 删除用户¶

请求参数¶

请求示例¶

响应¶

5. 按域查询用户¶

请求参数¶

请求示例¶

响应¶

6. 根据登录名查找用户¶

请求参数¶

请求示例¶

响应¶

7. 根据电话查找用户¶

请求参数¶

请求示例¶

响应¶

8. 根据邮箱查找用户¶

请求参数¶

请求示例¶

响应¶

9. 查询代理用户¶

请求参数¶

请求示例¶

响应¶

10. 更新用户锁定状态¶

请求参数¶

请求示例¶

响应¶

11. 批量创建用户¶

请求参数¶

请求示例¶

响应¶

12. 统计部门用户数¶

请求参数¶

请求示例¶

响应¶

13. 统计角色域用户数¶

请求参数¶

请求示例¶

响应¶

14. 查询用户角色¶

请求参数¶

请求示例¶

响应¶

15. 高级查询用户¶

请求参数¶

请求示例¶

响应¶

16. 按首字母查询¶

请求参数¶

请求示例¶

响应¶

17. 模糊查询¶

请求参数¶

请求示例¶

响应¶

18. 批量查询用户¶

请求参数¶

请求示例¶

响应¶

19. 按名称模糊查询¶

请求参数¶

数据模型：`UserPO`¶

分页结构：`DataPackage<UserPO>`¶