From cbf3ad6613b04e3f210448542648dc53ee73b617 Mon Sep 17 00:00:00 2001
From: eafonyang <eafonyang@gmail.com>
Date: Fri, 12 Jun 2026 17:09:21 +0800
Subject: [PATCH] =?UTF-8?q?docs(cache):=20=E6=B7=BB=E5=8A=A0=20share=5Fcod?=
 =?UTF-8?q?e=5Fcache.go=20=E6=96=87=E4=BB=B6=E7=BA=A7=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

描述 Redis 存储结构（Hash/ZSET/SET/锁）和完整数据流（创建/查询/导入/持久化）
---
 internal/cache/share_code_cache.go | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/internal/cache/share_code_cache.go b/internal/cache/share_code_cache.go
index 296df94..27bad8b 100644
--- a/internal/cache/share_code_cache.go
+++ b/internal/cache/share_code_cache.go
@@ -1,3 +1,33 @@
+// Package cache — 分享码 Redis 缓存层
+//
+// # Redis 存储结构
+//
+//	share:{code}              Hash, TTL 30min — 分享码主数据
+//	  mac_addr                创建者 MAC 地址
+//	  ip_addr                 创建者 IP
+//	  eq_data                 EQ 参数 JSON
+//	  expire_at               过期时间 (RFC3339)
+//	  persisted               是否已刷入 DB ("0"/"1")
+//
+//	share:mac:{mac}           ZSET — MAC 二级索引 (无 TTL, 查询时自动清理过期成员)
+//	  member = share_code
+//	  score  = expire_at unix timestamp
+//
+//	share:pending             SET — 导出持久化队列 (无 TTL, hash 过期后自动清理)
+//
+//	share:import:pending      Hash, TTL 12h (兜底) — 导入持久化队列
+//	  field = {mac}:{code}    幂等: 同 MAC+code 只保留一条
+//	  value = JSON payload
+//
+//	share:flush:lock:{code}         String, TTL 30s — 导出刷入分布式锁
+//	share:import:flush:lock:{field} String, TTL 30s — 导入刷入分布式锁
+//
+// # 数据流
+//
+//	创建: Lua 原子写入 hash + SADD pending + ZADD mac 索引
+//	查询: ZREMRANGEBYSCORE 清过期索引 → ZRANGE 取剩余 → HGETALL 兆底校验
+//	导入: HGETALL hash → HSET import:pending (幂等)
+//	持久化: 每 5 分钟任务 SMEMBERS/HGETALL pending → INSERT DB → 移除 pending 条目
 package cache
 
 import (