/**
 * @file   track_map.h
 * @brief  赛道地图 — 固化 S 型遍历拓扑
 *
 *         地图不做全局坐标定位，只回答三个问题：
 *           1. 从第 N 条沟完成后，下一条是第几条？
 *           2. 这次该往哪转？(左/右)
 *           3. 当前是不是最后一条沟？
 */

#ifndef TRACK_MAP_H
#define TRACK_MAP_H

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

#ifdef __cplusplus
extern "C" {
#endif

/* =========================================================
 * 常量
 * ========================================================= */
#define TRACK_MAP_CORRIDOR_COUNT    6       /* 总共 6 条垄沟 */
#define TRACK_MAP_LINK_DISTANCE_M   0.70f   /* 沟间距 (中心到中心) */
#define TRACK_MAP_CORRIDOR_LENGTH_M 2.20f   /* 垄沟标称长度 */

/* =========================================================
 * 枚举
 * ========================================================= */

/** 沟内行驶方向 */
typedef enum {
    TRAVEL_DIR_POSITIVE = 0,   /* 从左端到右端 (→) */
    TRAVEL_DIR_NEGATIVE = 1    /* 从右端到左端 (←) */
} TravelDirection_t;

/** 转向方向 */
typedef enum {
    TURN_DIR_LEFT  = +1,       /* 逆时针 (CCW), w > 0 */
    TURN_DIR_RIGHT = -1        /* 顺时针 (CW),  w < 0 */
} TurnDirection_t;

/* =========================================================
 * 数据结构
 * ========================================================= */

/** 单条垄沟描述 */
typedef struct {
    uint8_t            id;              /* 0-5 */
    TravelDirection_t  travel_dir;      /* 本沟行驶方向 */
    TurnDirection_t    exit_turn_dir;   /* 出沟时的转向方向 */
    TurnDirection_t    entry_turn_dir;  /* 入沟时的转向方向 */
    bool               is_last;         /* 是否为最后一条沟 */
} CorridorDescriptor_t;

/** 完整赛道地图 */
typedef struct {
    CorridorDescriptor_t corridors[TRACK_MAP_CORRIDOR_COUNT];
    uint8_t              entry_corridor_id;   /* 入场后第一条沟 = 0 */
    float                link_distance_m;     /* 连接段标称距离 */
    float                corridor_length_m;   /* 垄沟标称长度 */
} TrackMap_t;

/* =========================================================
 * API
 * ========================================================= */
void                        TrackMap_Init(void);
const TrackMap_t*            TrackMap_Get(void);
const CorridorDescriptor_t* TrackMap_GetCorridor(uint8_t id);
uint8_t                     TrackMap_GetNextCorridorId(uint8_t current_id);
bool                        TrackMap_IsLastCorridor(uint8_t id);
TurnDirection_t             TrackMap_GetExitTurnDir(uint8_t id);
TurnDirection_t             TrackMap_GetEntryTurnDir(uint8_t id);

#ifdef __cplusplus
}
#endif

#endif /* TRACK_MAP_H */