Converter 模块 API

Converter 模块是 MyApps 平台的**文件格式转换服务**（obpm-converter），提供 HTML 转 PDF、Office 文档套红、文件格式转换目标类型查询、转换后文件下载与预览能力（含 KMS 与 runtime 两个下载入口）。该模块的 context-path 占位符为 ${myapps.context-path.converter:}（部署时替换为具体上下文路径，缺省为空；lite 统一打包下为 /，此时模块路径前缀多一层 /converter）。

注：本仓库根 docs/restful-api/index.md「服务与基址」表暂未单独列出 converter 行；模块无独立 application*.yml 公开源码（端口由部署侧 server.port 决定）。本模块路径前缀与 URL 模式均以源码为准。

覆盖进度：2 / 2 控制器（已覆盖 ConverterController、PreviewDownloadController）

Converter 模块共有 2 个有端点的控制器，合计 6 个端点（转换 3 + 预览下载 3）。

已文档化控制器

文件	中文名	基址	端点数
converter.md	ConverterController（文档转换）	${myapps.context-path.converter:}	3
preview-download.md	PreviewDownloadController（预览/下载）	${myapps.context-path.converter:}	3

鉴权说明

（据源码）converter 模块**不使用 Spring Security**（全模块无 org.springframework.security 引用），不注册任何 Servlet Filter 或 HandlerInterceptor 做鉴权（ConverterMvcConfig 仅 implements WebMvcConfigurer，未重写任何方法、未注册 Bean）。访问控制完全依赖 obpm-common 提供的共享前置过滤器：

• PassFilter（obpm-common CommWebMvcConfig.filterRegistrationBeanPassFilter1，order=HIGHEST_PRECEDENCE）：命中白名单 URL（模块首页、/health、/actuator/health、静态资源后缀 .jpg .js .css .ico .png .gif .html .json .map .woff2 .woff .ttf .eot .svg .mpg .mp4 .mp3 .wav .avi .flv .m3u8 .m3 .ts、magic-api 等）即标记 request.setAttribute("pass", true) 放行。
• CommonSecurityFilter（obpm-common CommWebMvcConfig.filterRegistrationBeanCommonSecurityFilter1，URL 模式 /*，order=-1）：所有模块共享，行为如下——
• 携带合法 systemToken 请求头（系统间 Feign 调用，JWT 内 username 固定为 systemToken）→ 标记 pass=true 放行；
• 仅允许 GET/POST/HEAD/OPTIONS 方法，其他方法返回 HTTP 405（HTML 错误页）；OPTIONS 为浏览器 CORS 预检放行；
• Environment.isReady() 为 false 时返回 HTTP 500，响应体「系统正在启动中，请稍后再试！」；
• /v3/api-docs、/swagger-ui、/druid 须持有效 designerToken 或 adminToken；/actuator/health 放开；其余 /actuator/** 返回 401（无响应体）；
• 其他请求直接 chain.doFilter，不校验业务 accessToken。

converter 模块所有端点（/api/convert/htmlToPdf、/api/files/cover、/api/file/target_type、/api/preview/isFileExisted、/api/kms/converted/download、/api/runtime/converted/download）均不在 PassFilter 白名单内，但因 CommonSecurityFilter 不做 token 校验，实际可匿名访问。

控制器内对用户身份的使用

PreviewDownloadController.getUserId(HttpServletRequest) 通过 Security.getUserIdFromToken(request) 解析 accessToken 取 userId，用作 DesUtil.decryptTextByUserId(filepath, userId) 的密钥派生参数；若未携带 token，userId 为 null，解密失败将抛异常被 catch 吞掉，最终响应可能为空或带 HTML 错误文本。ConverterController 完全不引用用户身份。

完整鉴权机制与错误码说明见：顶层 index.md。

响应结构与错误码

converter 模块控制器返回**多种响应形态**，均不采用顶层统一 Resource：

形态一：纯字符串（ConverterController）

coverHtmlFile、coverFile、covertTargetFileType 通过 @ResponseBody 返回字符串：

• 成功："ok"（coverHtmlFile、coverFile）、目标文件扩展名字符串如 "pdf"（covertTargetFileType）；
• 失败：异常 e.getMessage()（直接返回错误文本，HTTP 状态仍 200）。

形态二：Resource（PreviewDownloadController.isFileExisted）

仅 isFileExisted 使用统一 Resource，与顶层 index.md「统一响应结构」一致。注意该端点 errcode 取值非标准：

errcode	含义
200	文件存在
500	编码类型错误 / 文件路径或类型不合法 / 文件不存在

形态三：二进制流 / 文本错误（PreviewDownloadController 下载类）

doFileDownload、doRuntimePreviewFileDownload 直接操作 HttpServletResponse：

• 成功：Content-Type 由 FileUtil.getMimeType(realFilePath) 推断（如 application/pdf），响应体为文件字节流；
• 失败：通过 response.getWriter().print(...) 写入纯文本错误（"Error: file path illegal!"、"找不到指定文件"），HTTP 状态仍 200。

错误码补充

converter 模块**未引入模块专属业务错误码**。鉴权 / 启动层引入以下与统一 Resource 不同的纯 HTTP 状态码：

errcode / HTTP	HTTP	含义
405	405	HTTP 方法不被允许（由 CommonSecurityFilter 拦截，仅允许 GET/POST/HEAD/OPTIONS，返回 HTML 错误页）
500	500	系统正在启动中（由 CommonSecurityFilter 在 Environment.isReady() 为 false 时返回，HTML 错误页）
500	200	isFileExisted 业务失败（编码错误、路径非法、文件不存在），包在 Resource 中
200	200	isFileExisted 文件存在

覆盖说明

本阶段覆盖 obpm-converter 工作树下的 ConverterController（文档转换，3 个端点，含 HTML 转 PDF、Office 套红、查询转换目标类型）、PreviewDownloadController（预览/下载，3 个端点，含文件存在性校验、KMS 转换文件下载、runtime 预览格式下载；后两者为二进制流响应）。converter 模块有端点控制器已**全部覆盖**。

---