第10章 中央库存系统

10.1 中央库存系统概述

中央库存系统是新零售SaaS平台的核心组成部分，它负责统一管理企业所有渠道的库存信息，实现库存的实时同步、精准控制和智能调配。在多渠道零售环境下，中央库存系统确保了库存数据的一致性和准确性，为企业提供了全局的库存视图和决策支持。

10.1.1 中央库存系统的重要性

在传统的零售模式中，不同渠道往往维护独立的库存系统，这导致了以下问题：

1. 库存数据不一致：各渠道库存数据无法实时同步，容易出现超卖或缺货情况
2. 库存可见性差：无法获得全局库存视图，影响采购和销售决策
3. 库存周转率低：无法实现库存在不同渠道间的灵活调配
4. 客户体验差：因库存信息不准确导致的订单取消和延迟交付

中央库存系统通过统一的库存管理，解决了这些问题：

/**
 * 中央库存系统核心价值
 */
public class CentralInventoryValue {
    
    /**
     * 库存统一管理的核心价值
     */
    public enum CoreValue {
        REAL_TIME_SYNC("实时同步", "所有渠道库存实时同步更新"),
        GLOBAL_VISIBILITY("全局可见", "提供企业级库存全局视图"),
        INTELLIGENT_ALLOCATION("智能调配", "基于算法的库存智能分配"),
        ACCURATE_CONTROL("精准控制", "精确的库存数量和状态管理"),
        UNIFIED_RULES("统一规则", "标准化的库存管理规则和流程");
        
        private final String name;
        private final String description;
        
        CoreValue(String name, String description) {
            this.name = name;
            this.description = description;
        }
        
        public String getName() { return name; }
        public String getDescription() { return description; }
    }
    
    /**
     * 业务收益指标
     */
    public static class BusinessBenefits {
        private double inventoryTurnoverImprovement;    // 库存周转率提升
        private double stockoutReduction;              // 缺货率降低
        private double oversellReduction;               // 超卖率降低
        private double customerSatisfactionIncrease;   // 客户满意度提升
        private double operationalEfficiencyGain;      // 运营效率提升
        
        public BusinessBenefits() {
            // 基于行业数据的预期收益
            this.inventoryTurnoverImprovement = 0.25;  // 25%提升
            this.stockoutReduction = 0.40;             // 40%降低
            this.oversellReduction = 0.90;             // 90%降低
            this.customerSatisfactionIncrease = 0.15;  // 15%提升
            this.operationalEfficiencyGain = 0.30;    // 30%提升
        }
        
        public Map<String, String> getBenefitsSummary() {
            Map<String, String> benefits = new HashMap<>();
            benefits.put("库存周转率", String.format("提升%.0f%%", inventoryTurnoverImprovement * 100));
            benefits.put("缺货率", String.format("降低%.0f%%", stockoutReduction * 100));
            benefits.put("超卖率", String.format("降低%.0f%%", oversellReduction * 100));
            benefits.put("客户满意度", String.format("提升%.0f%%", customerSatisfactionIncrease * 100));
            benefits.put("运营效率", String.format("提升%.0f%%", operationalEfficiencyGain * 100));
            return benefits;
        }
    }
}

10.1.2 系统架构设计原则

中央库存系统的设计遵循以下核心原则：

/**
 * 中央库存系统设计原则
 */
public class InventorySystemPrinciples {
    
    /**
     * 设计原则枚举
     */
    public enum DesignPrinciple {
        SINGLE_SOURCE_OF_TRUTH("单一数据源", "库存数据的唯一权威来源"),
        REAL_TIME_CONSISTENCY("实时一致性", "确保所有渠道库存数据实时一致"),
        HIGH_AVAILABILITY("高可用性", "系统7x24小时稳定运行"),
        SCALABILITY("可扩展性", "支持业务规模的快速增长"),
        FAULT_TOLERANCE("容错性", "具备故障自动恢复能力"),
        PERFORMANCE_OPTIMIZATION("性能优化", "高并发下的快速响应"),
        SECURITY_COMPLIANCE("安全合规", "数据安全和合规性保障");
        
        private final String name;
        private final String description;
        
        DesignPrinciple(String name, String description) {
            this.name = name;
            this.description = description;
        }
        
        public String getName() { return name; }
        public String getDescription() { return description; }
    }
    
    /**
     * 架构质量属性
     */
    public static class QualityAttributes {
        private Map<String, QualityRequirement> requirements;
        
        public QualityAttributes() {
            this.requirements = new HashMap<>();
            initializeRequirements();
        }
        
        private void initializeRequirements() {
            requirements.put("可用性", new QualityRequirement(
                "99.9%", "系统年度可用性不低于99.9%", "关键业务连续性保障"
            ));
            
            requirements.put("响应时间", new QualityRequirement(
                "<100ms", "库存查询响应时间小于100毫秒", "用户体验优化"
            ));
            
            requirements.put("并发处理", new QualityRequirement(
                "10000 TPS", "支持每秒10000次事务处理", "高并发场景支持"
            ));
            
            requirements.put("数据一致性", new QualityRequirement(
                "强一致性", "库存数据强一致性保证", "业务准确性要求"
            ));
            
            requirements.put("扩展性", new QualityRequirement(
                "水平扩展", "支持水平扩展到1000+节点", "业务增长支撑"
            ));
        }
        
        public QualityRequirement getRequirement(String attribute) {
            return requirements.get(attribute);
        }
        
        public Map<String, QualityRequirement> getAllRequirements() {
            return new HashMap<>(requirements);
        }
    }
    
    public static class QualityRequirement {
        private String target;          // 目标值
        private String description;     // 描述
        private String rationale;       // 理由
        
        public QualityRequirement(String target, String description, String rationale) {
            this.target = target;
            this.description = description;
            this.rationale = rationale;
        }
        
        // getters
        public String getTarget() { return target; }
        public String getDescription() { return description; }
        public String getRationale() { return rationale; }
    }
}

10.2 库存数据模型设计

库存数据模型是中央库存系统的基础，它定义了库存信息的结构、关系和约束。一个良好的数据模型能够支持复杂的业务场景，同时保证数据的完整性和一致性。

10.2.1 核心库存实体

/**
 * 库存核心实体定义
 */
