def _init_mobility(self):
    reset targets, speeds, pause timers
    if mobility_model != "random_waypoint":
        return
    waypoint_targets = random_points_in_cell(Mnum)
    node_speeds = uniform(v_min, v_max, size=Mnum)

def _update_positions(self, now_time):
    if mobility_model != "random_waypoint":
        return
    dt = now_time - last_position_update_time
    if dt < mobility_update_interval:
        return

    for each node:
        remaining = dt
        while remaining > 0:
            if node is pausing:
                consume pause time
                if pause ends:
                    refresh target and speed
            else:
                move toward current target
                if target can be reached in remaining time:
                    set position to target
                    enter random pause
                else:
                    advance by speed * remaining
                    remaining = 0

    last_position_update_time = now_time

def _calculate_power(self, idx):
    dxy = self._calculate_distance(self.bxy, self.mxy[idx])
    dxy = np.maximum(dxy, 1.0)
    shadow = self.shadow_std_db * self.mrnd[idx]
    power_dbm = (
        self.tpowdBm + self.txGain + self.rxGain
        - 38.5 - self.alfa * 10 * np.log10(dxy) - shadow
    )
    if self.channel_model == "rayleigh":
        h = (np.random.randn(len(idx)) + 1j * np.random.randn(len(idx))) / np.sqrt(2)
        rayleigh_gain = np.maximum(np.abs(h) ** 2, 1e-12)
        power_dbm += 10 * np.log10(rayleigh_gain)
    return 10 ** (power_dbm / 10)

def _calculate_sinr(self, idx):
    pow_vals = self._calculate_power(idx)
    max_pos = np.argmax(pow_vals)
    signal = pow_vals[max_pos]
    interference = np.sum(pow_vals) - signal
    sinr_db = 10 * np.log10(signal / (self.NoisePower + interference))
    return max_pos, sinr_db

def _resolve_channel(self, idx):
    if len(idx) <= 1:
        return
    self.collision_count += 1
    max_pos, sinr_db = self._calculate_sinr(idx)
    self.Mstate[idx] = COLLISION
    if sinr_db >= self.tcn:
        self.Mstate[idx[max_pos]] = TRANSMIT
        self.capture_success_count += 1

"""无线随机接入协议仿真脚本。

本文件同时完成三件事：
1. 对 Pure ALOHA、Slotted ALOHA、np-CSMA 三种 MAC 协议进行离散事件仿真；
2. 对比 baseline 与 enhanced 两组实验配置；
3. 将仿真结果输出到终端、JSON、Markdown 和 seaborn 图像。

baseline 与 enhanced 的核心区别只体现在业务源、运动模型和信道模型配置上。
两组实验统一使用 SINR 捕获判决，便于直接比较不同增强因素对吞吐量、冲突和时延的影响。
"""

import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
import pandas as pd
import random
import time
import json
import argparse
from pathlib import Path
from typing import List, Dict, Any, Optional

# 终端 MAC 状态常量。
# STANDBY：终端空闲或等待下一次分组到达；
# TRANSMIT：终端正在发送，若没有冲突或可被 SINR 捕获，则最终计为成功；
# COLLISION：终端当前发送已被判为冲突，后续会重新退避。
STANDBY = 0
TRANSMIT = 1
COLLISION = 2


def setup_chinese_font():
    """设置中文图表字体。

    seaborn 会重置 matplotlib 的部分样式参数，因此这里同时设置
    matplotlib rcParams 与 seaborn theme，保证保存图片时中文标题、
    坐标轴标签和负号都能正常显示。字体列表按优先级排列，宋体不可用时
    自动回退到系统常见中文字体。
    """
    font_options = [
        "SimSun",
        "宋体",
        "Microsoft YaHei",
        "SimHei",
        "Arial Unicode MS",
        "DejaVu Sans",
    ]
    plt.rcParams["font.sans-serif"] = font_options
    plt.rcParams["axes.unicode_minus"] = False
    sns.set_theme(
        style="whitegrid",
        rc={
            "font.sans-serif": font_options,
            "axes.unicode_minus": False,
        },
    )


