DomainAPIController（域管理 API）¶

用户中心模块的企业域（Domain）CRUD/查询控制器，提供域的创建、更新、查找、删除，以及按名称、父域、状态、密钥、用户名+域名+扩展字段复合分页查询，模糊名称查询等能力。该控制器由 obpm-runtime、obpm-manager、obpm-kms 等宿主服务以 Feign 方式内部调用（DomainAPI 接口），属于后端服务间数据面接口。

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

公共说明¶

鉴权¶

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

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

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（如 `DomainPO`、`List<DomainPO>`、`Collection<DomainPO>`、`DataPackage<DomainPO>`），不包裹 `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` 直接返回）

数据模型：`DomainPO`¶

返回的 DomainPO 继承自 AuthtimeValueObject，是企业域（租户）的核心配置实体。主要字段包括：

基础：id、name（域名称）、abbreviation（简称）、status（状态，1=有效/0=无效，默认 1）、description（描述）、parents（上级企业域）、defaultCalendar（默认工作日历种类）、skinType（皮肤类型）、systemName（系统名称）、logoUrl（Logo 地址）、serverHost（服务器公网域名）、log（是否启用日志）。
凭证：secret（Open API 调用秘钥）、yunApiKey（云能力中心 API Key）、bindApplicatons（绑定的软件，JSON 字符串）、isOpenThM（三员管理开关）。
邮件：sendHost/sendAddress/sendAccount/sendPassword/ccAddress、fetchServer/fetchServerPort/fetchProtocol/fetchssl、smtpServer/smtpServerPort/smtpAuthenticated/smtpssl、isUseClient/functionDomain/trash/sender/draft/removed。
微信：weixinCorpID/weixinCorpSecret/weixinAgentId/weixinProxyType/weixinToken/weixinEncodingAESKey、weixinQrCodeAgentId/weixinQrCodeSecret/weixinQrCodeCallbackUrl、weixinConfig/weixinConfigJson。
钉钉：dingdingCorpID/dingdingAppSecret/dingdingAppKey/dingdingAgentId/dingdingProxyType/dingdingServerHost/dingdingToken、dingdingQrCodeAppId/dingdingQrCodeAppSecret/dingdingQrCodeCallbackUrl、dingdingConfig/dingdingConfigJson。
飞书：feishuCorpID/feishuAppSecret/feishuAppKey/feishuProxyType/feishuServerHost/feishuToken、feishuConfig/feishuConfigJson。
扩展：field1_{field10（业务扩展字段）、field11}field20（系统扩展字段）、systemModuleConfigs/systemModuleConfigJson（系统模块配置）。

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

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

1. 创建域¶

创建一个新的企业域。事务保护：失败回滚。

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

请求参数¶

参数名	位置	类型	必填	说明
body	body	`DomainPO`	是	域信息，通常包含 `name`、`status`、`description` 等

请求示例¶

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

{
  "name": "obpm",
  "status": 1,
  "description": "默认企业域",
  "systemName": "MyApps 平台"
}

响应¶

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

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

失败示例：

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

2. 更新域¶

更新现有企业域的信息。事务保护：失败回滚。

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

请求参数¶

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

请求示例¶

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

{
  "id": "__DMN001",
  "name": "obpm-new",
  "description": "更新后的描述"
}

响应¶

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

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

失败示例：

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

3. 查找域¶

根据域 ID 查找单个企业域。

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

请求参数¶

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

请求示例¶

GET /usercenter/domain/find/__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

{
  "id": "__DMN001",
  "name": "obpm",
  "status": 1,
  "description": "默认企业域",
  "systemName": "MyApps 平台"
}

失败示例：

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

4. 删除域¶

根据域 ID 删除企业域。事务保护：失败回滚。

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

请求参数¶

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

请求示例¶

DELETE /usercenter/domain/remove/__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

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

失败示例：

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

5. 根据名称获取域¶

通过域名称查询域信息（返回单条）。

接口类型：REST 资源
请求方式：GET
请求路径：/getDomainByName（完整：<host>/usercenter/domain/getDomainByName）
鉴权：内部
Tag：Domain API

请求参数¶

参数名	位置	类型	必填	说明
name	query	string	是	域名称

请求示例¶

GET /usercenter/domain/getDomainByName?name=obpm HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DomainPO 对象 JSON（不包裹 Resource）；未找到时由 DAO 行为决定。

成功示例：

{
  "id": "__DMN001",
  "name": "obpm",
  "status": 1
}

失败示例：

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

6. 查询子域¶

根据父域 ID 查询其下所有子域。

接口类型：REST 资源
请求方式：GET
请求路径：/queryDomainsByParentId（完整：<host>/usercenter/domain/queryDomainsByParentId）
鉴权：内部
Tag：Domain API

请求参数¶

参数名	位置	类型	必填	说明
parentId	query	string	是	父域 ID

请求示例¶

GET /usercenter/domain/queryDomainsByParentId?parentId=__DMN001 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

[
  { "id": "__DMN002", "name": "obpm-子域", "status": 1, "parents": "__DMN001" }
]

失败示例：

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

7. 获取所有域¶

获取系统中所有企业域信息。

接口类型：REST 资源
请求方式：GET
请求路径：/getAllDomain（完整：<host>/usercenter/domain/getAllDomain）
鉴权：内部
Tag：Domain API

请求参数¶

无。

请求示例¶

GET /usercenter/domain/getAllDomain HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

