#ifndef DEVICE_ADC_H
#define DEVICE_ADC_H

#include <stdint.h>

/**
 * @brief ADC 采样模块。
 * @note 负责 VIN_ADC、内部温度与内部参考电压的 DMA 扫描采样与工程值换算。
 */
class Adc {
public:
    /**
     * @brief ADC 采样结果结构体。
     * @note 保存外部 VIN_ADC、内部温度与内部参考电压的原始值，以及可直接使用的工程值。
     */
    struct Sample {
        uint16_t vin_raw;     /**< 外部 VIN_ADC（PA6）原始 ADC 数值。 */
        uint16_t temp_raw;    /**< 内部温度通道原始 ADC 数值。 */
        uint16_t vref_raw;    /**< 内部参考电压通道原始 ADC 数值。 */
        float    vin_adc_v;   /**< VIN_ADC 引脚处电压（分压后的 ADC 端电压），单位 V。 */
        float    vdda;        /**< 根据内部参考电压换算得到的 MCU 供电电压，单位 V。 */
        float    temperature; /**< 根据温度通道换算得到的芯片温度，单位 ℃。 */
        uint8_t  valid;       /**< 采样是否有效：1=有效，0=存在原始值/换算异常。 */
    };

    /** init 故障码（0=成功；经 0xA3 INIT_STATUS fault_codes[] 上报，网页解码文字见 initial.h 注释） */
    enum InitFault : uint8_t {
        kFaultOk            = 0U, /**< 成功 */
        kFaultCalRstTimeout = 1U, /**< 校准复位（RSTCLB）等待超时，ADC 硬件无响应 */
        kFaultCalTimeout    = 2U, /**< 校准（CLB）等待超时 */
        kFaultVddaInvalid   = 3U, /**< 校准后 VREFINT→VDDA 采样链无效（DMA/通道/供电异常） */
    };

    /**
     * @brief 初始化 ADC 硬件、扫描通道与 DMA 循环缓存。
     * @param[in]  无。
     * @param[out] 无。
     * @retval uint8_t InitFault 故障码（0=校准完成且 VDDA 采样链有效）。
     * @note      完成 ADC 三通道扫描、DMA 循环搬运、PA6(VIN_ADC) 模拟输入配置以及内部通道校准。
     */
    static uint8_t init();

    /**
     * @brief 读取指定通道在 DMA 缓存中的原始 ADC 值。
     * @param[in] channel 目标 ADC 通道号。
     * @param[out] 无。
     * @retval uint16_t 对应通道原始值；不受支持的通道返回 0。
     */
    static uint16_t readRaw(uint8_t channel);

    /**
     * @brief 读取外部 VIN_ADC（PA6）通道原始值。
     * @param[in]  无。
     * @param[out] 无。
     * @retval uint16_t VIN_ADC 原始 ADC 数值。
     */
    static uint16_t readVinRaw();

    /**
     * @brief 读取内部参考电压原始值。
     * @param[in]  无。
     * @param[out] 无。
     * @retval uint16_t 内部 VREFINT 通道原始 ADC 数值。
     */
    static uint16_t readVrefRaw();

    /**
     * @brief 读取内部温度通道原始值。
     * @param[in]  无。
     * @param[out] 无。
     * @retval uint16_t 内部温度通道原始 ADC 数值。
     */
    static uint16_t readTempRaw();

    /**
     * @brief 根据 VIN_ADC 原始值与 VDDA 计算 ADC 引脚处电压。
     * @param[in]  vinRaw VIN_ADC 通道原始 ADC 数值。
     * @param[in]  vdda   当前 MCU 供电电压，单位 V。
     * @param[out] 无。
     * @retval float VIN_ADC 引脚电压，单位 V。
     * @note      当前仅计算分压后的 ADC 端电压；若需换算输入母线电压，需要补充完整分压比。
     */
    static float calculateVinAdcVoltage(uint16_t vinRaw, float vdda);

    /**
     * @brief 根据内部参考电压原始值计算 VDDA。
     * @param[in]  vrefRaw 内部 VREFINT 通道原始 ADC 数值。
     * @param[out] 无。
     * @retval float 换算得到的 MCU 供电电压，单位 V。
     * @note      当 vrefRaw 为 0 时返回默认值 VDDA，避免除零异常。
     */
    static float calculateVdda(uint16_t vrefRaw);

    /**
     * @brief 根据温度原始值与 VDDA 计算芯片温度。
     * @param[in]  tempRaw 内部温度通道原始 ADC 数值。
     * @param[in]  vdda    当前 MCU 供电电压，单位 V。
     * @param[out] 无。
     * @retval float 换算得到的芯片温度，单位 ℃。
     */
    static float calculateTemperature(uint16_t tempRaw, float vdda);

    /**
     * @brief 采集一组完整 ADC 样本并完成工程值换算。
     * @param[in]  sample 指向输出 Sample 的指针；允许为空。
     * @param[out] sample 当指针非空时，写入 VIN/温度/VREF 原始值与换算结果。
     * @retval    无返回值。
     * @note      当 sample 为 nullptr 时直接返回，不执行写操作。
     */
    static void collectSample(Sample *sample);

private:
    /**
     * @brief 初始化 ADC DMA 通道配置。
     * @param[in]  无。
     * @param[out] 无。
     * @retval    无返回值。
     */
    static void initDma();
};

#endif /* DEVICE_ADC_H */