puzzleweave/lib/play/board_play.dart

import 'dart:async';
import 'dart:io';
import 'dart:math';
import 'dart:ui' as ui;

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:fluttertoast/fluttertoast.dart';
import 'package:logging/logging.dart';
import 'package:provider/provider.dart';
import 'package:puzzleweave/audio/jc_audio_controller.dart';
import 'package:puzzleweave/config/device.dart';
import 'package:puzzleweave/l10n/app_localizations.dart';
import 'package:puzzleweave/models/data.dart';
import 'package:puzzleweave/models/download.dart';
import 'package:puzzleweave/models/items.dart';
import 'package:puzzleweave/play/board.dart';
import 'package:puzzleweave/play/board_painter.dart';
import 'package:puzzleweave/play/confetti_layer.dart';
import 'package:puzzleweave/play/overlayer.dart';
import 'package:puzzleweave/play/piece.dart';
import 'package:puzzleweave/rating/rating_helper.dart';
import 'package:puzzleweave/rating/rating_utils.dart';
import 'package:puzzleweave/settings/settings_controller.dart';
import 'package:puzzleweave/settings/settings_dialog.dart';
import 'package:puzzleweave/skin/skin.dart';
import 'package:puzzleweave/utils/mybutton.dart';
import 'package:puzzleweave/utils/utils.dart';
import 'package:vector_math/vector_math.dart' as vmath;
import 'package:vibration/vibration.dart';

final Logger _log = Logger('board_play.dart');

// 移动类型 (不再需要，但保留枚举以防止其他文件引用报错)
enum MoveType {
  group, // 整个群组一起移动
  single, // 单个碎片移动
}

// 操作类型
enum Action {
  revert, // 回归
  swap, // 交换
}

class BoardPlay extends StatefulWidget {
  final ListItem item;
  final bool firstRun;

  const BoardPlay({super.key, required this.item, this.firstRun = false});

  @override
  State<StatefulWidget> createState() {
    return _BoardPlayState();
  }

  static PageRouteBuilder buildRoute(ListItem item, {bool firstRun = false}) {
    return PageRouteBuilder(
      pageBuilder: (context, animation, secondaryAnimation) {
        return BoardPlay(item: item, firstRun: firstRun);
      },
      transitionsBuilder: (context, animation, secondaryAnimation, child) {
        return FadeTransition(opacity: animation, child: child);
        // return SlideTransition(
        //   position: Tween(begin: const Offset(1, 0), end: Offset.zero).animate(animation),
        //   child: child,
        // );
      },
    );
  }
}

class _BoardPlayState extends State<BoardPlay> with TickerProviderStateMixin {
  final GlobalKey boardKey = GlobalKey();
  Board? board;
  bool _isLoading = true;
  int progress = 0;
  bool isDownloadSlow = false;
  late Timer timer;

  late ItemLoader itemLoader;

  // late AudioController audio;
  late JcAudioController audio;
  late Data data;
  late SettingsController settings;

  late ConfettiLayer confettiLayer;

  ui.Image? _fingerImage; // 手指形状图片，用于制作引导动画
  int _hintCount = 0; // 已经展示的手势指引次数
  OverLayer? _overLayer; // 用于展示手势指引的layer层，采用OverlayEntry方案，置于顶层
  Timer? _hintTimer;
  int? _lastInteractionTick;
  // final int maxHints = 3;
  final int maxHints = 99; // 无限提示

  Piece? _draggingPiece;

  // 记录所有动画中的移动项 (位移/交换/归位)
  List<MoveItem>? moveItems;

  // 动画控制器
  late AnimationController _moveAnimationController; // 移动动画（位移）

  late AnimationController _mergeAnimationController; // merge动画（scale）
  // merge 动画的缩放值
  late Animation<double> _mergeScaleAnimation;
  List<PieceGroup>? _mergeGroups; // 记录当前merge的group

  late AnimationController _prepareAnimationController; // 预备动画， Opacity透明动画展示核心绘制区

  late AnimationController dealingAnimationController; // 发牌动画
  late AnimationController flipAnimationController; // 翻牌动画

  // 发牌动画相关
  late Animation<double> _dealingAnimation;
  // 发牌动画参数
  // 发牌间隔（ms）
  int get _dealingPieceInterval {
    if (board!.rows <= 3) return 120;
    if (board!.rows == 4) return 100;
    if (board!.rows == 5) return 80;
    if (board!.rows == 6) return 60;
    return 50;
  }

  // 每个卡片移动时间（ms）
  int get _dealingPieceDuration {
    if (board!.rows <= 3) return 500;
    if (board!.rows == 4) return 400;
    if (board!.rows == 5) return 300;
    if (board!.rows == 6) return 200;
    return 100;
  }

  // 发牌动画总时长
  int get _totalDealingDuration => (board!.pieces.length - 1) * _dealingPieceInterval + _dealingPieceDuration; // 发牌动画总时长（ms）

  Timer? _dealingPeriodicTimer;
  int _dealingCount = 0; // 计数：记录执行次数

  // 成功动画控制器
  late AnimationController _successAnimationController;
  late Animation<double> _offsetAnimation; // 用于控制核心绘制区上移
  late Animation<double> _bottomSlideAnimation; // 用于控制next按钮从屏幕下方移动上来
  late Animation<double> _topSlideAnimation; // 用于控制通关banner从屏幕上方移动上来

  // Hard Mode Banner 动画控制器
  late AnimationController _hardModeBannerController;
  // 缩放动画
  late Animation<double> _bannerScaleAnimation;
  // 透明度动画
  late Animation<double> _bannerFadeAnimation;
  // 是否显示 Hard Mode Banner 的标志
  bool _showHardModeBanner = false;

