新零售实战 | 新零售商品服务架构演进：从单品管理到全域协同的架构革命

class ProductPublisher {
  constructor() {
    // 校验器配置
    this.validators = [
      new BaseInfoValidator(),    // 基础属性校验
      new PriceValidator(),       // 价格策略校验
      new InventoryValidator()    // 库存模型校验
    ];
    
    // 流程管道配置
    this.pipelines = {
      default: [                  // 常规商品流程
        new InventorySync(),      // 库存服务同步
        new SearchIndex()         // 搜索索引更新
      ],
      presale: [                  // 预售商品流程
        new PresaleProcessor(),   // 预售规则处理
        new PaymentLink()         // 定金支付链接生成
      ]
    };
  }

  async publish(product, type = 'default') {
    // 参数说明：
    // product - 商品数据对象，结构示例：
    // {
    //   title: "商品标题",
    //   category: "类目ID",
    //   specs: [{name:"颜色",values:["红","蓝"]}],
    //   price: { base: 100, discount: 80 },
    //   inventory: { type: "virtual", total: 1000 }
    // }
    // type - 发布类型枚举值，支持 default/presale/flashsale
    
    // 阶段1：校验风暴
    for (const v of this.validators) {
      await v.validate(product); // 异步校验执行
    }

    // 阶段2：流程编排
    const pipeline = this.pipelines[type];
    let result = product;
    for (const processor of pipeline) {
      result = await processor.process(result); // 管道式处理
    }

    // 阶段3：持久化
    return Product.create(result); // 数据库写入
  }
}

class PresaleProcessor {
  async process(product) {
    return {
      ...product,
      presaleConfig: {
        start: product.presale.start,
        end: product.presale.end,
        deposit: this.calcDeposit(product.price)
      }
    };
  }

  calcDeposit(price) {
    return price.base * 0.2; // 定金比例20%
  }
}

class ComboProduct {
  constructor() {
    this.items = []; // 结构示例：[{product, quantity, optional}]
    this.rules = {}; // 扩展槽位，示例：{max_items:5, allow_duplicates:false}
  }

  /**
   * 添加子商品核心逻辑
   * @param {Object} product - 商品数据结构
   * @param {string} product.id - 商品唯一标识
   * @param {number} product.price - 商品单价
   * @param {Object} config - 组合配置
   * @param {number} [config.quantity=1] - 商品数量（支持小数，如0.5公斤）
   * @param {boolean} [config.optional=false] - 是否可选
   */
  addItem(product, config = {}) {
    // 防御性编程：空值检测
    if (!product?.id) throw new Error("无效商品对象");
    
    // 唯一性校验：深度比对
    const exists = this.items.some(item => 
      item.product.id === product.id && 
      item.quantity === (config.quantity || 1)
    );
    if (exists) throw new Error(`商品${product.id}已存在相同配置`);

    // 智能默认值处理
    const mergedConfig = {
      quantity: config.quantity >= 0 ? config.quantity : 1,
      optional: !!config.optional
    };

    // 异步埋点示例
    analytics.track('combo_item_added', {
      productId: product.id,
      quantity: mergedConfig.quantity
    });

    this.items.push({ product, ...mergedConfig });
  }

  /**
   * 组合完整性校验（可扩展设计）
   * @throws 校验失败时抛出带错误码的异常
   */
  validate() {
    // 必选商品校验（支持多层级校验）
    const requiredItems = this.items
      .filter(item => !item.optional)
      .filter(item => this._checkStock(item)); // 库存预校验

    if (requiredItems.length < 1) {
      throw new ComboError('REQUIRED_ITEM_MISSING', '至少需要选择一个必选商品');
    }

    // 价格合理性校验（动态计算基准价）
    const basePrice = this.items.reduce((sum, item) => 
      sum + (item.product.basePrice || item.product.price) * item.quantity, 0);
    
    const minAllowedPrice = basePrice * this.rules.minDiscountRate || 0.8;
    if (this.price < minAllowedPrice) {
      throw new ComboError('PRICE_ABNORMAL', 
        `套餐价格不得低于基准价${minAllowedPrice.toFixed(2)}元`);
    }

    // 扩展校验示例：组合商品嵌套检测
    if (this.items.some(item => item.product instanceof ComboProduct)) {
      if (!this.rules.allow_nested) {
        throw new ComboError('NESTED_COMBO', '当前配置不支持嵌套组合商品');
      }
    }
  }

