refactor: 全面重构代码并加白话注释，移动全局并行，去掉去向/重复记录

- 重构后端与前端，全程大白话注释（不懂程序也能看懂）
- 移动阶段改为全局并行（MoveAll，工人数=CPU核心数）
- 去掉记录每个文件搬去哪了（删除去向回填，解决写库卡顿）
- 去掉重复文件标记与统计：重复判定改为 MD5+路径都相同才算，重复则原地忽略不移动；MD5 相同但路径不同仍照常搬
- 媒体库去掉归类目录列，看板去掉重复/归类分布统计

internal/probe/brightness.go

@@ -14,18 +14,23 @@ import (
 	_ "golang.org/x/image/webp"
 )
 
+// 明暗分析相关的三个参数：
 const (
-	// brightnessDecodeLimit 明暗分析允许解码的最大像素数，超出时跳过分析（按 mid 归类），避免超大图 OOM
+	// brightnessDecodeLimit 允许分析的最大像素数。超过就跳过分析（按中性归类），
+	// 防止超大图把内存吃爆。
 	brightnessDecodeLimit = 40_000_000
-	// thumbnailMaxEdge 明暗分析时大图缩放后的最长边像素，缩小到该尺寸内再统计
+	// thumbnailMaxEdge 大图缩放后的最长边像素。先缩小再统计，省内存省时间。
 	thumbnailMaxEdge = 256
-	// thumbnailScaleThreshold 像素数超过该值才缩放为缩略图再统计
+	// thumbnailScaleThreshold 像素数超过这个值才缩放成缩略图再统计。
 	thumbnailScaleThreshold = 250_000
 )
 