  @override
  initState() {
    super.initState();

    itemLoader = ItemLoader.load(widget.item);
    _onProgressUpdate();
    itemLoader.progress.addListener(_onProgressUpdate);
    timer = Timer(const Duration(seconds: 5), () {
      if (mounted && progress < 50) {
        if (progress <= 1) {
          //啥都没下载到, 直接弹toast然后退出
          Fluttertoast.showToast(
            msg: AppLocalizations.of(context)!.networkNotGood,
            toastLength: Toast.LENGTH_SHORT,
            gravity: ToastGravity.CENTER,
            timeInSecForIosWeb: 1,
            backgroundColor: SkinHelper.slotBorderColor,
            textColor: Colors.white,
            fontSize: 16.0,
          );
          Navigator.pop(context);
        } else {
          // 有下载只是慢
          setState(() {
            isDownloadSlow = true;
          });
        }
      }
    });

    Device device = context.read<Device>();

    // audio = context.read<AudioController>();
    audio = context.read<JcAudioController>();
    data = context.read<Data>();
    settings = context.read<SettingsController>();

    confettiLayer = ConfettiLayer(this);

    Future.delayed(Duration.zero, () {
      if (mounted) {
        confettiLayer.setup(context);
      }
    });

    // 初始化移动动画，在dragging结束松手后的swap或evert操作都需要用到移动
    _moveAnimationController = AnimationController(vsync: this, duration: const Duration(milliseconds: 200));
    _moveAnimationController.addListener(_moveAnimationListener);
    _moveAnimationController.addStatusListener(_moveAnimationStatusListener);

    // 初始化 Merge 动画
    _mergeAnimationController = AnimationController(vsync: this, duration: const Duration(milliseconds: 300)); // 0.4s for scale up/down
    _mergeAnimationController.addListener(_mergeAnimationListener);
    _mergeAnimationController.addStatusListener(_mergeAnimationStatusListener);
    // 缩放值从 1.0 -> 1.1 -> 1.0 (使用 TweenSequence 实现放大再缩小)
    _mergeScaleAnimation =
        TweenSequence<double>([
          TweenSequenceItem(tween: Tween<double>(begin: 1.0, end: 1.06), weight: 50),
          TweenSequenceItem(tween: Tween<double>(begin: 1.06, end: 1.0), weight: 50),
        ]).animate(
          // 应用曲线：用 CurvedAnimation 包装控制器
          CurvedAnimation(
            parent: _mergeAnimationController, // 动画控制器
            curve: Curves.easeInOut, // 曲线类型（先加速后减速）
          ),
        );

    _prepareAnimationController = AnimationController(vsync: this, duration: const Duration(milliseconds: 800));
    _prepareAnimationController.addListener(_prepareAnimationListener);
    _prepareAnimationController.addStatusListener(_prepareAnimationStatusListener);

    // 初始化发牌动画
    dealingAnimationController = AnimationController(vsync: this);
    _dealingAnimation = CurvedAnimation(parent: dealingAnimationController, curve: Curves.linear);
    dealingAnimationController.addListener(_dealingAnimationListener);
    dealingAnimationController.addStatusListener(_dealingAnimationStatusListener);

    // 初始化翻转动画
    flipAnimationController = AnimationController(vsync: this, duration: Duration(milliseconds: 500));
    flipAnimationController.addListener(_flipAnimationListener);
    flipAnimationController.addStatusListener(_flipAnimationStatusListener);

    // 初始化成功动画
    _successAnimationController = AnimationController(vsync: this, duration: Duration(milliseconds: 500));
    final deltaY = (device.targetRect.top - device.appBarHeight) / 3;
    _offsetAnimation = Tween<double>(begin: 0.0, end: -deltaY).animate(_successAnimationController);
    _bottomSlideAnimation =
        Tween<double>(
          begin: -500, // 初始在屏幕外
          end: device.screenSize.height - device.targetRect.bottom + deltaY - 60,
        ).animate(
          CurvedAnimation(
            parent: _successAnimationController,
            curve: Curves.easeOut, // 缓出曲线，滑入更自然
          ),
        );
    _topSlideAnimation =
        Tween<double>(
          begin: -200, // 初始在屏幕外
          end: device.targetRect.top - deltaY - 70,
        ).animate(
          CurvedAnimation(
            parent: _successAnimationController,
            curve: Curves.easeOut, // 缓出曲线，滑入更自然
          ),
        );
    _successAnimationController.addListener(_successAnimationListener);
    _successAnimationController.addStatusListener(_successAnimationStatusListener);

    // 初始化 Hard Mode Banner 动画
    _hardModeBannerController = AnimationController(vsync: this, duration: const Duration(milliseconds: 1500));
    // 缩放：0.0 -> 1.0 (前 40% 时间快速放大)
    _bannerScaleAnimation = Tween<double>(begin: 0.0, end: 1.0).animate(
      CurvedAnimation(
        parent: _hardModeBannerController,
        curve: const Interval(0.0, 0.4, curve: Curves.easeOut),
      ),
    );
    // 透明度：1.0 -> 0.0 (后 70% 时间逐渐淡出)
    _bannerFadeAnimation = Tween<double>(begin: 1.0, end: 0.0).animate(
      CurvedAnimation(
        parent: _hardModeBannerController,
        curve: const Interval(0.3, 1.0, curve: Curves.easeIn),
      ),
    );
    // 监听器用于触发重绘
    _hardModeBannerController.addListener(() {
      // if (mounted) setState(() {}); // 效率较低，改用AnimatedBuilder来实现局部重绘
    });
    // 动画完成时，设置标志为 false，完全隐藏
    _hardModeBannerController.addStatusListener((status) {
      if (status == AnimationStatus.completed) {
        if (mounted) setState(() => _showHardModeBanner = false);
      }
    });

    try {
      _init();
    } catch (error) {
      _log.info('board init error: $error');
      Fluttertoast.showToast(
        msg: AppLocalizations.of(context)!.networkNotGood,
        toastLength: Toast.LENGTH_SHORT,
        gravity: ToastGravity.CENTER,
        timeInSecForIosWeb: 1,
        backgroundColor: SkinHelper.slotBorderColor,
        textColor: Colors.white,
        fontSize: 16.0,
      );
      Navigator.pop(context);
    }
  }

  _onProgressUpdate() {
    // progress = (downloadItem.progress.value * 100).ceil();
    progress = (itemLoader.progress.value * 100).ceil();
    _log.info('onProgressUpdate: progress=$progress');
    setState(() {});
  }

  void _successAnimationListener() {
    final delta = _offsetAnimation.value;
    board!.finalRect = board!.targetRect.translate(0, delta);
    board!.invalidate();
  }

  void _successAnimationStatusListener(AnimationStatus status) async {
    if (status == AnimationStatus.completed) {
      // delay 一下，等待撒花基本消失
      Future.delayed(Duration(seconds: 1), () async {
        if (!mounted) return;
        // 关卡完成判断是否需要评分
        final bool shouldShowRateDialog = await RatingHelper.shouldShowRateDialog(data.currentLevel);
        if (shouldShowRateDialog) {
          if (mounted) {
            showRateDialog(context);
          }
        }
      });
    }
  }

  void _dealingAnimationListener() {
    if (board == null) return;

    // 当前动画已运行的时间（ms）
    final currentTime = _dealingAnimation.value * _totalDealingDuration;

    // 逐个更新卡片位置(最后一张不需要动)
    for (int i = 0; i < board!.pieces.length - 1; i++) {
      final piece = board!.pieces[i];
      final startTime = i * _dealingPieceInterval;
      final duration = _dealingPieceDuration;

      // 尚未到启动时间：保持在起点
      if (currentTime < startTime) {
        continue;
      }

      // 计算移动进度（0~1）：已移动时间 / 总持续时间
      double progress = (currentTime - startTime) / duration;
      progress = progress.clamp(0.0, 1.0); // 限制进度不超过1（防止超调）

      // 计算当前位置（起点到终点的插值）
      final startTransform = board!.getBottomRightTransform();
      final endTransform = board!.getTransformByCoordinate(piece.curRow, piece.curCol);
      final tween = Matrix4Tween(begin: startTransform, end: endTransform);
      piece.transform = tween.lerp(progress);
    }

    board!.invalidate();
  }

  // 发牌动画状态监听器
  void _dealingAnimationStatusListener(AnimationStatus status) {
    if (status == AnimationStatus.completed) {
      board!.resetAllPieces();

      board!.shuffle(ShuffleStep.flipping);
      flipAnimationController.forward(from: 0.0);
      audio.playSfx(SfxType.flip);
    }
  }

  // 翻转动画监听器
  void _flipAnimationListener() {
    if (board == null) return;

    final flipValue = flipAnimationController.value;
    for (final piece in board!.pieces) {
      // 1. 计算翻转角度（0→π，180度翻转）
      final angle = flipValue * pi;

      // 2. 获取卡片的固定目标位置（基于curRow/curCol，不依赖动态transform）
      final targetTranslate = board!.getTransformByCoordinate(piece.curRow, piece.curCol);

      // 3. 执行翻转动画（传入固定目标位置）
      piece.updateFlipTransform(angle, targetTranslate);
    }

    board!.invalidate();
  }

  // 翻转动画状态监听器
  void _flipAnimationStatusListener(AnimationStatus status) {
    if (status == AnimationStatus.completed) {
      // 翻转完成，开始游戏
      board!.resetAllPieces();
      board!.rebuildAllGroups();

      // 检查是否初始化就已经merge的group
      final mergeGroups = board!.compareAllGroups();

      // 有新的区块合成，执行 merge 动画，稍稍放大然后再复原
      if (mergeGroups.isNotEmpty) {
        _log.info('Merge animation start for ${mergeGroups.length} groups.');

        // 启动 Merge 动画
        _mergeGroups = mergeGroups;
        _mergeAnimationController.forward(from: 0.0);
        audio.playSfx(SfxType.pop);
      }

      board!.start();
    }
  }