  // 库存预校验私有方法
  _checkStock(item) {
    return item.product.stock >= item.quantity * this.presetCount;
  }
}

// 自定义错误类型
class ComboError extends Error {
  constructor(code, message) {
    super(message);
    this.code = code;
  }
}

const validationLayers = [
  { name: '基础校验', handler: validateBasic }, // 必填项检查等
  { name: '业务规则', handler: validateBusiness }, // 价格/库存规则
  { name: '风控规则', handler: validateRisk }, // 防刷单/合规性
  { name: '扩展规则', handler: validateExtensions } // 第三方插件
];

async function fullValidate() {
  for (const layer of validationLayers) {
    await layer.handler();
  }
}

/**
 * 预售库存预占服务类
 * 提供基于Redis的原子化库存预占操作，并记录预占订单信息
 */
class PresaleInventory {
  /**
   * 执行商品库存预占操作
   * @param {string} productId - 需要预占的商品唯一标识符
   * @param {number} quantity - 需要预占的库存数量
   * @returns {Promise<void>} 无返回值，预占成功时resolve，失败时reject携带Error对象
   * @throws {Error} 当库存不足时抛出包含错误信息的异常
   */
  async reserve(productId, quantity) {
    // 生成Redis存储的库存键名
    const key = `presale:${productId}`;
    
    // 获取当前库存总量（注意：此处为演示代码，实际应考虑使用原子化操作同时获取库存）
    const total = await redis.get(key);

    // 前置库存检查：验证可用库存是否满足请求量
    if (total - quantity < 0) {
      throw new Error('库存不足');
    }

    // 原子化库存扣减操作
    // 使用Redis的DECRBY命令保证在高并发场景下的原子性操作
    const result = await redis.decrby(key, quantity);
    
    // 后置库存校验：处理可能出现的负库存情况
    if (result < 0) {
      // 库存不足时执行回滚操作：恢复被扣除的库存量
      await redis.incrby(key, quantity);
      throw new Error('库存不足');
    }

    // 创建预占订单记录
    // 将预占信息持久化到数据库，状态标记为"已预占"
    await PresaleOrder.create({
      productId,
      quantity,
      status: 'reserved',
    });
  }
}

class PresaleInventory {
  async reserve(productId, quantity) {
    const key = `presale:${productId}`; // Redis键设计规范
    
    // 第一重校验：快速失败
    const total = await redis.get(key);
    if (total - quantity < 0) throw new Error('库存不足');

    // 原子操作核心段
    const result = await redis.decrby(key, quantity);
    
    // 第二重校验：确保数据一致性
    if (result < 0) {
      await redis.incrby(key, quantity); // 数据回滚
      throw new Error('库存不足');
    }

    // 预占记录（异步持久化）
    await PresaleOrder.create({
      productId,
      quantity,
      status: 'reserved',
      expireAt: Date.now() + 300000 // 5分钟有效期
    });
  }
}

/**
 * 请求频率限制器类，用于限制单个用户的请求频率
 * 
 * 实现机制：
 * - 使用Map结构存储用户计数器
 * - 自动清理过期计数器
 */
class RequestLimiter {
  constructor() {
    // 存储用户ID与其对应请求计数器的映射关系
    this.counters = new Map();
  }

