ERP/shipments_redis_structure.md

发货记录 Redis 存储结构说明

Redis 数据结构

Hash 表：shipment_sn_mapping

用于存储 SN/MAC 到出货信息的映射关系。

数据类型: Redis Hash

Key: shipment_sn_mapping

结构:

Hash Key (Field)  ->  Hash Value
SN/MAC 号         ->  JSON 格式的出货信息

存储示例

HSET shipment_sn_mapping "SN0001" '{"date":"2025-11-20","box":"BOX001","ts":"2025-11-20T10:30:00"}'
HSET shipment_sn_mapping "SN0002" '{"date":"2025-11-20","box":"BOX001","ts":"2025-11-20T10:30:00"}'
HSET shipment_sn_mapping "SN0021" '{"date":"2025-11-20","box":"BOX002","ts":"2025-11-20T10:30:00"}'

JSON 值格式

{
  "date": "2025-11-20",     // 出货日期
  "box": "BOX001",          // 箱号
  "ts": "2025-11-20T10:30:00"  // 记录时间戳
}

查询方式

1. 通过 API 查询

接口: GET /api/shipments/query-by-sn?sn=SN0001

响应示例:

{
  "found": true,
  "sn": "SN0001",
  "date": "2025-11-20",
  "box": "BOX001",
  "ts": "2025-11-20T10:30:00"
}

2. 直接使用 Redis 命令查询

# 查询单个 SN
redis-cli HGET shipment_sn_mapping "SN0001"

# 查询多个 SN
redis-cli HMGET shipment_sn_mapping "SN0001" "SN0002" "SN0003"

# 查看所有记录数量
redis-cli HLEN shipment_sn_mapping

# 查看所有 SN（谨慎使用，数据量大时会很慢）
redis-cli HKEYS shipment_sn_mapping

# 扫描部分数据
redis-cli HSCAN shipment_sn_mapping 0 COUNT 100

数据导入流程

1. 用户上传 Excel 文件（包含：出货日期、箱号、SN1-SN20）
2. 系统解析 Excel 文件
3. 提取每行的出货日期、箱号和所有 SN
4. 将数据保存到 SQLite（用于统计和列表展示）
5. 同时将每个 SN 映射关系写入 Redis Hash（用于快速查询）

性能特点

• 查询速度: O(1) 时间复杂度，毫秒级响应
• 存储效率: Hash 结构比单独的 Key-Value 更节省内存
• 批量写入: 使用 Pipeline 批量写入，提高导入速度
• 容错性: Redis 写入失败不影响 SQLite 数据保存

使用场景

1. 快速查询: 扫描 SN 后立即查询出货信息
2. 追溯管理: 根据 MAC 地址追溯出货批次
3. 质量追踪: 结合不良品记录，追溯出货批次
4. 客户服务: 快速响应客户关于产品出货信息的查询

维护建议

1. 定期备份: 使用 Redis RDB 或 AOF 持久化
2. 监控容量: 定期检查 Hash 大小 HLEN shipment_sn_mapping
3. 数据清理: 根据业务需求定期清理过期数据
4. 索引优化: 如需按日期或箱号查询，可建立额外的索引结构