  // 关键修正：动画监听器，只注册一次
  void _moveAnimationListener() {
    if (moveItems == null || moveItems!.isEmpty) {
      return;
    }

    for (var item in moveItems!) {
      item.move();
    }

    board!.invalidate();
  }

  void _moveAnimationStatusListener(AnimationStatus status) {
    if (status == AnimationStatus.completed) {
      // 动画完成，确保所有 piece 都在它们的最终位置（endTransform）
      if (moveItems != null) {
        bool needRebuildGroup = moveItems!.any((item) => item.action == Action.swap);

        // 确保所有 piece 的 transform 最终停留在 endTransform
        for (var item in moveItems!) {
          item.stop();
        }

        if (needRebuildGroup) {
          board!.backupAllGroups();
          board!.rebuildAllGroups();
          final mergeGroups = board!.compareAllGroups();

          // 有新的区块合成，执行 merge 动画，稍稍放大然后再复原
          if (mergeGroups.isNotEmpty) {
            _log.info('Merge animation start for ${mergeGroups.length} groups.');

            // 启动 Merge 动画
            _mergeGroups = mergeGroups;
            _mergeAnimationController.forward(from: 0.0);
            audio.playSfx(SfxType.pop);

            // 如果执行了 merge 动画，将胜利条件检查推迟到 merge 动画完成时
            moveItems = null;
            return;
          }
        }

        moveItems = null;
      }
    }
  }

  // 新增：Merge 动画监听器
  void _mergeAnimationListener() {
    if (_mergeGroups == null || _mergeGroups!.isEmpty || board == null) {
      return;
    }

    // 当前缩放值 (从 1.0 -> 1.1 -> 1.0)
    final double scale = _mergeScaleAnimation.value;

    for (var group in _mergeGroups!) {
      final groupCenter = group.center;
      for (var piece in group.pieces) {
        // 1. 获取碎片归位后的基础位置(纯平移)
        final baseTransform = board!.getTransformByCoordinate(piece.curRow, piece.curCol);

        // 2. 计算碎片左上角到群组中心的偏移量
        final pieceTopLeft = Offset(baseTransform.storage[12], baseTransform.storage[13]);
        final offsetToCenter = groupCenter - pieceTopLeft;

        // 3. 创建围绕群组中心的缩放矩阵
        final scaleMatrix = vmath.Matrix4.identity()
          ..translate(offsetToCenter.dx, offsetToCenter.dy) // 移到群组中心
          ..scale(scale, scale, 1.0) // 缩放
          ..translate(-offsetToCenter.dx, -offsetToCenter.dy); // 移回原位

        // 4. 应用最终变换
        piece.transform = baseTransform * scaleMatrix;
      }
    }

    board!.invalidate();
  }

  // 新增：Merge 动画状态监听器
  void _mergeAnimationStatusListener(AnimationStatus status) {
    if (status == AnimationStatus.completed) {
      if (_mergeGroups != null && _mergeGroups!.isNotEmpty) {
        for (var group in _mergeGroups!) {
          for (var piece in group.pieces) {
            piece.transform = board!.getTransformByCoordinate(piece.curRow, piece.curCol);
          }
        }
      }

      _mergeGroups = null;

      // 检查胜利条件
      if (board!.checkWinCondition()) {
        _onSuccess();
      }

      board!.invalidate();
    }
  }

  void _prepareAnimationListener() {
    board!.invalidate();
  }

  // prepare动画结束，进入洗牌动画
  void _prepareAnimationStatusListener(AnimationStatus status) {
    if (status == AnimationStatus.completed) {
      if (board != null && board!.hard == true) {
        setState(() => _showHardModeBanner = true);
        _hardModeBannerController.forward(from: 0.0);
      }

      board!.setAllPieceToBottomRight();
      board!.shuffle(ShuffleStep.dealing);
      dealingAnimationController.duration = Duration(milliseconds: _totalDealingDuration);
      dealingAnimationController.forward(from: 0.0);
      audio.playSfx(SfxType.card);
      _dealingPeriodicTimer = Timer.periodic(Duration(milliseconds: 150), (timer) {
        if (mounted) {
          _dealingCount++;
          if (_dealingCount >= (_totalDealingDuration / 150) - 2) {
            timer.cancel();
          } else {
            audio.playSfx(SfxType.card);
          }
        }
      });
    }
  }

  _onSuccess() {
    _log.info('success! 游戏完成！');
    data.workDone(widget.item);

    board!.success();
    audio.playSfx(SfxType.success);
    confettiLayer.play();

    _successAnimationController.forward(from: 0.0);

    setState(() {});
  }

  _init() async {
    Device device = context.read<Device>();

    setState(() {
      _isLoading = true;
    });

    final dpr = device.devicePixelRatio;
    final targetRect = device.targetRect;
    final bestImageSize = device.bestImageSize;

    final image = await itemLoader.getImageBySize(bestImageSize.width.round(), bestImageSize.height.round());
    // final image = await itemLoader.getImage();
    _log.info('imageSize: (${image.width},${image.height}), bestImageSize: ($bestImageSize)');

    // 加载图片，后续改为从远程服务器加载， 目前demo从本地assets读取
    // final ByteData data = await rootBundle.load('assets/images/test.jpeg');
    // final ByteData data = await rootBundle.load(widget.item.image);
    // final ui.Codec codec = await ui.instantiateImageCodec(
    //   data.buffer.asUint8List(),
    //   targetWidth: bestImageSize.width.round(),
    //   targetHeight: bestImageSize.height.round(),
    // );
    // final ui.FrameInfo frameInfo = await codec.getNextFrame();
    // final image = frameInfo.image;

    // 加载扑克背面图片，用于制作发牌动画
    final Size bestCardImageSize = Size(targetRect.width * dpr / widget.item.rows, targetRect.height * dpr / widget.item.cols);
    final ByteData cardData = await rootBundle.load(widget.item.hard ? 'assets/images/backcard_red.png' : 'assets/images/backcard_blue.png');
    final ui.Codec cardCodec = await ui.instantiateImageCodec(
      cardData.buffer.asUint8List(),
      targetWidth: bestCardImageSize.width.round(),
      targetHeight: bestCardImageSize.height.round(),
    );
    final ui.FrameInfo cardFrameInfo = await cardCodec.getNextFrame();
    final cardImage = cardFrameInfo.image;

    board = Board(this, image, cardImage, widget.item.rows, widget.item.cols, widget.item.hard, targetRect, device);
    board!.prepare();

    // 首次打开应用，需要新手指引
    _loadFingerImageAndSetupHint();

    // **修正：在调用 AnimationController 之前检查 `mounted` 状态**
    if (!mounted) return;

    _prepareAnimationController.forward(from: 0.0);

    setState(() {
      _isLoading = false;
    });
  }

  // board_play.dart (在 _BoardPlayState 中新增)

  // !!! 新增：加载手势图片并设置 Overlay
  Future<void> _loadFingerImageAndSetupHint() async {
    // 仅在首次运行时或用户需要提示时才加载图片和设置 OverLayer
    if (!widget.firstRun) return;

    try {
      // 假设您将 fingerImage 命名为 _fingerImage
      _fingerImage = await loadUiImageFromAsset('assets/images/finger.png');
    } catch (e) {
      _log.severe('Failed to load assets/images/finger.png: $e');
      return;
    }

    if (!mounted || board == null) return;

    // 初始化 OverLayer
    _overLayer = OverLayer(board!, this);
    _overLayer!.setup(context);

    // 首次打开应用或设置开启提示时，启动自动提示计时器
    if (widget.firstRun) {
      Future.delayed(const Duration(seconds: 1), () {
        _lastInteractionTick = DateTime.now().millisecondsSinceEpoch;

        // 每秒检查一次是否需要提示
        _hintTimer = Timer.periodic(const Duration(seconds: 1), (Timer t) {
          if (!mounted) return;
          int nowTick = DateTime.now().millisecondsSinceEpoch;
          if (_overLayer!.isHinting) {
            _lastInteractionTick = DateTime.now().millisecondsSinceEpoch;
          }
          // 超过3秒没动静，且提示次数未超限，则给提示
          if ((nowTick - _lastInteractionTick!) > 3 * 1000 && _hintCount < maxHints) {
            hint();
            _lastInteractionTick = nowTick; // 提示后重置计时
            _hintCount++;
          } else if (_hintCount >= maxHints) {
            // 提示次数达到上限，取消计时器
            _hintTimer?.cancel();
          }
        });
      });
    }
  }