class WirelessNetworkSimulator:
    """无线随机接入网络的离散事件仿真器。

    一个实例代表一组实验配置，例如 baseline 或 enhanced。实例内部维护
    终端位置、业务到达时间、MAC 状态、移动模型状态、信道参数和统计量。
    外部调用 `simulate_all_protocols()` 后，会依次运行三种协议并返回曲线数据。
    """

    def __init__(
        self,
        Mnum: int = 100,
        spend: int = 10000,
        traffic_mode: str = "poisson",
        mobility_enabled: bool = False,
        shadow_std_db: float = 6.0,
        result_prefix: str = "baseline",
        mobility_model: Optional[str] = None,
        channel_model: str = "log_distance",
        mobility_update_interval: float = 0.01,
    ):
        """初始化仿真器参数和静态拓扑。

        Args:
            Mnum: 终端数量。
            spend: 每个业务负载 G 下需要累计的成功发送分组数。
            traffic_mode: 业务源模型，`poisson` 为原始泊松业务，
                `mixed` 为普通泊松业务与突发业务混合。
            mobility_enabled: 兼容旧接口的开关。未显式指定 `mobility_model`
                时，True 会映射为 random_waypoint，False 会映射为 static。
            shadow_std_db: 阴影衰落标准差，单位 dB。
            result_prefix: 实验组名称，用于标识 baseline/enhanced。
            mobility_model: 运动模型，支持 `static` 和 `random_waypoint`。
            channel_model: 信道模型，支持 `log_distance` 和 `rayleigh`。
            mobility_update_interval: 随机路点位置更新间隔。大于 0 时按固定
                时间间隔批量推进位置，避免每个 MAC 事件都更新所有终端。
        """
        # 系统参数。bit_rate 当前只保留为系统信息，实际分组持续时间由
        # packet_length / sym_rate 计算得到。
        self.bit_rate = 512e3
        self.sym_rate = 256e3
        self.packet_length = 128
        # Dtime 表示传播/侦听延迟相对于一个分组持续时间的比例。
        self.Dtime = 0.01
        # alfa 为路径损耗指数；sigma 保留原始参数，当前阴影衰落使用 shadow_std_db。
        self.alfa = 3
        self.sigma = 6

        # AP 参数。基站位于圆心上方 5 m，终端在半径 r 的二维圆域内移动。
        self.r = 100
        self.bxy = np.array([0, 0, 5])
        self.tcn = 10  # SINR 捕获门限，单位 dB。

        # 终端参数。
        self.Mnum = Mnum
        # 改进1：业务源模式，poisson 表示原始泊松业务，mixed 表示普通业务和突发业务混合。
        self.traffic_mode = traffic_mode
        # 改进2：运动模型，static 表示静态终端，random_waypoint 表示随机路点模型。
        if mobility_model is None:
            mobility_model = "random_waypoint" if mobility_enabled else "static"
        if mobility_model not in {"static", "random_waypoint"}:
            raise ValueError("mobility_model 必须是 'static' 或 'random_waypoint'")
        self.mobility_model = mobility_model
        self.mobility_enabled = self.mobility_model != "static"
        # 改进3：信道模型，log_distance 为路径损耗+阴影衰落，rayleigh 额外叠加快衰落。
        if channel_model not in {"log_distance", "rayleigh"}:
            raise ValueError("channel_model 必须是 'log_distance' 或 'rayleigh'")
        self.channel_model = channel_model
        # 阴影衰落标准差，baseline 保留原始 1 dB，enhanced 使用 sigma=6 dB。
        self.shadow_std_db = shadow_std_db
        # 为 baseline/enhanced 两组实验生成不同文件名前缀，避免结果互相覆盖。
        self.result_prefix = result_prefix
        # 突发业务终端比例，设置为 20% 便于体现不同业务强度。
        self.burst_ratio = 0.2
        # 突发终端平均发包间隔缩短为普通终端的 1/4。
        self.burst_factor = 4.0
        # 随机路点模型参数：速度单位按仿真时间尺度理解，暂停时间单位为秒。
        self.waypoint_min_speed = 0.5
        self.waypoint_max_speed = 2.0
        self.waypoint_max_pause_time = 1.0
        if mobility_update_interval < 0:
            raise ValueError("mobility_update_interval 必须大于等于 0")
        self.mobility_update_interval = mobility_update_interval
        # 记录上一次位置更新时间，用于按事件间隔推进终端位置。
        self.last_position_update_time = 0.0

        # 仿真参数。三种协议使用同一套信道、业务源和统计逻辑。
        self.protocols = ["Pure ALOHA", "Slotted ALOHA", "np-CSMA"]
        self.spend = spend

        # 计算参数。
        # Ttime 是一个分组占用信道的时间，也就是事件表中发送开始到发送结束的间隔。
        self.Ttime = self.packet_length / self.sym_rate
        self.tpowdBm = 20  # dbm
        self.txGain = 0
        self.rxGain = 0
        self.N0 = -174  # dbm/Hz
        self.NF = 5  # dB
        self.NoisePowerdBm = self.N0 + 10 * np.log10(self.sym_rate) + self.NF
        self.NoisePower = 10 ** (self.NoisePowerdBm / 10)
        # 初始化终端位置。
        # mxy 为 Mnum x 3 数组，前三列分别表示 x、y、z 坐标。
        self.mxy = self._generate_terminal_positions(self.r, self.Mnum, 0)
        # 保存初始拓扑，保证每个业务负载从同一组初始位置开始仿真。
        self.initial_mxy = self.mxy.copy()
        # mrnd 是每个终端固定的阴影衰落随机量。一次仿真中同一终端的阴影项保持一致。
        self.mrnd = np.random.randn(self.Mnum)
        # 记录哪些终端属于突发业务源。
        self.is_burst_node = np.zeros(self.Mnum, dtype=bool)
        # 随机路点模型状态：目标位置、当前速度、剩余暂停时间。
        self.waypoint_targets = np.zeros((self.Mnum, 2))
        self.node_speeds = np.zeros(self.Mnum)
        self.pause_remaining = np.zeros(self.Mnum)

    def _generate_terminal_positions(self, r: float, n: int, h: int = 0) -> np.ndarray:
        """生成初始终端位置。

        这里保留原始代码的离散随机撒点方式：随机产生整数 x/y 坐标，
        通过圆域约束和重复位置检查后写入坐标数组。这样可以避免多个终端
        完全重合，并保证初始终端都位于 AP 覆盖半径内。

        Args:
            r: 圆形覆盖半径。
            n: 需要生成的终端数量。
            h: 是否随机生成终端高度。当前实验默认 h=0，即终端位于 z=0 平面。
        """
        posxy = np.zeros((n, 3))
        occupied_positions = set()

        for i in range(n):
            while True:
                xx = round(r * random.random()) * np.sign(
                    np.sin(2 * np.pi * random.random())
                )
                yy = round(r * random.random()) * np.sign(
                    np.cos(2 * np.pi * random.random())
                )

                if xx**2 + yy**2 <= r**2 and (xx != 0 or yy != 0):
                    if (xx, yy) not in occupied_positions:
                        occupied_positions.add((xx, yy))
                        posxy[i, 0] = xx
                        posxy[i, 1] = yy
                        if h == 1:
                            posxy[i, 2] = random.random() + 3
                        break
        return posxy

    def _generate_random_points_in_cell(self, n: int) -> np.ndarray:
        """在圆形覆盖范围内均匀生成二维目标点。

        随机路点模型需要为终端生成新的移动目标。半径使用
        `r * sqrt(U)` 而不是 `r * U`，目的是让圆面积上的点分布均匀，
        避免目标点过度集中在圆心附近。
        """
        radius = self.r * np.sqrt(np.random.rand(n))
        theta = 2 * np.pi * np.random.rand(n)
        return np.column_stack((radius * np.cos(theta), radius * np.sin(theta)))

    def _reset_states(self):
        """重置单次仿真的动态状态和统计变量。

        每个协议、每个业务负载 G 都会调用一次该函数。这里不重新生成
        初始拓扑，只从 `initial_mxy` 恢复位置，保证不同 G 的比较不受上一次
        终端移动轨迹影响。
        """
        # Mstate 记录每个终端当前 MAC 状态。
        self.Mstate = np.zeros(self.Mnum, dtype=int)
        # Mplen 记录每个终端当前分组长度。当前模型所有分组等长。
        self.Mplen = np.full(self.Mnum, self.packet_length)
        # mgtime：分组生成时间；mtime：下一次事件时间；Mstime：最近一次发送开始时间。
        self.mgtime = None
        self.mtime = None
        self.Mstime = None
        self.slot = None
        # 每次单独仿真前恢复初始拓扑，避免上一组移动结果影响下一组。
        self.mxy = self.initial_mxy.copy()

        # 重置统计变量
        self.Spnum = 0
        self.Splen = 0
        self.Tplen = 0
        self.Wtime = 0
        # 新增统计：记录发生重叠传输的次数。
        self.collision_count = 0
        # 新增统计：记录 SINR 捕获成功次数。
        self.capture_success_count = 0

    def _init_traffic_state(self):
        """初始化普通业务终端和突发业务终端。

        baseline 使用 `poisson`，所有终端的到达过程相同。enhanced 使用
        `mixed`，随机选取一部分终端作为突发业务源，使其平均到达间隔更短。
        """
        # 默认所有终端都是普通泊松业务源。
        self.is_burst_node = np.zeros(self.Mnum, dtype=bool)
        if self.traffic_mode == "mixed":
            # 混合模式下随机选取一部分终端作为突发业务源。
            burst_num = max(1, int(self.Mnum * self.burst_ratio))
            burst_idx = np.random.choice(self.Mnum, burst_num, replace=False)
            self.is_burst_node[burst_idx] = True

    def _next_packet_time(self, node_id: int, now_time: float) -> float:
        """生成某个终端的下一次分组到达时间。

        分组到达间隔服从指数分布，使用反函数法生成：
        interval_sample = -mean_interval * log(1-U)。
        对突发终端，mean_interval 会除以 burst_factor，从而提高短时间内的发包密度。
        """
        interval = self.Tint
        if self.traffic_mode == "mixed" and self.is_burst_node[node_id]:
            # 突发终端缩短到达间隔，用来模拟短时间连续发包。
            interval = self.Tint / self.burst_factor
        return now_time - interval * np.log(1 - random.random())

    def _init_mobility(self):
        """初始化运动模型状态。

        `static` 模式只清空运动状态；`random_waypoint` 模式会为每个终端
        生成初始目标点和移动速度。该函数在每个业务负载 G 开始前调用，
        保证不同负载下的移动状态从同一时间起点重新开始。
        """
        self.last_position_update_time = 0.0
        self.waypoint_targets = np.zeros((self.Mnum, 2))
        self.node_speeds = np.zeros(self.Mnum)
        self.pause_remaining = np.zeros(self.Mnum)
        if self.mobility_model != "random_waypoint":
            return
        self.waypoint_targets = self._generate_random_points_in_cell(self.Mnum)
        speed_span = self.waypoint_max_speed - self.waypoint_min_speed
        self.node_speeds = self.waypoint_min_speed + speed_span * np.random.rand(
            self.Mnum
        )

    def _refresh_waypoint_target(self, node_id: int):
        """为一个终端选择新的随机路点目标和移动速度。

        终端到达当前目标并完成暂停后，会调用该函数进入下一段移动。
        速度在 [waypoint_min_speed, waypoint_max_speed] 内均匀抽样。
        """
        self.waypoint_targets[node_id] = self._generate_random_points_in_cell(1)[0]
        speed_span = self.waypoint_max_speed - self.waypoint_min_speed
        self.node_speeds[node_id] = (
            self.waypoint_min_speed + speed_span * random.random()
        )

    def _update_positions(self, now_time: float):
        """按事件时间推进随机路点运动状态。

        仿真主循环由 MAC 事件驱动。若每个事件都更新所有终端位置，在大规模节点
        和高业务负载下开销很大。因此这里使用 `mobility_update_interval` 做时间门限：
        只有距离上次位置更新足够久时，才批量推进全部终端的位置。
        """
        if self.mobility_model != "random_waypoint":
            return
        dt = now_time - self.last_position_update_time
        if dt <= 0:
            return
        # 运动模型按移动时间尺度更新，避免每个 MAC 事件都触发全节点位置计算。
        if self.mobility_update_interval > 0 and dt < self.mobility_update_interval:
            return
        for node_id in range(self.Mnum):
            # remaining 表示本次位置更新时间片中还没有被暂停或移动消耗的时间。
            remaining = dt
            while remaining > 0:
                if self.pause_remaining[node_id] > 0:
                    # 终端处于路点暂停阶段时，优先消耗暂停时间；暂停结束后再换新目标。
                    pause_step = min(remaining, self.pause_remaining[node_id])
                    self.pause_remaining[node_id] -= pause_step
                    remaining -= pause_step
                    if self.pause_remaining[node_id] <= 0:
                        self._refresh_waypoint_target(node_id)
                    continue

                current_xy = self.mxy[node_id, 0:2]
                target_xy = self.waypoint_targets[node_id]
                direction = target_xy - current_xy
                distance = float(np.linalg.norm(direction))
                if distance <= 1e-9:
                    # 已经到达目标点时进入随机暂停；暂停时间可能为 0，此时立即刷新目标。
                    self.pause_remaining[node_id] = (
                        self.waypoint_max_pause_time * random.random()
                    )
                    if self.pause_remaining[node_id] <= 0:
                        self._refresh_waypoint_target(node_id)
                    continue

                travel_time = distance / self.node_speeds[node_id]
                if travel_time <= remaining:
                    # 本次时间片足够到达目标点：终端停在目标点并进入暂停阶段。
                    self.mxy[node_id, 0:2] = target_xy
                    remaining -= travel_time
                    self.pause_remaining[node_id] = (
                        self.waypoint_max_pause_time * random.random()
                    )
                else:
                    # 本次时间片不足以到达目标点：沿目标方向前进 speed * remaining。
                    self.mxy[node_id, 0:2] += (
                        direction / distance * self.node_speeds[node_id] * remaining
                    )
                    remaining = 0
        self.last_position_update_time = now_time

    def _calculate_distance(self, bstn: np.ndarray, mstn: np.ndarray) -> np.ndarray:
        """计算 AP 到终端的三维欧氏距离。"""
        return np.sqrt(np.sum((bstn - mstn) ** 2, axis=1))

    def _calculate_power(self, idx: np.ndarray) -> np.ndarray:
        """计算指定终端集合在 AP 处的接收功率。

        返回值为线性功率，单位与 NoisePower 保持一致。计算过程为：
        1. 发射功率 + 天线增益；
        2. 扣除 1 m 参考路径损耗；
        3. 扣除对数距离路径损耗；
        4. 扣除阴影衰落；
        5. enhanced 的 Rayleigh 信道额外叠加快衰落增益。
        """
        dxy = self._calculate_distance(self.bxy, self.mxy[idx])
        # 距离下限设为 1 米，避免 log10(0) 或过小距离导致功率异常。
        dxy = np.maximum(dxy, 1.0)
        refPL_1m = 38.5
        shadow = self.shadow_std_db * self.mrnd[idx]
        # 前两层沿用原信道：对数距离路径损耗 + 阴影衰落。
        power = (
            self.tpowdBm
            + self.txGain
            + self.rxGain
            - refPL_1m
            - self.alfa * 10 * np.log10(dxy)
            - shadow
        )
        if self.channel_model == "rayleigh":
            # 第三层：Rayleigh 快衰落。h ~ CN(0, 1)，|h|^2 服从均值为 1 的指数分布。
            h = (np.random.randn(len(idx)) + 1j * np.random.randn(len(idx))) / np.sqrt(
                2
            )
            rayleigh_gain = np.maximum(np.abs(h) ** 2, 1e-12)
            power += 10 * np.log10(rayleigh_gain)
        pow_val = 10 ** (power / 10)
        return pow_val

    def _calculate_sinr(self, idx: np.ndarray):
        """计算最强接收终端及其 SINR。

        SINR 公式为 signal / (noise + interference)。其中 signal 取当前
        同时发送终端中接收功率最大的一个，interference 为其余同时发送终端
        接收功率之和。返回的 max_pos 是 idx 内部位置，不是全局终端编号。
        """
        pow_vals = self._calculate_power(idx)
        # 选择接收功率最大的终端作为捕获候选。
        max_pos = np.argmax(pow_vals)
        signal = pow_vals[max_pos]
        # 其他同时发送终端的功率都作为干扰。
        interference = np.sum(pow_vals) - signal
        sinr = signal / (self.NoisePower + interference)
        sinr_db = 10 * np.log10(max(sinr, 1e-30))
        return max_pos, sinr_db

    def _resolve_channel(self, idx: np.ndarray):
        """处理同时发送终端的冲突和 SINR 捕获。

        若当前只有 0 或 1 个活动发送终端，无需信道判决。若多个终端重叠发送，
        先记一次冲突，再计算最强终端的 SINR。只有 SINR 达到门限时，最强终端
        被捕获为成功发送，其余终端保持冲突状态。
        """
        if len(idx) <= 1:
            return
        # 同一时刻存在多个活动发送终端，记为一次冲突事件。
        self.collision_count += 1
        max_pos, sinr_db = self._calculate_sinr(idx)
        if self.Mstate[idx[max_pos]] == TRANSMIT:
            # 先默认全部冲突，再根据 SINR 门限恢复最强终端为成功发送状态。
            self.Mstate[idx] = COLLISION
            if sinr_db >= self.tcn:
                self.Mstate[idx[max_pos]] = TRANSMIT
                self.capture_success_count += 1

    def _carrier_sense(self, now_time: float) -> int:
        """np-CSMA 的载波侦听功能。

        根据各终端最近发送开始时间 Mstime 判断当前时刻是否落在某次传输窗口内。
        Dtime * Ttime 用于模拟传播/侦听延迟，使刚开始的发送不会立即被侦听到。
        返回 1 表示信道忙，返回 0 表示信道空闲。
        """
        if self.Mstime is None or self.Mstime.size == 0:
            return 0

        delay = self.Dtime * self.Ttime
        transmitting = np.where(
            (self.Mstime + delay <= now_time)
            & (now_time <= self.Mstime + delay + self.Ttime)
        )[0]
        return 1 if len(transmitting) > 0 else 0

    def _pure_aloha_protocol(self, now_time: float) -> float:
        """纯 ALOHA 协议的单步事件处理。

        该函数每次处理当前 now_time 对应的所有终端事件，并返回下一次事件时间。
        Pure ALOHA 不做时隙对齐，也不做发送前侦听；分组一到达就尝试发送。
        """
        if now_time < 0:  # 初始化
            self.mgtime = np.array(
                [self._next_packet_time(i, 0.0) for i in range(self.Mnum)]
            )
            self.mtime = self.mgtime.copy()
            self.Mstate = np.zeros(self.Mnum, dtype=int)
            self.Mstime = np.full(self.Mnum, -np.inf)
            return np.min(self.mtime)

        # 处理成功传输：上一轮被判定为 TRANSMIT 的终端在发送结束时累计吞吐量。
        idx_success = np.where((self.mtime == now_time) & (self.Mstate == TRANSMIT))[0]
        if len(idx_success) > 0:
            idx = idx_success[0]
            self.Spnum += 1
            self.Splen += self.Mplen[idx]
            self.Wtime += now_time - self.mgtime[idx]
            self.Mstate[idx] = STANDBY
            self.mgtime[idx] = self._next_packet_time(idx, now_time)
            self.mtime[idx] = self.mgtime[idx]

        # 处理冲突：冲突终端不计成功，按指数退避重新安排发送时间。
        idx_collision = np.where((self.mtime == now_time) & (self.Mstate == COLLISION))[
            0
        ]
        if len(idx_collision) > 0:
            self.Mstate[idx_collision] = STANDBY
            self.mtime[idx_collision] = now_time - self.Rint * np.log(
                1 - np.random.rand(len(idx_collision))
            )

        # 处理发送：到达当前事件时间的终端立即占用信道直到分组发送完成。
        idx_send = np.where(self.mtime == now_time)[0]
        if len(idx_send) > 0:
            self.Mstate[idx_send] = TRANSMIT
            self.mtime[idx_send] = now_time + self.Mplen[idx_send] / self.sym_rate
            self.Mstime[idx_send] = now_time
            self.Tplen += np.sum(self.Mplen[idx_send])

        return np.min(self.mtime)

    def _slotted_aloha_protocol(self, now_time: float) -> float:
        """Slotted ALOHA 协议的单步事件处理。

        与 Pure ALOHA 的主要区别是所有发送开始时间被对齐到下一个时隙边界。
        时隙长度等于一个分组持续时间，因此冲突只会发生在同一时隙内。
        """
        if self.slot is None:
            self.slot = self.packet_length / self.sym_rate

        if now_time < 0:  # 初始化
            self.mgtime = np.array(
                [self._next_packet_time(i, 0.0) for i in range(self.Mnum)]
            )
            self.mtime = (np.floor(self.mgtime / self.slot) + 1) * self.slot
            self.Mstate = np.zeros(self.Mnum, dtype=int)
            self.Mstime = np.full(self.Mnum, -np.inf)
            return np.min(self.mtime)

        # 处理成功传输
        idx_success = np.where((self.mtime == now_time) & (self.Mstate == TRANSMIT))[0]
        if len(idx_success) > 0:
            idx = idx_success[0]
            self.Spnum += 1
            self.Splen += self.Mplen[idx]
            self.Wtime += now_time - self.mgtime[idx]
            self.Mstate[idx] = STANDBY
            self.mgtime[idx] = self._next_packet_time(idx, now_time)
            self.mtime[idx] = (np.floor(self.mgtime[idx] / self.slot) + 1) * self.slot

        # 处理冲突
        idx_collision = np.where((self.mtime == now_time) & (self.Mstate == COLLISION))[
            0
        ]
        if len(idx_collision) > 0:
            self.Mstate[idx_collision] = STANDBY
            self.mtime[idx_collision] = now_time - self.Rint * np.log(
                1 - np.random.rand(len(idx_collision))
            )
            self.mtime[idx_collision] = (
                np.floor(self.mtime[idx_collision] / self.slot) + 1
            ) * self.slot

        # 处理发送
        idx_send = np.where(self.mtime == now_time)[0]
        if len(idx_send) > 0:
            self.Mstate[idx_send] = TRANSMIT
            self.mtime[idx_send] = now_time + self.Mplen[idx_send] / self.sym_rate
            self.mtime[idx_send] = (
                np.round(self.mtime[idx_send] / self.slot) * self.slot
            )
            self.Mstime[idx_send] = now_time
            self.Tplen += np.sum(self.Mplen[idx_send])

        return np.min(self.mtime)

    def _np_csma_protocol(self, now_time: float) -> float:
        """非坚持 CSMA 协议的单步事件处理。

        终端有分组待发时先进行载波侦听。若信道空闲则立即发送；
        若信道忙则按指数退避等待下一次尝试。该实现体现的是
        non-persistent CSMA 的“忙则退避，不持续监听”策略。
        """
        if now_time < 0:  # 初始化
            self.mgtime = np.array(
                [self._next_packet_time(i, 0.0) for i in range(self.Mnum)]
            )
            self.Mstime = np.full(self.Mnum, -np.inf)
            self.mtime = self.mgtime.copy()
            self.Mstate = np.zeros(self.Mnum, dtype=int)
            return np.min(self.mtime)

        # 处理成功传输
        idx_success = np.where((self.mtime == now_time) & (self.Mstate == TRANSMIT))[0]
        if len(idx_success) > 0:
            idx = idx_success[0]
            self.Spnum += 1
            self.Splen += self.Mplen[idx]
            self.Wtime += now_time - self.mgtime[idx]
            self.Mstate[idx] = STANDBY
            self.mgtime[idx] = self._next_packet_time(idx, now_time)
            self.mtime[idx] = self.mgtime[idx]

        # 处理冲突
        idx_collision = np.where((self.mtime == now_time) & (self.Mstate == COLLISION))[
            0
        ]
        if len(idx_collision) > 0:
            self.Mstate[idx_collision] = STANDBY
            self.mtime[idx_collision] = now_time - self.Rint * np.log(
                1 - np.random.rand(len(idx_collision))
            )

        # 处理待发送
        idx_standby = np.where((self.mtime == now_time) & (self.Mstate == STANDBY))[0]
        if len(idx_standby) > 0:
            self.Tplen += np.sum(self.Mplen[idx_standby])
            for jj in idx_standby:
                if self._carrier_sense(now_time) == 0:  # 信道空闲
                    self.Mstate[jj] = TRANSMIT
                    self.Mstime[jj] = now_time
                    self.mtime[jj] = now_time + self.Mplen[jj] / self.sym_rate
                else:  # 信道忙
                    self.mtime[jj] = now_time - self.Rint * np.log(1 - random.random())

        return np.min(self.mtime)

    def _run_single_simulation(self, protocol_func, G: float) -> Dict[str, Any]:
        """运行单个业务负载 G 下的一次完整仿真。

        主循环采用离散事件推进：协议函数负责处理当前事件并返回下一事件时间；
        运动模型在事件处理前更新终端位置；信道模型在事件处理后判断当前重叠发送。
        当成功分组数达到 spend 时停止，并返回吞吐量、冲突次数、平均等待时间等指标。
        """
        # 重置状态
        self._reset_states()
        # 计算参数。
        # G 是归一化业务负载。Tint 由泊松到达模型反推得到，用于控制平均到达间隔。
        self.Tint = -self.Ttime / np.log(1 - G / self.Mnum)
        self.Rint = self.Tint
        # 改进1：每次仿真根据 traffic_mode 初始化普通/突发业务源。
        self._init_traffic_state()
        # 改进2：每次仿真重新初始化运动模型状态。
        self._init_mobility()

        # 初始化终端
        now_time = protocol_func(-1)

        # 主仿真循环。每次迭代只推进到下一个离散事件，而不是按固定时间步扫描。
        while True:
            # 改进2：在每个事件处理前，根据当前仿真时间更新终端位置。
            self._update_positions(now_time)
            next_time = protocol_func(now_time)
            if self.Spnum >= self.spend:
                break

            # 检查传输状态。TRANSMIT 和 COLLISION 都代表当前有信号占用信道，
            # 因此都需要进入信道判决函数。
            idx = np.where((self.Mstate == TRANSMIT) | (self.Mstate == COLLISION))[0]
            # 改进3：统一使用信道处理函数完成冲突判断和 SINR 捕获。
            self._resolve_channel(idx)

            now_time = next_time

        # 计算统计量
        traffic = self.Tplen / self.sym_rate / now_time
        throughput = self.Splen / self.sym_rate / now_time

        return {
            "G": G,
            "traffic": traffic,
            "throughput": throughput,
            "total_time": now_time,
            "success_packets": self.Spnum,
            # 新增统计指标，用于报告中分析冲突、时延和捕获效果。
            "collision_count": self.collision_count,
            "avg_delay": self.Wtime / max(self.Spnum, 1),
            "capture_success_count": self.capture_success_count,
        }

    def _get_protocol_function(self, protocol_idx: int):
        """获取协议对应的仿真函数"""
        if protocol_idx == 0:
            return self._pure_aloha_protocol
        elif protocol_idx == 1:
            return self._slotted_aloha_protocol
        else:  # protocol_idx == 2
            return self._np_csma_protocol

    def simulate_single_protocol(self, protocol_idx: int) -> List[Dict[str, Any]]:
        """仿真单个协议在多个业务负载 G 下的性能曲线。

        G_values 对应报告中的吞吐量-负载曲线横轴。这里已移除理论值计算，
        只保留仿真测得的实际业务负载和吞吐量。
        """
        # 获取协议函数
        protocol_func = self._get_protocol_function(protocol_idx)
        if protocol_idx == 2:  # np-CSMA需要重置时隙参数
            self.slot = None

        results = []

        # 业务负载循环
        G_values = list(np.arange(0.1, 1.1, 0.1)) + list(np.arange(1.2, 2.1, 0.2))

        for i, G in enumerate(G_values):
            if G >= self.Mnum:
                break

            # 运行仿真
            result = self._run_single_simulation(protocol_func, G)
            results.append(result)

        return results

    def simulate_all_protocols(self) -> Dict[str, List[Dict[str, Any]]]:
        """依次仿真所有三种协议，并打印每种协议的耗时。"""
        all_results = {}

        for i, protocol_name in enumerate(self.protocols):
            start_time = time.time()
            results = self.simulate_single_protocol(i)
            elapsed_time = time.time() - start_time

            all_results[protocol_name] = results
            print(f"{protocol_name} 仿真完成，耗时: {elapsed_time:.2f} 秒")

        return all_results

    def config_summary(self) -> Dict[str, Any]:
        """返回当前实验组的关键参数。

        该字典会同时写入 JSON、Markdown 和终端输出，是复现实验配置的主要依据。
        """
        return {
            "Mnum": self.Mnum,
            "spend": self.spend,
            "traffic_mode": self.traffic_mode,
            "mobility_model": self.mobility_model,
            "mobility_enabled": self.mobility_enabled,
            "channel_model": self.channel_model,
            "shadow_std_db": self.shadow_std_db,
            "burst_ratio": self.burst_ratio,
            "burst_factor": self.burst_factor,
            "waypoint_min_speed": self.waypoint_min_speed,
            "waypoint_max_speed": self.waypoint_max_speed,
            "waypoint_max_pause_time": self.waypoint_max_pause_time,
            "mobility_update_interval": self.mobility_update_interval,
            "radius_m": self.r,
            "tx_power_dbm": self.tpowdBm,
            "path_loss_exponent": self.alfa,
            "packet_length_symbols": self.packet_length,
            "symbol_rate": self.sym_rate,
            "sinr_threshold_db": self.tcn,
        }


