多端开发实战 | 会员积分抵现系统设计与实现：基于 Taro 的跨平台解决方案

/**
 * 用户个人资料组件
 * 
 * 该组件根据提供的用户ID获取并显示用户信息
 * 
 * @param {Object} props - 组件属性
 * @param {string} props.userId - 需要获取的用户ID
 * @returns {JSX.Element} 显示用户名的div元素
 */
function UserProfile({ userId }) {
  // 使用状态管理用户数据
  const [user, setUser] = useState(null);

  /**
   * 副作用钩子：根据userId变化获取用户数据
   * 
   * 包含组件卸载时的清理逻辑，防止在已卸载组件上设置状态
   */
  useEffect(() => {
    let isMounted = true;

    // 异步获取用户数据
    fetchUser(userId).then(data => {
      if (isMounted) setUser(data);
    });

    // 清理函数：组件卸载时设置挂载标志为false
    return () => {
      isMounted = false;
    };
  }, [userId]);

  // 渲染用户名（使用可选链操作符防止user为null时报错）
  return <div>{user?.name}</div>;
}

import Taro, { useState, useEffect } from '@tarojs/taro';
import { View, Input, Button } from '@tarojs/components';

/**
 * 积分抵扣组件
 * @param {Object} props - 组件属性
 * @param {Function} props.onDeduction - 积分抵扣回调函数，参数为抵扣金额（单位：元）
 * @returns {JSX.Element} 积分抵扣界面
 */
export default function PointsDeduction({ onDeduction }) {
  // 积分状态管理实例，初始化时传入用户ID
  const [pointsManager] = useState(() => new PointsStateManager('user123'));
  // 本地积分状态
  const [state, setState] = useState(pointsManager.localState);
  // 用户输入的积分数量
  const [inputPoints, setInputPoints] = useState(0);

  /**
   * 监听积分状态变化
   * 当pointsManager状态变化时更新本地状态
   */
  useEffect(() => {
    const handler = () => setState({ ...pointsManager.localState });
    pointsManager.onStateChange(handler);
    return () => pointsManager.offStateChange(handler);
  }, []);

  // 计算当前可用的最大积分（考虑余额和每日限额）
  const maxUsable = Math.min(
    state.pointsBalance,
    DAILY_LIMIT - state.todayUsed,
  );

  /**
   * 处理积分使用逻辑
   * 调用pointsManager扣除积分，并通过回调通知父组件抵扣金额
   */
  const handleUsePoints = () => {
    try {
      pointsManager.usePoints(inputPoints, '订单抵扣');
      onDeduction(inputPoints / 100); // 100积分=1元
    } catch (error) {
      Taro.showToast({ title: error.message, icon: 'none' });
    }
  };

  return (
    <View className='points-deduction'>
      <View>可用积分: {state.pointsBalance}</View>
      <View>
        今日可用: {DAILY_LIMIT - state.todayUsed}/{DAILY_LIMIT}
      </View>

      <Input
        type='number'
        value={inputPoints}
        onInput={e => setInputPoints(e.detail.value)}
        placeholder={`最多可使用${maxUsable}积分`}
      />

      <Button onClick={handleUsePoints}>使用积分</Button>
    </View>
  );
}

/**
 * 积分过期提醒服务类
 * 用于监控用户即将过期的积分并发送提醒
 */
class ExpirationNotifier {
  /**
   * 构造函数
   * @param {string} userId - 需要监控的用户ID
   */
  constructor(userId) {
    this.userId = userId;
    // 设置检查间隔为24小时（单位：毫秒）
    this.checkInterval = 24 * 60 * 60 * 1000;
  }

  /**
   * 开始监控积分过期状态
   * 立即执行一次检查，然后按固定间隔定期检查
   */
  startMonitoring() {
    this.checkExpiration();
    setInterval(() => this.checkExpiration(), this.checkInterval);
  }

  /**
   * 检查即将过期的积分
   * 获取用户即将过期的积分数据，筛选出15天内会过期的积分并提醒用户
   * @async
   */
  async checkExpiration() {
    // 获取用户即将过期的积分数据
    const expiringPoints = await api.getExpiringPoints(this.userId);
    
    // 筛选出15天内会过期但尚未过期的积分
    const criticalPoints = expiringPoints.filter(
      p => p.daysLeft <= 15 && p.daysLeft > 0,
    );

    // 如果有即将过期的积分，显示提醒弹窗
    if (criticalPoints.length > 0) {
      Taro.showModal({
        title: '积分即将过期',
        content: `您有${criticalPoints.length}笔积分将在15天内过期`,
        confirmText: '立即使用',
        cancelText: '我知道了',
      }).then(res => {
        // 如果用户点击确认，跳转到积分商城页面
        if (res.confirm) {
          Taro.navigateTo({ url: '/pages/points-mall/index' });
        }
      });
    }
  }
}