@Entity
@Table(name = "inventory_item")
public class InventoryItem extends BaseEntity {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "sku_id", nullable = false)
    private String skuId;                    // SKU标识
    
    @Column(name = "warehouse_id", nullable = false)
    private String warehouseId;              // 仓库标识
    
    @Column(name = "location_id")
    private String locationId;               // 库位标识
    
    @Column(name = "available_quantity", nullable = false)
    private Integer availableQuantity;       // 可用库存
    
    @Column(name = "reserved_quantity", nullable = false)
    private Integer reservedQuantity;        // 预留库存
    
    @Column(name = "allocated_quantity", nullable = false)
    private Integer allocatedQuantity;       // 已分配库存
    
    @Column(name = "in_transit_quantity", nullable = false)
    private Integer inTransitQuantity;       // 在途库存
    
    @Column(name = "damaged_quantity", nullable = false)
    private Integer damagedQuantity;         // 损坏库存
    
    @Column(name = "total_quantity", nullable = false)
    private Integer totalQuantity;           // 总库存
    
    @Column(name = "safety_stock")
    private Integer safetyStock;             // 安全库存
    
    @Column(name = "reorder_point")
    private Integer reorderPoint;            // 补货点
    
    @Column(name = "max_stock")
    private Integer maxStock;                // 最大库存
    
    @Column(name = "unit_cost")
    private BigDecimal unitCost;             // 单位成本
    
    @Column(name = "last_updated")
    private LocalDateTime lastUpdated;       // 最后更新时间
    
    @Column(name = "version", nullable = false)
    @Version
    private Long version;                    // 乐观锁版本号
    
    @Enumerated(EnumType.STRING)
    @Column(name = "status")
    private InventoryStatus status;          // 库存状态
    
    @Column(name = "batch_number")
    private String batchNumber;              // 批次号
    
    @Column(name = "expiry_date")
    private LocalDate expiryDate;            // 过期日期
    
    @Column(name = "supplier_id")
    private String supplierId;               // 供应商ID
    
    // 构造函数
    public InventoryItem() {}
    
    public InventoryItem(String skuId, String warehouseId) {
        this.skuId = skuId;
        this.warehouseId = warehouseId;
        this.availableQuantity = 0;
        this.reservedQuantity = 0;
        this.allocatedQuantity = 0;
        this.inTransitQuantity = 0;
        this.damagedQuantity = 0;
        this.totalQuantity = 0;
        this.status = InventoryStatus.ACTIVE;
        this.lastUpdated = LocalDateTime.now();
    }
    
    /**
     * 计算可销售库存
     */
    public Integer getAvailableForSale() {
        return availableQuantity - reservedQuantity;
    }
    
    /**
     * 检查是否需要补货
     */
    public boolean needsReorder() {
        return reorderPoint != null && availableQuantity <= reorderPoint;
    }
    
    /**
     * 检查是否库存充足
     */
    public boolean hasSufficientStock(Integer requiredQuantity) {
        return getAvailableForSale() >= requiredQuantity;
    }
    
    /**
     * 更新总库存
     */
    public void updateTotalQuantity() {
        this.totalQuantity = availableQuantity + reservedQuantity + 
                           allocatedQuantity + inTransitQuantity + damagedQuantity;
        this.lastUpdated = LocalDateTime.now();
    }
    
    /**
     * 预留库存
     */
    public boolean reserveStock(Integer quantity) {
        if (hasSufficientStock(quantity)) {
            this.availableQuantity -= quantity;
            this.reservedQuantity += quantity;
            updateTotalQuantity();
            return true;
        }
        return false;
    }
    
    /**
     * 释放预留库存
     */
    public void releaseReservedStock(Integer quantity) {
        int releaseQuantity = Math.min(quantity, this.reservedQuantity);
        this.reservedQuantity -= releaseQuantity;
        this.availableQuantity += releaseQuantity;
        updateTotalQuantity();
    }
    
    /**
     * 分配库存
     */
    public boolean allocateStock(Integer quantity) {
        if (this.reservedQuantity >= quantity) {
            this.reservedQuantity -= quantity;
            this.allocatedQuantity += quantity;
            updateTotalQuantity();
            return true;
        }
        return false;
    }
    
    /**
     * 出库
     */
    public boolean shipStock(Integer quantity) {
        if (this.allocatedQuantity >= quantity) {
            this.allocatedQuantity -= quantity;
            updateTotalQuantity();
            return true;
        }
        return false;
    }
    
    /**
     * 入库
     */
    public void receiveStock(Integer quantity) {
        this.availableQuantity += quantity;
        updateTotalQuantity();
    }
    
    // getters and setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getSkuId() { return skuId; }
    public void setSkuId(String skuId) { this.skuId = skuId; }
    
    public String getWarehouseId() { return warehouseId; }
    public void setWarehouseId(String warehouseId) { this.warehouseId = warehouseId; }
    
    public String getLocationId() { return locationId; }
    public void setLocationId(String locationId) { this.locationId = locationId; }
    
    public Integer getAvailableQuantity() { return availableQuantity; }
    public void setAvailableQuantity(Integer availableQuantity) { 
        this.availableQuantity = availableQuantity;
        updateTotalQuantity();
    }
    
    public Integer getReservedQuantity() { return reservedQuantity; }
    public void setReservedQuantity(Integer reservedQuantity) { 
        this.reservedQuantity = reservedQuantity;
        updateTotalQuantity();
    }
    
    public Integer getAllocatedQuantity() { return allocatedQuantity; }
    public void setAllocatedQuantity(Integer allocatedQuantity) { 
        this.allocatedQuantity = allocatedQuantity;
        updateTotalQuantity();
    }
    
    public Integer getInTransitQuantity() { return inTransitQuantity; }
    public void setInTransitQuantity(Integer inTransitQuantity) { 
        this.inTransitQuantity = inTransitQuantity;
        updateTotalQuantity();
    }
    
    public Integer getDamagedQuantity() { return damagedQuantity; }
    public void setDamagedQuantity(Integer damagedQuantity) { 
        this.damagedQuantity = damagedQuantity;
        updateTotalQuantity();
    }
    
    public Integer getTotalQuantity() { return totalQuantity; }
    
    public Integer getSafetyStock() { return safetyStock; }
    public void setSafetyStock(Integer safetyStock) { this.safetyStock = safetyStock; }
    
    public Integer getReorderPoint() { return reorderPoint; }
    public void setReorderPoint(Integer reorderPoint) { this.reorderPoint = reorderPoint; }
    
    public Integer getMaxStock() { return maxStock; }
    public void setMaxStock(Integer maxStock) { this.maxStock = maxStock; }
    
    public BigDecimal getUnitCost() { return unitCost; }
    public void setUnitCost(BigDecimal unitCost) { this.unitCost = unitCost; }
    
    public LocalDateTime getLastUpdated() { return lastUpdated; }
    public void setLastUpdated(LocalDateTime lastUpdated) { this.lastUpdated = lastUpdated; }
    
    public Long getVersion() { return version; }
    public void setVersion(Long version) { this.version = version; }
    
    public InventoryStatus getStatus() { return status; }
    public void setStatus(InventoryStatus status) { this.status = status; }
    
    public String getBatchNumber() { return batchNumber; }
    public void setBatchNumber(String batchNumber) { this.batchNumber = batchNumber; }
    
    public LocalDate getExpiryDate() { return expiryDate; }
    public void setExpiryDate(LocalDate expiryDate) { this.expiryDate = expiryDate; }
    
    public String getSupplierId() { return supplierId; }
    public void setSupplierId(String supplierId) { this.supplierId = supplierId; }
}

/**
 * 库存状态枚举
 */
public enum InventoryStatus {
    ACTIVE("正常"),
    INACTIVE("停用"),
    QUARANTINE("隔离"),
    EXPIRED("过期"),
    DAMAGED("损坏"),
    RESERVED("预留"),
    ALLOCATED("已分配"),
    IN_TRANSIT("在途");
    
    private final String description;
    
    InventoryStatus(String description) {
        this.description = description;
    }
    
    public String getDescription() {
         return description;
     }
 }

10.7 API接口设计

中央库存系统需要提供完整的REST API接口，支持各种库存操作：

/**
 * 库存管理API控制器
 */
@RestController
@RequestMapping("/api/v1/inventory")
@Validated
public class InventoryController {
    
    private final InventoryService inventoryService;
    private final InventoryAnalyticsService analyticsService;
    private final IntelligentReplenishmentService replenishmentService;
    private final InventoryAlertService alertService;
    
    public InventoryController(InventoryService inventoryService,
                             InventoryAnalyticsService analyticsService,
                             IntelligentReplenishmentService replenishmentService,
                             InventoryAlertService alertService) {
        this.inventoryService = inventoryService;
        this.analyticsService = analyticsService;
        this.replenishmentService = replenishmentService;
        this.alertService = alertService;
    }
    
    /**
     * 查询库存信息
     */
    @GetMapping("/items")
    public ResponseEntity<PageResult<InventoryItemDTO>> getInventoryItems(
            @RequestParam(required = false) String warehouseId,
            @RequestParam(required = false) String skuId,
            @RequestParam(required = false) InventoryStatus status,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        
        InventoryQueryRequest request = new InventoryQueryRequest(
            warehouseId, skuId, status, page, size
        );
        
        PageResult<InventoryItem> result = inventoryService.queryInventory(request);
        PageResult<InventoryItemDTO> dtoResult = result.map(this::convertToDTO);
        
        return ResponseEntity.ok(dtoResult);
    }
    
    /**
     * 获取单个库存项详情
     */
    @GetMapping("/items/{warehouseId}/{skuId}")
    public ResponseEntity<InventoryItemDTO> getInventoryItem(
            @PathVariable String warehouseId,
            @PathVariable String skuId) {
        
        Optional<InventoryItem> inventory = inventoryService.getInventory(skuId, warehouseId);
        
        return inventory
                .map(item -> ResponseEntity.ok(convertToDTO(item)))
                .orElse(ResponseEntity.notFound().build());
    }
    
    /**
     * 检查库存可用性
     */
    @GetMapping("/availability")
    public ResponseEntity<InventoryAvailabilityDTO> checkAvailability(
            @RequestParam String skuId,
            @RequestParam String warehouseId,
            @RequestParam int quantity) {
        
        boolean available = inventoryService.checkAvailability(skuId, warehouseId, quantity);
        InventoryItem inventory = inventoryService.getInventory(skuId, warehouseId)
                .orElseThrow(() -> new InventoryNotFoundException("库存不存在"));
        
        InventoryAvailabilityDTO dto = new InventoryAvailabilityDTO(
            skuId,
            warehouseId,
            quantity,
            available,
            inventory.getAvailableQuantity(),
            inventory.getReservedQuantity()
        );
        
        return ResponseEntity.ok(dto);
    }
    
    /**
     * 预留库存
     */
    @PostMapping("/reserve")
    public ResponseEntity<InventoryReservationDTO> reserveInventory(
            @Valid @RequestBody InventoryReservationRequest request) {
        
        try {
            String reservationId = inventoryService.reserveInventory(
                request.getSkuId(),
                request.getWarehouseId(),
                request.getQuantity(),
                request.getReservationReason(),
                request.getExpiryTime()
            );
            
            InventoryReservationDTO dto = new InventoryReservationDTO(
                reservationId,
                request.getSkuId(),
                request.getWarehouseId(),
                request.getQuantity(),
                LocalDateTime.now(),
                request.getExpiryTime(),
                "RESERVED"
            );
            
            return ResponseEntity.ok(dto);
            
        } catch (InsufficientInventoryException e) {
            return ResponseEntity.badRequest()
                    .body(new InventoryReservationDTO(null, request.getSkuId(), 
                          request.getWarehouseId(), request.getQuantity(), 
                          LocalDateTime.now(), null, "FAILED: " + e.getMessage()));
        }
    }
    