def protocol_file_name(protocol_name: str) -> str:
    """将协议名称转换成适合文件名使用的形式。"""
    return protocol_name.replace(" ", "_")


def to_jsonable(value: Any) -> Any:
    """将 numpy 类型转成 JSON 可序列化的 Python 原生类型。

    仿真结果中包含 numpy 标量和数组，`json.dumps` 不能直接处理这些类型。
    该函数递归遍历 dict/list/tuple，把 numpy 类型转换为 int、float 或 list。
    """
    if isinstance(value, dict):
        return {key: to_jsonable(item) for key, item in value.items()}
    if isinstance(value, list):
        return [to_jsonable(item) for item in value]
    if isinstance(value, tuple):
        return [to_jsonable(item) for item in value]
    if isinstance(value, np.integer):
        return int(value)
    if isinstance(value, np.floating):
        return float(value)
    if isinstance(value, np.ndarray):
        return value.tolist()
    return value


def compute_statistics(
    results: Dict[str, List[Dict[str, Any]]],
) -> Dict[str, Dict[str, Any]]:
    """按协议汇总统计指标。

    输入是一组实验中三种协议的原始曲线数据，输出是报告和柱状图需要的
    汇总指标，包括平均吞吐量、最大吞吐量、最佳 G、总冲突次数、
    平均等待时间和捕获成功次数。
    """
    statistics = {}
    for protocol_name, protocol_results in results.items():
        # 吞吐量数组用于查找最大值和波动情况。
        throughputs = np.array(
            [row["throughput"] for row in protocol_results], dtype=float
        )
        best_idx = int(np.argmax(throughputs))
        best_row = protocol_results[best_idx]
        statistics[protocol_name] = {
            "avg_throughput": float(np.mean(throughputs)),
            "max_throughput": float(np.max(throughputs)),
            "min_throughput": float(np.min(throughputs)),
            "std_throughput": float(np.std(throughputs)),
            "best_G": float(best_row["G"]),
            "best_traffic": float(best_row["traffic"]),
            "total_collision_count": int(
                sum(row["collision_count"] for row in protocol_results)
            ),
            "mean_avg_delay": float(
                np.mean([row["avg_delay"] for row in protocol_results])
            ),
            "total_capture_success_count": int(
                sum(row["capture_success_count"] for row in protocol_results)
            ),
        }
    return statistics


