UserGroupSetAPIController（用户组集合管理 API）¶

用户中心模块的用户组集合域 CRUD/查询控制器，提供用户组集合（用户与用户组的关联关系）的创建、更新、查找、删除，以及「检查用户是否在指定用户组中」「从用户组中批量删除指定用户」等能力。该控制器由 obpm-runtime、obpm-manager、obpm-kms 等宿主服务以 Feign 方式内部调用（UserGroupSetAPI 接口），属于后端服务间数据面接口。

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

公共说明¶

鉴权¶

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

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

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}、DELETE /deleteByUser 在生产中正常工作的前提。

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

响应结构¶

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

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

数据模型：`UserGroupSetPO`¶

返回的 UserGroupSetPO 继承自 AuthtimeValueObject，表示一条「用户—用户组」的关联记录（用户加入某用户组的成员关系）。主要字段：id（主键）、userId（用户 ID）、userGroupId（所属用户组 ID）。提供两个构造器：无参构造与 (userId, userGroupId) 便捷构造。

1. 创建用户组设置¶

创建新的用户组集合（用户—用户组关联）记录。事务保护：失败回滚。

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

请求参数¶

参数名	位置	类型	必填	说明
body	body	`UserGroupSetPO`	是	用户组集合信息，包含 `userId`（用户 ID）与 `userGroupId`（用户组 ID）

请求示例¶

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

{
  "userId": "__v2yGm0001",
  "userGroupId": "__UG001"
}

响应¶

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

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

失败示例：

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

2. 更新用户组设置¶

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

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

请求参数¶

参数名	位置	类型	必填	说明
body	body	`UserGroupSetPO`	是	待更新记录（须含主键 `id`），可携带需更新的字段（`userId`、`userGroupId`）

请求示例¶

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

{
  "id": "__UGS001",
  "userId": "__v2yGm0001",
  "userGroupId": "__UG002"
}

响应¶

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

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

失败示例：

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

3. 根据 ID 查找用户组设置¶

根据用户组集合 ID 查找单条记录。

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

请求参数¶

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

请求示例¶

GET /usercenter/usergroupset/find/__UGS001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

{
  "id": "__UGS001",
  "userId": "__v2yGm0001",
  "userGroupId": "__UG001"
}

失败示例：

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

4. 根据 ID 删除用户组设置¶

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

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

请求参数¶

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

请求示例¶

DELETE /usercenter/usergroupset/remove/__UGS001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

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

失败示例：

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

5. 检查用户是否在指定用户组中¶

按用户 ID 与用户组 ID 检查该用户是否属于该用户组。

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

请求参数¶

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

请求示例¶

GET /usercenter/usergroupset/isUserInThisGroup?userId=__v2yGm0001&userGroupId=__UG001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

true

失败示例：

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

6. 从用户组中删除指定用户¶

按用户 ID 数组与用户组 ID 批量删除该用户组中指定的成员关系。事务保护：失败回滚。

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

请求参数¶

参数名	位置	类型	必填	说明
userid	body	`String[]`	是	用户 ID 数组（请求体，JSON 字符串数组）
userGroupId	query	string	是	用户组 ID

请求示例¶

DELETE /usercenter/usergroupset/deleteByUser?userGroupId=__UG001 HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

["__v2yGm0001", "__v2yGm0002"]

响应¶

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

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

失败示例：

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

UserGroupSetAPIController（用户组集合管理 API）¶

公共说明¶

鉴权¶

响应结构¶

数据模型：UserGroupSetPO¶

1. 创建用户组设置¶

请求参数¶

请求示例¶

响应¶

2. 更新用户组设置¶

请求参数¶

请求示例¶

响应¶

3. 根据 ID 查找用户组设置¶

请求参数¶

请求示例¶

响应¶

4. 根据 ID 删除用户组设置¶

请求参数¶

请求示例¶

响应¶

5. 检查用户是否在指定用户组中¶

请求参数¶

请求示例¶

响应¶

6. 从用户组中删除指定用户¶

请求参数¶

请求示例¶

响应¶

数据模型：`UserGroupSetPO`¶