    /**
     * 释放预留库存
     */
    @PostMapping("/release")
    public ResponseEntity<Void> releaseReservation(
            @Valid @RequestBody InventoryReleaseRequest request) {
        
        inventoryService.releaseReservation(
            request.getSkuId(),
            request.getWarehouseId(),
            request.getQuantity(),
            request.getReleaseReason()
        );
        
        return ResponseEntity.ok().build();
    }
    
    /**
     * 分配库存
     */
    @PostMapping("/allocate")
    public ResponseEntity<InventoryAllocationDTO> allocateInventory(
            @Valid @RequestBody InventoryAllocationRequest request) {
        
        try {
            String allocationId = inventoryService.allocateInventory(
                request.getSkuId(),
                request.getWarehouseId(),
                request.getQuantity(),
                request.getOrderId(),
                request.getAllocationReason()
            );
            
            InventoryAllocationDTO dto = new InventoryAllocationDTO(
                allocationId,
                request.getSkuId(),
                request.getWarehouseId(),
                request.getQuantity(),
                request.getOrderId(),
                LocalDateTime.now(),
                "ALLOCATED"
            );
            
            return ResponseEntity.ok(dto);
            
        } catch (InsufficientInventoryException e) {
            return ResponseEntity.badRequest()
                    .body(new InventoryAllocationDTO(null, request.getSkuId(),
                          request.getWarehouseId(), request.getQuantity(),
                          request.getOrderId(), LocalDateTime.now(),
                          "FAILED: " + e.getMessage()));
        }
    }
    
    /**
     * 库存出库
     */
    @PostMapping("/outbound")
    public ResponseEntity<InventoryTransactionDTO> outboundInventory(
            @Valid @RequestBody InventoryOutboundRequest request) {
        
        try {
            String transactionId = inventoryService.outbound(
                request.getSkuId(),
                request.getWarehouseId(),
                request.getQuantity(),
                request.getUnitCost(),
                request.getDocumentId(),
                request.getDocumentType(),
                request.getReason()
            );
            
            InventoryTransactionDTO dto = new InventoryTransactionDTO(
                transactionId,
                request.getSkuId(),
                request.getWarehouseId(),
                TransactionType.OUTBOUND,
                request.getQuantity(),
                request.getUnitCost(),
                LocalDateTime.now(),
                "COMPLETED"
            );
            
            return ResponseEntity.ok(dto);
            
        } catch (InsufficientInventoryException e) {
            return ResponseEntity.badRequest()
                    .body(new InventoryTransactionDTO(null, request.getSkuId(),
                          request.getWarehouseId(), TransactionType.OUTBOUND,
                          request.getQuantity(), request.getUnitCost(),
                          LocalDateTime.now(), "FAILED: " + e.getMessage()));
        }
    }
    
    /**
     * 库存入库
     */
    @PostMapping("/inbound")
    public ResponseEntity<InventoryTransactionDTO> inboundInventory(
            @Valid @RequestBody InventoryInboundRequest request) {
        
        String transactionId = inventoryService.inbound(
            request.getSkuId(),
            request.getWarehouseId(),
            request.getQuantity(),
            request.getUnitCost(),
            request.getDocumentId(),
            request.getDocumentType(),
            request.getBatchNumber(),
            request.getExpiryDate(),
            request.getSupplierId(),
            request.getReason()
        );
        
        InventoryTransactionDTO dto = new InventoryTransactionDTO(
            transactionId,
            request.getSkuId(),
            request.getWarehouseId(),
            TransactionType.INBOUND,
            request.getQuantity(),
            request.getUnitCost(),
            LocalDateTime.now(),
            "COMPLETED"
        );
        
        return ResponseEntity.ok(dto);
    }
    
    /**
     * 库存调整
     */
    @PostMapping("/adjust")
    public ResponseEntity<InventoryTransactionDTO> adjustInventory(
            @Valid @RequestBody InventoryAdjustmentRequest request) {
        
        String transactionId = inventoryService.adjustInventory(
            request.getSkuId(),
            request.getWarehouseId(),
            request.getQuantityChange(),
            request.getUnitCost(),
            request.getReason()
        );
        
        InventoryTransactionDTO dto = new InventoryTransactionDTO(
            transactionId,
            request.getSkuId(),
            request.getWarehouseId(),
            TransactionType.ADJUSTMENT,
            request.getQuantityChange(),
            request.getUnitCost(),
            LocalDateTime.now(),
            "COMPLETED"
        );
        
        return ResponseEntity.ok(dto);
    }
    
    /**
     * 库存转移
     */
    @PostMapping("/transfer")
    public ResponseEntity<InventoryTransferDTO> transferInventory(
            @Valid @RequestBody InventoryTransferRequest request) {
        
        try {
            String transferId = inventoryService.transferInventory(
                request.getSkuId(),
                request.getFromWarehouseId(),
                request.getToWarehouseId(),
                request.getQuantity(),
                request.getReason()
            );
            
            InventoryTransferDTO dto = new InventoryTransferDTO(
                transferId,
                request.getSkuId(),
                request.getFromWarehouseId(),
                request.getToWarehouseId(),
                request.getQuantity(),
                LocalDateTime.now(),
                "COMPLETED"
            );
            
            return ResponseEntity.ok(dto);
            
        } catch (InsufficientInventoryException e) {
            return ResponseEntity.badRequest()
                    .body(new InventoryTransferDTO(null, request.getSkuId(),
                          request.getFromWarehouseId(), request.getToWarehouseId(),
                          request.getQuantity(), LocalDateTime.now(),
                          "FAILED: " + e.getMessage()));
        }
    }
    
