KFC/tyt-api-nest
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
tyt-api-nest/docs/uploads.md
EL 2bfe8ac8c8 新增上传资产模型与迁移，支持 IMAGE、VIDEO、FILE 三类资产管理 
新增 B 端上传接口与列表接口，统一文件上传和分页查询能力
上传能力支持医院级数据隔离：系统管理员需显式指定医院，院内角色按登录医院自动隔离
图片上传自动压缩并转为 webp，视频上传自动转码并压缩为 mp4，普通文件按原始类型存储
增加上传目录与公开访问能力，统一输出可直接预览的访问地址
前端新增影像库页面，支持按类型筛选、关键字检索、分页浏览、在线预览与原文件访问
前端新增通用上传组件，支持在页面内复用并返回上传结果
管理后台新增影像库菜单与路由，并补充页面级角色权限控制
患者手术相关表单接入上传复用能力，支持术前资料与设备标签上传回填
新增上传模块 e2e 用例，覆盖成功路径、权限矩阵与关键失败场景
补充上传模块文档与安装依赖说明，完善工程内使用说明
2026-03-20 04:35:43 +08:00

2.6 KiB
Raw Blame History

上传资产模块说明（src/uploads）

1. 目标

  • 提供图片、视频、文件的统一上传入口。
  • 为 B 端“影像库/视频库/文件库”页面提供分页查询。
  • 为患者手术表单中的术前资料、植入物标签上传提供复用能力。

2. 数据模型

新增 UploadAsset 表，保存上传文件元数据：

  • hospitalId：医院归属
  • creatorId：上传人
  • type：IMAGE / VIDEO / FILE
  • originalName：原始文件名
  • fileName：服务端生成文件名
  • storagePath：相对存储路径
  • url：公开访问地址，前端直接用于预览
  • mimeType：文件 MIME 类型
  • fileSize：文件大小（字节）

文件本体默认落盘到：

  • 公开目录：storage/uploads
  • 临时目录：storage/tmp-uploads
  • 最终目录规则：storage/uploads/YYYY/MM/DD
  • 最终文件名规则：YYYYMMDDHHmmss-原文件名
    • 图片压缩后扩展名统一为 .webp
    • 视频压缩后扩展名统一为 .mp4
    • 如同一秒内出现同名文件，会自动追加 -1、-2 防止覆盖

3. 接口

  • POST /b/uploads
    • 角色：SYSTEM_ADMIN / HOSPITAL_ADMIN / DIRECTOR / LEADER / DOCTOR
    • 表单字段：
      • file：二进制文件
      • hospitalId：仅 SYSTEM_ADMIN 上传时必填
  • GET /b/uploads
    • 角色：SYSTEM_ADMIN / HOSPITAL_ADMIN
    • 查询参数：
      • keyword
      • type
      • hospitalId：仅 SYSTEM_ADMIN 可选
      • page
      • pageSize

4. 使用说明

  • 患者手术表单中的“术前 CT 影像/资料”支持直接上传，上传成功后自动回填 type/name/url。
  • 设备表单中的“植入物标签”支持直接上传图片，上传成功后自动回填 labelImageUrl。
  • 患者详情页会直接预览术前图片、视频和设备标签。
  • 单独新增“影像库”页面，按图片/视频/文件分页查看所有上传资产。
    • 页面访问权限仅 SYSTEM_ADMIN / HOSPITAL_ADMIN

5. 压缩策略

  • 图片上传后会自动压缩并统一转成 webp：
    • 自动纠正旋转方向
    • 最大边限制为 2560
    • 返回的 mimeType 为 image/webp
  • 视频上传后会自动压缩并统一转成 mp4：
    • 最大边限制为 1280
    • 视频编码为 H.264
    • 音频编码为 AAC
    • 返回的 mimeType 为 video/mp4
  • 普通文件类型不做转码，按原文件保存。
  • 如果本地 pnpm install 屏蔽了依赖安装脚本，ffmpeg-static 二进制不会自动落盘，视频压缩会失败。
    • 这种情况下手动执行：
      • node node_modules/.pnpm/ffmpeg-static@5.3.0/node_modules/ffmpeg-static/install.js