def build_comparison(experiments: Dict[str, Dict[str, Any]]) -> Dict[str, Any]:
    """生成 baseline 与 enhanced 的对比统计。

    该函数不重新计算原始曲线，只比较两组实验已经汇总出的 statistics。
    结果按协议组织，方便 Markdown 中按协议展示，也方便生成总对比表。
    """
    baseline_stats = experiments["baseline"]["statistics"]
    enhanced_stats = experiments["enhanced"]["statistics"]
    by_protocol = {}
    for protocol_name in baseline_stats:
        base = baseline_stats[protocol_name]
        enhanced = enhanced_stats[protocol_name]
        max_delta = enhanced["max_throughput"] - base["max_throughput"]
        by_protocol[protocol_name] = {
            "baseline_max_throughput": base["max_throughput"],
            "enhanced_max_throughput": enhanced["max_throughput"],
            "max_throughput_delta": max_delta,
            "max_throughput_delta_pct": (max_delta / base["max_throughput"] * 100)
            if base["max_throughput"]
            else None,
            "baseline_collision_count": base["total_collision_count"],
            "enhanced_collision_count": enhanced["total_collision_count"],
            "collision_count_delta": enhanced["total_collision_count"]
            - base["total_collision_count"],
            "baseline_mean_avg_delay": base["mean_avg_delay"],
            "enhanced_mean_avg_delay": enhanced["mean_avg_delay"],
            "mean_avg_delay_delta": enhanced["mean_avg_delay"] - base["mean_avg_delay"],
            "baseline_capture_success_count": base["total_capture_success_count"],
            "enhanced_capture_success_count": enhanced["total_capture_success_count"],
            "capture_success_count_delta": enhanced["total_capture_success_count"]
            - base["total_capture_success_count"],
        }
    return {"by_protocol": by_protocol}