  /**
   * 检查用户请求是否超过频率限制
   * @param {string} userId - 需要校验的用户唯一标识
   * @returns {boolean} - true表示允许请求，false表示触发限流
   * 
   * 实现逻辑：
   * - 获取用户当前计数器值
   * - 校验是否超过5次/秒的限制
   * - 更新计数器并设置定时清理
   */
  check(userId) {
    const key = `limit:${userId}`;
    const current = this.counters.get(key) || 0;
    if (current >= 5) return false;

    // 更新计数器并设置1秒后自动清除的定时器
    // 该设计实现滑动时间窗口效果
    this.counters.set(key, current + 1);
    setTimeout(() => this.counters.delete(key), 1000);
    return true;
  }
}

class InventorySyncer {
  constructor() {
    // 渠道适配器配置（可扩展设计）
    this.channels = {
      warehouse: new WarehouseAdapter(),    // 仓库WMS系统适配器
      store: new StorePOSAdapter(),         // 门店POS系统适配器
      thirdParty: new TPLAdapter()          // 第三方物流系统适配器
    };
  }

  /**
   * 执行库存同步操作
   * @param {string} sku - 商品SKU编码 
   * @param {number} delta - 库存变化量（+增加/-减少）
   * @returns {Promise<Array>} 各渠道同步结果
   */
  async sync(sku, delta) {
    // 并行执行所有渠道同步
    const promises = Object.values(this.channels).map(adapter => 
      adapter.updateInventory(sku, delta)
        .catch(e => { // 单渠道错误隔离
          console.error(`[${adapter.constructor.name}] 同步失败`, e);
          return { status: 'failed', reason: e.message };
        })
    );

    // 等待所有渠道完成（不中断其他渠道）
    return Promise.allSettled(promises);
  }
}

class Replenishment {
  /**
   * 计算补货建议量
   * @param {Object} params - 输入参数对象
   * @param {Array<number>} params.salesTrend - 历史销售趋势数据（用于时间序列预测）
   * @param {number} params.leadTime - 供应商交货周期（单位：天）
   * @param {number} params.safetyStock - 安全库存阈值（最低库存保障）
   * @param {number} params.currentStock - 当前实际库存量
   * @returns {number} 建议补货量（需同时满足常规需求和安全库存需求的最大值）
   */
  calculate(params) {
    // 参数解析：
    // salesTrend - 销售趋势数据
    // leadTime - 供应商交货周期
    // safetyStock - 安全库存阈值

    // 使用ARIMA模型预测未来销售量（基于销售趋势数据）
    const forecast = this.arimaModel.predict(params.salesTrend);
    
    // 计算调整后的需求（考虑供应商交货周期：将周转换为天比例）
    const demand = forecast * (1 + params.leadTime / 7);

    // 返回最大补货需求（常规补货需求 vs 安全库存补货需求）
    return Math.max(demand - params.currentStock, params.safetyStock - params.currentStock);
  }
}

/**
 * 库存防护系统
 * 管理商品库存保留策略和用户限购策略
 * 配置说明:
 * - total: 总库存保留比例（默认30%）
 * - perUser: 单人最大购买数量（默认5件）
 */
class InventoryGuard {
  constructor() {
    this.thresholds = {
      total: 0.3, // 总库存保留30%
      perUser: 5, // 单人最大购买量
    };
  }

  /**
   * 执行库存检查
   * @param {Object} product - 商品对象，需包含 totalStock（总库存）和 availableStock（可用库存）属性
   * @param {Object} user - 用户对象，用于获取购买记录
   * @returns {boolean} 检查通过返回 true
   * @throws {Error} 当库存不足或超过限购数量时抛出错误
   */
  check(product, user) {
    // 计算需要保留的基础库存量（总库存的30%）
    const reserved = product.totalStock * this.thresholds.total;
    
    // 核心库存检查：可用库存必须至少保留总库存的30%
    if (product.availableStock < reserved) {
      throw new Error('库存不足');
    }

    // 获取用户历史购买数量并检查限购
    const userBought = this.getUserPurchases(user);
    if (userBought >= this.thresholds.perUser) {
      throw new Error('超过限购数量');
    }

    return true;
  }
}