# 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。