feat: Phase 1 handover - schema migration, correction mechanism, API fixes

Schema changes: dev.chunks->dev.chunk, remove old_chunk_id/chunk_index
Correction: asr-1.json format, generate/apply scripts
API: 37/37 endpoints fixed and tested
Docs: HANDOVER_V2.0.md for M4

docs_v1.0/STANDARDS/API_DESIGN_PRINCIPLES_V1.0.0.md

@@ -0,0 +1,101 @@
+# API Design Principles v1.0.0
+
+## Entities
+
+- **Primary entities**: `file` / `files`, `identity` / `identities`
+- `video` is a type of `file` — not a separate entity
+
+## Route Structure: Action-Oriented
+
+```
+/api/v1/{entity}/{id}/{action}
+            ↑        ↑      ↑
+          實體      ID    動作（動詞）
+```
+
+Every path segment after the resource ID is a **verb** — an action on that resource.
+
+```
+/api/v1/file/:file_uuid
+  /video          → play video
+  /video/bbox     → play with bbox overlay
+  /thumbnail      → extract thumbnail
+  /process        → start processing
+  /probe          → probe metadata
+  /chunks         → list chunks
+  /identities     → list identities
+  /face_trace     → list face traces
+  /trace/:tid/faces → list detections
+```
+
+## Singular vs Plural
+
+| Usage | Form | Examples |
+|-------|------|----------|
+| **Collection list** | plural | `/files`, `/identities`, `/resources`, `/faces` |
+| **Single resource action** | singular | `/file/:uuid`, `/identity/:uuid` |
+
+## ID Naming
+
+| Scope | Naming | Examples |
+|-------|--------|----------|
+| **Globally unique** → `uuid` | `_uuid` suffix | `file_uuid`, `identity_uuid` |
+| **Unique within entity** → `id` | `_id` suffix | `trace_id`, `chunk_id`, `face_id` |
+
+## Pagination
+
+All list endpoints share consistent pagination parameters:
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `page` | int | 1 | Page number (1-based) |
+| `page_size` | int | 20 | Items per page |
+| `limit` | int | null | Hard cap (search-only, no pagination) |
+
+Response:
+```json
+{"data": [...], "total": 100, "page": 1, "page_size": 20}
+```
+
+## Trace Completeness & Density
+
+Face management references by `trace_id`, not `face_id` (except single-frame ops).
+
+| Density | face_count | Description |
+|:-------:|:----------:|-------------|
+| Sparse | 1 | Single detection, no tracking |
+| Minimal | 3 | First + mid + last |
+| Standard | 5 | First + 3 mid + last |
+| Dense | 10–30 | Every Nth frame |
+| Full | all | Every frame |
+| Interpolated | all + lerp | Linear interpolation between sparse detections |
+
+Default recommendation: **5** (standard) for most use cases. **Interpolated** for visual playback / MR.
+
+## Trace Data Model
+
+```
+Trace ──1:N──> Detection (single frame, bbox + confidence)
+Trace ──N:1──> Identity (person)
+```
+
+Each trace has:
+- `trace_id` (unique per file)
+- `file_uuid` (source video)
+- `face_count` (number of detections)
+- `first_frame`, `last_frame`, `duration_sec`
+- `avg_confidence`, `min_confidence`, `max_confidence`
+- `interpolated` flag per detection (true = lerp-generated)
+
+## Auth
+
+Header: `X-API-Key: <key>`
+
+Login endpoint: `POST /api/v1/auth/login` (unprotected)
+
+Demo credentials: `demo` / `demo`
+
+## Related
+
+- `API_V1.0.0/TRACE/TRACE_API_REFERENCE_V1.0.0.md` — Trace-specific design
+- `API_V1.0.0/API_DICTIONARY_V1.0.0.md` — Full endpoint list