def result_rows(
    group_name: str, results: Dict[str, List[Dict[str, Any]]]
) -> List[Dict[str, Any]]:
    """将单组实验的曲线结果展开成表格行。

    每一行对应“实验组 + 协议 + 一个业务负载 G”的结果，供终端输出、
    Markdown 表格和后续 DataFrame 转换复用。
    """
    rows = []
    for protocol_name, protocol_results in results.items():
        for row in protocol_results:
            rows.append(
                {
                    "实验组": group_name,
                    "协议": protocol_name,
                    "业务负载(G)": row["G"],
                    "实际业务负载": row["traffic"],
                    "吞吐量": row["throughput"],
                    "总时间(秒)": row["total_time"],
                    "成功包数": row["success_packets"],
                    "冲突次数": row["collision_count"],
                    "平均等待时间": row["avg_delay"],
                    "捕获成功次数": row["capture_success_count"],
                }
            )
    return rows


def all_results_dataframe(simulation_data: Dict[str, Any]) -> pd.DataFrame:
    """将所有实验组的原始曲线结果合并为一个 DataFrame。"""
    rows = []
    for group_name, experiment in simulation_data["experiments"].items():
        rows.extend(result_rows(group_name, experiment["results"]))
    return pd.DataFrame(rows)


def statistics_dataframe(simulation_data: Dict[str, Any]) -> pd.DataFrame:
    """将 baseline/enhanced 的统计指标整理成 DataFrame。"""
    rows = []
    for group_name, experiment in simulation_data["experiments"].items():
        for protocol_name, stats in experiment["statistics"].items():
            rows.append(
                {
                    "实验组": group_name,
                    "协议": protocol_name,
                    "平均吞吐量": stats["avg_throughput"],
                    "最大吞吐量": stats["max_throughput"],
                    "最小吞吐量": stats["min_throughput"],
                    "吞吐量标准差": stats["std_throughput"],
                    "最佳G": stats["best_G"],
                    "最佳实际业务负载": stats["best_traffic"],
                    "冲突次数": stats["total_collision_count"],
                    "平均等待时间": stats["mean_avg_delay"],
                    "捕获成功次数": stats["total_capture_success_count"],
                }
            )
    return pd.DataFrame(rows)


