feat(photo): implement photo tag management and update functionality

- Added UpdatePhotoTagsDto for validating photo tag updates.
- Implemented updateAssetTags method in PhotoAssetService to handle tag updates, including validation and error handling.
- Enhanced PhotoController with a new endpoint for updating photo tags.
- Introduced PhotoTagEditorModal for editing tags in the UI, allowing batch updates for selected photos.
- Updated PhotoLibrary components to support tag editing and display changes in the UI.

Signed-off-by: Innei <tukon479@gmail.com>

Author: Innei

be/apps/core/src/modules/content/photo/assets/photo-asset.dto.ts

@@ -0,0 +1,14 @@
+import { createZodDto } from '@afilmory/framework'
+import { z } from 'zod'
+
+const tagSchema = z
+  .string()
+  .trim()
+  .min(1, { message: '标签不能为空' })
+  .max(64, { message: '标签长度不能超过 64 个字符' })
+
+export class UpdatePhotoTagsDto extends createZodDto(
+  z.object({
+    tags: z.array(tagSchema).max(32, { message: '单张照片最多可设置 32 个标签' }),
+  }),
+) {}

be/apps/core/src/modules/content/photo/assets/photo-asset.service.ts

@@ -1,6 +1,7 @@
 import path from 'node:path'
 
 import type { BuilderConfig, PhotoManifestItem, StorageConfig, StorageObject } from '@afilmory/builder'
