feat: ASRX hybrid pipeline, identity history, worker fixes, checkpoint system

2026-06-02 07:13:23 +08:00
parent e3066c3f49
commit e1572907ae
198 changed files with 43705 additions and 8910 deletions
--- a/deliverable_v1.1.0/modules/02_health.md
+++ b/deliverable_v1.1.0/modules/02_health.md
@@ -0,0 +1,147 @@
+<!-- module: health -->
+<!-- description: Health check endpoints -->
+<!-- depends: 01_auth -->
+
+## Health Check
+
+### `GET /health`
+
+**Auth**: Public
+**Scope**: system-level
+
+Returns basic server health status — used by load balancers and monitoring.
+
+#### Example
+
+```bash
+curl "$API/health" | jq '{status, version}'
+```
+
+#### Response (200)
+
+```json
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "build_git_hash": "3a6c1865",
+  "build_timestamp": "2026-05-16T13:38:15Z",
+  "uptime_ms": 3015
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | string | `ok` or `degraded` |
+| `version` | string | Semver version |
+| `build_git_hash` | string | Git commit hash |
+| `build_timestamp` | string | Binary build time |
+| `uptime_ms` | integer | Milliseconds since server start |
+
+---
+
+### `GET /health/detailed`
+
+**Auth**: Required
+**Scope**: system-level
+
+Returns full system health including each service status, resource utilization, pipeline readiness, schema migration status, identity file sync status, and external integrations.
+
+> Requires authentication (JWT, session cookie, or API key). The basic `/health` endpoint remains public for load balancer checks.
+
+#### Example
+
+```bash
+curl "$API/health/detailed" | jq '{status, services, resources: {cpu: .resources.cpu_used_percent, memory: .resources.memory_used_percent}}'
+```
+
+#### Response (200)
+
+```json
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "services": {
+    "postgres": {"status": "ok", "latency_ms": 3},
+    "redis": {"status": "ok", "latency_ms": 1},
+    "qdrant": {"status": "ok", "latency_ms": 5}
+  },
+  "resources": {
+    "cpu_used_percent": 12.5,
+    "memory_available_mb": 32768,
+    "memory_used_percent": 31.7
+  },
+  "pipeline": {
+    "scripts_ready": true,
+    "scripts_count": 345,
+    "processors": {
+      "asr": true,
+      "yolo": true,
+      "face": true,
+      "pose": true,
+      "ocr": true,
+      "cut": true,
+      "scene": true,
+      "asrx": true,
+      "visual_chunk": true
+    },
+    "models_ready": true,
+    "models_count": 42,
+    "scripts_integrity": {"matched": 332, "total": 345, "ok": false},
+    "ffmpeg": true
+  },
+  "schema": {
+    "table_exists": true,
+    "applied": [{"filename": "migrate_add_users_table.sql"}],
+    "required": [],
+    "ok": true
+  },
+  "identities": {
+    "directory_exists": true,
+    "files_count": 3481,
+    "index_ok": true,
+    "db_count": 3481,
+    "synced": true
+  },
+  "integrations": {
+    "tmdb": {
+      "api_key_configured": false,
+      "enabled": false,
+      "api_reachable": null
+    }
+  }
+}
+```
+
+#### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | string | `ok` if all essential services healthy |
+| `services` | object | Per-service status (postgres, redis, qdrant) |
+| `services.*.status` | string | `ok`, `error`, or `degraded` |
+| `services.*.latency_ms` | int | Response time in milliseconds |
+| `resources` | object | CPU, memory usage |
+| `pipeline.scripts_ready` | boolean | Scripts directory accessible |
+| `pipeline.scripts_count` | int | Number of Python processor scripts |
+| `pipeline.processors` | object | Per-processor availability |
+| `pipeline.models_ready` | boolean | Models directory accessible |
+| `pipeline.scripts_integrity` | object | SHA256 checksum verification results |
+| `schema.ok` | boolean | All required migrations applied |
+| `identities.synced` | boolean | Identity file count matches DB count |
+| `integrations.tmdb` | object | TMDB API key config and reachability |
+
+#### Health status rules
+
+| Condition | status |
+|-----------|--------|
+| All services ok | `ok` |
+| Any service error | `degraded` |
+| Postgres or Redis error | `degraded` (server still responds) |
+
+---
+
+### Stats Endpoints
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/api/v1/stats/sftpgo` | No | SFTPGo service status |