def comparison_dataframe(simulation_data: Dict[str, Any]) -> pd.DataFrame:
    """将 baseline 与 enhanced 的差值指标整理成 DataFrame。"""
    rows = []
    for protocol_name, comparison in simulation_data["comparison"][
        "by_protocol"
    ].items():
        rows.append(
            {
                "协议": protocol_name,
                "baseline最大吞吐量": comparison["baseline_max_throughput"],
                "enhanced最大吞吐量": comparison["enhanced_max_throughput"],
                "最大吞吐量差值": comparison["max_throughput_delta"],
                "最大吞吐量变化(%)": comparison["max_throughput_delta_pct"],
                "baseline冲突次数": comparison["baseline_collision_count"],
                "enhanced冲突次数": comparison["enhanced_collision_count"],
                "冲突次数差值": comparison["collision_count_delta"],
                "baseline平均等待时间": comparison["baseline_mean_avg_delay"],
                "enhanced平均等待时间": comparison["enhanced_mean_avg_delay"],
                "平均等待时间差值": comparison["mean_avg_delay_delta"],
                "baseline捕获成功次数": comparison["baseline_capture_success_count"],
                "enhanced捕获成功次数": comparison["enhanced_capture_success_count"],
                "捕获成功次数差值": comparison["capture_success_count_delta"],
            }
        )
    return pd.DataFrame(rows)


def format_number(value: Any) -> str:
    """统一终端和 Markdown 表格中的数字显示格式。"""
    if value is None:
        return ""
    if isinstance(value, (bool, np.bool_)):
        return str(bool(value))
    if isinstance(value, (int, np.integer)):
        return str(int(value))
    if isinstance(value, (float, np.floating)):
        return f"{float(value):.6f}"
    return str(value)


def format_table_value(header: str, value: Any) -> str:
    """按列名决定表格单元格格式。

    计数字段必须显示为整数；吞吐量、时间等连续值保留小数。
    """
    integer_columns = {"成功包数", "冲突次数", "捕获成功次数", "Mnum", "spend"}
    if header in integer_columns and value is not None:
        return str(int(round(float(value))))
    return format_number(value)


def markdown_table(headers: List[str], rows: List[List[Any]]) -> str:
    """根据表头和二维数据生成 GitHub 风格 Markdown 表格。"""
    output = [
        "| " + " | ".join(headers) + " |",
        "| " + " | ".join(["---"] * len(headers)) + " |",
    ]
    for row in rows:
        output.append(
            "| "
            + " | ".join(
                format_table_value(header, item) for header, item in zip(headers, row)
            )
            + " |"
        )
    return "\n".join(output)


def dataframe_to_markdown(df: pd.DataFrame) -> str:
    """将 DataFrame 转换为 Markdown 表格字符串。"""
    rows = df.values.tolist()
    return markdown_table(list(df.columns), rows)


def aloha_theory_curve(protocol_name: str, g_values: np.ndarray):
    """返回 ALOHA 协议的经典理论吞吐量曲线。

    np-CSMA 没有直接对应的 ALOHA 理论参考曲线，因此返回 None。
    """
    if protocol_name == "Pure ALOHA":
        return g_values * np.exp(-2 * g_values), r"理论值 $S=Ge^{-2G}$"
    if protocol_name == "Slotted ALOHA":
        return g_values * np.exp(-g_values), r"理论值 $S=Ge^{-G}$"
    return None


def print_dataframe(title: str, df: pd.DataFrame):
    """在终端打印一个带标题的 DataFrame。

    终端输出与 Markdown/JSON 使用同一批数据源，避免不同输出之间出现口径差异。
    """
    print(f"\n{title}")
    print("-" * len(title))
    if df.empty:
        print("(无数据)")
        return
    print(
        df.to_string(
            index=False,
            formatters={
                col: format_number for col in df.columns if df[col].dtype.kind in "fiu"
            },
        )
    )


