MediaApiController（媒体资源 API）

用户中心模块的媒体资源控制器，提供媒体文件（图片、语音、视频、普通文件）元数据记录的创建、删除与按域/类型列表查询能力。该控制器由宿主服务以 Feign 方式内部调用（MediaApi 接口），用于维护用户中心内附件/素材资源的元信息索引，属于后端服务间数据面接口。

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

公共说明

鉴权

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

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

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

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

响应结构

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

情形	HTTP 状态	响应体
返回值为 void 的方法（创建/删除）成功	200	空响应体
返回值为集合的方法（list）成功	200	直接序列化的 Collection<MediaPO> JSON 数组，不包裹 errcode/errmsg/data/errors
业务/系统异常	500	{"errcode":500,"errmsg":"<异常信息>"}（由 obpm-common 的 CommonsExceptionResolver 全局异常处理器渲染，仅含 errcode/errmsg 两字段，无 data/errors）
HTTP 方法不被允许（无 systemToken 的 DELETE）	405	HTML 错误页（由 CommonSecurityFilter 直接返回）
系统启动中	500	HTML 错误页（由 CommonSecurityFilter 直接返回）

事务说明：create 与 remove 在控制器层**显式**包裹 HibernateBaseDAO.beginTransaction() / commitTransaction()，并在捕获异常时 rollbackTransaction() 后重新抛出，事务边界明确。list 为纯查询，无显式事务。

数据模型：MediaPO

cn.myapps.usercenter.dao.media.MediaPO 继承自 AuthtimeValueObject，表示一条媒体资源元数据记录。主要字段：type（媒体文件类型，image=图片 / voice=语音 / video=视频 / file=普通文件）、createDate（上传时间，@JsonFormat(pattern="yyyy-MM-dd HH:mm:ss", timezone="GMT+8")）、name（文件名称）、mediaid（媒体文件 ID，对应外部存储如微信/钉钉素材库的 media_id）、size（文件大小，long，单位字节），以及来自父类的 id 等通用字段。

---

1. 删除媒体

根据 ID 删除指定的媒体资源元数据记录。事务保护：失败回滚（控制器层显式 beginTransaction/commitTransaction/rollbackTransaction）。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	媒体资源 ID

请求示例

DELETE /usercenter/media/remove/__MED001 HTTP/1.1
systemToken: <系统间 JWT>

响应

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

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

失败示例：

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

---

2. 创建媒体

创建新的媒体资源元数据记录。事务保护：失败回滚（控制器层显式 beginTransaction/commitTransaction/rollbackTransaction）。

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

请求参数

参数名	位置	类型	必填	说明
body	body	MediaPO	是	媒体资源对象，通常包含 type、name、mediaid、size、createDate 等字段

请求示例

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

{
  "type": "image",
  "name": "avatar.png",
  "mediaid": "__WX_MEDIA_001",
  "size": 102400,
  "createDate": "2026-08-04 10:00:00"
}

响应

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

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

失败示例：

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

---

3. 获取媒体列表

根据域 ID 和媒体类型获取媒体资源列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/list（完整：<host>/usercenter/media/list）
• 鉴权：内部
• Tag：媒体管理接口

请求参数

参数名	位置	类型	必填	说明
domainid	query	string	是	域 ID
type	query	string	否	媒体类型（image/voice/video/file；缺省时不按类型过滤）

请求示例

GET /usercenter/media/list?domainid=__DMN001&type=image HTTP/1.1
systemToken: <系统间 JWT>

响应

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

成功示例：

[
  {
    "id": "__MED001",
    "type": "image",
    "name": "avatar.png",
    "mediaid": "__WX_MEDIA_001",
    "size": 102400,
    "createDate": "2026-08-04 10:00:00"
  }
]

失败示例：

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

---