feat: support virtual item detail images and COS access

README.md

@@ -108,13 +108,17 @@ tail -f logs/hera-error.log
 资料查询返回的头像 URL 和文件上传返回的 URL 有效期为 900 秒；过期后重新获取。
 历史 `/uploads/avatars/` 路径继续按原有本地静态资源配置访问，旧文件没有自动迁移。
 
-访问入口默认使用 `http://101.43.139.56/file/access?token=...`，Nginx 保留路径和查询参数
-转发至后端；参考 `deploy/nginx-file.conf.example`。后端校验文件专用短期凭证后，
+访问入口默认使用 `http://101.43.139.56/hera/file/access?token=...`，Nginx 将外部
+`/hera/file/access` 转发至后端 `/file/access`，保留查询参数；参考
+`deploy/nginx-file.conf.example`。不要将携带应用文件凭证的入口直接代理至 COS。后端校验文件专用短期凭证后，
 302 跳转至 COS 官方 HTTPS 签名 URL。入口不要求登录头，必须携带有效文件凭证。
 文件链接属于临时访问凭据，不应写入日志或分享给无权访问的人。
 部署时通过 `HERA_JWT_SECRET` 配置随机签名密钥，并通过 `TENCENT_COS_PUBLIC_BASE_URL`
 配置生产 HTTPS 域名下的 `/file/` 地址。小程序需配置入口和跳转目标的 HTTPS 合法域名。
 当前 HTTP IP 地址供联调使用，不满足正式小程序的 HTTPS 域名要求。
+如果部署环境或私有配置仍将 `TENCENT_COS_PUBLIC_BASE_URL`／`hera.cos.public-base-url`
+设为旧的 `/file/` 地址，需要一并改为 `http://101.43.139.56/hera/file/`，否则会覆盖默认值。
+更新配置并重启服务后，重新获取资料或天宫列表生成新链接；已有缓存链接不会自动改变。
 
 ### COS 验证
 
@@ -178,6 +182,7 @@ tail -f logs/hera-error.log
 - `GET /api/nfc/devices`：本人当前设备。
 - `GET /api/nfc/bindings`：本人绑定与解绑历史。
 - `GET /api/virtual-items`：启用的虚拟物字典，按字典排序。
+- `GET /api/tiangong/items`：本人神仙持有状态、上香计数及展示图片。
 - `GET /api/user/virtual-items`：本人资产，含失效与送神状态。
 - `GET /api/user/virtual-items/{id}`：本人持有关系详情。
 - `PUT /api/user/virtual-items/sort`：`{"ids":[持有关系ID,...]}`，按提交顺序设置排序值。
@@ -186,6 +191,27 @@ tail -f logs/hera-error.log
 - `POST /api/user/virtual-items/transfers`：`{"userVirtualItemId":1,"toUserId":2,"content":"祝福"}`。
 - `GET /api/user/virtual-items/transfers`：本人发出或收到的回向记录。
 
+虚拟物字典与天宫列表均返回 `iconUrl`（列表图标）和 `iconDetailUrl`（神仙详情页大图），
+两种图片独立配置，不互相覆盖。`virtual_item.icon_detail_url` 按现库使用
+`VARCHAR(255) NOT NULL`、无默认值，后台入库和更新字典时必须提供，已有表不由启动流程自动改列。
+私有桶图片与头像一致：数据库保存 `cos://hera/virtual-items/{itemId}/...` 持久标识，
+上述两个业务接口实时返回有效期 900 秒的文件访问入口，不向数据库写入临时签名 URL。
+已有普通 HTTP/HTTPS 图片地址保持原样。文件网关允许签名访问该专用目录，但不将它视为用户个人文件。
+COS 身份需具有该目录下的 `PutObject`、`GetObject` 权限；不改变存储桶私有读权限。
+
+`VirtualItemImageImportTest` 是显式授权才会执行的真实数据导入，默认跳过。
+启用参数为 `-Dhera.virtual-item.image-import=true`，并且必须同时指定
+`hera.import.item-id`、`hera.import.item-name`、`hera.import.icon-path`、`hera.import.detail-path`。
+它校验目标名称、PNG/WebP 文件头与 5MB 大小限制，按 SHA-256 命名对象并验证签名下载内容，
+先在 `target/` 备份旧图片值，再通过旧值条件同时更新两个图片字段；不修改其他字典项。
+`-Dhera.import.inspect-only=true` 只列出 ID 与名称，不上传或写库；新增缺失字典项必须显式设置
+`-Dhera.import.create-if-missing=true`，不允许将已有同名神仙用其他 ID 重复创建。
+批量导入可通过 `-Dhera.import.manifest=/absolute/path/manifest.json` 指定 JSON 数组，
+每项包含 `id`、`name`、`iconPath`、`detailPath`；批次内 ID 和名称不可重复。
+WebP 应在上传前用支持该格式的工具完整解码，核对尺寸、透明通道与压缩质量，
+导入器不会将不支持 WebP 的 JDK ImageIO 当作解码器；原始文件不应被压缩结果覆盖。
+不要在普通构建、CI 或无人审核的自动化中启用此参数。
+
 一个芯片仅允许一个当前用户，一个微信用户可以绑定多个芯片；要求有效账号已绑定微信和手机号。
 重复绑定本人设备只刷新更新时间，不增加绑定次数，也不重复发放资产。
 每台芯片按北京时间自然年最多解绑两次，次数跟随芯片，不因换用户而重置，跨年重新计算。