    /**
     * 获取库存事务历史
     */
    @GetMapping("/transactions")
    public ResponseEntity<PageResult<InventoryTransactionDTO>> getTransactionHistory(
            @RequestParam(required = false) String skuId,
            @RequestParam(required = false) String warehouseId,
            @RequestParam(required = false) TransactionType transactionType,
            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) LocalDateTime startTime,
            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) LocalDateTime endTime,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        
        PageResult<InventoryTransaction> result = inventoryService.getTransactionHistory(
            skuId, warehouseId, transactionType, startTime, endTime, page, size
        );
        
        PageResult<InventoryTransactionDTO> dtoResult = result.map(this::convertTransactionToDTO);
        
        return ResponseEntity.ok(dtoResult);
    }
    
    /**
     * 获取库存概览统计
     */
    @GetMapping("/stats/overview")
    public ResponseEntity<InventoryOverviewStatsDTO> getInventoryOverview(
            @RequestParam String warehouseId) {
        
        InventoryOverviewStats stats = analyticsService.getInventoryOverview(warehouseId);
        InventoryOverviewStatsDTO dto = convertOverviewStatsToDTO(stats);
        
        return ResponseEntity.ok(dto);
    }
    
    /**
     * 获取库存周转分析
     */
    @GetMapping("/analytics/turnover")
    public ResponseEntity<InventoryTurnoverAnalysisDTO> getTurnoverAnalysis(
            @RequestParam String warehouseId,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate) {
        
        InventoryTurnoverAnalysis analysis = analyticsService.getInventoryTurnoverAnalysis(
            warehouseId, startDate, endDate
        );
        
        InventoryTurnoverAnalysisDTO dto = convertTurnoverAnalysisToDTO(analysis);
        
        return ResponseEntity.ok(dto);
    }
    
    /**
     * 获取ABC分析
     */
    @GetMapping("/analytics/abc")
    public ResponseEntity<ABCAnalysisResultDTO> getABCAnalysis(
            @RequestParam String warehouseId,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate) {
        
        ABCAnalysisResult analysis = analyticsService.getABCAnalysis(warehouseId, startDate, endDate);
        ABCAnalysisResultDTO dto = convertABCAnalysisToDTO(analysis);
        
        return ResponseEntity.ok(dto);
    }
    
    /**
     * 获取库存异常分析
     */
    @GetMapping("/analytics/anomalies")
    public ResponseEntity<InventoryAnomalyAnalysisDTO> getAnomalyAnalysis(
            @RequestParam String warehouseId) {
        
        InventoryAnomalyAnalysis analysis = analyticsService.getInventoryAnomalyAnalysis(warehouseId);
        InventoryAnomalyAnalysisDTO dto = convertAnomalyAnalysisToDTO(analysis);
        
        return ResponseEntity.ok(dto);
    }
    
    /**
     * 获取补货建议
     */
    @GetMapping("/replenishment/recommendations")
    public ResponseEntity<ReplenishmentAnalysisResultDTO> getReplenishmentRecommendations(
            @RequestParam String warehouseId) {
        
        ReplenishmentAnalysisResult result = replenishmentService.analyzeWarehouseReplenishment(warehouseId);
        ReplenishmentAnalysisResultDTO dto = convertReplenishmentResultToDTO(result);
        
        return ResponseEntity.ok(dto);
    }
    
    /**
     * 获取库存预警
     */
    @GetMapping("/alerts")
    public ResponseEntity<List<InventoryAlertDTO>> getInventoryAlerts(
            @RequestParam String warehouseId,
            @RequestParam(required = false) AlertType alertType,
            @RequestParam(required = false) AlertLevel alertLevel) {
        
        List<InventoryAlert> alerts = alertService.checkInventoryAlerts(warehouseId, alertType, alertLevel);
        List<InventoryAlertDTO> dtoList = alerts.stream()
                .map(this::convertAlertToDTO)
                .collect(Collectors.toList());
        
        return ResponseEntity.ok(dtoList);
    }
    
    // DTO转换方法
    private InventoryItemDTO convertToDTO(InventoryItem item) {
        return new InventoryItemDTO(
            item.getSkuId(),
            item.getWarehouseId(),
            item.getLocationId(),
            item.getAvailableQuantity(),
            item.getReservedQuantity(),
            item.getAllocatedQuantity(),
            item.getInTransitQuantity(),
            item.getDamagedQuantity(),
            item.getTotalQuantity(),
            item.getSafetyStock(),
            item.getReorderPoint(),
            item.getMaxStock(),
            item.getUnitCost(),
            item.getLastUpdated(),
            item.getVersion(),
            item.getStatus(),
            item.getBatchNumber(),
            item.getExpiryDate(),
            item.getSupplierId()
        );
    }
    
    private InventoryTransactionDTO convertTransactionToDTO(InventoryTransaction transaction) {
        return new InventoryTransactionDTO(
            transaction.getTransactionId(),
            transaction.getSkuId(),
            transaction.getWarehouseId(),
            transaction.getTransactionType(),
            transaction.getQuantityChange(),
            transaction.getUnitCost(),
            transaction.getTransactionTime(),
            transaction.getTransactionStatus().name()
        );
    }
    
    private InventoryAlertDTO convertAlertToDTO(InventoryAlert alert) {
        return new InventoryAlertDTO(
            alert.getAlertId(),
            alert.getSkuId(),
            alert.getWarehouseId(),
            alert.getAlertType(),
            alert.getAlertLevel(),
            alert.getMessage(),
            alert.getCurrentQuantity(),
            alert.getThresholdQuantity(),
            alert.getCreatedTime(),
            alert.isResolved()
        );
    }
    
    // 其他DTO转换方法...
    private InventoryOverviewStatsDTO convertOverviewStatsToDTO(InventoryOverviewStats stats) {
        // 实现转换逻辑
        return new InventoryOverviewStatsDTO(/* 参数 */);
    }
    
    private InventoryTurnoverAnalysisDTO convertTurnoverAnalysisToDTO(InventoryTurnoverAnalysis analysis) {
        // 实现转换逻辑
        return new InventoryTurnoverAnalysisDTO(/* 参数 */);
    }
    
    private ABCAnalysisResultDTO convertABCAnalysisToDTO(ABCAnalysisResult analysis) {
        // 实现转换逻辑
        return new ABCAnalysisResultDTO(/* 参数 */);
    }
    
    private InventoryAnomalyAnalysisDTO convertAnomalyAnalysisToDTO(InventoryAnomalyAnalysis analysis) {
        // 实现转换逻辑
        return new InventoryAnomalyAnalysisDTO(/* 参数 */);
    }
    
    private ReplenishmentAnalysisResultDTO convertReplenishmentResultToDTO(ReplenishmentAnalysisResult result) {
        // 实现转换逻辑
        return new ReplenishmentAnalysisResultDTO(/* 参数 */);
    }
}

/**
 * 全局异常处理器
 */
@ControllerAdvice
public class InventoryExceptionHandler {
    
    @ExceptionHandler(InventoryNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleInventoryNotFound(InventoryNotFoundException e) {
        ErrorResponse error = new ErrorResponse(
            "INVENTORY_NOT_FOUND",
            e.getMessage(),
            LocalDateTime.now()
        );
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
    
    @ExceptionHandler(InsufficientInventoryException.class)
    public ResponseEntity<ErrorResponse> handleInsufficientInventory(InsufficientInventoryException e) {
        ErrorResponse error = new ErrorResponse(
            "INSUFFICIENT_INVENTORY",
            e.getMessage(),
            LocalDateTime.now()
        );
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(error);
    }
    
    @ExceptionHandler(InventoryLockException.class)
    public ResponseEntity<ErrorResponse> handleInventoryLock(InventoryLockException e) {
        ErrorResponse error = new ErrorResponse(
            "INVENTORY_LOCK_FAILED",
            e.getMessage(),
            LocalDateTime.now()
        );
        return ResponseEntity.status(HttpStatus.CONFLICT).body(error);
    }
    
    @ExceptionHandler(ValidationException.class)
    public ResponseEntity<ErrorResponse> handleValidation(ValidationException e) {
        ErrorResponse error = new ErrorResponse(
            "VALIDATION_ERROR",
            e.getMessage(),
            LocalDateTime.now()
        );
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(error);
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneral(Exception e) {
        ErrorResponse error = new ErrorResponse(
            "INTERNAL_ERROR",
            "系统内部错误，请稍后重试",
            LocalDateTime.now()
        );
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
    }
}

/**
 * 错误响应
 */
public class ErrorResponse {
    private final String code;
    private final String message;
    private final LocalDateTime timestamp;
    
    public ErrorResponse(String code, String message, LocalDateTime timestamp) {
        this.code = code;
        this.message = message;
        this.timestamp = timestamp;
    }
    
    // getters
    public String getCode() { return code; }
    public String getMessage() { return message; }
    public LocalDateTime getTimestamp() { return timestamp; }
}

10.8 性能优化策略

中央库存系统作为高并发系统，需要采用多种性能优化策略：

10.8.1 缓存策略

/**
 * 库存缓存服务
 */
@Service
public class InventoryCacheService {
    
    private final RedisTemplate<String, Object> redisTemplate;
    private final InventoryRepository inventoryRepository;
    
    private static final String INVENTORY_CACHE_PREFIX = "inventory:";
    private static final String AVAILABILITY_CACHE_PREFIX = "availability:";
    private static final int CACHE_TTL_SECONDS = 300; // 5分钟
    
    public InventoryCacheService(RedisTemplate<String, Object> redisTemplate,
                               InventoryRepository inventoryRepository) {
        this.redisTemplate = redisTemplate;
        this.inventoryRepository = inventoryRepository;
    }
    
    /**
     * 获取缓存的库存信息
     */
    public Optional<InventoryItem> getCachedInventory(String skuId, String warehouseId) {
        String key = INVENTORY_CACHE_PREFIX + skuId + ":" + warehouseId;
        InventoryItem cached = (InventoryItem) redisTemplate.opsForValue().get(key);
        return Optional.ofNullable(cached);
    }
    
    /**
     * 缓存库存信息
     */
    public void cacheInventory(InventoryItem inventory) {
        String key = INVENTORY_CACHE_PREFIX + inventory.getSkuId() + ":" + inventory.getWarehouseId();
        redisTemplate.opsForValue().set(key, inventory, CACHE_TTL_SECONDS, TimeUnit.SECONDS);
    }
    
    /**
     * 删除库存缓存
     */
    public void evictInventoryCache(String skuId, String warehouseId) {
        String key = INVENTORY_CACHE_PREFIX + skuId + ":" + warehouseId;
        redisTemplate.delete(key);
    }
    
    /**
     * 批量预热库存缓存
     */
    @Async
    public void warmUpInventoryCache(String warehouseId) {
        List<InventoryItem> inventories = inventoryRepository.findByWarehouseId(warehouseId);
        
        for (InventoryItem inventory : inventories) {
            cacheInventory(inventory);
        }
    }
    
    /**
     * 缓存库存可用性检查结果
     */
    public void cacheAvailabilityCheck(String skuId, String warehouseId, int quantity, boolean available) {
        String key = AVAILABILITY_CACHE_PREFIX + skuId + ":" + warehouseId + ":" + quantity;
        redisTemplate.opsForValue().set(key, available, 60, TimeUnit.SECONDS); // 1分钟缓存
    }
    
    /**
     * 获取缓存的可用性检查结果
     */
    public Optional<Boolean> getCachedAvailabilityCheck(String skuId, String warehouseId, int quantity) {
        String key = AVAILABILITY_CACHE_PREFIX + skuId + ":" + warehouseId + ":" + quantity;
        Boolean cached = (Boolean) redisTemplate.opsForValue().get(key);
        return Optional.ofNullable(cached);
    }
}

10.8.2 数据库优化

-- 库存表索引优化
CREATE INDEX idx_inventory_warehouse_sku ON inventory_items(warehouse_id, sku_id);
CREATE INDEX idx_inventory_status ON inventory_items(status);
CREATE INDEX idx_inventory_updated ON inventory_items(last_updated);
CREATE INDEX idx_inventory_safety_stock ON inventory_items(available_quantity, safety_stock);

-- 事务表索引优化
CREATE INDEX idx_transaction_sku_warehouse ON inventory_transactions(sku_id, warehouse_id);
CREATE INDEX idx_transaction_time ON inventory_transactions(transaction_time);
CREATE INDEX idx_transaction_type ON inventory_transactions(transaction_type);
CREATE INDEX idx_transaction_document ON inventory_transactions(document_id, document_type);

-- 分区策略（按时间分区）
CREATE TABLE inventory_transactions_2024_01 PARTITION OF inventory_transactions
FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');

CREATE TABLE inventory_transactions_2024_02 PARTITION OF inventory_transactions
FOR VALUES FROM ('2024-02-01') TO ('2024-03-01');

-- 库存汇总视图
CREATE MATERIALIZED VIEW inventory_summary AS
SELECT 
    warehouse_id,
    COUNT(*) as total_skus,
    SUM(total_quantity) as total_quantity,
    SUM(available_quantity) as available_quantity,
    SUM(reserved_quantity) as reserved_quantity,
    SUM(unit_cost * total_quantity) as total_value,
    COUNT(CASE WHEN available_quantity <= COALESCE(safety_stock, 10) THEN 1 END) as low_stock_count,
    COUNT(CASE WHEN available_quantity <= 0 THEN 1 END) as out_of_stock_count
FROM inventory_items
WHERE status = 'ACTIVE'
GROUP BY warehouse_id;

-- 定期刷新汇总视图
CREATE OR REPLACE FUNCTION refresh_inventory_summary()
RETURNS void AS $$
BEGIN
    REFRESH MATERIALIZED VIEW inventory_summary;
END;
$$ LANGUAGE plpgsql;

-- 创建定时任务刷新视图
SELECT cron.schedule('refresh-inventory-summary', '*/5 * * * *', 'SELECT refresh_inventory_summary();');

10.8.3 读写分离

/**
 * 读写分离配置
 */
@Configuration
public class DatabaseConfig {
    
    @Bean
    @Primary
    public DataSource routingDataSource() {
        RoutingDataSource routingDataSource = new RoutingDataSource();
        
        Map<Object, Object> dataSourceMap = new HashMap<>();
        dataSourceMap.put("write", writeDataSource());
        dataSourceMap.put("read", readDataSource());
        
        routingDataSource.setTargetDataSources(dataSourceMap);
        routingDataSource.setDefaultTargetDataSource(writeDataSource());
        
        return routingDataSource;
    }
    
    @Bean
    public DataSource writeDataSource() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:postgresql://write-db:5432/inventory");
        config.setUsername("inventory_user");
        config.setPassword("password");
        config.setMaximumPoolSize(20);
        return new HikariDataSource(config);
    }
    
    @Bean
    public DataSource readDataSource() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:postgresql://read-db:5432/inventory");
        config.setUsername("inventory_user");
        config.setPassword("password");
        config.setMaximumPoolSize(30);
        config.setReadOnly(true);
        return new HikariDataSource(config);
    }
}

/**
 * 动态数据源路由
 */
public class RoutingDataSource extends AbstractRoutingDataSource {
    
