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 (