fix: allow legacy clerk album entries

docker/docker-compose-apitest.yml

@@ -1,7 +1,7 @@
 version: "3.9"
 services:
   mysql-apitest:
-    image: mysql:8.0.24
+    image: mysql:8.0
     container_name: peipei-mysql-apitest
     restart: unless-stopped
     environment:
@@ -22,3 +22,11 @@ services:
       interval: 10s
       timeout: 5s
       retries: 10
+
+  redis-apitest:
+    image: redis:7-alpine
+    container_name: peipei-redis-apitest
+    restart: unless-stopped
+    command: ["redis-server", "--appendonly", "no"]
+    ports:
+      - "36379:6379"

media-migration-to-test.md

@@ -0,0 +1,24 @@
+## 媒資/相簿相容性：手動驗證清單
+
+1. **WeChat 店員端 - 個資頁預覽**
+   - 登入店員帳號進入「我的資料」，確認相簿縮圖顯示為合併後的 `mediaList + album`，不應出現重覆 URL。
+   - 點擊「照片」進入管理介面，確認 legacy album 中的圖片仍存在；上傳新媒資後應立即出現於列表。
+
+2. **媒資上傳與排序**
+   - 上傳圖片與影片各一，測試格式/大小超限的錯誤提示與成功上傳後的狀態。
+   - 排序、刪除媒資並提交審核，確認前端列表與預覽更新，且不會重複顯示相同 URL。
+
+3. **後台店員列表**
+   - 在管理端店員列表中，確認每位店員的照片區塊都展示合併後的媒資清單（舊 album + 新媒資）。
+   - 點擊圖片預覽，確認輪播順序正確、無重覆 URL。
+
+4. **後台店員審核詳情**
+   - 查看一筆含多張舊相簿照片的申請，確認圖片區塊已改用 `mediaGallery`，兼容新舊媒資。
+   - 點擊照片預覽，確認圖片來源為合併後的清單。
+
+5. **API 回應驗證**
+   - 呼叫 `/clerk/user/list` 或 WeChat 前端使用的 API，檢查 `album` 欄位仍保留原值，`mediaList` 會包含新媒資並附帶 legacy URL（無重複）。
+   - 若資料仍未遷移，確保 `mediaList` 仍會帶上舊 `album` 的 URL。
+
+6. **媒資審核流程**
+   - 走一次「上傳 → 排序 → 提交 → 審核」流程，確認審核通過後 `mediaList` 只保留 Approved 的媒資，但 `album` 不會被清除，舊客端仍能看到舊資料。

play-admin/src/main/java/com/starry/admin/modules/clerk/enums/ClerkMediaReviewState.java

@@ -0,0 +1,30 @@
+package com.starry.admin.modules.clerk.enums;
+
+import lombok.Getter;
+
+@Getter
+public enum ClerkMediaReviewState {
+
+    DRAFT("draft"),
+    PENDING("pending"),
+    APPROVED("approved"),
+    REJECTED("rejected");
+
+    private final String code;
+
+    ClerkMediaReviewState(String code) {
+        this.code = code;
+    }
+
+    public static ClerkMediaReviewState fromCode(String code) {
+        if (code == null || code.isEmpty()) {
+            return DRAFT;
+        }
+        for (ClerkMediaReviewState state : values()) {
+            if (state.code.equalsIgnoreCase(code) || state.name().equalsIgnoreCase(code)) {
+                return state;
+            }
+        }
+        return DRAFT;
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/clerk/enums/ClerkMediaUsage.java

@@ -0,0 +1,32 @@
+package com.starry.admin.modules.clerk.enums;
+
+import lombok.Getter;
+
+@Getter
+public enum ClerkMediaUsage {
+
+    PROFILE("profile"),
+    AVATAR("avatar"),
+    MOMENTS("moments"),
+    VOICE_INTRO("voice_intro"),
+    PROMO("promo"),
+    OTHER("other");
+
+    private final String code;
+
+    ClerkMediaUsage(String code) {
+        this.code = code;
+    }
+
+    public static ClerkMediaUsage fromCode(String code) {
+        if (code == null || code.isEmpty()) {
+            return PROFILE;
+        }
+        for (ClerkMediaUsage usage : values()) {
+            if (usage.code.equalsIgnoreCase(code) || usage.name().equalsIgnoreCase(code)) {
+                return usage;
+            }
+        }
+        return PROFILE;
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/clerk/mapper/PlayClerkMediaAssetMapper.java

@@ -0,0 +1,8 @@
+package com.starry.admin.modules.clerk.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+
+public interface PlayClerkMediaAssetMapper extends BaseMapper<PlayClerkMediaAssetEntity> {
+
+}

play-admin/src/main/java/com/starry/admin/modules/clerk/mapper/PlayClerkUserInfoMapper.java

@@ -1,7 +1,10 @@
 package com.starry.admin.modules.clerk.mapper;
 
+import com.baomidou.mybatisplus.annotation.InterceptorIgnore;
 import com.github.yulichang.base.MPJBaseMapper;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import java.util.List;
+import org.apache.ibatis.annotations.Select;
 
 /**
  * 店员Mapper接口
@@ -11,4 +14,7 @@ import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
  */
 public interface PlayClerkUserInfoMapper extends MPJBaseMapper<PlayClerkUserInfoEntity> {
 
+    @InterceptorIgnore(tenantLine = "true")
+    @Select("SELECT id, tenant_id, album FROM play_clerk_user_info WHERE deleted = 0 AND album IS NOT NULL")
+    List<PlayClerkUserInfoEntity> selectAllWithAlbumIgnoringTenant();
 }

play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkMediaAssetEntity.java

@@ -0,0 +1,40 @@
+package com.starry.admin.modules.clerk.module.entity;
+
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.starry.common.domain.BaseEntity;
+import java.time.LocalDateTime;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+@Data
+@EqualsAndHashCode(callSuper = false)
+@TableName(value = "play_clerk_media_asset")
+public class PlayClerkMediaAssetEntity extends BaseEntity<PlayClerkMediaAssetEntity> {
+
+    @TableId
+    private String id;
+
+    private String clerkId;
+
+    /**
+     * 租戶 ID，供 TenantLine 過濾
+     */
+    private String tenantId;
+
+    private String mediaId;
+
+    @TableField("`usage`")
+    private String usage;
+
+    private String reviewState;
+
+    private Integer orderIndex;
+
+    private LocalDateTime submittedTime;
+
+    private String reviewRecordId;
+
+    private String note;
+}

play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserReturnVo.java

@@ -3,6 +3,7 @@ package com.starry.admin.modules.clerk.module.entity;
 import com.fasterxml.jackson.annotation.JsonFormat;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.starry.admin.modules.order.module.entity.PlayOrderInfoEntity;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
 import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModelProperty;
 import java.math.BigDecimal;
@@ -94,6 +95,12 @@ public class PlayClerkUserReturnVo {
     @ApiModelProperty(value = "相册列表", notes = "店员相册图片URL列表")
     private List<String> album = new ArrayList<>();
 
+    /**
+     * 媒资列表
+     */
+    @ApiModelProperty(value = "媒资列表", notes = "结构化媒资数据")
+    private List<MediaVo> mediaList = new ArrayList<>();
+
     /**
      * 个性签名
      */

play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewReturnVo.java

@@ -60,6 +60,15 @@ public class PlayClerkDataReviewReturnVo {
     @ApiModelProperty(value = "资料内容", example = "[\"https://example.com/photo1.jpg\"]", notes = "资料内容，根据资料类型有不同格式")
     private List<String> dataContent;
 
+    /**
+     * 媒资对应的视频地址（仅当资料类型为头像/相册且为视频时有值，顺序与 dataContent 一一对应）
+     */
+    @ApiModelProperty(
+            value = "媒资视频地址列表",
+            example = "[\"https://example.com/video1.mp4\"]",
+            notes = "仅当资料类型为头像/相册且为视频时有值，顺序与 dataContent 一一对应")
+    private List<String> mediaVideoUrls;
+
     /**
      * 审核状态（0：未审核:1：审核通过，2：审核不通过）
      */

play-admin/src/main/java/com/starry/admin/modules/clerk/service/IPlayClerkMediaAssetService.java

@@ -0,0 +1,25 @@
+package com.starry.admin.modules.clerk.service;
+
+import com.baomidou.mybatisplus.extension.service.IService;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import java.util.Collection;
+import java.util.List;
+
+public interface IPlayClerkMediaAssetService extends IService<PlayClerkMediaAssetEntity> {
+
+    PlayClerkMediaAssetEntity linkDraftAsset(String tenantId, String clerkId, String mediaId, ClerkMediaUsage usage);
+
+    void submitWithOrder(String clerkId, ClerkMediaUsage usage, List<String> mediaIds);
+
+    void reorder(String clerkId, ClerkMediaUsage usage, List<String> mediaIds);
+
+    void softDelete(String clerkId, String mediaId);
+
+    List<PlayClerkMediaAssetEntity> listByState(String clerkId, ClerkMediaUsage usage, Collection<ClerkMediaReviewState> states);
+
+    List<PlayClerkMediaAssetEntity> listActiveByUsage(String clerkId, ClerkMediaUsage usage);
+
+    void applyReviewDecision(String clerkId, ClerkMediaUsage usage, List<String> approvedValues, String reviewRecordId, String note);
+}

play-admin/src/main/java/com/starry/admin/modules/clerk/service/IPlayClerkUserInfoService.java

@@ -190,6 +190,17 @@ public interface IPlayClerkUserInfoService extends IService<PlayClerkUserInfoEnt
      */
     IPage<PlayClerkUserInfoResultVo> selectPlayClerkUserInfoByPage(PlayClerkUserInfoQueryVo vo);
 
+    /**
+     * 构建面向顾客的店员详情视图对象（包含媒资与兼容相册）。
+     *
+     * @param clerkId
+     *            店员ID
+     * @param customUserId
+     *            顾客ID（可为空，用于标记关注状态）
+     * @return 店员详情视图对象
+     */
+    PlayClerkUserInfoResultVo buildCustomerDetail(String clerkId, String customUserId);
+
     /**
      * 确认店员处于可用状态，否则抛出异常
      *
@@ -252,5 +263,12 @@ public interface IPlayClerkUserInfoService extends IService<PlayClerkUserInfoEnt
 
     List<PlayClerkUserInfoEntity> simpleList();
 
+    /**
+     * 查询存在相册字段数据的店员（忽略租户隔离）
+     *
+     * @return 店员集合
+     */
+    List<PlayClerkUserInfoEntity> listWithAlbumIgnoringTenant();
+
     JSONObject getPcData(PlayClerkUserInfoEntity entity);
 }

play-admin/src/main/java/com/starry/admin/modules/clerk/service/impl/PlayClerkDataReviewInfoServiceImpl.java

@@ -1,5 +1,6 @@
 package com.starry.admin.modules.clerk.service.impl;
 
+import cn.hutool.core.collection.CollectionUtil;
 import cn.hutool.core.util.StrUtil;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
@@ -7,20 +8,33 @@ import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
 import com.github.yulichang.wrapper.MPJLambdaWrapper;
 import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
 import com.starry.admin.modules.clerk.mapper.PlayClerkDataReviewInfoMapper;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkUserReviewInfoEntity;
+import com.starry.admin.modules.clerk.module.enums.ClerkDataType;
 import com.starry.admin.modules.clerk.module.vo.PlayClerkDataReviewQueryVo;
 import com.starry.admin.modules.clerk.module.vo.PlayClerkDataReviewReturnVo;
 import com.starry.admin.modules.clerk.module.vo.PlayClerkDataReviewStateEditVo;
 import com.starry.admin.modules.clerk.service.IPlayClerkDataReviewInfoService;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
 import com.starry.admin.modules.clerk.service.IPlayClerkUserInfoService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaKind;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.enums.MediaStatus;
+import com.starry.admin.modules.media.service.IPlayMediaService;
 import com.starry.common.enums.ClerkReviewState;
 import com.starry.common.utils.IdUtils;
 import java.time.LocalDateTime;
+import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
 import javax.annotation.Resource;
 import org.springframework.stereotype.Service;
 
@@ -42,6 +56,12 @@ public class PlayClerkDataReviewInfoServiceImpl
     @Resource
     private IPlayClerkUserInfoService playClerkUserInfoService;
 
+    @Resource
+    private IPlayClerkMediaAssetService clerkMediaAssetService;
+
+    @Resource
+    private IPlayMediaService mediaService;
+
     /**
      * 查询店员资料审核
      *
@@ -107,8 +127,11 @@ public class PlayClerkDataReviewInfoServiceImpl
             lambdaQueryWrapper.between(PlayClerkDataReviewInfoEntity::getAddTime, vo.getAddTime().get(0),
                     vo.getAddTime().get(1));
         }
-        return this.baseMapper.selectJoinPage(new Page<>(vo.getPageNum(), vo.getPageSize()),
-                PlayClerkDataReviewReturnVo.class, lambdaQueryWrapper);
+        IPage<PlayClerkDataReviewReturnVo> page = this.baseMapper.selectJoinPage(
+                new Page<>(vo.getPageNum(), vo.getPageSize()), PlayClerkDataReviewReturnVo.class,
+                lambdaQueryWrapper);
+        enrichDataContentWithMediaPreview(page);
+        return page;
     }
 
     /**
@@ -129,6 +152,72 @@ public class PlayClerkDataReviewInfoServiceImpl
         return save(playClerkDataReviewInfo);
     }
 
+    /**
+     * 为头像 / 相册审核记录补充可预览的 URL。
+     *
+     * <p>dataContent 中现在可能是媒资 ID（mediaId）或历史 URL，这里做一次向前兼容：
+     * <ul>
+     *   <li>如果是 mediaId，则解析到 play_media 记录，并返回封面或原始 URL；</li>
+     *   <li>如果查不到媒资，则保留原值。</li>
+     * </ul>
+     * 这样 PC 端审核页面始终可以正确预览图片/视频。</p>
+     */
+    private void enrichDataContentWithMediaPreview(IPage<PlayClerkDataReviewReturnVo> page) {
+        if (page == null || page.getRecords() == null || page.getRecords().isEmpty()) {
+            return;
+        }
+        for (PlayClerkDataReviewReturnVo row : page.getRecords()) {
+            ClerkDataType type = row.getDataTypeEnum();
+            if (type == null) {
+                continue;
+            }
+            if (type == ClerkDataType.AVATAR || type == ClerkDataType.PHOTO_ALBUM) {
+                List<String> content = row.getDataContent();
+                if (CollectionUtil.isEmpty(content)) {
+                    continue;
+                }
+                List<String> previewUrls = new ArrayList<>();
+                List<String> videoUrls = new ArrayList<>();
+                for (String value : content) {
+                    if (StrUtil.isBlank(value)) {
+                        continue;
+                    }
+                    MediaPreviewPair pair = resolvePreviewPair(value);
+                    if (pair == null || StrUtil.isBlank(pair.getPreviewUrl())) {
+                        continue;
+                    }
+                    previewUrls.add(pair.getPreviewUrl());
+                    videoUrls.add(pair.getVideoUrl());
+                }
+                row.setDataContent(previewUrls);
+                row.setMediaVideoUrls(videoUrls);
+            }
+        }
+    }
+
+    private MediaPreviewPair resolvePreviewPair(String value) {
+        if (StrUtil.isBlank(value)) {
+            return null;
+        }
+        PlayMediaEntity media = mediaService.getById(value);
+        if (media == null) {
+            MediaPreviewPair fallback = new MediaPreviewPair();
+            fallback.setPreviewUrl(value);
+            fallback.setVideoUrl(null);
+            return fallback;
+        }
+        MediaPreviewPair pair = new MediaPreviewPair();
+        if (MediaKind.VIDEO.getCode().equals(media.getKind())) {
+            String coverUrl = StrUtil.isNotBlank(media.getCoverUrl()) ? media.getCoverUrl() : media.getUrl();
+            pair.setPreviewUrl(coverUrl);
+            pair.setVideoUrl(media.getUrl());
+        } else {
+            pair.setPreviewUrl(media.getUrl());
+            pair.setVideoUrl(null);
+        }
+        return pair;
+    }
+
     @Override
     public void updateDataReviewState(PlayClerkDataReviewStateEditVo vo) {
         PlayClerkDataReviewInfoEntity entity = this.selectPlayClerkDataReviewInfoById(vo.getId());
@@ -147,7 +236,8 @@ public class PlayClerkDataReviewInfoServiceImpl
                 userInfo.setAvatar(entity.getDataContent().get(0));
             }
             if ("2".equals(entity.getDataType())) {
-                userInfo.setAlbum(entity.getDataContent());
+                userInfo.setAlbum(new ArrayList<>());
+                synchronizeApprovedAlbumMedia(entity);
             }
             if ("3".equals(entity.getDataType())) {
                 userInfo.setAudio(entity.getDataContent().get(0));
@@ -159,6 +249,71 @@ public class PlayClerkDataReviewInfoServiceImpl
         }
     }
 
+    private void synchronizeApprovedAlbumMedia(PlayClerkDataReviewInfoEntity reviewInfo) {
+        PlayClerkUserInfoEntity clerkInfo = playClerkUserInfoService.getById(reviewInfo.getClerkId());
+        if (clerkInfo == null) {
+            throw new CustomException("店员信息不存在，无法同步媒资");
+        }
+
+        List<String> rawContent = reviewInfo.getDataContent();
+        List<String> sanitized = CollectionUtil.isEmpty(rawContent)
+                ? Collections.emptyList()
+                : rawContent.stream().filter(StrUtil::isNotBlank).map(String::trim).distinct()
+                        .collect(Collectors.toList());
+
+        List<String> resolvedMediaIds = new ArrayList<>();
+        for (String value : sanitized) {
+            PlayMediaEntity media = resolveMediaEntity(clerkInfo, value);
+            if (media == null) {
+                continue;
+            }
+            clerkMediaAssetService.linkDraftAsset(clerkInfo.getTenantId(), clerkInfo.getId(), media.getId(),
+                    ClerkMediaUsage.PROFILE);
+            resolvedMediaIds.add(media.getId());
+        }
+
+        clerkMediaAssetService.applyReviewDecision(clerkInfo.getId(), ClerkMediaUsage.PROFILE, resolvedMediaIds,
+                reviewInfo.getId(), reviewInfo.getReviewCon());
+    }
+
+    private PlayMediaEntity resolveMediaEntity(PlayClerkUserInfoEntity clerkInfo, String value) {
+        if (StrUtil.isBlank(value)) {
+            return null;
+        }
+        PlayMediaEntity media = mediaService.getById(value);
+        if (media != null) {
+            return media;
+        }
+        media = mediaService.lambdaQuery()
+                .eq(PlayMediaEntity::getOwnerType, MediaOwnerType.CLERK)
+                .eq(PlayMediaEntity::getOwnerId, clerkInfo.getId())
+                .eq(PlayMediaEntity::getUrl, value)
+                .last("limit 1")
+                .one();
+        if (media != null) {
+            return media;
+        }
+        return createMediaFromLegacyUrl(clerkInfo, value);
+    }
+
+    private PlayMediaEntity createMediaFromLegacyUrl(PlayClerkUserInfoEntity clerkInfo, String url) {
+        PlayMediaEntity media = new PlayMediaEntity();
+        media.setId(IdUtils.getUuid());
+        media.setTenantId(clerkInfo.getTenantId());
+        media.setOwnerType(MediaOwnerType.CLERK);
+        media.setOwnerId(clerkInfo.getId());
+        media.setKind(MediaKind.IMAGE.getCode());
+        media.setStatus(MediaStatus.READY.getCode());
+        media.setUrl(url);
+        Map<String, Object> metadata = new HashMap<>();
+        metadata.put("legacySource", "album_review");
+        media.setMetadata(metadata);
+        mediaService.normalizeAndSave(media);
+        media.setStatus(MediaStatus.READY.getCode());
+        mediaService.updateById(media);
+        return media;
+    }
+
     /**
      * 修改店员资料审核
      *
@@ -194,4 +349,28 @@ public class PlayClerkDataReviewInfoServiceImpl
     public int deletePlayClerkDataReviewInfoById(String id) {
         return playClerkDataReviewInfoMapper.deleteById(id);
     }
+
+    /**
+     * 简单的预览地址 / 视频地址对，避免在主体逻辑中使用 Map 或魔法下标。
+     */
+    private static class MediaPreviewPair {
+        private String previewUrl;
+        private String videoUrl;
+
+        String getPreviewUrl() {
+            return previewUrl;
+        }
+
+        void setPreviewUrl(String previewUrl) {
+            this.previewUrl = previewUrl;
+        }
+
+        String getVideoUrl() {
+            return videoUrl;
+        }
+
+        void setVideoUrl(String videoUrl) {
+            this.videoUrl = videoUrl;
+        }
+    }
 }

play-admin/src/main/java/com/starry/admin/modules/clerk/service/impl/PlayClerkMediaAssetServiceImpl.java

@@ -0,0 +1,280 @@
+package com.starry.admin.modules.clerk.service.impl;
+
+import cn.hutool.core.collection.CollectionUtil;
+import cn.hutool.core.util.StrUtil;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.mapper.PlayClerkMediaAssetMapper;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.common.utils.IdUtils;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.stream.Collectors;
+import javax.annotation.Resource;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+public class PlayClerkMediaAssetServiceImpl extends ServiceImpl<PlayClerkMediaAssetMapper, PlayClerkMediaAssetEntity>
+        implements IPlayClerkMediaAssetService {
+
+    @Resource
+    private IPlayMediaService mediaService;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public PlayClerkMediaAssetEntity linkDraftAsset(String tenantId, String clerkId, String mediaId,
+            ClerkMediaUsage usage) {
+        LambdaQueryWrapper<PlayClerkMediaAssetEntity> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PlayClerkMediaAssetEntity::getClerkId, clerkId)
+                .eq(StrUtil.isNotBlank(tenantId), PlayClerkMediaAssetEntity::getTenantId, tenantId)
+                .eq(PlayClerkMediaAssetEntity::getUsage, usage.getCode())
+                .eq(PlayClerkMediaAssetEntity::getMediaId, mediaId);
+        PlayClerkMediaAssetEntity existing = this.getOne(wrapper, false);
+        if (existing != null) {
+            if (StrUtil.isBlank(existing.getTenantId()) && StrUtil.isNotBlank(tenantId)) {
+                existing.setTenantId(tenantId);
+            }
+            if (Boolean.TRUE.equals(existing.getDeleted())) {
+                existing.setDeleted(false);
+            }
+            existing.setReviewState(ClerkMediaReviewState.DRAFT.getCode());
+            if (existing.getOrderIndex() == null) {
+                existing.setOrderIndex(resolveNextOrderIndex(clerkId, usage));
+            }
+            this.updateById(existing);
+            return existing;
+        }
+
+        PlayClerkMediaAssetEntity entity = new PlayClerkMediaAssetEntity();
+        entity.setId(IdUtils.getUuid());
+        entity.setClerkId(clerkId);
+        entity.setTenantId(tenantId);
+        entity.setMediaId(mediaId);
+        entity.setUsage(usage.getCode());
+        entity.setReviewState(ClerkMediaReviewState.DRAFT.getCode());
+        entity.setOrderIndex(resolveNextOrderIndex(clerkId, usage));
+        entity.setDeleted(false);
+        this.save(entity);
+        return entity;
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void submitWithOrder(String clerkId, ClerkMediaUsage usage, List<String> mediaIds) {
+        List<String> ordered = distinctMediaIds(mediaIds);
+        List<PlayClerkMediaAssetEntity> assets = listActiveByUsage(clerkId, usage);
+        if (CollectionUtil.isEmpty(assets)) {
+            return;
+        }
+        Map<String, PlayClerkMediaAssetEntity> assetsByMediaId = assets.stream()
+                .collect(Collectors.toMap(PlayClerkMediaAssetEntity::getMediaId, item -> item));
+        List<PlayClerkMediaAssetEntity> updates = new ArrayList<>();
+        int order = 0;
+        for (String mediaId : ordered) {
+            PlayClerkMediaAssetEntity asset = assetsByMediaId.get(mediaId);
+            if (asset == null) {
+                continue;
+            }
+            asset.setOrderIndex(order++);
+            asset.setReviewState(ClerkMediaReviewState.PENDING.getCode());
+            asset.setSubmittedTime(LocalDateTime.now());
+            updates.add(asset);
+        }
+
+        Set<String> keepSet = ordered.stream().collect(Collectors.toSet());
+        for (PlayClerkMediaAssetEntity asset : assets) {
+            if (!keepSet.contains(asset.getMediaId())) {
+                asset.setReviewState(ClerkMediaReviewState.REJECTED.getCode());
+                asset.setOrderIndex(0);
+                updates.add(asset);
+            }
+        }
+        if (CollectionUtil.isNotEmpty(updates)) {
+            this.updateBatchById(updates);
+        }
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void reorder(String clerkId, ClerkMediaUsage usage, List<String> mediaIds) {
+        List<String> ordered = distinctMediaIds(mediaIds);
+        if (CollectionUtil.isEmpty(ordered)) {
+            return;
+        }
+        List<PlayClerkMediaAssetEntity> assets = listActiveByUsage(clerkId, usage);
+        if (CollectionUtil.isEmpty(assets)) {
+            return;
+        }
+        Map<String, PlayClerkMediaAssetEntity> assetsByMediaId = assets.stream()
+                .collect(Collectors.toMap(PlayClerkMediaAssetEntity::getMediaId, item -> item));
+        List<PlayClerkMediaAssetEntity> updates = new ArrayList<>();
+        int order = 0;
+        for (String mediaId : ordered) {
+            PlayClerkMediaAssetEntity asset = assetsByMediaId.get(mediaId);
+            if (asset == null) {
+                continue;
+            }
+            if (!Objects.equals(asset.getOrderIndex(), order)) {
+                asset.setOrderIndex(order);
+                updates.add(asset);
+            }
+            order++;
+        }
+        if (CollectionUtil.isNotEmpty(updates)) {
+            this.updateBatchById(updates);
+        }
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void softDelete(String clerkId, String mediaId) {
+        LambdaQueryWrapper<PlayClerkMediaAssetEntity> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PlayClerkMediaAssetEntity::getClerkId, clerkId)
+                .eq(PlayClerkMediaAssetEntity::getMediaId, mediaId)
+                .eq(PlayClerkMediaAssetEntity::getDeleted, false);
+        PlayClerkMediaAssetEntity asset = this.getOne(wrapper, false);
+        if (asset == null) {
+            return;
+        }
+        asset.setDeleted(true);
+        asset.setReviewState(ClerkMediaReviewState.REJECTED.getCode());
+        this.updateById(asset);
+    }
+
+    @Override
+    public List<PlayClerkMediaAssetEntity> listByState(String clerkId, ClerkMediaUsage usage,
+            Collection<ClerkMediaReviewState> states) {
+        LambdaQueryWrapper<PlayClerkMediaAssetEntity> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PlayClerkMediaAssetEntity::getClerkId, clerkId)
+                .eq(PlayClerkMediaAssetEntity::getUsage, usage.getCode())
+                .eq(PlayClerkMediaAssetEntity::getDeleted, false)
+                .orderByAsc(PlayClerkMediaAssetEntity::getOrderIndex)
+                .orderByDesc(PlayClerkMediaAssetEntity::getCreatedTime);
+        if (CollectionUtil.isNotEmpty(states)) {
+            wrapper.in(PlayClerkMediaAssetEntity::getReviewState,
+                    states.stream().map(ClerkMediaReviewState::getCode).collect(Collectors.toList()));
+        }
+        return this.list(wrapper);
+    }
+
+    @Override
+    public List<PlayClerkMediaAssetEntity> listActiveByUsage(String clerkId, ClerkMediaUsage usage) {
+        LambdaQueryWrapper<PlayClerkMediaAssetEntity> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PlayClerkMediaAssetEntity::getClerkId, clerkId)
+                .eq(PlayClerkMediaAssetEntity::getUsage, usage.getCode())
+                .eq(PlayClerkMediaAssetEntity::getDeleted, false)
+                .orderByAsc(PlayClerkMediaAssetEntity::getOrderIndex)
+                .orderByDesc(PlayClerkMediaAssetEntity::getCreatedTime);
+        return this.list(wrapper);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void applyReviewDecision(String clerkId, ClerkMediaUsage usage, List<String> approvedValues,
+            String reviewRecordId, String note) {
+        List<PlayClerkMediaAssetEntity> assets = listActiveByUsage(clerkId, usage);
+        if (CollectionUtil.isEmpty(assets)) {
+            return;
+        }
+        List<String> normalized = distinctMediaIds(approvedValues);
+        Map<String, PlayClerkMediaAssetEntity> byMediaId = assets.stream()
+                .collect(Collectors.toMap(PlayClerkMediaAssetEntity::getMediaId, item -> item));
+        Map<String, PlayClerkMediaAssetEntity> byUrl = buildAssetByUrlMap(assets);
+
+        List<PlayClerkMediaAssetEntity> updates = new ArrayList<>();
+        Set<String> approvedAssetIds = new java.util.HashSet<>();
+        int order = 0;
+        for (String value : normalized) {
+            PlayClerkMediaAssetEntity asset = byMediaId.get(value);
+            if (asset == null) {
+                asset = byUrl.get(value);
+            }
+            if (asset == null) {
+                continue;
+            }
+            asset.setReviewState(ClerkMediaReviewState.APPROVED.getCode());
+            asset.setOrderIndex(order++);
+            asset.setReviewRecordId(reviewRecordId);
+            if (StrUtil.isNotBlank(note)) {
+                asset.setNote(note);
+            }
+            updates.add(asset);
+            approvedAssetIds.add(asset.getId());
+        }
+
+        for (PlayClerkMediaAssetEntity asset : assets) {
+            if (approvedAssetIds.contains(asset.getId())) {
+                continue;
+            }
+            asset.setReviewState(ClerkMediaReviewState.REJECTED.getCode());
+            asset.setReviewRecordId(reviewRecordId);
+            updates.add(asset);
+        }
+
+        if (CollectionUtil.isNotEmpty(updates)) {
+            this.updateBatchById(updates);
+        }
+    }
+
+    private int resolveNextOrderIndex(String clerkId, ClerkMediaUsage usage) {
+        LambdaQueryWrapper<PlayClerkMediaAssetEntity> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PlayClerkMediaAssetEntity::getClerkId, clerkId)
+                .eq(PlayClerkMediaAssetEntity::getUsage, usage.getCode())
+                .eq(PlayClerkMediaAssetEntity::getDeleted, false)
+                .orderByDesc(PlayClerkMediaAssetEntity::getOrderIndex)
+                .last("limit 1");
+        PlayClerkMediaAssetEntity last = this.getOne(wrapper, false);
+        if (last == null || last.getOrderIndex() == null) {
+            return 0;
+        }
+        return last.getOrderIndex() + 1;
+    }
+
+    private List<String> distinctMediaIds(List<String> mediaIds) {
+        if (CollectionUtil.isEmpty(mediaIds)) {
+            return Collections.emptyList();
+        }
+        return mediaIds.stream()
+                .filter(StrUtil::isNotBlank)
+                .map(String::trim)
+                .distinct()
+                .collect(Collectors.toList());
+    }
+
+    private Map<String, PlayClerkMediaAssetEntity> buildAssetByUrlMap(List<PlayClerkMediaAssetEntity> assets) {
+        if (CollectionUtil.isEmpty(assets)) {
+            return Collections.emptyMap();
+        }
+        List<String> mediaIds = assets.stream().map(PlayClerkMediaAssetEntity::getMediaId).collect(Collectors.toList());
+        List<PlayMediaEntity> mediaList = mediaService.listByIds(mediaIds);
+        if (CollectionUtil.isEmpty(mediaList)) {
+            return Collections.emptyMap();
+        }
+        Map<String, String> mediaIdToUrl = mediaList.stream()
+                .filter(item -> StrUtil.isNotBlank(item.getUrl()))
+                .collect(Collectors.toMap(PlayMediaEntity::getId, PlayMediaEntity::getUrl, (left, right) -> left));
+        Map<String, PlayClerkMediaAssetEntity> map = new HashMap<>();
+        for (PlayClerkMediaAssetEntity asset : assets) {
+            String url = mediaIdToUrl.get(asset.getMediaId());
+            if (StrUtil.isNotBlank(url)) {
+                map.put(url, asset);
+            }
+        }
+        return map;
+    }
+
+}

play-admin/src/main/java/com/starry/admin/modules/clerk/service/impl/PlayClerkUserInfoServiceImpl.java

@@ -1,5 +1,6 @@
 package com.starry.admin.modules.clerk.service.impl;
 
+import cn.hutool.core.collection.CollectionUtil;
 import cn.hutool.core.util.StrUtil;
 import com.alibaba.fastjson2.JSONObject;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
@@ -12,10 +13,13 @@ import com.github.yulichang.wrapper.MPJLambdaWrapper;
 import com.starry.admin.common.component.JwtToken;
 import com.starry.admin.common.domain.LoginUser;
 import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
 import com.starry.admin.modules.clerk.mapper.PlayClerkUserInfoMapper;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkCommodityEntity;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkLevelInfoEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkUserQueryVo;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkUserReturnVo;
@@ -29,9 +33,13 @@ import com.starry.admin.modules.clerk.module.vo.PlayClerkUnsettledWagesInfoRetur
 import com.starry.admin.modules.clerk.service.IPlayClerkCommodityService;
 import com.starry.admin.modules.clerk.service.IPlayClerkDataReviewInfoService;
 import com.starry.admin.modules.clerk.service.IPlayClerkLevelInfoService;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
 import com.starry.admin.modules.clerk.service.IPlayClerkUserInfoService;
 import com.starry.admin.modules.custom.entity.PlayCustomFollowInfoEntity;
 import com.starry.admin.modules.custom.service.IPlayCustomFollowInfoService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaStatus;
+import com.starry.admin.modules.media.service.IPlayMediaService;
 import com.starry.admin.modules.order.module.entity.PlayOrderInfoEntity;
 import com.starry.admin.modules.order.service.IPlayOrderInfoService;
 import com.starry.admin.modules.personnel.module.entity.PlayPersonnelAdminInfoEntity;
@@ -43,7 +51,9 @@ import com.starry.admin.modules.personnel.service.IPlayPersonnelGroupInfoService
 import com.starry.admin.modules.personnel.service.IPlayPersonnelWaiterInfoService;
 import com.starry.admin.modules.statistics.module.vo.PlayClerkPerformanceInfoQueryVo;
 import com.starry.admin.modules.system.service.LoginService;
+import com.starry.admin.modules.weichat.assembler.ClerkMediaAssembler;
 import com.starry.admin.modules.weichat.entity.PlayClerkUserLoginResponseVo;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
 import com.starry.admin.modules.weichat.entity.clerk.PlayClerkUserInfoQueryVo;
 import com.starry.admin.modules.weichat.entity.clerk.PlayClerkUserInfoResultVo;
 import com.starry.admin.utils.SecurityUtils;
@@ -53,6 +63,7 @@ import com.starry.common.utils.StringUtils;
 import java.math.BigDecimal;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
@@ -86,6 +97,10 @@ public class PlayClerkUserInfoServiceImpl extends ServiceImpl<PlayClerkUserInfoM
     @Resource
     private IPlayCustomFollowInfoService customFollowInfoService;
     @Resource
+    private IPlayClerkMediaAssetService clerkMediaAssetService;
+    @Resource
+    private IPlayMediaService mediaService;
+    @Resource
     private IPlayBalanceDetailsInfoService playBalanceDetailsInfoService;
     @Resource
     private IPlayOrderInfoService playOrderInfoService;
@@ -220,6 +235,9 @@ public class PlayClerkUserInfoServiceImpl extends ServiceImpl<PlayClerkUserInfoM
 
         result.setPcData(this.getPcData(userInfo));
         result.setLevelInfo(playClerkLevelInfoService.selectPlayClerkLevelInfoById(userInfo.getLevelId()));
+        List<MediaVo> mediaList = loadMediaForClerk(userInfo.getId(), true);
+        result.setMediaList(mergeLegacyAlbum(userInfo.getAlbum(), mediaList));
+        result.setAlbum(CollectionUtil.isEmpty(userInfo.getAlbum()) ? new ArrayList<>() : new ArrayList<>(userInfo.getAlbum()));
         return result;
     }
 
@@ -328,27 +346,32 @@ public class PlayClerkUserInfoServiceImpl extends ServiceImpl<PlayClerkUserInfoM
 
         // 排序：非空的等级排序号优先，值越小越靠前；同一排序号在线状态优先
         lambdaQueryWrapper
-                .orderByDesc(PlayClerkUserInfoEntity::getPinToTopState)
                 .orderByDesc(PlayClerkUserInfoEntity::getOnlineState)
+                .orderByDesc(PlayClerkUserInfoEntity::getPinToTopState)
                 .orderByAsc(true, "CASE WHEN t1.order_number IS NULL THEN 1 ELSE 0 END")
                 .orderByAsc(PlayClerkLevelInfoEntity::getOrderNumber)
                 .orderByAsc(PlayClerkUserInfoEntity::getCreatedTime)
+                .orderByAsc(PlayClerkUserInfoEntity::getNickname)
                 .orderByAsc(PlayClerkUserInfoEntity::getId);
 
-        IPage<PlayClerkUserInfoResultVo> rawPage = this.baseMapper.selectJoinPage(page, PlayClerkUserInfoResultVo.class, lambdaQueryWrapper);
-        if (rawPage != null && rawPage.getRecords() != null) {
+        IPage<PlayClerkUserInfoResultVo> pageResult = this.baseMapper.selectJoinPage(page,
+                PlayClerkUserInfoResultVo.class, lambdaQueryWrapper);
+        if (pageResult != null && pageResult.getRecords() != null) {
             List<PlayClerkUserInfoResultVo> deduped = new ArrayList<>();
             Set<String> seen = new HashSet<>();
-            for (PlayClerkUserInfoResultVo record : rawPage.getRecords()) {
+            for (PlayClerkUserInfoResultVo record : pageResult.getRecords()) {
                 String id = record.getId();
                 if (id == null || !seen.add(id)) {
                     continue;
                 }
                 deduped.add(record);
             }
-            rawPage.setRecords(deduped);
+            pageResult.setRecords(deduped);
         }
-        return rawPage;
+        if (pageResult != null) {
+            attachMediaToResultVos(pageResult.getRecords(), false);
+        }
+        return pageResult;
     }
 
     @Override
@@ -500,6 +523,7 @@ public class PlayClerkUserInfoServiceImpl extends ServiceImpl<PlayClerkUserInfoM
             record.setOrderContinueNumber(String.valueOf(orderContinueNumber));
         }
 
+        attachMediaToAdminVos(page.getRecords());
         return page;
     }
 