    @Override
    protected Object determineCurrentLookupKey() {
        return DatabaseContextHolder.getDataSourceType();
    }
}

/**
 * 数据源上下文
 */
public class DatabaseContextHolder {
    
    private static final ThreadLocal<String> contextHolder = new ThreadLocal<>();
    
    public static void setDataSourceType(String dataSourceType) {
        contextHolder.set(dataSourceType);
    }
    
    public static String getDataSourceType() {
        return contextHolder.get();
    }
    
    public static void clearDataSourceType() {
        contextHolder.remove();
    }
}

/**
 * 读写分离注解
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ReadOnly {
}

/**
 * 读写分离切面
 */
@Aspect
@Component
public class ReadOnlyAspect {
    
    @Before("@annotation(readOnly)")
    public void setReadDataSourceType(ReadOnly readOnly) {
        DatabaseContextHolder.setDataSourceType("read");
    }
    
    @Before("@within(readOnly) && !@annotation(org.springframework.transaction.annotation.Transactional)")
    public void setReadDataSourceTypeForClass(ReadOnly readOnly) {
        DatabaseContextHolder.setDataSourceType("read");
    }
    
    @After("@annotation(readOnly) || @within(readOnly)")
    public void resetDataSourceType() {
        DatabaseContextHolder.clearDataSourceType();
    }
}

10.9 本章总结

本章详细介绍了SaaS平台中央库存系统的设计与实现，涵盖了以下核心内容：

10.9.1 系统架构设计

中央库存系统采用了分层架构设计，包括：

• 数据层：基于关系型数据库的库存数据模型，支持多仓库、多SKU的复杂库存管理
• 服务层：核心业务逻辑实现，包括库存查询、预留、分配、出入库等操作
• 缓存层：基于Redis的分布式缓存，提升系统性能和响应速度
• API层：RESTful API接口，支持各种库存操作和查询需求

10.9.2 核心功能实现

系统实现了完整的库存管理功能：

1. 基础库存管理

   • 多维度库存数据模型（可用、预留、分配、在途、损坏等）
   • 完整的库存事务记录和审计跟踪
   • 灵活的库存状态管理和生命周期控制

2. 库存操作功能

   • 库存查询和可用性检查
   • 库存预留和释放机制
   • 库存分配和出入库操作
   • 库存调整和转移功能

3. 数据一致性保证

   • 基于Redis的分布式锁机制
   • 事件驱动的库存同步
   • 库存数据一致性检查和修复

4. 智能预警和补货

   • 多层次库存预警系统
   • 基于历史数据的智能补货策略
   • 经济订货量（EOQ）和安全库存计算

5. 统计分析功能

   • 库存概览和实时统计
   • 库存周转率分析
   • ABC分析和异常检测

10.9.3 技术特点

系统在技术实现上具有以下特点：

1. 高并发处理

   • 分布式锁保证并发安全
   • 缓存策略提升访问性能
   • 读写分离优化数据库负载

2. 数据一致性

   • 事务管理确保操作原子性
   • 事件驱动保证数据同步
   • 定期一致性检查和修复

3. 可扩展性

   • 微服务架构支持水平扩展
   • 数据库分区支持大数据量
   • 插件化设计支持功能扩展

4. 监控和运维

   • 完整的日志记录和审计
   • 性能监控和预警机制
   • 自动化运维和故障恢复

10.9.4 实践建议

在实际项目中实施中央库存系统时，建议：

1. 分阶段实施

   • 先实现基础库存管理功能
   • 逐步增加智能预警和分析功能
   • 最后优化性能和扩展功能

2. 数据质量管理

   • 建立完善的数据校验机制
   • 定期进行数据一致性检查
   • 制定数据清理和修复流程

3. 性能优化

   • 合理设计缓存策略
   • 优化数据库查询和索引
   • 监控系统性能指标

4. 业务集成

   • 与订单系统紧密集成
   • 支持多渠道库存共享
   • 提供灵活的API接口

10.9.5 发展趋势

中央库存系统的发展趋势包括：

1. 智能化升级

   • AI驱动的需求预测
   • 机器学习优化补货策略
   • 智能库存配置建议

2. 实时化处理

   • 流式数据处理
   • 实时库存同步
   • 即时预警和响应

3. 云原生架构

   • 容器化部署
   • 服务网格管理
   • 弹性伸缩能力

中央库存系统作为SaaS平台的核心组件，其设计和实现质量直接影响整个平台的稳定性和性能。通过本章的学习，读者应该能够理解和掌握构建高可用、高性能库存管理系统的关键技术和最佳实践。

10.2.2 库存事务记录

为了确保库存数据的可追溯性和审计能力，系统需要记录所有的库存变更事务：

/**
 * 库存事务记录
 */
@Entity
@Table(name = "inventory_transaction")
public class InventoryTransaction extends BaseEntity {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "transaction_id", unique = true, nullable = false)
    private String transactionId;            // 事务ID
    
    @Column(name = "sku_id", nullable = false)
    private String skuId;                    // SKU标识
    
    @Column(name = "warehouse_id", nullable = false)
    private String warehouseId;              // 仓库标识
    
    @Column(name = "location_id")
    private String locationId;               // 库位标识
    
    @Enumerated(EnumType.STRING)
    @Column(name = "transaction_type", nullable = false)
    private TransactionType transactionType; // 事务类型
    
    @Column(name = "quantity_change", nullable = false)
    private Integer quantityChange;          // 数量变更
    
    @Column(name = "quantity_before")
    private Integer quantityBefore;          // 变更前数量
    
    @Column(name = "quantity_after")
    private Integer quantityAfter;           // 变更后数量
    
    @Column(name = "unit_cost")
    private BigDecimal unitCost;             // 单位成本
    
    @Column(name = "total_cost")
    private BigDecimal totalCost;            // 总成本
    
    @Column(name = "reference_id")
    private String referenceId;              // 关联单据ID
    
    @Column(name = "reference_type")
    private String referenceType;            // 关联单据类型
    
    @Column(name = "batch_number")
    private String batchNumber;              // 批次号
    
