[AZ-137] [AZ-138] Decompose test tasks and scaffold E2E test infrastructure

Made-with: Cursor

_docs/02_document/system-flows.md

@@ -150,7 +150,34 @@ sequenceDiagram
 | 4 | Engine | Inference | raw detections | numpy ndarray |
 | 5 | Inference | API (callback) | Annotation + percent | Python objects |
 | 6 | API | SSE clients | DetectionEvent | SSE JSON stream |
-| 7 | API | Annotations Service | detections + base64 image | HTTP POST JSON |
+| 7 | API | Annotations Service | CreateAnnotationRequest | HTTP POST JSON |
+
+**Step 7 — Annotations POST detail:**
+
+Fired once per detection batch when auth token is present. The request to `POST {ANNOTATIONS_URL}/annotations` carries:
+
+```json
+{
+  "mediaId": "string",
+  "source": 0,
+  "videoTime": "00:01:23",
+  "detections": [
+    {
+      "centerX": 0.56, "centerY": 0.67,
+      "width": 0.25, "height": 0.22,
+      "classNum": 3, "label": "ArmorVehicle",
+      "confidence": 0.92
+    }
+  ],
+  "image": "<base64 encoded frame bytes, optional>"
+}
+```
+
+`userId` is not included — the Annotations service resolves the user from the JWT. The Annotations API contract also accepts `description`, `affiliation`, and `combatReadiness` on each detection, but Detections does not populate these.
+
+Authorization: `Bearer {accessToken}` forwarded from the original client request. For long-running video, the token is auto-refreshed via `POST {ANNOTATIONS_URL}/auth/refresh`.
+
+The Annotations service responds 201 on success, 400 if neither image nor mediaId provided, 404 if mediaId unknown. On the Annotations side, the saved annotation triggers: SSE notification to UI, and enqueue to the RabbitMQ sync pipeline (unless SilentDetection mode).
 
 ### Error Scenarios
 
@@ -160,6 +187,8 @@ sequenceDiagram
 | Engine unavailable | run_detect | engine is None | Error event pushed to SSE |
 | Inference failure | processing | Exception | Error event pushed to SSE, media_id cleared |
 | Annotations POST failure | _post_annotation | Exception | Silently caught, detection continues |
+| Annotations 404 | _post_annotation | MediaId not found in Annotations DB | Silently caught, detection continues |
+| Token refresh failure | TokenManager | Exception on /auth/refresh | Silently caught, subsequent POSTs may fail with 401 |
 | SSE queue full | event broadcast | QueueFull | Event silently dropped for that client |
 
 ---