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

FastAPI + SQLAlchemy + asyncio TCP 服务器，支持设备管理、实时定位、告警、考勤打卡、蓝牙记录、指令下发、TTS语音播报等功能。
2026-03-27 10:19:34 +00:00
commit d54e53e0b7
43 changed files with 15078 additions and 0 deletions
--- a/app/init.py
+++ b/app/init.py
--- a/app/config.py
+++ b/app/config.py
@@ -0,0 +1,50 @@
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+# Project root directory (where config.py lives → parent = app/ → parent = project root)
+_PROJECT_ROOT = Path(__file__).resolve().parent.parent
+_DEFAULT_DB_PATH = _PROJECT_ROOT / "badge_admin.db"
+
+
+class Settings(BaseSettings):
+    APP_NAME: str = "KKS Badge Management System"
+    DATABASE_URL: str = Field(
+        default=f"sqlite+aiosqlite:///{_DEFAULT_DB_PATH}",
+        description="Database connection URL (absolute path for SQLite)",
+    )
+    TCP_HOST: str = "0.0.0.0"
+    TCP_PORT: int = Field(default=5000, ge=1, le=65535)
+    API_HOST: str = "0.0.0.0"
+    API_PORT: int = Field(default=8088, ge=1, le=65535)
+    DEBUG: bool = Field(default=False, description="Enable debug mode (SQL echo, verbose errors)")
+
+    # API authentication
+    API_KEY: str | None = Field(default=None, description="API key for authentication (None=disabled)")
+    CORS_ORIGINS: str = Field(default="*", description="Comma-separated allowed CORS origins")
+
+    # Rate limiting
+    RATE_LIMIT_DEFAULT: str = Field(default="60/minute", description="Default rate limit")
+    RATE_LIMIT_WRITE: str = Field(default="30/minute", description="Rate limit for write operations")
+
+    # 高德地图 API (geocoding)
+    AMAP_KEY: str | None = Field(default=None, description="高德地图 Web API key")
+    AMAP_SECRET: str | None = Field(default=None, description="高德地图安全密钥")
+
+    # Geocoding
+    GEOCODING_DEFAULT_IMEI: str = Field(default="868120334031363", description="Default IMEI for AMAP geocoding API")
+    GEOCODING_CACHE_SIZE: int = Field(default=10000, description="Max geocoding cache entries")
+
+    # Track query limit
+    TRACK_MAX_POINTS: int = Field(default=10000, description="Maximum points returned by track endpoint")
+
+    # Data retention
+    DATA_RETENTION_DAYS: int = Field(default=90, description="Days to keep location/heartbeat/alarm/attendance/bluetooth records")
+    DATA_CLEANUP_INTERVAL_HOURS: int = Field(default=24, description="Hours between automatic cleanup runs")
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8", "extra": "ignore"}
+
+
+settings = Settings()
--- a/app/database.py
+++ b/app/database.py
@@ -0,0 +1,49 @@
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+
+from app.config import settings
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    connect_args={"check_same_thread": False},
+)
+
+async_session = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+async def get_db() -> AsyncSession:
+    """Dependency injection for async database sessions."""
+    async with async_session() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()
+
+
+async def init_db() -> None:
+    """Create all database tables."""
+    async with engine.begin() as conn:
+        from app.models import (  # noqa: F401
+            AlarmRecord,
+            AttendanceRecord,
+            BluetoothRecord,
+            CommandLog,
+            Device,
+            HeartbeatRecord,
+            LocationRecord,
+        )
+
+        await conn.run_sync(Base.metadata.create_all)
--- a/app/dependencies.py
+++ b/app/dependencies.py
@@ -0,0 +1,85 @@
+"""
+Shared FastAPI dependencies.
+Supports master API key (env) and database-managed API keys with permission levels.
+"""
+
+import hashlib
+import secrets
+from datetime import datetime, timezone
+
+from fastapi import Depends, HTTPException, Security
+from fastapi.security import APIKeyHeader
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.database import get_db
+
+_api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+# Permission hierarchy: admin > write > read
+_PERMISSION_LEVELS = {"read": 1, "write": 2, "admin": 3}
+
+
+def _hash_key(key: str) -> str:
+    """SHA-256 hash of an API key."""
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+async def verify_api_key(
+    api_key: str | None = Security(_api_key_header),
+    db: AsyncSession = Depends(get_db),
+) -> dict | None:
+    """Verify API key. Returns key info dict or None (auth disabled).
+
+    Checks master key first, then database keys.
+    Returns {"permissions": "admin"|"write"|"read", "key_id": int|None, "name": str}.
+    """
+    if settings.API_KEY is None:
+        return None  # Auth disabled
+
+    if api_key is None:
+        raise HTTPException(status_code=401, detail="Missing API key / 缺少 API Key")
+
+    # Check master key
+    if secrets.compare_digest(api_key, settings.API_KEY):
+        return {"permissions": "admin", "key_id": None, "name": "master"}
+
+    # Check database keys
+    from app.models import ApiKey
+
+    key_hash = _hash_key(api_key)
+    result = await db.execute(
+        select(ApiKey).where(ApiKey.key_hash == key_hash, ApiKey.is_active == True)  # noqa: E712
+    )
+    db_key = result.scalar_one_or_none()
+    if db_key is None:
+        raise HTTPException(status_code=401, detail="Invalid API key / 无效的 API Key")
+
+    # Update last_used_at
+    db_key.last_used_at = datetime.now(timezone.utc)
+    await db.flush()
+
+    return {"permissions": db_key.permissions, "key_id": db_key.id, "name": db_key.name}
+
+
+def require_permission(min_level: str):
+    """Factory for permission-checking dependencies."""
+
+    async def _check(key_info: dict | None = Depends(verify_api_key)):
+        if key_info is None:
+            return  # Auth disabled
+        current = _PERMISSION_LEVELS.get(key_info["permissions"], 0)
+        required = _PERMISSION_LEVELS.get(min_level, 0)
+        if current < required:
+            raise HTTPException(
+                status_code=403,
+                detail=f"Insufficient permissions. Requires '{min_level}' / 权限不足，需要 '{min_level}' 权限",
+            )
+        return key_info
+
+    return _check
+
+
+require_write = require_permission("write")
+require_admin = require_permission("admin")
--- a/app/extensions.py
+++ b/app/extensions.py
@@ -0,0 +1,22 @@
+"""
+Shared extension instances (rate limiter, etc.) to avoid circular imports.
+"""
+
+from starlette.requests import Request
+from slowapi import Limiter
+
+from app.config import settings
+
+
+def _get_real_client_ip(request: Request) -> str:
+    """Extract real client IP from X-Forwarded-For (behind Cloudflare/nginx) or fallback."""
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    cf_ip = request.headers.get("CF-Connecting-IP")
+    if cf_ip:
+        return cf_ip.strip()
+    return request.client.host if request.client else "127.0.0.1"
+
+
+limiter = Limiter(key_func=_get_real_client_ip, default_limits=[settings.RATE_LIMIT_DEFAULT])
--- a/app/geocoding.py
+++ b/app/geocoding.py
@@ -0,0 +1,308 @@
+"""
+Geocoding service - Convert cell tower / WiFi AP data to lat/lon coordinates,
+and reverse geocode coordinates to addresses.
+
+All services use 高德 (Amap) API exclusively.
+- Forward geocoding (cell/WiFi → coords): 高德智能硬件定位
+- Reverse geocoding (coords → address): 高德逆地理编码
+"""
+
+import hashlib
+import logging
+import math
+from collections import OrderedDict
+from typing import Optional
+
+import aiohttp
+
+logger = logging.getLogger(__name__)
+
+from app.config import settings as _settings
+
+AMAP_KEY: Optional[str] = _settings.AMAP_KEY
+AMAP_SECRET: Optional[str] = _settings.AMAP_SECRET
+
+_CACHE_MAX_SIZE = _settings.GEOCODING_CACHE_SIZE
+
+
+# ---------------------------------------------------------------------------
+# WGS-84 → GCJ-02 coordinate conversion (server-side)
+# ---------------------------------------------------------------------------
+
+_A = 6378245.0
+_EE = 0.00669342162296594
+
+
+def _out_of_china(lat: float, lon: float) -> bool:
+    return not (73.66 < lon < 135.05 and 3.86 < lat < 53.55)
+
+
+def _transform_lat(x: float, y: float) -> float:
+    ret = -100.0 + 2.0 * x + 3.0 * y + 0.2 * y * y + 0.1 * x * y + 0.2 * math.sqrt(abs(x))
+    ret += (20.0 * math.sin(6.0 * x * math.pi) + 20.0 * math.sin(2.0 * x * math.pi)) * 2.0 / 3.0
+    ret += (20.0 * math.sin(y * math.pi) + 40.0 * math.sin(y / 3.0 * math.pi)) * 2.0 / 3.0
+    ret += (160.0 * math.sin(y / 12.0 * math.pi) + 320.0 * math.sin(y * math.pi / 30.0)) * 2.0 / 3.0
+    return ret
+
+
+def _transform_lon(x: float, y: float) -> float:
+    ret = 300.0 + x + 2.0 * y + 0.1 * x * x + 0.1 * x * y + 0.1 * math.sqrt(abs(x))
+    ret += (20.0 * math.sin(6.0 * x * math.pi) + 20.0 * math.sin(2.0 * x * math.pi)) * 2.0 / 3.0
+    ret += (20.0 * math.sin(x * math.pi) + 40.0 * math.sin(x / 3.0 * math.pi)) * 2.0 / 3.0
+    ret += (150.0 * math.sin(x / 12.0 * math.pi) + 300.0 * math.sin(x / 30.0 * math.pi)) * 2.0 / 3.0
+    return ret
+
+
+def wgs84_to_gcj02(lat: float, lon: float) -> tuple[float, float]:
+    """Convert WGS-84 to GCJ-02 (used by 高德)."""
+    if _out_of_china(lat, lon):
+        return (lat, lon)
+    d_lat = _transform_lat(lon - 105.0, lat - 35.0)
+    d_lon = _transform_lon(lon - 105.0, lat - 35.0)
+    rad_lat = lat / 180.0 * math.pi
+    magic = math.sin(rad_lat)
+    magic = 1 - _EE * magic * magic
+    sqrt_magic = math.sqrt(magic)
+    d_lat = (d_lat * 180.0) / ((_A * (1 - _EE)) / (magic * sqrt_magic) * math.pi)
+    d_lon = (d_lon * 180.0) / (_A / sqrt_magic * math.cos(rad_lat) * math.pi)
+    return (lat + d_lat, lon + d_lon)
+
+
+# ---------------------------------------------------------------------------
+# LRU Cache
+# ---------------------------------------------------------------------------
+
+
+class LRUCache(OrderedDict):
+    """Simple LRU cache based on OrderedDict."""
+
+    def __init__(self, maxsize: int = _CACHE_MAX_SIZE):
+        super().__init__()
+        self._maxsize = maxsize
+
+    def get_cached(self, key):
+        if key in self:
+            self.move_to_end(key)
+            return self[key]
+        return None
+
+    def put(self, key, value):
+        if key in self:
+            self.move_to_end(key)
+        self[key] = value
+        while len(self) > self._maxsize:
+            self.popitem(last=False)
+
+
+_cell_cache: LRUCache = LRUCache()
+_wifi_cache: LRUCache = LRUCache()
+_address_cache: LRUCache = LRUCache()
+
+
+# ---------------------------------------------------------------------------
+# 高德数字签名 (AMAP_SECRET)
+# ---------------------------------------------------------------------------
+
+def _amap_sign(params: dict) -> str:
+    """Generate 高德 API digital signature (MD5)."""
+    if not AMAP_SECRET:
+        return ""
+    sorted_str = "&".join(f"{k}={params[k]}" for k in sorted(params.keys()))
+    raw = sorted_str + AMAP_SECRET
+    return hashlib.md5(raw.encode()).hexdigest()
+
+
+# ===========================================================================
+# Forward Geocoding: cell/WiFi → lat/lon
+# ===========================================================================
+
+
+async def geocode_location(
+    mcc: Optional[int] = None,
+    mnc: Optional[int] = None,
+    lac: Optional[int] = None,
+    cell_id: Optional[int] = None,
+    wifi_list: Optional[list[dict]] = None,
+    neighbor_cells: Optional[list[dict]] = None,
+    imei: Optional[str] = None,
+) -> tuple[Optional[float], Optional[float]]:
+    """
+    Convert cell tower and/or WiFi AP data to lat/lon.
+
+    Uses 高德智能硬件定位 API exclusively.
+    """
+    # Check cache first
+    if mcc is not None and lac is not None and cell_id is not None:
+        cache_key = (mcc, mnc or 0, lac, cell_id)
+        cached = _cell_cache.get_cached(cache_key)
+        if cached is not None:
+            return cached
+
+    if AMAP_KEY:
+        result = await _geocode_amap(mcc, mnc, lac, cell_id, wifi_list, neighbor_cells, imei=imei)
+        if result[0] is not None:
+            if mcc is not None and lac is not None and cell_id is not None:
+                _cell_cache.put((mcc, mnc or 0, lac, cell_id), result)
+            return result
+
+    return (None, None)
+
+
+async def _geocode_amap(
+    mcc, mnc, lac, cell_id, wifi_list, neighbor_cells, *, imei: Optional[str] = None
+) -> tuple[Optional[float], Optional[float]]:
+    """
+    Use 高德智能硬件定位 API (apilocate.amap.com/position).
+
+    Returns coordinates (高德 returns GCJ-02).
+    """
+    # Build bts (base station) parameter: mcc,mnc,lac,cellid,signal
+    bts = ""
+    if mcc is not None and lac is not None and cell_id is not None:
+        bts = f"{mcc},{mnc or 0},{lac},{cell_id},-65"
+
+    # Build nearbts (neighbor cells)
+    nearbts_parts = []
+    if neighbor_cells:
+        for nc in neighbor_cells:
+            nc_lac = nc.get("lac", 0)
+            nc_cid = nc.get("cell_id", 0)
+            nc_signal = -(nc.get("rssi", 0)) if nc.get("rssi") else -80
+            nearbts_parts.append(f"{mcc or 460},{mnc or 0},{nc_lac},{nc_cid},{nc_signal}")
+
+    # Build macs (WiFi APs): mac,signal,ssid
+    macs_parts = []
+    if wifi_list:
+        for ap in wifi_list:
+            mac = ap.get("mac", "").lower().replace(":", "")
+            signal = -(ap.get("signal", 0)) if ap.get("signal") else -70
+            ssid = ap.get("ssid", "")
+            macs_parts.append(f"{mac},{signal},{ssid}")
+
+    if not bts and not macs_parts:
+        return (None, None)
+
+    params = {"accesstype": "0", "imei": imei or _settings.GEOCODING_DEFAULT_IMEI, "key": AMAP_KEY}
+    if bts:
+        params["bts"] = bts
+    if nearbts_parts:
+        params["nearbts"] = "|".join(nearbts_parts)
+    if macs_parts:
+        params["macs"] = "|".join(macs_parts)
+
+    # Add digital signature
+    sig = _amap_sign(params)
+    if sig:
+        params["sig"] = sig
+
+    url = "https://apilocate.amap.com/position"
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                url, params=params, timeout=aiohttp.ClientTimeout(total=5)
+            ) as resp:
+                if resp.status == 200:
+                    data = await resp.json(content_type=None)
+                    if data.get("status") == "1" and data.get("result"):
+                        result = data["result"]
+                        location = result.get("location", "")
+                        if location and "," in location:
+                            lon_str, lat_str = location.split(",")
+                            lat = float(lat_str)
+                            lon = float(lon_str)
+                            logger.info("Amap geocode: lat=%.6f, lon=%.6f", lat, lon)
+                            return (lat, lon)
+                    else:
+                        infocode = data.get("infocode", "")
+                        if infocode == "10012":
+                            logger.debug("Amap geocode: insufficient permissions (enterprise cert needed)")
+                        else:
+                            logger.warning("Amap geocode error: %s (code=%s)", data.get("info", ""), infocode)
+                else:
+                    logger.warning("Amap geocode HTTP %d", resp.status)
+    except Exception as e:
+        logger.warning("Amap geocode error: %s", e)
+
+    return (None, None)
+
+
+# ===========================================================================
+# Reverse Geocoding: coordinates → address
+# ===========================================================================
+
+
+async def reverse_geocode(
+    lat: float, lon: float
+) -> Optional[str]:
+    """
+    Convert lat/lon (WGS-84) to a human-readable address.
+
+    Uses 高德逆地理编码 API exclusively.
+    """
+    cache_key = (round(lat, 3), round(lon, 3))
+    cached = _address_cache.get_cached(cache_key)
+    if cached is not None:
+        return cached
+
+    if AMAP_KEY:
+        result = await _reverse_geocode_amap(lat, lon)
+        if result:
+            _address_cache.put(cache_key, result)
+            return result
+
+    return None
+
+
+async def _reverse_geocode_amap(
+    lat: float, lon: float
+) -> Optional[str]:
+    """
+    Use 高德逆地理编码 API.
+
+    API: https://restapi.amap.com/v3/geocode/regeo
+    Input: GCJ-02 coordinates (need to convert from WGS-84).
+    Free tier: 5,000 requests/day (personal), 1,000,000/day (enterprise).
+    """
+    gcj_lat, gcj_lon = wgs84_to_gcj02(lat, lon)
+
+    params = {
+        "key": AMAP_KEY,
+        "location": f"{gcj_lon:.6f},{gcj_lat:.6f}",
+        "extensions": "base",
+        "output": "json",
+    }
+
+    sig = _amap_sign(params)
+    if sig:
+        params["sig"] = sig
+
+    url = "https://restapi.amap.com/v3/geocode/regeo"
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                url, params=params, timeout=aiohttp.ClientTimeout(total=5)
+            ) as resp:
+                if resp.status == 200:
+                    data = await resp.json(content_type=None)
+                    if data.get("status") == "1":
+                        regeocode = data.get("regeocode", {})
+                        formatted = regeocode.get("formatted_address", "")
+                        if formatted and formatted != "[]":
+                            logger.info(
+                                "Amap reverse geocode: %.6f,%.6f -> %s",
+                                lat, lon, formatted,
+                            )
+                            return formatted
+                    else:
+                        logger.warning(
+                            "Amap reverse geocode error: info=%s, infocode=%s",
+                            data.get("info", ""), data.get("infocode", ""),
+                        )
+                else:
+                    logger.warning("Amap reverse geocode HTTP %d", resp.status)
+    except Exception as e:
+        logger.warning("Amap reverse geocode error: %s", e)
+
+    return None
--- a/app/main.py
+++ b/app/main.py
@@ -0,0 +1,238 @@
+from pathlib import Path
+
+from fastapi import Depends, FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from contextlib import asynccontextmanager
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.middleware import SlowAPIMiddleware
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+
+from app.database import init_db, async_session, engine
+from app.tcp_server import tcp_manager
+from app.config import settings
+from app.routers import devices, locations, alarms, attendance, commands, bluetooth, beacons, heartbeats, api_keys, ws, geocoding
+from app.dependencies import verify_api_key, require_write, require_admin
+
+import asyncio
+import logging
+
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+# Rate limiter (shared instance via app.extensions for router access)
+from app.extensions import limiter
+
+
+async def run_data_cleanup():
+    """Delete records older than DATA_RETENTION_DAYS."""
+    from datetime import datetime, timezone, timedelta
+    from sqlalchemy import delete
+    from app.models import LocationRecord, HeartbeatRecord, AlarmRecord, AttendanceRecord, BluetoothRecord
+
+    cutoff = datetime.now(timezone.utc) - timedelta(days=settings.DATA_RETENTION_DAYS)
+    total_deleted = 0
+    async with async_session() as session:
+        async with session.begin():
+            for model, time_col in [
+                (LocationRecord, LocationRecord.created_at),
+                (HeartbeatRecord, HeartbeatRecord.created_at),
+                (AlarmRecord, AlarmRecord.created_at),
+                (AttendanceRecord, AttendanceRecord.created_at),
+                (BluetoothRecord, BluetoothRecord.created_at),
+            ]:
+                result = await session.execute(
+                    delete(model).where(time_col < cutoff)
+                )
+                if result.rowcount:
+                    total_deleted += result.rowcount
+                    logger.info("Cleanup: deleted %d old %s records", result.rowcount, model.__tablename__)
+    return total_deleted
+
+
+async def _data_cleanup_loop():
+    """Background task that runs cleanup periodically."""
+    while True:
+        try:
+            await asyncio.sleep(settings.DATA_CLEANUP_INTERVAL_HOURS * 3600)
+            deleted = await run_data_cleanup()
+            if deleted:
+                logger.info("Data cleanup completed: %d records removed", deleted)
+        except asyncio.CancelledError:
+            break
+        except Exception:
+            logger.exception("Data cleanup error")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    logger.info("Initializing database...")
+    await init_db()
+    # Reset all devices to offline on startup (stale state from previous run)
+    try:
+        from sqlalchemy import update
+        from app.models import Device
+        async with async_session() as session:
+            async with session.begin():
+                await session.execute(update(Device).values(status="offline"))
+        logger.info("All devices reset to offline on startup")
+    except Exception:
+        logger.exception("Failed to reset device statuses on startup")
+    # Create missing indexes (safe for existing databases)
+    try:
+        from sqlalchemy import text as sa_text
+        async with engine.begin() as conn:
+            for stmt in [
+                "CREATE INDEX IF NOT EXISTS ix_alarm_type ON alarm_records(alarm_type)",
+                "CREATE INDEX IF NOT EXISTS ix_alarm_ack ON alarm_records(acknowledged)",
+                "CREATE INDEX IF NOT EXISTS ix_bt_beacon_mac ON bluetooth_records(beacon_mac)",
+                "CREATE INDEX IF NOT EXISTS ix_loc_type ON location_records(location_type)",
+                "CREATE INDEX IF NOT EXISTS ix_att_type ON attendance_records(attendance_type)",
+            ]:
+                await conn.execute(sa_text(stmt))
+        logger.info("Database indexes verified/created")
+    except Exception:
+        logger.exception("Failed to create indexes")
+
+    logger.info("Starting TCP server on %s:%d", settings.TCP_HOST, settings.TCP_PORT)
+    tcp_task = asyncio.create_task(tcp_manager.start(settings.TCP_HOST, settings.TCP_PORT))
+    cleanup_task = asyncio.create_task(_data_cleanup_loop())
+    yield
+    # Shutdown
+    cleanup_task.cancel()
+    logger.info("Shutting down TCP server...")
+    await tcp_manager.stop()
+    tcp_task.cancel()
+
+app = FastAPI(
+    title="KKS Badge Management System / KKS工牌管理系统",
+    description="""
+## KKS P240 & P241 蓝牙工牌管理后台 API
+
+### 功能模块 / Features:
+- **设备管理 / Device Management** - 设备注册、状态监控
+- **位置数据 / Location Data** - GPS/LBS/WIFI定位数据查询与轨迹回放
+- **报警管理 / Alarm Management** - SOS、围栏、低电等报警处理
+- **考勤管理 / Attendance** - 打卡记录查询与统计
+- **指令管理 / Commands** - 远程指令下发与留言
+- **蓝牙数据 / Bluetooth** - 蓝牙打卡与定位数据
+- **信标管理 / Beacons** - 蓝牙信标注册与位置配置
+- **心跳数据 / Heartbeats** - 设备心跳记录查询
+
+### 认证 / Authentication:
+设置 `API_KEY` 环境变量后，所有 `/api/` 请求需携带 `X-API-Key` 请求头。
+
+### 通讯协议 / Protocol:
+- TCP端口: {tcp_port} (设备连接)
+- 支持协议: KKS P240/P241 通讯协议
+    """.format(tcp_port=settings.TCP_PORT),
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan,
+)
+
+# Rate limiter — SlowAPIMiddleware applies default_limits to all routes
+app.state.limiter = limiter
+app.add_middleware(SlowAPIMiddleware)
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+# CORS
+_origins = [o.strip() for o in settings.CORS_ORIGINS.split(",") if o.strip()]
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_origins,
+    allow_credentials="*" not in _origins,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Global exception handler — prevent stack trace leaks
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    from fastapi.exceptions import RequestValidationError
+    from starlette.exceptions import HTTPException as StarletteHTTPException
+    # Let FastAPI handle its own exceptions
+    if isinstance(exc, (StarletteHTTPException, RequestValidationError)):
+        raise exc
+    logger.exception("Unhandled exception on %s %s", request.method, request.url.path)
+    return JSONResponse(
+        status_code=500,
+        content={"code": 500, "message": "Internal server error", "data": None},
+    )
+
+
+# Include API routers (all under /api/ prefix, protected by API key if configured)
+_api_deps = [verify_api_key] if settings.API_KEY else []
+
+app.include_router(devices.router, dependencies=[*_api_deps])
+app.include_router(locations.router, dependencies=[*_api_deps])
+app.include_router(alarms.router, dependencies=[*_api_deps])
+app.include_router(attendance.router, dependencies=[*_api_deps])
+app.include_router(commands.router, dependencies=[*_api_deps])
+app.include_router(bluetooth.router, dependencies=[*_api_deps])
+app.include_router(beacons.router, dependencies=[*_api_deps])
+app.include_router(heartbeats.router, dependencies=[*_api_deps])
+app.include_router(api_keys.router, dependencies=[*_api_deps])
+app.include_router(ws.router)  # WebSocket handles auth internally
+app.include_router(geocoding.router, dependencies=[*_api_deps])
+
+_STATIC_DIR = Path(__file__).parent / "static"
+app.mount("/static", StaticFiles(directory=str(_STATIC_DIR)), name="static")
+
+
+@app.get("/admin", response_class=HTMLResponse, tags=["Admin"])
+async def admin_page():
+    """管理后台页面 / Admin Dashboard"""
+    html_path = _STATIC_DIR / "admin.html"
+    return HTMLResponse(content=html_path.read_text(encoding="utf-8"))
+
+
+@app.get("/", tags=["Root"])
+async def root():
+    return {
+        "name": settings.APP_NAME,
+        "version": "1.0.0",
+        "docs": "/docs",
+        "redoc": "/redoc",
+        "admin": "/admin",
+        "tcp_port": settings.TCP_PORT,
+        "auth_enabled": settings.API_KEY is not None,
+    }
+
+
+@app.get("/health", tags=["Root"])
+async def health():
+    """Health check with database connectivity test."""
+    db_ok = False
+    try:
+        from sqlalchemy import text
+        async with engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+        db_ok = True
+    except Exception:
+        logger.warning("Health check: database unreachable")
+
+    from app.websocket_manager import ws_manager
+    status = "healthy" if db_ok else "degraded"
+    return {
+        "status": status,
+        "database": "ok" if db_ok else "error",
+        "connected_devices": len(tcp_manager.connections),
+        "websocket_connections": ws_manager.connection_count,
+    }
+
+
+@app.post("/api/system/cleanup", tags=["System / 系统管理"], dependencies=[Depends(require_admin)] if settings.API_KEY else [])
+async def manual_cleanup():
+    """手动触发数据清理 / Manually trigger data cleanup (admin only)."""
+    try:
+        deleted = await run_data_cleanup()
+        return {"code": 0, "message": f"Cleanup completed: {deleted} records removed", "data": {"deleted": deleted}}
+    except Exception as e:
+        logger.exception("Manual cleanup failed")
+        return {"code": 500, "message": f"Cleanup failed: {str(e)}", "data": None}
--- a/app/models.py
+++ b/app/models.py
@@ -0,0 +1,342 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import (
+    BigInteger,
+    Boolean,
+    DateTime,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+)
+from sqlalchemy.dialects.sqlite import JSON
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.database import Base
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class Device(Base):
+    """Registered Bluetooth badge devices."""
+
+    __tablename__ = "devices"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    imei: Mapped[str] = mapped_column(String(20), unique=True, index=True, nullable=False)
+    device_type: Mapped[str] = mapped_column(String(10), nullable=False)
+    name: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    status: Mapped[str] = mapped_column(String(20), default="offline", nullable=False)
+    battery_level: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    gsm_signal: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    last_heartbeat: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    last_login: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    iccid: Mapped[str | None] = mapped_column(String(30), nullable=True)
+    imsi: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    timezone: Mapped[str] = mapped_column(String(30), default="+8", nullable=False)
+    language: Mapped[str] = mapped_column(String(10), default="cn", nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+    updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime, default=_utcnow, onupdate=_utcnow, nullable=True
+    )
+
+    # Relationships
+    locations: Mapped[list["LocationRecord"]] = relationship(
+        back_populates="device", cascade="all, delete-orphan", lazy="noload"
+    )
+    alarms: Mapped[list["AlarmRecord"]] = relationship(
+        back_populates="device", cascade="all, delete-orphan", lazy="noload"
+    )
+    heartbeats: Mapped[list["HeartbeatRecord"]] = relationship(
+        back_populates="device", cascade="all, delete-orphan", lazy="noload"
+    )
+    attendance_records: Mapped[list["AttendanceRecord"]] = relationship(
+        back_populates="device", cascade="all, delete-orphan", lazy="noload"
+    )
+    bluetooth_records: Mapped[list["BluetoothRecord"]] = relationship(
+        back_populates="device", cascade="all, delete-orphan", lazy="noload"
+    )
+    command_logs: Mapped[list["CommandLog"]] = relationship(
+        back_populates="device", cascade="all, delete-orphan", lazy="noload"
+    )
+
+    def __repr__(self) -> str:
+        return f"<Device(id={self.id}, imei={self.imei}, status={self.status})>"
+
+
+class LocationRecord(Base):
+    """GPS / LBS / WIFI location records."""
+
+    __tablename__ = "location_records"
+    __table_args__ = (
+        Index("ix_location_device_time", "device_id", "recorded_at"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("devices.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    location_type: Mapped[str] = mapped_column(
+        String(10), nullable=False
+    )  # gps, lbs, wifi, gps_4g, lbs_4g, wifi_4g
+    latitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    longitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    speed: Mapped[float | None] = mapped_column(Float, nullable=True)
+    course: Mapped[float | None] = mapped_column(Float, nullable=True)
+    gps_satellites: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    gps_positioned: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    mcc: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    mnc: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    lac: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    cell_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    rssi: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    neighbor_cells: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    wifi_data: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    report_mode: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    is_realtime: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    mileage: Mapped[float | None] = mapped_column(Float, nullable=True)
+    address: Mapped[str | None] = mapped_column(Text, nullable=True)
+    raw_data: Mapped[str | None] = mapped_column(Text, nullable=True)
+    recorded_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+
+    device: Mapped["Device"] = relationship(back_populates="locations")
+
+    def __repr__(self) -> str:
+        return (
+            f"<LocationRecord(id={self.id}, device_id={self.device_id}, "
+            f"type={self.location_type})>"
+        )
+
+
+class AlarmRecord(Base):
+    """Alarm events raised by devices."""
+
+    __tablename__ = "alarm_records"
+    __table_args__ = (
+        Index("ix_alarm_device_time", "device_id", "recorded_at"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("devices.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    alarm_type: Mapped[str] = mapped_column(
+        String(30), nullable=False
+    )  # sos, low_battery, power_on, power_off, enter_fence, exit_fence, ...
+    alarm_source: Mapped[str | None] = mapped_column(
+        String(20), nullable=True
+    )  # single_fence, multi_fence, lbs, wifi
+    protocol_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    latitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    longitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    speed: Mapped[float | None] = mapped_column(Float, nullable=True)
+    course: Mapped[float | None] = mapped_column(Float, nullable=True)
+    mcc: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    mnc: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    lac: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    cell_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    battery_level: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    gsm_signal: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    fence_data: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    wifi_data: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    address: Mapped[str | None] = mapped_column(Text, nullable=True)
+    acknowledged: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    recorded_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+
+    device: Mapped["Device"] = relationship(back_populates="alarms")
+
+    def __repr__(self) -> str:
+        return (
+            f"<AlarmRecord(id={self.id}, device_id={self.device_id}, "
+            f"type={self.alarm_type})>"
+        )
+
+
+class HeartbeatRecord(Base):
+    """Heartbeat history from devices."""
+
+    __tablename__ = "heartbeat_records"
+    __table_args__ = (
+        Index("ix_heartbeat_device_time", "device_id", "created_at"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("devices.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    protocol_number: Mapped[int] = mapped_column(Integer, nullable=False)  # 0x13 or 0x36
+    terminal_info: Mapped[int] = mapped_column(Integer, nullable=False)
+    battery_level: Mapped[int] = mapped_column(Integer, nullable=False)
+    gsm_signal: Mapped[int] = mapped_column(Integer, nullable=False)
+    extension_data: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+
+    device: Mapped["Device"] = relationship(back_populates="heartbeats")
+
+    def __repr__(self) -> str:
+        return f"<HeartbeatRecord(id={self.id}, device_id={self.device_id})>"
+
+
+class AttendanceRecord(Base):
+    """Attendance punch records from badges."""
+
+    __tablename__ = "attendance_records"
+    __table_args__ = (
+        Index("ix_attendance_device_time", "device_id", "recorded_at"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("devices.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    attendance_type: Mapped[str] = mapped_column(
+        String(20), nullable=False
+    )  # clock_in, clock_out
+    protocol_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    gps_positioned: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    latitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    longitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    speed: Mapped[float | None] = mapped_column(Float, nullable=True)
+    course: Mapped[float | None] = mapped_column(Float, nullable=True)
+    gps_satellites: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    battery_level: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    gsm_signal: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    mcc: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    mnc: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    lac: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    cell_id: Mapped[int | None] = mapped_column(BigInteger, nullable=True)
+    wifi_data: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    lbs_data: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    address: Mapped[str | None] = mapped_column(Text, nullable=True)
+    recorded_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+
+    device: Mapped["Device"] = relationship(back_populates="attendance_records")
+
+    def __repr__(self) -> str:
+        return (
+            f"<AttendanceRecord(id={self.id}, device_id={self.device_id}, "
+            f"type={self.attendance_type})>"
+        )
+
+
+class BluetoothRecord(Base):
+    """Bluetooth punch card and location records."""
+
+    __tablename__ = "bluetooth_records"
+    __table_args__ = (
+        Index("ix_bluetooth_device_time", "device_id", "recorded_at"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("devices.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    record_type: Mapped[str] = mapped_column(
+        String(20), nullable=False
+    )  # punch, location
+    protocol_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    beacon_mac: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    beacon_uuid: Mapped[str | None] = mapped_column(String(36), nullable=True)
+    beacon_major: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    beacon_minor: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    rssi: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    beacon_battery: Mapped[float | None] = mapped_column(Float, nullable=True)
+    beacon_battery_unit: Mapped[str | None] = mapped_column(String(10), nullable=True)
+    attendance_type: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    bluetooth_data: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    latitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    longitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    recorded_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+
+    device: Mapped["Device"] = relationship(back_populates="bluetooth_records")
+
+    def __repr__(self) -> str:
+        return (
+            f"<BluetoothRecord(id={self.id}, device_id={self.device_id}, "
+            f"type={self.record_type})>"
+        )
+
+
+class BeaconConfig(Base):
+    """Registered Bluetooth beacon configuration for indoor positioning."""
+
+    __tablename__ = "beacon_configs"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    beacon_mac: Mapped[str] = mapped_column(String(20), unique=True, index=True, nullable=False)
+    beacon_uuid: Mapped[str | None] = mapped_column(String(36), nullable=True)
+    beacon_major: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    beacon_minor: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    floor: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    area: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    latitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    longitude: Mapped[float | None] = mapped_column(Float, nullable=True)
+    address: Mapped[str | None] = mapped_column(Text, nullable=True)
+    status: Mapped[str] = mapped_column(String(20), default="active", nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+    updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime, default=_utcnow, onupdate=_utcnow, nullable=True
+    )
+
+    def __repr__(self) -> str:
+        return f"<BeaconConfig(id={self.id}, mac={self.beacon_mac}, name={self.name})>"
+
+
+class CommandLog(Base):
+    """Log of commands sent to devices."""
+
+    __tablename__ = "command_logs"
+    __table_args__ = (
+        Index("ix_command_device_status", "device_id", "status"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("devices.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    command_type: Mapped[str] = mapped_column(String(30), nullable=False)
+    command_content: Mapped[str] = mapped_column(Text, nullable=False)
+    server_flag: Mapped[str] = mapped_column(String(20), nullable=False)
+    response_content: Mapped[str | None] = mapped_column(Text, nullable=True)
+    status: Mapped[str] = mapped_column(
+        String(20), default="pending", nullable=False
+    )  # pending, sent, success, failed
+    sent_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    response_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+
+    device: Mapped["Device"] = relationship(back_populates="command_logs")
+
+    def __repr__(self) -> str:
+        return (
+            f"<CommandLog(id={self.id}, device_id={self.device_id}, "
+            f"type={self.command_type}, status={self.status})>"
+        )
+
+
+class ApiKey(Base):
+    """API keys for external system authentication."""
+
+    __tablename__ = "api_keys"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    key_hash: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    permissions: Mapped[str] = mapped_column(
+        String(20), default="read", nullable=False
+    )  # read, write, admin
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    last_used_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_utcnow, nullable=False)
+
+    def __repr__(self) -> str:
+        return f"<ApiKey(id={self.id}, name={self.name}, permissions={self.permissions})>"
--- a/app/protocol/init.py
+++ b/app/protocol/init.py
@@ -0,0 +1,20 @@
+"""
+KKS Bluetooth Badge Protocol
+
+Provides packet parsing, building, and CRC computation for the
+KKS Bluetooth badge communication protocol over TCP.
+"""
+
+from .constants import *  # noqa: F401,F403
+from .crc import crc_itu, verify_crc
+from .parser import PacketParser
+from .builder import PacketBuilder
+
+__all__ = [
+    # CRC
+    "crc_itu",
+    "verify_crc",
+    # Classes
+    "PacketParser",
+    "PacketBuilder",
+]
--- a/app/protocol/builder.py
+++ b/app/protocol/builder.py
@@ -0,0 +1,298 @@
+"""
+KKS Bluetooth Badge Protocol Packet Builder
+
+Constructs server response packets for the KKS badge protocol.
+"""
+
+from __future__ import annotations
+
+import struct
+import time
+from datetime import datetime, timezone
+from typing import Optional
+
+from .constants import (
+    PROTO_HEARTBEAT,
+    PROTO_HEARTBEAT_EXT,
+    PROTO_LBS_ADDRESS_REQ,
+    PROTO_LBS_MULTI_REPLY,
+    PROTO_LOGIN,
+    PROTO_MESSAGE,
+    PROTO_ONLINE_CMD,
+    PROTO_TIME_SYNC,
+    PROTO_TIME_SYNC_2,
+    PROTO_ADDRESS_REPLY_EN,
+    START_MARKER_LONG,
+    START_MARKER_SHORT,
+    STOP_MARKER,
+)
+from .crc import crc_itu
+
+
+class PacketBuilder:
+    """Builds server response packets for the KKS badge protocol."""
+
+    # ------------------------------------------------------------------
+    # Core builder
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def build_response(
+        protocol_number: int,
+        serial_number: int,
+        info_content: bytes = b"",
+    ) -> bytes:
+        """
+        Build a complete response packet.
+
+        Packet layout (short form, 0x7878):
+            START(2) + LENGTH(1) + PROTO(1) + INFO(N) + SERIAL(2) + CRC(2) + STOP(2)
+            LENGTH = 1(proto) + N(info) + 2(serial) + 2(crc)
+
+        If the payload exceeds 255 bytes the long form (0x7979, 2-byte
+        length) is used automatically.
+
+        Parameters
+        ----------
+        protocol_number : int
+            Protocol number byte.
+        serial_number : int
+            Packet serial number (16-bit).
+        info_content : bytes
+            Information content (may be empty).
+
+        Returns
+        -------
+        bytes
+            The fully assembled packet.
+        """
+        proto_byte = struct.pack("B", protocol_number)
+        serial_bytes = struct.pack("!H", serial_number)
+
+        # Payload for length calculation: proto + info + serial + crc
+        payload_len = 1 + len(info_content) + 2 + 2  # proto + info + serial + crc
+
+        if payload_len > 0xFF:
+            # Long packet
+            length_bytes = struct.pack("!H", payload_len)
+            start_marker = START_MARKER_LONG
+        else:
+            length_bytes = struct.pack("B", payload_len)
+            start_marker = START_MARKER_SHORT
+
+        # CRC is computed over: length_bytes + proto + info + serial
+        crc_input = length_bytes + proto_byte + info_content + serial_bytes
+        crc_value = crc_itu(crc_input)
+        crc_bytes = struct.pack("!H", crc_value)
+
+        return (
+            start_marker
+            + length_bytes
+            + proto_byte
+            + info_content
+            + serial_bytes
+            + crc_bytes
+            + STOP_MARKER
+        )
+
+    # ------------------------------------------------------------------
+    # Specific response builders
+    # ------------------------------------------------------------------
+
+    def build_login_response(self, serial_number: int) -> bytes:
+        """
+        Build a login response (0x01).
+
+        The server responds with an empty info content to acknowledge login.
+        """
+        return self.build_response(PROTO_LOGIN, serial_number)
+
+    def build_heartbeat_response(
+        self,
+        serial_number: int,
+        protocol: int = PROTO_HEARTBEAT,
+    ) -> bytes:
+        """
+        Build a heartbeat response.
+
+        Works for both standard heartbeat (0x13) and extended heartbeat (0x36).
+        """
+        return self.build_response(protocol, serial_number)
+
+    def build_time_sync_response(
+        self,
+        serial_number: int,
+        protocol: int = PROTO_TIME_SYNC,
+        language: int = 0x0001,
+    ) -> bytes:
+        """
+        Build a time sync response (0x1F).
+
+        Returns the current UTC time as a 4-byte Unix timestamp + 2-byte language.
+        For Chinese (0x0001), the timestamp is GMT+8.
+        """
+        utc_now = int(time.time())
+        if language == 0x0001:
+            utc_now += 8 * 3600  # GMT+8 for Chinese
+        info = struct.pack("!IH", utc_now, language)
+        return self.build_response(protocol, serial_number, info)
+
+    def build_time_sync_8a_response(self, serial_number: int) -> bytes:
+        """
+        Build a Time Sync 2 response (0x8A).
+
+        Returns the current UTC time as YY MM DD HH MM SS (6 bytes).
+        """
+        now = datetime.now(timezone.utc)
+        info = struct.pack(
+            "BBBBBB",
+            now.year - 2000,
+            now.month,
+            now.day,
+            now.hour,
+            now.minute,
+            now.second,
+        )
+        return self.build_response(PROTO_TIME_SYNC_2, serial_number, info)
+
+    def build_lbs_multi_response(self, serial_number: int) -> bytes:
+        """
+        Build an LBS Multi Reply response (0x2E).
+
+        The server acknowledges with an empty info content.
+        """
+        return self.build_response(PROTO_LBS_MULTI_REPLY, serial_number)
+
+    def build_online_command(
+        self,
+        serial_number: int,
+        server_flag: int,
+        command: str,
+        language: int = 0x0001,
+    ) -> bytes:
+        """
+        Build an online command packet (0x80).
+
+        Parameters
+        ----------
+        serial_number : int
+            Packet serial number.
+        server_flag : int
+            Server flag bits (32-bit).
+        command : str
+            The command string to send (ASCII).
+        language : int
+            Language code (default 0x0001 = Chinese).
+
+        Returns
+        -------
+        bytes
+            Complete packet.
+        """
+        cmd_bytes = command.encode("ascii")
+        # inner_len = server_flag(4) + cmd_content(N) + language(2)
+        inner_len = 4 + len(cmd_bytes) + 2
+
+        info = struct.pack("B", inner_len)              # 1 byte inner length
+        info += struct.pack("!I", server_flag)           # 4 bytes server flag
+        info += cmd_bytes                                # N bytes command
+        info += struct.pack("!H", language)              # 2 bytes language
+
+        return self.build_response(PROTO_ONLINE_CMD, serial_number, info)
+
+    def build_message(
+        self,
+        serial_number: int,
+        server_flag: int,
+        message_text: str,
+        language: int = 0x0001,
+    ) -> bytes:
+        """
+        Build a message packet (0x82).
+
+        The message is encoded in UTF-16 Big-Endian.
+
+        Parameters
+        ----------
+        serial_number : int
+            Packet serial number.
+        server_flag : int
+            Server flag bits (32-bit).
+        message_text : str
+            The message string to send.
+        language : int
+            Language code (default 0x0001 = Chinese).
+
+        Returns
+        -------
+        bytes
+            Complete packet.
+        """
+        msg_bytes = message_text.encode("utf-16-be")
+        # inner_len = server_flag(4) + msg_content(N) + language(2)
+        inner_len = 4 + len(msg_bytes) + 2
+
+        info = struct.pack("B", inner_len)               # 1 byte inner length
+        info += struct.pack("!I", server_flag)            # 4 bytes server flag
+        info += msg_bytes                                 # N bytes message (UTF16BE)
+        info += struct.pack("!H", language)               # 2 bytes language
+
+        return self.build_response(PROTO_MESSAGE, serial_number, info)
+
+    def build_address_reply_cn(
+        self,
+        serial_number: int,
+        server_flag: int = 0,
+        address: str = "",
+        phone: str = "",
+        protocol: int = PROTO_LBS_ADDRESS_REQ,
+        is_alarm: bool = False,
+    ) -> bytes:
+        """
+        Build a Chinese address reply packet (0x17).
+
+        Format: cmd_length(1) + server_flag(4) + ADDRESS/ALARMSMS + && + addr(UTF16BE) + && + phone(21) + ##
+        """
+        flag_bytes = struct.pack("!I", server_flag)
+        marker = b"ALARMSMS" if is_alarm else b"ADDRESS"
+        separator = b"&&"
+        terminator = b"##"
+
+        addr_bytes = address.encode("utf-16-be")
+        # Phone field: 21 bytes ASCII, zero-padded
+        phone_bytes = phone.encode("ascii", errors="ignore")[:21].ljust(21, b"0")
+
+        inner = flag_bytes + marker + separator + addr_bytes + separator + phone_bytes + terminator
+        # 0x17 uses 1-byte cmd_length
+        cmd_len = min(len(inner), 0xFF)
+        info = bytes([cmd_len]) + inner
+
+        return self.build_response(protocol, serial_number, info)
+
+    def build_address_reply_en(
+        self,
+        serial_number: int,
+        server_flag: int = 0,
+        address: str = "",
+        phone: str = "",
+        protocol: int = PROTO_ADDRESS_REPLY_EN,
+        is_alarm: bool = False,
+    ) -> bytes:
+        """
+        Build an English address reply packet (0x97).
+
+        Format: cmd_length(2) + server_flag(4) + ADDRESS/ALARMSMS + && + addr(UTF-8) + && + phone(21) + ##
+        """
+        flag_bytes = struct.pack("!I", server_flag)
+        marker = b"ALARMSMS" if is_alarm else b"ADDRESS"
+        separator = b"&&"
+        terminator = b"##"
+
+        addr_bytes = address.encode("utf-8")
+        phone_bytes = phone.encode("ascii", errors="ignore")[:21].ljust(21, b"0")
+
+        inner = flag_bytes + marker + separator + addr_bytes + separator + phone_bytes + terminator
+        # 0x97 uses 2-byte cmd_length
+        info = struct.pack("!H", len(inner)) + inner
+
+        return self.build_response(protocol, serial_number, info)
--- a/app/protocol/constants.py
+++ b/app/protocol/constants.py
@@ -0,0 +1,223 @@
+"""
+KKS Bluetooth Badge Protocol Constants
+
+Defines all protocol markers, protocol numbers, alarm types,
+signal strength levels, data report modes, and related mappings.
+"""
+
+from typing import Dict, FrozenSet
+
+# ---------------------------------------------------------------------------
+# Start / Stop Markers
+# ---------------------------------------------------------------------------
+START_MARKER_SHORT: bytes = b'\x78\x78'   # 1-byte packet length field
+START_MARKER_LONG: bytes = b'\x79\x79'    # 2-byte packet length field
+STOP_MARKER: bytes = b'\x0D\x0A'
+
+# ---------------------------------------------------------------------------
+# Protocol Numbers
+# ---------------------------------------------------------------------------
+PROTO_LOGIN: int = 0x01
+PROTO_HEARTBEAT: int = 0x13
+PROTO_LBS_ADDRESS_REQ: int = 0x17
+PROTO_ADDRESS_QUERY: int = 0x1A
+PROTO_TIME_SYNC: int = 0x1F
+PROTO_GPS: int = 0x22
+PROTO_LBS_MULTI: int = 0x28
+PROTO_LBS_MULTI_REPLY: int = 0x2E
+PROTO_WIFI: int = 0x2C
+PROTO_HEARTBEAT_EXT: int = 0x36
+PROTO_ONLINE_CMD: int = 0x80
+PROTO_ONLINE_CMD_REPLY: int = 0x81
+PROTO_MESSAGE: int = 0x82
+PROTO_TIME_SYNC_2: int = 0x8A
+PROTO_GENERAL_INFO: int = 0x94
+PROTO_ADDRESS_REPLY_EN: int = 0x97
+PROTO_GPS_4G: int = 0xA0
+PROTO_LBS_4G: int = 0xA1
+PROTO_WIFI_4G: int = 0xA2
+PROTO_ALARM_SINGLE_FENCE: int = 0xA3
+PROTO_ALARM_MULTI_FENCE: int = 0xA4
+PROTO_ALARM_LBS_4G: int = 0xA5
+PROTO_LBS_4G_ADDRESS_REQ: int = 0xA7
+PROTO_ALARM_ACK: int = 0x26
+PROTO_ALARM_WIFI: int = 0xA9
+PROTO_ATTENDANCE: int = 0xB0
+PROTO_ATTENDANCE_4G: int = 0xB1
+PROTO_BT_PUNCH: int = 0xB2
+PROTO_BT_LOCATION: int = 0xB3
+
+# ---------------------------------------------------------------------------
+# Alarm Types  (bit-pattern -> name)
+# ---------------------------------------------------------------------------
+ALARM_TYPES: Dict[int, str] = {
+    0x00: "normal",
+    0x01: "sos",
+    0x02: "power_cut",
+    0x03: "vibration",
+    0x04: "enter_fence",
+    0x05: "exit_fence",
+    0x06: "over_speed",
+    0x09: "displacement",
+    0x0A: "enter_gps_dead_zone",
+    0x0B: "exit_gps_dead_zone",
+    0x0C: "power_on",
+    0x0D: "gps_first_fix",
+    0x0E: "low_battery",
+    0x0F: "low_battery_protection",
+    0x10: "sim_change",
+    0x11: "power_off",
+    0x12: "airplane_mode",
+    0x13: "remove",
+    0x14: "door",
+    0x15: "shutdown",
+    0x16: "voice_alarm",
+    0x17: "fake_base_station",
+    0x18: "cover_open",
+    0x19: "internal_low_battery",
+    0xFE: "acc_on",
+    0xFF: "acc_off",
+}
+
+# ---------------------------------------------------------------------------
+# GSM Signal Strength Levels
+# ---------------------------------------------------------------------------
+GSM_SIGNAL_LEVELS: Dict[int, str] = {
+    0x00: "No Signal",
+    0x01: "Very Weak",
+    0x02: "Weak",
+    0x03: "Good",
+    0x04: "Strong",
+}
+
+# ---------------------------------------------------------------------------
+# Data Report Mode  (0x00 - 0x0F)
+# ---------------------------------------------------------------------------
+DATA_REPORT_MODES: Dict[int, str] = {
+    0x00: "Timing Upload",           # 定时上报
+    0x01: "Distance Upload",         # 定距上报
+    0x02: "Turn Point Upload",       # 拐点上传
+    0x03: "ACC Status Changed",      # ACC状态改变上传
+    0x04: "Last Point After Stop",   # 运动→静止补传最后定位点
+    0x05: "Reconnect Upload",        # 断网重连上报最后有效点
+    0x06: "Ephemeris Force Upload",  # 星历更新强制上传GPS点
+    0x07: "Button Upload",           # 按键上传定位点
+    0x08: "Power On Upload",         # 开机上报位置信息
+    0x09: "Unused",                  # 未使用
+    0x0A: "Static Update",           # 设备静止后上报(时间更新)
+    0x0B: "WiFi Parsed Upload",      # WIFI解析经纬度上传
+    0x0C: "LJDW Upload",             # 立即定位指令上报
+    0x0D: "Static Last Point",       # 设备静止后上报最后经纬度
+    0x0E: "GPSDUP Upload",           # 静止状态定时上传
+    0x0F: "Exit Tracking Mode",      # 退出追踪模式
+}
+
+# ---------------------------------------------------------------------------
+# Protocol Numbers That Require a Server Response
+# ---------------------------------------------------------------------------
+PROTOCOLS_REQUIRING_RESPONSE: FrozenSet[int] = frozenset({
+    PROTO_LOGIN,
+    PROTO_HEARTBEAT,
+    PROTO_LBS_ADDRESS_REQ,
+    PROTO_ADDRESS_QUERY,
+    PROTO_TIME_SYNC,
+    # Note: PROTO_LBS_MULTI (0x28) does NOT require response; only 0x2E does
+    PROTO_HEARTBEAT_EXT,
+    PROTO_TIME_SYNC_2,
+    # PROTO_GENERAL_INFO (0x94) does NOT require response per protocol doc
+    PROTO_ALARM_SINGLE_FENCE,
+    PROTO_ALARM_MULTI_FENCE,
+    PROTO_ALARM_LBS_4G,
+    PROTO_LBS_4G_ADDRESS_REQ,
+    PROTO_ALARM_WIFI,
+    PROTO_ATTENDANCE,
+    PROTO_ATTENDANCE_4G,
+    PROTO_BT_PUNCH,
+    # Note: PROTO_BT_LOCATION (0xB3) does NOT require a response per protocol spec
+})
+
+# ---------------------------------------------------------------------------
+# Device Defaults
+# ---------------------------------------------------------------------------
+DEFAULT_DEVICE_TYPE: str = "P240"
+
+# ---------------------------------------------------------------------------
+# Language Codes (used in 0x80 / 0x82 packets)
+# ---------------------------------------------------------------------------
+LANG_CHINESE: int = 0x0001
+LANG_ENGLISH: int = 0x0002
+DEFAULT_LANGUAGE: int = LANG_CHINESE
+DEFAULT_LANGUAGE_BYTES: bytes = b"\x00\x01"
+
+# Server flag placeholder (4 bytes, used in command/message packets)
+SERVER_FLAG_BYTES: bytes = b"\x00\x00\x00\x00"
+
+# ---------------------------------------------------------------------------
+# Attendance Status (from terminal_info byte, bits[5:2])
+# ---------------------------------------------------------------------------
+ATTENDANCE_STATUS_SHIFT: int = 2
+ATTENDANCE_STATUS_MASK: int = 0x0F
+ATTENDANCE_TYPES: Dict[int, str] = {
+    0b0001: "clock_in",
+    0b0010: "clock_out",
+}
+
+# ---------------------------------------------------------------------------
+# GPS Course/Status Bit Fields
+# ---------------------------------------------------------------------------
+COURSE_BIT_REALTIME: int = 0x2000       # bit 13
+COURSE_BIT_POSITIONED: int = 0x1000     # bit 12
+COURSE_BIT_EAST: int = 0x0800           # bit 11
+COURSE_BIT_NORTH: int = 0x0400          # bit 10
+COURSE_MASK: int = 0x03FF               # bits 9-0
+
+# MCC high-bit flag: if set, MNC is 2 bytes instead of 1
+MCC_MNC2_FLAG: int = 0x8000
+
+# ---------------------------------------------------------------------------
+# Voltage Levels (0x00-0x06)
+# ---------------------------------------------------------------------------
+VOLTAGE_LEVELS: Dict[int, str] = {
+    0x00: "shutdown",
+    0x01: "very_low",
+    0x02: "low",
+    0x03: "medium",
+    0x04: "good",
+    0x05: "high",
+    0x06: "full",
+}
+
+# ---------------------------------------------------------------------------
+# Protocol Number -> Human-Readable Name
+# ---------------------------------------------------------------------------
+PROTOCOL_NAMES: Dict[int, str] = {
+    PROTO_LOGIN:               "Login",
+    PROTO_HEARTBEAT:           "Heartbeat",
+    PROTO_LBS_ADDRESS_REQ:     "LBS Address Request",
+    PROTO_ADDRESS_QUERY:       "Address Query",
+    PROTO_TIME_SYNC:           "Time Sync",
+    PROTO_ALARM_ACK:           "Alarm ACK",
+    PROTO_GPS:                 "GPS",
+    PROTO_LBS_MULTI:           "LBS Multi",
+    PROTO_LBS_MULTI_REPLY:     "LBS Multi Reply",
+    PROTO_WIFI:                "WIFI",
+    PROTO_HEARTBEAT_EXT:       "Heartbeat Extended",
+    PROTO_ONLINE_CMD:          "Online Command",
+    PROTO_ONLINE_CMD_REPLY:    "Online Command Reply",
+    PROTO_MESSAGE:             "Message",
+    PROTO_TIME_SYNC_2:         "Time Sync 2",
+    PROTO_GENERAL_INFO:        "General Info",
+    PROTO_ADDRESS_REPLY_EN:    "Address Reply (EN)",
+    PROTO_GPS_4G:              "GPS 4G",
+    PROTO_LBS_4G:              "LBS 4G",
+    PROTO_WIFI_4G:             "WIFI 4G",
+    PROTO_ALARM_SINGLE_FENCE:  "Alarm Single Fence",
+    PROTO_ALARM_MULTI_FENCE:   "Alarm Multi Fence",
+    PROTO_ALARM_LBS_4G:        "Alarm LBS 4G",
+    PROTO_LBS_4G_ADDRESS_REQ:  "LBS 4G Address Request",
+    PROTO_ALARM_WIFI:          "Alarm WIFI",
+    PROTO_ATTENDANCE:          "Attendance",
+    PROTO_ATTENDANCE_4G:       "Attendance 4G",
+    PROTO_BT_PUNCH:            "BT Punch",
+    PROTO_BT_LOCATION:         "BT Location",
+}
--- a/app/protocol/crc.py
+++ b/app/protocol/crc.py
@@ -0,0 +1,76 @@
+"""
+CRC-ITU Implementation for KKS Badge Protocol
+
+Uses CRC-16/X-25 (reflected CRC-CCITT):
+  Polynomial: 0x8408 (reflected 0x1021)
+  Initial value: 0xFFFF
+  Final XOR: 0xFFFF
+"""
+
+from typing import List
+
+# ---------------------------------------------------------------------------
+# Pre-computed CRC lookup table (256 entries, reflected polynomial 0x8408)
+# ---------------------------------------------------------------------------
+
+_CRC_TABLE: List[int] = []
+
+
+def _generate_crc_table() -> List[int]:
+    """Generate the CRC-16/X-25 lookup table for reflected polynomial 0x8408."""
+    table: List[int] = []
+    for i in range(256):
+        crc = i
+        for _ in range(8):
+            if crc & 1:
+                crc = (crc >> 1) ^ 0x8408
+            else:
+                crc >>= 1
+        table.append(crc)
+    return table
+
+
+_CRC_TABLE = _generate_crc_table()
+
+
+def crc_itu(data: bytes) -> int:
+    """
+    Compute the CRC-ITU checksum for the given data.
+
+    Uses the CRC-16/X-25 algorithm (reflected CRC-CCITT with final XOR).
+    For a KKS protocol packet this should be the bytes from (and including)
+    the packet-length field through the serial-number field.
+
+    Parameters
+    ----------
+    data : bytes
+        The data to compute the CRC over.
+
+    Returns
+    -------
+    int
+        16-bit CRC value.
+    """
+    crc: int = 0xFFFF
+    for byte in data:
+        crc = (crc >> 8) ^ _CRC_TABLE[(crc ^ byte) & 0xFF]
+    return crc ^ 0xFFFF
+
+
+def verify_crc(data: bytes, expected_crc: int) -> bool:
+    """
+    Verify that *data* produces the *expected_crc*.
+
+    Parameters
+    ----------
+    data : bytes
+        The data slice to check (same range used when computing the CRC).
+    expected_crc : int
+        The 16-bit CRC value to compare against.
+
+    Returns
+    -------
+    bool
+        ``True`` if the computed CRC matches *expected_crc*.
+    """
+    return crc_itu(data) == (expected_crc & 0xFFFF)
--- a/app/protocol/parser.py
+++ b/app/protocol/parser.py
--- a/app/routers/init.py
+++ b/app/routers/init.py
--- a/app/routers/alarms.py
+++ b/app/routers/alarms.py
@@ -0,0 +1,183 @@
+"""
+Alarms Router - 报警管理接口
+API endpoints for alarm record queries, acknowledgement, and statistics.
+"""
+
+import math
+from datetime import datetime, timezone
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import require_write
+
+from app.database import get_db
+from app.models import AlarmRecord
+from app.schemas import (
+    AlarmAcknowledge,
+    AlarmRecordResponse,
+    APIResponse,
+    PaginatedList,
+)
+
+router = APIRouter(prefix="/api/alarms", tags=["Alarms / 报警管理"])
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[AlarmRecordResponse]],
+    summary="获取报警记录列表 / List alarms",
+)
+async def list_alarms(
+    device_id: int | None = Query(default=None, description="设备ID / Device ID"),
+    alarm_type: str | None = Query(default=None, description="报警类型 / Alarm type"),
+    alarm_source: str | None = Query(default=None, description="报警来源 / Alarm source (single_fence/multi_fence/lbs/wifi)"),
+    acknowledged: bool | None = Query(default=None, description="是否已确认 / Acknowledged status"),
+    start_time: datetime | None = Query(default=None, description="开始时间 / Start time (ISO 8601)"),
+    end_time: datetime | None = Query(default=None, description="结束时间 / End time (ISO 8601)"),
+    sort_order: Literal["asc", "desc"] = Query(default="desc", description="排序方向 / Sort order (asc/desc)"),
+    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 alarm records with filters for device, alarm type, source, acknowledged status, and time range.
+    """
+    query = select(AlarmRecord)
+    count_query = select(func.count(AlarmRecord.id))
+
+    if device_id is not None:
+        query = query.where(AlarmRecord.device_id == device_id)
+        count_query = count_query.where(AlarmRecord.device_id == device_id)
+
+    if alarm_type:
+        query = query.where(AlarmRecord.alarm_type == alarm_type)
+        count_query = count_query.where(AlarmRecord.alarm_type == alarm_type)
+
+    if alarm_source:
+        query = query.where(AlarmRecord.alarm_source == alarm_source)
+        count_query = count_query.where(AlarmRecord.alarm_source == alarm_source)
+
+    if acknowledged is not None:
+        query = query.where(AlarmRecord.acknowledged == acknowledged)
+        count_query = count_query.where(AlarmRecord.acknowledged == acknowledged)
+
+    if start_time:
+        query = query.where(AlarmRecord.recorded_at >= start_time)
+        count_query = count_query.where(AlarmRecord.recorded_at >= start_time)
+
+    if end_time:
+        query = query.where(AlarmRecord.recorded_at <= end_time)
+        count_query = count_query.where(AlarmRecord.recorded_at <= end_time)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    order = AlarmRecord.recorded_at.asc() if sort_order == "asc" else AlarmRecord.recorded_at.desc()
+    query = query.order_by(order).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    alarms = list(result.scalars().all())
+
+    return APIResponse(
+        data=PaginatedList(
+            items=[AlarmRecordResponse.model_validate(a) for a in alarms],
+            total=total,
+            page=page,
+            page_size=page_size,
+            total_pages=math.ceil(total / page_size) if total else 0,
+        )
+    )
+
+
+@router.get(
+    "/stats",
+    response_model=APIResponse[dict],
+    summary="获取报警统计 / Get alarm statistics",
+)
+async def alarm_stats(db: AsyncSession = Depends(get_db)):
+    """
+    获取报警统计：总数、未确认数、按类型分组统计。
+    Get alarm statistics: total, unacknowledged count, and breakdown by type.
+    """
+    # Total alarms
+    total_result = await db.execute(select(func.count(AlarmRecord.id)))
+    total = total_result.scalar() or 0
+
+    # Unacknowledged alarms
+    unack_result = await db.execute(
+        select(func.count(AlarmRecord.id)).where(AlarmRecord.acknowledged == False)  # noqa: E712
+    )
+    unacknowledged = unack_result.scalar() or 0
+
+    # By type
+    type_result = await db.execute(
+        select(AlarmRecord.alarm_type, func.count(AlarmRecord.id))
+        .group_by(AlarmRecord.alarm_type)
+        .order_by(func.count(AlarmRecord.id).desc())
+    )
+    by_type = {row[0]: row[1] for row in type_result.all()}
+
+    return APIResponse(
+        data={
+            "total": total,
+            "unacknowledged": unacknowledged,
+            "acknowledged": total - unacknowledged,
+            "by_type": by_type,
+        }
+    )
+
+
+@router.get(
+    "/{alarm_id}",
+    response_model=APIResponse[AlarmRecordResponse],
+    summary="获取报警详情 / Get alarm details",
+)
+async def get_alarm(alarm_id: int, db: AsyncSession = Depends(get_db)):
+    """
+    按ID获取报警记录详情。
+    Get alarm record details by ID.
+    """
+    result = await db.execute(
+        select(AlarmRecord).where(AlarmRecord.id == alarm_id)
+    )
+    alarm = result.scalar_one_or_none()
+    if alarm is None:
+        raise HTTPException(status_code=404, detail=f"Alarm {alarm_id} not found / 未找到报警记录{alarm_id}")
+    return APIResponse(data=AlarmRecordResponse.model_validate(alarm))
+
+
+@router.put(
+    "/{alarm_id}/acknowledge",
+    response_model=APIResponse[AlarmRecordResponse],
+    summary="确认报警 / Acknowledge alarm",
+    dependencies=[Depends(require_write)],
+)
+async def acknowledge_alarm(
+    alarm_id: int,
+    body: AlarmAcknowledge | None = None,
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    确认（或取消确认）报警记录。
+    Acknowledge (or un-acknowledge) an alarm record.
+    """
+    result = await db.execute(
+        select(AlarmRecord).where(AlarmRecord.id == alarm_id)
+    )
+    alarm = result.scalar_one_or_none()
+    if alarm is None:
+        raise HTTPException(status_code=404, detail=f"Alarm {alarm_id} not found / 未找到报警记录{alarm_id}")
+
+    acknowledged = body.acknowledged if body else True
+    alarm.acknowledged = acknowledged
+
+    await db.flush()
+    await db.refresh(alarm)
+    return APIResponse(
+        message="Alarm acknowledged / 报警已确认" if acknowledged else "Alarm un-acknowledged / 已取消确认",
+        data=AlarmRecordResponse.model_validate(alarm),
+    )
--- a/app/routers/api_keys.py
+++ b/app/routers/api_keys.py
@@ -0,0 +1,142 @@
+"""
+API Keys Router - API密钥管理接口
+Endpoints for creating, listing, updating, and deactivating API keys.
+Admin permission required.
+"""
+
+import secrets
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import require_admin, _hash_key
+from app.models import ApiKey
+from app.schemas import (
+    APIResponse,
+    ApiKeyCreate,
+    ApiKeyCreateResponse,
+    ApiKeyResponse,
+    ApiKeyUpdate,
+    PaginatedList,
+)
+
+import math
+
+router = APIRouter(prefix="/api/keys", tags=["API Keys / 密钥管理"])
+
+
+def _generate_key() -> str:
+    """Generate a random 32-char hex API key."""
+    return secrets.token_hex(16)
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[ApiKeyResponse]],
+    summary="列出API密钥 / List API keys",
+    dependencies=[Depends(require_admin)],
+)
+async def list_keys(
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=20, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+):
+    """列出所有API密钥（不返回密钥值）/ List all API keys (key values are never shown)."""
+    count_result = await db.execute(select(func.count(ApiKey.id)))
+    total = count_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    result = await db.execute(
+        select(ApiKey).order_by(ApiKey.created_at.desc()).offset(offset).limit(page_size)
+    )
+    keys = list(result.scalars().all())
+
+    return APIResponse(
+        data=PaginatedList(
+            items=[ApiKeyResponse.model_validate(k) for k in keys],
+            total=total,
+            page=page,
+            page_size=page_size,
+            total_pages=math.ceil(total / page_size) if total else 0,
+        )
+    )
+
+
+@router.post(
+    "",
+    response_model=APIResponse[ApiKeyCreateResponse],
+    status_code=201,
+    summary="创建API密钥 / Create API key",
+    dependencies=[Depends(require_admin)],
+)
+async def create_key(body: ApiKeyCreate, db: AsyncSession = Depends(get_db)):
+    """创建新的API密钥。明文密钥仅在创建时返回一次。
+    Create a new API key. The plaintext key is returned only once."""
+    raw_key = _generate_key()
+    key_hash = _hash_key(raw_key)
+
+    db_key = ApiKey(
+        key_hash=key_hash,
+        name=body.name,
+        permissions=body.permissions,
+    )
+    db.add(db_key)
+    await db.flush()
+    await db.refresh(db_key)
+
+    # Build response with plaintext key included (shown once)
+    base_data = ApiKeyResponse.model_validate(db_key).model_dump()
+    base_data["key"] = raw_key
+    response_data = ApiKeyCreateResponse(**base_data)
+
+    return APIResponse(
+        message="API key created. Store the key securely — it won't be shown again. / API密钥已创建，请妥善保管",
+        data=response_data,
+    )
+
+
+@router.put(
+    "/{key_id}",
+    response_model=APIResponse[ApiKeyResponse],
+    summary="更新API密钥 / Update API key",
+    dependencies=[Depends(require_admin)],
+)
+async def update_key(
+    key_id: int, body: ApiKeyUpdate, db: AsyncSession = Depends(get_db)
+):
+    """更新API密钥的名称、权限或激活状态 / Update key name, permissions, or active status."""
+    result = await db.execute(select(ApiKey).where(ApiKey.id == key_id))
+    db_key = result.scalar_one_or_none()
+    if db_key is None:
+        raise HTTPException(status_code=404, detail="API key not found / 未找到密钥")
+
+    update_data = body.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(db_key, field, value)
+
+    await db.flush()
+    await db.refresh(db_key)
+    return APIResponse(
+        message="API key updated / 密钥已更新",
+        data=ApiKeyResponse.model_validate(db_key),
+    )
+
+
+@router.delete(
+    "/{key_id}",
+    response_model=APIResponse,
+    summary="停用API密钥 / Deactivate API key",
+    dependencies=[Depends(require_admin)],
+)
+async def deactivate_key(key_id: int, db: AsyncSession = Depends(get_db)):
+    """停用API密钥（软删除）/ Deactivate an API key (soft delete)."""
+    result = await db.execute(select(ApiKey).where(ApiKey.id == key_id))
+    db_key = result.scalar_one_or_none()
+    if db_key is None:
+        raise HTTPException(status_code=404, detail="API key not found / 未找到密钥")
+
+    db_key.is_active = False
+    await db.flush()
+    return APIResponse(message="API key deactivated / 密钥已停用")
--- a/app/routers/attendance.py
+++ b/app/routers/attendance.py
@@ -0,0 +1,204 @@
+"""
+Attendance Router - 考勤管理接口
+API endpoints for attendance record queries and statistics.
+"""
+
+import math
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.models import AttendanceRecord
+from app.schemas import (
+    APIResponse,
+    AttendanceRecordResponse,
+    PaginatedList,
+)
+from app.services import device_service
+
+router = APIRouter(prefix="/api/attendance", tags=["Attendance / 考勤管理"])
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[AttendanceRecordResponse]],
+    summary="获取考勤记录列表 / List attendance records",
+)
+async def list_attendance(
+    device_id: int | None = Query(default=None, description="设备ID / Device ID"),
+    attendance_type: str | None = Query(default=None, description="考勤类型 / Attendance type"),
+    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 attendance records with filters for device, type, and time range.
+    """
+    query = select(AttendanceRecord)
+    count_query = select(func.count(AttendanceRecord.id))
+
+    if device_id is not None:
+        query = query.where(AttendanceRecord.device_id == device_id)
+        count_query = count_query.where(AttendanceRecord.device_id == device_id)
+
+    if attendance_type:
+        query = query.where(AttendanceRecord.attendance_type == attendance_type)
+        count_query = count_query.where(AttendanceRecord.attendance_type == attendance_type)
+
+    if start_time:
+        query = query.where(AttendanceRecord.recorded_at >= start_time)
+        count_query = count_query.where(AttendanceRecord.recorded_at >= start_time)
+
+    if end_time:
+        query = query.where(AttendanceRecord.recorded_at <= end_time)
+        count_query = count_query.where(AttendanceRecord.recorded_at <= end_time)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    query = query.order_by(AttendanceRecord.recorded_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    records = list(result.scalars().all())
+
+    return APIResponse(
+        data=PaginatedList(
+            items=[AttendanceRecordResponse.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(
+    "/stats",
+    response_model=APIResponse[dict],
+    summary="获取考勤统计 / Get attendance statistics",
+)
+async def attendance_stats(
+    device_id: int | None = Query(default=None, description="设备ID / Device ID (optional)"),
+    start_time: datetime | None = Query(default=None, description="开始时间 / Start time"),
+    end_time: datetime | None = Query(default=None, description="结束时间 / End time"),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    获取考勤统计：总记录数、按类型分组统计、按设备分组统计。
+    Get attendance statistics: total records, breakdown by type and by device.
+    """
+    base_filter = []
+    if device_id is not None:
+        base_filter.append(AttendanceRecord.device_id == device_id)
+    if start_time:
+        base_filter.append(AttendanceRecord.recorded_at >= start_time)
+    if end_time:
+        base_filter.append(AttendanceRecord.recorded_at <= end_time)
+
+    # Total count
+    total_q = select(func.count(AttendanceRecord.id)).where(*base_filter) if base_filter else select(func.count(AttendanceRecord.id))
+    total_result = await db.execute(total_q)
+    total = total_result.scalar() or 0
+
+    # By type
+    type_q = select(
+        AttendanceRecord.attendance_type, func.count(AttendanceRecord.id)
+    ).group_by(AttendanceRecord.attendance_type)
+    if base_filter:
+        type_q = type_q.where(*base_filter)
+    type_result = await db.execute(type_q)
+    by_type = {row[0]: row[1] for row in type_result.all()}
+
+    # By device (top 20)
+    device_q = select(
+        AttendanceRecord.device_id, func.count(AttendanceRecord.id)
+    ).group_by(AttendanceRecord.device_id).order_by(
+        func.count(AttendanceRecord.id).desc()
+    ).limit(20)
+    if base_filter:
+        device_q = device_q.where(*base_filter)
+    device_result = await db.execute(device_q)
+    by_device = {str(row[0]): row[1] for row in device_result.all()}
+
+    return APIResponse(
+        data={
+            "total": total,
+            "by_type": by_type,
+            "by_device": by_device,
+        }
+    )
+
+
+@router.get(
+    "/device/{device_id}",
+    response_model=APIResponse[PaginatedList[AttendanceRecordResponse]],
+    summary="获取设备考勤记录 / Get device attendance records",
+)
+async def device_attendance(
+    device_id: int,
+    start_time: datetime | None = Query(default=None, description="开始时间 / Start time"),
+    end_time: datetime | None = Query(default=None, description="结束时间 / End time"),
+    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),
+):
+    """
+    获取指定设备的考勤记录。
+    Get attendance records for a specific 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}")
+
+    query = select(AttendanceRecord).where(AttendanceRecord.device_id == device_id)
+    count_query = select(func.count(AttendanceRecord.id)).where(AttendanceRecord.device_id == device_id)
+
+    if start_time:
+        query = query.where(AttendanceRecord.recorded_at >= start_time)
+        count_query = count_query.where(AttendanceRecord.recorded_at >= start_time)
+
+    if end_time:
+        query = query.where(AttendanceRecord.recorded_at <= end_time)
+        count_query = count_query.where(AttendanceRecord.recorded_at <= end_time)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    query = query.order_by(AttendanceRecord.recorded_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    records = list(result.scalars().all())
+
+    return APIResponse(
+        data=PaginatedList(
+            items=[AttendanceRecordResponse.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,
+        )
+    )
+
+
+# NOTE: /{attendance_id} must be after /stats and /device/{device_id} to avoid route conflicts
+@router.get(
+    "/{attendance_id}",
+    response_model=APIResponse[AttendanceRecordResponse],
+    summary="获取考勤记录详情 / Get attendance record",
+)
+async def get_attendance(attendance_id: int, db: AsyncSession = Depends(get_db)):
+    """按ID获取考勤记录详情 / Get attendance record details by ID."""
+    result = await db.execute(
+        select(AttendanceRecord).where(AttendanceRecord.id == attendance_id)
+    )
+    record = result.scalar_one_or_none()
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Attendance {attendance_id} not found")
+    return APIResponse(data=AttendanceRecordResponse.model_validate(record))
--- a/app/routers/beacons.py
+++ b/app/routers/beacons.py
@@ -0,0 +1,104 @@
+"""
+Beacons Router - 蓝牙信标管理接口
+API endpoints for managing Bluetooth beacon configuration.
+"""
+
+import math
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import require_write
+
+from app.database import get_db
+from app.schemas import (
+    APIResponse,
+    BeaconConfigCreate,
+    BeaconConfigResponse,
+    BeaconConfigUpdate,
+    PaginatedList,
+)
+from app.services import beacon_service
+
+router = APIRouter(prefix="/api/beacons", tags=["Beacons / 蓝牙信标"])
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[BeaconConfigResponse]],
+    summary="获取信标列表 / List beacons",
+)
+async def list_beacons(
+    status: str | None = Query(default=None, description="状态筛选 (active/inactive)"),
+    search: str | None = Query(default=None, description="搜索 MAC/名称/区域"),
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=20, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+):
+    records, total = await beacon_service.get_beacons(
+        db, page=page, page_size=page_size, status_filter=status, search=search
+    )
+    return APIResponse(
+        data=PaginatedList(
+            items=[BeaconConfigResponse.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(
+    "/{beacon_id}",
+    response_model=APIResponse[BeaconConfigResponse],
+    summary="获取信标详情 / Get beacon",
+)
+async def get_beacon(beacon_id: int, db: AsyncSession = Depends(get_db)):
+    beacon = await beacon_service.get_beacon(db, beacon_id)
+    if beacon is None:
+        raise HTTPException(status_code=404, detail="Beacon not found")
+    return APIResponse(data=BeaconConfigResponse.model_validate(beacon))
+
+
+@router.post(
+    "",
+    response_model=APIResponse[BeaconConfigResponse],
+    status_code=201,
+    summary="添加信标 / Create beacon",
+    dependencies=[Depends(require_write)],
+)
+async def create_beacon(body: BeaconConfigCreate, db: AsyncSession = Depends(get_db)):
+    existing = await beacon_service.get_beacon_by_mac(db, body.beacon_mac)
+    if existing:
+        raise HTTPException(status_code=400, detail=f"Beacon MAC {body.beacon_mac} already exists")
+    beacon = await beacon_service.create_beacon(db, body)
+    return APIResponse(message="Beacon created", data=BeaconConfigResponse.model_validate(beacon))
+
+
+@router.put(
+    "/{beacon_id}",
+    response_model=APIResponse[BeaconConfigResponse],
+    summary="更新信标 / Update beacon",
+    dependencies=[Depends(require_write)],
+)
+async def update_beacon(
+    beacon_id: int, body: BeaconConfigUpdate, db: AsyncSession = Depends(get_db)
+):
+    beacon = await beacon_service.update_beacon(db, beacon_id, body)
+    if beacon is None:
+        raise HTTPException(status_code=404, detail="Beacon not found")
+    return APIResponse(message="Beacon updated", data=BeaconConfigResponse.model_validate(beacon))
+
+
+@router.delete(
+    "/{beacon_id}",
+    response_model=APIResponse,
+    summary="删除信标 / Delete beacon",
+    dependencies=[Depends(require_write)],
+)
+async def delete_beacon(beacon_id: int, db: AsyncSession = Depends(get_db)):
+    success = await beacon_service.delete_beacon(db, beacon_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Beacon not found")
+    return APIResponse(message="Beacon deleted")
--- a/app/routers/bluetooth.py
+++ b/app/routers/bluetooth.py
@@ -0,0 +1,159 @@
+"""
+Bluetooth Router - 蓝牙数据接口
+API endpoints for querying Bluetooth punch and location records.
+"""
+
+import math
+from datetime import datetime
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.models import BluetoothRecord
+from app.schemas import (
+    APIResponse,
+    BluetoothRecordResponse,
+    PaginatedList,
+)
+from app.services import device_service
+
+router = APIRouter(prefix="/api/bluetooth", tags=["Bluetooth / 蓝牙数据"])
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[BluetoothRecordResponse]],
+    summary="获取蓝牙记录列表 / List bluetooth records",
+)
+async def list_bluetooth_records(
+    device_id: int | None = Query(default=None, description="设备ID / Device ID"),
+    record_type: str | None = Query(default=None, description="记录类型 / Record type (punch/location)"),
+    beacon_mac: str | None = Query(default=None, description="信标MAC / Beacon MAC filter"),
+    start_time: datetime | None = Query(default=None, description="开始时间 / Start time (ISO 8601)"),
+    end_time: datetime | None = Query(default=None, description="结束时间 / End time (ISO 8601)"),
+    sort_order: Literal["asc", "desc"] = Query(default="desc", description="排序方向 / Sort order (asc/desc)"),
+    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),
+):
+    """
+    获取蓝牙数据记录列表，支持按设备、记录类型、信标MAC、时间范围过滤。
+    List Bluetooth records with filters for device, record type, beacon MAC, and time range.
+    """
+    query = select(BluetoothRecord)
+    count_query = select(func.count(BluetoothRecord.id))
+
+    if device_id is not None:
+        query = query.where(BluetoothRecord.device_id == device_id)
+        count_query = count_query.where(BluetoothRecord.device_id == device_id)
+
+    if record_type:
+        query = query.where(BluetoothRecord.record_type == record_type)
+        count_query = count_query.where(BluetoothRecord.record_type == record_type)
+
+    if beacon_mac:
+        query = query.where(BluetoothRecord.beacon_mac == beacon_mac)
+        count_query = count_query.where(BluetoothRecord.beacon_mac == beacon_mac)
+
+    if start_time:
+        query = query.where(BluetoothRecord.recorded_at >= start_time)
+        count_query = count_query.where(BluetoothRecord.recorded_at >= start_time)
+
+    if end_time:
+        query = query.where(BluetoothRecord.recorded_at <= end_time)
+        count_query = count_query.where(BluetoothRecord.recorded_at <= end_time)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    order = BluetoothRecord.recorded_at.asc() if sort_order == "asc" else BluetoothRecord.recorded_at.desc()
+    query = query.order_by(order).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    records = list(result.scalars().all())
+
+    return APIResponse(
+        data=PaginatedList(
+            items=[BluetoothRecordResponse.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(
+    "/device/{device_id}",
+    response_model=APIResponse[PaginatedList[BluetoothRecordResponse]],
+    summary="获取设备蓝牙记录 / Get bluetooth records for device",
+)
+async def device_bluetooth_records(
+    device_id: int,
+    record_type: str | None = Query(default=None, description="记录类型 / Record type (punch/location)"),
+    start_time: datetime | None = Query(default=None, description="开始时间 / Start time"),
+    end_time: datetime | None = Query(default=None, description="结束时间 / End time"),
+    page: int = Query(default=1, ge=1, description="页码"),
+    page_size: int = Query(default=20, ge=1, le=100, description="每页数量"),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    获取指定设备的蓝牙数据记录。
+    Get Bluetooth records for a specific device.
+    """
+    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}")
+
+    query = select(BluetoothRecord).where(BluetoothRecord.device_id == device_id)
+    count_query = select(func.count(BluetoothRecord.id)).where(BluetoothRecord.device_id == device_id)
+
+    if record_type:
+        query = query.where(BluetoothRecord.record_type == record_type)
+        count_query = count_query.where(BluetoothRecord.record_type == record_type)
+
+    if start_time:
+        query = query.where(BluetoothRecord.recorded_at >= start_time)
+        count_query = count_query.where(BluetoothRecord.recorded_at >= start_time)
+
+    if end_time:
+        query = query.where(BluetoothRecord.recorded_at <= end_time)
+        count_query = count_query.where(BluetoothRecord.recorded_at <= end_time)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    query = query.order_by(BluetoothRecord.recorded_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    records = list(result.scalars().all())
+
+    return APIResponse(
+        data=PaginatedList(
+            items=[BluetoothRecordResponse.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,
+        )
+    )
+
+
+# NOTE: /{record_id} must be after /device/{device_id} to avoid route conflicts
+@router.get(
+    "/{record_id}",
+    response_model=APIResponse[BluetoothRecordResponse],
+    summary="获取蓝牙记录详情 / Get bluetooth record",
+)
+async def get_bluetooth_record(record_id: int, db: AsyncSession = Depends(get_db)):
+    """按ID获取蓝牙记录详情 / Get bluetooth record details by ID."""
+    result = await db.execute(
+        select(BluetoothRecord).where(BluetoothRecord.id == record_id)
+    )
+    record = result.scalar_one_or_none()
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Bluetooth record {record_id} not found")
+    return APIResponse(data=BluetoothRecordResponse.model_validate(record))
--- a/app/routers/commands.py
+++ b/app/routers/commands.py
@@ -0,0 +1,330 @@
+"""
+Commands Router - 指令管理接口
+API endpoints for sending commands / messages to devices and viewing command history.
+"""
+
+import logging
+import math
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.config import settings
+from app.extensions import limiter
+from app.schemas import (
+    APIResponse,
+    BatchCommandRequest,
+    BatchCommandResponse,
+    BatchCommandResult,
+    CommandResponse,
+    PaginatedList,
+)
+from app.dependencies import require_write
+from app.services import command_service, device_service
+from app.services import tcp_command_service
+
+router = APIRouter(prefix="/api/commands", tags=["Commands / 指令管理"])
+
+
+# ---------------------------------------------------------------------------
+# Request schemas specific to this router
+# ---------------------------------------------------------------------------
+
+
+class SendCommandRequest(BaseModel):
+    """Request body for sending a command to a device."""
+    device_id: int | None = Field(None, description="设备ID / Device ID (provide device_id or imei)")
+    imei: str | None = Field(None, description="IMEI号 / IMEI number (provide device_id or imei)")
+    command_type: str = Field(..., max_length=30, description="指令类型 / Command type (e.g. online_cmd)")
+    command_content: str = Field(..., max_length=500, description="指令内容 / Command content")
+
+
+class SendMessageRequest(BaseModel):
+    """Request body for sending a message (0x82) to a device."""
+    device_id: int | None = Field(None, description="设备ID / Device ID (provide device_id or imei)")
+    imei: str | None = Field(None, description="IMEI号 / IMEI number (provide device_id or imei)")
+    message: str = Field(..., max_length=500, description="消息内容 / Message content")
+
+
+class SendTTSRequest(BaseModel):
+    """Request body for sending a TTS voice broadcast to a device."""
+    device_id: int | None = Field(None, description="设备ID / Device ID (provide device_id or imei)")
+    imei: str | None = Field(None, description="IMEI号 / IMEI number (provide device_id or imei)")
+    text: str = Field(..., min_length=1, max_length=200, description="语音播报文本 / TTS text content")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+async def _resolve_device(
+    db: AsyncSession,
+    device_id: int | None,
+    imei: str | None,
+):
+    """Resolve a device from either device_id or imei. Returns the Device ORM instance."""
+    if device_id is None and imei is None:
+        raise HTTPException(
+            status_code=400,
+            detail="Either device_id or imei must be provided / 必须提供 device_id 或 imei",
+        )
+
+    if device_id is not None:
+        device = await device_service.get_device(db, device_id)
+    else:
+        device = await device_service.get_device_by_imei(db, imei)
+
+    if device is None:
+        identifier = f"ID={device_id}" if device_id else f"IMEI={imei}"
+        raise HTTPException(
+            status_code=404,
+            detail=f"Device {identifier} not found / 未找到设备 {identifier}",
+        )
+    return device
+
+
+async def _send_to_device(
+    db: AsyncSession,
+    device,
+    command_type: str,
+    command_content: str,
+    executor,
+    success_msg: str,
+    fail_msg: str,
+):
+    """Common logic for sending command/message/tts to a device via TCP.
+
+    Parameters
+    ----------
+    executor : async callable
+        The actual send function, e.g. tcp_command_service.send_command(...)
+    """
+    if not tcp_command_service.is_device_online(device.imei):
+        raise HTTPException(
+            status_code=400,
+            detail=f"Device {device.imei} is not online / 设备 {device.imei} 不在线",
+        )
+
+    command_log = await command_service.create_command(
+        db,
+        device_id=device.id,
+        command_type=command_type,
+        command_content=command_content,
+    )
+
+    try:
+        await executor()
+    except Exception as e:
+        logging.getLogger(__name__).error("Command send failed: %s", e)
+        command_log.status = "failed"
+        await db.flush()
+        await db.refresh(command_log)
+        raise HTTPException(
+            status_code=500,
+            detail=fail_msg,
+        )
+
+    command_log.status = "sent"
+    command_log.sent_at = datetime.now(timezone.utc)
+    await db.flush()
+    await db.refresh(command_log)
+
+    return APIResponse(
+        message=success_msg,
+        data=CommandResponse.model_validate(command_log),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[CommandResponse]],
+    summary="获取指令历史 / List command history",
+)
+async def list_commands(
+    device_id: int | None = Query(default=None, description="设备ID / Device ID"),
+    command_type: str | None = Query(default=None, description="指令类型 / Command type (online_cmd/message/tts)"),
+    status: str | None = Query(default=None, description="指令状态 / Command status (pending/sent/success/failed)"),
+    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 command history with optional device, command type and status filters.
+    """
+    commands, total = await command_service.get_commands(
+        db, device_id=device_id, command_type=command_type, status=status, page=page, page_size=page_size
+    )
+    return APIResponse(
+        data=PaginatedList(
+            items=[CommandResponse.model_validate(c) for c in commands],
+            total=total,
+            page=page,
+            page_size=page_size,
+            total_pages=math.ceil(total / page_size) if total else 0,
+        )
+    )
+
+
+@router.post(
+    "/send",
+    response_model=APIResponse[CommandResponse],
+    status_code=201,
+    summary="发送指令 / Send command to device",
+    dependencies=[Depends(require_write)],
+)
+async def send_command(body: SendCommandRequest, db: AsyncSession = Depends(get_db)):
+    """
+    向设备发送指令（通过TCP连接下发）。
+    Send a command to a device via the TCP connection.
+    Requires the device to be online.
+    """
+    device = await _resolve_device(db, body.device_id, body.imei)
+    return await _send_to_device(
+        db, device,
+        command_type=body.command_type,
+        command_content=body.command_content,
+        executor=lambda: tcp_command_service.send_command(
+            device.imei, body.command_type, body.command_content
+        ),
+        success_msg="Command sent successfully / 指令发送成功",
+        fail_msg="Failed to send command / 指令发送失败",
+    )
+
+
+@router.post(
+    "/message",
+    response_model=APIResponse[CommandResponse],
+    status_code=201,
+    summary="发送留言 / Send message to device (0x82)",
+    dependencies=[Depends(require_write)],
+)
+async def send_message(body: SendMessageRequest, db: AsyncSession = Depends(get_db)):
+    """
+    向设备发送留言消息（协议号 0x82）。
+    Send a text message to a device using protocol 0x82.
+    """
+    device = await _resolve_device(db, body.device_id, body.imei)
+    return await _send_to_device(
+        db, device,
+        command_type="message",
+        command_content=body.message,
+        executor=lambda: tcp_command_service.send_message(device.imei, body.message),
+        success_msg="Message sent successfully / 留言发送成功",
+        fail_msg="Failed to send message / 留言发送失败",
+    )
+
+
+@router.post(
+    "/tts",
+    response_model=APIResponse[CommandResponse],
+    status_code=201,
+    summary="语音下发 / Send TTS voice broadcast to device",
+    dependencies=[Depends(require_write)],
+)
+async def send_tts(body: SendTTSRequest, db: AsyncSession = Depends(get_db)):
+    """
+    向设备发送 TTS 语音播报（通过 0x80 在线指令，TTS 命令格式）。
+    Send a TTS voice broadcast to a device via online command (0x80).
+    The device will use its built-in TTS engine to speak the text aloud.
+    """
+    device = await _resolve_device(db, body.device_id, body.imei)
+    tts_command = f"TTS,{body.text}"
+    return await _send_to_device(
+        db, device,
+        command_type="tts",
+        command_content=tts_command,
+        executor=lambda: tcp_command_service.send_command(
+            device.imei, "tts", tts_command
+        ),
+        success_msg="TTS sent successfully / 语音下发成功",
+        fail_msg="Failed to send TTS / 语音下发失败",
+    )
+
+
+@router.post(
+    "/batch",
+    response_model=APIResponse[BatchCommandResponse],
+    status_code=201,
+    summary="批量发送指令 / Batch send command to multiple devices",
+    dependencies=[Depends(require_write)],
+)
+@limiter.limit(settings.RATE_LIMIT_WRITE)
+async def batch_send_command(request: Request, body: BatchCommandRequest, db: AsyncSession = Depends(get_db)):
+    """
+    向多台设备批量发送同一指令，最多100台。
+    Send the same command to multiple devices (up to 100). Skips offline devices.
+    """
+    # Resolve devices in single query (mutual exclusion validated by schema)
+    if body.device_ids:
+        devices = await device_service.get_devices_by_ids(db, body.device_ids)
+    else:
+        devices = await device_service.get_devices_by_imeis(db, body.imeis)
+
+    results = []
+    for device in devices:
+        if not tcp_command_service.is_device_online(device.imei):
+            results.append(BatchCommandResult(
+                device_id=device.id, imei=device.imei,
+                success=False, error="Device offline",
+            ))
+            continue
+
+        try:
+            cmd_log = await command_service.create_command(
+                db,
+                device_id=device.id,
+                command_type=body.command_type,
+                command_content=body.command_content,
+            )
+            await tcp_command_service.send_command(
+                device.imei, body.command_type, body.command_content
+            )
+            cmd_log.status = "sent"
+            cmd_log.sent_at = datetime.now(timezone.utc)
+            await db.flush()
+            await db.refresh(cmd_log)
+            results.append(BatchCommandResult(
+                device_id=device.id, imei=device.imei,
+                success=True, command_id=cmd_log.id,
+            ))
+        except Exception as e:
+            logging.getLogger(__name__).error("Batch cmd failed for %s: %s", device.imei, e)
+            results.append(BatchCommandResult(
+                device_id=device.id, imei=device.imei,
+                success=False, error="Send failed",
+            ))
+
+    sent = sum(1 for r in results if r.success)
+    failed = len(results) - sent
+    return APIResponse(
+        message=f"Batch command: {sent} sent, {failed} failed",
+        data=BatchCommandResponse(
+            total=len(results), sent=sent, failed=failed, results=results,
+        ),
+    )
+
+
+@router.get(
+    "/{command_id}",
+    response_model=APIResponse[CommandResponse],
+    summary="获取指令详情 / Get command details",
+)
+async def get_command(command_id: int, db: AsyncSession = Depends(get_db)):
+    """
+    按ID获取指令详情。
+    Get command log details by ID.
+    """
+    command = await command_service.get_command(db, command_id)
+    if command is None:
+        raise HTTPException(status_code=404, detail=f"Command {command_id} not found / 未找到指令{command_id}")
+    return APIResponse(data=CommandResponse.model_validate(command))
--- a/app/routers/devices.py
+++ b/app/routers/devices.py
@@ -0,0 +1,253 @@
+"""
+Devices Router - 设备管理接口
+API endpoints for device CRUD operations and statistics.
+"""
+
+import math
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.schemas import (
+    APIResponse,
+    BatchDeviceCreateRequest,
+    BatchDeviceCreateResponse,
+    BatchDeviceCreateResult,
+    BatchDeviceDeleteRequest,
+    BatchDeviceUpdateRequest,
+    DeviceCreate,
+    DeviceResponse,
+    DeviceUpdate,
+    PaginatedList,
+)
+from app.config import settings
+from app.dependencies import require_write
+from app.extensions import limiter
+from app.schemas import LocationRecordResponse
+from app.services import device_service, location_service
+
+router = APIRouter(prefix="/api/devices", tags=["Devices / 设备管理"])
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[DeviceResponse]],
+    summary="获取设备列表 / List devices",
+)
+async def list_devices(
+    page: int = Query(default=1, ge=1, description="页码 / Page number"),
+    page_size: int = Query(default=20, ge=1, le=100, description="每页数量 / Items per page"),
+    status: str | None = Query(default=None, description="状态过滤 / Status filter (online/offline)"),
+    search: str | None = Query(default=None, description="搜索IMEI或名称 / Search by IMEI or name"),
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    获取设备列表，支持分页、状态过滤和搜索。
+    List devices with pagination, optional status filter, and search.
+    """
+    devices, total = await device_service.get_devices(
+        db, page=page, page_size=page_size, status_filter=status, search=search
+    )
+    return APIResponse(
+        data=PaginatedList(
+            items=[DeviceResponse.model_validate(d) for d in devices],
+            total=total,
+            page=page,
+            page_size=page_size,
+            total_pages=math.ceil(total / page_size) if total else 0,
+        )
+    )
+
+
+@router.get(
+    "/stats",
+    response_model=APIResponse[dict],
+    summary="获取设备统计 / Get device statistics",
+)
+async def device_stats(db: AsyncSession = Depends(get_db)):
+    """
+    获取设备统计信息：总数、在线、离线。
+    Get device statistics: total, online, offline counts.
+    """
+    stats = await device_service.get_device_stats(db)
+    return APIResponse(data=stats)
+
+
+@router.get(
+    "/imei/{imei}",
+    response_model=APIResponse[DeviceResponse],
+    summary="按IMEI查询设备 / Get device by IMEI",
+)
+async def get_device_by_imei(imei: str, db: AsyncSession = Depends(get_db)):
+    """
+    按IMEI号查询设备信息。
+    Get device details by IMEI number.
+    """
+    device = await device_service.get_device_by_imei(db, imei)
+    if device is None:
+        raise HTTPException(status_code=404, detail=f"Device with IMEI {imei} not found / 未找到IMEI为{imei}的设备")
+    return APIResponse(data=DeviceResponse.model_validate(device))
+
+
+@router.get(
+    "/all-latest-locations",
+    response_model=APIResponse[list[LocationRecordResponse]],
+    summary="获取所有在线设备位置 / Get all online device locations",
+)
+async def all_latest_locations(db: AsyncSession = Depends(get_db)):
+    """
+    获取所有在线设备的最新位置，用于地图总览。
+    Get latest location for all online devices, for map overview.
+    """
+    records = await location_service.get_all_online_latest_locations(db)
+    return APIResponse(data=[LocationRecordResponse.model_validate(r) for r in records])
+
+
+@router.post(
+    "/batch",
+    response_model=APIResponse[BatchDeviceCreateResponse],
+    status_code=201,
+    summary="批量创建设备 / Batch create devices",
+    dependencies=[Depends(require_write)],
+)
+@limiter.limit(settings.RATE_LIMIT_WRITE)
+async def batch_create_devices(request: Request, body: BatchDeviceCreateRequest, db: AsyncSession = Depends(get_db)):
+    """
+    批量注册设备（最多500台），跳过IMEI重复的设备。
+    Batch register devices (up to 500). Skips devices with duplicate IMEIs.
+    """
+    results = await device_service.batch_create_devices(db, body.devices)
+    created = sum(1 for r in results if r["success"])
+    failed = len(results) - created
+    return APIResponse(
+        message=f"Batch create: {created} created, {failed} failed",
+        data=BatchDeviceCreateResponse(
+            total=len(results),
+            created=created,
+            failed=failed,
+            results=[BatchDeviceCreateResult(**r) for r in results],
+        ),
+    )
+
+
+@router.put(
+    "/batch",
+    response_model=APIResponse[dict],
+    summary="批量更新设备 / Batch update devices",
+    dependencies=[Depends(require_write)],
+)
+@limiter.limit(settings.RATE_LIMIT_WRITE)
+async def batch_update_devices(request: Request, body: BatchDeviceUpdateRequest, db: AsyncSession = Depends(get_db)):
+    """
+    批量更新设备信息（名称、状态等），最多500台。
+    Batch update device fields (name, status, etc.) for up to 500 devices.
+    """
+    results = await device_service.batch_update_devices(db, body.device_ids, body.update)
+    updated = sum(1 for r in results if r["success"])
+    failed = len(results) - updated
+    return APIResponse(
+        message=f"Batch update: {updated} updated, {failed} failed",
+        data={"total": len(results), "updated": updated, "failed": failed, "results": results},
+    )
+
+
+@router.post(
+    "/batch-delete",
+    response_model=APIResponse[dict],
+    summary="批量删除设备 / Batch delete devices",
+    dependencies=[Depends(require_write)],
+)
+@limiter.limit(settings.RATE_LIMIT_WRITE)
+async def batch_delete_devices(
+    request: Request,
+    body: BatchDeviceDeleteRequest,
+    db: AsyncSession = Depends(get_db),
+):
+    """
+    批量删除设备（最多100台）。通过 POST body 传递 device_ids 列表。
+    Batch delete devices (up to 100). Pass device_ids in request body.
+    """
+    results = await device_service.batch_delete_devices(db, body.device_ids)
+    deleted = sum(1 for r in results if r["success"])
+    failed = len(results) - deleted
+    return APIResponse(
+        message=f"Batch delete: {deleted} deleted, {failed} failed",
+        data={"total": len(results), "deleted": deleted, "failed": failed, "results": results},
+    )
+
+
+@router.get(
+    "/{device_id}",
+    response_model=APIResponse[DeviceResponse],
+    summary="获取设备详情 / Get device details",
+)
+async def get_device(device_id: int, db: AsyncSession = Depends(get_db)):
+    """
+    按ID获取设备详细信息。
+    Get device details by ID.
+    """
+    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}")
+    return APIResponse(data=DeviceResponse.model_validate(device))
+
+
+@router.post(
+    "",
+    response_model=APIResponse[DeviceResponse],
+    status_code=201,
+    summary="创建设备 / Create device",
+    dependencies=[Depends(require_write)],
+)
+async def create_device(device_data: DeviceCreate, db: AsyncSession = Depends(get_db)):
+    """
+    手动注册新设备。
+    Manually register a new device.
+    """
+    # Check for duplicate IMEI
+    existing = await device_service.get_device_by_imei(db, device_data.imei)
+    if existing is not None:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Device with IMEI {device_data.imei} already exists / IMEI {device_data.imei} 已存在",
+        )
+
+    device = await device_service.create_device(db, device_data)
+    return APIResponse(data=DeviceResponse.model_validate(device))
+
+
+@router.put(
+    "/{device_id}",
+    response_model=APIResponse[DeviceResponse],
+    summary="更新设备信息 / Update device",
+    dependencies=[Depends(require_write)],
+)
+async def update_device(
+    device_id: int, device_data: DeviceUpdate, db: AsyncSession = Depends(get_db)
+):
+    """
+    更新设备信息（名称、状态等）。
+    Update device information (name, status, etc.).
+    """
+    device = await device_service.update_device(db, device_id, device_data)
+    if device is None:
+        raise HTTPException(status_code=404, detail=f"Device {device_id} not found / 未找到设备{device_id}")
+    return APIResponse(data=DeviceResponse.model_validate(device))
+
+
+@router.delete(
+    "/{device_id}",
+    response_model=APIResponse,
+    summary="删除设备 / Delete device",
+    dependencies=[Depends(require_write)],
+)
+async def delete_device(device_id: int, db: AsyncSession = Depends(get_db)):
+    """
+    删除设备及其关联数据。
+    Delete a device and all associated records.
+    """
+    deleted = await device_service.delete_device(db, device_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Device {device_id} not found / 未找到设备{device_id}")
+    return APIResponse(message="Device deleted successfully / 设备删除成功")
--- a/app/routers/geocoding.py
+++ b/app/routers/geocoding.py
@@ -0,0 +1,55 @@
+"""Geocoding proxy endpoints — keeps AMAP_KEY server-side."""
+
+from fastapi import APIRouter, Query
+import httpx
+
+from app.config import settings
+from app.geocoding import reverse_geocode, _amap_sign, AMAP_KEY
+
+router = APIRouter(prefix="/api/geocode", tags=["geocoding"])
+
+
+@router.get("/search")
+async def search_location(
+    keyword: str = Query(..., min_length=1, max_length=100),
+    city: str = Query(default="", max_length=50),
+):
+    """Proxy for Amap POI text search. Returns GCJ-02 coordinates."""
+    if not AMAP_KEY:
+        return {"results": []}
+    params = {
+        "key": AMAP_KEY,
+        "keywords": keyword,
+        "output": "json",
+        "offset": "10",
+        "page": "1",
+    }
+    if city:
+        params["city"] = city
+    sig = _amap_sign(params)
+    if sig:
+        params["sig"] = sig
+    async with httpx.AsyncClient(timeout=5.0) as client:
+        resp = await client.get("https://restapi.amap.com/v3/place/text", params=params)
+        data = resp.json()
+    if data.get("status") != "1":
+        return {"results": []}
+    results = []
+    for poi in data.get("pois", [])[:10]:
+        if poi.get("location"):
+            results.append({
+                "name": poi.get("name", ""),
+                "address": poi.get("address", ""),
+                "location": poi["location"],  # "lng,lat" in GCJ-02
+            })
+    return {"results": results}
+
+
+@router.get("/reverse")
+async def reverse_geocode_endpoint(
+    lat: float = Query(..., ge=-90, le=90),
+    lon: float = Query(..., ge=-180, le=180),
+):
+    """Reverse geocode WGS-84 coords to address via Amap."""
+    address = await reverse_geocode(lat, lon)
+    return {"address": address or ""}
--- a/app/routers/heartbeats.py
+++ b/app/routers/heartbeats.py
@@ -0,0 +1,92 @@
+"""
+Heartbeats Router - 心跳数据接口
+API endpoints for querying device heartbeat records.
+"""
+
+import math
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.models import HeartbeatRecord
+from app.schemas import (
+    APIResponse,
+    HeartbeatRecordResponse,
+    PaginatedList,
+)
+from app.services import device_service
+
+router = APIRouter(prefix="/api/heartbeats", tags=["Heartbeats / 心跳数据"])
+
+
+@router.get(
+    "",
+    response_model=APIResponse[PaginatedList[HeartbeatRecordResponse]],
+    summary="获取心跳记录列表 / List heartbeat records",
+)
+async def list_heartbeats(
+    device_id: int | None = Query(default=None, description="设备ID / Device ID"),
+    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 heartbeat records with optional device and time range filters.
+    """
+    query = select(HeartbeatRecord)
+    count_query = select(func.count(HeartbeatRecord.id))
+
+    if device_id is not None:
+        query = query.where(HeartbeatRecord.device_id == device_id)
+        count_query = count_query.where(HeartbeatRecord.device_id == device_id)
+
+    if start_time:
+        query = query.where(HeartbeatRecord.created_at >= start_time)
+        count_query = count_query.where(HeartbeatRecord.created_at >= start_time)
+
+    if end_time:
+        query = query.where(HeartbeatRecord.created_at <= end_time)
+        count_query = count_query.where(HeartbeatRecord.created_at <= end_time)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    query = query.order_by(HeartbeatRecord.created_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    records = list(result.scalars().all())
+
+    return APIResponse(
+        data=PaginatedList(
+            items=[HeartbeatRecordResponse.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(
+    "/{heartbeat_id}",
+    response_model=APIResponse[HeartbeatRecordResponse],
+    summary="获取心跳详情 / Get heartbeat details",
+)
+async def get_heartbeat(heartbeat_id: int, db: AsyncSession = Depends(get_db)):
+    """
+    按ID获取心跳记录详情。
+    Get heartbeat record details by ID.
+    """
+    result = await db.execute(
+        select(HeartbeatRecord).where(HeartbeatRecord.id == heartbeat_id)
+    )
+    record = result.scalar_one_or_none()
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Heartbeat {heartbeat_id} not found")
+    return APIResponse(data=HeartbeatRecordResponse.model_validate(record))
--- a/app/routers/locations.py
+++ b/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))
--- a/app/routers/ws.py
+++ b/app/routers/ws.py
@@ -0,0 +1,81 @@
+"""
+WebSocket Router - WebSocket 实时推送接口
+Real-time data push via WebSocket with topic subscriptions.
+"""
+
+import logging
+import secrets
+
+from fastapi import APIRouter, Query, WebSocket, WebSocketDisconnect
+
+from app.config import settings
+from app.websocket_manager import ws_manager, VALID_TOPICS
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["WebSocket / 实时推送"])
+
+
+@router.websocket("/ws")
+async def websocket_endpoint(
+    websocket: WebSocket,
+    api_key: str | None = Query(default=None, alias="api_key"),
+    topics: str | None = Query(default=None, description="Comma-separated topics"),
+):
+    """
+    WebSocket endpoint for real-time data push.
+
+    Connect: ws://host/ws?api_key=xxx&topics=location,alarm
+    Topics: location, alarm, device_status, attendance, bluetooth
+    If no topics specified, subscribes to all.
+    """
+    # Authenticate
+    if settings.API_KEY is not None:
+        if api_key is None or not secrets.compare_digest(api_key, settings.API_KEY):
+            # For DB keys, do a simple hash check
+            if api_key is not None:
+                from app.dependencies import _hash_key
+                from app.database import async_session
+                from sqlalchemy import select
+                from app.models import ApiKey
+
+                try:
+                    async with async_session() as session:
+                        key_hash = _hash_key(api_key)
+                        result = await session.execute(
+                            select(ApiKey.id).where(
+                                ApiKey.key_hash == key_hash,
+                                ApiKey.is_active == True,  # noqa: E712
+                            )
+                        )
+                        if result.scalar_one_or_none() is None:
+                            await websocket.close(code=4001, reason="Invalid API key")
+                            return
+                except Exception:
+                    await websocket.close(code=4001, reason="Auth error")
+                    return
+            else:
+                await websocket.close(code=4001, reason="Missing API key")
+                return
+
+    # Parse topics
+    requested_topics = set()
+    if topics:
+        requested_topics = {t.strip() for t in topics.split(",") if t.strip() in VALID_TOPICS}
+
+    if not await ws_manager.connect(websocket, requested_topics):
+        return
+
+    try:
+        # Keep connection alive, handle pings
+        while True:
+            data = await websocket.receive_text()
+            # Client can send "ping" to keep alive
+            if data.strip().lower() == "ping":
+                await websocket.send_text("pong")
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        logger.debug("WebSocket connection error", exc_info=True)
+    finally:
+        ws_manager.disconnect(websocket)
--- a/app/schemas.py
+++ b/app/schemas.py
@@ -0,0 +1,515 @@
+from datetime import datetime
+from typing import Any, Generic, Literal, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+T = TypeVar("T")
+
+
+# ---------------------------------------------------------------------------
+# Generic API response wrapper
+# ---------------------------------------------------------------------------
+
+
+class APIResponse(BaseModel, Generic[T]):
+    """Standard envelope for every API response."""
+
+    code: int = 0
+    message: str = "success"
+    data: T | None = None
+
+
+class PaginationParams(BaseModel):
+    """Query parameters for paginated list endpoints."""
+
+    page: int = Field(default=1, ge=1, description="Page number (1-indexed)")
+    page_size: int = Field(default=20, ge=1, le=100, description="Items per page")
+
+
+class PaginatedList(BaseModel, Generic[T]):
+    """Paginated result set."""
+
+    items: list[T]
+    total: int
+    page: int
+    page_size: int
+    total_pages: int
+
+
+# ---------------------------------------------------------------------------
+# Device schemas
+# ---------------------------------------------------------------------------
+
+
+class DeviceBase(BaseModel):
+    imei: str = Field(..., min_length=15, max_length=20, pattern=r"^\d{15,17}$", description="IMEI number (digits only)")
+    device_type: str = Field(..., max_length=10, description="Device type code (e.g. P240, P241)")
+    name: str | None = Field(None, max_length=100, description="Friendly name")
+    timezone: str = Field(default="+8", max_length=30)
+    language: str = Field(default="cn", max_length=10)
+
+
+class DeviceCreate(DeviceBase):
+    pass
+
+
+class DeviceUpdate(BaseModel):
+    name: str | None = Field(None, max_length=100)
+    iccid: str | None = Field(None, max_length=30)
+    imsi: str | None = Field(None, max_length=20)
+    timezone: str | None = Field(None, max_length=30)
+    language: str | None = Field(None, max_length=10)
+
+
+class DeviceResponse(DeviceBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    status: str
+    battery_level: int | None = None
+    gsm_signal: int | None = None
+    last_heartbeat: datetime | None = None
+    last_login: datetime | None = None
+    iccid: str | None = None
+    imsi: str | None = None
+    created_at: datetime
+    updated_at: datetime | None = None
+
+
+class DeviceListResponse(APIResponse[PaginatedList[DeviceResponse]]):
+    pass
+
+
+class DeviceSingleResponse(APIResponse[DeviceResponse]):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Location Record schemas
+# ---------------------------------------------------------------------------
+
+
+class LocationRecordBase(BaseModel):
+    device_id: int
+    location_type: str = Field(..., max_length=10)
+    latitude: float | None = Field(None, ge=-90, le=90)
+    longitude: float | None = Field(None, ge=-180, le=180)
+    speed: float | None = None
+    course: float | None = None
+    gps_satellites: int | None = None
+    gps_positioned: bool = False
+    mcc: int | None = None
+    mnc: int | None = None
+    lac: int | None = None
+    cell_id: int | None = None
+    rssi: int | None = None
+    neighbor_cells: list[dict[str, Any]] | None = None
+    wifi_data: list[dict[str, Any]] | None = None
+    report_mode: int | None = None
+    is_realtime: bool = True
+    mileage: float | None = None
+    address: str | None = None
+    raw_data: str | None = None
+    recorded_at: datetime
+
+
+class LocationRecordCreate(LocationRecordBase):
+    pass
+
+
+class LocationRecordResponse(LocationRecordBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    created_at: datetime
+
+
+class LocationRecordFilters(BaseModel):
+    device_id: int | None = None
+    location_type: str | None = None
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+
+
+class LocationListResponse(APIResponse[PaginatedList[LocationRecordResponse]]):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Alarm Record schemas
+# ---------------------------------------------------------------------------
+
+
+class AlarmRecordBase(BaseModel):
+    device_id: int
+    alarm_type: str = Field(..., max_length=30)
+    alarm_source: str | None = Field(None, max_length=20)
+    protocol_number: int
+    latitude: float | None = Field(None, ge=-90, le=90)
+    longitude: float | None = Field(None, ge=-180, le=180)
+    speed: float | None = None
+    course: float | None = None
+    mcc: int | None = None
+    mnc: int | None = None
+    lac: int | None = None
+    cell_id: int | None = None
+    battery_level: int | None = None
+    gsm_signal: int | None = None
+    fence_data: dict[str, Any] | None = None
+    wifi_data: list[dict[str, Any]] | None = None
+    address: str | None = None
+    recorded_at: datetime
+
+
+class AlarmRecordCreate(AlarmRecordBase):
+    pass
+
+
+class AlarmRecordResponse(AlarmRecordBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    acknowledged: bool
+    created_at: datetime
+
+
+class AlarmAcknowledge(BaseModel):
+    acknowledged: bool = True
+
+
+class AlarmRecordFilters(BaseModel):
+    device_id: int | None = None
+    alarm_type: str | None = None
+    acknowledged: bool | None = None
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+
+
+class AlarmListResponse(APIResponse[PaginatedList[AlarmRecordResponse]]):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Heartbeat Record schemas
+# ---------------------------------------------------------------------------
+
+
+class HeartbeatRecordBase(BaseModel):
+    device_id: int
+    protocol_number: int
+    terminal_info: int
+    battery_level: int
+    gsm_signal: int
+    extension_data: dict[str, Any] | None = None
+
+
+class HeartbeatRecordCreate(HeartbeatRecordBase):
+    pass
+
+
+class HeartbeatRecordResponse(HeartbeatRecordBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    created_at: datetime
+
+
+class HeartbeatListResponse(APIResponse[PaginatedList[HeartbeatRecordResponse]]):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Attendance Record schemas
+# ---------------------------------------------------------------------------
+
+
+class AttendanceRecordBase(BaseModel):
+    device_id: int
+    attendance_type: str = Field(..., max_length=20)
+    protocol_number: int
+    gps_positioned: bool = False
+    latitude: float | None = Field(None, ge=-90, le=90)
+    longitude: float | None = Field(None, ge=-180, le=180)
+    speed: float | None = None
+    course: float | None = None
+    gps_satellites: int | None = None
+    battery_level: int | None = None
+    gsm_signal: int | None = None
+    mcc: int | None = None
+    mnc: int | None = None
+    lac: int | None = None
+    cell_id: int | None = None
+    wifi_data: list[dict[str, Any]] | None = None
+    lbs_data: list[dict[str, Any]] | None = None
+    address: str | None = None
+    recorded_at: datetime
+
+
+class AttendanceRecordCreate(AttendanceRecordBase):
+    pass
+
+
+class AttendanceRecordResponse(AttendanceRecordBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    created_at: datetime
+
+
+class AttendanceRecordFilters(BaseModel):
+    device_id: int | None = None
+    attendance_type: str | None = None
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+
+
+class AttendanceListResponse(APIResponse[PaginatedList[AttendanceRecordResponse]]):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Bluetooth Record schemas
+# ---------------------------------------------------------------------------
+
+
+class BluetoothRecordBase(BaseModel):
+    device_id: int
+    record_type: str = Field(..., max_length=20)
+    protocol_number: int
+    beacon_mac: str | None = None
+    beacon_uuid: str | None = None
+    beacon_major: int | None = None
+    beacon_minor: int | None = None
+    rssi: int | None = None
+    beacon_battery: float | None = None
+    beacon_battery_unit: str | None = None
+    attendance_type: str | None = None
+    bluetooth_data: dict[str, Any] | None = None
+    latitude: float | None = Field(None, ge=-90, le=90)
+    longitude: float | None = Field(None, ge=-180, le=180)
+    recorded_at: datetime
+
+
+class BluetoothRecordCreate(BluetoothRecordBase):
+    pass
+
+
+class BluetoothRecordResponse(BluetoothRecordBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    created_at: datetime
+
+
+class BluetoothRecordFilters(BaseModel):
+    device_id: int | None = None
+    record_type: str | None = None
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+
+
+class BluetoothListResponse(APIResponse[PaginatedList[BluetoothRecordResponse]]):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Beacon Config schemas
+# ---------------------------------------------------------------------------
+
+
+class BeaconConfigBase(BaseModel):
+    beacon_mac: str = Field(..., max_length=20, pattern=r"^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$", description="信标MAC地址 (AA:BB:CC:DD:EE:FF)")
+    beacon_uuid: str | None = Field(None, max_length=36, description="iBeacon UUID")
+    beacon_major: int | None = Field(None, ge=0, le=65535, description="iBeacon Major")
+    beacon_minor: int | None = Field(None, ge=0, le=65535, description="iBeacon Minor")
+    name: str = Field(..., max_length=100, description="信标名称")
+    floor: str | None = Field(None, max_length=20, description="楼层")
+    area: str | None = Field(None, max_length=100, description="区域")
+    latitude: float | None = Field(None, ge=-90, le=90, description="纬度")
+    longitude: float | None = Field(None, ge=-180, le=180, description="经度")
+    address: str | None = Field(None, description="详细地址")
+    status: Literal["active", "inactive"] = Field(default="active", description="状态")
+
+
+class BeaconConfigCreate(BeaconConfigBase):
+    pass
+
+
+class BeaconConfigUpdate(BaseModel):
+    beacon_uuid: str | None = Field(None, max_length=36)
+    beacon_major: int | None = Field(None, ge=0, le=65535)
+    beacon_minor: int | None = Field(None, ge=0, le=65535)
+    name: str | None = Field(None, max_length=100)
+    floor: str | None = Field(None, max_length=20)
+    area: str | None = Field(None, max_length=100)
+    latitude: float | None = Field(None, ge=-90, le=90)
+    longitude: float | None = Field(None, ge=-180, le=180)
+    address: str | None = None
+    status: Literal["active", "inactive"] | None = None
+
+
+class BeaconConfigResponse(BaseModel):
+    """Response model — no pattern validation on output (existing data may not conform)."""
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    beacon_mac: str
+    beacon_uuid: str | None = None
+    beacon_major: int | None = None
+    beacon_minor: int | None = None
+    name: str
+    floor: str | None = None
+    area: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    address: str | None = None
+    status: str
+    created_at: datetime
+    updated_at: datetime | None = None
+
+
+# ---------------------------------------------------------------------------
+# Command Log schemas
+# ---------------------------------------------------------------------------
+
+
+class CommandCreate(BaseModel):
+    device_id: int
+    command_type: str = Field(..., max_length=30)
+    command_content: str = Field(..., max_length=500)
+    server_flag: str = Field(..., max_length=20)
+
+
+# ---------------------------------------------------------------------------
+# Batch operation schemas
+# ---------------------------------------------------------------------------
+
+
+class BatchDeviceCreateItem(BaseModel):
+    """Single device in a batch create request."""
+    imei: str = Field(..., min_length=15, max_length=20, pattern=r"^\d{15,17}$", description="IMEI number")
+    device_type: str = Field(default="P241", max_length=10, description="Device type (P240/P241)")
+    name: str | None = Field(None, max_length=100, description="Friendly name")
+
+
+class BatchDeviceCreateRequest(BaseModel):
+    """Batch create devices."""
+    devices: list[BatchDeviceCreateItem] = Field(..., min_length=1, max_length=500, description="List of devices to create")
+
+
+class BatchDeviceCreateResult(BaseModel):
+    """Result of a single device in batch create."""
+    imei: str
+    success: bool
+    device_id: int | None = None
+    error: str | None = None
+
+
+class BatchDeviceCreateResponse(BaseModel):
+    """Summary of batch create operation."""
+    total: int
+    created: int
+    failed: int
+    results: list[BatchDeviceCreateResult]
+
+
+class BatchCommandRequest(BaseModel):
+    """Send the same command to multiple devices."""
+    device_ids: list[int] | None = Field(default=None, min_length=1, max_length=100, description="Device IDs (provide device_ids or imeis)")
+    imeis: list[str] | None = Field(default=None, min_length=1, max_length=100, description="IMEI list (alternative to device_ids)")
+    command_type: str = Field(..., max_length=30, description="Command type (e.g. online_cmd)")
+    command_content: str = Field(..., max_length=500, description="Command content")
+
+    @model_validator(mode="after")
+    def check_device_ids_or_imeis(self):
+        if not self.device_ids and not self.imeis:
+            raise ValueError("Must provide device_ids or imeis / 必须提供 device_ids 或 imeis")
+        if self.device_ids and self.imeis:
+            raise ValueError("Provide device_ids or imeis, not both / 不能同时提供 device_ids 和 imeis")
+        return self
+
+
+class BatchCommandResult(BaseModel):
+    """Result of a single command in batch send."""
+    device_id: int
+    imei: str
+    success: bool
+    command_id: int | None = None
+    error: str | None = None
+
+
+class BatchCommandResponse(BaseModel):
+    """Summary of batch command operation."""
+    total: int
+    sent: int
+    failed: int
+    results: list[BatchCommandResult]
+
+
+class BatchDeviceDeleteRequest(BaseModel):
+    """Batch delete devices."""
+    device_ids: list[int] = Field(..., min_length=1, max_length=100, description="Device IDs to delete")
+
+
+class BatchDeviceUpdateRequest(BaseModel):
+    """Batch update devices with the same settings."""
+    device_ids: list[int] = Field(..., min_length=1, max_length=500, description="Device IDs to update")
+    update: DeviceUpdate = Field(..., description="Fields to update")
+
+
+class CommandUpdate(BaseModel):
+    response_content: str | None = None
+    status: str | None = Field(None, max_length=20)
+    sent_at: datetime | None = None
+    response_at: datetime | None = None
+
+
+class CommandResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    device_id: int
+    command_type: str
+    command_content: str
+    server_flag: str
+    response_content: str | None = None
+    status: str
+    sent_at: datetime | None = None
+    response_at: datetime | None = None
+    created_at: datetime
+
+
+class CommandListResponse(APIResponse[PaginatedList[CommandResponse]]):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# API Key schemas
+# ---------------------------------------------------------------------------
+
+
+class ApiKeyCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100, description="Key name / 名称")
+    permissions: Literal["read", "write", "admin"] = Field(default="read", description="Permission level")
+
+
+class ApiKeyUpdate(BaseModel):
+    name: str | None = Field(None, max_length=100)
+    permissions: Literal["read", "write", "admin"] | None = None
+    is_active: bool | None = None
+
+
+class ApiKeyResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    name: str
+    permissions: str
+    is_active: bool
+    last_used_at: datetime | None = None
+    created_at: datetime
+
+
+class ApiKeyCreateResponse(ApiKeyResponse):
+    """Returned only on creation — includes the plaintext key (shown once)."""
+    key: str
--- a/app/services/init.py
+++ b/app/services/init.py
--- a/app/services/beacon_service.py
+++ b/app/services/beacon_service.py
@@ -0,0 +1,94 @@
+"""
+Beacon Service - 蓝牙信标管理服务
+Provides CRUD operations for Bluetooth beacon configuration.
+"""
+
+from datetime import datetime, timezone
+
+from sqlalchemy import func, select, or_
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import BeaconConfig
+from app.schemas import BeaconConfigCreate, BeaconConfigUpdate
+
+
+async def get_beacons(
+    db: AsyncSession,
+    page: int = 1,
+    page_size: int = 20,
+    status_filter: str | None = None,
+    search: str | None = None,
+) -> tuple[list[BeaconConfig], int]:
+    """Get paginated beacon list with optional filters."""
+    query = select(BeaconConfig)
+    count_query = select(func.count(BeaconConfig.id))
+
+    if status_filter:
+        query = query.where(BeaconConfig.status == status_filter)
+        count_query = count_query.where(BeaconConfig.status == status_filter)
+
+    if search:
+        like = f"%{search}%"
+        cond = or_(
+            BeaconConfig.beacon_mac.ilike(like),
+            BeaconConfig.name.ilike(like),
+            BeaconConfig.area.ilike(like),
+        )
+        query = query.where(cond)
+        count_query = count_query.where(cond)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    query = query.order_by(BeaconConfig.created_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    return list(result.scalars().all()), total
+
+
+async def get_beacon(db: AsyncSession, beacon_id: int) -> BeaconConfig | None:
+    result = await db.execute(
+        select(BeaconConfig).where(BeaconConfig.id == beacon_id)
+    )
+    return result.scalar_one_or_none()
+
+
+async def get_beacon_by_mac(db: AsyncSession, mac: str) -> BeaconConfig | None:
+    result = await db.execute(
+        select(BeaconConfig).where(BeaconConfig.beacon_mac == mac)
+    )
+    return result.scalar_one_or_none()
+
+
+async def create_beacon(db: AsyncSession, data: BeaconConfigCreate) -> BeaconConfig:
+    beacon = BeaconConfig(**data.model_dump())
+    db.add(beacon)
+    await db.flush()
+    await db.refresh(beacon)
+    return beacon
+
+
+async def update_beacon(
+    db: AsyncSession, beacon_id: int, data: BeaconConfigUpdate
+) -> BeaconConfig | None:
+    beacon = await get_beacon(db, beacon_id)
+    if beacon is None:
+        return None
+
+    update_data = data.model_dump(exclude_unset=True)
+    for key, value in update_data.items():
+        setattr(beacon, key, value)
+    beacon.updated_at = datetime.now(timezone.utc)
+
+    await db.flush()
+    await db.refresh(beacon)
+    return beacon
+
+
+async def delete_beacon(db: AsyncSession, beacon_id: int) -> bool:
+    beacon = await get_beacon(db, beacon_id)
+    if beacon is None:
+        return False
+    await db.delete(beacon)
+    await db.flush()
+    return True
--- a/app/services/command_service.py
+++ b/app/services/command_service.py
@@ -0,0 +1,110 @@
+"""
+Command Service - 指令管理服务
+Provides CRUD operations for device command logs.
+"""
+
+from datetime import datetime, timezone
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import CommandLog
+
+
+async def get_commands(
+    db: AsyncSession,
+    device_id: int | None = None,
+    command_type: str | None = None,
+    status: str | None = None,
+    page: int = 1,
+    page_size: int = 20,
+) -> tuple[list[CommandLog], int]:
+    """
+    获取指令列表（分页）/ Get paginated command logs.
+    """
+    query = select(CommandLog)
+    count_query = select(func.count(CommandLog.id))
+
+    if device_id is not None:
+        query = query.where(CommandLog.device_id == device_id)
+        count_query = count_query.where(CommandLog.device_id == device_id)
+
+    if command_type:
+        query = query.where(CommandLog.command_type == command_type)
+        count_query = count_query.where(CommandLog.command_type == command_type)
+
+    if status:
+        query = query.where(CommandLog.status == status)
+        count_query = count_query.where(CommandLog.status == status)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    query = query.order_by(CommandLog.created_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    commands = list(result.scalars().all())
+
+    return commands, total
+
+
+async def create_command(
+    db: AsyncSession,
+    device_id: int,
+    command_type: str,
+    command_content: str,
+    server_flag: str = "badge_admin",
+) -> CommandLog:
+    """
+    创建指令记录 / Create a new command log entry.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    device_id : int
+        Target device ID.
+    command_type : str
+        Type of command.
+    command_content : str
+        Command payload content.
+    server_flag : str
+        Server flag identifier.
+
+    Returns
+    -------
+    CommandLog
+        The newly created command log.
+    """
+    command = CommandLog(
+        device_id=device_id,
+        command_type=command_type,
+        command_content=command_content,
+        server_flag=server_flag,
+        status="pending",
+    )
+    db.add(command)
+    await db.flush()
+    await db.refresh(command)
+    return command
+
+
+async def get_command(db: AsyncSession, command_id: int) -> CommandLog | None:
+    """
+    按ID获取指令 / Get command log by ID.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    command_id : int
+        Command log primary key.
+
+    Returns
+    -------
+    CommandLog | None
+    """
+    result = await db.execute(
+        select(CommandLog).where(CommandLog.id == command_id)
+    )
+    return result.scalar_one_or_none()
--- a/app/services/device_service.py
+++ b/app/services/device_service.py
@@ -0,0 +1,312 @@
+"""
+Device Service - 设备管理服务
+Provides CRUD operations and statistics for badge devices.
+"""
+
+from datetime import datetime, timezone
+
+from sqlalchemy import func, select, or_
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import Device
+from app.schemas import DeviceCreate, DeviceUpdate, BatchDeviceCreateItem
+
+
+async def get_devices(
+    db: AsyncSession,
+    page: int = 1,
+    page_size: int = 20,
+    status_filter: str | None = None,
+    search: str | None = None,
+) -> tuple[list[Device], int]:
+    """
+    获取设备列表（分页）/ Get paginated device list.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    page : int
+        Page number (1-indexed).
+    page_size : int
+        Number of items per page.
+    status_filter : str, optional
+        Filter by device status (online / offline).
+    search : str, optional
+        Search by IMEI or device name.
+
+    Returns
+    -------
+    tuple[list[Device], int]
+        (list of devices, total count)
+    """
+    query = select(Device)
+    count_query = select(func.count(Device.id))
+
+    if status_filter:
+        query = query.where(Device.status == status_filter)
+        count_query = count_query.where(Device.status == status_filter)
+
+    if search:
+        pattern = f"%{search}%"
+        search_clause = or_(
+            Device.imei.ilike(pattern),
+            Device.name.ilike(pattern),
+        )
+        query = query.where(search_clause)
+        count_query = count_query.where(search_clause)
+
+    # Total count
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    # Paginated results
+    offset = (page - 1) * page_size
+    query = query.order_by(Device.updated_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    devices = list(result.scalars().all())
+
+    return devices, total
+
+
+async def get_device(db: AsyncSession, device_id: int) -> Device | None:
+    """
+    按ID获取设备 / Get device by ID.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    device_id : int
+        Device primary key.
+
+    Returns
+    -------
+    Device | None
+    """
+    result = await db.execute(select(Device).where(Device.id == device_id))
+    return result.scalar_one_or_none()
+
+
+async def get_device_by_imei(db: AsyncSession, imei: str) -> Device | None:
+    """
+    按IMEI获取设备 / Get device by IMEI number.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    imei : str
+        Device IMEI number.
+
+    Returns
+    -------
+    Device | None
+    """
+    result = await db.execute(select(Device).where(Device.imei == imei))
+    return result.scalar_one_or_none()
+
+
+async def create_device(db: AsyncSession, device_data: DeviceCreate) -> Device:
+    """
+    创建设备 / Create a new device.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    device_data : DeviceCreate
+        Device creation data.
+
+    Returns
+    -------
+    Device
+        The newly created device.
+    """
+    device = Device(**device_data.model_dump())
+    db.add(device)
+    await db.flush()
+    await db.refresh(device)
+    return device
+
+
+async def update_device(
+    db: AsyncSession, device_id: int, device_data: DeviceUpdate
+) -> Device | None:
+    """
+    更新设备信息 / Update device information.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    device_id : int
+        Device primary key.
+    device_data : DeviceUpdate
+        Fields to update (only non-None fields are applied).
+
+    Returns
+    -------
+    Device | None
+        The updated device, or None if not found.
+    """
+    device = await get_device(db, device_id)
+    if device is None:
+        return None
+
+    update_fields = device_data.model_dump(exclude_unset=True)
+    for field, value in update_fields.items():
+        setattr(device, field, value)
+
+    device.updated_at = datetime.now(timezone.utc)
+    await db.flush()
+    await db.refresh(device)
+    return device
+
+
+async def delete_device(db: AsyncSession, device_id: int) -> bool:
+    """
+    删除设备 / Delete a device.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    device_id : int
+        Device primary key.
+
+    Returns
+    -------
+    bool
+        True if the device was deleted, False if not found.
+    """
+    device = await get_device(db, device_id)
+    if device is None:
+        return False
+
+    await db.delete(device)
+    await db.flush()
+    return True
+
+
+async def get_devices_by_ids(db: AsyncSession, device_ids: list[int]) -> list[Device]:
+    """Fetch multiple devices by IDs in a single query."""
+    if not device_ids:
+        return []
+    result = await db.execute(select(Device).where(Device.id.in_(device_ids)))
+    return list(result.scalars().all())
+
+
+async def get_devices_by_imeis(db: AsyncSession, imeis: list[str]) -> list[Device]:
+    """Fetch multiple devices by IMEIs in a single query."""
+    if not imeis:
+        return []
+    result = await db.execute(select(Device).where(Device.imei.in_(imeis)))
+    return list(result.scalars().all())
+
+
+async def batch_create_devices(
+    db: AsyncSession, items: list[BatchDeviceCreateItem]
+) -> list[dict]:
+    """Batch create devices, skipping duplicates. Uses single query to check existing."""
+    # One query to find all existing IMEIs
+    imeis = [item.imei for item in items]
+    existing_devices = await get_devices_by_imeis(db, imeis)
+    existing_imeis = {d.imei for d in existing_devices}
+
+    results: list[dict] = [{} for _ in range(len(items))]  # preserve input order
+    new_device_indices: list[tuple[int, Device]] = []
+    seen_imeis: set[str] = set()
+    for i, item in enumerate(items):
+        if item.imei in existing_imeis:
+            results[i] = {"imei": item.imei, "success": False, "device_id": None, "error": f"IMEI {item.imei} already exists"}
+            continue
+        if item.imei in seen_imeis:
+            results[i] = {"imei": item.imei, "success": False, "device_id": None, "error": "Duplicate IMEI in request"}
+            continue
+        seen_imeis.add(item.imei)
+        device = Device(imei=item.imei, device_type=item.device_type, name=item.name)
+        db.add(device)
+        new_device_indices.append((i, device))
+
+    if new_device_indices:
+        await db.flush()
+        for idx, device in new_device_indices:
+            await db.refresh(device)
+            results[idx] = {"imei": device.imei, "success": True, "device_id": device.id, "error": None}
+
+    return results
+
+
+async def batch_update_devices(
+    db: AsyncSession, device_ids: list[int], update_data: DeviceUpdate
+) -> list[dict]:
+    """Batch update devices with the same settings. Uses single query to fetch all."""
+    devices = await get_devices_by_ids(db, device_ids)
+    found_map = {d.id: d for d in devices}
+    update_fields = update_data.model_dump(exclude_unset=True)
+    now = datetime.now(timezone.utc)
+
+    results = []
+    for device_id in device_ids:
+        device = found_map.get(device_id)
+        if device is None:
+            results.append({"device_id": device_id, "success": False, "error": f"Device {device_id} not found"})
+            continue
+        for field, value in update_fields.items():
+            setattr(device, field, value)
+        device.updated_at = now
+        results.append({"device_id": device_id, "success": True, "error": None})
+
+    if any(r["success"] for r in results):
+        await db.flush()
+
+    return results
+
+
+async def batch_delete_devices(
+    db: AsyncSession, device_ids: list[int]
+) -> list[dict]:
+    """Batch delete devices. Uses single query to fetch all."""
+    devices = await get_devices_by_ids(db, device_ids)
+    found_map = {d.id: d for d in devices}
+
+    results = []
+    for device_id in device_ids:
+        device = found_map.get(device_id)
+        if device is None:
+            results.append({"device_id": device_id, "success": False, "error": f"Device {device_id} not found"})
+            continue
+        await db.delete(device)
+        results.append({"device_id": device_id, "success": True, "error": None})
+
+    if any(r["success"] for r in results):
+        await db.flush()
+
+    return results
+
+
+async def get_device_stats(db: AsyncSession) -> dict:
+    """
+    获取设备统计信息 / Get device statistics.
+
+    Returns
+    -------
+    dict
+        {"total": int, "online": int, "offline": int}
+    """
+    total_result = await db.execute(select(func.count(Device.id)))
+    total = total_result.scalar() or 0
+
+    online_result = await db.execute(
+        select(func.count(Device.id)).where(Device.status == "online")
+    )
+    online = online_result.scalar() or 0
+
+    offline = total - online
+
+    return {
+        "total": total,
+        "online": online,
+        "offline": offline,
+    }
--- a/app/services/location_service.py
+++ b/app/services/location_service.py
@@ -0,0 +1,183 @@
+"""
+Location Service - 位置数据服务
+Provides query operations for GPS / LBS / WIFI location records.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import LocationRecord
+
+
+async def get_locations(
+    db: AsyncSession,
+    device_id: int | None = None,
+    location_type: str | None = None,
+    start_time: datetime | None = None,
+    end_time: datetime | None = None,
+    page: int = 1,
+    page_size: int = 20,
+) -> tuple[list[LocationRecord], int]:
+    """
+    获取位置记录列表（分页）/ Get paginated location records.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    device_id : int, optional
+        Filter by device ID.
+    location_type : str, optional
+        Filter by location type (gps, lbs, wifi, gps_4g, lbs_4g, wifi_4g).
+    start_time : datetime, optional
+        Filter records after this time.
+    end_time : datetime, optional
+        Filter records before this time.
+    page : int
+        Page number (1-indexed).
+    page_size : int
+        Number of items per page.
+
+    Returns
+    -------
+    tuple[list[LocationRecord], int]
+        (list of location records, total count)
+    """
+    query = select(LocationRecord)
+    count_query = select(func.count(LocationRecord.id))
+
+    if device_id is not None:
+        query = query.where(LocationRecord.device_id == device_id)
+        count_query = count_query.where(LocationRecord.device_id == device_id)
+
+    if location_type:
+        query = query.where(LocationRecord.location_type == location_type)
+        count_query = count_query.where(LocationRecord.location_type == location_type)
+
+    if start_time:
+        query = query.where(LocationRecord.recorded_at >= start_time)
+        count_query = count_query.where(LocationRecord.recorded_at >= start_time)
+
+    if end_time:
+        query = query.where(LocationRecord.recorded_at <= end_time)
+        count_query = count_query.where(LocationRecord.recorded_at <= end_time)
+
+    total_result = await db.execute(count_query)
+    total = total_result.scalar() or 0
+
+    offset = (page - 1) * page_size
+    query = query.order_by(LocationRecord.recorded_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(query)
+    records = list(result.scalars().all())
+
+    return records, total
+
+
+async def get_latest_location(
+    db: AsyncSession, device_id: int
+) -> LocationRecord | None:
+    """
+    获取设备最新位置 / Get the most recent location for a device.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    device_id : int
+        Device ID.
+
+    Returns
+    -------
+    LocationRecord | None
+    """
+    result = await db.execute(
+        select(LocationRecord)
+        .where(LocationRecord.device_id == device_id)
+        .order_by(LocationRecord.recorded_at.desc())
+        .limit(1)
+    )
+    return result.scalar_one_or_none()
+
+
+async def get_batch_latest_locations(
+    db: AsyncSession, device_ids: list[int]
+) -> list[LocationRecord]:
+    """
+    批量获取多设备最新位置 / Get the most recent location for each device in the list.
+
+    Uses a subquery with MAX(id) GROUP BY device_id for efficiency.
+    """
+    if not device_ids:
+        return []
+
+    # Subquery: max id per device_id
+    subq = (
+        select(func.max(LocationRecord.id).label("max_id"))
+        .where(LocationRecord.device_id.in_(device_ids))
+        .group_by(LocationRecord.device_id)
+        .subquery()
+    )
+    result = await db.execute(
+        select(LocationRecord).where(LocationRecord.id.in_(select(subq.c.max_id)))
+    )
+    return list(result.scalars().all())
+
+
+async def get_all_online_latest_locations(
+    db: AsyncSession,
+) -> list[LocationRecord]:
+    """
+    获取所有在线设备的最新位置 / Get latest location for all online devices.
+    """
+    from app.models import Device
+
+    # Get online device IDs
+    online_result = await db.execute(
+        select(Device.id).where(Device.status == "online")
+    )
+    online_ids = [row[0] for row in online_result.all()]
+    if not online_ids:
+        return []
+
+    return await get_batch_latest_locations(db, online_ids)
+
+
+async def get_device_track(
+    db: AsyncSession,
+    device_id: int,
+    start_time: datetime,
+    end_time: datetime,
+    max_points: int = 10000,
+) -> list[LocationRecord]:
+    """
+    获取设备轨迹 / Get device movement track within a time range.
+
+    Parameters
+    ----------
+    db : AsyncSession
+        Database session.
+    device_id : int
+        Device ID.
+    start_time : datetime
+        Start of time range.
+    end_time : datetime
+        End of time range.
+
+    Returns
+    -------
+    list[LocationRecord]
+        Location records ordered by recorded_at ascending (chronological).
+    """
+    result = await db.execute(
+        select(LocationRecord)
+        .where(
+            LocationRecord.device_id == device_id,
+            LocationRecord.recorded_at >= start_time,
+            LocationRecord.recorded_at <= end_time,
+        )
+        .order_by(LocationRecord.recorded_at.asc())
+        .limit(max_points)
+    )
+    return list(result.scalars().all())
--- a/app/services/tcp_command_service.py
+++ b/app/services/tcp_command_service.py
@@ -0,0 +1,31 @@
+"""
+TCP Command Service — Abstraction layer for sending commands to devices via TCP.
+
+Breaks the circular import between routers/commands.py and tcp_server.py
+by lazily importing tcp_manager only when needed.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _get_tcp_manager():
+    """Lazily import tcp_manager to avoid circular imports."""
+    from app.tcp_server import tcp_manager
+    return tcp_manager
+
+
+def is_device_online(imei: str) -> bool:
+    """Check if a device is currently connected via TCP."""
+    return imei in _get_tcp_manager().connections
+
+
+async def send_command(imei: str, command_type: str, command_content: str) -> bool:
+    """Send an online command (0x80) to a connected device."""
+    return await _get_tcp_manager().send_command(imei, command_type, command_content)
+
+
+async def send_message(imei: str, message: str) -> bool:
+    """Send a text message (0x82) to a connected device."""
+    return await _get_tcp_manager().send_message(imei, message)
--- a/app/static/admin.html
+++ b/app/static/admin.html
--- a/app/tcp_server.py
+++ b/app/tcp_server.py
--- a/app/websocket_manager.py
+++ b/app/websocket_manager.py
@@ -0,0 +1,89 @@
+"""
+WebSocket Manager - WebSocket 连接管理器
+Manages client connections, topic subscriptions, and broadcasting.
+"""
+
+import asyncio
+import json
+import logging
+from datetime import datetime, timezone
+
+from fastapi import WebSocket
+
+logger = logging.getLogger(__name__)
+
+# Maximum concurrent WebSocket connections
+MAX_CONNECTIONS = 100
+
+# Valid topics
+VALID_TOPICS = {"location", "alarm", "device_status", "attendance", "bluetooth"}
+
+
+class WebSocketManager:
+    """Manages WebSocket connections with topic-based subscriptions."""
+
+    def __init__(self):
+        # {websocket: set_of_topics}
+        self.active_connections: dict[WebSocket, set[str]] = {}
+
+    @property
+    def connection_count(self) -> int:
+        return len(self.active_connections)
+
+    async def connect(self, websocket: WebSocket, topics: set[str]) -> bool:
+        """Accept and register a WebSocket connection. Returns False if limit reached."""
+        if self.connection_count >= MAX_CONNECTIONS:
+            await websocket.close(code=1013, reason="Max connections reached")
+            return False
+
+        await websocket.accept()
+        filtered = topics & VALID_TOPICS
+        self.active_connections[websocket] = filtered if filtered else VALID_TOPICS
+        logger.info(
+            "WebSocket connected (%d total), topics: %s",
+            self.connection_count,
+            self.active_connections[websocket],
+        )
+        return True
+
+    def disconnect(self, websocket: WebSocket):
+        """Remove a WebSocket connection."""
+        self.active_connections.pop(websocket, None)
+        logger.info("WebSocket disconnected (%d remaining)", self.connection_count)
+
+    async def broadcast(self, topic: str, data: dict):
+        """Broadcast a message to all subscribers of the given topic."""
+        if topic not in VALID_TOPICS:
+            return
+
+        message = json.dumps(
+            {"topic": topic, "data": data, "timestamp": datetime.now(timezone.utc).isoformat()},
+            default=str,
+            ensure_ascii=False,
+        )
+
+        disconnected = []
+        # Snapshot dict to avoid RuntimeError from concurrent modification
+        for ws, topics in list(self.active_connections.items()):
+            if topic in topics:
+                try:
+                    await ws.send_text(message)
+                except Exception:
+                    disconnected.append(ws)
+
+        for ws in disconnected:
+            self.active_connections.pop(ws, None)
+
+    def broadcast_nonblocking(self, topic: str, data: dict):
+        """Fire-and-forget broadcast (used from TCP handler context)."""
+        asyncio.create_task(self._safe_broadcast(topic, data))
+
+    async def _safe_broadcast(self, topic: str, data: dict):
+        try:
+            await self.broadcast(topic, data)
+        except Exception:
+            logger.exception("WebSocket broadcast error for topic %s", topic)
+
+
+# Singleton instance
+ws_manager = WebSocketManager()