  // board_play.dart (在 _BoardPlayState 中，修正 hint 方法)

  hint() async {
    // 使用私有字段 _fingerImage, _overLayer, _hintCount
    if (_fingerImage == null || _overLayer == null || board == null || board!.status != BoardStatus.playing) return;

    Piece? p1Ref; // 拖拽起点 piece 的参考 (单碎片或群组的 topLeftPiece)
    Piece? p2; // 合并目标 piece
    int bestSize = 0; // 记录找到的最佳群组大小

    // --- Step 1: 确定所有可移动的实体（单碎片和群组）及其大小 ---
    final List<Map<String, dynamic>> movableEntities = [];
    final Set<PieceGroup> seenGroups = {};

    for (final piece in board!.pieces) {
      if (piece.isOK) continue; // 已归位的碎片/群组不移动

      if (piece.group == null) {
        // 1. 单个碎片
        movableEntities.add({'ref': piece, 'size': 1});
      } else if (!seenGroups.contains(piece.group!)) {
        // 2. 群组：使用 topLeftPiece 作为群组的参考点
        movableEntities.add({'ref': piece.group!.topLeftPiece, 'size': piece.group!.length});
        seenGroups.add(piece.group!);
      }
    }

    // --- Step 2: 按实体大小降序排列，优先引导大群组 ---
    // b['size'].compareTo(a['size']) 实现降序排序
    movableEntities.sort((a, b) => b['size'].compareTo(a['size']));

    // --- Step 3: 搜索有效的合并机会 (Merge Opportunity) ---

    for (final entityMap in movableEntities) {
      final p1RefCandidate = entityMap['ref'] as Piece;
      final currentSize = entityMap['size'] as int;
      final movingEntity = p1RefCandidate.group ?? p1RefCandidate;
      final movingPieces = (movingEntity is PieceGroup) ? movingEntity.pieces : [p1RefCandidate];

      // 遍历移动实体内的所有碎片 p1，寻找一个可以与外部 p2 合并的边缘碎片
      for (final p1 in movingPieces) {
        // 遍历 p1 的原图邻居 p2
        for (final neighborIndex in p1.getNeighbourIndexes()) {
          final p2Candidate = board!.getPieceByIndex(neighborIndex);

          if (p2Candidate == null) continue;

          // p2Candidate 必须不是正在移动的实体的一部分
          if (p2Candidate.isSameGroup(p1)) continue;

          // 1. 检查 p1 和 p2Candidate 的相对位置是否正确 (满足合并的前提条件)
          final isRelativePositionCorrect =
              (p1.col == p2Candidate.col && (p1.row - p2Candidate.row) == (p1.curRow - p2Candidate.curRow)) ||
              (p1.row == p2Candidate.row && (p1.col - p2Candidate.col) == (p1.curCol - p2Candidate.curCol));

          // 2. 如果它们已经是邻居，则应已自动合并，跳过提示
          if (p1.isCurNeighbour(p2Candidate)) continue;

          if (isRelativePositionCorrect) {
            // --- Step 3.1: 模拟移动并进行碰撞/边界检查 (Validity Check) ---

            // 计算使 p1 与 p2Candidate 合并所需的位移量 (dMoveRow, dMoveCol)

            // a. p1 在原图上相对于 p2 的差值
            final int dRow = p1.row - p2Candidate.row;
            final int dCol = p1.col - p2Candidate.col;

            // b. p1 移动后的目标网格坐标
            final targetP1Row = p2Candidate.curRow + dRow;
            final targetP1Col = p2Candidate.curCol + dCol;

            // c. 整个实体所需的移动位移 (从 p1 的当前位置到目标位置的距离)
            final dMoveRow = targetP1Row - p1.curRow;
            final dMoveCol = targetP1Col - p1.curCol;

            // 检查整个实体 (movingPieces) 移动 (dMoveRow, dMoveCol) 是否可行
            bool canPlace = true;
            for (final movingPiece in movingPieces) {
              final newRow = movingPiece.curRow + dMoveRow;
              final newCol = movingPiece.curCol + dMoveCol;

              // i. 边界检查
              if (newRow < 0 || newRow >= board!.rows || newCol < 0 || newCol >= board!.cols) {
                canPlace = false;
                break;
              }

              // ii. 碰撞检查: 目标槽位不能被非本实体内的其他碎片占据
              final overlapPiece = board!.getPieceByCoordinate(newRow, newCol);

              // 碰撞条件：目标槽位被占据 且 占据者不属于正在移动的实体
              if (overlapPiece != null && !movingPieces.contains(overlapPiece)) {
                canPlace = false;
                break;
              }
            }

            if (canPlace) {
              p1Ref = p1RefCandidate; // 拖拽起点 (群组的参考 Piece)
              p2 = p2Candidate; // 合并目标 Piece
              bestSize = currentSize; // 记录大小
              break; // 找到有效的合并提示，跳出 p2 循环
            }
          }
        }
        if (p1Ref != null) break; // 找到有效的合并提示，跳出 p1 循环
      }
      if (p1Ref != null) break; // 找到有效的合并提示，跳出实体循环 (因为它涉及当前找到的最大群组)
    }

    // ----------------------------------------------------
    // --- Step 4: 执行引导动画 (Merge or Revert) ---
    // ----------------------------------------------------

    // 引导参数
    const double fingerSize = 30.0;
    HintItem? hintItem;

    if (p1Ref != null && p2 != null) {
      // 找到了有效的合并提示 (优先选择的合并操作)

      // a. 拖拽起点中心点: p1Ref 的群组中心或自身中心
      final p1Center = p1Ref!.group?.center ?? p1Ref!.currentCenter;

      // b. 拖拽终点中心点: p1Ref 移动后的目标槽位中心

      // 重新计算 p1Ref 应该移动到的目标网格坐标 (targetRefRow, targetRefCol)
      final movingEntity = p1Ref!.group ?? p1Ref;
      final movingPieces = (movingEntity is PieceGroup) ? movingEntity.pieces : [p1Ref!];

      // 寻找群组中能与 p2 合并的那个边缘碎片 p1
      final p1 = movingPieces.firstWhere(
        (p) =>
            p.isNeighbour(p2!) &&
            ((p.col == p2!.col && (p.row - p2!.row) == (p.curRow - p2!.curRow)) || (p.row == p2!.row && (p.col - p2!.col) == (p.curCol - p2!.curCol))),
      );

      final int dRow = p1.row - p2!.row;
      final int dCol = p1.col - p2!.col;
      final targetP1Row = p2!.curRow + dRow;
      final targetP1Col = p2!.curCol + dCol;

      final dMoveRow = targetP1Row - p1.curRow;
      final dMoveCol = targetP1Col - p1.curCol;

      // 最终目标网格坐标是 p1Ref 的当前坐标加上总位移
      final targetRefRow = p1Ref!.curRow + dMoveRow;
      final targetRefCol = p1Ref!.curCol + dMoveCol;

      // 获取目标槽位的中心点
      final targetTransform = board!.getTransformByCoordinate(targetRefRow, targetRefCol);
      final targetCenter = Offset(targetTransform.storage[12] + board!.pieceLogicalWidth / 2, targetTransform.storage[13] + board!.pieceLogicalHeight / 2);

      // 引导：从当前位置拖拽到目标位置
      final rectStart = Rect.fromCenter(center: p1Center, width: fingerSize, height: fingerSize);
      final rectEnd = Rect.fromCenter(center: targetCenter, width: fingerSize, height: fingerSize);

      _log.info(
        'Hint: MERGE guidance for largest Entity (size: $bestSize) starting at ${p1Ref!.index} to grid ($targetRefRow, $targetRefCol). Merges with ${p2!.index}',
      );
      hintItem = HintItem(_fingerImage!, rectStart, rectEnd);
    } else {
      // 3. 找不到合并操作，回退到归位引导

      // 沿用之前的逻辑：找一个未归位的单碎片，提示归位。
      Piece? pRevert = board!.pieces.firstWhereOrNull((p) => !p.isOK && (p.group == null || p.group!.length == 1));

      if (pRevert != null) {
        final pRevertCenter = pRevert.group?.center ?? pRevert.currentCenter;

        // 归位目标位置 (正确网格槽位的中心点)
        final targetTransform = board!.getTransformByCoordinate(pRevert.row, pRevert.col);
        final targetCenter = Offset(targetTransform.storage[12] + board!.pieceLogicalWidth / 2, targetTransform.storage[13] + board!.pieceLogicalHeight / 2);

        // 如果当前中心点和目标中心点距离很近，不提示归位
        if ((pRevertCenter - targetCenter).distanceSquared < pow(fingerSize * 2, 2)) {
          _log.info('Hint: Revert target for Piece ${pRevert.index} too close. Skipping.');
          return;
        }

        // 引导：从当前位置拖拽到正确网格中心
        final rectStart = Rect.fromCenter(center: pRevertCenter, width: fingerSize, height: fingerSize);
        final rectEnd = Rect.fromCenter(center: targetCenter, width: fingerSize, height: fingerSize);

        _log.info('Hint: Revert guidance for Piece ${pRevert.index}');
        hintItem = HintItem(_fingerImage!, rectStart, rectEnd);
      }
    }

    // 4. 执行引导动画
    if (hintItem != null) {
      _overLayer?.doHint(hintItem);
      Fluttertoast.showToast(
        msg: AppLocalizations.of(context)!.moveToComplete,
        toastLength: Toast.LENGTH_SHORT,
        gravity: ToastGravity.BOTTOM,
        timeInSecForIosWeb: 1,
        backgroundColor: SkinHelper.slotBorderColor,
        textColor: Colors.white,
        fontSize: 16.0,
      );
    }
  }

