UserDefinedAPIController（用户自定义 API）

用户中心模块的用户自定义域 CRUD/查询控制器，提供用户自定义配置（每用户的个性化首页/布局/样式等定制项）的创建、更新、查找、删除，以及「按用户 ID + 应用 ID 查找该用户的自定义配置」能力。该控制器由 obpm-runtime、obpm-manager、obpm-kms 等宿主服务以 Feign 方式内部调用（UserDefinedAPI 接口），属于后端服务间数据面接口。

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

公共说明

鉴权

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

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

• 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（如 UserDefinedPO），不包裹 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 直接返回）

数据模型：UserDefinedPO

返回的 UserDefinedPO 继承自 AuthtimeValueObject，表示一条用户自定义配置记录（用户个性化的首页布局、模板、风格、汇总项等）。主要字段：id（主键）、name（配置名称）、type（类型）、description（描述）、layoutType（布局类型）、userId（所属用户 ID）、creator（创建者）、applicationid（所属应用 ID）、roleIds/roleNames（角色 ID/名称）、displayTo（对谁可见）、homepageId（首页 ID）、templateStyle/templateElement/templateContext（模板风格/元素/上下文）、style（StyleRepositoryVO 风格对象）、summaryCfgs（Set<SummaryCfgVO> 汇总配置集合）、defineMode（定制模式，常量 REGULAR_MODE=16 常规/CUSTOMIZE_MODE=256 自定义，缺省 REGULAR_MODE）、published（是否发布）、usedDefined（是否已使用自定义，常量 IS_DEFINED=1/ISNOT_DEFINED=0，缺省 ISNOT_DEFINED）、usualStartMenus（常用启动菜单）。

---

1. 创建用户自定义

创建新的用户自定义配置。事务保护：失败回滚。

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

请求参数

参数名	位置	类型	必填	说明
body	body	UserDefinedPO	是	用户自定义配置信息，通常包含 name、userId、applicationid、defineMode 等

请求示例

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

{
  "name": "张三的首页定制",
  "userId": "__v2yGm0001",
  "applicationid": "__APP001",
  "defineMode": 16,
  "published": false
}

响应

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

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

失败示例：

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

---

2. 更新用户自定义

更新现有的用户自定义配置。事务保护：失败回滚。

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

请求参数

参数名	位置	类型	必填	说明
body	body	UserDefinedPO	是	待更新配置（须含主键 id），可携带需更新的字段

请求示例

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

{
  "id": "__UD001",
  "name": "张三的首页定制-new",
  "published": true
}

响应

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

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

失败示例：

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

---

3. 根据 ID 查找用户自定义

根据用户自定义 ID 查找单条配置。

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

请求参数

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

请求示例

GET /usercenter/userdefined/find/__UD001 HTTP/1.1
systemToken: <系统间 JWT>

响应

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

成功示例：

{
  "id": "__UD001",
  "name": "张三的首页定制",
  "userId": "__v2yGm0001",
  "applicationid": "__APP001",
  "defineMode": 16,
  "published": false,
  "usedDefined": 0
}

失败示例：

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

---

4. 根据 ID 删除用户自定义

根据用户自定义 ID 删除配置。事务保护：失败回滚。

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

请求参数

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

请求示例

DELETE /usercenter/userdefined/remove/__UD001 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
• 请求路径：/findMyCustomUserDefined（完整：<host>/usercenter/userdefined/findMyCustomUserDefined）
• 鉴权：内部
• Tag：用户自定义 API

请求参数

参数名	位置	类型	必填	说明
userId	query	string	是	用户 ID
applicationId	query	string	否	应用 ID（required=false，缺省由 DAO 决定过滤行为）

请求示例

GET /usercenter/userdefined/findMyCustomUserDefined?userId=__v2yGm0001&applicationId=__APP001 HTTP/1.1
systemToken: <系统间 JWT>

响应

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

成功示例：

{
  "id": "__UD001",
  "name": "张三的首页定制",
  "userId": "__v2yGm0001",
  "applicationid": "__APP001",
  "defineMode": 16,
  "published": false
}

失败示例：

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

---