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

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

internal/api/scan_ws.go

@@ -1,4 +1,8 @@
-// 扫描状态 WebSocket 实时推送端点。
+// 扫描状态实时推送：用 WebSocket 把进度不停推给前端页面。
+//
+// 大白话理解：网页和服务器之间开一条"专线"，服务器一有动静（进度变了、
+// 日志多了、干完了）就主动通过这条线喊一声，页面立刻更新。
+// 以前是页面每隔一秒"问一次"，现在是服务器"主动喊"，实时又不浪费。
 package api
 
 import (
@@ -10,51 +14,58 @@ import (
 	"github.com/gorilla/websocket"
 )
 
-// wsUpgrader WebSocket 升级器
+// wsUpgrader 负责把普通的网页请求"升级"成 WebSocket 专线。
+// 同一个管理页面访问，所以允许任意来源（也方便局域网内访问）。
 var wsUpgrader = websocket.Upgrader{
 	ReadBufferSize:  1024,
 	WriteBufferSize: 4096,
-	// 同源管理页，允许任意来源，便于局域网访问
-	CheckOrigin: func(r *http.Request) bool { return true },
+	CheckOrigin:     func(r *http.Request) bool { return true },
 }
 
+// 心跳相关的三个时间：
 const (
-	wsWriteWait  = 10 * time.Second
-	wsPongWait   = 60 * time.Second
-	wsPingPeriod = (wsPongWait * 9) / 10
+	wsWriteWait  = 10 * time.Second      // 写消息的最长等待时间
+	wsPongWait   = 60 * time.Second      // 等客户端"应答"的最长时间，超了就当它掉了
+	wsPingPeriod = (wsPongWait * 9) / 10 // 每隔多久主动发一次"心跳"
 )
 
-// Ws GET /api/scan/ws 建立 WebSocket 连接，持续推送扫描状态。
-// 连接建立后立即推送当前状态快照；断开后前端可自动重连（服务端不做重连保证）。
+// Ws 处理 GET /api/scan/ws：建立专线后，不停把扫描状态推给前端。
+//
+// 连接一建立，先立刻把当前状态推一份（快照），之后一有更新就推。
+// 前端页面刷新、网络断了之后会自己重新连上来，这里只管服务端这一端。
 func (c *ScanController) Ws(ctx *gin.Context) {
+	// 升级成 WebSocket 专线
 	conn, err := wsUpgrader.Upgrade(ctx.Writer, ctx.Request, nil)
 	if err != nil {
 		return
 	}
+	// 订阅进度更新：之后有状态就送到 ch 这个管道里
 	ch, cancel := c.service.Subscribe()
 	defer func() {
 		cancel()
 		conn.Close()
 	}()
 
-	// 读协程：仅用于感知客户端断开/失活（配合 pong 心跳），不处理业务消息
+	// 读消息的协程只是用来"感知"客户端还在不在（配合心跳应答），不处理实际内容
 	conn.SetReadLimit(1024)
 	_ = conn.SetReadDeadline(time.Now().Add(wsPongWait))
 	conn.SetPongHandler(func(string) error {
 		return conn.SetReadDeadline(time.Now().Add(wsPongWait))
 	})
 
-	// 写协程：先推送快照，再转发订阅更新，并周期性 ping 保活
+	// 写消息的协程：先推一份当前状态快照，再不停转发订阅到的更新，
+	// 空闲时定期发心跳（ping），防止专线被路由器等中间设备掐断。
 	writeDone := make(chan struct{})
 	go func() {
 		defer close(writeDone)
 		write := func(msgType int, data []byte) bool {
 			if err := conn.WriteMessage(msgType, data); err != nil {
-				conn.Close() // 写失败即断开，让读协程退出
+				conn.Close() // 写失败说明专线断了，把连接关掉，让读协程收工
 				return false
 			}
 			return true
 		}
+		// 先推快照
 		if b, err := json.Marshal(c.service.Status()); err == nil {
 			if !write(websocket.TextMessage, b) {
 				return
@@ -66,7 +77,7 @@ func (c *ScanController) Ws(ctx *gin.Context) {
 			select {
 			case st, ok := <-ch:
 				if !ok {
-					return
+					return // 订阅被取消了（连接要关了）
 				}
 				b, err := json.Marshal(st)
 				if err != nil {
@@ -76,6 +87,7 @@ func (c *ScanController) Ws(ctx *gin.Context) {
 					return
 				}
 			case <-ticker.C:
+				// 定期发心跳
 				if !write(websocket.PingMessage, nil) {
 					return
 				}
@@ -83,11 +95,13 @@ func (c *ScanController) Ws(ctx *gin.Context) {
 		}
 	}()
 
+	// 主线程一直等着读：客户端断开或失活时 ReadMessage 会出错，这里就收工
 	for {
 		if _, _, err := conn.ReadMessage(); err != nil {
 			break
 		}
 	}
-	cancel() // 先关闭订阅频道，让写协程退出，避免 <-writeDone 永久阻塞
+	// 先关掉订阅，让写协程退出，避免白等
+	cancel()
 	<-writeDone
 }