@@ -524,6 +548,33 @@ public class PlayClerkUserInfoServiceImpl extends ServiceImpl<PlayClerkUserInfoM
         return voPage;
     }
 
+    @Override
+    public PlayClerkUserInfoResultVo buildCustomerDetail(String clerkId, String customUserId) {
+        PlayClerkUserInfoEntity entity = this.baseMapper.selectById(clerkId);
+        if (entity == null) {
+            throw new CustomException("店员不存在");
+        }
+        PlayClerkUserInfoResultVo vo = ConvertUtil.entityToVo(entity, PlayClerkUserInfoResultVo.class);
+        vo.setAddress(entity.getCity());
+        vo.setCommodity(playClerkCommodityService.getClerkCommodityList(vo.getId(), "1"));
+
+        String followState = "0";
+        if (StrUtil.isNotBlank(customUserId)) {
+            LambdaQueryWrapper<PlayCustomFollowInfoEntity> wrapper = new LambdaQueryWrapper<>();
+            wrapper.eq(PlayCustomFollowInfoEntity::getCustomId, customUserId)
+                    .eq(PlayCustomFollowInfoEntity::getClerkId, clerkId);
+            PlayCustomFollowInfoEntity followInfo = customFollowInfoService.getOne(wrapper, false);
+            if (followInfo != null && "1".equals(followInfo.getFollowState())) {
+                followState = "1";
+            }
+        }
+        vo.setFollowState(followState);
+
+        List<MediaVo> mediaList = loadMediaForClerk(clerkId, false);
+        vo.setMediaList(mergeLegacyAlbum(entity.getAlbum(), mediaList));
+        return vo;
+    }
+
     /**
      * 新增店员
      *
@@ -591,6 +642,11 @@ public class PlayClerkUserInfoServiceImpl extends ServiceImpl<PlayClerkUserInfoM
         return this.baseMapper.selectList(lambdaQueryWrapper);
     }
 
+    @Override
+    public List<PlayClerkUserInfoEntity> listWithAlbumIgnoringTenant() {
+        return playClerkUserInfoMapper.selectAllWithAlbumIgnoringTenant();
+    }
+
     @Override
     public JSONObject getPcData(PlayClerkUserInfoEntity entity) {
         JSONObject data = new JSONObject();
@@ -628,4 +684,97 @@ public class PlayClerkUserInfoServiceImpl extends ServiceImpl<PlayClerkUserInfoM
             invalidateClerkSession(beforeUpdate.getId());
         }
     }
+    private void attachMediaToResultVos(List<PlayClerkUserInfoResultVo> records, boolean includePending) {
+        if (CollectionUtil.isEmpty(records)) {
+            return;
+        }
+        Map<String, List<MediaVo>> mediaMap = resolveMediaByAssets(
+                records.stream().map(PlayClerkUserInfoResultVo::getId).collect(Collectors.toList()), includePending);
+        for (PlayClerkUserInfoResultVo record : records) {
+            List<MediaVo> mediaList = new ArrayList<>(mediaMap.getOrDefault(record.getId(), Collections.emptyList()));
+            record.setMediaList(mergeLegacyAlbum(record.getAlbum(), mediaList));
+        }
+    }
+
+    private void attachMediaToAdminVos(List<PlayClerkUserReturnVo> records) {
+        if (CollectionUtil.isEmpty(records)) {
+            return;
+        }
+        Map<String, List<MediaVo>> mediaMap = resolveMediaByAssets(
+                records.stream().map(PlayClerkUserReturnVo::getId).collect(Collectors.toList()), true);
+        for (PlayClerkUserReturnVo record : records) {
+            List<MediaVo> mediaList = new ArrayList<>(mediaMap.getOrDefault(record.getId(), Collections.emptyList()));
+            record.setMediaList(mergeLegacyAlbum(record.getAlbum(), mediaList));
+        }
+    }
+
+    private List<MediaVo> loadMediaForClerk(String clerkId, boolean includePending) {
+        Map<String, List<MediaVo>> mediaMap = resolveMediaByAssets(Collections.singletonList(clerkId), includePending);
+        return new ArrayList<>(mediaMap.getOrDefault(clerkId, Collections.emptyList()));
+    }
+
+    private Map<String, List<MediaVo>> resolveMediaByAssets(List<String> clerkIds, boolean includePending) {
+        if (CollectionUtil.isEmpty(clerkIds)) {
+            return Collections.emptyMap();
+        }
+
+        List<ClerkMediaReviewState> targetStates = includePending
+                ? Arrays.asList(ClerkMediaReviewState.APPROVED, ClerkMediaReviewState.PENDING,
+                        ClerkMediaReviewState.DRAFT, ClerkMediaReviewState.REJECTED)
+                : Collections.singletonList(ClerkMediaReviewState.APPROVED);
+
+        List<PlayClerkMediaAssetEntity> assets = clerkMediaAssetService.lambdaQuery()
+                .in(PlayClerkMediaAssetEntity::getClerkId, clerkIds)
+                .eq(PlayClerkMediaAssetEntity::getUsage, ClerkMediaUsage.PROFILE.getCode())
+                .eq(PlayClerkMediaAssetEntity::getDeleted, false)
+                .in(CollectionUtil.isNotEmpty(targetStates), PlayClerkMediaAssetEntity::getReviewState,
+                        targetStates.stream().map(ClerkMediaReviewState::getCode).collect(Collectors.toList()))
+                .orderByAsc(PlayClerkMediaAssetEntity::getOrderIndex)
+                .orderByDesc(PlayClerkMediaAssetEntity::getCreatedTime)
+                .list();
+        if (CollectionUtil.isEmpty(assets)) {
+            Map<String, List<MediaVo>> empty = new HashMap<>();
+            clerkIds.forEach(id -> empty.put(id, Collections.emptyList()));
+            return empty;
+        }
+
+        List<String> mediaIds = assets.stream().map(PlayClerkMediaAssetEntity::getMediaId).distinct()
+                .collect(Collectors.toList());
+        Map<String, PlayMediaEntity> mediaById = CollectionUtil.isEmpty(mediaIds)
+                ? Collections.emptyMap()
+                : mediaService.listByIds(mediaIds).stream()
+                        .collect(Collectors.toMap(PlayMediaEntity::getId, item -> item, (left, right) -> left));
+
+        Map<String, List<PlayClerkMediaAssetEntity>> groupedAssets = assets.stream()
+                .collect(Collectors.groupingBy(PlayClerkMediaAssetEntity::getClerkId));
+
+        Map<String, List<MediaVo>> result = new HashMap<>(groupedAssets.size());
+        groupedAssets.forEach((clerkId, assetList) -> result.put(clerkId, ClerkMediaAssembler.toVoList(assetList, mediaById)));
+
+        clerkIds.forEach(id -> result.computeIfAbsent(id, key -> Collections.emptyList()));
+        return result;
+    }
+
+    static List<MediaVo> mergeLegacyAlbum(List<String> legacyAlbum, List<MediaVo> destination) {
+        if (CollectionUtil.isEmpty(legacyAlbum)) {
+            return destination;
+        }
+        Set<String> existingUrls = destination.stream()
+                .map(MediaVo::getUrl)
+                .filter(StrUtil::isNotBlank)
+                .collect(Collectors.toSet());
+        for (String url : legacyAlbum) {
+            if (StrUtil.isBlank(url) || !existingUrls.add(url)) {
+                continue;
+            }
+            MediaVo legacyVo = new MediaVo();
+            legacyVo.setId(url);
+            legacyVo.setUrl(url);
+            legacyVo.setUsage(ClerkMediaUsage.PROFILE.getCode());
+            legacyVo.setStatus(MediaStatus.READY.getCode());
+            legacyVo.setReviewState(ClerkMediaReviewState.APPROVED.getCode());
+            destination.add(legacyVo);
+        }
+        return destination;
+    }
 }

play-admin/src/main/java/com/starry/admin/modules/clerk/task/ClerkAlbumMigrationRunner.java

@@ -0,0 +1,132 @@
+package com.starry.admin.modules.clerk.task;
+
+import cn.hutool.core.collection.CollectionUtil;
+import cn.hutool.core.util.StrUtil;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.clerk.service.IPlayClerkUserInfoService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaKind;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.enums.MediaStatus;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.admin.utils.SecurityUtils;
+import com.starry.common.utils.IdUtils;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.stream.Collectors;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.ApplicationArguments;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * 一次性迁移旧相册数据到媒资表。启用方式：启动时配置
+ * {@code clerk.media.migration-enabled=true}。
+ */
+@Component
+@ConditionalOnProperty(prefix = "clerk.media", name = "migration-enabled", havingValue = "true")
+@RequiredArgsConstructor
+@Slf4j
+public class ClerkAlbumMigrationRunner implements ApplicationRunner {
+
+    private final IPlayClerkUserInfoService clerkUserInfoService;
+    private final IPlayMediaService mediaService;
+    private final IPlayClerkMediaAssetService clerkMediaAssetService;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void run(ApplicationArguments args) {
+        log.info("[ClerkAlbumMigration] start migration from legacy album column");
+        List<PlayClerkUserInfoEntity> candidates = clerkUserInfoService.listWithAlbumIgnoringTenant();
+
+        if (CollectionUtil.isEmpty(candidates)) {
+            log.info("[ClerkAlbumMigration] no clerk records with legacy album found, skip");
+            return;
+        }
+
+        AtomicInteger migratedOwners = new AtomicInteger();
+        AtomicInteger migratedMedia = new AtomicInteger();
+        String originalTenantId = SecurityUtils.getTenantId();
+        for (PlayClerkUserInfoEntity clerk : candidates) {
+            String tenantId = StrUtil.blankToDefault(clerk.getTenantId(), originalTenantId);
+            SecurityUtils.setTenantId(tenantId);
+            try {
+                List<String> album = clerk.getAlbum();
+                if (CollectionUtil.isEmpty(album)) {
+                    continue;
+                }
+                List<String> sanitizedAlbum = album.stream()
+                        .filter(StrUtil::isNotBlank)
+                        .map(String::trim)
+                        .distinct()
+                        .collect(Collectors.toList());
+                if (CollectionUtil.isEmpty(sanitizedAlbum)) {
+                    continue;
+                }
+        List<String> approvedMediaIds = new ArrayList<>();
+        for (String value : sanitizedAlbum) {
+            PlayMediaEntity media = resolveMediaEntity(clerk, value);
+            if (media == null) {
+                continue;
+            }
+            media.setStatus(MediaStatus.READY.getCode());
+            mediaService.updateById(media);
+            clerkMediaAssetService.linkDraftAsset(clerk.getTenantId(), clerk.getId(), media.getId(),
+                    ClerkMediaUsage.PROFILE);
+            approvedMediaIds.add(media.getId());
+        }
+
+                clerkMediaAssetService.applyReviewDecision(clerk.getId(), ClerkMediaUsage.PROFILE, approvedMediaIds,
+                        null, null);
+                migratedOwners.incrementAndGet();
+                migratedMedia.addAndGet(approvedMediaIds.size());
+                log.info("[ClerkAlbumMigration] processed {} media for clerk {}", approvedMediaIds.size(),
+                        clerk.getId());
+            } finally {
+                SecurityUtils.setTenantId(originalTenantId);
+            }
+        }
+        log.info("[ClerkAlbumMigration] completed, owners migrated: {}, media migrated: {}", migratedOwners.get(),
+                migratedMedia.get());
+    }
+
+    private PlayMediaEntity resolveMediaEntity(PlayClerkUserInfoEntity clerk, String value) {
+        if (StrUtil.isBlank(value)) {
+            return null;
+        }
+        PlayMediaEntity byId = mediaService.getById(value);
+        if (byId != null) {
+            return byId;
+        }
+        PlayMediaEntity byUrl = mediaService.lambdaQuery()
+                .eq(PlayMediaEntity::getOwnerType, MediaOwnerType.CLERK)
+                .eq(PlayMediaEntity::getOwnerId, clerk.getId())
+                .eq(PlayMediaEntity::getUrl, value)
+                .last("limit 1")
+                .one();
+        if (byUrl != null) {
+            return byUrl;
+        }
+        PlayMediaEntity media = new PlayMediaEntity();
+        media.setId(IdUtils.getUuid());
+        media.setTenantId(clerk.getTenantId());
+        media.setOwnerType(MediaOwnerType.CLERK);
+        media.setOwnerId(clerk.getId());
+        media.setKind(MediaKind.IMAGE.getCode());
+        media.setStatus(MediaStatus.READY.getCode());
+        media.setUrl(value);
+        Map<String, Object> metadata = new HashMap<>();
+        metadata.put("legacySource", "album_migration");
+        media.setMetadata(metadata);
+        mediaService.normalizeAndSave(media);
+        return media;
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/media/entity/PlayMediaEntity.java

@@ -0,0 +1,92 @@
+package com.starry.admin.modules.media.entity;
+
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baomidou.mybatisplus.extension.handlers.JacksonTypeHandler;
+import java.util.Date;
+import java.util.Map;
+import lombok.Data;
+
+/**
+ * 媒资表 play_media
+ *
+ * <p>存储各类业务（店员、顾客等）的图片/视频。</p>
+ */
+@Data
+@TableName(value = "play_media", autoResultMap = true)
+public class PlayMediaEntity {
+
+    @TableId
+    private String id;
+
+    /**
+     * 租户ID
+     */
+    private String tenantId;
+
+    /**
+     * 归属业务类型，例如 clerk/custom/order
+     */
+    private String ownerType;
+
+    /**
+     * 归属业务主键，例如店员ID
+     */
+    private String ownerId;
+
+    /**
+     * 媒资类型 image / video
+     */
+    private String kind;
+
+    /**
+     * 媒资状态 uploaded / processing / ready / approved / rejected
+     */
+    private String status;
+
+    /**
+     * 资源地址
+     */
+    private String url;
+
+    /**
+     * 视频封面地址
+     */
+    private String coverUrl;
+
+    /**
+     * 时长（毫秒）
+     */
+    private Long durationMs;
+
+    /**
+     * 媒资宽度
+     */
+    private Integer width;
+
+    /**
+     * 媒资高度
+     */
+    private Integer height;
+
+    /**
+     * 文件大小（字节）
+     */
+    private Long sizeBytes;
+
+    /**
+     * 排序序号，从 0 开始
+     */
+    private Integer orderIndex;
+
+    /**
+     * 扩展字段
+     */
+    @TableField(typeHandler = JacksonTypeHandler.class)
+    private Map<String, Object> metadata;
+
+    private Date createdTime;
+
+    private Date updatedTime;
+}

play-admin/src/main/java/com/starry/admin/modules/media/enums/MediaKind.java

@@ -0,0 +1,33 @@
+package com.starry.admin.modules.media.enums;
+
+import lombok.Getter;
+
+@Getter
+public enum MediaKind {
+
+    IMAGE("image"),
+    VIDEO("video");
+
+    private final String code;
+
+    MediaKind(String code) {
+        this.code = code;
+    }
+
+    public static boolean isVideo(String value) {
+        return VIDEO.code.equalsIgnoreCase(value);
+    }
+
+    public static boolean isImage(String value) {
+        return IMAGE.code.equalsIgnoreCase(value);
+    }
+
+    public static MediaKind fromCode(String value) {
+        for (MediaKind kind : values()) {
+            if (kind.code.equalsIgnoreCase(value)) {
+                return kind;
+            }
+        }
+        throw new IllegalArgumentException("Unsupported media kind: " + value);
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/media/enums/MediaOwnerType.java

@@ -0,0 +1,9 @@
+package com.starry.admin.modules.media.enums;
+
+public final class MediaOwnerType {
+
+    private MediaOwnerType() {
+    }
+
+    public static final String CLERK = "clerk";
+}

play-admin/src/main/java/com/starry/admin/modules/media/enums/MediaStatus.java

@@ -0,0 +1,22 @@
+package com.starry.admin.modules.media.enums;
+
+import lombok.Getter;
+
+@Getter
+public enum MediaStatus {
+    UPLOADED("uploaded"),
+    PROCESSING("processing"),
+    READY("ready"),
+    APPROVED("approved"),
+    REJECTED("rejected");
+
+    private final String code;
+
+    MediaStatus(String code) {
+        this.code = code;
+    }
+
+    public static boolean isTerminal(String value) {
+        return APPROVED.code.equalsIgnoreCase(value) || REJECTED.code.equalsIgnoreCase(value);
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/media/mapper/PlayMediaMapper.java

@@ -0,0 +1,8 @@
+package com.starry.admin.modules.media.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+
+public interface PlayMediaMapper extends BaseMapper<PlayMediaEntity> {
+
+}

play-admin/src/main/java/com/starry/admin/modules/media/service/IPlayMediaService.java

@@ -0,0 +1,21 @@
+package com.starry.admin.modules.media.service;
+
+import com.baomidou.mybatisplus.extension.service.IService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import java.util.Collection;
+import java.util.List;
+
+public interface IPlayMediaService extends IService<PlayMediaEntity> {
+
+    List<PlayMediaEntity> listByOwner(String ownerType, String ownerId);
+
+    List<PlayMediaEntity> listByOwner(String ownerType, String ownerId, Collection<String> statuses);
+
+    List<PlayMediaEntity> listApprovedByOwner(String ownerType, String ownerId);
+
+    PlayMediaEntity normalizeAndSave(PlayMediaEntity entity);
+
+    void updateOrder(String ownerType, String ownerId, List<String> orderedIds);
+
+    void softDelete(String ownerType, String ownerId, String mediaId);
+}

play-admin/src/main/java/com/starry/admin/modules/media/service/impl/PlayMediaServiceImpl.java

@@ -0,0 +1,136 @@
+package com.starry.admin.modules.media.service.impl;
+
+import cn.hutool.core.collection.CollectionUtil;
+import cn.hutool.core.lang.Assert;
+import cn.hutool.core.util.StrUtil;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.enums.MediaStatus;
+import com.starry.admin.modules.media.mapper.PlayMediaMapper;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import java.util.*;
+import java.util.stream.Collectors;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+public class PlayMediaServiceImpl extends ServiceImpl<PlayMediaMapper, PlayMediaEntity>
+        implements IPlayMediaService {
+
+    @Override
+    public List<PlayMediaEntity> listByOwner(String ownerType, String ownerId) {
+        return listByOwner(ownerType, ownerId, null);
+    }
+
+    @Override
+    public List<PlayMediaEntity> listByOwner(String ownerType, String ownerId, Collection<String> statuses) {
+        LambdaQueryWrapper<PlayMediaEntity> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PlayMediaEntity::getOwnerType, ownerType)
+                .eq(PlayMediaEntity::getOwnerId, ownerId)
+                .orderByAsc(PlayMediaEntity::getOrderIndex)
+                .orderByDesc(PlayMediaEntity::getCreatedTime);
+        if (CollectionUtil.isNotEmpty(statuses)) {
+            wrapper.in(PlayMediaEntity::getStatus, statuses);
+        }
+        return this.list(wrapper);
+    }
+
+    @Override
+    public List<PlayMediaEntity> listApprovedByOwner(String ownerType, String ownerId) {
+        return listByOwner(ownerType, ownerId, Collections.singleton(MediaStatus.READY.getCode()));
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public PlayMediaEntity normalizeAndSave(PlayMediaEntity entity) {
+        Assert.notNull(entity, "媒资信息不能为空");
+        Assert.isTrue(StrUtil.isNotBlank(entity.getOwnerId()), "媒资归属ID不能为空");
+        // ownerType 默认 clerk
+        if (StrUtil.isBlank(entity.getOwnerType())) {
+            entity.setOwnerType(MediaOwnerType.CLERK);
+        }
+        if (entity.getOrderIndex() == null) {
+            entity.setOrderIndex(resolveNextOrderIndex(entity.getOwnerType(), entity.getOwnerId()));
+        }
+        if (StrUtil.isBlank(entity.getStatus())) {
+            entity.setStatus(MediaStatus.UPLOADED.getCode());
+        }
+        boolean saved = this.save(entity);
+        if (!saved) {
+            throw new CustomException("媒资保存失败");
+        }
+        return entity;
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void updateOrder(String ownerType, String ownerId, List<String> orderedIds) {
+        List<PlayMediaEntity> mediaList = listByOwner(ownerType, ownerId);
+        if (CollectionUtil.isEmpty(mediaList)) {
+            return;
+        }
+        Map<String, PlayMediaEntity> mediaById = mediaList.stream()
+                .collect(Collectors.toMap(PlayMediaEntity::getId, item -> item));
+        Set<String> keepSet = new LinkedHashSet<>();
+        if (CollectionUtil.isNotEmpty(orderedIds)) {
+            keepSet.addAll(orderedIds);
+        }
+        List<PlayMediaEntity> updates = new ArrayList<>();
+        int index = 0;
+        for (String mediaId : keepSet) {
+            PlayMediaEntity entity = mediaById.get(mediaId);
+            if (entity == null) {
+                throw new CustomException("媒资不存在或已被删除");
+            }
+            entity.setOrderIndex(index++);
+            if (MediaStatus.REJECTED.getCode().equals(entity.getStatus())) {
+                entity.setStatus(MediaStatus.READY.getCode());
+            }
+            updates.add(entity);
+        }
+        // 其他未保留的标记为 rejected
+        for (PlayMediaEntity entity : mediaList) {
+            if (!keepSet.contains(entity.getId())
+                    && !MediaStatus.REJECTED.getCode().equals(entity.getStatus())) {
+                entity.setStatus(MediaStatus.REJECTED.getCode());
+                entity.setOrderIndex(0);
+                updates.add(entity);
+            }
+        }
+        if (CollectionUtil.isNotEmpty(updates)) {
+            this.updateBatchById(updates);
+        }
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void softDelete(String ownerType, String ownerId, String mediaId) {
+        PlayMediaEntity entity = this.getById(mediaId);
+        if (entity == null) {
+            return;
+        }
+        if (!ownerType.equals(entity.getOwnerType()) || !ownerId.equals(entity.getOwnerId())) {
+            throw new CustomException("无权删除该媒资");
+        }
+        entity.setStatus(MediaStatus.REJECTED.getCode());
+        entity.setOrderIndex(0);
+        this.updateById(entity);
+    }
+
+    private int resolveNextOrderIndex(String ownerType, String ownerId) {
+        LambdaQueryWrapper<PlayMediaEntity> wrapper = new LambdaQueryWrapper<>();
+        wrapper.eq(PlayMediaEntity::getOwnerType, ownerType)
+                .eq(PlayMediaEntity::getOwnerId, ownerId)
+                .ne(PlayMediaEntity::getStatus, MediaStatus.REJECTED.getCode())
+                .orderByDesc(PlayMediaEntity::getOrderIndex)
+                .last("limit 1");
+        PlayMediaEntity last = this.getOne(wrapper, false);
+        if (last == null || last.getOrderIndex() == null) {
+            return 0;
+        }
+        return last.getOrderIndex() + 1;
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/weichat/assembler/ClerkMediaAssembler.java

@@ -0,0 +1,52 @@
+package com.starry.admin.modules.weichat.assembler;
+
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.stream.Collectors;
+
+public final class ClerkMediaAssembler {
+
+    private ClerkMediaAssembler() {
+    }
+
+    public static MediaVo toVo(PlayMediaEntity media, PlayClerkMediaAssetEntity asset) {
+        if (media == null || asset == null || Boolean.TRUE.equals(asset.getDeleted())) {
+            return null;
+        }
+        MediaVo vo = new MediaVo();
+        vo.setId(media.getId());
+        vo.setMediaId(media.getId());
+        vo.setAssetId(asset.getId());
+        vo.setKind(media.getKind());
+        vo.setStatus(media.getStatus());
+        vo.setUrl(media.getUrl());
+        vo.setCoverUrl(media.getCoverUrl());
+        vo.setDurationMs(media.getDurationMs());
+        vo.setWidth(media.getWidth());
+        vo.setHeight(media.getHeight());
+        vo.setSizeBytes(media.getSizeBytes());
+        vo.setOrderIndex(asset.getOrderIndex());
+        vo.setMetadata(media.getMetadata());
+        vo.setUsage(asset.getUsage());
+        vo.setReviewState(asset.getReviewState());
+        vo.setSubmittedTime(asset.getSubmittedTime());
+        vo.setReviewNote(asset.getNote());
+        return vo;
+    }
+
+    public static List<MediaVo> toVoList(List<PlayClerkMediaAssetEntity> assets,
+            Map<String, PlayMediaEntity> mediaById) {
+        if (assets == null || assets.isEmpty()) {
+            return Collections.emptyList();
+        }
+        return assets.stream()
+                .map(asset -> toVo(mediaById.get(asset.getMediaId()), asset))
+                .filter(Objects::nonNull)
+                .collect(Collectors.toList());
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/weichat/assembler/MediaAssembler.java

@@ -0,0 +1,44 @@
+package com.starry.admin.modules.weichat.assembler;
+
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+import java.util.stream.Collectors;
+
+public final class MediaAssembler {
+
+    private MediaAssembler() {
+    }
+
+    public static MediaVo toVo(PlayMediaEntity entity) {
+        if (entity == null) {
+            return null;
+        }
+        MediaVo vo = new MediaVo();
+        vo.setId(entity.getId());
+        vo.setMediaId(entity.getId());
+        vo.setKind(entity.getKind());
+        vo.setStatus(entity.getStatus());
+        vo.setUrl(entity.getUrl());
+        vo.setCoverUrl(entity.getCoverUrl());
+        vo.setDurationMs(entity.getDurationMs());
+        vo.setWidth(entity.getWidth());
+        vo.setHeight(entity.getHeight());
+        vo.setSizeBytes(entity.getSizeBytes());
+        vo.setOrderIndex(entity.getOrderIndex());
+        vo.setMetadata(entity.getMetadata());
+        return vo;
+    }
+
+    public static List<MediaVo> toVoList(List<PlayMediaEntity> entities) {
+        if (entities == null) {
+            return Collections.emptyList();
+        }
+        return entities.stream()
+                .filter(Objects::nonNull)
+                .map(MediaAssembler::toVo)
+                .collect(Collectors.toList());
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkController.java

@@ -6,12 +6,16 @@ import com.baomidou.mybatisplus.core.metadata.IPage;
 import com.starry.admin.common.aspect.ClerkUserLogin;
 import com.starry.admin.common.conf.ThreadLocalRequestDetail;
 import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
 import com.starry.admin.modules.clerk.module.entity.*;
 import com.starry.admin.modules.clerk.module.vo.PlayClerkCommodityEditVo;
 import com.starry.admin.modules.clerk.module.vo.PlayClerkCommodityQueryVo;
 import com.starry.admin.modules.clerk.service.*;
 import com.starry.admin.modules.clerk.service.impl.PlayClerkUserInfoServiceImpl;
 import com.starry.admin.modules.clerk.service.impl.PlayClerkUserReviewInfoServiceImpl;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.service.IPlayMediaService;
 import com.starry.admin.modules.order.module.constant.OrderConstant.OperatorType;
 import com.starry.admin.modules.order.module.entity.PlayOrderInfoEntity;
 import com.starry.admin.modules.order.module.vo.PlayOrderCompleteVo;
@@ -41,6 +45,7 @@ import com.starry.admin.utils.SecurityUtils;
 import com.starry.admin.utils.SmsUtils;
 import com.starry.common.redis.RedisCache;
 import com.starry.common.result.R;
+import com.starry.common.result.TypedR;
 import com.starry.common.utils.ConvertUtil;
 import com.starry.common.utils.StringUtils;
 import com.starry.common.utils.VerificationCodeUtils;
@@ -53,6 +58,7 @@ import java.time.LocalDateTime;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
@@ -120,6 +126,10 @@ public class WxClerkController {
     private SmsUtils smsUtils;
     @Resource
     private WxCustomMpService wxCustomMpService;
+    @Resource
+    private com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService clerkMediaAssetService;
+    @Resource
+    private IPlayMediaService mediaService;
 
     /**
      * 店员获取个人业绩信息
@@ -268,7 +278,7 @@ public class WxClerkController {
         entity.setReviewState("0");
         entity.setDataContent(Collections.singletonList(vo.getNickname()));
         playClerkDataReviewInfoService.create(entity);
-        return R.ok("提交成功，等待审核~");
+        return R.ok().message("提交成功，等待审核~");
     }
 
     @ApiOperation(value = "更新性别", notes = "店员更新性别")
@@ -283,7 +293,7 @@ public class WxClerkController {
         entity.setReviewState("0");
         entity.setDataContent(Collections.singletonList(String.valueOf(vo.getSex())));
         playClerkDataReviewInfoService.create(entity);
-        return R.ok("提交成功，等待审核~");
+        return R.ok().message("提交成功，等待审核~");
     }
 
     @ApiOperation(value = "更新头像", notes = "店员更新头像")
@@ -305,25 +315,138 @@ public class WxClerkController {
         list.add(vo.getAvatar());
         entity.setDataContent(list);
         playClerkDataReviewInfoService.create(entity);
-        return R.ok("提交成功，等待审核~");
+        return R.ok().message("提交成功，等待审核~");
     }
 
     @ClerkUserLogin
     @PostMapping("/user/updateAlbum")
     public R updateAlbum(@Validated @RequestBody PlayClerkUserAlbumVo vo) {
         PlayClerkUserInfoEntity userInfo = ThreadLocalRequestDetail.getClerkUserInfo();
-        // PlayClerkDataReviewInfoEntity entity =
-        // playClerkDataReviewInfoService.queryByClerkId(userInfo.getId(), "2", "0");
-        // if (entity != null) {
-        // throw new CustomException("已有申请未审核");
-        // }
+        List<String> requested = vo.getAlbum() == null ? new ArrayList<>() : vo.getAlbum().stream()
+                .filter(StrUtil::isNotBlank)
+                .map(String::trim)
+                .distinct()
+                .collect(Collectors.toList());
+
+        // 查询当前所有已审核通过的 PROFILE 媒资
+        List<PlayClerkMediaAssetEntity> approvedAssets = clerkMediaAssetService.listByState(
+                userInfo.getId(),
+                ClerkMediaUsage.PROFILE,
+                Collections.singletonList(ClerkMediaReviewState.APPROVED));
+
+        LinkedHashSet<String> requestedSet = new LinkedHashSet<>(requested);
+        if (requestedSet.isEmpty()) {
+            throw new CustomException("最少上传一张照片");
+        }
+
+        // 计算哪些是新媒资（需走审核），哪些是纯删除/排序
+        java.util.Set<String> approvedIds = approvedAssets.stream()
+                .map(PlayClerkMediaAssetEntity::getMediaId)
+                .filter(StrUtil::isNotBlank)
+                .collect(java.util.stream.Collectors.toSet());
+        java.util.Set<String> newMediaIds = requestedSet.stream()
+                .filter(id -> !approvedIds.contains(id))
+                .collect(java.util.stream.Collectors.toSet());
+
+        if (log.isInfoEnabled()) {
+            log.info("[ClerkAlbumUpdate] clerkId={} tenantId={} requestedSet={} approvedIds={} newMediaIds={}",
+                    userInfo.getId(), userInfo.getTenantId(), requestedSet, approvedIds, newMediaIds);
+        }
+
+        if (!newMediaIds.isEmpty()) {
+            // 新增媒资必须是当前店员本人名下、已就绪的媒资，才能进入审核流程
+            java.util.List<com.starry.admin.modules.media.entity.PlayMediaEntity> newMediaEntities =
+                    mediaService.lambdaQuery()
+                            .in(com.starry.admin.modules.media.entity.PlayMediaEntity::getId, newMediaIds)
+                            .list();
+
+            java.util.Set<String> existingMediaIds = newMediaEntities.stream()
+                    .map(com.starry.admin.modules.media.entity.PlayMediaEntity::getId)
+                    .collect(java.util.stream.Collectors.toSet());
+            java.util.Set<String> missingMediaIds = new java.util.HashSet<>(newMediaIds);
+            missingMediaIds.removeAll(existingMediaIds);
+
+            if (!missingMediaIds.isEmpty()) {
+                // 这里很可能是历史相册里的纯 URL（未经过媒资化），我们记录日志但不直接失败，
+                // 在审核内容中仍然保留这些字符串，由审核端用回显逻辑处理。
+                log.warn(
+                        "[ClerkAlbumUpdate] some album entries not found in play_media, treating as legacy values, clerkId={} tenantId={} missingIds={} existingIds={}",
+                        userInfo.getId(),
+                        userInfo.getTenantId(),
+                        missingMediaIds,
+                        existingMediaIds);
+            }
+
+            if (log.isInfoEnabled()) {
+                log.info(
+                        "[ClerkAlbumUpdate] loaded newMediaEntities for validation, clerkId={} tenantId={} mediaSummaries={}",
+                        userInfo.getId(),
+                        userInfo.getTenantId(),
+                        newMediaEntities.stream()
+                                .map(m -> String.format("id=%s,status=%s,ownerType=%s,ownerId=%s,tenantId=%s",
+                                        m.getId(), m.getStatus(), m.getOwnerType(), m.getOwnerId(), m.getTenantId()))
+                                .collect(java.util.stream.Collectors.toList()));
+            }
+
+            for (com.starry.admin.modules.media.entity.PlayMediaEntity media : newMediaEntities) {
+                boolean tenantMatched = userInfo.getTenantId().equals(media.getTenantId());
+                boolean ownerTypeMatched = MediaOwnerType.CLERK.equals(media.getOwnerType());
+                boolean ownerIdMatched = userInfo.getId().equals(media.getOwnerId());
+                boolean statusReady = com.starry.admin.modules.media.enums.MediaStatus.READY.getCode()
+                        .equals(media.getStatus());
+
+                if (!tenantMatched || !ownerTypeMatched || !ownerIdMatched || !statusReady) {
+                    log.warn(
+                            "[ClerkAlbumUpdate] invalid new media for clerk, clerkId={} tenantId={} mediaId={} mediaStatus={} mediaTenantId={} mediaOwnerType={} mediaOwnerId={} tenantMatched={} ownerTypeMatched={} ownerIdMatched={} statusReady={}",
+                            userInfo.getId(),
+                            userInfo.getTenantId(),
+                            media.getId(),
+                            media.getStatus(),
+                            media.getTenantId(),
+                            media.getOwnerType(),
+                            media.getOwnerId(),
+                            tenantMatched,
+                            ownerTypeMatched,
+                            ownerIdMatched,
+                            statusReady);
+                    throw new CustomException("存在无效的照片/视频，请刷新后重试");
+                }
+                if (!statusReady) {
+                    log.warn(
+                            "[ClerkAlbumUpdate] media not in READY state for clerk, clerkId={} tenantId={} mediaId={} mediaStatus={}",
+                            userInfo.getId(),
+                            userInfo.getTenantId(),
+                            media.getId(),
+                            media.getStatus());
+                    throw new CustomException("存在未完成上传的照片/视频，请稍后重试");
+                }
+            }
+
+            // 只要存在新增媒资，则按原有逻辑走资料审核，由审核通过时统一生效
             PlayClerkDataReviewInfoEntity entity = new PlayClerkDataReviewInfoEntity();
             entity.setClerkId(userInfo.getId());
             entity.setDataType("2");
             entity.setReviewState("0");
-        entity.setDataContent(vo.getAlbum());
+            entity.setDataContent(new ArrayList<>(requestedSet));
             playClerkDataReviewInfoService.create(entity);
-        return R.ok("提交成功，等待审核~");
+            return R.ok().message("提交成功，等待审核~");
+        }
+
+        // 仅删除/排序：直接应用变更，不再生成审核记录
+        // 先根据新的顺序更新 orderIndex
+        clerkMediaAssetService.reorder(userInfo.getId(), ClerkMediaUsage.PROFILE, new ArrayList<>(requestedSet));
+
+        // 再对不再保留的媒资执行软删除
+        java.util.Set<String> requestedOnly = new java.util.HashSet<>(requestedSet);
+        java.util.Set<String> deletedMediaIds = approvedIds.stream()
+                .filter(id -> !requestedOnly.contains(id))
+                .collect(java.util.stream.Collectors.toSet());
+        for (String mediaId : deletedMediaIds) {
+            clerkMediaAssetService.softDelete(userInfo.getId(), mediaId);
+            mediaService.softDelete(MediaOwnerType.CLERK, userInfo.getId(), mediaId);
+        }
+
+        return R.ok().message("修改成功");
     }
 
     @ClerkUserLogin
@@ -343,7 +466,7 @@ public class WxClerkController {
         list.add(vo.getAudio());
         entity.setDataContent(list);
         playClerkDataReviewInfoService.create(entity);
-        return R.ok("提交成功，等待审核~");
+        return R.ok().message("提交成功，等待审核~");
     }
 
     @ClerkUserLogin
@@ -394,10 +517,10 @@ public class WxClerkController {
      * @return 店员列表
      */
     @PostMapping("/user/queryByPage")
-    public R queryByPage(@RequestBody PlayClerkUserInfoQueryVo vo) {
+    public TypedR<IPage<PlayClerkUserInfoResultVo>> queryByPage(@RequestBody PlayClerkUserInfoQueryVo vo) {
         IPage<PlayClerkUserInfoResultVo> page = playClerkUserInfoService.selectByPage(vo,
                 customUserService.getLoginUserId());
-        return R.ok(page);
+        return TypedR.ok(page);
     }
 
     /**

play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkMediaController.java

@@ -0,0 +1,121 @@
+package com.starry.admin.modules.weichat.controller;
+
+import cn.hutool.core.collection.CollUtil;
+import com.starry.admin.common.aspect.ClerkUserLogin;
+import com.starry.admin.common.conf.ThreadLocalRequestDetail;
+import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.admin.modules.weichat.assembler.ClerkMediaAssembler;
+import com.starry.admin.modules.weichat.entity.clerk.MediaOrderRequest;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import com.starry.admin.modules.weichat.service.MediaUploadService;
+import com.starry.common.result.R;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+import javax.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+@Api(tags = "店员媒资接口")
+@RestController
+@RequestMapping("/wx/clerk/media")
+@Validated
+@RequiredArgsConstructor
+public class WxClerkMediaController {
+
+    private final MediaUploadService mediaUploadService;
+    private final IPlayMediaService mediaService;
+    private final IPlayClerkMediaAssetService clerkMediaAssetService;
+
+    @ApiOperation("上传媒资（图片/视频）")
+    @PostMapping("/upload")
+    @ClerkUserLogin
+    public R upload(@RequestParam("file") MultipartFile file,
+            @RequestParam(value = "usage", required = false) String usageCode) {
+        PlayClerkUserInfoEntity clerkInfo = requireClerkInfo();
+        MediaVo vo = mediaUploadService.upload(file, clerkInfo, ClerkMediaUsage.fromCode(usageCode));
+        return R.ok(vo);
+    }
+
+    @ApiOperation("更新媒资顺序并提交保留列表")
+    @PutMapping("/order")
+    @ClerkUserLogin
+    public R updateOrder(@Valid @RequestBody MediaOrderRequest request) {
+        PlayClerkUserInfoEntity clerkInfo = requireClerkInfo();
+        ClerkMediaUsage usage = ClerkMediaUsage.fromCode(request.getUsage());
+        List<String> mediaIds = CollUtil.isEmpty(request.getMediaIds()) ? Collections.emptyList()
+                : request.getMediaIds().stream().distinct().collect(Collectors.toList());
+        clerkMediaAssetService.submitWithOrder(clerkInfo.getId(), usage, mediaIds);
+        return R.ok();
+    }
+
+    @ApiOperation("删除媒资（软删除）")
+    @DeleteMapping("/{id}")
+    @ClerkUserLogin
+    public R delete(@PathVariable("id") String mediaId) {
+        PlayClerkUserInfoEntity clerkInfo = requireClerkInfo();
+        clerkMediaAssetService.softDelete(clerkInfo.getId(), mediaId);
+        mediaService.softDelete(MediaOwnerType.CLERK, clerkInfo.getId(), mediaId);
+        return R.ok();
+    }
+
+    @ApiOperation("查询草稿媒资列表")
+    @GetMapping("/list")
+    @ClerkUserLogin
+    public R listDraft(@RequestParam(value = "usage", required = false) String usageCode) {
+        PlayClerkUserInfoEntity clerkInfo = requireClerkInfo();
+        ClerkMediaUsage usage = ClerkMediaUsage.fromCode(usageCode);
+        List<PlayClerkMediaAssetEntity> assets = clerkMediaAssetService.listByState(clerkInfo.getId(), usage,
+                Arrays.asList(ClerkMediaReviewState.DRAFT, ClerkMediaReviewState.PENDING,
+                        ClerkMediaReviewState.REJECTED));
+        Map<String, PlayMediaEntity> mediaMap = loadMediaMap(assets);
+        return R.ok(ClerkMediaAssembler.toVoList(assets, mediaMap));
+    }
+
+    @ApiOperation("查询已审核通过的媒资")
+    @GetMapping("/approved")
+    @ClerkUserLogin
+    public R listApproved(@RequestParam(value = "usage", required = false) String usageCode) {
+        PlayClerkUserInfoEntity clerkInfo = requireClerkInfo();
+        ClerkMediaUsage usage = ClerkMediaUsage.fromCode(usageCode);
+        List<PlayClerkMediaAssetEntity> assets = clerkMediaAssetService.listByState(clerkInfo.getId(), usage,
+                Collections.singletonList(ClerkMediaReviewState.APPROVED));
+        Map<String, PlayMediaEntity> mediaMap = loadMediaMap(assets);
+        return R.ok(ClerkMediaAssembler.toVoList(assets, mediaMap));
+    }
+
+    private PlayClerkUserInfoEntity requireClerkInfo() {
+        PlayClerkUserInfoEntity clerk = ThreadLocalRequestDetail.getClerkUserInfo();
+        if (clerk == null) {
+            throw new CustomException("店员未登录");
+        }
+        return clerk;
+    }
+
+    private Map<String, PlayMediaEntity> loadMediaMap(List<PlayClerkMediaAssetEntity> assets) {
+        if (CollUtil.isEmpty(assets)) {
+            return Collections.emptyMap();
+        }
+        List<String> mediaIds = assets.stream().map(PlayClerkMediaAssetEntity::getMediaId).distinct()
+                .collect(Collectors.toList());
+        List<PlayMediaEntity> mediaList = mediaService.listByIds(mediaIds);
+        if (CollUtil.isEmpty(mediaList)) {
+            return Collections.emptyMap();
+        }
+        return mediaList.stream().collect(Collectors.toMap(PlayMediaEntity::getId, item -> item));
+    }
+}

play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCustomController.java

@@ -151,16 +151,9 @@ public class WxCustomController {
     @ApiResponses({@ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserInfoResultVo.class)})
     @GetMapping("/queryClerkDetailedById")
     public R queryClerkDetailedById(@RequestParam("id") String id) {
-        PlayClerkUserInfoEntity entity = clerkUserInfoService.selectById(id);
-        PlayClerkUserInfoResultVo vo = ConvertUtil.entityToVo(entity, PlayClerkUserInfoResultVo.class);
-        vo.setAddress(entity.getCity());
-        // 查询是否关注，未登录情况下，默认为未关注
         String loginUserId = customUserService.getLoginUserId();
-        if (StringUtils.isNotEmpty(loginUserId)) {
-            vo.setFollowState(playCustomFollowInfoService.queryFollowState(loginUserId, vo.getId()));
-        }
-        // 服务项目
-        vo.setCommodity(playClerkCommodityService.getClerkCommodityList(vo.getId(), "1"));
+        PlayClerkUserInfoResultVo vo = clerkUserInfoService.buildCustomerDetail(id,
+                StringUtils.isNotEmpty(loginUserId) ? loginUserId : "");
         return R.ok(vo);
     }
 

play-admin/src/main/java/com/starry/admin/modules/weichat/entity/PlayClerkUserLoginResponseVo.java

@@ -3,6 +3,7 @@ package com.starry.admin.modules.weichat.entity;
 import com.alibaba.fastjson2.JSONObject;
 import com.starry.admin.modules.clerk.module.entity.PlayClerkLevelInfoEntity;
 import com.starry.admin.modules.clerk.module.vo.PlayClerkCommodityQueryVo;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
 import java.util.ArrayList;
 import java.util.List;
 import lombok.Data;
@@ -45,6 +46,11 @@ public class PlayClerkUserLoginResponseVo {
      */
     private List<String> album = new ArrayList<>();
 
+    /**
+     * 新媒资列表
+     */
+    private List<MediaVo> mediaList = new ArrayList<>();
+
     /**
      * 相册是否运行编辑
      */

play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/MediaOrderRequest.java

@@ -0,0 +1,14 @@
+package com.starry.admin.modules.weichat.entity.clerk;
+
+import java.util.List;
+import javax.validation.constraints.NotNull;
+import lombok.Data;
+
+@Data
+public class MediaOrderRequest {
+
+    private String usage;
+
+    @NotNull(message = "媒资ID列表不能为空")
+    private List<String> mediaIds;
+}

play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/MediaVo.java

@@ -0,0 +1,44 @@
+package com.starry.admin.modules.weichat.entity.clerk;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+import java.util.Map;
+import lombok.Data;
+
+@Data
+public class MediaVo implements Serializable {
+
+    private String id;
+
+    private String assetId;
+
+    private String mediaId;
+
+    private String kind;
+
+    private String status;
+
+    private String url;
+
+    private String coverUrl;
+
+    private Long durationMs;
+
+    private Integer width;
+
+    private Integer height;
+
+    private Long sizeBytes;
+
+    private Integer orderIndex;
+
+    private Map<String, Object> metadata;
+
+    private String usage;
+
+    private String reviewState;
+
+    private LocalDateTime submittedTime;
+
+    private String reviewNote;
+}

play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoResultVo.java

@@ -75,6 +75,12 @@ public class PlayClerkUserInfoResultVo {
     @ApiModelProperty(value = "相册列表", notes = "店员相册图片URL列表")
     private List<String> album = new ArrayList<>();
 
+    /**
+     * 媒资列表
+     */
+    @ApiModelProperty(value = "媒资列表", notes = "结构化媒资数据")
+    private List<MediaVo> mediaList = new ArrayList<>();
+
     /**
      * 个性签名
      */

play-admin/src/main/java/com/starry/admin/modules/weichat/service/MediaUploadService.java

@@ -0,0 +1,284 @@
+package com.starry.admin.modules.weichat.service;
+
+import cn.hutool.core.io.FileTypeUtil;
+import cn.hutool.core.io.FileUtil;
+import cn.hutool.core.util.IdUtil;
+import cn.hutool.core.util.StrUtil;
+import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.common.oss.service.IOssFileService;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaKind;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.enums.MediaStatus;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.admin.modules.weichat.assembler.ClerkMediaAssembler;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import com.starry.common.utils.IdUtils;
+import java.awt.image.BufferedImage;
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.file.Files;
+import java.util.HashMap;
+import java.util.Locale;
+import java.util.Map;
+import javax.imageio.ImageIO;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.multipart.MultipartFile;
+import ws.schild.jave.Encoder;
+import ws.schild.jave.MultimediaObject;
+import ws.schild.jave.encode.AudioAttributes;
+import ws.schild.jave.encode.EncodingAttributes;
+import ws.schild.jave.encode.VideoAttributes;
+import ws.schild.jave.info.MultimediaInfo;
+import ws.schild.jave.info.VideoInfo;
+import ws.schild.jave.info.VideoSize;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class MediaUploadService {
+
+    private static final long MAX_VIDEO_BYTES = 30L * 1024 * 1024;
+    private static final long MAX_VIDEO_DURATION_MS = 45_000;
+    private static final String IMAGE_OUTPUT_FORMAT = "image2";
+    private static final String VIDEO_OUTPUT_FORMAT = "mp4";
+
+    private final IOssFileService ossFileService;
+    private final IPlayMediaService mediaService;
+    private final IPlayClerkMediaAssetService clerkMediaAssetService;
+
+    @Transactional(rollbackFor = Exception.class)
+    public MediaVo upload(MultipartFile file, PlayClerkUserInfoEntity clerkInfo, ClerkMediaUsage usage) {
+        if (file == null || file.isEmpty()) {
+            throw new CustomException("请选择要上传的文件");
+        }
+        if (clerkInfo == null) {
+            throw new CustomException("店员信息不存在");
+        }
+
+        String originalFilename = StrUtil.blankToDefault(file.getOriginalFilename(), file.getName());
+        File tempFile = null;
+        File processedVideoFile = null;
+        File coverFile = null;
+        try {
+            String suffix = resolveSuffix(originalFilename);
+            tempFile = createTempFile("media_", suffix);
+            file.transferTo(tempFile);
+
+            String detectedType = detectFileType(tempFile, file.getContentType());
+            boolean isVideo = isVideoType(detectedType, file.getContentType());
+            boolean isImage = isImageType(detectedType, file.getContentType());
+            if (!isVideo && !isImage) {
+                log.warn("Unsupported media type: {} / {}", detectedType, file.getContentType());
+                throw new CustomException("不支持的文件格式");
+            }
+
+            PlayMediaEntity entity = buildSkeletonEntity(file, clerkInfo,
+                    isVideo ? MediaKind.VIDEO : MediaKind.IMAGE);
+            entity.getMetadata().put("detectedType", detectedType);
+            entity.getMetadata().put("isVideo", isVideo);
+
+            if (isImage) {
+                handleImageUpload(tempFile, entity, clerkInfo, originalFilename);
+            } else {
+                processedVideoFile = createTempFile("media_video_", ".mp4");
+                coverFile = createTempFile("media_cover_", ".jpg");
+                handleVideoUpload(tempFile, processedVideoFile, coverFile, entity, clerkInfo, originalFilename);
+            }
+            entity.setStatus(MediaStatus.READY.getCode());
+            mediaService.normalizeAndSave(entity);
+            PlayClerkMediaAssetEntity asset = clerkMediaAssetService.linkDraftAsset(
+                    clerkInfo.getTenantId(),
+                    clerkInfo.getId(),
+                    entity.getId(),
+                    usage == null ? ClerkMediaUsage.PROFILE : usage);
+            return ClerkMediaAssembler.toVo(entity, asset);
+        } catch (CustomException customException) {
+            throw customException;
+        } catch (Exception ex) {
+            log.error("媒资上传失败", ex);
+            throw new CustomException("媒资上传失败，请稍后重试");
+        } finally {
+            deleteQuietly(tempFile);
+            deleteQuietly(processedVideoFile);
+            deleteQuietly(coverFile);
+        }
+    }
+
+    private PlayMediaEntity buildSkeletonEntity(MultipartFile file, PlayClerkUserInfoEntity clerkInfo, MediaKind kind) {
+        PlayMediaEntity entity = new PlayMediaEntity();
+        entity.setId(IdUtils.getUuid());
+        entity.setTenantId(clerkInfo.getTenantId());
+        entity.setOwnerType(MediaOwnerType.CLERK);
+        entity.setOwnerId(clerkInfo.getId());
+        entity.setKind(kind.getCode());
+        entity.setStatus(MediaStatus.UPLOADED.getCode());
+        entity.setSizeBytes(file.getSize());
+        Map<String, Object> metadata = new HashMap<>();
+        metadata.put("originalFilename", file.getOriginalFilename());
+        metadata.put("contentType", file.getContentType());
+        metadata.put("uploadTraceId", IdUtil.fastUUID());
+        metadata.put("sourceSizeBytes", file.getSize());
+        entity.setMetadata(metadata);
+        return entity;
+    }
+
+    private void handleImageUpload(File tempFile, PlayMediaEntity entity, PlayClerkUserInfoEntity clerkInfo,
+            String originalFilename) throws IOException {
+        BufferedImage image = ImageIO.read(tempFile);
+        if (image == null) {
+            throw new CustomException("图片文件已损坏或格式不受支持");
+        }
+        entity.setWidth(image.getWidth());
+        entity.setHeight(image.getHeight());
+        try (InputStream is = Files.newInputStream(tempFile.toPath())) {
+            String targetName = buildObjectName("img", originalFilename);
+            String url = ossFileService.upload(is, clerkInfo.getTenantId(), targetName);
+            entity.setUrl(url);
+        }
+    }
+
+    private void handleVideoUpload(File sourceFile, File targetFile, File coverFile, PlayMediaEntity entity,
+            PlayClerkUserInfoEntity clerkInfo, String originalFilename) throws Exception {
+        if (entity.getSizeBytes() != null && entity.getSizeBytes() > MAX_VIDEO_BYTES) {
+            throw new CustomException("视频大小不能超过30MB");
+        }
+        MultimediaObject multimediaObject = new MultimediaObject(sourceFile);
+        MultimediaInfo info = multimediaObject.getInfo();
+        if (info == null || info.getVideo() == null) {
+            throw new CustomException("无法读取视频信息");
+        }
+        long durationMs = info.getDuration();
+        if (durationMs > MAX_VIDEO_DURATION_MS) {
+            throw new CustomException("视频时长不能超过45秒");
+        }
+        VideoInfo videoInfo = info.getVideo();
+        VideoSize size = videoInfo.getSize();
+        if (size != null) {
+            entity.setWidth(size.getWidth());
+            entity.setHeight(size.getHeight());
+        }
+        entity.setDurationMs(durationMs);
+
+        AudioAttributes audioAttrs = new AudioAttributes();
+        audioAttrs.setCodec("aac");
+        audioAttrs.setBitRate(128_000);
+        audioAttrs.setChannels(2);
+        audioAttrs.setSamplingRate(44_100);
+
+        VideoAttributes videoAttrs = new VideoAttributes();
+        videoAttrs.setCodec("h264");
+        videoAttrs.setBitRate(1_500_000);
+        if (size != null) {
+            videoAttrs.setSize(size);
+        }
+        float frameRate = videoInfo.getFrameRate();
+        videoAttrs.setFrameRate(frameRate > 0 ? Math.round(frameRate) : 30);
+
+        Encoder encoder = new Encoder();
+        EncodingAttributes attrs = new EncodingAttributes();
+        attrs.setOutputFormat(VIDEO_OUTPUT_FORMAT);
+        attrs.setAudioAttributes(audioAttrs);
+        attrs.setVideoAttributes(videoAttrs);
+        encoder.encode(multimediaObject, targetFile, attrs);
+
+        long processedSize = targetFile.length();
+        entity.setSizeBytes(processedSize);
+
+        // 抽取首帧作为封面
+        EncodingAttributes coverAttrs = new EncodingAttributes();
+        VideoAttributes coverVideoAttrs = new VideoAttributes();
+        coverVideoAttrs.setCodec("mjpeg");
+        if (size != null) {
+            coverVideoAttrs.setSize(size);
+        }
+        coverAttrs.setOutputFormat(IMAGE_OUTPUT_FORMAT);
+        coverAttrs.setVideoAttributes(coverVideoAttrs);
+        coverAttrs.setDuration(0.01f);
+        coverAttrs.setOffset(0f);
+        coverAttrs.setAudioAttributes(null);
+        encoder.encode(new MultimediaObject(targetFile), coverFile, coverAttrs);
+
+        try (InputStream videoIs = Files.newInputStream(targetFile.toPath());
+                InputStream coverIs = Files.newInputStream(coverFile.toPath())) {
+            String videoName = buildObjectName("video", originalFilename);
+            String coverName = buildObjectName("cover", originalFilename + ".jpg");
+            String videoUrl = ossFileService.upload(videoIs, clerkInfo.getTenantId(), videoName);
+            String coverUrl = ossFileService.upload(coverIs, clerkInfo.getTenantId(), coverName);
+            entity.setUrl(videoUrl);
+            entity.setCoverUrl(coverUrl);
+        }
+        if (entity.getMetadata() != null) {
+            entity.getMetadata().put("durationMs", durationMs);
+        }
+    }
+
+    private String detectFileType(File file, String contentType) {
+        String type = null;
+        try {
+            type = FileTypeUtil.getType(file);
+        } catch (Exception ex) {
+            log.warn("Failed to read file type via signature, fallback to contentType: {}", contentType, ex);
+        }
+        if (StrUtil.isNotBlank(type)) {
+            return type.toLowerCase(Locale.ROOT);
+        }
+        if (StrUtil.isNotBlank(contentType)) {
+            return contentType.toLowerCase(Locale.ROOT);
+        }
+        return "";
+    }
+
+    private boolean isVideoType(String detectedType, String mime) {
+        if (StrUtil.isBlank(detectedType) && StrUtil.isBlank(mime)) {
+            return false;
+        }
+        String lower = StrUtil.blankToDefault(detectedType, "");
+        if (lower.contains("mp4") || lower.contains("mov") || lower.contains("quicktime")) {
+            return true;
+        }
+        String mimeLower = StrUtil.blankToDefault(mime, "").toLowerCase(Locale.ROOT);
+        return mimeLower.startsWith("video/");
+    }
+
+    private boolean isImageType(String detectedType, String mime) {
+        String lower = StrUtil.blankToDefault(detectedType, "");
+        if (lower.contains("jpg") || lower.contains("jpeg") || lower.contains("png") || lower.contains("gif")
+                || lower.contains("webp")) {
+            return true;
+        }
+        String mimeLower = StrUtil.blankToDefault(mime, "").toLowerCase(Locale.ROOT);
+        return mimeLower.startsWith("image/");
+    }
+
+    private String buildObjectName(String category, String originalFilename) {
+        String ext = resolveSuffix(originalFilename);
+        return StrUtil.join("/", "clerk", category, IdUtils.getUuid() + ext);
+    }
+
+    private String resolveSuffix(String filename) {
+        if (StrUtil.isBlank(filename) || !filename.contains(".")) {
+            return "";
+        }
+        return filename.substring(filename.lastIndexOf('.'));
+    }
+
+    private void deleteQuietly(File file) {
+        if (file != null && file.exists()) {
+            FileUtil.del(file);
+        }
+    }
+
+    private File createTempFile(String prefix, String suffix) throws IOException {
+        String effectiveSuffix = StrUtil.isBlank(suffix) ? ".tmp" : suffix;
+        return Files.createTempFile(prefix, effectiveSuffix).toFile();
+    }
+}

play-admin/src/main/resources/application-dev.yml

@@ -96,6 +96,10 @@ logging:
     org.springframework.web.servlet.DispatcherServlet: debug
     org.springframework.security: debug
 
+clerk:
+  media:
+    migration-enabled: false
+
 jwt:
   tokenHeader: X-Token #JWT存储的请求头
   tokenHead: Bearer  #JWT负载中拿到开头
@@ -117,4 +121,3 @@ xl:
     authCode:
       # 登录验证码是否开启，开发环境配置false方便测试
       enable: ${XL_LOGIN_AUTHCODE_ENABLE:false}
-

play-admin/src/main/resources/db/migration/V17__create_media.sql

@@ -0,0 +1,43 @@
+CREATE TABLE `play_media` (
+  `id`           varchar(32)   NOT NULL,
+  `tenant_id`    varchar(32)   NOT NULL,
+  `owner_type`   varchar(32)   NOT NULL COMMENT 'clerk/article/...',
+  `owner_id`     varchar(32)   NOT NULL,
+  `kind`         varchar(16)   NOT NULL COMMENT 'image | video',
+  `status`       varchar(16)   NOT NULL COMMENT 'uploaded|processing|ready|approved|rejected',
+  `url`          varchar(1024) NOT NULL,
+  `cover_url`    varchar(1024) DEFAULT NULL,
+  `duration_ms`  bigint        DEFAULT NULL,
+  `width`        int           DEFAULT NULL,
+  `height`       int           DEFAULT NULL,
+  `size_bytes`   bigint        DEFAULT NULL,
+  `order_index`  int           NOT NULL DEFAULT 0,
+  `metadata`     json          DEFAULT NULL,
+  `created_time` datetime      DEFAULT CURRENT_TIMESTAMP,
+  `updated_time` datetime      DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  PRIMARY KEY (`id`),
+  KEY `idx_media_owner` (`owner_type`,`owner_id`),
+  KEY `idx_media_order` (`tenant_id`,`owner_type`,`owner_id`,`order_index`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE `play_clerk_media_asset` (
+  `id`               varchar(32)   NOT NULL,
+  `clerk_id`         varchar(32)   NOT NULL,
+  `tenant_id`        varchar(32)   NOT NULL,
+  `media_id`         varchar(32)   NOT NULL,
+  `usage`            varchar(32)   NOT NULL,
+  `review_state`     varchar(16)   NOT NULL,
+  `order_index`      int           NOT NULL DEFAULT 0,
+  `submitted_time`   datetime      DEFAULT NULL,
+  `review_record_id` varchar(32)   DEFAULT NULL,
+  `note`             varchar(255)  DEFAULT NULL,
+  `deleted`          tinyint(1)    NOT NULL DEFAULT 0,
+  `created_by`       varchar(32)   DEFAULT NULL,
+  `created_time`     datetime      DEFAULT CURRENT_TIMESTAMP,
+  `updated_time`     datetime      DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  `updated_by`       varchar(32)   DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_clerk_usage_media` (`clerk_id`,`usage`,`media_id`),
+  KEY `idx_clerk_usage_state` (`clerk_id`,`usage`,`review_state`,`deleted`),
+  KEY `idx_clerk_media_asset_media` (`media_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

play-admin/src/test/java/com/starry/admin/api/PlayClerkUserInfoApiTest.java

@@ -17,8 +17,12 @@ import com.starry.admin.utils.SecurityUtils;
 import com.starry.common.utils.IdUtils;
 import java.time.LocalDateTime;
 import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 import java.util.concurrent.ThreadLocalRandom;
+import java.util.stream.Collectors;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -37,6 +41,13 @@ class PlayClerkUserInfoApiTest extends AbstractApiTest {
 
     private final List<String> levelIdsToCleanup = new ArrayList<>();
     private final List<String> clerkIdsToCleanup = new ArrayList<>();
+    private int scenarioSequence = 0;
+    private static final Comparator<ClerkScenario> BACKEND_ORDERING = Comparator
+            .comparing(ClerkScenario::isOnline, Comparator.reverseOrder())
+            .thenComparing(ClerkScenario::isPinned, Comparator.reverseOrder())
+            .thenComparingLong(ClerkScenario::getLevelOrder)
+            .thenComparingInt(ClerkScenario::getSequence)
+            .thenComparing(ClerkScenario::getId);
 
     @AfterEach
     void tearDown() {
@@ -83,9 +94,10 @@ class PlayClerkUserInfoApiTest extends AbstractApiTest {
         }
 
         assertThat(orderedIds).contains(lowOrderClerkId, highOrderClerkId);
-        assertThat(orderedIds.indexOf(lowOrderClerkId))
-                .withFailMessage("Unexpected order for token %s: %s", filterToken, orderedIds)
-                .isLessThan(orderedIds.indexOf(highOrderClerkId));
+        assertThat(orderedIds.indexOf(highOrderClerkId))
+                .withFailMessage("Online clerk should appear before offline regardless of level. token=%s list=%s",
+                        filterToken, orderedIds)
+                .isLessThan(orderedIds.indexOf(lowOrderClerkId));
     }
 
     @Test
@@ -351,17 +363,96 @@ class PlayClerkUserInfoApiTest extends AbstractApiTest {
             orderedIds.add(record.path("id").asText());
         }
 
-        assertThat(orderedIds.indexOf(pinnedOnline))
-                .isLessThan(orderedIds.indexOf(pinnedOffline));
-        assertThat(orderedIds.indexOf(pinnedOffline))
-                .isLessThan(orderedIds.indexOf(online1));
-        assertThat(orderedIds.indexOf(online1))
-                .isLessThan(orderedIds.indexOf(offline));
-        assertThat(orderedIds.indexOf(online1))
-                .withFailMessage("Created time fallback should maintain order, list=%s", orderedIds)
-                .isLessThan(orderedIds.indexOf(online2));
+        Map<String, ClerkScenario> expectedScenarios = new HashMap<>();
+        expectedScenarios.put(pinnedOnline, new ClerkScenario(pinnedOnline, 1L, true, true, 0));
+        expectedScenarios.put(online1, new ClerkScenario(online1, 1L, true, false, 1));
+        expectedScenarios.put(online2, new ClerkScenario(online2, 1L, true, false, 2));
+        expectedScenarios.put(pinnedOffline, new ClerkScenario(pinnedOffline, 1L, false, true, 3));
+        expectedScenarios.put(offline, new ClerkScenario(offline, 1L, false, false, 4));
+
+        List<ClerkScenario> actualScenarios = orderedIds.stream()
+                .map(expectedScenarios::get)
+                .collect(Collectors.toList());
+
+        for (int i = 1; i < actualScenarios.size(); i++) {
+            ClerkScenario previous = actualScenarios.get(i - 1);
+            ClerkScenario current = actualScenarios.get(i);
+            assertThat(previous).isNotNull();
+            assertThat(current).isNotNull();
+            assertThat(BACKEND_ORDERING.compare(previous, current))
+                    .withFailMessage("Ordering violation between %s and %s, list=%s", previous.getId(), current.getId(),
+                            orderedIds)
+                    .isLessThanOrEqualTo(0);
+        }
     }
 
+    @Test
+    void listOrderingHandlesBulkDataset() throws Exception {
+        ensureTenantContext();
+        String token = "bulk-" + IdUtils.getUuid().substring(0, 6);
+        PlayClerkLevelInfoEntity gold = createClerkLevel(token + "-gold", 1L, 90);
+        PlayClerkLevelInfoEntity silver = createClerkLevel(token + "-silver", 2L, 80);
+        PlayClerkLevelInfoEntity iron = createClerkLevel(token + "-iron", 3L, 70);
+
+        List<ClerkScenario> scenarios = new ArrayList<>();
+        scenarios.add(buildScenario(token, "G-Pin-ON", gold, true, true));
+        scenarios.add(buildScenario(token, "G-UnPin-ON", gold, true, false));
+        scenarios.add(buildScenario(token, "G-Pin-Off", gold, false, true));
+        scenarios.add(buildScenario(token, "G-UnPin-Off", gold, false, false));
+        scenarios.add(buildScenario(token, "S-Pin-ON", silver, true, true));
+        scenarios.add(buildScenario(token, "S-UnPin-ON", silver, true, false));
+        scenarios.add(buildScenario(token, "S-Pin-Off", silver, false, true));
+        scenarios.add(buildScenario(token, "S-UnPin-Off", silver, false, false));
+        scenarios.add(buildScenario(token, "I-Pin-ON", iron, true, true));
+        scenarios.add(buildScenario(token, "I-UnPin-ON", iron, true, false));
+        scenarios.add(buildScenario(token, "I-Pin-Off", iron, false, true));
+        scenarios.add(buildScenario(token, "I-UnPin-Off", iron, false, false));
+
+        MvcResult result = mockMvc.perform(get("/clerk/user/list")
+                        .param("pageNum", "1")
+                        .param("pageSize", "80")
+                        .param("nickname", token)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(USER_HEADER, DEFAULT_USER))
+                .andExpect(status().isOk())
+                .andReturn();
+
+        JsonNode root = objectMapper.readTree(result.getResponse().getContentAsString());
+        JsonNode records = root.path("data");
+        List<String> orderedIds = new ArrayList<>();
+        for (JsonNode record : records) {
+            orderedIds.add(record.path("id").asText());
+        }
+
+        Map<String, ClerkScenario> scenarioById = scenarios.stream()
+                .collect(Collectors.toMap(ClerkScenario::getId, scenario -> scenario));
+
+        assertThat(orderedIds).containsExactlyInAnyOrderElementsOf(scenarioById.keySet());
+
+        List<ClerkScenario> orderedScenarios = orderedIds.stream()
+                .map(scenarioById::get)
+                .collect(Collectors.toList());
+        for (int i = 1; i < orderedScenarios.size(); i++) {
+            ClerkScenario previous = orderedScenarios.get(i - 1);
+            ClerkScenario current = orderedScenarios.get(i);
+            assertThat(BACKEND_ORDERING.compare(previous, current))
+                    .withFailMessage("Ordering violation between %s and %s, list=%s",
+                            previous.getId(), current.getId(), orderedIds)
+                    .isLessThanOrEqualTo(0);
+        }
+    }
+
+
+    private ClerkScenario buildScenario(String token, String suffix, PlayClerkLevelInfoEntity level, boolean online, boolean pinned) {
+        String id = createClerk(token + "-" + suffix, level.getId(), online ? "1" : "0");
+        if (pinned) {
+            togglePin(id, "1");
+        }
+        long levelOrder = level.getOrderNumber() == null ? Long.MAX_VALUE : level.getOrderNumber();
+        ClerkScenario scenario = new ClerkScenario(id, levelOrder, online, pinned, scenarioSequence++);
+        pause(15);
+        return scenario;
+    }
 
     private void togglePin(String clerkId, String pinState) {
         ensureTenantContext();
@@ -378,4 +469,40 @@ class PlayClerkUserInfoApiTest extends AbstractApiTest {
             Thread.currentThread().interrupt();
         }
     }
+
+    private static class ClerkScenario {
+        private final String id;
+        private final long levelOrder;
+        private final boolean online;
+        private final boolean pinned;
+        private final int sequence;
+
+        ClerkScenario(String id, long levelOrder, boolean online, boolean pinned, int sequence) {
+            this.id = id;
+            this.levelOrder = levelOrder;
+            this.online = online;
+            this.pinned = pinned;
+            this.sequence = sequence;
+        }
+
+        String getId() {
+            return id;
+        }
+
+        long getLevelOrder() {
+            return levelOrder;
+        }
+
+        boolean isOnline() {
+            return online;
+        }
+
+        boolean isPinned() {
+            return pinned;
+        }
+
+        int getSequence() {
+            return sequence;
+        }
+    }
 }

play-admin/src/test/java/com/starry/admin/api/WxClerkAlbumUpdateApiTest.java

@@ -0,0 +1,321 @@
+package com.starry.admin.api;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.starry.admin.common.apitest.ApiTestDataSeeder;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkDataReviewInfoService;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.clerk.service.IPlayClerkUserInfoService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.enums.MediaStatus;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import com.starry.admin.modules.weichat.entity.clerk.PlayClerkUserInfoResultVo;
+import com.starry.admin.modules.weichat.service.WxTokenService;
+import com.starry.admin.utils.SecurityUtils;
+import com.starry.common.constant.Constants;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MvcResult;
+
+/**
+ * 专门验证 /wx/clerk/user/updateAlbum 在“只有删除/排序”时不会创建新的审核记录，
+ * 并且会立即更新顾客端视图。
+ */
+class WxClerkAlbumUpdateApiTest extends AbstractApiTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Autowired
+    private WxTokenService wxTokenService;
+
+    @Autowired
+    private IPlayClerkUserInfoService clerkUserInfoService;
+
+    @Autowired
+    private IPlayClerkDataReviewInfoService dataReviewInfoService;
+
+    @Autowired
+    private IPlayClerkMediaAssetService mediaAssetService;
+
+    @Autowired
+    private IPlayMediaService mediaService;
+
+    @Test
+    void reorderExistingApprovedMediaDoesNotCreateNewReviewAndUpdatesOrder() throws Exception {
+        ensureTenantContext();
+        String clerkId = ApiTestDataSeeder.DEFAULT_CLERK_ID;
+        String clerkToken = wxTokenService.createWxUserToken(clerkId);
+        clerkUserInfoService.updateTokenById(clerkId, clerkToken);
+
+        PlayMediaEntity media1 = seedMedia(clerkId);
+        PlayMediaEntity media2 = seedMedia(clerkId);
+        PlayMediaEntity media3 = seedMedia(clerkId);
+
+        seedApprovedAsset(clerkId, media1.getId(), 0);
+        seedApprovedAsset(clerkId, media2.getId(), 1);
+        seedApprovedAsset(clerkId, media3.getId(), 2);
+
+        long reviewCountBefore = dataReviewInfoService.lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId, clerkId)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .count();
+
+        // 仅调整顺序：album 只包含已审核通过的媒资 id，不引入任何新媒资
+        List<String> reordered = List.of(media3.getId(), media1.getId(), media2.getId());
+        ObjectNode payload = objectMapper.createObjectNode();
+        com.fasterxml.jackson.databind.node.ArrayNode albumArray = payload.putArray("album");
+        reordered.forEach(albumArray::add);
+
+        mockMvc.perform(post("/wx/clerk/user/updateAlbum")
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(Constants.CLERK_USER_LOGIN_TOKEN, Constants.TOKEN_PREFIX + clerkToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(payload.toString()))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        ensureTenantContext();
+        long reviewCountAfter = dataReviewInfoService.lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId, clerkId)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .count();
+        assertThat(reviewCountAfter)
+                .as("reordering without introducing new media should not create review records")
+                .isEqualTo(reviewCountBefore);
+
+        List<PlayClerkMediaAssetEntity> assets = mediaAssetService
+                .listByState(clerkId, ClerkMediaUsage.PROFILE,
+                        Collections.singletonList(ClerkMediaReviewState.APPROVED));
+        PlayClerkMediaAssetEntity asset1 = assets.stream()
+                .filter(a -> media1.getId().equals(a.getMediaId()))
+                .max(java.util.Comparator.comparing(PlayClerkMediaAssetEntity::getCreatedTime))
+                .orElse(null);
+        PlayClerkMediaAssetEntity asset2 = assets.stream()
+                .filter(a -> media2.getId().equals(a.getMediaId()))
+                .max(java.util.Comparator.comparing(PlayClerkMediaAssetEntity::getCreatedTime))
+                .orElse(null);
+        PlayClerkMediaAssetEntity asset3 = assets.stream()
+                .filter(a -> media3.getId().equals(a.getMediaId()))
+                .max(java.util.Comparator.comparing(PlayClerkMediaAssetEntity::getCreatedTime))
+                .orElse(null);
+
+        assertThat(asset3).as("asset for media3 should exist").isNotNull();
+        assertThat(asset1).as("asset for media1 should exist").isNotNull();
+        assertThat(asset2).as("asset for media2 should exist").isNotNull();
+
+        assertThat(asset3.getOrderIndex()).isEqualTo(0);
+        assertThat(asset1.getOrderIndex()).isEqualTo(1);
+        assertThat(asset2.getOrderIndex()).isEqualTo(2);
+
+        PlayClerkUserInfoResultVo detail = clerkUserInfoService.buildCustomerDetail(clerkId, "");
+        List<String> customerMediaIds = detail.getMediaList().stream()
+                .map(MediaVo::getMediaId)
+                .collect(Collectors.toList());
+
+        int index3 = customerMediaIds.indexOf(media3.getId());
+        int index1 = customerMediaIds.indexOf(media1.getId());
+        int index2 = customerMediaIds.indexOf(media2.getId());
+
+        assertThat(index3).isGreaterThanOrEqualTo(0);
+        assertThat(index1).isGreaterThanOrEqualTo(0);
+        assertThat(index2).isGreaterThanOrEqualTo(0);
+        assertThat(index3).isLessThan(index1);
+        assertThat(index1).isLessThan(index2);
+    }
+
+    @Test
+    void deleteAndReorderAlbumDoesNotCreateNewReviewAndIsImmediatelyVisible() throws Exception {
+        ensureTenantContext();
+        String clerkId = ApiTestDataSeeder.DEFAULT_CLERK_ID;
+        String clerkToken = wxTokenService.createWxUserToken(clerkId);
+        clerkUserInfoService.updateTokenById(clerkId, clerkToken);
+
+        // 预置两条已审核通过的 PROFILE 媒资
+        PlayMediaEntity media1 = seedMedia(clerkId);
+        PlayMediaEntity media2 = seedMedia(clerkId);
+
+        seedApprovedAsset(clerkId, media1.getId(), 0);
+        seedApprovedAsset(clerkId, media2.getId(), 1);
+
+        // 顾客端初始视图应包含两条媒资
+        PlayClerkUserInfoResultVo beforeDetail = clerkUserInfoService.buildCustomerDetail(clerkId, "");
+        List<String> beforeIds = beforeDetail.getMediaList().stream()
+                .map(MediaVo::getMediaId)
+                .collect(Collectors.toList());
+        assertThat(beforeIds).contains(media1.getId(), media2.getId());
+
+        // 记录当前相册审核记录数量
+        long reviewCountBefore = dataReviewInfoService.lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId, clerkId)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .count();
+
+        // 现在通过 updateAlbum 只保留 media2，相当于“删除 media1 + 不引入新媒资”
+        ObjectNode payload = objectMapper.createObjectNode();
+        payload.putArray("album").add(media2.getId());
+
+        mockMvc.perform(post("/wx/clerk/user/updateAlbum")
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(Constants.CLERK_USER_LOGIN_TOKEN, Constants.TOKEN_PREFIX + clerkToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(payload.toString()))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        ensureTenantContext();
+        long reviewCountAfter = dataReviewInfoService.lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId, clerkId)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .count();
+        assertThat(reviewCountAfter)
+                .as("Deleting/reordering without new media should not create new review records")
+                .isEqualTo(reviewCountBefore);
+
+        // 资产表中仅剩 media2 且仍为 APPROVED 状态
+        List<PlayClerkMediaAssetEntity> assets = mediaAssetService
+                .listByState(clerkId, ClerkMediaUsage.PROFILE,
+                        Collections.singletonList(ClerkMediaReviewState.APPROVED));
+        List<String> assetMediaIds = assets.stream()
+                .map(PlayClerkMediaAssetEntity::getMediaId)
+                .collect(Collectors.toList());
+        assertThat(assetMediaIds)
+                .contains(media2.getId())
+                .doesNotContain(media1.getId());
+
+        // 顾客端视图应立即反映删除结果
+        PlayClerkUserInfoResultVo afterDetail = clerkUserInfoService.buildCustomerDetail(clerkId, "");
+        List<String> afterIds = afterDetail.getMediaList().stream()
+                .map(MediaVo::getMediaId)
+                .collect(Collectors.toList());
+        assertThat(afterIds)
+                .contains(media2.getId())
+                .doesNotContain(media1.getId());
+    }
+
+    @Test
+    void updateAlbumRejectsEmptyAlbumPayload() throws Exception {
+        ensureTenantContext();
+        String clerkId = ApiTestDataSeeder.DEFAULT_CLERK_ID;
+        String clerkToken = wxTokenService.createWxUserToken(clerkId);
+        clerkUserInfoService.updateTokenById(clerkId, clerkToken);
+
+        ObjectNode payload = objectMapper.createObjectNode();
+        payload.putArray("album"); // 空数组
+
+        MvcResult result = mockMvc.perform(post("/wx/clerk/user/updateAlbum")
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(Constants.CLERK_USER_LOGIN_TOKEN, Constants.TOKEN_PREFIX + clerkToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(payload.toString()))
+                .andExpect(status().isOk())
+                .andReturn();
+
+        String body = result.getResponse().getContentAsString();
+        com.fasterxml.jackson.databind.JsonNode root = new ObjectMapper().readTree(body);
+        assertThat(root.path("code").asInt())
+                .as("empty album should be rejected, response=%s", body)
+                .isEqualTo(500);
+        assertThat(root.path("message").asText())
+                .as("error message for empty album should be present, response=%s", body)
+                .isNotBlank();
+    }
+
+    @Test
+    void updateAlbumAllowsMixedLegacyUrlsAndNewMediaIdsForReview() throws Exception {
+        ensureTenantContext();
+        String clerkId = ApiTestDataSeeder.DEFAULT_CLERK_ID;
+        String clerkToken = wxTokenService.createWxUserToken(clerkId);
+        clerkUserInfoService.updateTokenById(clerkId, clerkToken);
+
+        // 预置一条已就绪的媒资，模拟“新上传的视频/图片”
+        PlayMediaEntity media = seedMedia(clerkId);
+
+        // 模拟老相册中的 URL（未媒资化的历史数据）
+        String legacyUrl1 = "https://oss.apitest/legacy-1.png";
+        String legacyUrl2 = "https://oss.apitest/legacy-2.png";
+
+        long reviewCountBefore = dataReviewInfoService.lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId, clerkId)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .count();
+
+        ObjectNode payload = objectMapper.createObjectNode();
+        com.fasterxml.jackson.databind.node.ArrayNode albumArray = payload.putArray("album");
+        albumArray.add(legacyUrl1);
+        albumArray.add(legacyUrl2);
+        albumArray.add(media.getId());
+
+        MvcResult result = mockMvc.perform(post("/wx/clerk/user/updateAlbum")
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(Constants.CLERK_USER_LOGIN_TOKEN, Constants.TOKEN_PREFIX + clerkToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(payload.toString()))
+                .andExpect(status().isOk())
+                .andReturn();
+
+        String body = result.getResponse().getContentAsString();
+        com.fasterxml.jackson.databind.JsonNode root = new ObjectMapper().readTree(body);
+        assertThat(root.path("code").asInt())
+                .as("mixed legacy URLs and new media ids should be accepted for review, response=%s", body)
+                .isEqualTo(200);
+
+        ensureTenantContext();
+        long reviewCountAfter = dataReviewInfoService.lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId, clerkId)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .count();
+        assertThat(reviewCountAfter)
+                .as("mixed legacy URLs and new media ids should create exactly one new review record")
+                .isEqualTo(reviewCountBefore + 1);
+    }
+
+    private PlayMediaEntity seedMedia(String clerkId) {
+        String mediaId = "media-" + java.util.UUID.randomUUID().toString().substring(0, 16);
+        PlayMediaEntity entity = new PlayMediaEntity();
+        entity.setId(mediaId);
+        entity.setTenantId(ApiTestDataSeeder.DEFAULT_TENANT_ID);
+        entity.setOwnerType(MediaOwnerType.CLERK);
+        entity.setOwnerId(clerkId);
+        entity.setKind("image");
+        entity.setStatus(MediaStatus.READY.getCode());
+        entity.setUrl("https://oss.apitest/" + mediaId + ".png");
+        mediaService.save(entity);
+        return entity;
+    }
+
+    private void seedApprovedAsset(String clerkId, String mediaId, int orderIndex) {
+        PlayClerkMediaAssetEntity asset = new PlayClerkMediaAssetEntity();
+        asset.setId("asset-" + mediaId);
+        asset.setTenantId(ApiTestDataSeeder.DEFAULT_TENANT_ID);
+        asset.setClerkId(clerkId);
+        asset.setMediaId(mediaId);
+        asset.setUsage(ClerkMediaUsage.PROFILE.getCode());
+        asset.setOrderIndex(orderIndex);
+        asset.setReviewState(ClerkMediaReviewState.APPROVED.getCode());
+        asset.setDeleted(false);
+        mediaAssetService.save(asset);
+    }
+
+    private void ensureTenantContext() {
+        SecurityUtils.setTenantId(ApiTestDataSeeder.DEFAULT_TENANT_ID);
+    }
+}

play-admin/src/test/java/com/starry/admin/api/WxClerkMediaControllerApiTest.java

@@ -0,0 +1,329 @@
+package com.starry.admin.api;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.multipart;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.starry.admin.common.apitest.ApiTestDataSeeder;
+import com.starry.admin.common.oss.service.IOssFileService;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkDataReviewInfoService;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.clerk.service.IPlayClerkUserInfoService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.admin.modules.weichat.entity.PlayClerkUserLoginResponseVo;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import com.starry.admin.modules.weichat.entity.clerk.PlayClerkUserInfoResultVo;
+import com.starry.admin.modules.weichat.service.WxTokenService;
+import com.starry.admin.utils.SecurityUtils;
+import com.starry.common.constant.Constants;
+import com.starry.common.enums.ClerkReviewState;
+import java.awt.image.BufferedImage;
+import java.io.ByteArrayOutputStream;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.time.LocalDateTime;
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+import javax.imageio.ImageIO;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.http.MediaType;
+import org.springframework.mock.web.MockMultipartFile;
+import org.springframework.test.web.servlet.MvcResult;
+
+/**
+ * 覆盖店员端媒资上传与相册审核的关键业务路径（图片/视频 + 删除后不复活）。
+ */
+class WxClerkMediaControllerApiTest extends AbstractApiTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Autowired
+    private WxTokenService wxTokenService;
+
+    @Autowired
+    private IPlayClerkUserInfoService clerkUserInfoService;
+
+    @Autowired
+    private IPlayMediaService mediaService;
+
+    @Autowired
+    private IPlayClerkDataReviewInfoService dataReviewInfoService;
+
+    @Autowired
+    private IPlayClerkMediaAssetService mediaAssetService;
+
+    @MockBean
+    private IOssFileService ossFileService;
+
+    @Test
+    void clerkCanUploadImageMediaAndPersistUrl() throws Exception {
+        ensureTenantContext();
+        String clerkToken = wxTokenService.createWxUserToken(ApiTestDataSeeder.DEFAULT_CLERK_ID);
+        clerkUserInfoService.updateTokenById(ApiTestDataSeeder.DEFAULT_CLERK_ID, clerkToken);
+
+        String ossUrl = "https://oss.mock/apitest/avatar.png";
+        when(ossFileService.upload(any(), eq(ApiTestDataSeeder.DEFAULT_TENANT_ID), anyString()))
+                .thenReturn(ossUrl);
+
+        BufferedImage image = new BufferedImage(2, 2, BufferedImage.TYPE_INT_RGB);
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        ImageIO.write(image, "png", baos);
+        MockMultipartFile file = new MockMultipartFile(
+                "file",
+                "avatar.png",
+                "image/png",
+                baos.toByteArray());
+
+        MvcResult result = mockMvc.perform(multipart("/wx/clerk/media/upload")
+                        .file(file)
+                        .param("usage", "profile")
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(Constants.CLERK_USER_LOGIN_TOKEN, Constants.TOKEN_PREFIX + clerkToken)
+                        .contentType(MediaType.MULTIPART_FORM_DATA))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.url").value(ossUrl))
+                .andExpect(jsonPath("$.data.kind").value("image"))
+                .andExpect(jsonPath("$.data.usage").value("profile"))
+                .andReturn();
+
+        String body = result.getResponse().getContentAsString();
+        JsonNode root = objectMapper.readTree(body);
+        JsonNode data = root.path("data");
+        String mediaId = data.path("mediaId").asText(null);
+        assertThat(mediaId).isNotBlank();
+
+        ensureTenantContext();
+        PlayMediaEntity persisted = mediaService.getById(mediaId);
+        assertThat(persisted).isNotNull();
+        assertThat(persisted.getOwnerType()).isEqualTo(MediaOwnerType.CLERK);
+        assertThat(persisted.getOwnerId()).isEqualTo(ApiTestDataSeeder.DEFAULT_CLERK_ID);
+        assertThat(persisted.getUrl()).isEqualTo(ossUrl);
+    }
+
+    @Test
+    void clerkCanUploadVideoMediaAndPersistUrl() throws Exception {
+        ensureTenantContext();
+        String clerkToken = wxTokenService.createWxUserToken(ApiTestDataSeeder.DEFAULT_CLERK_ID);
+        clerkUserInfoService.updateTokenById(ApiTestDataSeeder.DEFAULT_CLERK_ID, clerkToken);
+
+        String videoUrl = "https://oss.mock/apitest/video.mp4";
+        String coverUrl = "https://oss.mock/apitest/video-cover.jpg";
+        when(ossFileService.upload(any(), eq(ApiTestDataSeeder.DEFAULT_TENANT_ID), anyString()))
+                .thenReturn(videoUrl, coverUrl);
+
+        byte[] videoBytes = Files.readAllBytes(Paths.get("/Volumes/main/code/yunpei/sample_data/sample_video.mp4"));
+        MockMultipartFile file = new MockMultipartFile(
+                "file",
+                "sample_video.mp4",
+                "video/mp4",
+                videoBytes);
+
+        MvcResult result = mockMvc.perform(multipart("/wx/clerk/media/upload")
+                        .file(file)
+                        .param("usage", "profile")
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(Constants.CLERK_USER_LOGIN_TOKEN, Constants.TOKEN_PREFIX + clerkToken)
+                        .contentType(MediaType.MULTIPART_FORM_DATA))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.kind").value("video"))
+                .andExpect(jsonPath("$.data.usage").value("profile"))
+                .andReturn();
+
+        String body = result.getResponse().getContentAsString();
+        JsonNode root = objectMapper.readTree(body);
+        JsonNode data = root.path("data");
+        String mediaId = data.path("mediaId").asText(null);
+        assertThat(mediaId).isNotBlank();
+
+        ensureTenantContext();
+        PlayMediaEntity persisted = mediaService.getById(mediaId);
+        assertThat(persisted).isNotNull();
+        assertThat(persisted.getKind()).isEqualTo("video");
+        assertThat(persisted.getUrl()).isEqualTo(videoUrl);
+        assertThat(persisted.getCoverUrl()).isEqualTo(coverUrl);
+    }
+
+    @Test
+    void aggressiveAlbumLifecycleWithFourMediaAndDeletionReflectedForClerkAndCustomer() throws Exception {
+        ensureTenantContext();
+        String clerkToken = wxTokenService.createWxUserToken(ApiTestDataSeeder.DEFAULT_CLERK_ID);
+        clerkUserInfoService.updateTokenById(ApiTestDataSeeder.DEFAULT_CLERK_ID, clerkToken);
+
+        when(ossFileService.upload(any(), eq(ApiTestDataSeeder.DEFAULT_TENANT_ID), anyString()))
+                .thenReturn(
+                        "https://oss.mock/apitest/album-a.png",
+                        "https://oss.mock/apitest/album-b.png",
+                        "https://oss.mock/apitest/album-c.png",
+                        "https://oss.mock/apitest/album-d.png");
+
+        String mediaIdA = extractMediaIdFromUpload(buildTinyPng("album-a.png"), clerkToken);
+        String mediaIdB = extractMediaIdFromUpload(buildTinyPng("album-b.png"), clerkToken);
+        String mediaIdC = extractMediaIdFromUpload(buildTinyPng("album-c.png"), clerkToken);
+        String mediaIdD = extractMediaIdFromUpload(buildTinyPng("album-d.png"), clerkToken);
+
+        List<String> allMediaIds = List.of(mediaIdA, mediaIdB, mediaIdC, mediaIdD);
+
+        submitAlbumUpdate(allMediaIds, clerkToken);
+        ensureTenantContext();
+        approveLatestAlbumReview();
+
+        List<PlayClerkMediaAssetEntity> assetsAfterFirstApprove = mediaAssetService
+                .listActiveByUsage(ApiTestDataSeeder.DEFAULT_CLERK_ID, ClerkMediaUsage.PROFILE);
+        assertThat(assetsAfterFirstApprove)
+                .extracting(PlayClerkMediaAssetEntity::getMediaId)
+                .containsAll(allMediaIds);
+        List<String> reviewStatesForNewMedia = assetsAfterFirstApprove.stream()
+                .filter(asset -> allMediaIds.contains(asset.getMediaId()))
+                .map(PlayClerkMediaAssetEntity::getReviewState)
+                .collect(Collectors.toList());
+        assertThat(reviewStatesForNewMedia).containsOnly(ClerkMediaReviewState.APPROVED.getCode());
+
+        List<String> clerkVisibleMediaIdsAfterFirst = assetsAfterFirstApprove.stream()
+                .filter(asset -> !ClerkMediaReviewState.REJECTED.getCode().equals(asset.getReviewState()))
+                .map(PlayClerkMediaAssetEntity::getMediaId)
+                .collect(Collectors.toList());
+        assertThat(clerkVisibleMediaIdsAfterFirst).containsAll(allMediaIds);
+
+        PlayClerkUserInfoResultVo customerDetailAfterFirst =
+                clerkUserInfoService.buildCustomerDetail(ApiTestDataSeeder.DEFAULT_CLERK_ID, "");
+        List<String> customerMediaIdsAfterFirst = customerDetailAfterFirst.getMediaList().stream()
+                .map(MediaVo::getMediaId)
+                .collect(Collectors.toList());
+        assertThat(customerMediaIdsAfterFirst).containsAll(allMediaIds);
+
+        List<String> keptMedia = List.of(mediaIdA, mediaIdC);
+
+        // 第二次提交：只删除与重新排序，不再生成新的资料审核记录，应直接生效
+        long reviewCountBeforeSecond = dataReviewInfoService.lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId,
+                        ApiTestDataSeeder.DEFAULT_CLERK_ID)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .count();
+        submitAlbumUpdate(keptMedia, clerkToken);
+        ensureTenantContext();
+        long reviewCountAfterSecond = dataReviewInfoService.lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId,
+                        ApiTestDataSeeder.DEFAULT_CLERK_ID)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .count();
+        assertThat(reviewCountAfterSecond)
+                .as("deleting/reordering album should not create another review record")
+                .isEqualTo(reviewCountBeforeSecond);
+
+        List<PlayClerkMediaAssetEntity> assetsAfterSecondApprove = mediaAssetService
+                .listActiveByUsage(ApiTestDataSeeder.DEFAULT_CLERK_ID, ClerkMediaUsage.PROFILE);
+
+        PlayClerkMediaAssetEntity assetA = assetsAfterSecondApprove.stream()
+                .filter(a -> mediaIdA.equals(a.getMediaId()))
+                .max(Comparator.comparing(PlayClerkMediaAssetEntity::getCreatedTime))
+                .orElse(null);
+        PlayClerkMediaAssetEntity assetC = assetsAfterSecondApprove.stream()
+                .filter(a -> mediaIdC.equals(a.getMediaId()))
+                .max(Comparator.comparing(PlayClerkMediaAssetEntity::getCreatedTime))
+                .orElse(null);
+        assertThat(assetA.getReviewState()).isEqualTo(ClerkMediaReviewState.APPROVED.getCode());
+        assertThat(assetA.getOrderIndex()).isEqualTo(0);
+        assertThat(assetC.getReviewState()).isEqualTo(ClerkMediaReviewState.APPROVED.getCode());
+        assertThat(assetC.getOrderIndex()).isEqualTo(1);
+
+        PlayClerkUserInfoResultVo customerDetailAfterSecond =
+                clerkUserInfoService.buildCustomerDetail(ApiTestDataSeeder.DEFAULT_CLERK_ID, "");
+        List<String> customerMediaIdsAfterSecond = customerDetailAfterSecond.getMediaList().stream()
+                .map(MediaVo::getMediaId)
+                .collect(Collectors.toList());
+        assertThat(customerMediaIdsAfterSecond)
+                .contains(mediaIdA, mediaIdC)
+                .doesNotContain(mediaIdB, mediaIdD);
+
+        List<String> clerkVisibleMediaIdsAfterSecond = assetsAfterSecondApprove.stream()
+                .filter(asset -> !ClerkMediaReviewState.REJECTED.getCode().equals(asset.getReviewState()))
+                .map(PlayClerkMediaAssetEntity::getMediaId)
+                .collect(Collectors.toList());
+        assertThat(clerkVisibleMediaIdsAfterSecond)
+                .contains(mediaIdA, mediaIdC)
+                .doesNotContain(mediaIdB, mediaIdD);
+    }
+
+    private MockMultipartFile buildTinyPng(String filename) throws Exception {
+        BufferedImage image = new BufferedImage(2, 2, BufferedImage.TYPE_INT_RGB);
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        ImageIO.write(image, "png", baos);
+        return new MockMultipartFile("file", filename, "image/png", baos.toByteArray());
+    }
+
+    private String extractMediaIdFromUpload(MockMultipartFile file, String clerkToken) throws Exception {
+        MvcResult result = mockMvc.perform(multipart("/wx/clerk/media/upload")
+                        .file(file)
+                        .param("usage", "profile")
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(Constants.CLERK_USER_LOGIN_TOKEN, Constants.TOKEN_PREFIX + clerkToken)
+                        .contentType(MediaType.MULTIPART_FORM_DATA))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andReturn();
+        String body = result.getResponse().getContentAsString();
+        JsonNode root = objectMapper.readTree(body);
+        return root.path("data").path("mediaId").asText();
+    }
+
+    private void submitAlbumUpdate(List<String> mediaIds, String clerkToken) throws Exception {
+        ObjectNode payload = objectMapper.createObjectNode();
+        com.fasterxml.jackson.databind.node.ArrayNode albumArray = payload.putArray("album");
+        mediaIds.forEach(albumArray::add);
+
+        mockMvc.perform(org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post("/wx/clerk/user/updateAlbum")
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(Constants.CLERK_USER_LOGIN_TOKEN, Constants.TOKEN_PREFIX + clerkToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(payload.toString()))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+    }
+
+    private void approveLatestAlbumReview() {
+        List<com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity> reviews = dataReviewInfoService
+                .lambdaQuery()
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getClerkId,
+                        ApiTestDataSeeder.DEFAULT_CLERK_ID)
+                .eq(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getDataType, "2")
+                .orderByDesc(com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity::getAddTime)
+                .list();
+        assertThat(reviews).isNotEmpty();
+        com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity latest = reviews.get(0);
+
+        com.starry.admin.modules.clerk.module.vo.PlayClerkDataReviewStateEditVo vo =
+                new com.starry.admin.modules.clerk.module.vo.PlayClerkDataReviewStateEditVo();
+        vo.setId(latest.getId());
+        vo.setReviewState(ClerkReviewState.APPROVED);
+        vo.setReviewCon("ok");
+        vo.setReviewTime(LocalDateTime.now());
+        dataReviewInfoService.updateDataReviewState(vo);
+    }
+
+    private void ensureTenantContext() {
+        SecurityUtils.setTenantId(ApiTestDataSeeder.DEFAULT_TENANT_ID);
+    }
+}

play-admin/src/test/java/com/starry/admin/api/WxClerkUserBackwardCompatApiTest.java

@@ -0,0 +1,206 @@
+package com.starry.admin.api;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.starry.admin.common.apitest.ApiTestDataSeeder;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkUserInfoService;
+import com.starry.admin.modules.media.enums.MediaStatus;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import com.starry.admin.modules.weichat.entity.clerk.PlayClerkUserInfoResultVo;
+import com.starry.admin.utils.SecurityUtils;
+import com.starry.common.utils.IdUtils;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MvcResult;
+
+/**
+ * 覆盖微信顾客端店员列表 / 详情在仅存在历史相册数据时的兼容行为。
+ *
+ * <p>重点校验：
+ * <ul>
+ *     <li>旧字段 {@code album} 在列表接口中仍然可见；</li>
+ *     <li>同时会被折叠进 {@code mediaList}，且不会破坏后续媒资结构（id/url/usage/status/reviewState）；</li>
+ *     <li>详情接口中 {@link PlayClerkUserInfoResultVo#mediaList} 也包含这些历史相册。</li>
+ * </ul>
+ * </p>
+ */
+class WxClerkUserBackwardCompatApiTest extends AbstractApiTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Autowired
+    private IPlayClerkUserInfoService clerkUserInfoService;
+
+    private final List<String> clerkIdsToCleanup = new ArrayList<>();
+
+    @AfterEach
+    void tearDown() {
+        ensureTenantContext();
+        if (!clerkIdsToCleanup.isEmpty()) {
+            clerkUserInfoService.removeByIds(clerkIdsToCleanup);
+            clerkIdsToCleanup.clear();
+        }
+    }
+
+    /**
+     * 场景：只有旧相册(album) 而没有 play_media / play_clerk_media_asset 记录时，
+     * 微信顾客端列表接口仍然返回可用的 album 和 mediaList。
+     */
+    @Test
+    void customerListIncludesLegacyAlbumAsMediaList() throws Exception {
+        ensureTenantContext();
+        String marker = "legacy-album-" + IdUtils.getUuid().substring(0, 8);
+        List<String> legacyAlbum = List.of(
+                "https://example.com/apitest/legacy/" + marker + "-a.png",
+                "https://example.com/apitest/legacy/" + marker + "-b.png");
+        String clerkId = createLegacyAlbumClerk(marker, legacyAlbum);
+
+        ObjectNode payload = objectMapper.createObjectNode();
+        payload.put("pageNum", 1);
+        payload.put("pageSize", 20);
+        payload.put("nickname", marker);
+        payload.put("typeId", "");
+        payload.put("levelId", "");
+        payload.put("sex", "");
+        payload.put("province", "");
+
+        MvcResult result = mockMvc.perform(post("/wx/clerk/user/queryByPage")
+                        .header(TENANT_HEADER, DEFAULT_TENANT)
+                        .header(USER_HEADER, DEFAULT_USER)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(payload.toString()))
+                .andExpect(status().isOk())
+                .andReturn();
+
+        String body = result.getResponse().getContentAsString();
+        JsonNode root = objectMapper.readTree(body);
+        assertThat(root.path("code").asInt()).as("response=%s", body).isEqualTo(200);
+
+        JsonNode records = root.path("data").path("records");
+        assertThat(records.isArray()).as("records should be array, response=%s", body).isTrue();
+
+        JsonNode target = null;
+        for (JsonNode record : records) {
+            if (clerkId.equals(record.path("id").asText())) {
+                target = record;
+                break;
+            }
+        }
+        assertThat(target)
+                .withFailMessage("列表中未找到目标店员 %s, response=%s", clerkId, body)
+                .isNotNull();
+
+        // album 字段仍然保留原有的历史值
+        JsonNode albumNode = target.path("album");
+        assertThat(albumNode.isArray()).isTrue();
+        Set<String> albumUrls = new HashSet<>();
+        albumNode.forEach(node -> albumUrls.add(node.asText()));
+        assertThat(albumUrls).containsExactlyInAnyOrderElementsOf(legacyAlbum);
+
+        // mediaList 中应当包含折叠后的 Legacy 媒资，并为其补齐 usage/status/reviewState 等字段
+        JsonNode mediaListNode = target.path("mediaList");
+        assertThat(mediaListNode.isArray()).isTrue();
+        assertThat(mediaListNode.size()).isEqualTo(legacyAlbum.size());
+
+        Set<String> mediaUrls = new HashSet<>();
+        for (JsonNode media : mediaListNode) {
+            String url = media.path("url").asText();
+            mediaUrls.add(url);
+            if (!legacyAlbum.contains(url)) {
+                continue;
+            }
+            // 对于从 album 折叠出来的条目，我们要求：
+            // id 与 url 相同；usage/status/reviewState 均为兼容值。
+            assertThat(media.path("id").asText()).isEqualTo(url);
+            assertThat(media.path("usage").asText()).isEqualTo(ClerkMediaUsage.PROFILE.getCode());
+            assertThat(media.path("status").asText()).isEqualTo(MediaStatus.READY.getCode());
+            assertThat(media.path("reviewState").asText())
+                    .isEqualTo(ClerkMediaReviewState.APPROVED.getCode());
+        }
+        assertThat(mediaUrls).containsAll(legacyAlbum);
+    }
+
+    /**
+     * 场景：只有旧相册(album) 数据时，顾客端店员详情接口 buildCustomerDetail 也会将其折叠进 mediaList，
+     * 同时保留 album 字段不变。
+     */
+    @Test
+    void customerDetailMergesLegacyAlbumIntoMediaList() {
+        ensureTenantContext();
+        String marker = "legacy-detail-" + IdUtils.getUuid().substring(0, 8);
+        List<String> legacyAlbum = List.of(
+                "https://example.com/apitest/legacy/" + marker + "-a.png",
+                "https://example.com/apitest/legacy/" + marker + "-b.png");
+        String clerkId = createLegacyAlbumClerk(marker, legacyAlbum);
+
+        PlayClerkUserInfoResultVo detail = clerkUserInfoService.buildCustomerDetail(clerkId, "");
+
+        assertThat(detail.getAlbum()).containsExactlyElementsOf(legacyAlbum);
+        List<MediaVo> mediaList = detail.getMediaList();
+        assertThat(mediaList).isNotNull();
+        assertThat(mediaList).hasSize(legacyAlbum.size());
+
+        Set<String> mediaUrls = new HashSet<>();
+        for (MediaVo media : mediaList) {
+            String url = media.getUrl();
+            mediaUrls.add(url);
+            if (!legacyAlbum.contains(url)) {
+                continue;
+            }
+            assertThat(media.getId()).isEqualTo(url);
+            assertThat(media.getUsage()).isEqualTo(ClerkMediaUsage.PROFILE.getCode());
+            assertThat(media.getStatus()).isEqualTo(MediaStatus.READY.getCode());
+            assertThat(media.getReviewState()).isEqualTo(ClerkMediaReviewState.APPROVED.getCode());
+        }
+        assertThat(mediaUrls).containsAll(legacyAlbum);
+    }
+
+    private String createLegacyAlbumClerk(String marker, List<String> album) {
+        String clerkId = IdUtils.getUuid();
+        PlayClerkUserInfoEntity clerk = new PlayClerkUserInfoEntity();
+        clerk.setId(clerkId);
+        clerk.setTenantId(ApiTestDataSeeder.DEFAULT_TENANT_ID);
+        clerk.setNickname("兼容测试店员-" + marker);
+        clerk.setLevelId(ApiTestDataSeeder.DEFAULT_CLERK_LEVEL_ID);
+        clerk.setClerkState("1");
+        clerk.setOnboardingState("1");
+        clerk.setListingState("1");
+        clerk.setDisplayState("1");
+        clerk.setRecommendationState("0");
+        clerk.setPinToTopState("0");
+        clerk.setRandomOrderState("1");
+        clerk.setFixingLevel("0");
+        clerk.setOnlineState("1");
+        clerk.setPhone("138" + clerkId.substring(0, 8));
+        clerk.setOpenid("openid-legacy-" + marker);
+        clerk.setWeiChatCode("wx-code-legacy-" + marker);
+        clerk.setTypeId("api-type-legacy");
+        clerk.setProvince("API省");
+        clerk.setCity("API市");
+        clerk.setEntryTime(LocalDateTime.now());
+        clerk.setAddTime(LocalDateTime.now());
+        clerk.setAlbum(new ArrayList<>(album));
+        clerkUserInfoService.save(clerk);
+        clerkIdsToCleanup.add(clerkId);
+        return clerkId;
+    }
+
+    private void ensureTenantContext() {
+        SecurityUtils.setTenantId(ApiTestDataSeeder.DEFAULT_TENANT_ID);
+    }
+}

play-admin/src/test/java/com/starry/admin/modules/clerk/service/impl/PlayClerkDataReviewInfoServiceImplTest.java

@@ -0,0 +1,235 @@
+package com.starry.admin.modules.clerk.service.impl;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkDataReviewInfoEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.module.enums.ClerkDataType;
+import com.starry.admin.modules.clerk.module.vo.PlayClerkDataReviewReturnVo;
+import com.starry.admin.modules.clerk.module.vo.PlayClerkDataReviewStateEditVo;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.clerk.service.IPlayClerkUserInfoService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.common.enums.ClerkReviewState;
+import java.time.LocalDateTime;
+import java.util.Arrays;
+import java.util.Collections;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.test.util.ReflectionTestUtils;
+
+@ExtendWith(MockitoExtension.class)
+class PlayClerkDataReviewInfoServiceImplTest {
+
+    @Mock
+    private IPlayClerkUserInfoService clerkUserInfoService;
+    @Mock
+    private IPlayClerkMediaAssetService clerkMediaAssetService;
+    @Mock
+    private IPlayMediaService mediaService;
+
+    private PlayClerkDataReviewInfoServiceImpl service;
+
+    @BeforeEach
+    void setUp() {
+        service = spy(new PlayClerkDataReviewInfoServiceImpl());
+        ReflectionTestUtils.setField(service, "playClerkUserInfoService", clerkUserInfoService);
+        ReflectionTestUtils.setField(service, "clerkMediaAssetService", clerkMediaAssetService);
+        ReflectionTestUtils.setField(service, "mediaService", mediaService);
+        org.mockito.Mockito.lenient()
+                .doReturn(true)
+                .when(service)
+                .update(any(PlayClerkDataReviewInfoEntity.class));
+    }
+
+    @Test
+    void updateDataReviewStateShouldSynchronizeAlbumOnApproval() {
+        PlayClerkDataReviewInfoEntity review = buildReview("review-1", "clerk-1", "2",
+                Arrays.asList("media-existing", "media-new"));
+        doReturn(review).when(service).selectPlayClerkDataReviewInfoById("review-1");
+
+        PlayClerkUserInfoEntity clerk = new PlayClerkUserInfoEntity();
+        clerk.setId("clerk-1");
+        clerk.setTenantId("tenant-1");
+        when(clerkUserInfoService.getById("clerk-1")).thenReturn(clerk);
+
+        PlayMediaEntity existingMedia = new PlayMediaEntity();
+        existingMedia.setId("media-existing");
+        when(mediaService.getById("media-existing")).thenReturn(existingMedia);
+        PlayMediaEntity newMedia = new PlayMediaEntity();
+        newMedia.setId("media-new");
+        when(mediaService.getById("media-new")).thenReturn(newMedia);
+
+        PlayClerkMediaAssetEntity assetStub = new PlayClerkMediaAssetEntity();
+        assetStub.setId("asset-1");
+        when(clerkMediaAssetService.linkDraftAsset(any(), any(), any(), any())).thenReturn(assetStub);
+
+        PlayClerkDataReviewStateEditVo vo = new PlayClerkDataReviewStateEditVo();
+        vo.setId("review-1");
+        vo.setReviewState(ClerkReviewState.APPROVED);
+        vo.setReviewCon("ok");
+
+        service.updateDataReviewState(vo);
+
+        verify(clerkMediaAssetService).linkDraftAsset(eq("tenant-1"), eq("clerk-1"), eq("media-existing"),
+                eq(ClerkMediaUsage.PROFILE));
+        verify(clerkMediaAssetService).linkDraftAsset(eq("tenant-1"), eq("clerk-1"), eq("media-new"), eq(ClerkMediaUsage.PROFILE));
+        verify(clerkMediaAssetService).applyReviewDecision(eq("clerk-1"), eq(ClerkMediaUsage.PROFILE),
+                eq(Arrays.asList("media-existing", "media-new")), eq("review-1"), eq("ok"));
+        verify(clerkUserInfoService).update(any(PlayClerkUserInfoEntity.class));
+    }
+
+    @Test
+    void updateDataReviewStateThrowsWhenClerkMissing() {
+        PlayClerkDataReviewInfoEntity review = buildReview("review-2", "ghost", "2",
+                Collections.singletonList("media"));
+        doReturn(review).when(service).selectPlayClerkDataReviewInfoById("review-2");
+        when(clerkUserInfoService.getById("ghost")).thenReturn(null);
+
+        PlayClerkDataReviewStateEditVo vo = new PlayClerkDataReviewStateEditVo();
+        vo.setId("review-2");
+        vo.setReviewState(ClerkReviewState.APPROVED);
+
+        assertThatThrownBy(() -> service.updateDataReviewState(vo))
+                .isInstanceOf(CustomException.class)
+                .hasMessageContaining("店员信息不存在");
+    }
+
+    @Test
+    void enrichDataContentWithMediaPreviewPopulatesCoverAndVideoUrls() {
+        PlayClerkDataReviewInfoServiceImpl impl = service;
+
+        PlayClerkDataReviewReturnVo videoRow = new PlayClerkDataReviewReturnVo();
+        videoRow.setId("row-video");
+        videoRow.setDataTypeEnum(ClerkDataType.PHOTO_ALBUM);
+        videoRow.setDataContent(java.util.Collections.singletonList("media-video"));
+
+        PlayClerkDataReviewReturnVo imageRow = new PlayClerkDataReviewReturnVo();
+        imageRow.setId("row-image");
+        imageRow.setDataTypeEnum(ClerkDataType.PHOTO_ALBUM);
+        imageRow.setDataContent(java.util.Collections.singletonList("media-image"));
+
+        IPage<PlayClerkDataReviewReturnVo> page = new Page<>(1, 10);
+        page.setRecords(java.util.Arrays.asList(videoRow, imageRow));
+
+        PlayMediaEntity videoMedia = new PlayMediaEntity();
+        videoMedia.setId("media-video");
+        videoMedia.setKind(com.starry.admin.modules.media.enums.MediaKind.VIDEO.getCode());
+        videoMedia.setUrl("https://oss/video.mp4");
+        videoMedia.setCoverUrl("https://oss/video-cover.jpg");
+
+        PlayMediaEntity imageMedia = new PlayMediaEntity();
+        imageMedia.setId("media-image");
+        imageMedia.setKind(com.starry.admin.modules.media.enums.MediaKind.IMAGE.getCode());
+        imageMedia.setUrl("https://oss/image.png");
+
+        when(mediaService.getById("media-video")).thenReturn(videoMedia);
+        when(mediaService.getById("media-image")).thenReturn(imageMedia);
+
+        org.springframework.test.util.ReflectionTestUtils.invokeMethod(
+                impl, "enrichDataContentWithMediaPreview", page);
+
+        assertThat(videoRow.getDataContent()).containsExactly("https://oss/video-cover.jpg");
+        assertThat(videoRow.getMediaVideoUrls()).containsExactly("https://oss/video.mp4");
+
+        assertThat(imageRow.getDataContent()).containsExactly("https://oss/image.png");
+        assertThat(imageRow.getMediaVideoUrls()).containsExactly((String) null);
+    }
+
+    @Test
+    void enrichDataContentWithMediaPreviewFallsBackToLegacyUrlWhenMediaMissing() {
+        PlayClerkDataReviewInfoServiceImpl impl = service;
+
+        String legacyUrl = "https://oss/legacy-only.png";
+        PlayClerkDataReviewReturnVo row = new PlayClerkDataReviewReturnVo();
+        row.setId("row-legacy");
+        row.setDataTypeEnum(ClerkDataType.PHOTO_ALBUM);
+        row.setDataContent(java.util.Collections.singletonList(legacyUrl));
+
+        IPage<PlayClerkDataReviewReturnVo> page = new Page<>(1, 10);
+        page.setRecords(java.util.Collections.singletonList(row));
+
+        // 当无法通过 mediaId 查询到记录时，应当保持 dataContent 为原始 URL，
+        // 并且对应的 mediaVideoUrls 位置为 null。
+        when(mediaService.getById(legacyUrl)).thenReturn(null);
+
+        org.springframework.test.util.ReflectionTestUtils.invokeMethod(
+                impl, "enrichDataContentWithMediaPreview", page);
+
+        assertThat(row.getDataContent()).containsExactly(legacyUrl);
+        assertThat(row.getMediaVideoUrls()).containsExactly((String) null);
+    }
+
+    @Test
+    void updateDataReviewStateUpdatesAvatarOnApproval() {
+        PlayClerkDataReviewInfoEntity review = buildReview("review-avatar", "clerk-1", "1",
+                java.util.Collections.singletonList("https://oss/avatar.png"));
+        // 审核服务内部通过 selectPlayClerkDataReviewInfoById 查询审核记录
+        org.mockito.Mockito.doReturn(review).when(service).selectPlayClerkDataReviewInfoById("review-avatar");
+
+        PlayClerkDataReviewStateEditVo vo = new PlayClerkDataReviewStateEditVo();
+        vo.setId("review-avatar");
+        vo.setReviewState(ClerkReviewState.APPROVED);
+
+        service.updateDataReviewState(vo);
+
+        ArgumentCaptor<PlayClerkUserInfoEntity> captor = ArgumentCaptor.forClass(PlayClerkUserInfoEntity.class);
+        verify(clerkUserInfoService).update(captor.capture());
+        PlayClerkUserInfoEntity updated = captor.getValue();
+        assertThat(updated.getId()).isEqualTo("clerk-1");
+        assertThat(updated.getAvatar()).isEqualTo("https://oss/avatar.png");
+        // 其他字段不应被误改
+        assertThat(updated.getNickname()).isNull();
+        assertThat(updated.getAudio()).isNull();
+    }
+
+    @Test
+    void updateDataReviewStateUpdatesAudioOnApproval() {
+        PlayClerkDataReviewInfoEntity review = buildReview("review-audio", "clerk-2", "3",
+                java.util.Collections.singletonList("https://oss/audio.m4a"));
+        org.mockito.Mockito.doReturn(review).when(service).selectPlayClerkDataReviewInfoById("review-audio");
+
+        PlayClerkDataReviewStateEditVo vo = new PlayClerkDataReviewStateEditVo();
+        vo.setId("review-audio");
+        vo.setReviewState(ClerkReviewState.APPROVED);
+
+        service.updateDataReviewState(vo);
+
+        ArgumentCaptor<PlayClerkUserInfoEntity> captor = ArgumentCaptor.forClass(PlayClerkUserInfoEntity.class);
+        verify(clerkUserInfoService, org.mockito.Mockito.atLeastOnce()).update(captor.capture());
+        PlayClerkUserInfoEntity updated = captor.getValue();
+        assertThat(updated.getId()).isEqualTo("clerk-2");
+        assertThat(updated.getAudio()).isEqualTo("https://oss/audio.m4a");
+        assertThat(updated.getNickname()).isNull();
+        assertThat(updated.getAvatar()).isNull();
+    }
+
+    private PlayClerkDataReviewInfoEntity buildReview(String id, String clerkId, String dataType,
+            java.util.List<String> payload) {
+        PlayClerkDataReviewInfoEntity entity = new PlayClerkDataReviewInfoEntity();
+        entity.setId(id);
+        entity.setClerkId(clerkId);
+        entity.setDataType(dataType);
+        entity.setDataContent(payload);
+        entity.setAddTime(LocalDateTime.now());
+        return entity;
+    }
+}

play-admin/src/test/java/com/starry/admin/modules/clerk/service/impl/PlayClerkMediaAssetServiceImplTest.java

@@ -0,0 +1,128 @@
+package com.starry.admin.modules.clerk.service.impl;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.when;
+
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.List;
+import java.util.stream.Collectors;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.test.util.ReflectionTestUtils;
+
+@ExtendWith(MockitoExtension.class)
+class PlayClerkMediaAssetServiceImplTest {
+
+    @Mock
+    private IPlayMediaService mediaService;
+
+    @Test
+    void submitWithOrderShouldReindexAndFlagPending() {
+        PlayClerkMediaAssetServiceImpl service = org.mockito.Mockito.spy(new PlayClerkMediaAssetServiceImpl());
+        ReflectionTestUtils.setField(service, "mediaService", mediaService);
+        List<PlayClerkMediaAssetEntity> assets = Arrays.asList(
+                buildAsset("A", "media-a", 0),
+                buildAsset("B", "media-b", 1),
+                buildAsset("C", "media-c", 2));
+
+        doReturn(assets).when(service).listActiveByUsage("clerk-1", ClerkMediaUsage.PROFILE);
+
+        java.util.List<java.util.List<PlayClerkMediaAssetEntity>> batches = new java.util.ArrayList<>();
+        org.mockito.Mockito.doAnswer(inv -> {
+            java.util.Collection<PlayClerkMediaAssetEntity> collection = inv.getArgument(0);
+            batches.add(new java.util.ArrayList<>(collection));
+            return true;
+        }).when(service).updateBatchById(any());
+
+        service.submitWithOrder("clerk-1", ClerkMediaUsage.PROFILE, Arrays.asList("media-b", "media-a"));
+
+        List<PlayClerkMediaAssetEntity> updates = flatten(batches);
+        PlayClerkMediaAssetEntity b = find(updates, "B");
+        PlayClerkMediaAssetEntity a = find(updates, "A");
+        PlayClerkMediaAssetEntity c = find(updates, "C");
+
+        assertThat(b.getOrderIndex()).isEqualTo(0);
+        assertThat(b.getReviewState()).isEqualTo(ClerkMediaReviewState.PENDING.getCode());
+        assertThat(a.getOrderIndex()).isEqualTo(1);
+        assertThat(a.getReviewState()).isEqualTo(ClerkMediaReviewState.PENDING.getCode());
+        assertThat(c.getReviewState()).isEqualTo(ClerkMediaReviewState.REJECTED.getCode());
+    }
+
+    @Test
+    void applyReviewDecisionShouldApproveAndReject() {
+        PlayClerkMediaAssetServiceImpl service = org.mockito.Mockito.spy(new PlayClerkMediaAssetServiceImpl());
+        ReflectionTestUtils.setField(service, "mediaService", mediaService);
+        List<PlayClerkMediaAssetEntity> assets = Arrays.asList(
+                buildAsset("A", "media-1", 0),
+                buildAsset("B", "media-2", 1));
+
+        doReturn(assets).when(service).listActiveByUsage("clerk-1", ClerkMediaUsage.PROFILE);
+        when(mediaService.listByIds(any())).thenReturn(Arrays.asList(
+                buildMedia("media-1"),
+                buildMedia("media-2")));
+
+        java.util.List<java.util.List<PlayClerkMediaAssetEntity>> batches = new java.util.ArrayList<>();
+        org.mockito.Mockito.doAnswer(inv -> {
+            java.util.Collection<PlayClerkMediaAssetEntity> collection = inv.getArgument(0);
+            batches.add(new java.util.ArrayList<>(collection));
+            return true;
+        }).when(service).updateBatchById(any());
+
+        service.applyReviewDecision("clerk-1", ClerkMediaUsage.PROFILE, Arrays.asList("media-2"), "review-1", "ok");
+
+        List<PlayClerkMediaAssetEntity> updates = flatten(batches);
+        PlayClerkMediaAssetEntity approved = find(updates, "B");
+        PlayClerkMediaAssetEntity rejected = find(updates, "A");
+
+        assertThat(approved.getReviewState()).isEqualTo(ClerkMediaReviewState.APPROVED.getCode());
+        assertThat(approved.getOrderIndex()).isEqualTo(0);
+        assertThat(approved.getReviewRecordId()).isEqualTo("review-1");
+        assertThat(rejected.getReviewState()).isEqualTo(ClerkMediaReviewState.REJECTED.getCode());
+    }
+
+    private static PlayClerkMediaAssetEntity buildAsset(String id, String mediaId, int order) {
+        PlayClerkMediaAssetEntity entity = new PlayClerkMediaAssetEntity();
+        entity.setId(id);
+        entity.setClerkId("clerk-1");
+        entity.setTenantId("tenant-1");
+        entity.setMediaId(mediaId);
+        entity.setUsage(ClerkMediaUsage.PROFILE.getCode());
+        entity.setReviewState(ClerkMediaReviewState.DRAFT.getCode());
+        entity.setOrderIndex(order);
+        entity.setSubmittedTime(LocalDateTime.now());
+        return entity;
+    }
+
+    private static PlayMediaEntity buildMedia(String id) {
+        PlayMediaEntity media = new PlayMediaEntity();
+        media.setId(id);
+        media.setUrl("url-" + id);
+        return media;
+    }
+
+    private static PlayClerkMediaAssetEntity find(List<PlayClerkMediaAssetEntity> updates, String id) {
+        return updates.stream()
+                .filter(asset -> id.equals(asset.getId()))
+                .findFirst()
+                .orElseThrow();
+    }
+
+    @SuppressWarnings("unchecked")
+    private static List<PlayClerkMediaAssetEntity> flatten(List<? extends List<PlayClerkMediaAssetEntity>> captured) {
+        return captured.stream()
+                .flatMap(List::stream)
+                .collect(Collectors.toCollection(ArrayList::new));
+    }
+}

play-admin/src/test/java/com/starry/admin/modules/clerk/service/impl/PlayClerkUserInfoServiceImplTest.java

@@ -0,0 +1,46 @@
+package com.starry.admin.modules.clerk.service.impl;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+class PlayClerkUserInfoServiceImplTest {
+
+    @Test
+    void mergeLegacyAlbumAppendsUniqueUrls() {
+        List<String> legacy = Arrays.asList("https://oss/1.png", " ", "https://oss/2.png", "https://oss/1.png");
+        List<MediaVo> destination = new ArrayList<>();
+        MediaVo existing = new MediaVo();
+        existing.setUrl("https://oss/2.png");
+        destination.add(existing);
+
+        List<MediaVo> merged = PlayClerkUserInfoServiceImpl.mergeLegacyAlbum(legacy, destination);
+
+        assertThat(merged).hasSize(2);
+        assertThat(merged.stream().map(MediaVo::getUrl))
+                .containsExactlyInAnyOrder("https://oss/2.png", "https://oss/1.png");
+    }
+
+    @Test
+    void mergeLegacyAlbumFillsUsageStatusAndReviewStateForLegacyEntries() {
+        List<String> legacy = Arrays.asList("https://oss/legacy-only.png");
+        List<MediaVo> destination = new ArrayList<>();
+
+        List<MediaVo> merged = PlayClerkUserInfoServiceImpl.mergeLegacyAlbum(legacy, destination);
+
+        assertThat(merged).hasSize(1);
+        MediaVo legacyVo = merged.get(0);
+        assertThat(legacyVo.getUrl()).isEqualTo("https://oss/legacy-only.png");
+        assertThat(legacyVo.getId())
+                .as("legacy media id should fallback to url for compatibility")
+                .isEqualTo("https://oss/legacy-only.png");
+        assertThat(legacyVo.getUsage()).isEqualTo(com.starry.admin.modules.clerk.enums.ClerkMediaUsage.PROFILE.getCode());
+        assertThat(legacyVo.getStatus()).isEqualTo(com.starry.admin.modules.media.enums.MediaStatus.READY.getCode());
+        assertThat(legacyVo.getReviewState())
+                .isEqualTo(com.starry.admin.modules.clerk.enums.ClerkMediaReviewState.APPROVED.getCode());
+    }
+}

play-admin/src/test/java/com/starry/admin/modules/weichat/controller/WxClerkMediaControllerTest.java

@@ -0,0 +1,143 @@
+package com.starry.admin.modules.weichat.controller;
+
+import static org.hamcrest.Matchers.hasSize;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.multipart;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.starry.admin.common.conf.ThreadLocalRequestDetail;
+import com.starry.admin.modules.clerk.enums.ClerkMediaReviewState;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.admin.modules.weichat.entity.clerk.MediaOrderRequest;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import com.starry.admin.modules.weichat.service.MediaUploadService;
+import java.time.LocalDateTime;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.http.MediaType;
+import org.springframework.mock.web.MockMultipartFile;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+
+@ExtendWith(MockitoExtension.class)
+public class WxClerkMediaControllerTest {
+
+    @Mock
+    private MediaUploadService mediaUploadService;
+    @Mock
+    private IPlayMediaService mediaService;
+    @Mock
+    private IPlayClerkMediaAssetService clerkMediaAssetService;
+    @InjectMocks
+    private WxClerkMediaController controller;
+
+    private MockMvc mockMvc;
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    private PlayClerkUserInfoEntity clerk;
+
+    @BeforeEach
+    void setUp() {
+        mockMvc = MockMvcBuilders.standaloneSetup(controller).build();
+        clerk = new PlayClerkUserInfoEntity();
+        clerk.setId("clerk-1");
+        clerk.setTenantId("tenant-1");
+        ThreadLocalRequestDetail.setRequestDetail(clerk);
+    }
+
+    @AfterEach
+    void tearDown() {
+        ThreadLocalRequestDetail.remove();
+    }
+
+    @Test
+    void uploadShouldReturnMediaVo() throws Exception {
+        MediaVo vo = new MediaVo();
+        vo.setId("media-1");
+        vo.setUsage(ClerkMediaUsage.PROFILE.getCode());
+        when(mediaUploadService.upload(any(), eq(clerk), eq(ClerkMediaUsage.PROFILE))).thenReturn(vo);
+
+        MockMultipartFile file = new MockMultipartFile("file", "avatar.png", "image/png", new byte[] {1, 2});
+
+        mockMvc.perform(multipart("/wx/clerk/media/upload")
+                        .file(file)
+                        .param("usage", ClerkMediaUsage.PROFILE.getCode()))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.id").value("media-1"));
+    }
+
+    @Test
+    void updateOrderShouldDelegateToService() throws Exception {
+        MediaOrderRequest request = new MediaOrderRequest();
+        request.setUsage(ClerkMediaUsage.PROFILE.getCode());
+        request.setMediaIds(Arrays.asList("m1", "m2"));
+
+        mockMvc.perform(put("/wx/clerk/media/order")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(objectMapper.writeValueAsString(request)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        verify(clerkMediaAssetService).submitWithOrder(eq("clerk-1"), eq(ClerkMediaUsage.PROFILE),
+                eq(Arrays.asList("m1", "m2")));
+    }
+
+    @Test
+    void listApprovedShouldReturnAssemblerOutput() throws Exception {
+        PlayClerkMediaAssetEntity asset = new PlayClerkMediaAssetEntity();
+        asset.setId("asset-1");
+        asset.setClerkId("clerk-1");
+        asset.setUsage(ClerkMediaUsage.PROFILE.getCode());
+        asset.setMediaId("media-1");
+        asset.setReviewState(ClerkMediaReviewState.APPROVED.getCode());
+        asset.setCreatedTime(java.sql.Timestamp.valueOf(LocalDateTime.now()));
+        when(clerkMediaAssetService.listByState(eq("clerk-1"), eq(ClerkMediaUsage.PROFILE),
+                eq(Collections.singletonList(ClerkMediaReviewState.APPROVED)))).thenReturn(
+                        Collections.singletonList(asset));
+
+        PlayMediaEntity media = new PlayMediaEntity();
+        media.setId("media-1");
+        media.setUrl("https://oss/mock.png");
+        when(mediaService.listByIds(Collections.singletonList("media-1")))
+                .thenReturn(Collections.singletonList(media));
+
+        mockMvc.perform(get("/wx/clerk/media/approved"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data", hasSize(1)))
+                .andExpect(jsonPath("$.data[0].url").value("https://oss/mock.png"));
+    }
+
+    @Test
+    void deleteShouldInvokeServices() throws Exception {
+        mockMvc.perform(delete("/wx/clerk/media/{id}", "media-77"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        verify(clerkMediaAssetService).softDelete("clerk-1", "media-77");
+        verify(mediaService).softDelete(MediaOwnerType.CLERK, "clerk-1", "media-77");
+    }
+}

play-admin/src/test/java/com/starry/admin/modules/weichat/service/MediaUploadServiceTest.java

@@ -0,0 +1,137 @@
+package com.starry.admin.modules.weichat.service;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.starry.admin.common.exception.CustomException;
+import com.starry.admin.common.oss.service.IOssFileService;
+import com.starry.admin.modules.clerk.enums.ClerkMediaUsage;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkMediaAssetEntity;
+import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity;
+import com.starry.admin.modules.clerk.service.IPlayClerkMediaAssetService;
+import com.starry.admin.modules.media.entity.PlayMediaEntity;
+import com.starry.admin.modules.media.enums.MediaOwnerType;
+import com.starry.admin.modules.media.service.IPlayMediaService;
+import com.starry.admin.modules.weichat.entity.clerk.MediaVo;
+import java.awt.image.BufferedImage;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import javax.imageio.ImageIO;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.mock.web.MockMultipartFile;
+import org.springframework.web.multipart.MultipartFile;
+
+@ExtendWith(MockitoExtension.class)
+class MediaUploadServiceTest {
+
+    @Mock
+    private IOssFileService ossFileService;
+    @Mock
+    private IPlayMediaService mediaService;
+    @Mock
+    private IPlayClerkMediaAssetService clerkMediaAssetService;
+
+    private MediaUploadService service;
+
+    @BeforeEach
+    void setUp() {
+        service = new MediaUploadService(ossFileService, mediaService, clerkMediaAssetService);
+    }
+
+    @Test
+    @DisplayName("上传图片时应创建媒资与草稿资产，并返回完整的 MediaVo")
+    void uploadImageCreatesMediaAndAsset() throws Exception {
+        PlayClerkUserInfoEntity clerk = buildClerk();
+        MultipartFile file = buildImageFile("avatar.png", "image/png");
+
+        when(mediaService.normalizeAndSave(any())).thenAnswer(invocation -> invocation.getArgument(0));
+        when(ossFileService.upload(any(), eq(clerk.getTenantId()), any()))
+                .thenReturn("https://oss.mock/avatar.png");
+
+        PlayClerkMediaAssetEntity asset = new PlayClerkMediaAssetEntity();
+        asset.setId("asset-1");
+        asset.setUsage(ClerkMediaUsage.PROFILE.getCode());
+        asset.setReviewState("draft");
+        when(clerkMediaAssetService.linkDraftAsset(any(), any(), any(), any())).thenAnswer(invocation -> {
+            asset.setMediaId(invocation.getArgument(2));
+            return asset;
+        });
+
+        MediaVo result = service.upload(file, clerk, null);
+
+        assertThat(result).isNotNull();
+        assertThat(result.getUrl()).isEqualTo("https://oss.mock/avatar.png");
+        assertThat(result.getUsage()).isEqualTo(ClerkMediaUsage.PROFILE.getCode());
+        assertThat(result.getAssetId()).isEqualTo("asset-1");
+
+        ArgumentCaptor<PlayMediaEntity> mediaCaptor = ArgumentCaptor.forClass(PlayMediaEntity.class);
+        verify(mediaService).normalizeAndSave(mediaCaptor.capture());
+        PlayMediaEntity persisted = mediaCaptor.getValue();
+        assertThat(persisted.getOwnerType()).isEqualTo(MediaOwnerType.CLERK);
+        assertThat(persisted.getOwnerId()).isEqualTo(clerk.getId());
+        assertThat(persisted.getMetadata()).containsKeys("originalFilename", "contentType", "uploadTraceId");
+
+        verify(clerkMediaAssetService).linkDraftAsset(
+                eq(clerk.getTenantId()),
+                eq(clerk.getId()),
+                eq(persisted.getId()),
+                eq(ClerkMediaUsage.PROFILE));
+    }
+
+    @Test
+    @DisplayName("不支援的檔案格式應回報錯誤，且不呼叫外部服務")
+    void uploadRejectsUnsupportedFormat() {
+        PlayClerkUserInfoEntity clerk = buildClerk();
+        MultipartFile invalidFile = new MockMultipartFile("file", "note.txt", "text/plain", "oops".getBytes());
+
+        assertThatThrownBy(() -> service.upload(invalidFile, clerk, ClerkMediaUsage.PROFILE))
+                .isInstanceOf(CustomException.class)
+                .hasMessage("不支持的文件格式");
+
+        verify(mediaService, never()).normalizeAndSave(any());
+        verify(ossFileService, never()).upload(any(), any(), any());
+        verify(clerkMediaAssetService, never()).linkDraftAsset(any(), any(), any(), any());
+    }
+
+    @Test
+    @DisplayName("缺少檔案或店員資訊時應回報錯誤")
+    void uploadRejectsMissingInputs() {
+        PlayClerkUserInfoEntity clerk = buildClerk();
+        MultipartFile emptyFile = new MockMultipartFile("file", new byte[0]);
+
+        assertThatThrownBy(() -> service.upload(emptyFile, clerk, ClerkMediaUsage.PROFILE))
+                .isInstanceOf(CustomException.class)
+                .hasMessage("请选择要上传的文件");
+
+        MultipartFile file = new MockMultipartFile("file", "a.png", "image/png", new byte[] {1});
+        assertThatThrownBy(() -> service.upload(file, null, ClerkMediaUsage.PROFILE))
+                .isInstanceOf(CustomException.class)
+                .hasMessage("店员信息不存在");
+    }
+
+    private MultipartFile buildImageFile(String filename, String contentType) throws IOException {
+        BufferedImage image = new BufferedImage(2, 2, BufferedImage.TYPE_INT_RGB);
+        try (ByteArrayOutputStream baos = new ByteArrayOutputStream()) {
+            ImageIO.write(image, "png", baos);
+            return new MockMultipartFile("file", filename, contentType, baos.toByteArray());
+        }
+    }
+
+    private PlayClerkUserInfoEntity buildClerk() {
+        PlayClerkUserInfoEntity entity = new PlayClerkUserInfoEntity();
+        entity.setId("clerk-1");
+        entity.setTenantId("tenant-1");
+        return entity;
+    }
+}