def plot_single_group_figures(
    simulation_data: Dict[str, Any], figures_dir: Path
) -> List[str]:
    """绘制每个实验组、每个协议的单独吞吐量-负载曲线。

    输出数量为 2 组实验 x 3 种协议，共 6 张图。每张图只绘制一个实验组下
    一个 MAC 协议的仿真结果；Pure ALOHA 和 Slotted ALOHA 额外叠加对应的
    经典理论吞吐量曲线，np-CSMA 不叠加 ALOHA 理论曲线。
    """
    simulation_color = "#2563EB"
    theory_color = "#4B5563"
    figure_paths = []
    for group_name, experiment in simulation_data["experiments"].items():
        for protocol_name, results in experiment["results"].items():
            df = pd.DataFrame(results)
            fig, ax = plt.subplots(figsize=(9, 6))
            ax.plot(
                df["G"],
                df["throughput"],
                color=simulation_color,
                marker="o",
                linestyle="-",
                linewidth=2.2,
                markersize=5.5,
                label="仿真结果",
            )
            theory_g = np.linspace(0, 2.2, 300)
            theory_curve = aloha_theory_curve(protocol_name, theory_g)
            if theory_curve is not None:
                theory_s, theory_label = theory_curve
                ax.plot(
                    theory_g,
                    theory_s,
                    color=theory_color,
                    linestyle="--",
                    linewidth=2.0,
                    label=theory_label,
                )
            ax.set_title(f"{group_name} - {protocol_name} 吞吐量-负载曲线")
            ax.set_xlabel("业务负载 G")
            ax.set_ylabel("吞吐量 S")
            ax.set_xlim(0, 2.2)
            ax.set_ylim(0, 0.8)
            ax.legend()
            fig.tight_layout()
            output_path = (
                figures_dir / f"{group_name}_{protocol_file_name(protocol_name)}.png"
            )
            fig.savefig(output_path, dpi=300, bbox_inches="tight")
            plt.close(fig)
            figure_paths.append(str(output_path))
    return figure_paths


def plot_protocol_comparison_figures(
    simulation_data: Dict[str, Any], figures_dir: Path
) -> List[str]:
    """绘制每个协议的 baseline vs enhanced 对比曲线。

    输出数量为 3 张图，每张图只比较一种协议在两组实验中的吞吐量变化。
    """
    figure_paths = []
    for protocol_name in simulation_data["metadata"]["protocols"]:
        rows = []
        for group_name, experiment in simulation_data["experiments"].items():
            for result in experiment["results"][protocol_name]:
                rows.append(
                    {
                        "实验组": group_name,
                        "业务负载 G": result["G"],
                        "吞吐量 S": result["throughput"],
                    }
                )
        df = pd.DataFrame(rows)
        fig, ax = plt.subplots(figsize=(9, 6))
        sns.lineplot(
            data=df,
            x="业务负载 G",
            y="吞吐量 S",
            hue="实验组",
            style="实验组",
            markers=True,
            dashes=False,
            linewidth=2.2,
            ax=ax,
        )
        ax.set_title(f"{protocol_name} baseline vs enhanced 吞吐量-负载曲线")
        ax.set_xlim(0, 2.2)
        ax.set_ylim(0, 0.8)
        fig.tight_layout()
        output_path = (
            figures_dir
            / f"compare_{protocol_file_name(protocol_name)}_baseline_vs_enhanced.png"
        )
        fig.savefig(output_path, dpi=300, bbox_inches="tight")
        plt.close(fig)
        figure_paths.append(str(output_path))
    return figure_paths


def plot_all_protocols_comparison(
    simulation_data: Dict[str, Any], figures_dir: Path
) -> str:
    """将三种协议、两组实验的吞吐量曲线绘制到同一张图中。

    该图用于报告中的总览对比：颜色区分协议，线型/标记区分实验组。
    """
    rows = []
    for group_name, experiment in simulation_data["experiments"].items():
        for protocol_name, results in experiment["results"].items():
            for result in results:
                rows.append(
                    {
                        "实验组": group_name,
                        "协议": protocol_name,
                        "业务负载 G": result["G"],
                        "吞吐量 S": result["throughput"],
                    }
                )
    df = pd.DataFrame(rows)
    fig, ax = plt.subplots(figsize=(11, 7))
    sns.lineplot(
        data=df,
        x="业务负载 G",
        y="吞吐量 S",
        hue="协议",
        style="实验组",
        markers=True,
        linewidth=2.0,
        ax=ax,
    )
    ax.set_title("baseline vs enhanced 吞吐量-负载曲线")
    ax.set_xlim(0, 2.2)
    ax.set_ylim(0, 0.8)
    fig.tight_layout()
    output_path = figures_dir / "compare_all_protocols_baseline_vs_enhanced.png"
    fig.savefig(output_path, dpi=300, bbox_inches="tight")
    plt.close(fig)
    return str(output_path)


def plot_statistics_bar(simulation_data: Dict[str, Any], figures_dir: Path) -> str:
    """绘制统计指标分组柱状图。

    三个子图分别展示最大吞吐量、冲突次数和平均等待时间；
    每个子图中按协议分组，并用 hue 区分 baseline 与 enhanced。
    """
    stats_df = statistics_dataframe(simulation_data)
    metrics = [
        ("最大吞吐量", "最大吞吐量"),
        ("冲突次数", "冲突次数"),
        ("平均等待时间", "平均等待时间"),
    ]
    fig, axes = plt.subplots(1, 3, figsize=(16, 5))
    for ax, (column, title) in zip(axes, metrics):
        sns.barplot(data=stats_df, x="协议", y=column, hue="实验组", ax=ax)
        ax.set_title(title)
        ax.set_xlabel("协议")
        ax.set_ylabel(title)
        ax.tick_params(axis="x", rotation=15)
    fig.suptitle("统计指标对比")
    fig.tight_layout()
    output_path = figures_dir / "compare_statistics_bar.png"
    fig.savefig(output_path, dpi=300, bbox_inches="tight")
    plt.close(fig)
    return str(output_path)


def generate_figures(simulation_data: Dict[str, Any], output_dir: Path) -> List[str]:
    """生成报告要求的全部图像，并返回相对输出目录的路径列表。"""
    figures_dir = output_dir / "figures"
    figures_dir.mkdir(parents=True, exist_ok=True)
    figure_paths = []
    figure_paths.extend(plot_single_group_figures(simulation_data, figures_dir))
    figure_paths.extend(plot_protocol_comparison_figures(simulation_data, figures_dir))
    figure_paths.append(plot_all_protocols_comparison(simulation_data, figures_dir))
    figure_paths.append(plot_statistics_bar(simulation_data, figures_dir))
    return [str(Path(path).relative_to(output_dir)) for path in figure_paths]


def write_json_report(simulation_data: Dict[str, Any], output_dir: Path):
    """写出完整 JSON 结果。

    JSON 保留原始曲线、统计指标、对比指标、配置和图片路径，适合后续二次分析。
    """
    output_path = output_dir / "simulation_results.json"
    output_path.write_text(
        json.dumps(to_jsonable(simulation_data), ensure_ascii=False, indent=2),
        encoding="utf-8",
    )


