init: add contract definitions and database schema with migrations skeleton

contract/api/common.schema.json

@@ -0,0 +1,17 @@
+{
+  "$id": "contract/api/common.schema.json",
+  "type": "object",  "required": ["ok"],
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "data": {},
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": { "type": "string" },
+        "message": { "type": "string" }
+      }
+    }
+  }
+}

contract/api/timeseries.schema.json

@@ -0,0 +1,18 @@
+{
+  "type": "object",
+  "required": ["points"],
+  "properties": {
+    "points": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["ts", "value"],
+        "properties": {
+          "ts": { "type": "integer" },
+          "value": {}
+        },
+        "additionalProperties": false
+      }
+    }
+  }
+}

contract/ingest/common.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "contract/ingest/common.schema.json",
+  "type": "object",
+  "required": ["v", "id", "type", "ts", "deviceId", "payload"],
+  "additionalProperties": false,
+  "properties": {
+    "v": {
+      "type": "integer",
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "type": {
+      "type": "string",
+      "enum": ["telemetry", "event"]
+    },
+    "ts": {
+      "type": "integer",
+      "minimum": 1600000000000,
+      "description": "Unix time in milliseconds (UTC)"
+    },
+    "deviceId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "payload": {
+      "type": "object"
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

contract/ingest/event.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "contract/ingest/event.schema.json",
+  "allOf": [
+    { "$ref": "contract/ingest/common.schema.json" },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "const": "event"
+        },
+        "payload": {
+          "type": "object",
+          "required": ["name"],
+          "additionalProperties": false,
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Event identifier, e.g. device.overheat"
+            },
+            "severity": {
+              "type": "string",
+              "enum": ["debug", "info", "warn", "error", "fatal"]
+            },
+            "message": {
+              "type": "string"
+            },
+            "data": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      }
+    }
+  ]
+}

contract/ingest/telemetry.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "contract/ingest/telemetry.schema.json",
+  "allOf": [
+    { "$ref": "contract/ingest/common.schema.json" },
+    {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["measurements"],
+          "additionalProperties": false,
+          "properties": {
+            "measurements": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "required": ["metric", "value"],
+                "additionalProperties": false,
+                "properties": {
+                  "metric": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "value": {
+                    "type": ["number", "string", "boolean"]
+                  },
+                  "unit": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  },
+                  "ts": {
+                    "type": "integer"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

contract/readme.md

@@ -0,0 +1,18 @@
+## Контракты
+
+В системе используются два независимых контракта:
+
+### 1. Ingest (devices → backend)
+
+- поток сырых данных
+- оптимизирован под запись
+- минимальный размер сообщений
+- формат: telemetry / event
+
+### 2. API (backend → mobile)
+
+- агрегированные данные
+- оптимизирован под чтение
+- формат зависит от UI (графики, таблицы, статусы)
+
+⚠️ Эти контракты НЕ обязаны совпадать