default
ced836179c
- Add BEIJING_TZ constant in config.py - Replace all timezone.utc references across 11 files - Device-reported times, DB defaults, protocol sync all use Beijing time via [HAPI](https://hapi.run) Co-Authored-By: HAPI <noreply@hapi.run>
333 lines
12 KiB
Python
333 lines
12 KiB
Python
"""
|
||
Commands Router - 指令管理接口
|
||
API endpoints for sending commands / messages to devices and viewing command history.
|
||
"""
|
||
|
||
import logging
|
||
import math
|
||
from datetime import datetime
|
||
|
||
from app.config import BEIJING_TZ
|
||
|
||
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(BEIJING_TZ)
|
||
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(BEIJING_TZ)
|
||
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))
|