feat: KKS P240/P241 蓝牙工牌管理系统初始提交

FastAPI + SQLAlchemy + asyncio TCP 服务器，支持设备管理、实时定位、
告警、考勤打卡、蓝牙记录、指令下发、TTS语音播报等功能。

app/routers/locations.py

@@ -0,0 +1,155 @@
+"""
+Locations Router - 位置数据接口
+API endpoints for querying location records and device tracks.
+"""
+
+import math
+from datetime import datetime
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.models import LocationRecord
+from app.schemas import (
+    APIResponse,
+    LocationRecordResponse,
+    PaginatedList,
+)
+from app.services import device_service, location_service
+
+router = APIRouter(prefix="/api/locations", tags=["Locations / 位置数据"])
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[LocationRecordResponse]],
+    summary="获取位置记录列表 / List location records",
+)
+async def list_locations(
+    device_id: int | None = Query(default=None, description="设备ID / Device ID"),
+    location_type: str | None = Query(default=None, description="定位类型 / Location type (gps/lbs/wifi)"),
+    start_time: datetime | None = Query(default=None, description="开始时间 / Start time (ISO 8601)"),
+    end_time: datetime | None = Query(default=None, description="结束时间 / End time (ISO 8601)"),
+    page: int = Query(default=1, ge=1, description="页码 / Page number"),
+    page_size: int = Query(default=20, ge=1, le=100, description="每页数量 / Items per page"),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    获取位置记录列表，支持按设备、定位类型、时间范围过滤。
+    List location records with filters for device, location type, and time range.
+    """
+    records, total = await location_service.get_locations(
+        db,
+        device_id=device_id,
+        location_type=location_type,
+        start_time=start_time,
+        end_time=end_time,
+        page=page,
+        page_size=page_size,
+    )
+    return APIResponse(
+        data=PaginatedList(
+            items=[LocationRecordResponse.model_validate(r) for r in records],
+            total=total,
+            page=page,
+            page_size=page_size,
+            total_pages=math.ceil(total / page_size) if total else 0,
+        )
+    )
+
+
+@router.get(
+    "/latest/{device_id}",
+    response_model=APIResponse[LocationRecordResponse | None],
+    summary="获取设备最新位置 / Get latest location",
+)
+async def latest_location(device_id: int, db: AsyncSession = Depends(get_db)):
+    """
+    获取指定设备的最新位置信息。
+    Get the most recent location record for a device.
+    """
+    # Verify device exists
+    device = await device_service.get_device(db, device_id)
+    if device is None:
+        raise HTTPException(status_code=404, detail=f"Device {device_id} not found / 未找到设备{device_id}")
+
+    record = await location_service.get_latest_location(db, device_id)
+    if record is None:
+        return APIResponse(
+            code=0,
+            message="No location data available / 暂无位置数据",
+            data=None,
+        )
+    return APIResponse(data=LocationRecordResponse.model_validate(record))
+
+
+@router.post(
+    "/batch-latest",
+    response_model=APIResponse[list[LocationRecordResponse | None]],
+    summary="批量获取设备最新位置 / Batch get latest locations",
+)
+async def batch_latest_locations(
+    device_ids: list[int] = Body(..., min_length=1, max_length=100, embed=True),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    传入 device_ids 列表，返回每台设备的最新位置（按输入顺序）。
+    Pass device_ids list, returns latest location per device in input order.
+    """
+    records = await location_service.get_batch_latest_locations(db, device_ids)
+    result_map = {r.device_id: r for r in records}
+    return APIResponse(data=[
+        LocationRecordResponse.model_validate(result_map[did]) if did in result_map else None
+        for did in device_ids
+    ])
+
+
+@router.get(
+    "/track/{device_id}",
+    response_model=APIResponse[list[LocationRecordResponse]],
+    summary="获取设备轨迹 / Get device track",
+)
+async def device_track(
+    device_id: int,
+    start_time: datetime = Query(..., description="开始时间 / Start time (ISO 8601)"),
+    end_time: datetime = Query(..., description="结束时间 / End time (ISO 8601)"),
+    max_points: int = Query(default=10000, ge=1, le=50000, description="最大轨迹点数 / Max track points"),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    获取设备在指定时间范围内的运动轨迹（按时间正序排列）。
+    Get device movement track within a time range (ordered chronologically).
+    """
+    # Verify device exists
+    device = await device_service.get_device(db, device_id)
+    if device is None:
+        raise HTTPException(status_code=404, detail=f"Device {device_id} not found / 未找到设备{device_id}")
+
+    if start_time >= end_time:
+        raise HTTPException(
+            status_code=400,
+            detail="start_time must be before end_time / 开始时间必须早于结束时间",
+        )
+
+    records = await location_service.get_device_track(db, device_id, start_time, end_time, max_points=max_points)
+    return APIResponse(
+        data=[LocationRecordResponse.model_validate(r) for r in records]
+    )
+
+
+@router.get(
+    "/{location_id}",
+    response_model=APIResponse[LocationRecordResponse],
+    summary="获取位置记录详情 / Get location record",
+)
+async def get_location(location_id: int, db: AsyncSession = Depends(get_db)):
+    """按ID获取位置记录详情 / Get location record details by ID."""
+    result = await db.execute(
+        select(LocationRecord).where(LocationRecord.id == location_id)
+    )
+    record = result.scalar_one_or_none()
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Location {location_id} not found")
+    return APIResponse(data=LocationRecordResponse.model_validate(record))