hyb-oa/.trellis/tasks/07-27-yang-jun-reimbursement-readiness/research/wecom-native-file-preview.md

企业微信自建应用原生文件预览调研

结论

企业微信自建应用内可以预览 PDF，不应以普通链接在 WebView 中的下载表现判断企业微信是否具备 PDF 预览能力。官方 JS-SDK 提供 ww.previewFile / wx.previewFile，兼容企业微信 iOS、Android，由企业微信原生层下载 URL 对应文件并在内置预览器中打开，官方说明支持图片、音频、视频、文档等格式。

本任务应优先验证并接入企业微信原生 previewFile，而不是先引入 PDF.js 或服务端转图片。PC 普通浏览器继续使用浏览器预览；两端保持“查看原件”业务能力一致，但底层实现按运行环境分流。

官方证据

• 企业微信开发者中心《预览文件》：https://developer.work.weixin.qq.com/document/path/100623
  • 参数为 url、size、name。
  • size 必填且必须准确，否则打开失败。
  • name 应包含正确文件扩展名。
  • 原生层会重新请求文件 URL；iOS WKWebView 中的 Cookie 不会自动带给原生请求。
  • 官方建议资源 cookie-free；需要鉴权时，在 URL 中携带业务侧短时 access token。
• 腾讯企业微信维护的 JS-SDK：https://github.com/TencentWecom/wecom-jssdk
  • npm 包 @wecom/jssdk 的类型定义明确标注 previewFile 兼容 WeCom iOS、Android。
  • SDK 将 previewFile 调用传递给企业微信原生 WeixinJSBridge。
• JS-SDK 总入口：https://developer.work.weixin.qq.com/document/path/90547
  • 自建应用需完成 JS-SDK 注册和当前页面 URL 的 config 签名；官方 SDK README 说明自建应用只需提供 getConfigSignature。

对 hyb-oa 的影响

1. 当前项目没有 JS-SDK ticket/signature 接口，也未引入 @wecom/jssdk，需要补最小自建应用签名链路。
2. 发票已有短时签名文件 URL，可复用其 cookie-free 形态，但报销详情还需返回准确 fileSize 和带扩展名的 originalName。
3. 报销附件当前仅支持带 OA Bearer token 的 Blob 下载；企业微信原生请求不会携带该请求头，需要增加对象级授权后的短时签名 URL，不能改为公开文件。
4. 签名 URL 必须短时、限定文件与申请人、保留实际打开审计；不得把长期 token、Cookie、Secret 或原始企微凭据放入 URL。
5. 移动企微内调用 previewFile；普通 PC 浏览器使用签名 URL 的浏览器预览。非企微移动浏览器可保留明确下载或浏览器预览 fallback。

建议验证顺序

1. 先用不含业务数据的安全 PDF，在生产同域受控页面完成 JS-SDK config + previewFile 技术探针，验证马建勇实际 Android/iOS 企业微信版本。
2. 探针通过后再接发票短时 URL和附件短时 URL，避免拿真实票据做首轮 SDK 调试。
3. 合成数据覆盖：签名 URL 权限、过期/篡改拒绝、准确 size/name、企微原生调用、PC fallback、审批人只读边界。
4. 生产部署后先用安全 PDF 验收，再让经理查看真实报销材料；材料可见前不得审批。

行业实现归纳

企业微信 H5 的常见稳妥实现是“JS-SDK 原生预览 + cookie-free 短时签名 URL + Web fallback”。其关键不在 PDF 渲染库，而在把受保护文件临时转换成原生层可拉取、可过期、可审计的 URL。PDF.js 或服务端转图片适合作为官方原生接口在特定机型失败后的第二级 fallback，不应作为本项目首选路径。