  // 展现提示 (自动手势引导)
  hint2() async {
    _log.info('新手手势提示');

    // 使用私有字段 _fingerImage, _overLayer, _hintCount
    if (_fingerImage == null || _overLayer == null || board == null || board!.status != BoardStatus.playing) return;

    // 1. 尝试寻找一个可以触发合并 (merge) 的拖拽操作 (p1 拖向 p2 的邻居槽位)
    Piece? p1; // 拖拽起点 piece
    Piece? p2; // 拖拽目标 piece (p1 将拖到 p2 的邻居槽位，从而实现合并)

    // 遍历所有碎片，寻找可以作为拖拽起点 p1 的候选碎片：
    // 仅考虑未归位的、单个碎片或群组的边缘碎片。
    // 我们依然使用 (p.group == null || length == 1) 的逻辑来简化起点筛选，即只引导单个碎片。
    for (final piece in board!.pieces) {
      // 限制 p1 为未归位的单个碎片/群组 (修正后的 null/length == 1 检查)
      if (piece.isOK || (piece.group != null && piece.group!.length > 1)) {
        continue;
      }

      // 找到 piece 在原图上的所有邻居 (p2 的候选)
      for (final neighborIndex in piece.getNeighbourIndexes()) {
        final neighbor = board!.getPieceByIndex(neighborIndex);

        if (neighbor == null) continue;

        // 检查 p1 和 p2 是否满足合并的“原图条件”和“相对位置条件”
        // canMerge() 依赖 isNeighbour()，所以 p1 和 p2 必须是原图邻居。
        // 注意：canMerge() 也会检查 isCurNeighbour()。

        // 核心逻辑：如果满足 canMerge，说明当前已经合并或即将自动合并，不需要提示。
        // 我们需要找的是：原图相邻且相对位置正确，但 *当前不相邻* 的碎片。

        // p1 和 p2 必须是原图邻居
        if (!piece.isNeighbour(neighbor)) continue;

        // 检查 p1 和 p2 的相对位置是否正确（确保可以合并）
        final isRelativePositionCorrect =
            (piece.col == neighbor.col && (piece.row - neighbor.row) == (piece.curRow - neighbor.curRow)) ||
            (piece.row == neighbor.row && (piece.col - neighbor.col) == (piece.curCol - neighbor.curCol));

        // 检查它们当前是否相邻
        final isCurrentlyNeighbor = piece.isCurNeighbour(neighbor);

        // 提示条件：原图是邻居 AND 相对位置正确 AND 当前不相邻
        if (isRelativePositionCorrect && !isCurrentlyNeighbor) {
          p1 = piece;
          p2 = neighbor;
          break; // 找到第一个非相邻的合并机会即可
        }
      }
      if (p1 != null) break;
    }

    // 引导参数
    const double fingerSize = 30.0;
    HintItem? hintItem;

    if (p1 != null && p2 != null) {
      // 2. 执行“连接”引导 (p1 拖向 p2 所在的网格槽位，使其相邻)

      // a. 拖拽起点：p1 群组的当前中心点
      final p1Center = p1.group?.center ?? p1.currentCenter;

      // b. 拖拽终点：p1 拖动后应到达的网格槽位的中心点。
      // 这个目标槽位是 p2 当前所占网格槽位旁边的一个空槽位，该槽位应与 p1 在原图上的相对位置一致。

      // 确定 p1 应该移动到的目标网格坐标 (row, col)
      int targetRow = p2.curRow;
      int targetCol = p2.curCol;

      // 根据 p1 和 p2 在原图上的相对位置，计算 p1 移动后应占领的网格槽位
      // 目标网格坐标 = p2 的当前网格坐标 + (p1 的正确坐标 - p2 的正确坐标)
      // 假设 p1(R:1, C:2) 和 p2(R:1, C:3) 是原图邻居。
      // 相对位移: dR = 0, dC = -1.
      // 如果 p2 当前在 (curR: 5, curC: 5)， 那么 p1 应该移动到 (5, 5 + (-1)) = (5, 4)。

      final int dRow = p1.row - p2.row; // p1 相对于 p2 的行差值 (-1, 0, 1)
      final int dCol = p1.col - p2.col; // p1 相对于 p2 的列差值 (-1, 0, 1)

      targetRow = p2.curRow + dRow;
      targetCol = p2.curCol + dCol;

      // 检查目标网格是否溢出边界（理论上不需要，因为 p2 在板上，dRow/dCol 只有 +/-1 或 0）
      if (targetRow < 0 || targetRow >= board!.rows || targetCol < 0 || targetCol >= board!.cols) {
        // 目标网格无效，跳过本次提示
        _log.warning('Hint target coordinate ($targetRow, $targetCol) out of bounds. Skipping.');
        return;
      }

      // 获取目标槽位的变换矩阵 (左上角坐标)
      final targetTransform = board!.getTransformByCoordinate(targetRow, targetCol);
      final targetCenter = Offset(targetTransform.storage[12] + board!.pieceLogicalWidth / 2, targetTransform.storage[13] + board!.pieceLogicalHeight / 2);

      // 拖拽起点 Rect (中心在 p1Center)
      final rectStart = Rect.fromCenter(center: p1Center, width: fingerSize, height: fingerSize);
      // 拖拽终点 Rect (中心在 targetCenter)
      final rectEnd = Rect.fromCenter(center: targetCenter, width: fingerSize, height: fingerSize);

      _log.info('Hint: Merge guidance for Piece ${p1.index} to neighbour of Piece ${p2.index} at grid ($targetRow, $targetCol)');
      hintItem = HintItem(_fingerImage!, rectStart, rectEnd);
    } else {
      // 3. 找不到合并操作，尝试执行“归位”引导 (将未归位的 piece 拖向正确槽位)
      // 沿用之前的逻辑：找一个未归位的单碎片，提示归位。
      Piece? pRevert = board!.pieces.firstWhereOrNull((p) => !p.isOK && (p.group == null || p.group!.length == 1));

      if (pRevert != null) {
        final pRevertCenter = pRevert.group?.center ?? pRevert.currentCenter;

        // 归位目标位置 (正确网格槽位的中心点)
        final targetTransform = board!.getTransformByCoordinate(pRevert.row, pRevert.col);
        final targetCenter = Offset(targetTransform.storage[12] + board!.pieceLogicalWidth / 2, targetTransform.storage[13] + board!.pieceLogicalHeight / 2);

        // 如果当前中心点和目标中心点距离很近，不提示归位
        if ((pRevertCenter - targetCenter).distanceSquared < pow(fingerSize * 2, 2)) {
          _log.info('Hint: Revert target for Piece ${pRevert.index} too close. Skipping.');
          return;
        }

        // 引导：从当前位置拖拽到正确网格中心
        final rectStart = Rect.fromCenter(center: pRevertCenter, width: fingerSize, height: fingerSize);
        final rectEnd = Rect.fromCenter(center: targetCenter, width: fingerSize, height: fingerSize);

        _log.info('Hint: Revert guidance for Piece ${pRevert.index}');
        hintItem = HintItem(_fingerImage!, rectStart, rectEnd);
      }
    }

    // 4. 执行引导动画
    if (hintItem != null) {
      _overLayer?.doHint(hintItem);
    }
  }

