raman/ISSUES.md

已知问题

ISSUE-001：设置光谱仪模拟增益后，采集停在 98% 并出现设备掉线

• 记录日期：2026-09-14
• 状态：已临时规避，根因及正式修复待确认。
• 验证结果：用户反馈，屏蔽模拟增益设置代码后问题不再出现，确认该设置调用是当前故障的重点关联因素。尚未确认 SDK 内部故障机制。

运行环境与触发场景

• Windows，桌面应用以 win-x86、真实硬件模式运行，使用 SeaSDK.dll。
• 同时使用两台光谱仪：NIRPRO（JEBI40090347）和 XS11639（LCAI40090258）。
• 荧光与近红外吸收共用 NIRPRO；可见光吸收使用 XS11639。
• 荧光模块配置 InternalAnalogGainLevel=1，近红外吸收配置为 0。
• 从荧光采集切换到近红外吸收时，对同一台 NIRPRO 下发增益从 1 到 0 的设置，随后读取光谱出现阻塞。
• 此处“模拟增益”指 Analog Gain，不是 Mock/模拟设备模式。

故障日志与现象

2026-09-14 的故障运行日志显示：

1. 16:52:08 前，NIRPRO 的荧光采集正常完成，返回 512 点。
2. 16:52:08，近红外吸收阶段设置增益为 0；设置调用返回后，GetFormattedSpectrum 读取阻塞。
3. 16:52:40，约 32 秒后返回 Sea SDK error 6；项目定义为 TransferError。
4. 界面显示采集停在 98%，用户报告光谱仪卡住、掉线。98% 是按预计时间计算的进度上限，不是设备报告的真实进度。
5. 自动重连仍使用 nativeIndex=0，日志标记原设备序列号，但像素数变为 2048。尚不能确定是设备索引变化还是 SDK 状态异常，不应将其视为原设备已正确恢复的证据。

原始日志位于 src/RamanApp/bin/Debug/net9.0/win-x86/startup.log，每次重启会覆盖；以上时间线已摘录保存。

当前临时规避

• 文件：src/RamanApp/Services/SeaSpectrometerAdapter.cs。
• 将 InternalAnalogGainWritesEnabled 设为 false。
• ApplyInternalAnalogGainIfNeededAsync 提前返回，不调用 SetInternalAnalogGainAsync，并记录诊断禁用日志。
• 正常采集及重连后的增益设置均被屏蔽。
• 屏蔽范围是桌面应用中经该适配器访问的所有 SeaSDK 光谱仪，不仅是 NIRPRO 的 1 到 0 切换。
• 不修改原有配置，不改变积分时间、平均次数等设置；继续使用真实硬件模式。

限制与注意事项

• 这是禁用增益写入，不是把实际硬件增益固定为 1；硬件当前增益未核实。
• 界面、配置及结果元数据中的增益仍可能是请求值，不能据此认定硬件已应用该增益。
• 屏蔽后采集仅用于故障对照；正式测量前应确认实际增益，并重新验证暗谱、参考谱与样品采集条件的一致性。
• 本次验证禁用了全部增益写入，尚未单独区分首次设置、重复设置和 1 到 0 切换各自的影响。

后续处理

• 核对厂商接口定义、调用约定和适用型号，确认当前 SetInternalAnalogGainAsync 封装是否正确。
• 确认采集间切换增益是否需要停止采集、等待稳定、确认状态或重初始化。
• 在受控条件下分别验证不设置增益、首次设置、相同值重复设置、1 到 0 和 0 到 1 切换。
• 重连后核对真实序列号、型号及像素数，禁止仅凭旧 nativeIndex 接收数据。
• 修正读取阻塞时的进度提示、取消和故障状态，避免失败后仍报告已连接。
• 正式修复通过双光谱仪连续采集、模式切换与异常恢复验证后，再启用增益写入。

恢复入口：将 InternalAnalogGainWritesEnabled 改为 true，然后调用 .\restart.bat 重新编译启动；未经验证不要直接恢复用于正式测量。