feat(share): 新增 shareList 接口 + 分享码模块全链路优化

- 新增 GET /audio/shareList?mac=xx 查询未过期分享码（纯 Redis，ZSET 索引）
- share:mac:{mac} 从 SET 改为 ZSET（score=expire_at），支持 ZREMRANGEBYSCORE 精确过期清理
- 空 ZSET 自动 DEL，避免 key 累积
- share:import:pending 增加 12h 兜底 TTL，防止 DB 不可用时内存泄漏
- 导入日志 field 改为 mac:code（去掉 nanotime），同 MAC+code 多次导入幂等去重
- MarkPersisted 保存/恢复 PTTL，防御性编程
- shareCreate 改为 POST + JSON body
- 全量 handler 补充 Swagger 注释，集成 swag 文档生成
- Makefile 使用 $(go env GOPATH)/bin/swag 解决 PATH 问题

internal/cache/share_code_cache.go

@@ -7,21 +7,24 @@ import (
 	"errors"
 	"fmt"
 	"math/big"
+	"strings"
 	"time"
 
 	"github.com/redis/go-redis/v9"
 )
 
 const (
-	shareCodeKeyPrefix  = "share:"
-	sharePendingSet        = "share:pending"
-	shareImportPendingHash = "share:import:pending"
-	shareFlushLockPref     = "share:flush:lock:"
+	shareCodeKeyPrefix       = "share:"
+	sharePendingSet          = "share:pending"
+	shareImportPendingHash   = "share:import:pending"
+	shareFlushLockPref       = "share:flush:lock:"
 	shareImportFlushLockPref = "share:import:flush:lock:"
-	shareCodeLength     = 5
-	shareCodeTTL        = 30 * time.Minute
-	shareCodeCharset    = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
-	shareCodeMaxRetries = 20
+	shareMacIndexPrefix      = "share:mac:"
+	shareCodeLength          = 5
+	shareCodeTTL             = 30 * time.Minute
+	shareImportPendingTTL    = 12 * time.Hour
+	shareCodeCharset         = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
+	shareCodeMaxRetries      = 20
 
 	fieldMacAddr   = "mac_addr"
 	fieldIPAddr    = "ip_addr"
@@ -43,6 +46,8 @@ redis.call('HSET', KEYS[1],
 )
 redis.call('EXPIRE', KEYS[1], tonumber(ARGV[5]))
 redis.call('SADD', KEYS[2], ARGV[6])
+-- ZSET: score = expire_at unix timestamp, member = share code
+redis.call('ZADD', KEYS[3], tonumber(ARGV[7]), ARGV[6])
 return 1
 `)
 
@@ -86,8 +91,9 @@ func (c *ShareCodeCache) Create(ctx context.Context, macAddr, ipAddr string, eqD
 		}
 
 		key := shareCodeKey(code)
-		ok, err := shareCreateScript.Run(ctx, c.rdb, []string{key, sharePendingSet},
-			macAddr, ipAddr, eqJSON, expireAt.Format(time.RFC3339), int(shareCodeTTL.Seconds()), code,
+		macIdxKey := shareMacIndexKey(macAddr)
+		ok, err := shareCreateScript.Run(ctx, c.rdb, []string{key, sharePendingSet, macIdxKey},
+			macAddr, ipAddr, eqJSON, expireAt.Format(time.RFC3339), int(shareCodeTTL.Seconds()), code, expireAt.Unix(),
 		).Int()
 		if err != nil {
 			return nil, fmt.Errorf("create share code in redis: %w", err)
@@ -151,14 +157,27 @@ func (c *ShareCodeCache) ReleaseFlushLock(ctx context.Context, shareCode string)
 
 func (c *ShareCodeCache) MarkPersisted(ctx context.Context, shareCode string) error {
 	key := shareCodeKey(shareCode)
+
+	// preserve remaining TTL before HSET (HSET clears TTL in some Redis versions)
+	remainTTL, err := c.rdb.PTTL(ctx, key).Result()
+	if err != nil {
+		return fmt.Errorf("get share code ttl: %w", err)
+	}
+
 	if err := c.rdb.HSet(ctx, key, fieldPersisted, "1").Err(); err != nil {
 		return fmt.Errorf("mark share code persisted: %w", err)
 	}
+
+	// restore TTL
+	if remainTTL > 0 {
+		_ = c.rdb.PExpire(ctx, key, remainTTL).Err()
+	}
+
 	return c.rdb.SRem(ctx, sharePendingSet, shareCode).Err()
 }
 
 func (c *ShareCodeCache) EnqueueImportLog(ctx context.Context, macAddr, shareCode, ipAddr, eqData string, expireAt time.Time) error {
-	field := fmt.Sprintf("%s:%s:%d", macAddr, shareCode, time.Now().UnixNano())
+	field := fmt.Sprintf("%s:%s", macAddr, shareCode) // 同 MAC+code 幂等，避免重复导入产生多条记录
 	payload, err := json.Marshal(ShareImportPendingLog{
 		MacAddr:   macAddr,
 		ShareCode: shareCode,
@@ -172,6 +191,8 @@ func (c *ShareCodeCache) EnqueueImportLog(ctx context.Context, macAddr, shareCod
 	if err := c.rdb.HSet(ctx, shareImportPendingHash, field, payload).Err(); err != nil {
 		return fmt.Errorf("enqueue import log: %w", err)
 	}
+	// Fallback TTL: prevent unbounded growth if persist task is disabled or DB is down
+	c.rdb.Expire(ctx, shareImportPendingHash, shareImportPendingTTL)
 	return nil
 }
 
@@ -195,6 +216,50 @@ func (c *ShareCodeCache) ReleaseImportFlushLock(ctx context.Context, field strin
 	return c.rdb.Del(ctx, shareImportFlushLockPref+field).Err()
 }
 
+func (c *ShareCodeCache) ListByMac(ctx context.Context, macAddr string) ([]*ShareCodeData, error) {
+	key := shareMacIndexKey(macAddr)
+	now := time.Now()
+
+	// Remove expired entries from ZSET (score = expire_at unix timestamp)
+	_, err := c.rdb.ZRemRangeByScore(ctx, key, "-inf", fmt.Sprintf("%d", now.Unix())).Result()
+	if err != nil && strings.Contains(err.Error(), "WRONGTYPE") {
+		// Old SET-type key from previous version, delete it
+		_ = c.rdb.Del(ctx, key).Err()
+		return nil, nil
+	}
+
+	// Get remaining (unexpired) codes
+	codes, err := c.rdb.ZRange(ctx, key, 0, -1).Result()
+	if err != nil {
+		return nil, fmt.Errorf("zrange mac index: %w", err)
+	}
+	if len(codes) == 0 {
+		// ZSET is empty, remove the key to avoid accumulating empty keys
+		_ = c.rdb.Del(ctx, key).Err()
+		return nil, nil
+	}
+
+	var result []*ShareCodeData
+	for _, code := range codes {
+		data, err := c.Get(ctx, code)
+		if err != nil {
+			return nil, err
+		}
+		if data == nil {
+			// hash already expired/removed, clean from ZSET
+			_ = c.rdb.ZRem(ctx, key, code).Err()
+			continue
+		}
+		result = append(result, data)
+	}
+
+	return result, nil
+}
+
+func shareMacIndexKey(macAddr string) string {
+	return shareMacIndexPrefix + macAddr
+}
+
 func shareCodeKey(code string) string {
 	return shareCodeKeyPrefix + code
 }