[
  { "id": "__DMN001", "name": "obpm", "status": 1 },
  { "id": "__DMN002", "name": "obpm-子域", "status": 1 }
]

失败示例：

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

8. 根据状态获取域¶

获取指定状态的所有企业域。

接口类型：REST 资源
请求方式：GET
请求路径：/getDomainByStatus（完整：<host>/usercenter/domain/getDomainByStatus）
鉴权：内部
Tag：Domain API

请求参数¶

参数名	位置	类型	必填	说明
status	query	int	是	域状态（`1`=有效，`0`=无效）

请求示例¶

GET /usercenter/domain/getDomainByStatus?status=1 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

[
  { "id": "__DMN001", "name": "obpm", "status": 1 }
]

失败示例：

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

9. 根据状态查询域¶

查询指定状态的所有企业域。与 getDomainByStatus 在控制器层语义等价（均按 status 过滤），底层分别调用 DomainDAO 的 queryDomainsByStatus 与 getDomainByStatus。

接口类型：REST 资源
请求方式：GET
请求路径：/queryDomainsByStatus（完整：<host>/usercenter/domain/queryDomainsByStatus）
鉴权：内部
Tag：Domain API

请求参数¶

参数名	位置	类型	必填	说明
status	query	int	是	域状态（`1`=有效，`0`=无效）

请求示例¶

GET /usercenter/domain/queryDomainsByStatus?status=1 HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

[
  { "id": "__DMN001", "name": "obpm", "status": 1 }
]

失败示例：

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

10. 复合查询域¶

根据用户名、域名（模糊）和扩展字段查询条件分页查询企业域；请求体为扩展字段映射（Map<String, String>），透传至 DAO。

接口类型：REST 资源
请求方式：POST
请求路径：/queryDomainsByUsernameAndDomainNameAndFieldExtends（完整：<host>/usercenter/domain/queryDomainsByUsernameAndDomainNameAndFieldExtends）
鉴权：内部
Tag：Domain API

请求参数¶

参数名	位置	类型	必填	说明
body	body	`Map<String, String>`	是	扩展字段查询条件映射（透传至 DAO）
userName	query	string	是	用户名
domainName	query	string	是	域名称（模糊匹配）
page	query	int	是	页码（1 起）
lines	query	int	是	每页行数

请求示例¶

POST /usercenter/domain/queryDomainsByUsernameAndDomainNameAndFieldExtends?userName=zhangsan&domainName=obpm&page=1&lines=20 HTTP/1.1
Content-Type: application/json
systemToken: <系统间 JWT>

{ "field1": "value1" }

响应¶

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

成功示例：

{
  "datas": [
    { "id": "__DMN001", "name": "obpm", "status": 1 }
  ],
  "rowCount": 1,
  "pageNo": 1,
  "linesPerPage": 20
}

失败示例：

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

11. 简单查询域¶

根据域名称（模糊匹配）查询企业域集合。

接口类型：REST 资源
请求方式：GET
请求路径：/simpleQuery（完整：<host>/usercenter/domain/simpleQuery）
鉴权：内部
Tag：Domain API

请求参数¶

参数名	位置	类型	必填	说明
name	query	string	是	域名称（模糊匹配）

请求示例¶

GET /usercenter/domain/simpleQuery?name=obpm HTTP/1.1
systemToken: <系统间 JWT>

响应¶

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

成功示例：

[
  { "id": "__DMN001", "name": "obpm", "status": 1 }
]

失败示例：

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

12. 根据密钥获取域¶

通过 Open API 调用秘钥（secret）查询对应的企业域信息。

接口类型：REST 资源
请求方式：GET
请求路径：/getDomainBySecret（完整：<host>/usercenter/domain/getDomainBySecret）
鉴权：内部
Tag：Domain API

请求参数¶

参数名	位置	类型	必填	说明
secret	query	string	是	Open API 调用秘钥

请求示例¶

GET /usercenter/domain/getDomainBySecret?secret=<密钥字符串> HTTP/1.1
systemToken: <系统间 JWT>

响应¶

结构：成功为 DomainPO 对象 JSON（不包裹 Resource）；未找到时由 DAO 行为决定。

成功示例：

{
  "id": "__DMN001",
  "name": "obpm",
  "status": 1,
  "secret": "<密钥字符串>"
}

失败示例：

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

DomainAPIController（域管理 API）¶

公共说明¶

鉴权¶

响应结构¶

数据模型：DomainPO¶

分页结构：DataPackage<DomainPO>¶

1. 创建域¶

请求参数¶

请求示例¶

响应¶

2. 更新域¶

请求参数¶

请求示例¶

响应¶

3. 查找域¶

请求参数¶

请求示例¶

响应¶

4. 删除域¶

请求参数¶

请求示例¶

响应¶

5. 根据名称获取域¶

请求参数¶

请求示例¶

响应¶

6. 查询子域¶

请求参数¶

请求示例¶

响应¶

7. 获取所有域¶

请求参数¶

请求示例¶

响应¶

8. 根据状态获取域¶

请求参数¶

请求示例¶

响应¶

9. 根据状态查询域¶

请求参数¶

请求示例¶

响应¶

10. 复合查询域¶

请求参数¶

请求示例¶

响应¶

11. 简单查询域¶

请求参数¶

请求示例¶

响应¶

12. 根据密钥获取域¶

请求参数¶

请求示例¶

响应¶

数据模型：`DomainPO`¶

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