PR_Min_APP_V2/openspec/specs/webview-preview/spec.md

webview-preview Specification

Purpose

提供统一 WebView、PDF/文档、图片/影像、EMR HTML 和外部资源安全预览契约，供报告、眼健康档案、个人中心、订单和内容模块复用，避免各业务模块重复实现预览底层或绕过 host 白名单、下载打开和错误兜底规则。

Requirements

Requirement: REQ-COMMON-002-01 COMMON-002 WebView/PDF/外部预览契约

系统 MUST 按 PRI-MP-COMMON-002 上下文包、功能点专项矩阵和集成队列裁定口径实现本模块能力，并保留跨模块契约、真实接口边界和人工联调边界。

• 历史追溯：本模块最初从 develop@9a529fc 的 feature/PRI-MP-COMMON-002-webview-preview 分支开发；该记录不构成当前业务或验收要求。
• MUST：覆盖当前模块功能点专项矩阵，并对每个功能点给出已实现、暂缓、划归其他模块、待确认或不属于本模块的结论。
• MUST：记录契约与依赖闭环，未完成依赖必须使用待开放、禁用态或安全兜底。
• MUST：自检报告包含新版设计基线、旧源码功能基线、视觉布局基线、真实接口与禁止模拟业务数据检查。
• MUST：提交待集成时列出共享文件清单、固定检查结果和人工联调项。
• MUST NOT：子 Agent 自行合并或推送 develop。
• MUST NOT：使用 mock、本地假接口、硬编码业务返回或静态业务数据替代真实接口。
• MUST NOT：主动触发真实支付、医保、退款、订单创建、预约提交、实名/OCR/人脸、IM/TRTC 等高风险真实动作；涉及本模块的真实动作必须列为人工联调。

Scenario: 模块提交待集成

• Given PRI-MP-COMMON-002 模块开发完成
• When 子 Agent 提交待集成材料
• Then OpenSpec strict、功能点矩阵闭环、契约与依赖闭环、共享文件清单、禁止 mock/硬编码扫描、人工联调项和固定检查结果 MUST 齐全。

Requirement: REQ-COMMON-002-02 安全 WebView 打开

系统 MUST 提供统一 WebView 页面和安全 URL 校验。

• MUST：注册 pages/common/webview/webview。
• MUST：兼容 query url/title/source 和 eventChannel.openUrl/previewPayload 入参。
• MUST：对 URL 进行 decode、http/https 协议校验和 host 白名单校验。
• MUST：拒绝空 URL、javascript:、file:、data:、非 http/https 和未登记 host。
• MUST：加载中、加载失败、返回、重试状态稳定展示。
• MUST：CONTENT-001 首页科普、科普列表和 EYE-001 眼健康文章外链 MUST 复用该契约。

Scenario: 未登记 host 被拒绝

• Given 调用方传入一个未登记业务域名的 H5 链接
• When WebView 页面加载
• Then 系统 MUST 显示服务暂不可用，不得渲染 web-view。

Requirement: REQ-COMMON-002-03 PDF/文档下载打开

系统 MUST 提供统一文档预览页和下载后打开能力。

• MUST：注册 pages/common/preview/preview。
• MUST：支持 url 直开和 filename/fileName/path 拼接。
• MUST：复原旧 PDF 路径规则：filename 不含 /h 且未声明跳过院区路径时，使用 hisHospID.toLowerCase() 拼接。
• MUST：复用 COMMON-001 utils/resource.downloadFile。
• MUST：处理非 2xx、空 tempFilePath、下载失败、文件类型不支持和 wx.openDocument fail。
• MUST NOT：生成本地假 PDF 或静态文件。

Scenario: hisHospID 缺失

• Given 调用方只传入相对 filename
• And 当前医院态缺少 hisHospID
• When 用户打开文档预览
• Then 系统 MUST 显示文件路径缺失或医院配置缺失错误态，不得拼接空路径。

Requirement: REQ-COMMON-002-04 图片/影像预览

系统 MUST 提供统一图片预览契约。

• MUST：支持 current/url/urls[]。
• MUST：过滤空 URL、异常 URL 和未通过白名单校验的 URL。
• MUST：全部为空时不得调用 wx.previewImage。
• MUST：订单已有发票资源预览 MUST 复用本契约；生成发票不属于本模块。

Scenario: 发票图片预览

• Given 订单存在真实 invoiceUrl
• When 用户点击查看发票
• Then 系统 MUST 进入统一预览契约并调用 wx.previewImage 打开真实资源。

Requirement: REQ-COMMON-002-05 动态路由与跨模块边界

系统 MUST 保留动态路由白名单和跨模块复用边界。

• MUST：新增 common 页面进入 homeRoute 白名单。
• MUST：jumpPages/routePath/sourceUrl 只能解析为已登记小程序路由或安全 WebView。
• MUST：EMR HTML 只提供真实 URL 打开契约，不解析、不伪造病历内容。
• MUST：tempCommon/activityform/routeHospital 旧缺口本模块只承接安全展示壳或划出，不实现业务提交、电子签名、地图真机授权或支付类逻辑。

Scenario: 消息 jumpPages 未命中

• Given 消息 jumpPages 解析后不在小程序白名单
• When 调用方尝试打开
• Then 系统 MUST 显示安全兜底，不得直接透传到 web-view。