UserGroupAPIController（用户组管理 API）¶

用户中心模块的用户组域 CRUD/查询控制器，提供用户组（通讯录用户组的分组定义）的创建、更新、查找、删除，以及「获取用户所属的用户组列表（分页）」「按用户组名称 + 所有者检查用户组是否存在」等能力。该控制器由 obpm-runtime、obpm-manager、obpm-kms 等宿主服务以 Feign 方式内部调用（UserGroupAPI 接口），属于后端服务间数据面接口。

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

公共说明¶

鉴权¶

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

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

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

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

响应结构¶

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

情形	HTTP 状态	响应体
返回值为 `void` 的方法（创建/更新/删除）成功	200	空响应体
返回值为领域对象/集合/包装类型的方法成功	200	直接序列化的对象 JSON（如 `UserGroupPO`、`DataPackage<UserGroupPO>`、`boolean`），不包裹 `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` 直接返回）

数据模型：`UserGroupPO`¶

返回的 UserGroupPO 继承自 AuthtimeValueObject，类级标注 @JSR303，表示一个通讯录用户组。主要字段：id（主键，继承自父类）、name（用户组名称，@NotEmpty(message = "1111")，必填）、ownerId（所有者 ID）。

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

getUserGroupsByUser 返回 cn.myapps.common.data.DataPackage<UserGroupPO>，标准字段为 datas（当前页数据集合）、rowCount（总行数）、pageNo（当前页码）、linesPerPage（每页行数）等。

1. 创建用户组¶

创建新的用户组记录。事务保护：失败回滚。

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

请求参数¶

参数名	位置	类型	必填	说明
body	body	`UserGroupPO`	是	用户组信息，至少包含 `name`（`@NotEmpty`）；通常还包含 `ownerId`（所有者 ID）

请求示例¶

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

{
  "name": "研发通讯录组",
  "ownerId": "__v2yGm0001"
}

响应¶

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

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

失败示例：

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

2. 更新用户组¶

更新现有的用户组记录。事务保护：失败回滚。

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

请求参数¶

参数名	位置	类型	必填	说明
body	body	`UserGroupPO`	是	待更新用户组（须含主键 `id`），可携带需更新的字段（`name`、`ownerId`）

请求示例¶

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

{
  "id": "__UG001",
  "name": "研发通讯录组-new",
  "ownerId": "__v2yGm0001"
}

响应¶

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

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

失败示例：

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

3. 根据 ID 查找用户组¶

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

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

请求参数¶

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

请求示例¶

GET /usercenter/usergroup/find/__UG001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

{
  "id": "__UG001",
  "name": "研发通讯录组",
  "ownerId": "__v2yGm0001"
}

失败示例：

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

4. 根据 ID 删除用户组¶

根据用户组 ID 删除用户组。事务保护：失败回滚。

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

请求参数¶

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

请求示例¶

DELETE /usercenter/usergroup/remove/__UG001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

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

失败示例：

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

5. 获取用户所属的用户组列表¶

根据用户 ID 分页查询该用户所属的全部用户组列表。

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

请求参数¶

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

请求示例¶

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

响应¶

结构：成功为 DataPackage<UserGroupPO> 对象 JSON（不包裹 Resource），含 datas（当前页用户组集合）、rowCount、pageNo、linesPerPage 等字段；分页参数（页码、每页行数）由 DAO 默认值决定，本端点未暴露 page/lines 入参。

成功示例：

{
  "datas": [
    { "id": "__UG001", "name": "研发通讯录组", "ownerId": "__v2yGm0001" }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 10
}

失败示例：

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

6. 检查用户组是否存在¶

按用户组名称 + 所有者 ID 检查同名的用户组是否已存在（用于创建前的重名校验）。

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

请求参数¶

参数名	位置	类型	必填	说明
userGroupName	query	string	是	用户组名称
ownerId	query	string	是	所有者 ID

请求示例¶

GET /usercenter/usergroup/isExistGroup?userGroupName=研发通讯录组&ownerId=__v2yGm0001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 boolean（裸 true/false，不包裹 Resource）。

成功示例：

false

失败示例：

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

UserGroupAPIController（用户组管理 API）¶

公共说明¶

鉴权¶

响应结构¶

数据模型：UserGroupPO¶

分页结构：DataPackage<UserGroupPO>¶

1. 创建用户组¶

请求参数¶

请求示例¶

响应¶

2. 更新用户组¶

请求参数¶

请求示例¶

响应¶

3. 根据 ID 查找用户组¶

请求参数¶

请求示例¶

响应¶

4. 根据 ID 删除用户组¶

请求参数¶

请求示例¶

响应¶

5. 获取用户所属的用户组列表¶

请求参数¶

请求示例¶

响应¶

6. 检查用户组是否存在¶

请求参数¶

请求示例¶

响应¶

数据模型：`UserGroupPO`¶

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