/**
 * @file    app_mppt.h
 * @brief   MPPT 模块 — P&O 扰动观察法
 *
 * 用于光伏板输入 (PV mode) 的最大功率点追踪。
 * DC 适配器模式下本模块不运行。
 *
 * 工作流程:
 *   1. MpptTask 每 10ms 读取 Vpv/Ipv
 *   2. 每 MPPT_PERIOD_DIV 次 (默认 ×50 = 500ms) 执行一次 P&O 扰动
 *   3. P&O 调整 vin_set, 输出给 PID 控制环 (在 charge.c 中)
 *   4. 定期做全面板扫描 (RESTART), 逃出局部最优
 *
 * 依赖:
 *   - BspCharge_GetVpv() / BspCharge_GetIpv() — 面板电压/电流 ADC 读数
 *   - BspCharge_SetVinRef() — 设置输入电压环的目标值 (mV)
 *   - charge.c 中的输入电压 PID 环跟踪 vin_set
 */

#ifndef __APP_MPPT_H
#define __APP_MPPT_H

#include <stdint.h>
#include <stdbool.h>

/*===========================================================================
 * 配置宏
 *===========================================================================*/

/** P&O 扰动步长 (mV) — 每次扰动改变 vin_set 的量 */
#define MPPT_PNO_STEP_MV      200

/** 扰动间隔 = MPPT_PERIOD_DIV × 任务周期 (默认 5 = 50ms) */
#define MPPT_PNO_PERIOD_MS    500

/** 全面板扫描周期 (ms) — 默认 10 分钟 */
#define MPPT_RESTART_PERIOD_MS  (10 * 60 * 1000)

/** 功率跌到历史最大值的百分比以下触发 restar — 0.85 = 85% */
#define MPPT_POWER_LOST_RATIO   85

/** 全扫描时电压范围的步长 (mV) */
#define MPPT_SWEEP_STEP_MV     500

/** 全扫描时每个电压点的稳定等待 (ms) */
#define MPPT_SWEEP_SETTLE_MS   100

/** 输入电压下限/上限 (mV) — 限幅保护 */
#define MPPT_VIN_MIN_MV        12000    /* 12V — 低于此值面板可能阴影 */
#define MPPT_VIN_MAX_MV        60000    /* 60V — 面板开路电压上限 */

/*===========================================================================
 * 运行模式
 *===========================================================================*/

typedef enum {
    MPPT_MODE_DISABLED = 0,    /* 未启用 (DC 适配器模式) */
    MPPT_MODE_TRACKING,        /* 正常 P&O 追踪 */
    MPPT_MODE_SWEEP,           /* 全扫描中 */
    MPPT_MODE_LOCKED,          /* 锁定最优点 (功率稳定, 减少扰动) */
} MpptMode;

/*===========================================================================
 * 状态数据结构
 *===========================================================================*/

typedef struct {
    /* 当前读数 */
    int32_t vpv_mv;            /* 面板电压 (mV) */
    int32_t ipv_ma;            /* 面板电流 (mA) */
    int32_t ppv_mw;            /* 面板功率 (mW) */

    /* P&O 追踪 */
    int32_t vin_ref_mv;        /* 当前输入电压目标值 (mV) — 输出给 PID */
    int8_t  pno_dir;           /* 扰动方向: +1 或 -1 */
    int32_t ppv_last_mw;       /* 上次扰动时的功率 */

    /* 历史最大功率点 */
    int32_t ppv_max_mw;        /* 历史最大功率 */
    int32_t vin_max_mw;        /* 最大功率时的电压 */

    /* 全扫描 */
    int32_t sweep_vin_start;   /* 扫描起点 */
    int32_t sweep_vin_end;     /* 扫描终点 */
    int32_t sweep_vin_cur;     /* 当前扫描到的电压 */
    int32_t sweep_ppv_max;     /* 扫描过程中最大功率 */
    int32_t sweep_vin_best;    /* 扫描过程中最优点电压 */

    /* 模式 & 计时 */
    MpptMode mode;
    uint32_t pno_timer_ms;     /* P&O 间隔计时 */
    uint32_t restart_timer_ms; /* 全扫描周期计时 */

    /* 统计 */
    uint32_t pno_count;        /* P&O 执行次数 */
    uint32_t restart_count;    /* 全扫描次数 */
} MpptState;

/*===========================================================================
 * 接口函数
 *===========================================================================*/

/**
 * @brief  初始化 MPPT 模块
 * @return 0=成功, -1=失败
 */
int Mppt_Init(void);

/**
 * @brief  获取当前输入电压目标值
 * @return 输入电压目标值 (mV)
 */
int32_t Mppt_GetVinRef(void);

/**
 * @brief  设置 MPPT 模式 — 切换输入源时调用
 * @param  enable  true=PV模式启用MPPT, false=DC模式停用MPPT
 */
void Mppt_SetEnable(bool enable);

/**
 * @brief  获取当前 MPPT 状态 (调试用)
 */
void Mppt_GetStatus(MpptState *out);

/**
 * @brief  MPPT 调度函数 — 每个控制周期调用一次
 *
 * 由 ChargeTask 内部控制循环调用。
 * 内部自动处理 P&O 扰动间隔、全扫描时序。
 */
void Mppt_Scheduler(void);

#endif /* __APP_MPPT_H */