  @override
  void didChangeDependencies() async {
    super.didChangeDependencies();
    _log.info("didChangeDependencies");
  }

  @override
  dispose() {
    timer.cancel();
    itemLoader.progress.removeListener(_onProgressUpdate);

    _moveAnimationController.removeListener(_moveAnimationListener);
    _moveAnimationController.removeStatusListener(_moveAnimationStatusListener);
    _moveAnimationController.dispose();

    _mergeAnimationController.removeListener(_mergeAnimationListener);
    _mergeAnimationController.removeStatusListener(_mergeAnimationStatusListener);
    _mergeAnimationController.dispose();

    _prepareAnimationController.removeListener(_prepareAnimationListener);
    _prepareAnimationController.removeStatusListener(_prepareAnimationStatusListener);
    _prepareAnimationController.dispose();

    dealingAnimationController.removeListener(_dealingAnimationListener);
    dealingAnimationController.removeStatusListener(_dealingAnimationStatusListener);
    dealingAnimationController.dispose();

    flipAnimationController.removeListener(_flipAnimationListener);
    flipAnimationController.removeStatusListener(_flipAnimationStatusListener);
    flipAnimationController.dispose();

    _successAnimationController.removeListener(_successAnimationListener);
    _successAnimationController.removeStatusListener(_successAnimationStatusListener);

    _hardModeBannerController.dispose();

    _dealingPeriodicTimer?.cancel();

    confettiLayer.dispose();

    board?.dispose();

    _overLayer?.destroy();

    super.dispose();
  }

  /// gallery页面加载的时候，可能广告模块还没有初始化完毕
  // Future<bool> _bannerReadyAndShouldShow() async {
  //   bool ready = await adSDKReady();
  //   return ready && shouldShowBannerAd(data.currentLevel);
  // }

  @override
  Widget build(BuildContext context) {
    Device device = context.read<Device>();

    return Scaffold(
      body: Stack(
        children: <Widget>[
          if (!_isLoading) Positioned.fill(child: _buildPuzzleCanvas(device.screenSize.width, device.screenSize.height)),
          if (board == null || board!.status != BoardStatus.success) Positioned(top: 0, left: 0, right: 0, child: appBar),
          // Positioned(top: 0, left: 0, right: 0, child: appBar),
          Positioned(
            bottom: 0,
            left: 0,
            right: 0,
            child: Container(),
            // child: SafeArea(
            //   child: SizedBox(
            //     // 始终预留一个固定的高度，防止布局跳变
            //     height: context.read<Device>().bannerHeight,
            //     width: double.infinity,
            //     child: FutureBuilder<bool>(
            //       future: _bannerReadyAndShouldShow(),
            //       builder: (context, snapshot) {
            //         if (snapshot.hasData && snapshot.data == true) {
            //           return adBanner;
            //         }
            //         return Container(
            //           // color: Colors.grey.shade100,
            //         );
            //       },
            //     ),
            //   ),
            // ),
          ),
          successBanner,
          nextButton,
          if (_isLoading)
            Positioned.fill(
              child: Container(
                color: SkinHelper.wholeBgColor,
                child: const Center(child: CircularProgressIndicator(valueColor: AlwaysStoppedAnimation<Color>(Colors.white))),
              ),
            ),
        ],
      ),
    );
  }

  Widget get appBar => SafeArea(
    child: Padding(
      padding: const EdgeInsets.symmetric(horizontal: 30.0, vertical: 10.0),
      child: Row(
        mainAxisAlignment: MainAxisAlignment.spaceBetween,
        crossAxisAlignment: CrossAxisAlignment.center,
        children: [
          // 左侧占位（保持标题居中）
          const SizedBox(width: 30),
          // 中间标题
          Text(
            board != null && board!.status == BoardStatus.success
                ? AppLocalizations.of(context)!.levelPass
                : '${AppLocalizations.of(context)!.level} ${data.currentLevel + 1}',
            style: const TextStyle(color: Colors.white, fontSize: 20, fontWeight: FontWeight.w600),
          ),
          // 右侧设置按钮（30x30 圆形、深绿色背景、白色图标）
          SizedBox(
            width: 30,
            height: 30,
            child: IconButton(
              icon: const Icon(Icons.settings, color: Colors.white, size: 22),
              iconSize: 22,
              padding: EdgeInsets.zero, // 清除默认内边距，确保按钮尺寸准确
              onPressed: () {
                audio.playSfx(SfxType.click);
                Navigator.push(context, SettingsDialog.buildRoute(showReturn: true, showRestart: true, item: widget.item));
              },
              style: ButtonStyle(
                // 深绿色背景（与你之前的按钮风格一致，使用 Color(0xff26600c) 深绿色）
                backgroundColor: WidgetStateProperty.all(SkinHelper.slotBorderColor),
                // 圆形形状
                shape: WidgetStateProperty.all(
                  RoundedRectangleBorder(
                    borderRadius: BorderRadius.circular(15), // 30x30 按钮对应 15 圆角
                  ),
                ),
                // 固定按钮尺寸（30x30）
                minimumSize: WidgetStateProperty.all(const Size(30, 30)),
                maximumSize: WidgetStateProperty.all(const Size(30, 30)),
              ),
            ),
          ),
        ],
      ),
    ),
  );

  Widget _buildPuzzleCanvas(double width, double height) {
    return RepaintBoundary(
      child: CustomPaint(
        painter: BoardPainter(board: board!, prepareAnimation: _prepareAnimationController),
        size: Size(width, height),
        child: GestureDetector(
          key: boardKey,
          onPanStart: _onPanStart,
          onPanUpdate: _onPanUpdate,
          onPanEnd: _onPanEnd,
          child: // 根据游戏状态动态显示提示动画或透明容器
          board != null && board!.hard && _showHardModeBanner
              ? _hardModeBanner
              : Container(color: Colors.transparent), // 非显示条件时，使用透明容器
        ),
      ),
    );
  }