    @Column(name = "supplier_id")
    private String supplierId;               // 供应商ID
    
    @Column(name = "customer_id")
    private String customerId;               // 客户ID
    
    @Column(name = "reason")
    private String reason;                   // 变更原因
    
    @Column(name = "notes")
    private String notes;                    // 备注
    
    @Column(name = "transaction_time", nullable = false)
    private LocalDateTime transactionTime;   // 事务时间
    
    @Column(name = "processed_by")
    private String processedBy;              // 处理人
    
    @Enumerated(EnumType.STRING)
    @Column(name = "status")
    private TransactionStatus status;        // 事务状态
    
    // 构造函数
    public InventoryTransaction() {
        this.transactionId = generateTransactionId();
        this.transactionTime = LocalDateTime.now();
        this.status = TransactionStatus.PENDING;
    }
    
    public InventoryTransaction(String skuId, String warehouseId, 
                              TransactionType transactionType, Integer quantityChange) {
        this();
        this.skuId = skuId;
        this.warehouseId = warehouseId;
        this.transactionType = transactionType;
        this.quantityChange = quantityChange;
    }
    
    /**
     * 生成事务ID
     */
    private String generateTransactionId() {
        return "TXN" + System.currentTimeMillis() + 
               String.format("%04d", new Random().nextInt(10000));
    }
    
    /**
     * 计算总成本
     */
    public void calculateTotalCost() {
        if (unitCost != null && quantityChange != null) {
            this.totalCost = unitCost.multiply(new BigDecimal(Math.abs(quantityChange)));
        }
    }
    
    /**
     * 标记事务完成
     */
    public void markCompleted() {
        this.status = TransactionStatus.COMPLETED;
    }
    
    /**
     * 标记事务失败
     */
    public void markFailed(String reason) {
        this.status = TransactionStatus.FAILED;
        this.reason = reason;
    }
    
    // getters and setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getTransactionId() { return transactionId; }
    public void setTransactionId(String transactionId) { this.transactionId = transactionId; }
    
    public String getSkuId() { return skuId; }
    public void setSkuId(String skuId) { this.skuId = skuId; }
    
    public String getWarehouseId() { return warehouseId; }
    public void setWarehouseId(String warehouseId) { this.warehouseId = warehouseId; }
    
    public String getLocationId() { return locationId; }
    public void setLocationId(String locationId) { this.locationId = locationId; }
    
    public TransactionType getTransactionType() { return transactionType; }
    public void setTransactionType(TransactionType transactionType) { this.transactionType = transactionType; }
    
    public Integer getQuantityChange() { return quantityChange; }
    public void setQuantityChange(Integer quantityChange) { 
        this.quantityChange = quantityChange;
        calculateTotalCost();
    }
    
    public Integer getQuantityBefore() { return quantityBefore; }
    public void setQuantityBefore(Integer quantityBefore) { this.quantityBefore = quantityBefore; }
    
    public Integer getQuantityAfter() { return quantityAfter; }
    public void setQuantityAfter(Integer quantityAfter) { this.quantityAfter = quantityAfter; }
    
    public BigDecimal getUnitCost() { return unitCost; }
    public void setUnitCost(BigDecimal unitCost) { 
        this.unitCost = unitCost;
        calculateTotalCost();
    }
    
    public BigDecimal getTotalCost() { return totalCost; }
    public void setTotalCost(BigDecimal totalCost) { this.totalCost = totalCost; }
    
    public String getReferenceId() { return referenceId; }
    public void setReferenceId(String referenceId) { this.referenceId = referenceId; }
    
    public String getReferenceType() { return referenceType; }
    public void setReferenceType(String referenceType) { this.referenceType = referenceType; }
    
    public String getBatchNumber() { return batchNumber; }
    public void setBatchNumber(String batchNumber) { this.batchNumber = batchNumber; }
    
    public String getSupplierId() { return supplierId; }
    public void setSupplierId(String supplierId) { this.supplierId = supplierId; }
    
    public String getCustomerId() { return customerId; }
    public void setCustomerId(String customerId) { this.customerId = customerId; }
    
    public String getReason() { return reason; }
    public void setReason(String reason) { this.reason = reason; }
    
    public String getNotes() { return notes; }
    public void setNotes(String notes) { this.notes = notes; }
    
    public LocalDateTime getTransactionTime() { return transactionTime; }
    public void setTransactionTime(LocalDateTime transactionTime) { this.transactionTime = transactionTime; }
    
    public String getProcessedBy() { return processedBy; }
    public void setProcessedBy(String processedBy) { this.processedBy = processedBy; }
    
    public TransactionStatus getStatus() { return status; }
    public void setStatus(TransactionStatus status) { this.status = status; }
}

/**
 * 事务类型枚举
 */
public enum TransactionType {
    INBOUND("入库", 1),
    OUTBOUND("出库", -1),
    TRANSFER_IN("调拨入库", 1),
    TRANSFER_OUT("调拨出库", -1),
    ADJUSTMENT_INCREASE("盘盈", 1),
    ADJUSTMENT_DECREASE("盘亏", -1),
    RESERVE("预留", 0),
    RELEASE_RESERVE("释放预留", 0),
    ALLOCATE("分配", 0),
    DAMAGE("损坏", -1),
    RETURN("退货", 1),
    CONSUME("消耗", -1);
    
    private final String description;
    private final int quantityMultiplier;  // 数量乘数，用于计算库存变化方向
    
    TransactionType(String description, int quantityMultiplier) {
        this.description = description;
        this.quantityMultiplier = quantityMultiplier;
    }
    
    public String getDescription() {
        return description;
    }
    
    public int getQuantityMultiplier() {
        return quantityMultiplier;
    }
    
    /**
     * 是否为入库类型
     */
    public boolean isInbound() {
        return quantityMultiplier > 0;
    }
    
    /**
     * 是否为出库类型
     */
    public boolean isOutbound() {
        return quantityMultiplier < 0;
    }
    
    /**
     * 是否为状态变更类型
     */
    public boolean isStatusChange() {
        return quantityMultiplier == 0;
    }
}

/**
 * 事务状态枚举
 */
public enum TransactionStatus {
    PENDING("待处理"),
    PROCESSING("处理中"),
    COMPLETED("已完成"),
    FAILED("失败"),
    CANCELLED("已取消"),
    REVERSED("已冲销");
    
    private final String description;
    
    TransactionStatus(String description) {
        this.description = description;
    }
    
    public String getDescription() {
        return description;
    }
}

10.3 库存服务核心功能

中央库存系统的核心功能包括库存查询、库存更新、库存预留、库存分配等。这些功能需要保证高性能、高并发和数据一致性。

10.3.1 库存服务接口设计

/**
 * 库存服务接口
 */
public interface InventoryService {
    
    /**
     * 查询库存信息
     */
    InventoryItem getInventory(String skuId, String warehouseId);
    
    /**
     * 批量查询库存信息
     */
    List<InventoryItem> getInventories(List<String> skuIds, String warehouseId);
    
    /**
     * 查询SKU在所有仓库的库存
     */
    List<InventoryItem> getInventoriesBySku(String skuId);
    
    /**
     * 查询仓库所有库存
     */
    List<InventoryItem> getInventoriesByWarehouse(String warehouseId);
    
    /**
     * 检查库存可用性
     */
    boolean checkAvailability(String skuId, String warehouseId, Integer quantity);
    
    /**
     * 批量检查库存可用性
     */
    Map<String, Boolean> checkAvailabilities(Map<String, Integer> skuQuantities, String warehouseId);
    
    /**
     * 预留库存
     */
    ReservationResult reserveInventory(InventoryReservationRequest request);
    
    /**
     * 批量预留库存
     */
    List<ReservationResult> reserveInventories(List<InventoryReservationRequest> requests);
    
    /**
     * 释放预留库存
     */
    boolean releaseReservation(String reservationId);
    
    /**
     * 分配库存
     */
    AllocationResult allocateInventory(InventoryAllocationRequest request);
    
    /**
     * 批量分配库存
     */
    List<AllocationResult> allocateInventories(List<InventoryAllocationRequest> requests);
    
    /**
     * 出库
     */
    ShipmentResult shipInventory(InventoryShipmentRequest request);
    
    /**
     * 入库
     */
    ReceiptResult receiveInventory(InventoryReceiptRequest request);
    
    /**
     * 库存调整
     */
    AdjustmentResult adjustInventory(InventoryAdjustmentRequest request);
    
    /**
     * 库存转移
     */
    TransferResult transferInventory(InventoryTransferRequest request);
    
    /**
     * 获取库存事务历史
     */
    List<InventoryTransaction> getTransactionHistory(String skuId, String warehouseId, 
                                                   LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 获取低库存预警
     */
    List<InventoryAlert> getLowStockAlerts(String warehouseId);
    
    /**
     * 获取库存统计信息
     */
    InventoryStatistics getInventoryStatistics(String warehouseId, LocalDate date);
}

10.3.2 库存服务实现

/**
 * 库存服务实现
 */
@Service
@Transactional
public class InventoryServiceImpl implements InventoryService {
    
