# 探测器信号模拟器需求文档

## 1. 时间戳处理

### 1.1 时间戳单位转换
- **需求描述**：同步脉冲时间单位为10ns，需转换为微秒
- **实现方式**：`pulse_start_time_us = pulse_start_time / 100` (10ns = 0.01us)
- **状态**：✅ 已完成
- **代码位置**：`core/simulator.py` 第563行

### 1.2 时间戳非负整数
- **需求描述**：确保时间戳为非负整数
- **实现方式**：`timestamp_us = max(0, int(timestamp_us))`
- **状态**：✅ 已完成

---

## 2. 调试文件格式

### 2.1 事件分隔
- **需求描述**：通过64位整数最高位判断事件结束（bit63=1表示事件最后一个信号）
- **实现方式**：在`encode_time_series`中对每个事件的最后一个信号调用`set_event_end_flag`
- **状态**：✅ 已完成
- **代码位置**：`core/simulator.py` 第834行

### 2.2 调试文件内容格式
- **需求描述**：包含事件分隔、信号序号、十六进制编码和解析结果
- **状态**：✅ 已完成

### 2.3 过滤能量为0的探测器
- **需求描述**：调试文件中不显示能量为0的探测器信息
- **状态**：✅ 已完成

### 2.4 数据包统计信息
- **需求描述**：按事件分隔信号，显示数据包统计信息（总信号数、总事件数、数据包数量）
- **状态**：✅ 已完成

### 2.5 输出文件格式优化
- **需求描述**：
  - 在debug.txt输出文件中，不再单独打印类似"# 事件 0 "的信息
  - 输出文件（包括bin、txt、debug文件）中，每8个信号为一组
  - 每组内部按照倒序的方式排列
  - debug文件中，事件ID应能反映信号分组规律
  - 两组信号之间空一行
- **实现方式**：
  - 修改`write_events_debug_text`方法，移除单独的事件信息行
  - 实现每8个信号为一组的处理逻辑
  - 每组内从后往前处理信号（倒序）
  - 组间添加空行
- **状态**：✅ 已完成
- **代码位置**：`core/data_writer.py` 第687-756行和第1042-1110行

---

## 3. 同步脉冲与事件关联

### 3.1 事件数量计算
- **需求描述**：每个同步脉冲对应一个事件
- **示例**：CO模式下同步脉冲1（475个）、脉冲2（20个）、脉冲3（1个），期望生成496个事件
- **状态**：✅ 已完成

### 3.2 时间序列总时长计算
- **需求描述**：验证时间序列总时长计算正确性
- **实现方式**：串行计算所有脉冲序列的总时间
  ```python
  total_duration = (
      pulse1_count * pulse1_period +
      pulse2_count * pulse2_period +
      pulse3_count * pulse3_period +
      pulse4_count * pulse4_period
  )
  ```
- **状态**：✅ 已完成
- **代码位置**：`core/simulator.py` 第550-554行

### 3.3 时间窗口过滤
- **需求描述**：时间戳超出同步脉冲时间范围的样本需丢弃
- **实现方式**：检查`sample_time_us <= max_time_us`
- **状态**：✅ 已完成
- **代码位置**：`core/simulator.py` 第577行

---

## 4. 概率分布

### 4.1 补充分布类型
- **需求描述**：在样本空间生成中增加gamma、poisson、lognormal分布
- **实现方式**：在`SampleSpaceGenerator.generate_from_distribution`中添加相应分支
- **状态**：✅ 已完成
- **代码位置**：`core/simulator.py`

### 4.2 常量分布
- **需求描述**：添加常数分布（constant）
- **状态**：✅ 已完成

---

## 5. 抽样逻辑

### 5.1 按同步脉冲配置信号数 ✅ 已完成
- **需求描述**：
  - 在每个同步脉冲配置下，为3个探测器分别设置最小信号数和最大信号数
  - 例如：同步脉冲1（475个，160微秒）下，探测器1/2/3各有独立的min/max信号数配置