  // 困难模式提示动画组件
  Widget get _hardModeBanner => Center(
    // 使用 AnimatedBuilder 包裹需要动画的组件
    child: AnimatedBuilder(
      animation: _hardModeBannerController, // 监听控制器
      builder: (context, child) {
        return FadeTransition(
          opacity: _bannerFadeAnimation, // 使用控制器驱动的动画值
          child: ScaleTransition(
            scale: _bannerScaleAnimation, // 使用控制器驱动的动画值
            child: child, // 不随动画重建的子组件
          ),
        );
      },
      // child 是不依赖动画状态变化的组件，只会构建一次
      child: Container(
        width: double.infinity,
        height: 60,
        margin: const EdgeInsets.symmetric(horizontal: 10),
        decoration: BoxDecoration(
          color: Colors.red,
          borderRadius: BorderRadius.circular(10),
          border: Border.all(color: const Color.fromARGB(255, 247, 143, 135), width: 2),
          boxShadow: [BoxShadow(color: Color.fromRGBO(0, 0, 0, 0.3), blurRadius: 5, offset: const Offset(0, 3))],
        ),
        child: Center(
          child: Text(
            AppLocalizations.of(context)!.hardMode,
            style: TextStyle(color: Colors.white, fontSize: 30, fontWeight: FontWeight.bold),
          ),
        ),
      ),
    ),
  );

  Widget get nextButton {
    Device device = context.read<Device>();
    return AnimatedBuilder(
      // 监听显式动画 _bottomSlideAnimation
      animation: _bottomSlideAnimation,
      builder: (context, child) {
        return AnimatedPositioned(
          duration: _successAnimationController.duration!,
          // 从动画中获取实时 value，赋值给 bottom
          bottom: _bottomSlideAnimation.value,
          left: (device.screenSize.width - 200) / 2,
          child: child!, // 固定子组件，优化性能
        );
      },
      // 固定的按钮组件（仅构建一次，优化性能）
      child: MyElevatedButton(
        width: 200,
        borderRadius: BorderRadius.circular(20),
        gradient: LinearGradient(colors: [SkinHelper.coreBgColor, SkinHelper.slotBorderColor]),
        onPressed: () async {
          audio.playSfx(SfxType.click);
          // audio.pauseMusic();
          // await showInterstitialAd('level_exit', widget.item.id, data.currentLevel);
          // audio.startMusic();
          // if (!mounted) return;
          Navigator.pop(context, true);
        },
        child: Text(AppLocalizations.of(context)!.next, style: TextStyle(color: Colors.white, fontSize: 20)),
      ),
    );
  }

