Usercenter 模块 API¶
Usercenter 模块是 MyApps 平台的**用户中心共享库**（obpm-usercenter，jar 打包），为企业域内的用户、账户、部门、域、用户组、用户组集合、字段扩展、工作日历（标准日/特殊日）、媒体资源、同步日志等提供统一的数据持久化与查询能力。该模块**本身不可独立运行**——它作为一个 jar 被以下可部署单元加载，由宿主单元提供 Spring Boot 启动类、Servlet 容器与依赖注入容器：
obpm-usercenter-war（独立 WAR 部署，server.port=8080、server.servlet.context-path=/usercenter、spring.application.name=obpm-usercenter）obpm-usercenter-consul（独立 Spring Boot + Consul 注册中心部署，server.port=8088、server.servlet.context-path=/usercenter）obpm-lite（统一打包部署，server.port=8888、server.servlet.context-path=/，并在application.yml显式配置myapps.context-path.usercenter=/usercenter）
模块入口类均为
cn.myapps.run.UserCenterApp，@ComponentScan(basePackages = {"cn.myapps.*.conf", "cn/myapps"})+@EnableFeignClients(basePackages = {"cn.myapps.usercenter"})。
服务与基址¶
| 部署形态 | 端口 | context-path | 控制器占位符解析 | 实际基址示例 |
|---|---|---|---|---|
| obpm-usercenter-war（独立 WAR） | 8080 | /usercenter（来自 server.servlet.context-path） |
${myapps.context-path.usercenter:} 缺省为空 |
<host>:8080/usercenter/user |
| obpm-usercenter-consul（独立 + Consul） | 8088 | /usercenter（来自 server.servlet.context-path） |
${myapps.context-path.usercenter:} 缺省为空 |
<host>:8088/usercenter/user |
| obpm-lite（统一打包） | 8888 | /（来自 server.servlet.context-path） |
myapps.context-path.usercenter=/usercenter（yml 显式） |
<host>:8888/usercenter/user |
控制器类级 @RequestMapping 统一写作 ${myapps.context-path.usercenter:}/<resource>：独立部署下「占位符为空 + servlet context-path=/usercenter」，统一部署下「占位符=/usercenter + servlet context-path=/」，两种形态最终对外路径一致（均为 <host>/usercenter/<resource>）。
Usercenter 模块的 REST 基址并非统一的
/api/rest，而是按控制器分布在${myapps.context-path.usercenter:}/<resource>（如/user、/account、/department等）。详见各控制器文档。
鉴权说明¶
（据源码）usercenter 模块**自身不定义任何安全过滤器或鉴权拦截器**。模块内唯一的 @Configuration（cn.myapps.usercenter.conf.UsercenterMvcConfig）仅注册一个 PersistenceHandlerInterceptor——用于在 postHandle 阶段提交 Hibernate 事务并关闭 Session（DAO 资源清理），preHandle 永远返回 true，不做任何权限判断。usercenter 的 @ControllerAdvice/@ExceptionHandler 亦未定义。
usercenter 作为共享库被宿主服务加载后，会通过 @ComponentScan(basePackages = {"cn.myapps.*.conf", "cn/myapps"}) 拾取 obpm-common 提供的以下 Servlet Filter / WebMvc 配置（这些类位于 usercenter 的依赖 obpm-common 上）：
CommWebMvcConfig（cn.myapps.common.conf，@Configuration）：filterRegistrationBeanPassFilter1（order=HIGHEST_PRECEDENCE）：按硬编码 URL pattern 列表（/、/manager、/signon、/health、/actuator/health、*.js/*.css等静态后缀、/api/rest/accessToken等）命中的请求，标记pass=true/static=true放行。filterRegistrationBeanCommonSecurityFilter1（order=-1，URL 模式/*）：注册CommonSecurityFilter（见下）。filterRegistrationBeanSecurityFilter1（order=1，URL 模式/*）：注册 Spring 的HiddenHttpMethodFilter，允许 POST +_method=put/delete表单参数转换为对应的 HTTP 方法（在CommonSecurityFilter之后执行）。configureHandlerExceptionResolvers：注册全局异常处理器CommonsExceptionResolver。CommonSecurityFilter（cn.myapps.common.web）：对/user/**等用户中心路径的实际影响仅限以下几条：- 系统间调用放行：携带合法
systemToken请求头（JWT，HMAC256，issuer=auth0，claimusername固定为字符串systemToken）的请求被标记pass=true直接放行，并绕过下述方法限制。这是obpm-runtime/obpm-manager/obpm-kms等宿主服务通过 Feign 调用 usercenter 时使用的鉴权方式。 - HTTP 方法限制：未携带合法
systemToken的请求，仅允许GET/POST/HEAD/OPTIONS；PUT/DELETE/PATCH等被直接返回 HTTP405（Content-Type: text/html，无 JSON 体）。 - 系统未就绪：
Environment.isReady()为 false 时返回 HTTP500（HTML 提示「系统正在启动中」）。 - /swagger-ui、/v3/api-docs、/druid：需
designerToken或adminToken（开发者中心/管理控制台登录）。 /actuator/health放开；/actuator/**其他路径 HTTP401。
关键结论：usercenter 的控制器**不做用户级身份校验**（不读取
accessToken/adminToken/designerToken，控制器内也不取执行用户）。其访问控制完全依赖**网络层隔离与系统间systemToken——这与其作为「内部数据面服务」的定位一致，终端用户**不直接访问 usercenter 接口，所有调用均来自可信内部服务经 Feign 触发。将 usercenter 暴露到公网而无前置网关/防火墙保护属严重配置错误。
完整鉴权机制与错误码说明见：顶层 index.md。
统一响应结构¶
usercenter 模块的控制器不使用顶层 index.md 描述的统一 Resource 结构（{errcode,errmsg,data,errors}）。控制器方法返回类型直接序列化为 JSON：
- 返回
void的方法（创建/更新/删除/批量/状态变更等）成功时**响应体为空**（HTTP 200）。 - 返回领域对象/集合/包装类型的方法（
UserPO、Collection<UserPO>、DataPackage<UserPO>、int、Collection<String>、List<String>、Collection<UserDepartmentRoleSet>等）成功时**直接序列化对象**，不包裹errcode/errmsg/data/errors。 - 异常由
CommonsExceptionResolver（obpm-common）统一渲染为 HTTP500，响应体仅含两字段：{"errcode":500,"errmsg":"<异常信息>"}（OBPMValidateException取getValidateMessage()，其余取e.getMessage()，空消息时取「系统异常，请联系管理员！」）。
各控制器文档的「响应」小节会再次说明此约定。
错误码补充¶
usercenter 模块未引入专属业务错误码。鉴权层与异常层引入以下与统一 Resource 不同的纯 HTTP 状态码 / 简化 JSON 体：
| errcode | HTTP | 含义 |
|---|---|---|
| 500 | 500 | 业务/系统异常（CommonsExceptionResolver 渲染，响应体 {"errcode":500,"errmsg":"<异常信息>"}，仅两字段）。注：OBPMValidateException 的 errmsg 取 getValidateMessage()（如 {*[core.superuser.referenced]*} 占位符串，未做 i18n 解析）。 |
| 405 | 405 | HTTP 方法不被允许（CommonSecurityFilter 拦截，仅允许 GET/POST/HEAD/OPTIONS；针对未携带 systemToken 的 PUT/DELETE/PATCH 等请求，返回 HTML 错误页，无 JSON 体） |
| 401 | 401 | /actuator/**（非 /actuator/health）访问被拒（CommonSecurityFilter 直接设置状态码，无响应体） |
| 500 | 500 | 系统启动中（CommonSecurityFilter 检测 !Environment.isReady()，返回 HTML 错误页） |
注：控制器方法在事务
try/catch内捕获异常后会回滚事务并throw e重新抛出，最终由CommonsExceptionResolver渲染为 HTTP 500 的简化 JSON 体（响应不含data/errors字段，与统一Resource不同）。
控制器清单¶
usercenter 模块共有约 13 个 *APIController / *ApiController（用户、账户、部门、域、用户组、用户组集合、字段扩展、工作日历、媒体资源、同步日志、自定义用户字段、标准日/特殊日等），已全部覆盖。已文档化端点合计 118。
| 文件 | 中文名 | 基址 | 端点数 |
|---|---|---|---|
user-api.md |
UserAPIController（用户管理 API） | ${myapps.context-path.usercenter:}/user |
32 |
department-api.md |
DepartmentAPIController（部门管理 API） | ${myapps.context-path.usercenter:}/department |
19 |
domain-api.md |
DomainAPIController（域管理 API） | ${myapps.context-path.usercenter:}/domain |
12 |
calendar-api.md |
CalendarAPIController（日历管理 API） | ${myapps.context-path.usercenter:}/calendar |
11 |
field-extends-api.md |
FieldExtendsAPIController（字段扩展管理 API） | ${myapps.context-path.usercenter:}/fieldextends |
10 |
user-group-set-api.md |
UserGroupSetAPIController（用户组集合管理 API） | ${myapps.context-path.usercenter:}/usergroupset |
6 |
user-group-api.md |
UserGroupAPIController（用户组管理 API） | ${myapps.context-path.usercenter:}/usergroup |
6 |
user-defined-api.md |
UserDefinedAPIController（用户自定义 API） | ${myapps.context-path.usercenter:}/userdefined |
5 |
standard-day-api.md |
StandardDayAPIController（标准工作日 API） | ${myapps.context-path.usercenter:}/standardday |
5 |
special-day-api.md |
SpecialDayAPIController（特殊日期 API） | ${myapps.context-path.usercenter:}/specialday |
5 |
media-api.md |
MediaApiController（媒体资源 API） | ${myapps.context-path.usercenter:}/media |
3 |
sync-log-api.md |
SyncLogAPIController（同步日志 API） | ${myapps.context-path.usercenter:}/SyncLogPO |
3 |
account-api.md |
AccountAPIController（账户 API） | ${myapps.context-path.usercenter:}/account |
1 |
覆盖状态¶
usercenter 模块下全部 *APIController / *ApiController（约 13 个、共 118 个端点）已全部覆盖，无待补控制器。