    private final InventoryRepository inventoryRepository;
    private final InventoryTransactionRepository transactionRepository;
    private final InventoryLockService lockService;
    private final InventoryEventPublisher eventPublisher;
    private final InventoryValidator validator;
    private final RedisTemplate<String, Object> redisTemplate;
    
    public InventoryServiceImpl(InventoryRepository inventoryRepository,
                              InventoryTransactionRepository transactionRepository,
                              InventoryLockService lockService,
                              InventoryEventPublisher eventPublisher,
                              InventoryValidator validator,
                              RedisTemplate<String, Object> redisTemplate) {
        this.inventoryRepository = inventoryRepository;
        this.transactionRepository = transactionRepository;
        this.lockService = lockService;
        this.eventPublisher = eventPublisher;
        this.validator = validator;
        this.redisTemplate = redisTemplate;
    }
    
    @Override
    @Cacheable(value = "inventory", key = "#skuId + ':' + #warehouseId")
    public InventoryItem getInventory(String skuId, String warehouseId) {
        return inventoryRepository.findBySkuIdAndWarehouseId(skuId, warehouseId)
                .orElse(null);
    }
    
    @Override
    public List<InventoryItem> getInventories(List<String> skuIds, String warehouseId) {
        return inventoryRepository.findBySkuIdInAndWarehouseId(skuIds, warehouseId);
    }
    
    @Override
    public List<InventoryItem> getInventoriesBySku(String skuId) {
        return inventoryRepository.findBySkuId(skuId);
    }
    
    @Override
    public List<InventoryItem> getInventoriesByWarehouse(String warehouseId) {
        return inventoryRepository.findByWarehouseId(warehouseId);
    }
    
    @Override
    public boolean checkAvailability(String skuId, String warehouseId, Integer quantity) {
        InventoryItem inventory = getInventory(skuId, warehouseId);
        return inventory != null && inventory.hasSufficientStock(quantity);
    }
    
    @Override
    public Map<String, Boolean> checkAvailabilities(Map<String, Integer> skuQuantities, String warehouseId) {
        Map<String, Boolean> results = new HashMap<>();
        
        List<String> skuIds = new ArrayList<>(skuQuantities.keySet());
        List<InventoryItem> inventories = getInventories(skuIds, warehouseId);
        
        Map<String, InventoryItem> inventoryMap = inventories.stream()
                .collect(Collectors.toMap(InventoryItem::getSkuId, Function.identity()));
        
        for (Map.Entry<String, Integer> entry : skuQuantities.entrySet()) {
            String skuId = entry.getKey();
            Integer quantity = entry.getValue();
            
            InventoryItem inventory = inventoryMap.get(skuId);
            boolean available = inventory != null && inventory.hasSufficientStock(quantity);
            results.put(skuId, available);
        }
        
        return results;
    }
    
    @Override
    public ReservationResult reserveInventory(InventoryReservationRequest request) {
        String lockKey = generateLockKey(request.getSkuId(), request.getWarehouseId());
        
        return lockService.executeWithLock(lockKey, () -> {
            // 验证请求
            validator.validateReservationRequest(request);
            
            // 获取库存
            InventoryItem inventory = getInventory(request.getSkuId(), request.getWarehouseId());
            if (inventory == null) {
                return ReservationResult.failure("库存不存在");
            }
            
            // 检查库存可用性
            if (!inventory.hasSufficientStock(request.getQuantity())) {
                return ReservationResult.failure("库存不足");
            }
            
            // 预留库存
            boolean success = inventory.reserveStock(request.getQuantity());
            if (!success) {
                return ReservationResult.failure("预留失败");
            }
            
            // 保存库存变更
            inventoryRepository.save(inventory);
            
            // 记录事务
            InventoryTransaction transaction = createTransaction(
                request.getSkuId(), request.getWarehouseId(),
                TransactionType.RESERVE, request.getQuantity(),
                request.getReferenceId(), request.getReferenceType()
            );
            transactionRepository.save(transaction);
            
            // 清除缓存
            evictInventoryCache(request.getSkuId(), request.getWarehouseId());
            
            // 发布事件
            eventPublisher.publishInventoryReserved(inventory, request.getQuantity());
            
            return ReservationResult.success(transaction.getTransactionId());
        });
    }
    
    @Override
    public List<ReservationResult> reserveInventories(List<InventoryReservationRequest> requests) {
        List<ReservationResult> results = new ArrayList<>();
        
        for (InventoryReservationRequest request : requests) {
            try {
                ReservationResult result = reserveInventory(request);
                results.add(result);
                
                // 如果预留失败，回滚之前的预留
                if (!result.isSuccess()) {
                    rollbackReservations(results);
                    break;
                }
            } catch (Exception e) {
                results.add(ReservationResult.failure("预留异常: " + e.getMessage()));
                rollbackReservations(results);
                break;
            }
        }
        
        return results;
    }
    
    @Override
    public boolean releaseReservation(String reservationId) {
        InventoryTransaction transaction = transactionRepository.findByTransactionId(reservationId)
                .orElse(null);
        
        if (transaction == null || transaction.getTransactionType() != TransactionType.RESERVE) {
            return false;
        }
        
        String lockKey = generateLockKey(transaction.getSkuId(), transaction.getWarehouseId());
        
        return lockService.executeWithLock(lockKey, () -> {
            InventoryItem inventory = getInventory(transaction.getSkuId(), transaction.getWarehouseId());
            if (inventory == null) {
                return false;
            }
            
            // 释放预留库存
            inventory.releaseReservedStock(transaction.getQuantityChange());
            inventoryRepository.save(inventory);
            
            // 记录释放事务
            InventoryTransaction releaseTransaction = createTransaction(
                transaction.getSkuId(), transaction.getWarehouseId(),
                TransactionType.RELEASE_RESERVE, transaction.getQuantityChange(),
                transaction.getReferenceId(), transaction.getReferenceType()
            );
            transactionRepository.save(releaseTransaction);
            
            // 清除缓存
            evictInventoryCache(transaction.getSkuId(), transaction.getWarehouseId());
            
            // 发布事件
            eventPublisher.publishReservationReleased(inventory, transaction.getQuantityChange());
            
            return true;
        });
    }
    
    @Override
    public AllocationResult allocateInventory(InventoryAllocationRequest request) {
        String lockKey = generateLockKey(request.getSkuId(), request.getWarehouseId());
        
        return lockService.executeWithLock(lockKey, () -> {
            // 验证请求
            validator.validateAllocationRequest(request);
            
            // 获取库存
            InventoryItem inventory = getInventory(request.getSkuId(), request.getWarehouseId());
            if (inventory == null) {
                return AllocationResult.failure("库存不存在");
            }
            
            // 分配库存
            boolean success = inventory.allocateStock(request.getQuantity());
            if (!success) {
                return AllocationResult.failure("分配失败，预留库存不足");
            }
            
            // 保存库存变更
            inventoryRepository.save(inventory);
            
            // 记录事务
            InventoryTransaction transaction = createTransaction(
                request.getSkuId(), request.getWarehouseId(),
                TransactionType.ALLOCATE, request.getQuantity(),
                request.getReferenceId(), request.getReferenceType()
            );
            transactionRepository.save(transaction);
            
            // 清除缓存
            evictInventoryCache(request.getSkuId(), request.getWarehouseId());
            
            // 发布事件
            eventPublisher.publishInventoryAllocated(inventory, request.getQuantity());
            
            return AllocationResult.success(transaction.getTransactionId());
        });
    }
    
    @Override
    public List<AllocationResult> allocateInventories(List<InventoryAllocationRequest> requests) {
        List<AllocationResult> results = new ArrayList<>();
        
        for (InventoryAllocationRequest request : requests) {
            try {
                AllocationResult result = allocateInventory(request);
                results.add(result);
                
                // 如果分配失败，回滚之前的分配
                if (!result.isSuccess()) {
                    rollbackAllocations(results);
                    break;
                }
            } catch (Exception e) {
                results.add(AllocationResult.failure("分配异常: " + e.getMessage()));
                rollbackAllocations(results);
                break;
            }
        }
        
        return results;
    }
    
    @Override
    public ShipmentResult shipInventory(InventoryShipmentRequest request) {
        String lockKey = generateLockKey(request.getSkuId(), request.getWarehouseId());
        
        return lockService.executeWithLock(lockKey, () -> {
            // 验证请求
            validator.validateShipmentRequest(request);
            
            // 获取库存
            InventoryItem inventory = getInventory(request.getSkuId(), request.getWarehouseId());
            if (inventory == null) {
                return ShipmentResult.failure("库存不存在");
            }
            
            // 出库
            boolean success = inventory.shipStock(request.getQuantity());
            if (!success) {
                return ShipmentResult.failure("出库失败，已分配库存不足");
            }
            
            // 保存库存变更
            inventoryRepository.save(inventory);
            
            // 记录事务
            InventoryTransaction transaction = createTransaction(
                request.getSkuId(), request.getWarehouseId(),
                TransactionType.OUTBOUND, request.getQuantity(),
                request.getReferenceId(), request.getReferenceType()
            );
            transaction.setCustomerId(request.getCustomerId());
            transactionRepository.save(transaction);
            
            // 清除缓存
            evictInventoryCache(request.getSkuId(), request.getWarehouseId());
            
            // 发布事件
            eventPublisher.publishInventoryShipped(inventory, request.getQuantity());
            
            return ShipmentResult.success(transaction.getTransactionId());
        });
    }
    