-// AnalyzeBrightness 打开并解码图片，分析明暗程度。
-// darkScore: 暗色像素（亮度 < 80）占比；lightScore: 亮色像素（亮度 > 175）占比。
-// 超大图（超过 brightnessDecodeLimit 像素）直接跳过分析返回 mid；大图先缩放为缩略图再统计，降低内存与耗时。
+// AnalyzeBrightness 打开一张图片，分析它偏暗还是偏亮。
+//   - darkScore：暗色像素（亮度 < 80）占多少比例
+//   - lightScore：亮色像素（亮度 > 175）占多少比例
+//
+// 超大图直接跳过（返回两个 0，调用方会按"中性"归类）；
+// 普通大图先缩小成缩略图再统计，既快又不失真（整体明暗分布基本保留）。
 func AnalyzeBrightness(filePath string) (darkScore float64, lightScore float64, err error) {
 	f, err := os.Open(filePath)
 	if err != nil {
@@ -33,13 +38,15 @@ func AnalyzeBrightness(filePath string) (darkScore float64, lightScore float64,
 	}
 	defer f.Close()
 
+	// 先只读配置看看多大，太大就不分析了
 	cfg, _, err := image.DecodeConfig(f)
 	if err != nil {
 		return 0, 0, err
 	}
 	if cfg.Width <= 0 || cfg.Height <= 0 || cfg.Width*cfg.Height > brightnessDecodeLimit {
-		return 0, 0, nil // 超大图跳过，由调用方按 mid 归类
+		return 0, 0, nil // 超大图，跳过
 	}
+	// 回到文件开头，重新完整解码
 	if _, err := f.Seek(0, 0); err != nil {
 		return 0, 0, err
 	}
@@ -48,6 +55,7 @@ func AnalyzeBrightness(filePath string) (darkScore float64, lightScore float64,
 		return 0, 0, err
 	}
 
+	// 大图先缩小成缩略图
 	if img.Bounds().Dx()*img.Bounds().Dy() > thumbnailScaleThreshold {
 		img = scaleToThumbnail(img, thumbnailMaxEdge)
 	}
@@ -55,8 +63,8 @@ func AnalyzeBrightness(filePath string) (darkScore float64, lightScore float64,
 	return dark, light, nil
 }
 
-// scaleToThumbnail 将大图等比缩放到最长边不超过 maxEdge 的缩略图（纯内存，不落盘）。
-// 缩放是像素平均，整体亮度分布基本保留，用于粗粒度明暗分类足够准确。
+// scaleToThumbnail 把大图等比缩放到最长边不超过 maxEdge 的缩略图（只占内存，不写盘）。
+// 缩小时是像素平均，整体明暗分布基本保留，用来粗分亮暗足够了。
 func scaleToThumbnail(img image.Image, maxEdge int) image.Image {
 	srcBounds := img.Bounds()
 	srcW, srcH := srcBounds.Dx(), srcBounds.Dy()
@@ -76,9 +84,11 @@ func scaleToThumbnail(img image.Image, maxEdge int) image.Image {
 	return dst
 }
 
-// analyzeBrightness 统计暗色/亮色像素占比（ITU-R BT.601 亮度公式）。
-// 完全透明的像素（alpha=0）不计入统计。
-// 对常见内存布局（NRGBA/RGBA/Gray）直接访问像素数组，避免 image.At 接口逐像素开销。
+// analyzeBrightness 数一数暗色/亮色像素各占多少比例。
+// 用 ITU-R BT.601 的亮度公式算每个像素的"亮度值"。
+// 完全透明的像素（alpha=0）不算数。
+// 为了快，常见的内存格式（NRGBA/RGBA/Gray）直接翻底层像素数组，
+// 不常见的才用慢一点的通用方式。
 func analyzeBrightness(img image.Image) (darkScore float64, lightScore float64) {
 	bounds := img.Bounds()
 	totalPixels := bounds.Dx() * bounds.Dy()
@@ -108,7 +118,8 @@ func analyzeBrightness(img image.Image) (darkScore float64, lightScore float64)
 		for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
 			offset := m.PixOffset(bounds.Min.X, y)
 			for x := bounds.Min.X; x < bounds.Max.X; x++ {
-				// 预乘 alpha：若完全不透明则按直接值，否则近似取非预乘分量
+				// RGBA 是"预乘 alpha"，完全不透明就用原值，
+				// 半透明的按比例还原出真实颜色分量再算亮度
 				a := pix[offset+3]
 				if a == 0 {
 					offset += 4
@@ -126,6 +137,7 @@ func analyzeBrightness(img image.Image) (darkScore float64, lightScore float64)
 			}
 		}
 	case *image.Gray:
+		// 灰度图：像素本身就是亮度值
 		pix := m.Pix
 		for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
 			offset := m.PixOffset(bounds.Min.X, y)
@@ -141,6 +153,7 @@ func analyzeBrightness(img image.Image) (darkScore float64, lightScore float64)
 			}
 		}
 	default:
+		// 其他格式：用通用的读法
 		for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
 			for x := bounds.Min.X; x < bounds.Max.X; x++ {
 				r, g, b, a := img.At(x, y).RGBA()
@@ -159,7 +172,7 @@ func analyzeBrightness(img image.Image) (darkScore float64, lightScore float64)
 	return float64(darkCount) / float64(sampleCount), float64(lightCount) / float64(sampleCount)
 }
 
-// countBrightness 按 BT.601 亮度公式累计暗/亮像素计数
+// countBrightness 按亮度公式（BT.601）判断一个像素偏暗还是偏亮，并计数。
 func countBrightness(r, g, b float64, darkCount, lightCount *int64) {
 	brightness := 0.299*r + 0.587*g + 0.114*b
 	if brightness < 80 {

internal/probe/ffprobe.go

@@ -5,20 +5,22 @@ import (
 	"os"
 )
 
-// FFprobeExeName 释放到当前目录的解码器文件名
+// FFprobeExeName 释放出来的解码器文件名。程序启动时扫到它要跳过，
+// 免得把自己人（ffprobe）当成媒体文件收走了。
 const FFprobeExeName = "ffprobe.exe"
 
-// FFprobePath 返回当前目录下的 ffprobe 可执行路径（Windows/Unix 均可直接执行）
+// FFprobePath 返回当前目录下 ffprobe 的完整路径。
 func FFprobePath() string {
 	return "." + string(os.PathSeparator) + FFprobeExeName
 }
 
-// HasEmbeddedFFprobe 当前平台是否内嵌了 ffprobe
+// HasEmbeddedFFprobe 当前编译出的程序里有没有内嵌 ffprobe。
+// 内嵌的版本只在对应系统里编译时带进去，所以要先问一句有没有。
 func HasEmbeddedFFprobe() bool {
 	return len(embeddedFFprobe) > 0
 }
 
-// ReleaseFFprobe 释放内嵌的 ffprobe 到当前目录（按当前系统自动选择对应版本）
+// ReleaseFFprobe 把内嵌的 ffprobe 释放（写）到当前目录，才能当程序调用它。
 func ReleaseFFprobe() error {
 	if len(embeddedFFprobe) == 0 {
 		return fmt.Errorf("当前系统没有内嵌的ffprobe")
@@ -26,7 +28,7 @@ func ReleaseFFprobe() error {
 	return os.WriteFile(FFprobeExeName, embeddedFFprobe, 0777)
 }
 
-// RemoveFFprobe 删除当前目录下释放的 ffprobe
+// RemoveFFprobe 整理完把临时释放的 ffprobe 删掉，不留在目录里。
 func RemoveFFprobe() {
 	_ = os.Remove(FFprobeExeName)
 }

internal/probe/image.go

@@ -8,7 +8,8 @@ import (
 	"strings"
 )
 
-// supportImageTypes 支持的标准图片扩展名（大小写不敏感）
+// supportImageTypes 认识的图片扩展名（大小写不敏感）。
+// 这些格式可以自己读出尺寸；列表之外的（如 tiff）在 ffprobe 可用时兜底探测。
 var supportImageTypes = []string{
 	".bmp",
 	".gif",
@@ -21,7 +22,7 @@ var supportImageTypes = []string{
 	".jfif",
 }
 
-// IsSupportImage 判断扩展名是否属于支持的图片格式
+// IsSupportImage 判断扩展名是不是认识的图片格式。
 func IsSupportImage(ext string) bool {
 	for _, t := range supportImageTypes {
 		if strings.EqualFold(t, ext) {
@@ -31,14 +32,17 @@ func IsSupportImage(ext string) bool {
 	return false
 }
 
-// ProbeImage 统一探测图片尺寸：
-//  1. 特殊格式（webp/bmp/psd/psb）走专用解码器，失败后用 ffprobe 兜底
-//  2. 其余白名单格式走 Go 标准库 image.DecodeConfig
-//  3. 标准库失败时用 ffprobe 兜底（ffmpeg 支持的图片格式更广，如 tiff/svg 等）
+// ProbeImage 探测一张图片的尺寸（宽高）。
 //
-// ffprobePath 为空表示不启用 ffprobe 兜底；非白名单扩展名（如 tiff）在 ffprobe 可用时兜底探测。
+// 流程（从快到慢、从准到兜底）：
+//  1. 特殊格式（WebP/BMP/PSD）用专门写的读取函数，它们标准库不一定认识；
+//  2. 其余认识的格式用 Go 标准库读（最轻量）；
+//  3. 上面都失败、或者格式不常见时，用 ffprobe 兜底（它认识的图片格式更多）。
+//
+// ffprobePath 为空表示不启用兜底；遇到不认识的格式就报"不支持"。
 func ProbeImage(filePath, ffprobePath string) (*ProbeResult, error) {
 	ext := strings.ToLower(filepath.Ext(filePath))
+	// 先试试专门的读取函数
 	switch ext {
 	case ".webp":
 		if res, err := probeWebp(filePath); err == nil {
@@ -53,34 +57,38 @@ func ProbeImage(filePath, ffprobePath string) (*ProbeResult, error) {
 			return res, nil
 		}
 	}
+	// 不在认识列表里的格式：只能用 ffprobe 碰运气
 	if !IsSupportImage(ext) {
-		// 非白名单扩展名（tiff/svg 等）：ffprobe 可用时兜底探测，否则视为不支持
 		if res, err := probeByFFprobe(ffprobePath, filePath); err == nil {
 			return res, nil
 		}
 		return nil, fmt.Errorf("不支持的图片格式: %s", ext)
 	}
+	// 用标准库读宽高
 	if w, h, err := decodeConfig(filePath); err == nil {
 		return &ProbeResult{Width: w, Height: h}, nil
 	}
+	// 标准库读不出 → 用 ffprobe 兜底
 	if res, err := probeByFFprobe(ffprobePath, filePath); err == nil {
 		return res, nil
 	}
 	return nil, fmt.Errorf("无法读取图片尺寸: %s", filePath)
 }
 
-// probeByFFprobe 用 ffprobe 兜底探测图片尺寸；ffprobePath 为空或探测失败时返回错误
+// probeByFFprobe 用 ffprobe 兜底读图片尺寸。
+// ffprobePath 为空或探测失败时返回错误。
 func probeByFFprobe(ffprobePath, filePath string) (*ProbeResult, error) {
 	if ffprobePath == "" {
 		return nil, fmt.Errorf("未启用 ffprobe 兜底")
 	}
+	// 图片在 ffprobe 眼里会被当成"只有视频流"的视频
 	if res, err := ProbeMediaFile(ffprobePath, filePath); err == nil && res.HasVideo {
 		return res, nil
 	}
 	return nil, fmt.Errorf("ffprobe 兜底失败: %s", filePath)
 }
 
-// decodeConfig 用 Go 标准库读取图片宽高
+// decodeConfig 用 Go 标准库读图片宽高（只解码头部配置，不加载整张图，很快）。
 func decodeConfig(filePath string) (int, int, error) {
 	f, err := os.Open(filePath)
 	if err != nil {

internal/probe/probe.go

@@ -1,4 +1,10 @@
-// Package probe 负责媒体信息探测：图片尺寸读取、ffprobe 视频/音频解析与内嵌解码器释放。
+// Package probe 负责给媒体文件"体检"：
+//   - 图片：读出它的宽高（尺寸），特殊格式（WebP/BMP/PSD）有专门的读法
+//   - 视频/音频：调 ffprobe 程序读出编码、时长、宽高等信息
+//   - 明暗分析：图片是偏暗还是偏亮（给图片分类用）
+//
+// 大白话理解：这一步负责搞清楚"这个文件到底是什么样的"，好让后面决定把它归到哪。
+// 体检结果统一放进 ProbeResult 这一个结构里，图片、视频、音频都往里填。
 package probe
 
 import (
@@ -10,44 +16,51 @@ import (
 	"time"
 )
 
-// ProbeResult 媒体探测结果（图片/视频/音频通用）
+// ProbeResult 一份"体检报告"，图片/视频/音频通用。
 type ProbeResult struct {
-	HasVideo   bool
-	HasAudio   bool
-	Width      int
-	Height     int
-	Duration   float64
-	VideoCodec string
-	AudioCodec string
-	Format     string
-	RawJSON    string
+	HasVideo   bool    // 有没有视频流
+	HasAudio   bool    // 有没有音频流
+	Width      int     // 宽（像素）
+	Height     int     // 高（像素）
+	Duration   float64 // 时长（秒）
+	VideoCodec string  // 视频编码（如 h264）
+	AudioCodec string  // 音频编码（如 aac）
+	Format     string  // 容器格式（如 mp4）
+	RawJSON    string  // ffprobe 读出的原始信息，存下来留底
 }
 
+// streamInfo 是 ffprobe 输出里"一条流"的 JSON 结构（视频流/音频流都会列出来）。
 type streamInfo struct {
 	Index     int    `json:"index"`
-	CodecType string `json:"codec_type"`
+	CodecType string `json:"codec_type"` // video / audio
 	CodecName string `json:"codec_name"`
 	Width     int    `json:"width"`
 	Height    int    `json:"height"`
 }
 
+// formatInfo 是 ffprobe 输出里"容器格式"部分的 JSON 结构。
 type formatInfo struct {
 	Duration string `json:"duration"`
 	Format   string `json:"format_name"`
 }
 
+// probeOutput 是 ffprobe 完整输出的 JSON 结构。
 type probeOutput struct {
 	Streams []streamInfo `json:"streams"`
 	Format  formatInfo   `json:"format"`
 }
 
-// ffprobeTimeout ffprobe 探测超时时间，超时视为探测失败（避免损坏文件卡死程序）
+// ffprobeTimeout 调 ffprobe 的超时时间。超过就当探测失败，
+// 免得遇到损坏文件时卡住整个程序。
 const ffprobeTimeout = 30 * time.Second
 
-// ProbeMediaFile 用 ffprobe 探测媒体文件，一次调用同时获取视频/音频流与时长
+// ProbeMediaFile 调 ffprobe 探测一个媒体文件，一次调用就把
+// 视频流/音频流/时长/格式全部拿到。
 func ProbeMediaFile(ffprobePath, filePath string) (*ProbeResult, error) {
+	// 带超时的执行环境：文件坏了也不至于永远卡住
 	ctx, cancel := context.WithTimeout(context.Background(), ffprobeTimeout)
 	defer cancel()
+	// 用 ffprobe 读信息，指定输出 JSON 格式
 	cmd := exec.CommandContext(ctx, ffprobePath, "-v", "error",
 		"-show_entries", "stream=index,codec_type,codec_name,width,height:format=duration,format_name",
 		"-of", "json", filePath)
@@ -55,6 +68,7 @@ func ProbeMediaFile(ffprobePath, filePath string) (*ProbeResult, error) {
 	if err != nil {
 		return nil, fmt.Errorf("ffprobe failed: %w", err)
 	}
+	// 把 JSON 输出翻译成结构体
 	var out probeOutput
 	if err := json.Unmarshal(output, &out); err != nil {
 		return nil, fmt.Errorf("parse ffprobe output: %w", err)
@@ -63,9 +77,13 @@ func ProbeMediaFile(ffprobePath, filePath string) (*ProbeResult, error) {
 		Format:  out.Format.Format,
 		RawJSON: string(output),
 	}
+	// 时长（秒）
 	if d, err := strconv.ParseFloat(out.Format.Duration, 64); err == nil {
 		res.Duration = d
 	}
+	// 把每条流的信息填进报告：
+	//   视频流 → 记下"有视频"，补上编码和宽高；
+	//   音频流 → 记下"有音频"，补上编码。
 	for _, s := range out.Streams {
 		switch s.CodecType {
 		case "video":