  Widget get successBanner {
    Device device = context.read<Device>();
    // 计算banner宽高
    final bannerWidth = device.screenSize.width - 40 * 2; // 左右各30间距
    final bannerHeight = 60.0;

    return AnimatedBuilder(
      animation: _bottomSlideAnimation,
      builder: (context, child) {
        return AnimatedPositioned(
          duration: _successAnimationController.duration!,
          top: _topSlideAnimation.value, // 固定底部位置
          left: 40, // 左间距30，与bannerWidth配合实现水平居中
          child: child!,
        );
      },
      // 核心：用Container固定尺寸，Stack填充Container，确保图片和文字尺寸对齐
      child: SizedBox(
        width: bannerWidth, // 容器宽=图片宽
        height: bannerHeight, // 容器高=图片高
        child: Stack(
          children: [
            // 1. 图片充满容器（与容器尺寸一致）
            Image.asset(
              'assets/images/banner3.png',
              width: double.infinity, // 图片宽=容器宽
              height: double.infinity, // 图片高=容器高
              fit: BoxFit.cover, // 图片填充容器（不拉伸，超出部分裁剪）
              cacheWidth: (context.watch<Device>().devicePixelRatio * bannerWidth).toInt(),
              cacheHeight: (context.watch<Device>().devicePixelRatio * bannerHeight).toInt(),
            ),
            Center(
              child: Padding(
                padding: EdgeInsets.only(top: 16.0),
                child: Text(
                  AppLocalizations.of(context)!.levelPass,
                  style: TextStyle(
                    color: Colors.white,
                    fontSize: 22,
                    fontWeight: FontWeight.bold,
                    shadows: [Shadow(color: Colors.black54, offset: Offset(1, 1), blurRadius: 2)],
                  ),
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }

  Offset _globalToLocal(Offset globalPosition) {
    final RenderBox renderBox = boardKey.currentContext!.findRenderObject() as RenderBox;
    return renderBox.globalToLocal(globalPosition);
  }

  void _onPanStart(DragStartDetails details) {
    _log.info('_onPanStart');

    _lastInteractionTick = DateTime.now().millisecondsSinceEpoch;
    _overLayer?.stopHint();

    if (board!.status != BoardStatus.playing) {
      _log.info('不是playing状态，不响应onPanStart');
      return;
    }

    if (board!.checkWinCondition()) {
      _log.info('游戏已经完成，不再响应onPanStart');
      return;
    }

    // 动画中断逻辑：如果动画正在进行，立即停止并强制所有 pieces 归位到最终位置
    if (_moveAnimationController.isAnimating && moveItems != null) {
      _log.info('移动动画中断，强制归位/交换');
      for (var item in moveItems!) {
        item.stop();
      }

      bool needRebuildGroup = moveItems!.any((item) => item.action == Action.swap);
      if (needRebuildGroup) {
        board!.backupAllGroups();
        board!.rebuildAllGroups();
        final mergeGroups = board!.compareAllGroups();

        if (mergeGroups.isNotEmpty) {
          // 此时不需要触发 merge 动画，只需确保数据结构正确
        }
      }

      moveItems = null; // 清空动画列表
      _moveAnimationController.stop();
      board!.invalidate(); // 触发一次重绘来显示最终位置
    }

    // 如果 merge 动画正在进行，也应该中断并立即归位
    if (_mergeAnimationController.isAnimating && _mergeGroups != null) {
      _log.info('合并动画中断，强制归位');

      for (var group in _mergeGroups!) {
        for (var piece in group.pieces) {
          piece.transform = board!.getTransformByCoordinate(piece.curRow, piece.curCol);
        }
      }
      _mergeGroups = null;
      _mergeAnimationController.stop();
      board!.invalidate();
    }

    // 停止所有正在运行的动画（如果尚未停止）
    _moveAnimationController.stop();
    _mergeAnimationController.stop();
    moveItems = null;

    final localPosition = _globalToLocal(details.globalPosition);
    final touchedPiece = board?.findPieceAt(localPosition);

    if (touchedPiece != null) {
      audio.playSfx(SfxType.panstart);
      if (settings.vibrate.value) {
        if (Platform.isAndroid) {
          Vibration.vibrate(duration: 60, amplitude: 50);
        } else {
          HapticFeedback.mediumImpact();
        }
      }

      _draggingPiece = touchedPiece;

      final draggingGroup = _draggingPiece!.group;
      if (draggingGroup != null) {
        // 将拖拽群组置于 pieces 列表末尾，确保它在 CustomPainter 中被最后绘制（在最上层）
        board!.pieces.removeWhere((p) => draggingGroup.contains(p));
        board!.pieces.addAll(draggingGroup.pieces);
      } else {
        board!.pieces.remove(_draggingPiece);
        board!.pieces.add(_draggingPiece!);
      }
      board!.invalidate();
    }
  }

  void _onPanUpdate(DragUpdateDetails details) {
    _lastInteractionTick = DateTime.now().millisecondsSinceEpoch;
    _overLayer?.stopHint();

    if (_draggingPiece == null) return;

    final Offset delta = details.delta;

    final draggingGroup = _draggingPiece!.group;
    if (draggingGroup != null) {
      // 拖拽过程中，所有群组成员共享相同的位移
      for (var piece in draggingGroup.pieces) {
        piece.applyDelta(delta);
      }
    } else {
      _draggingPiece!.applyDelta(delta);
    }

    board!.invalidate();
  }

  void _onPanEnd(DragEndDetails details) {
    _log.info('_onPanEnd');

    _lastInteractionTick = DateTime.now().millisecondsSinceEpoch;
    _overLayer?.stopHint();

    if (_draggingPiece == null) {
      return;
    }

    audio.playSfx(SfxType.tap);

    // 保存当前拖拽结束的碎片，以备动画使用
    Piece leaderPiece = _draggingPiece!;
    _draggingPiece = null; // 结束拖拽

    board!.invalidate();

    /// 交换或归位

    // 获取碎片的中心点，判断中心点是否落到某个piece上
    Piece? targetPiece = board!.findPieceAtExclude(leaderPiece.currentCenter, leaderPiece);

    // 群组特殊处理：如果 leaderPiece 没有落在其他碎片上，检查群组其他成员
    if (targetPiece == null && leaderPiece.group != null) {
      for (var p in leaderPiece.group!.pieces) {
        targetPiece = board!.findPieceAtExclude(p.currentCenter, p);
        if (targetPiece != null) {
          _log.info('推举 ${p.toString()} 为新leader');
          leaderPiece = p; // p 落在有效的其他piece上，推举为leaderPiece
          break;
        }
      }
    }

    // 判断是否可以交换
    if (targetPiece != null && targetPiece != leaderPiece && leaderPiece.canPlaceTo(targetPiece)) {
      _log.info("swap animation start");
      _animateSwap(leaderPiece, targetPiece);
    } else {
      _log.info("revert animation start");
      _animateRevert(leaderPiece);
    }
  }

  // 为所有涉及移动的 piece 创建独立的 MoveItem
  void _animateSwap(Piece leaderPiece, Piece targetPiece) {
    List<MoveItem> items = [];

    // 1. 确定涉及移动的所有碎片
    final List<Piece> draggingPieces = leaderPiece.group != null ? leaderPiece.group!.pieces : [leaderPiece];
    final int dr = targetPiece.curRow - leaderPiece.curRow; // 目标位置的行位移
    final int dc = targetPiece.curCol - leaderPiece.curCol; // 目标位置的列位移

    // 2. 识别被替换/推开的碎片
    List<Piece> displacedPieces = [];
    if (leaderPiece.group != null) {
      // 群组交换：找到群组新目标位置上的所有非自身群组的碎片
      for (var p in draggingPieces) {
        final int targetRow = p.curRow + dr;
        final int targetCol = p.curCol + dc;
        final Piece? other = board!.getPieceByCoordinate(targetRow, targetCol);
        if (other != null && !p.isSameGroup(other)) {
          displacedPieces.add(other);
        }
      }
    } else {
      // 单碎片交换：被替换的碎片就是 targetPiece
      displacedPieces.add(targetPiece);
    }

    // 3. 更新逻辑坐标 (curRow, curCol) - 必须在创建动画前完成

    // a. 更新拖拽群组/碎片的位置
    for (var p in draggingPieces) {
      p.curRow += dr;
      p.curCol += dc;
    }

    // b. 更新被推开的碎片的位置 (移入拖拽群组腾出的槽位)
    if (leaderPiece.group == null) {
      // 单碎片交换：targetPiece 移入 leaderPiece 的旧槽位
      targetPiece.curRow -= dr;
      targetPiece.curCol -= dc;
    } else {
      // 群组交换：被推开的碎片向后退 dr/dc 距离，找到空槽位
      for (var p in displacedPieces) {
        int newRow = p.curRow - dr;
        int newCol = p.curCol - dc;

        do {
          final Piece? pieceInSlot = board!.getPieceByCoordinate(newRow, newCol);
          if (pieceInSlot == null) {
            p.curRow = newRow;
            p.curCol = newCol;
            break;
          } else {
            newRow -= dr;
            newCol -= dc;
          }
        } while (newRow >= 0 && newRow < p.rows && newCol >= 0 && newCol < p.cols);
      }
    }

    // 4. 为所有涉及移动的碎片创建 MoveItem

    // a. 被推开的碎片
    for (var p in displacedPieces) {
      // 动画起点：旧的逻辑网格坐标 (p.transform)
      final startTransform = p.transform;
      // 动画终点：新的逻辑网格坐标
      final endTransform = board!.getTransformByCoordinate(p.curRow, p.curCol);
      final animation = Matrix4Tween(begin: startTransform, end: endTransform).animate(_moveAnimationController);

      items.add(MoveItem(piece: p, animation: animation, startTransform: startTransform, endTransform: endTransform, action: Action.swap));

      board!.pieces.remove(p);
      board!.pieces.add(p);
    }

    // b. 拖拽群组/碎片
    for (var p in draggingPieces) {
      // 动画起点：拖拽结束时的实际 Canvas 坐标 (p.transform)
      final startTransform = p.transform;
      // 动画终点：新的逻辑网格坐标
      final endTransform = board!.getTransformByCoordinate(p.curRow, p.curCol);
      final animation = Matrix4Tween(begin: startTransform, end: endTransform).animate(_moveAnimationController);

      items.add(MoveItem(piece: p, animation: animation, startTransform: startTransform, endTransform: endTransform, action: Action.swap));
      board!.pieces.remove(p);
      board!.pieces.add(p);
    }

    // 5. 启动动画
    moveItems = items;
    _moveAnimationController.forward(from: 0.0);
  }

  // 关键重构：为所有涉及归位的 piece 创建独立的 MoveItem
  void _animateRevert(Piece piece) {
    List<MoveItem> items = [];
    final List<Piece> groupPieces = piece.group != null ? piece.group!.pieces : [piece];

    for (var p in groupPieces) {
      // 动画起点：拖拽结束时的实际 Canvas 坐标 (p.transform)
      final startTransform = p.transform;
      // 动画终点：归位位置（即拖拽前所在的逻辑网格坐标）
      final endTransform = board!.getTransformByCoordinate(p.curRow, p.curCol);
      final animation = Matrix4Tween(begin: startTransform, end: endTransform).animate(_moveAnimationController);

      items.add(MoveItem(piece: p, animation: animation, startTransform: startTransform, endTransform: endTransform, action: Action.revert));
    }

    moveItems = items;
    _moveAnimationController.forward(from: 0.0);
  }
}

// 辅助类：用于对 vmath.Matrix4 进行线性插值 (lerp)，实现平滑动画
class Matrix4Tween extends Tween<vmath.Matrix4> {
  Matrix4Tween({required vmath.Matrix4 begin, required vmath.Matrix4 end}) : super(begin: begin, end: end);

  @override
  vmath.Matrix4 lerp(double t) {
    if (begin == null || end == null) return begin ?? end ?? vmath.Matrix4.identity();

    final List<double> lerpedStorage = List.generate(16, (i) {
      // 确保使用 ui.lerpDouble 进行插值
      return ui.lerpDouble(begin!.storage[i], end!.storage[i], t)!;
    });

    return vmath.Matrix4.fromList(lerpedStorage.cast<double>());
  }
}

// 动画辅助类，记录移动信息
class MoveItem {
  // 要移动的piece
  final Piece piece;
  // 动画animation
  final Animation<vmath.Matrix4> animation;
  // 起始位置（拖拽结束时的实际 Canvas 坐标）
  final vmath.Matrix4 startTransform;
  // 结束位置（目标网格槽位的 Canvas 坐标）
  final vmath.Matrix4 endTransform;

  // 移除了 MoveType，因为现在每个 piece 都有自己的 MoveItem
  // final MoveType moveType;

  final Action action;

  MoveItem({required this.piece, required this.animation, required this.startTransform, required this.endTransform, required this.action});

  // 关键修正：直接设置 piece 的 transform 为动画插值
  void move() {
    // 关键修正：直接设置piece的transform为动画插值，而不是累加delta
    piece.transform = animation.value;
  }

  void stop() {
    // 关键修正：动画中断时，直接设置到最终目标位置 (endTransform)
    // 此时 piece 的 curRow/curCol 已经是目标网格坐标
    piece.transform = endTransform;
  }
}