PlateRecApp/src/weight_scale.h

/**
 * weight_scale.h — 称重系统模块（fix20完整实现）
 * 从 plate_log2mqtt.cpp 完整迁移 F1-F12 功能
 * 包括：耀华仪表TCP通信、稳定读数检测、称重数据上报平台
 */
#ifndef WEIGHT_SCALE_H
#define WEIGHT_SCALE_H
#include "common.h"
#include <string>

/**
 * 初始化称重系统（启动TCP客户端线程连接称重仪表）
 * @return true=初始化成功, false=未启用或失败
 */
bool weight_scale_init();

/**
 * 读取当前称重数据（阻塞等待稳定读数）
 * @param weight_kg 输出：重量(kg)
 * @param timeout_sec 超时秒数（实际使用g_weight_detection_time）
 * @return true=读取成功, false=超时或失败
 */
bool weight_scale_read(double& weight_kg, int timeout_sec);

/**
 * fix24 v43 Bug#18: 快照优先读取称重数据
 * 先检查采样池中近 max_age_sec 秒内是否已有稳定读数（车辆上秤后
 * TCP采集线程持续收数，识别+建单完成时往往已稳定），命中则直接返回；
 * 未命中则清空采样池并阻塞等待 g_weight_detection_time 秒。
 * 解决出站空车过秤快、清空后等不到稳定读数导致"未获取有效重量"的竞态。
 *
 * @param weight_kg   输出：重量(kg)
 * @param threshold_kg 最小有效重量阈值(kg)，低于此值视为无效
 * @param max_age_sec 快照最大年龄(秒)，仅接受此时长内采集的稳定样本
 * @return true=读取成功, false=超时或失败
 */
bool weight_scale_read_snapshot(double& weight_kg, double threshold_kg, int max_age_sec);

/**
 * fix24 v44 P0: 预检测锁定读取（最快路径，0等待）
 * 检查 TCP 线程是否已提前锁定稳定重量（车辆上秤后重量 > PRELOCK_THRESHOLD_KG
 * 且连续稳定），命中则直接返回并消费锁定值。
 * 仅适用于地磅场景（整车一次性上秤，无半上秤误判）。
 *
 * @param weight_kg    输出：重量(kg)
 * @param threshold_kg 最小有效重量阈值(kg)，低于此值视为无效
 * @return true=预锁定命中, false=无锁定值（需走快照/阻塞等待）
 */
bool weight_scale_read_prelocked(double& weight_kg, double threshold_kg);

/**
 * 关闭称重系统（停止TCP线程）
 */
void weight_scale_close();

/**
 * 提交称重+MQTT任务到异步队列（不阻塞主循环）
 * @param plate 车牌号
 * @param station_type 1=进站, 2=出站
 * @param tb_num 联单编号
 */
void enqueue_weight_mqtt_task(const std::string& plate, int station_type,
                               const std::string& tb_num);

/**
 * 启动称重+MQTT异步worker线程
 */
void start_weight_mqtt_worker();

/**
 * 停止称重+MQTT异步worker线程
 */
void stop_weight_mqtt_worker();

/**
 * 手动重试称重上传（fix24-v9）
 * @param record_id 称重记录ID
 * @return true=重试成功, false=重试失败
 */
bool weight_manual_retry(int record_id);

// ==================== fix24 v43: 并行称重调度器接口 ====================
/**
 * 重量数据上传到平台（公开接口，供 weight_dispatcher 调用）
 * @param tb_no 联单编号
 * @param weight_ton 重量（吨）
 * @return 0=成功, -1=失败
 */
int upload_weight_data_public(const std::string& tb_no, float weight_ton);

/**
 * 带重试的重量上传（公开接口）
 */
int upload_weight_with_retry_public(const std::string& tb_no, float weight_ton);

#endif