### 注意事项
一定要注意文件编码问题，有可能会引起字符错乱
这是后端项目，前端系统不在这个项目里

### 项目运行环境
这是开发环境，运行环境在centos7的容器里，分别为
qaup-app
qaup-redis
qaup-postgis

### Docker/日志/数据库定位
- 后端应用容器：`qaup-app`。
- Redis 容器：`qaup-redis`。
- PostGIS/PostgreSQL 容器：`qaup-postgis`。
- 后端主日志优先看宿主机路径：`/home/project_20250804/offline-deploy/logs/app/sys-info.log`，历史滚动日志类似 `sys-info.2026-04-28.2.log`。
- 容器 overlay 中也可能有同一份日志：`/var/lib/docker/overlay2/.../merged/logs/sys-info*.log`。
- 碰撞测试独立日志在 qaup-app 容器内：`/logs/collision-tests/`。启动时主日志会打印：`Collision test session file log initialized: enabled=true, directory=/logs/collision-tests`。
- 按车牌或航班查测试日志：`docker exec qaup-app sh -c 'grep -R -l "TEST003" /logs/collision-tests 2>/dev/null'`。
- `/home/project_20250804/qaup/logs` 下看到的 `mock_traffic_light.log`、`mock_unmanned_vehicle.log` 是模拟器日志，不是 qaup-app 主应用日志。
- qaup-app 容器内通常没有 `psql`，查库优先用：`docker exec qaup-postgis psql -U postgres -d qaup -c "SQL"`。
- 已确认数据库环境变量示例：`DB_HOST=172.17.0.4`、`DB_PORT=5432`、`DB_USERNAME=postgres`、`DB_PASSWORD=123456`、`DB_NAME=qaup`。

### 碰撞测试流程排查要点
- `/api/VehicleRegistry` 是全量覆盖注册，不是增量追加。
- 测试会话日志关键字：`collision test session started`、`collision test session replaced`、`collision-diagnostic`。
- 诊断日志中重点看：`collisionManagedObjects`、`pairsSupported`、`missingRoute`、`routeDeviation`、`speedTooLow`、`thresholdNotReached`、`eventsPublished`。
- 如果 `pairsTotal=0`，说明参与碰撞检测的对象不足两个，先查注册对象和实时位置对象是否匹配。
- 如果 `routeDeviation>0`，说明实时位置距离后端绑定路线过远，优先查本轮路线绑定是否正确。
- 路径绑定表是 `object_route_assignments`，真实字段为：`id`、`object_type`、`object_name`、`assigned_route_id`、`assigned_at`。不要使用 `object_id`、`route_id`、`route_name` 这些不存在的字段。
- 查对象路线绑定示例：`docker exec qaup-postgis psql -U postgres -d qaup -c "select object_type, object_name, assigned_route_id, assigned_at from object_route_assignments where object_name in ('MU2465','TEST003') order by assigned_at desc;"`
- 如需看路线名称，连接 `transport_routes`：`docker exec qaup-postgis psql -U postgres -d qaup -c "select a.object_type, a.object_name, a.assigned_route_id, r.name, a.assigned_at from object_route_assignments a left join transport_routes r on r.id = a.assigned_route_id where a.object_name in ('MU2465','TEST003') order by a.assigned_at desc;"`
- 历史上曾出现同一对象编号跨类型或旧路线残留导致误判，注册覆盖时需要同步清理旧路径绑定。

### 碰撞现场测试快速流程
- 测试开始后先定位本次独立测试日志：`docker exec qaup-app sh -c 'ls -lt /logs/collision-tests | head -20'`。
- 已知车牌或航班号时，直接按对象编号找日志文件：`docker exec qaup-app sh -c 'grep -R -l "TEST003" /logs/collision-tests 2>/dev/null'`。
- 找到日志后优先看方向锁定和碰撞计算链路：`docker exec qaup-app sh -c 'grep -E "DIRECTION_LOCK|DIRECTION_LOCK_FAILED|PAIR_RESULT|PATH_CONFLICT_POINT_SENT|EVENT_PUBLISHED|CYCLE" /logs/collision-tests/具体文件名.log'`。
- 不知道具体日志名但知道对象编号时，可一条命令定位并查看：`docker exec qaup-app sh -c 'f=$(grep -R -l "TEST003" /logs/collision-tests 2>/dev/null | tail -1); echo $f; grep -E "DIRECTION_LOCK|DIRECTION_LOCK_FAILED|PAIR_RESULT|PATH_CONFLICT_POINT_SENT|EVENT_PUBLISHED|CYCLE" "$f"'`。
- 方向锁定判断：正常应看到 `DIRECTION_LOCK`；如果看到 `DIRECTION_LOCK_FAILED`，先看原因是否为 `initial_position_too_close_to_conflict_point` 或 `conflict_points_on_both_sides`。
- 本项目碰撞测试要求：车和飞机不必停在路线起点，但应能投影到绑定路线，并且测试开始时不要贴近冲突点，建议距离冲突点至少 `10-20米`，避免定位抖动触发方向无法锁定。
- 前端 WebSocket 调试消息看 `type=path_conflict_status`，重点看 `payload.calculationStatus`、`payload.directionLockStatus`、`payload.directionLockReason`、`payload.vehicleDistanceToConflictMeters`、`payload.aircraftDistanceToConflictMeters`、`payload.object1ForwardDistanceMeters`、`payload.object2ForwardDistanceMeters`。
- 正常测试现象：`directionLockStatus=DIRECTION_LOCKED`，车和飞机到冲突点的距离逐步变小；达到预警/告警阈值后后端发预警/告警，车辆停车；飞机越过冲突点并超过解除距离后车辆恢复通行。
- 如果前端看到距离不变大/不变小，先对照测试日志中的 `forwardDistance`、`PAIR_RESULT` 和路线绑定表，判断是定位数据问题、路线绑定问题，还是方向未锁定问题。

### 红绿灯接入说明
- 正式环境中，qaup-app 的红绿灯接入方式为 MQTT，不是 HTTP。
- 正式环境配置中 `traffic.light.tcp.enabled=false`，`traffic.light.mqtt.enabled=true`。
- MQTT Broker 地址示例：`tcp://10.64.58.228:8082`，订阅 Topic 示例：`cusc/v2/SF053/QingDrsu001/data`。
- 注意区分 MQTT Broker 的 TCP 连接地址与业务 TCP 直连服务，前者不是“红绿灯走 TCP 直连”的意思。