    @Override
    public ReceiptResult receiveInventory(InventoryReceiptRequest request) {
        String lockKey = generateLockKey(request.getSkuId(), request.getWarehouseId());
        
        return lockService.executeWithLock(lockKey, () -> {
            // 验证请求
            validator.validateReceiptRequest(request);
            
            // 获取或创建库存
            InventoryItem inventory = getInventory(request.getSkuId(), request.getWarehouseId());
            if (inventory == null) {
                inventory = new InventoryItem(request.getSkuId(), request.getWarehouseId());
                inventory.setLocationId(request.getLocationId());
                inventory.setBatchNumber(request.getBatchNumber());
                inventory.setSupplierId(request.getSupplierId());
                inventory.setUnitCost(request.getUnitCost());
            }
            
            // 入库
            inventory.receiveStock(request.getQuantity());
            
            // 保存库存变更
            inventoryRepository.save(inventory);
            
            // 记录事务
            InventoryTransaction transaction = createTransaction(
                request.getSkuId(), request.getWarehouseId(),
                TransactionType.INBOUND, request.getQuantity(),
                request.getReferenceId(), request.getReferenceType()
            );
            transaction.setSupplierId(request.getSupplierId());
            transaction.setBatchNumber(request.getBatchNumber());
            transaction.setUnitCost(request.getUnitCost());
            transactionRepository.save(transaction);
            
            // 清除缓存
            evictInventoryCache(request.getSkuId(), request.getWarehouseId());
            
            // 发布事件
            eventPublisher.publishInventoryReceived(inventory, request.getQuantity());
            
            return ReceiptResult.success(transaction.getTransactionId());
        });
    }
    
    @Override
    public AdjustmentResult adjustInventory(InventoryAdjustmentRequest request) {
        String lockKey = generateLockKey(request.getSkuId(), request.getWarehouseId());
        
        return lockService.executeWithLock(lockKey, () -> {
            // 验证请求
            validator.validateAdjustmentRequest(request);
            
            // 获取库存
            InventoryItem inventory = getInventory(request.getSkuId(), request.getWarehouseId());
            if (inventory == null) {
                return AdjustmentResult.failure("库存不存在");
            }
            
            // 记录调整前数量
            Integer quantityBefore = inventory.getAvailableQuantity();
            
            // 调整库存
            inventory.setAvailableQuantity(request.getNewQuantity());
            
            // 保存库存变更
            inventoryRepository.save(inventory);
            
            // 计算调整数量
            Integer adjustmentQuantity = request.getNewQuantity() - quantityBefore;
            TransactionType transactionType = adjustmentQuantity > 0 ? 
                TransactionType.ADJUSTMENT_INCREASE : TransactionType.ADJUSTMENT_DECREASE;
            
            // 记录事务
            InventoryTransaction transaction = createTransaction(
                request.getSkuId(), request.getWarehouseId(),
                transactionType, Math.abs(adjustmentQuantity),
                request.getReferenceId(), "ADJUSTMENT"
            );
            transaction.setQuantityBefore(quantityBefore);
            transaction.setQuantityAfter(request.getNewQuantity());
            transaction.setReason(request.getReason());
            transactionRepository.save(transaction);
            
            // 清除缓存
            evictInventoryCache(request.getSkuId(), request.getWarehouseId());
            
            // 发布事件
            eventPublisher.publishInventoryAdjusted(inventory, adjustmentQuantity);
            
            return AdjustmentResult.success(transaction.getTransactionId());
        });
    }
    
    @Override
    public TransferResult transferInventory(InventoryTransferRequest request) {
        // 使用分布式锁确保转移操作的原子性
        String lockKey1 = generateLockKey(request.getSkuId(), request.getFromWarehouseId());
        String lockKey2 = generateLockKey(request.getSkuId(), request.getToWarehouseId());
        
        // 按字典序排序锁键，避免死锁
        List<String> lockKeys = Arrays.asList(lockKey1, lockKey2);
        Collections.sort(lockKeys);
        
        return lockService.executeWithLocks(lockKeys, () -> {
            // 验证请求
            validator.validateTransferRequest(request);
            
            // 获取源仓库库存
            InventoryItem fromInventory = getInventory(request.getSkuId(), request.getFromWarehouseId());
            if (fromInventory == null || !fromInventory.hasSufficientStock(request.getQuantity())) {
                return TransferResult.failure("源仓库库存不足");
            }
            
            // 获取或创建目标仓库库存
            InventoryItem toInventory = getInventory(request.getSkuId(), request.getToWarehouseId());
            if (toInventory == null) {
                toInventory = new InventoryItem(request.getSkuId(), request.getToWarehouseId());
            }
            
            // 执行转移
            fromInventory.setAvailableQuantity(fromInventory.getAvailableQuantity() - request.getQuantity());
            toInventory.receiveStock(request.getQuantity());
            
            // 保存库存变更
            inventoryRepository.save(fromInventory);
            inventoryRepository.save(toInventory);
            
            // 记录转出事务
            InventoryTransaction outTransaction = createTransaction(
                request.getSkuId(), request.getFromWarehouseId(),
                TransactionType.TRANSFER_OUT, request.getQuantity(),
                request.getReferenceId(), "TRANSFER"
            );
            transactionRepository.save(outTransaction);
            
            // 记录转入事务
            InventoryTransaction inTransaction = createTransaction(
                request.getSkuId(), request.getToWarehouseId(),
                TransactionType.TRANSFER_IN, request.getQuantity(),
                request.getReferenceId(), "TRANSFER"
            );
            transactionRepository.save(inTransaction);
            
            // 清除缓存
            evictInventoryCache(request.getSkuId(), request.getFromWarehouseId());
            evictInventoryCache(request.getSkuId(), request.getToWarehouseId());
            
            // 发布事件
            eventPublisher.publishInventoryTransferred(fromInventory, toInventory, request.getQuantity());
            
            return TransferResult.success(outTransaction.getTransactionId(), inTransaction.getTransactionId());
        });
    }
    
    @Override
    public List<InventoryTransaction> getTransactionHistory(String skuId, String warehouseId, 
                                                          LocalDateTime startTime, LocalDateTime endTime) {
        return transactionRepository.findBySkuIdAndWarehouseIdAndTransactionTimeBetween(
            skuId, warehouseId, startTime, endTime
        );
    }
    
    @Override
    public List<InventoryAlert> getLowStockAlerts(String warehouseId) {
        List<InventoryItem> lowStockItems = inventoryRepository.findLowStockItems(warehouseId);
        
        return lowStockItems.stream()
                .map(this::createLowStockAlert)
                .collect(Collectors.toList());
    }
    
    @Override
    public InventoryStatistics getInventoryStatistics(String warehouseId, LocalDate date) {
        return inventoryRepository.calculateStatistics(warehouseId, date);
    }
    
    // 私有辅助方法
    
    private String generateLockKey(String skuId, String warehouseId) {
        return "inventory:lock:" + skuId + ":" + warehouseId;
    }
    
    private InventoryTransaction createTransaction(String skuId, String warehouseId,
                                                 TransactionType type, Integer quantity,
                                                 String referenceId, String referenceType) {
        InventoryTransaction transaction = new InventoryTransaction(skuId, warehouseId, type, quantity);
        transaction.setReferenceId(referenceId);
        transaction.setReferenceType(referenceType);
        transaction.setProcessedBy(getCurrentUserId());
        return transaction;
    }
    
    private void evictInventoryCache(String skuId, String warehouseId) {
        String cacheKey = skuId + ":" + warehouseId;
        redisTemplate.delete("inventory::" + cacheKey);
    }
    
    private void rollbackReservations(List<ReservationResult> results) {
        for (ReservationResult result : results) {
            if (result.isSuccess()) {
                releaseReservation(result.getReservationId());
            }
        }
    }
    
    private void rollbackAllocations(List<AllocationResult> results) {
        // 实现分配回滚逻辑
        // 这里需要根据具体业务需求实现
    }
    
    private InventoryAlert createLowStockAlert(InventoryItem inventory) {
        return new InventoryAlert(
            inventory.getSkuId(),
            inventory.getWarehouseId(),
            AlertType.LOW_STOCK,
            "库存不足，当前库存: " + inventory.getAvailableQuantity() + 
            ", 安全库存: " + inventory.getSafetyStock()
        );
    }
    
    private String getCurrentUserId() {
        // 从安全上下文获取当前用户ID
        return "system"; // 简化实现
    }
}