+import { createStorageKeyNormalizer } from '@afilmory/builder/photo/index.js'
 import {
   DEFAULT_CONTENT_TYPE,
   DEFAULT_DIRECTORY as DEFAULT_THUMBNAIL_DIRECTORY,
@@ -30,6 +31,7 @@ import { injectable } from 'tsyringe'
 
 import { PhotoBuilderService } from '../builder/photo-builder.service'
 import { PhotoStorageService } from '../storage/photo-storage.service'
+import { inferContentTypeFromKey } from './storage.utils'
 
 type PhotoAssetRecord = typeof photoAssets.$inferSelect
 
@@ -1002,6 +1004,136 @@ export class PhotoAssetService {
     return await Promise.resolve(storageManager.generatePublicUrl(storageKey))
   }
 
+  async updateAssetTags(assetId: string, tagsInput: readonly string[]): Promise<PhotoAssetListItem> {
+    const tenant = requireTenantContext()
+    const db = this.dbAccessor.get()
+
+    if (!assetId) {
+      throw new BizException(ErrorCode.COMMON_BAD_REQUEST, { message: '缺少资源 ID' })
+    }
+
+    const record = await db
+      .select()
+      .from(photoAssets)
+      .where(and(eq(photoAssets.tenantId, tenant.tenant.id), eq(photoAssets.id, assetId)))
+      .limit(1)
+      .then((rows) => rows[0])
+
+    if (!record) {
+      throw new BizException(ErrorCode.COMMON_NOT_FOUND, { message: '未找到指定的图片资源' })
+    }
+
+    if (!record.manifest?.data) {
+      throw new BizException(ErrorCode.PHOTO_MANIFEST_GENERATION_FAILED, { message: '该资源缺少有效的清单数据' })
+    }
+
+    if (record.storageProvider === DATABASE_ONLY_PROVIDER) {
+      throw new BizException(ErrorCode.COMMON_BAD_REQUEST, { message: '数据库占位资源不支持修改标签' })
+    }
+
+    const normalizedTags = this.normalizeTagList(tagsInput)
+    const { builderConfig, storageConfig } = await this.photoStorageService.resolveConfigForTenant(tenant.tenant.id)
+    const storageManager = this.createStorageManager(builderConfig, storageConfig)
+
+    const sanitizeKey = this.normalizeKeyPath(record.storageKey)
+    const normalizeStorageKey = createStorageKeyNormalizer(storageConfig)
+    const relativeKey = normalizeStorageKey(sanitizeKey)
+    const fileName = path.basename(relativeKey || sanitizeKey)
+    if (!fileName) {
+      throw new BizException(ErrorCode.COMMON_BAD_REQUEST, { message: '无法解析当前图片文件名' })
+    }
+
+    const prefixSegment = this.extractStoragePrefix(sanitizeKey, relativeKey)
+    const tagDirectory = normalizedTags.length > 0 ? this.joinStorageSegments(...normalizedTags) : null
+    const newRelativeKey = tagDirectory ? `${tagDirectory}/${fileName}` : fileName
+    const normalizedRelativeKey = this.normalizeKeyPath(newRelativeKey)
+    const newStorageKey = prefixSegment
+      ? this.joinStorageSegments(prefixSegment, normalizedRelativeKey)
+      : normalizedRelativeKey
+
+    const manifest = structuredClone(record.manifest)
+    const photoData = manifest.data
+    let storageSnapshot: ReturnType<typeof this.createStorageSnapshot> | null = null
+
+    if (newStorageKey !== record.storageKey) {
+      const moved = this.normalizeStorageObjectKey(
+        await storageManager.moveFile(record.storageKey, newStorageKey, {
+          contentType: inferContentTypeFromKey(newStorageKey),
+        }),
+        newStorageKey,
+      )
+      storageSnapshot = this.createStorageSnapshot(moved)
+      const livePhotoUpdate = await this.relocateLivePhotoVideo(photoData, storageManager, newStorageKey)
+      if (livePhotoUpdate) {
+        photoData.video = {
+          ...photoData.video,
+          type: 'live-photo',
+          videoUrl: livePhotoUpdate.videoUrl,
+          s3Key: livePhotoUpdate.s3Key,
+        }
+      }
+
+      if (storageSnapshot.size !== null) {
+        photoData.size = storageSnapshot.size
+      }
+      if (storageSnapshot.lastModified) {
+        photoData.lastModified = storageSnapshot.lastModified
+      }
+    }
+
+    const originalUrl = await Promise.resolve(storageManager.generatePublicUrl(newStorageKey))
+    photoData.tags = normalizedTags
+    photoData.originalUrl = originalUrl
+    photoData.s3Key = newStorageKey
+
+    const now = new Date().toISOString()
+    const updatePayload: Partial<typeof photoAssets.$inferInsert> = {
+      storageKey: newStorageKey,
+      manifest,
+      updatedAt: now,
+      syncStatus: 'synced',
+    }
+
+    if (storageSnapshot) {
+      updatePayload.size = storageSnapshot.size
+      updatePayload.etag = storageSnapshot.etag
+      updatePayload.lastModified = storageSnapshot.lastModified
+      updatePayload.metadataHash = storageSnapshot.metadataHash
+      updatePayload.syncedAt = now
+    }
+
+    const [saved] = await db
+      .update(photoAssets)
+      .set(updatePayload)
+      .where(and(eq(photoAssets.id, record.id), eq(photoAssets.tenantId, tenant.tenant.id)))
+      .returning()
+
+    if (!saved) {
+      throw new BizException(ErrorCode.COMMON_INTERNAL_SERVER_ERROR, { message: '更新标签失败，请稍后再试' })
+    }
+
+    const publicUrl =
+      saved.storageProvider === DATABASE_ONLY_PROVIDER
+        ? null
+        : await Promise.resolve(storageManager.generatePublicUrl(saved.storageKey))
+
+    await this.emitManifestChanged(tenant.tenant.id)
+
+    return {
+      id: saved.id,
+      photoId: saved.photoId,
+      storageKey: saved.storageKey,
+      storageProvider: saved.storageProvider,
+      manifest: saved.manifest,
+      syncedAt: saved.syncedAt,
+      updatedAt: saved.updatedAt,
+      createdAt: saved.createdAt,
+      publicUrl,
+      size: saved.size ?? null,
+      syncStatus: saved.syncStatus,
+    }
+  }
+
   private createUploadSummary(pendingCount: number, existingRecords: number): DataSyncResultSummary {
     return {
       storageObjects: pendingCount,
@@ -1373,4 +1505,89 @@ export class PhotoAssetService {
     const base = path.basename(value, ext)
     return base.trim().toLowerCase()
   }
+
+  private normalizeTagList(input: readonly string[] | undefined): string[] {
+    if (!Array.isArray(input) || input.length === 0) {
+      return []
+    }
+
+    const seen = new Set<string>()
+    const normalized: string[] = []
+
+    for (const raw of input) {
+      if (typeof raw !== 'string') {
+        continue
+      }
+      const sanitized = raw
+        .replaceAll(/[\\/]+/g, '-')
+        .replaceAll(/\s+/g, ' ')
+        .trim()
+      if (!sanitized || sanitized === '.' || sanitized === '..') {
+        continue
+      }
+      const truncated = sanitized.slice(0, 64)
+      const key = truncated.toLowerCase()
+      if (seen.has(key)) {
+        continue
+      }
+      seen.add(key)
+      normalized.push(truncated)
+      if (normalized.length >= 32) {
+        break
+      }
+    }
+
+    return normalized
+  }
+
+  private extractStoragePrefix(fullKey: string, relativeKey: string): string | null {
+    if (!fullKey || fullKey === relativeKey) {
+      return null
+    }
+
+    const diffLength = fullKey.length - relativeKey.length
+    if (diffLength <= 0) {
+      return null
+    }
+
+    const prefix = fullKey.slice(0, diffLength).replace(/\/+$/, '')
+    return prefix.length > 0 ? prefix : null
+  }
+
+  private async relocateLivePhotoVideo(
+    manifest: PhotoManifestItem,
+    storageManager: StorageManager,
+    newPhotoKey: string,
+  ): Promise<{ s3Key: string; videoUrl: string } | null> {
+    const { video } = manifest
+    if (!video || video.type !== 'live-photo' || !video.s3Key) {
+      return null
+    }
+
+    const normalizedVideoKey = this.normalizeKeyPath(video.s3Key)
+    const { basePath: newPhotoBase } = this.splitStorageKey(newPhotoKey)
+    if (!newPhotoBase) {
+      return null
+    }
+
+    const extension = path.extname(normalizedVideoKey) || '.mov'
+    const nextVideoKey = `${newPhotoBase}${extension}`
+
+    if (nextVideoKey === normalizedVideoKey) {
+      const videoUrl = await Promise.resolve(storageManager.generatePublicUrl(nextVideoKey))
+      return { s3Key: nextVideoKey, videoUrl }
+    }
+
+    const moved = this.normalizeStorageObjectKey(
+      await storageManager.moveFile(normalizedVideoKey, nextVideoKey, {
+        contentType: inferContentTypeFromKey(nextVideoKey),
+      }),
+      nextVideoKey,
+    )
+    const videoUrl = await Promise.resolve(storageManager.generatePublicUrl(moved.key ?? nextVideoKey))
+    return {
+      s3Key: moved.key ?? nextVideoKey,
+      videoUrl,
+    }
+  }
 }

be/apps/core/src/modules/content/photo/assets/photo.controller.ts

@@ -1,11 +1,13 @@
-import { Body, ContextParam, Controller, Delete, Get, Post, Query } from '@afilmory/framework'
+import { Body, ContextParam, Controller, Delete, Get, Param, Patch, Post, Query } from '@afilmory/framework'
 import { BizException, ErrorCode } from 'core/errors'
 import { Roles } from 'core/guards/roles.decorator'
+import { BypassResponseTransform } from 'core/interceptors/response-transform.decorator'
 import type { DataSyncProgressEvent } from 'core/modules/infrastructure/data-sync/data-sync.types'
 import { createProgressSseResponse } from 'core/modules/shared/http/sse'
 import type { Context } from 'hono'
 import { inject } from 'tsyringe'
 
+import { UpdatePhotoTagsDto } from './photo-asset.dto'
 import type { PhotoAssetListItem, PhotoAssetSummary } from './photo-asset.service'
 import { PhotoAssetService } from './photo-asset.service'
 
@@ -20,6 +22,7 @@ export class PhotoController {
   constructor(@inject(PhotoAssetService) private readonly photoAssetService: PhotoAssetService) {}
 
   @Get('assets')
+  @BypassResponseTransform()
   async listAssets(): Promise<PhotoAssetListItem[]> {
     return await this.photoAssetService.listAssets()
   }
@@ -98,4 +101,9 @@ export class PhotoController {
     const url = await this.photoAssetService.generatePublicUrl(key)
     return { url }
   }
+
+  @Patch('assets/:id/tags')
+  async updateAssetTags(@Param('id') id: string, @Body() body: UpdatePhotoTagsDto): Promise<PhotoAssetListItem> {
+    return await this.photoAssetService.updateAssetTags(id, body.tags ?? [])
+  }
 }

be/apps/core/src/modules/content/photo/assets/storage.utils.ts

@@ -0,0 +1,30 @@
+import path from 'node:path'
+
+const MIME_MAP: Record<string, string> = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.jfif': 'image/jpeg',
+  '.pjpeg': 'image/jpeg',
+  '.pjp': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.heic': 'image/heic',
+  '.heif': 'image/heic',
+  '.hif': 'image/heic',
+  '.bmp': 'image/bmp',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+  '.mov': 'video/quicktime',
+  '.qt': 'video/quicktime',
+  '.mp4': 'video/mp4',
+}
+
+export function inferContentTypeFromKey(key: string): string | undefined {
+  const ext = path.extname(key).toLowerCase()
+  if (!ext) {
+    return undefined
+  }
+  return MIME_MAP[ext]
+}