def write_markdown_report(simulation_data: Dict[str, Any], output_dir: Path):
    """写出 Markdown 结果报告。

    Markdown 按一级标题区分 Baseline、Enhanced、Baseline vs Enhanced 和 Figures，
    按二级标题区分参数、协议结果、统计指标和对比表，便于直接复制到实验报告。
    """
    lines = [
        "# 仿真实验结果",
        "",
        f"生成时间：{simulation_data['metadata']['generated_at']}",
        "",
    ]
    for group_title, group_name in [("Baseline", "baseline"), ("Enhanced", "enhanced")]:
        experiment = simulation_data["experiments"][group_name]
        lines.extend([f"# {group_title}", "", "## 参数设置", ""])
        config_rows = [[key, value] for key, value in experiment["config"].items()]
        lines.extend([markdown_table(["参数", "值"], config_rows), ""])
        for protocol_name, results in experiment["results"].items():
            lines.extend([f"## {protocol_name} Results", ""])
            df = pd.DataFrame(result_rows(group_name, {protocol_name: results})).drop(
                columns=["实验组", "协议"]
            )
            lines.extend([dataframe_to_markdown(df), ""])
        lines.extend(["## Statistics", ""])
        stats_rows = []
        for protocol_name, stats in experiment["statistics"].items():
            stats_rows.append(
                [
                    protocol_name,
                    stats["avg_throughput"],
                    stats["max_throughput"],
                    stats["best_G"],
                    stats["total_collision_count"],
                    stats["mean_avg_delay"],
                    stats["total_capture_success_count"],
                ]
            )
        lines.extend(
            [
                markdown_table(
                    [
                        "协议",
                        "平均吞吐量",
                        "最大吞吐量",
                        "最佳G",
                        "冲突次数",
                        "平均等待时间",
                        "捕获成功次数",
                    ],
                    stats_rows,
                ),
                "",
            ]
        )

    lines.extend(["# Baseline vs Enhanced", ""])
    comparison_df = comparison_dataframe(simulation_data)
    for protocol_name in simulation_data["metadata"]["protocols"]:
        lines.extend([f"## {protocol_name} 对比", ""])
        protocol_df = comparison_df[comparison_df["协议"] == protocol_name]
        lines.extend([dataframe_to_markdown(protocol_df), ""])
    lines.extend(["## 统计指标对比", "", dataframe_to_markdown(comparison_df), ""])
    lines.extend(["# Figures", ""])
    for figure in simulation_data["figures"]:
        lines.append(f"- {figure}")
    lines.append("")
    (output_dir / "simulation_report.md").write_text("\n".join(lines), encoding="utf-8")


def print_terminal_report(simulation_data: Dict[str, Any]):
    """在终端一次性输出 baseline、enhanced 和两组对比结果。"""
    print("\n" + "=" * 80)
    print("baseline 和 enhanced 仿真实验结果")
    print("=" * 80)
    for group_name in ["baseline", "enhanced"]:
        experiment = simulation_data["experiments"][group_name]
        print(f"\n# {group_name}")
        config_df = pd.DataFrame(
            [{"参数": key, "值": value} for key, value in experiment["config"].items()]
        )
        print_dataframe("参数设置", config_df)
        for protocol_name, results in experiment["results"].items():
            df = pd.DataFrame(result_rows(group_name, {protocol_name: results})).drop(
                columns=["实验组", "协议"]
            )
            print_dataframe(f"{protocol_name} Results", df)
        stats_df = statistics_dataframe({"experiments": {group_name: experiment}})
        print_dataframe(f"{group_name} Statistics", stats_df)

    print_dataframe("Baseline vs Enhanced 对比", comparison_dataframe(simulation_data))
    print("\n输出文件")
    print(f"- {simulation_data['metadata']['output_dir']}/simulation_results.json")
    print(f"- {simulation_data['metadata']['output_dir']}/simulation_report.md")
    for figure in simulation_data["figures"]:
        print(f"- {simulation_data['metadata']['output_dir']}/{figure}")


def main():
    """运行基线组和增强组两组对比实验。

    主函数负责命令行参数解析、随机种子设置、输出目录创建、两组实验执行、
    数据汇总、绘图和结果写出。具体协议行为由 WirelessNetworkSimulator 完成。
    """
    parser = argparse.ArgumentParser(description="无线随机接入协议仿真")
    parser.add_argument("--mnum", type=int, default=100, help="终端数量")
    parser.add_argument(
        "--spend", type=int, default=10000, help="每个业务负载下的成功包数"
    )
    parser.add_argument(
        "--output-root", type=Path, default=Path("outputs"), help="结果输出根目录"
    )
    parser.add_argument("--seed", type=int, default=None, help="随机种子")
    args = parser.parse_args()

    if args.seed is not None:
        random.seed(args.seed)
        np.random.seed(args.seed)

    setup_chinese_font()
    timestamp = time.strftime("%Y%m%d_%H%M%S")
    output_dir = args.output_root / timestamp
    output_dir.mkdir(parents=True, exist_ok=True)

    print("=" * 60)
    print("无线随机接入协议仿真：基线模型与增强模型对比")
    print("=" * 60)
    print(f"输出目录: {output_dir}")

    # baseline 和 enhanced 使用同一套 SINR 判决，区别在业务源、运动模型和信道衰落层次。
    experiment_groups = [
        # 基线组：原始泊松业务、静态终端、路径损耗 + 6 dB 阴影衰落。
        (
            "baseline",
            {
                "traffic_mode": "poisson",
                "mobility_model": "static",
                "channel_model": "log_distance",
                "shadow_std_db": 6.0,
            },
        ),
        # 增强组：混合突发业务、随机路点、路径损耗 + 6 dB 阴影衰落 + Rayleigh 快衰落。
        (
            "enhanced",
            {
                "traffic_mode": "mixed",
                "mobility_model": "random_waypoint",
                "channel_model": "rayleigh",
                "shadow_std_db": 6.0,
                "mobility_update_interval": 0.01,
            },
        ),
    ]

    simulation_data = {
        "metadata": {
            "generated_at": time.strftime("%Y-%m-%d %H:%M:%S"),
            "output_dir": str(output_dir),
            "protocols": ["Pure ALOHA", "Slotted ALOHA", "np-CSMA"],
            "Mnum": args.mnum,
            "spend": args.spend,
            "seed": args.seed,
        },
        "experiments": {},
        "comparison": {},
        "figures": [],
    }

    for group_name, config in experiment_groups:
        print(f"\n正在运行 {group_name} 实验")
        # 根据实验组配置创建仿真器，保持主流程一致，便于对比。
        simulator = WirelessNetworkSimulator(
            Mnum=args.mnum, spend=args.spend, result_prefix=group_name, **config
        )
        start_total_time = time.time()
        all_results = simulator.simulate_all_protocols()
        total_elapsed_time = time.time() - start_total_time
        print(f"{group_name} 实验完成，耗时: {total_elapsed_time:.2f} 秒")
        simulation_data["experiments"][group_name] = {
            "config": simulator.config_summary(),
            "elapsed_time": total_elapsed_time,
            "results": all_results,
            "statistics": compute_statistics(all_results),
        }

    simulation_data["comparison"] = build_comparison(simulation_data["experiments"])
    simulation_data["figures"] = generate_figures(simulation_data, output_dir)
    write_json_report(simulation_data, output_dir)
    write_markdown_report(simulation_data, output_dir)
    print_terminal_report(simulation_data)
    print("\n所有实验已完成。")


if __name__ == "__main__":
    main()