docs: пояснения почему выбрана такая логика (reasoning)

api/dtc.py

@@ -37,7 +37,12 @@ def register(app):
 
     @app.route("/api/v1/dtc/decode", methods=["POST"])
     def dtc_decode():
-        """Расшифровка кодов DTC из справочника."""
+        """Расшифровка кодов DTC из справочника doc/dtc_codes.txt.
+
+        Принимает: {"codes": ["P0301", "P0302"]}
+        Возвращает: {"codes": [{"code": "P0301", "desc": "..."}]}
+        Неизвестные коды возвращаются как есть — справочник неполный.
+        """
         data = request.get_json(silent=True) or {}
         codes = data.get("codes", [])
         if not codes:
@@ -48,7 +53,13 @@ def register(app):
 
     @app.route("/api/v1/dtc/upload", methods=["POST"])
     def dtc_upload():
-        """Приём кодов ошибок (без полной диагностики)."""
+        """Приём кодов ошибок (без полной диагностики, только Ошибки).
+
+        Идемпотентность: если client шлёт request_id, сервер:
+          1. Проверяет кэш — если есть, возвращает его (LLM не вызывается)
+          2. Если нет — сохраняет, кэширует ответ
+        Это предотвращает дубликаты при повторных отправках (например, 499).
+        """
         data = request.get_json(silent=True)
         if not data:
             return jsonify({"error": "empty"}), 400

api/parser.py

@@ -44,13 +44,20 @@ def parse_batch(responses: list[dict]) -> dict:
 
 
 def _parse_vin(result: dict, raw: str, decoded: str):
+    """Извлечь VIN из decoded (Android) или из raw HEX (fallback).
+
+    Два пути получения VIN:
+      1. Android-декодер уже распарсил → decoded = "VIN: WVWZZZ..."
+      2. Сырой HEX от ELM → парсим 490201 + 17 байт ASCII
+    Fallback нужен для старых клиентов без декодера.
+    """
     if decoded.startswith("VIN:"):
         vin = decoded.replace("VIN:", "").strip()
         if len(vin) == 17:
             result["vin"] = vin
             return
 
-    # Fallback: парсим VIN из raw HEX
+    # Fallback: парсим VIN из raw HEX (CAN multi-frame, ISO-TP, обычный)
     if "49" in raw and ("02" in raw or "4902" in raw.replace(" ", "")):
         # Чистим: убираем CAN адресацию (N:), ISO-TP (10..), двоеточия
         import re