/**
 * @file Algorithm/pid.h
 * @brief 算法模块源文件
 * @note 本文件仅补充 Doxygen 文档注释，不改变代码逻辑。
 */

#ifndef PID_H
#define PID_H

/**
 * @brief PIDController 类或结构体
 */
class PIDController {
  public:
	PIDController(float P, float I, float D, float ramp, float limit);
	~PIDController() = default;

	/**
	 * @brief PID 计算（唯一入口）
	 * @param[in] error 控制误差
	 * @param[in] measurement 反馈测量量（D 项对它微分，目标阶跃不产生微分踢）
	 * @return float PID 输出
	 */
	float operator()(float error, float measurement);
	/**
	 * @brief 设置 set_PID 对应的参数
	 * @param[in] P 参数
	 * @param[in] I 参数
	 * @param[in] D 参数
	 * @return void
	 */
	void set_PID(float P, float I, float D);
	/**
	 * @brief 设置 set_P 对应的参数
	 * @param[in] pp 参数
	 * @return void
	 */
	void set_P(float pp);
	/**
	 * @brief 设置 set_limit 对应的参数
	 * @param[in] limit 参数
	 * @return void
	 */
	void set_limit(float limit);
	/**
	 * @brief 复位对象内部状态
	 * @return void
	 */
	void reset();  // 重置PID控制器状态
	/**
	 * @brief reset_integral 函数
	 * @return void
	 */
	void reset_integral(); // 仅清除积分项，保留输出斜坡状态
	/**
	 * @brief 外部饱和泄放积分（反算抗饱和的补充入口）
	 * @param[in] excess 输出超出限幅的部分（带符号），如前馈叠加后超限
	 * @return void
	 * @note 调用方向须与 PID 输出到最终 Uq 的符号一致（有 ×DIR 的要乘上 DIR）
	 */
	void bleed_integral(float excess);

	float P; //!< 比例增益(P环增益)
	float I; //!< 积分增益（I环增益）
	float D; //!< 微分增益（D环增益）
	float output_ramp;
	float limit;

  protected:
	/**
	 * @brief 公共计算路径：积分、抗饱和、输出斜坡
	 * @param[in] error 控制误差
	 * @param[in] derivative 已完成低通滤波的微分项（D 已乘入）
	 * @return float PID 输出
	 */
	float step(float error, float derivative);

	float error_prev;			  //!< 最后的跟踪误差值
	float output_prev;			  //!< 最后一个 pid 输出值
	float integral_prev;		  //!< 最后一个积分分量值
	float measurement_prev;		  //!< 上次测量值（对测量微分用）
	float derivative_filt;		  //!< 微分项一阶低通滤波后的变化率
	bool deriv_init;			  //!< 测量微分是否已完成首次采样
};

#endif