- **UI布局**：
  - 同步脉冲1 个数: [输入框]  周期(10ns): [输入框]
    探测器1 [min] - [max]  探测器2 [min] - [max]  探测器3 [min] - [max]
  - 同步脉冲2 个数: [输入框]  周期(10ns): [输入框]
    探测器1 [min] - [max]  探测器2 [min] - [max]  探测器3 [min] - [max]
  - 同步脉冲3 个数: [输入框]  周期(10ns): [输入框]
    探测器1 [min] - [max]  探测器2 [min] - [max]  探测器3 [min] - [max]
  - 同步脉冲4 个数: [输入框]  周期(10ns): [输入框]
    探测器1 [min] - [max]  探测器2 [min] - [max]  探测器3 [min] - [max]
- **实现方式**：
  - 每个同步脉冲的信号数配置直接放在对应同步脉冲的个数和周期设置下方
  - 采用紧凑布局，探测器信号数配置与同步脉冲设置在同一框架内
- **状态**：✅ 已完成
- **代码位置**：`gui/tabs/main_config.py` 第206-340行

### 5.2 信号排序
- **需求描述**：在同一个事件中，每个探测器信号各自独立按时间戳从小到大排序后再合并
- **实现方式**：`time_series[det_name].sort(key=lambda x: x[0])`
- **状态**：✅ 已完成
- **代码位置**：`core/simulator.py` 第630行

---

## 6. 能量转换

### 6.1 能量单位转换
- **需求描述**：将keV转换为mV，通过系数K和B
- **实现方式**：`energy_mv = int(energy_kev * self.energy_K + self.energy_B)`
- **状态**：✅ 已完成

### 6.2 能量非负
- **需求描述**：确保能量为非负整数
- **实现方式**：`energy_mv = max(0, energy_mv)`
- **状态**：✅ 已完成

---

## 7. UI界面

### 7.1 参数配置
- **需求描述**：修复"每探测器信号数"参数配置报错问题
- **实现方式**：将IntVar改为StringVar，添加异常处理
- **状态**：✅ 已完成
- **代码位置**：`gui/tabs/main_config.py`

### 7.2 删除随机模式参数区域 ✅ 已完成
- **需求描述**：删除基本设置中的"随机模式参数"整个区域（包括最小/最大信号数设置）
- **原因**：信号数配置已移到同步脉冲配置区域
- **状态**：✅ 已完成
- **代码位置**：`gui/tabs/main_config.py` 第159-213行已删除

### 7.3 滚动条控制
- **需求描述**：左侧面板滚动条显示/隐藏控制
- **状态**：✅ 已完成

---

## 8. 数据打包

### 8.1 数据包格式
- **需求描述**：每包800个信号+2字节CRC
- **状态**：✅ 已完成

### 8.2 DDR地址计算
- **需求描述**：DDR终止地址必须是800的整数倍
- **实现方式**：`ddr_end_addr = (total_data_bytes // 800) * 800`
- **状态**：✅ 已完成

---

## 9. 指令配置

### 9.1 信号类型选择
- **需求描述**：信号类型有两种选择（0x70电压信号、0x07电流信号）
- **状态**：✅ 已完成

### 9.2 DDR地址十六进制显示
- **需求描述**：DDR起始地址和终止地址用16进制表示（0x格式）
- **状态**：✅ 已完成

---

## 10. 硬件控制

### 10.1 自动连接设备
- **需求描述**：启动程序时自动连接硬件设备
- **状态**：✅ 已完成

### 10.2 超时设置
- **需求描述**：连接超时时间设为100或500毫秒
- **状态**：✅ 已完成

### 10.3 配置文件保存
- **需求描述**：记住上次程序关闭时的配置信息
- **状态**：✅ 已完成

### 10.4 清除DDR内存
- **需求描述**：添加清除DDR内存按钮
- **状态**：✅ 已完成

---

## 11. 待实现需求

### 11.1 进度更新机制
- **需求描述**：在状态栏提示时间序列生成的进度和状态信息
- **优先级**：中
- **状态**：⏳ 待实现

---

## 工作流程

1. **需求变更流程**：
   - 用户提出新需求或修改需求
   - 更新本文档，标注状态为"待实现"
   - 等待用户确认需求文档
   - 确认后开始实现代码
   - 实现完成后更新状态为"已完成"

2. **代码修改原则**：
   - 修改代码前必须先更新需求文档
   - 确认需求文档后再动代码
   - 避免改错之前已经正确的地方
   - 每次修改后更新对应需求的状态

---

## 版本历史

- **v1.0** (2026-03-10): 初始版本，整理所有已完成和待实现的需求