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 变更，不得包含具体业务页面实现。

spec.md 5.5 KB Permalink Histórico Raw