feat(worker): watermark versioning with atomic history regeneration

Co-Authored-By: Claude Code <noreply@anthropic.com>

packages/storage/src/index.ts

@@ -9,6 +9,12 @@ export { MinioStorageAdapter } from './minio.adapter';
 export type { MinioStorageConfig } from './minio.adapter';
 export { StorageError, ErrorCodes } from './errors';
 export type { StoragePort, UploadCredential } from './port';
+export {
+  OBJECT_KEY_ROOT,
+  variantsObjectKey,
+  watermarkVariantObjectKey,
+} from './keys';
+export type { PhotoVariantName } from './keys';
 
 /**
  * 从 S3_* 环境变量构造 MinIO/S3 兼容适配器（仓库根 .env 经 dotenv-cli 或

packages/storage/src/keys.ts

@@ -0,0 +1,35 @@
+// packages/storage/src/keys.ts —— 对象键布局的跨服务权威段（P4a Task 3 起）。
+// 此前 OBJECT_KEY_ROOT 在 api uploads/support.ts 与 worker publish.service.ts
+// 各持一份字面量；水印引入第三处消费方（ov 公开侧模式键推导，无任何 DB 行可
+// 依赖），收敛到存储包单一出处，杜绝多环境前缀化时（P5）三处漂移。
+// P1a 单环境（env=dev）硬编码；多环境前缀化属 P5 部署事项。
+
+/** 对象键根（与各 test/reset.ts 的 MinIO 清理前缀一致）。 */
+export const OBJECT_KEY_ROOT = 'photo-live/dev';
+
+/** photo_variants 变体名（与 db-cn photo_variants.variant 取值一致）。 */
+export type PhotoVariantName = 'thumb' | 'browse' | 'watermark';
+
+/** 变体对象键（worker 写入位 / ov 模式键推导位，同一实现）。 */
+export function variantsObjectKey(
+  albumId: string,
+  photoId: string,
+  version: number,
+  variant: PhotoVariantName,
+): string {
+  return `${OBJECT_KEY_ROOT}/albums/${albumId}/variants/${photoId}/${version}/${variant}.jpg`;
+}
+
+/**
+ * 水印变体键的便捷推导（P4a Task 3 ov 侧核心约定）：键由 (albumId, photoId,
+ * configVersion) 确定性构成——ov 副本不逐照片同步变体键，公开侧按相册有效
+ * watermarkConfigVersion 直接推导（对象存在性由 cn 侧有效版本语义保证，见
+ * packages/contracts/src/watermark.ts）。
+ */
+export function watermarkVariantObjectKey(
+  albumId: string,
+  photoId: string,
+  configVersion: number,
+): string {
+  return variantsObjectKey(albumId, photoId, configVersion, 'watermark');
+}