/**
 * 风控检查中间件
 * 用于检查用户积分变更操作的风险控制规则，包括单日上限和操作频率限制
 * 
 * @param {Object} change - 积分变更对象
 * @param {string} change.type - 变更类型，如'USE_POINTS'表示使用积分
 * @param {string} change.userId - 用户ID
 * @param {number} change.amount - 变更的积分数量
 * @returns {Promise<boolean>} - 返回true表示风控检查通过
 * @throws {Error} - 当检查不通过时抛出错误
 */
const riskCheckMiddleware = async change => {
  // 检查单日积分使用是否超过上限
  if (change.type === 'USE_POINTS') {
    const todayUsed = await getTodayUsed(change.userId);
    if (todayUsed + change.amount > DAILY_LIMIT) {
      throw new Error(`超过单日积分使用上限(${DAILY_LIMIT})`);
    }
  }

  // 检查最近1小时内的操作频率是否过高
  const lastHourChanges = await getRecentChanges(change.userId, '1h');
  if (lastHourChanges.length > MAX_HOURLY_CHANGES) {
    throw new Error('操作过于频繁');
  }

  return true;
};

/**
 * 审计日志记录器对象，用于记录积分系统的变更操作
 * 
 * @property {Function} log - 记录审计日志的异步方法
 *   @param {Object} change - 变更操作对象
 *     @property {string} userId - 操作用户ID
 *     @property {string} type - 操作类型
 *     @property {number} amount - 操作涉及的积分数量
 *   @param {Object} oldState - 变更前的状态
 *     @property {number} pointsBalance - 变更前的积分余额
 *   @param {Object} newState - 变更后的状态
 *     @property {number} pointsBalance - 变更后的积分余额
 *   @returns {Promise<void>} 无返回值
 */
const auditLogger = {
  async log(change, oldState, newState) {
    // 构建完整的审计日志条目，包含用户操作、状态变更和设备信息
    const logEntry = {
      userId: change.userId,
      action: change.type,
      amount: change.amount,
      before: oldState.pointsBalance,
      after: newState.pointsBalance,
      timestamp: new Date(),
      deviceInfo: getDeviceInfo(),
      ipLocation: await getIPLocation(),
    };

    // 持久化存储审计日志到数据库
    await db.collection('points_audit').insertOne(logEntry);

    // 向所有连接的客户端广播审计日志更新
    wsServer.broadcast('AUDIT_UPDATE', logEntry);
  },
};

// 多端样式适配示例
const styles = Taro.createStyle({
  container: {
    display: 'flex',
    padding: '10px',
    // 小程序需要特别处理
    /* @ifndef MP-WEIXIN */
    boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
    /* @endif */
    /* @ifdef MP-WEIXIN */
    boxShadow: '0 2px 4px #eee',
    /* @endif */
  }
});

/**
 * WebSocket统一封装类，提供跨平台的WebSocket实现
 * 根据运行环境自动选择小程序WebSocket或标准WebSocket实现
 */
class UnifiedWebSocket {
  /**
   * 构造函数，创建WebSocket连接
   * @param {string} url - WebSocket服务器地址
   */
  constructor(url) {
    this.url = url;
    
    // 根据Taro环境变量选择不同的WebSocket实现
    if (process.env.TARO_ENV === 'weapp') {
      this.impl = new MiniProgramSocket(url);
    } else {
      this.impl = new StandardWebSocket(url);
    }
  }

  /**
   * 发送消息到WebSocket服务器
   * @param {string|ArrayBuffer} message - 要发送的消息内容
   * @returns {void}
   */
  send(message) {
    return this.impl.send(message);
  }

  /**
   * 注册消息接收回调函数
   * @param {function} callback - 消息接收回调函数
   * @returns {void}
   */
  onMessage(callback) {
    this.impl.onMessage(callback);
  }

  /**
   * 重新连接WebSocket服务器
   * 针对小程序环境做了特殊处理：当应用在后台时不立即重连
   * @returns {void}
   */
  reconnect() {
    if (process.env.TARO_ENV === 'weapp') {
      // 小程序环境下需要检查应用状态
      if (this.appState === 'background') {
        this.scheduleReconnect();
      } else {
        this.impl.connect();
      }
    } else {
      // 非小程序环境直接重连
      this.impl.connect();
    }
  }
}

// 动态加载积分计算模块
const pointsCalculator = await import('@/modules/points-calculator');

// 使用Taro虚拟列表组件
<TaroVirtualList
  height={500}
  width='100%'
  itemData={couponList}
  itemCount={couponList.length}
  itemSize={100}
  renderItem={({ index, style }) => (
    <CouponItem data={couponList[index]} style={style} />
  )}
/>

// 使用lodash防抖
const updatePointsDisplay = debounce(() => {
  this.setState({ points: this.state.points });
}, 300);