Fix API regressions and refresh project docs

app/api/routes/control.py

@@ -1,12 +1,14 @@
 import asyncio
 import json
 import logging
-from typing import Optional
+from typing import Any, Optional
+
 from fastapi import APIRouter, Depends, HTTPException
-from app.core.state import state_manager
-from app.core.database import async_session
-from app.drivers.wiz import WizDriver
+
 from app.api.deps import verify_token, AuthContext
+from app.core.database import async_session
+from app.core.state import state_manager
+from app.drivers.wiz import WizDriver, WizResponse
 from app.models.event_log import EventLog
 
 logger = logging.getLogger(__name__)
@@ -34,21 +36,171 @@ async def _log_event(
         logger.error(f"Ошибка записи в лог: {e}")
 
 
-async def log_toggle(auth: AuthContext, target_type: str, target_id: str, params: dict):
-    """Логирует toggle_on/toggle_off если в params есть state."""
+def _build_command_params(
+    state: Optional[bool],
+    brightness: Optional[int],
+    scene: Optional[str],
+    temp: Optional[int],
+    r: Optional[int],
+    g: Optional[int],
+    b: Optional[int],
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    if state is not None:
+        params["state"] = state
+    if brightness is not None:
+        params["dimming"] = brightness
+
+    if scene is not None:
+        if scene not in wiz.SCENES:
+            raise HTTPException(status_code=400, detail="Неизвестная сцена")
+        params["sceneId"] = wiz.SCENES[scene]
+    elif temp is not None:
+        params["temp"] = temp
+    elif any(v is not None for v in [r, g, b]):
+        params["r"], params["g"], params["b"] = r or 0, g or 0, b or 0
+
+    return params
+
+
+def _resolve_action_name(params: dict[str, Any]) -> str:
     if "state" in params:
-        action = "toggle_on" if params["state"] else "toggle_off"
-        await _log_event(auth, action, target_type, target_id, params)
+        return "toggle_on" if params["state"] else "toggle_off"
+    if "sceneId" in params:
+        return "scene"
+    if any(channel in params for channel in ("r", "g", "b")):
+        return "color"
+    if "temp" in params:
+        return "temperature"
+    if "dimming" in params:
+        return "brightness"
+    return "command"
 
 
-async def log_toggle_by_name(
-    key_name: str, target_type: str, target_id: str, params: dict
+def _build_event_payload(
+    params: dict[str, Any],
+    *,
+    success_count: int | None = None,
+    failure_count: int | None = None,
+    target_count: int | None = None,
+    status: str | None = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {"command": params}
+    outcome = {
+        "status": status,
+        "success_count": success_count,
+        "failure_count": failure_count,
+        "target_count": target_count,
+    }
+    payload["outcome"] = {k: v for k, v in outcome.items() if v is not None}
+    return payload
+
+
+async def log_command_result(
+    auth: AuthContext,
+    target_type: str,
+    target_id: str,
+    params: dict[str, Any],
+    *,
+    success_count: int,
+    failure_count: int,
+    target_count: int,
 ):
-    """Логирует toggle из контекста без AuthContext (для планировщика)."""
-    if "state" in params:
-        auth = AuthContext(is_master=False, is_admin=False, key_name=key_name)
-        action = "toggle_on" if params["state"] else "toggle_off"
-        await _log_event(auth, action, target_type, target_id, params)
+    action = _resolve_action_name(params)
+    await _log_event(
+        auth,
+        f"{action}_requested",
+        target_type,
+        target_id,
+        _build_event_payload(params, target_count=target_count, status="requested"),
+    )
+
+    if success_count == 0:
+        await _log_event(
+            auth,
+            f"{action}_failed",
+            target_type,
+            target_id,
+            _build_event_payload(
+                params,
+                success_count=0,
+                failure_count=failure_count,
+                target_count=target_count,
+                status="failed",
+            ),
+        )
+        return
+
+    outcome_status = "ok" if failure_count == 0 else "partial"
+    await _log_event(
+        auth,
+        action,
+        target_type,
+        target_id,
+        _build_event_payload(
+            params,
+            success_count=success_count,
+            failure_count=failure_count,
+            target_count=target_count,
+            status=outcome_status,
+        ),
+    )
+
+
+async def log_command_result_by_name(
+    key_name: str,
+    target_type: str,
+    target_id: str,
+    params: dict,
+    *,
+    success_count: int = 1,
+    failure_count: int = 0,
+    target_count: int = 1,
+):
+    """Логирует результат команды из контекста без AuthContext (для планировщика)."""
+    auth = AuthContext(is_master=False, is_admin=False, key_name=key_name)
+    await log_command_result(
+        auth,
+        target_type,
+        target_id,
+        params,
+        success_count=success_count,
+        failure_count=failure_count,
+        target_count=target_count,
+    )
+
+
+def _response_error_status(result: WizResponse) -> int:
+    if result.kind == "timeout":
+        return 504
+    return 502
+
+
+def _response_error_detail(result: WizResponse, *, prefix: str) -> str:
+    if result.message:
+        return f"{prefix}: {result.message}"
+    if result.kind == "timeout":
+        return f"{prefix}: таймаут ответа"
+    return f"{prefix}: ошибка обмена с лампой"
+
+
+def _serialize_wiz_result(ip: str, result: WizResponse) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ip": ip,
+        "ok": result.ok,
+        "kind": result.kind,
+    }
+    if result.ok:
+        payload["result"] = result.result
+    else:
+        payload["error"] = result.message or result.kind
+    return payload
+
+
+def _summarize_group_results(results: list[WizResponse]) -> tuple[int, int]:
+    success_count = sum(1 for item in results if item.ok)
+    failure_count = len(results) - success_count
+    return success_count, failure_count
 
 
 @router.post("/device/{device_id}")
@@ -67,27 +219,42 @@ async def control_device(
     if not device:
         raise HTTPException(status_code=404, detail="Лампа не в сети")
 
-    params = {}
-    if state is not None:
-        params["state"] = state
-    if brightness is not None:
-        params["dimming"] = brightness
-
-    if scene and scene in wiz.SCENES:
-        params["sceneId"] = wiz.SCENES[scene]
-    elif temp is not None:
-        params["temp"] = temp
-    elif any(v is not None for v in [r, g, b]):
-        params["r"], params["g"], params["b"] = r or 0, g or 0, b or 0
-
+    params = _build_command_params(state, brightness, scene, temp, r, g, b)
     if not params:
         raise HTTPException(status_code=400, detail="Никаких команд не передано")
 
     result = await wiz.set_pilot(device.ip, params)
+    if not result.ok:
+        await log_command_result(
+            auth,
+            "device",
+            device_id,
+            params,
+            success_count=0,
+            failure_count=1,
+            target_count=1,
+        )
+        raise HTTPException(
+            status_code=_response_error_status(result),
+            detail=_response_error_detail(result, prefix="Команда лампе не доставлена"),
+        )
 
-    await log_toggle(auth, "device", device_id, params)
+    await log_command_result(
+        auth,
+        "device",
+        device_id,
+        params,
+        success_count=1,
+        failure_count=0,
+        target_count=1,
+    )
 
-    return {"device_id": device_id, "applied": params, "result": result}
+    return {
+        "device_id": device_id,
+        "applied": params,
+        "result": result.payload,
+        "status": "ok",
+    }
 
 
 @router.post("/group/{group_id}")
@@ -106,25 +273,44 @@ async def control_group(
     if not ips:
         raise HTTPException(status_code=404, detail="Группа не найдена или оффлайн")
 
-    params = {}
-    if state is not None:
-        params["state"] = state
-    if brightness is not None:
-        params["dimming"] = brightness
-
-    if scene and scene in wiz.SCENES:
-        params["sceneId"] = wiz.SCENES[scene]
-    elif temp is not None:
-        params["temp"] = temp
-    elif any(v is not None for v in [r, g, b]):
-        params["r"], params["g"], params["b"] = r or 0, g or 0, b or 0
+    params = _build_command_params(state, brightness, scene, temp, r, g, b)
+    if not params:
+        raise HTTPException(status_code=400, detail="Никаких команд не передано")
 
     tasks = [wiz.set_pilot(ip, params) for ip in ips]
-    await asyncio.gather(*tasks, return_exceptions=True)
+    results = await asyncio.gather(*tasks)
+    success_count, failure_count = _summarize_group_results(results)
 
-    await log_toggle(auth, "group", group_id, params)
+    await log_command_result(
+        auth,
+        "group",
+        group_id,
+        params,
+        success_count=success_count,
+        failure_count=failure_count,
+        target_count=len(results),
+    )
 
-    return {"status": "ok", "applied": params, "sent_to": ips}
+    if success_count == 0:
+        first_failure = next(item for item in results if not item.ok)
+        raise HTTPException(
+            status_code=_response_error_status(first_failure),
+            detail=_response_error_detail(
+                first_failure, prefix="Команда группе не доставлена"
+            ),
+        )
+
+    group_status = "ok" if failure_count == 0 else "partial"
+    return {
+        "status": group_status,
+        "applied": params,
+        "sent_to": ips,
+        "success_count": success_count,
+        "failure_count": failure_count,
+        "results": [
+            _serialize_wiz_result(ip, result) for ip, result in zip(ips, results)
+        ],
+    }
 
 
 @router.post("/device/{device_id}/blink")
@@ -133,16 +319,36 @@ async def blink_device(device_id: str, _auth: AuthContext = Depends(verify_token
     if not device:
         raise HTTPException(status_code=404, detail="Лампа оффлайн")
 
-    try:
-        current = await wiz.get_pilot(device.ip)
-        original_state = current.get("result", {}).get("state", False)
-        await wiz.set_pilot(device.ip, {"state": not original_state})
-        await asyncio.sleep(0.5)
-        await wiz.set_pilot(device.ip, {"state": original_state})
-        return {"status": "blink_done", "original": original_state}
-    except Exception as e:
-        logger.error(f"Blink error: {e}")
-        raise HTTPException(status_code=500, detail="Ошибка связи с лампой")
+    current = await wiz.get_pilot(device.ip)
+    if not current.ok:
+        raise HTTPException(
+            status_code=_response_error_status(current),
+            detail=_response_error_detail(
+                current, prefix="Не удалось получить текущее состояние лампы"
+            ),
+        )
+
+    original_state = current.result.get("state", False)
+    first_toggle = await wiz.set_pilot(device.ip, {"state": not original_state})
+    if not first_toggle.ok:
+        raise HTTPException(
+            status_code=_response_error_status(first_toggle),
+            detail=_response_error_detail(
+                first_toggle, prefix="Не удалось выполнить первую фазу blink"
+            ),
+        )
+
+    await asyncio.sleep(0.5)
+    second_toggle = await wiz.set_pilot(device.ip, {"state": original_state})
+    if not second_toggle.ok:
+        raise HTTPException(
+            status_code=_response_error_status(second_toggle),
+            detail=_response_error_detail(
+                second_toggle, prefix="Не удалось восстановить исходное состояние"
+            ),
+        )
+
+    return {"status": "blink_done", "original": original_state}
 
 
 @router.get("/device/{device_id}/status")
@@ -152,11 +358,14 @@ async def get_device_status(device_id: str, _auth: AuthContext = Depends(verify_
     if not device:
         raise HTTPException(status_code=404, detail="Лампа оффлайн или не найдена")
 
-    try:
-        status = await wiz.get_pilot(device.ip)
-        return {"device_id": device_id, "status": status.get("result", {})}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Ошибка опроса лампы: {e}")
+    status = await wiz.get_pilot(device.ip)
+    if not status.ok:
+        raise HTTPException(
+            status_code=_response_error_status(status),
+            detail=_response_error_detail(status, prefix="Ошибка опроса лампы"),
+        )
+
+    return {"device_id": device_id, "status": status.result}
 
 
 @router.get("/group/{group_id}/status")
@@ -166,14 +375,20 @@ async def get_group_status(group_id: str, _auth: AuthContext = Depends(verify_to
     if not ips:
         raise HTTPException(status_code=404, detail="Группа не найдена или оффлайн")
 
-    tasks = [wiz.get_pilot(ip) for ip in ips]
-    results = await asyncio.gather(*tasks, return_exceptions=True)
+    results = await asyncio.gather(*[wiz.get_pilot(ip) for ip in ips])
 
     status_report = []
     for ip, res in zip(ips, results):
-        if isinstance(res, Exception):
-            status_report.append({"ip": ip, "error": str(res)})
-        else:
-            status_report.append({"ip": ip, "status": res.get("result", {})})
+        if res.ok:
+            status_report.append({"ip": ip, "status": res.result})
+            continue
+
+        status_report.append(
+            {
+                "ip": ip,
+                "error": res.message or res.kind,
+                "kind": res.kind,
+            }
+        )
 
     return {"group_id": group_id, "results": status_report}