# resource-reuse Specification

## Purpose
沉淀小程序内图片、附件、上传、下载和服务器资源地址的统一契约，兼容旧源码医院资源字段和后续业务模块复用。
## Requirements
### Requirement: REQ-COMMON-001-01 资源地址归一

系统 MUST 提供统一资源地址归一能力，供业务模块生成图片、附件和下载 URL。

- MUST：保留并兼容 `getImageUrl(path)`、`getUploadUrl(options)`、`getDownloadUrl(path, options)`。
- MUST：支持 `http://`、`https://` 绝对地址原样返回。
- MUST：支持 `/` 开头根路径拼接项目 `env.baseHost`。
- MUST：展示图片地址使用项目 `resourceConfig.imageHost/env.baseHost` 兜底，不得误拼到上传返回文件下载目录。
- MUST：上传返回文件下载地址支持按医院 `consultFile/consultFileUpload`、`patientPhotoPath/patientPhotoUpload`、`downLoadUrl/upLoadUrl` 和旧源码默认目录拼接。
- MUST：兼容医院配置中 `upLoadUrl/downLoadUrl/uploadUrl/downloadUrl/patientPhotoUpload/patientPhotoPath/consultFileUpload/consultFile/cosultFile` 字段命名差异。
- MUST：缺少必要路径时返回空字符串或结构化错误，不得拼出 `undefined/null` URL。

#### Scenario: 展示图片相对路径拼接

- Given 传入医院 logo 或医生头像相对路径
- When 调用 `getImageUrl('logo/logo1.png')`
- Then 系统 MUST 返回基于项目图片 host 拼接后的完整 URL。

#### Scenario: 绝对 URL 保持

- Given 传入 `https://example.com/a.png`
- When 调用资源归一方法
- Then 系统 MUST 原样返回该 URL。

### Requirement: REQ-COMMON-001-02 上传 URL 归一

系统 MUST 基于医院配置和项目配置提供上传 URL。

- MUST：咨询类上传优先读取 `consultFileUpload`，其次兼容 `upLoadUrl/uploadUrl`。
- MUST：患者照片类上传优先读取 `patientPhotoUpload`，其次兼容 `upLoadUrl/uploadUrl`。
- MUST：当医院上传地址为相对路径时，按项目 `env.baseHost` 拼接。
- MUST：当医院上传地址缺失时，咨询类使用旧源码默认 `https://np.h03.p0551.com/uploadFile?fileType=consult`，患者照片类使用旧源码默认 `https://np.h03.p0551.com/uploadFile?fileType=picture`。
- MUST：支持调用方显式传入 `url` 覆盖。

#### Scenario: 医院上传地址缺失

- Given `userData.upLoadUrl` 为空
- When 调用 `getUploadUrl()`
- Then 系统 MUST 返回旧源码对应 fileType 的默认上传地址。

### Requirement: REQ-COMMON-001-03 文件上传封装

系统 MUST 提供受控 `wx.uploadFile` 封装。

- MUST：调用方必须传入 `filePath`，否则拒绝并返回结构化错误。
- MUST：支持 `name`，默认值为 `file`。
- MUST：支持 `formData`、`fileType`、`url`、`timeout`。
- MUST：成功后解析服务端 JSON 字符串或对象返回。
- MUST：优先解析旧源码服务端返回的 `filePath`，并归一返回 `raw`、`result`、`filePath`、`fileName`、`url`、`downloadUrl` 等常用字段。
- MUST：失败时返回 `{ type, message, raw }`，覆盖配置缺失、网络失败、业务失败和解析失败。
- MUST NOT：本模块不得主动触发真实敏感文件上传，只提供调用契约。

#### Scenario: 业务模块上传文件

- Given 调用方传入合法 `filePath`
- When `wx.uploadFile` 返回成功且服务端返回文件名
- Then 系统 MUST 解析并返回归一后的文件结果，供调用方自行保存。

### Requirement: REQ-COMMON-001-04 文件下载封装

系统 MUST 提供 `wx.downloadFile` 封装。

- MUST：支持完整 URL、根路径或资源相对路径。
- MUST：下载前使用资源地址归一生成完整 URL。
- MUST：咨询类相对文件名优先拼接 `consultFile/cosultFile/downLoadUrl`，缺失时使用旧源码默认 `https://np.h03.p0551.com/images/consult/`。
- MUST：患者照片类相对文件名优先拼接 `patientPhotoPath/downLoadUrl`，缺失时使用旧源码默认 `https://np.h03.p0551.com/images/picture/`。
- MUST：校验 `statusCode` 在 200-299 范围。
- MUST：成功时返回 `tempFilePath`、`statusCode`、`url` 和原始响应。
- MUST：失败时返回 `{ type, message, raw }`。
- MUST NOT：不自动打开 PDF、WebView 或文件预览，预览归 `PRI-MP-COMMON-002` 或调用方。

#### Scenario: 下载附件

- Given 调用方传入资源相对路径
- When `wx.downloadFile` 成功返回 `tempFilePath`
- Then 系统 MUST 返回临时文件路径和最终下载 URL。

### Requirement: REQ-COMMON-001-05 资源失败兜底

系统 MUST 提供资源加载失败兜底契约。

- MUST：提供可复用的错误归一方法，输出 `type/message/raw`。
- MUST：提供图片错误时可复用的空图或置空策略，避免页面崩溃。
- MUST：调用方可以据此展示模块语义化空态或重试入口。

#### Scenario: 图片加载失败

- Given 图片组件触发 error
- When 调用方使用本模块兜底方法
- Then 系统 MUST 能清空错误图片 URL 或返回可展示兜底状态，不得导致页面异常。

### Requirement: REQ-COMMON-001-06 禁止越界

系统 MUST 保持本模块为公共资源工具模块。

- MUST NOT：新增业务页面或注册业务入口。
- MUST NOT：实现报告、咨询、反馈、订单、实名、人脸、IM/TRTC 的业务提交。
- MUST NOT：调用支付、医保、实名 OCR、人脸识别接口。
- MUST NOT：使用 mock、本地假数据或硬编码业务返回替代真实接口。

#### Scenario: 模块边界检查

- Given 开发完成
- When 进行代码审查
- Then 系统 MUST 只包含公共资源工具和文档/OpenSpec 变更，不得包含具体业务页面实现。