init: add contract definitions and database schema with migrations skeleton

.gitignore

@@ -30,3 +30,16 @@ build/
 sdkconfig
 sdkconfig.old
 Kconfig
+
+.git/
+
+# ide
+.idea/
+.vscode/
+
+# env
+.env
+*.env
+
+application.yaml
+application.conf

backend/src/main/resources/application.conf.example

@@ -0,0 +1,16 @@
+ktor {
+  host = "0.0.0.0"
+  port = 8080
+}
+
+app {
+  name = "iot-backend"
+}
+
+api {
+  prefix = "/api/v1"
+}
+
+ws {
+  path = "/ws"
+}

backend/src/main/resources/application.yaml.example

@@ -0,0 +1,12 @@
+ktor:
+  host: 0.0.0.0
+  port: 8080
+
+app:
+  name: iot-backend
+
+api:
+  prefix: /api/v1
+
+ws:
+  path: /ws

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 (графики, таблицы, статусы)
+
+⚠️ Эти контракты НЕ обязаны совпадать

db/README.md

@@ -0,0 +1,4 @@
+- все изменения только через migrations
+- schema.sql = текущее состояние
+- старые migrations не редактируем
+- версия базы = schema_version

db/schema.sql

@@ -0,0 +1,5 @@
+CREATE TABLE schema_version (
+    version    INT PRIMARY KEY,
+    applied_at TIMESTAMP NOT NULL,
+    checksum   VARCHAR(64) NOT NULL
+);

protocol/schema.json

@@ -1,12 +1,31 @@
 {
   "type": "object",
-  "required": ["v", "id", "type", "ts", "deviceId", "payload"],
+  "required": ["v", "type", "ts", "deviceId", "payload"],
   "properties": {
-    "v": { "type": "integer" },
-    "id": { "type": "string" },
-    "type": { "type": "string" },
-    "ts": { "type": "integer" },
-    "deviceId": { "type": "string" },
-    "payload": { "type": "object" }
+    "v": {
+      "type": "integer",
+      "description": "Protocol version"
+    },
+
+    "type": {
+      "type": "string",
+      "description": "Message type"
+    },
+
+    "ts": {
+      "type": "integer",
+      "description": "Unix time in milliseconds"
+    },
+
+    "deviceId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique device identifier"
+    },
+
+    "payload": {
+      "type": "object",
+      "description": "Message-specific data"
+    }
   }
 }