docs: update TKG, profile, identity module docs with trace management and external_id fix

- 15_tkg.md: external_id format changed to trace_N, added trace management section (delete/restore/merge) - 18_profile.md: note external_id matching fix - 07_identity.md: note bind/unbind external_id fix - regenerated user docs (doc/)
2026-07-21 03:22:09 +08:00
parent 52bec30c90
commit 644516769c
7 changed files with 237 additions and 29 deletions
@@ -1102,4 +1102,5 @@ PATCH /api/v1/identity/:identity_uuid
 This **replaces** the entire `aliases` array. To add to existing aliases, include all existing entries in the request.

 ---
+*Updated: 2026-07-21 — Fixed bind/unbind TKG update to match both trace_N and face_track_N external_id formats*
 *Updated: 2026-06-20 — Added identity files, chunks, faces, status, and JSON endpoints*
@@ -14,7 +14,7 @@ TKG is a time-aligned knowledge graph built from multi-processor outputs (face,

 | Node Type | External ID Format | Description | Key Properties |
 |-----------|-------------------|-------------|----------------|
-| `face_track` | `face_track_{trace_id}` | A tracked face identity over time | `trace_id`, `frame_count`, `status`, `pending_identity_name`, `confidence`, `identity_uuid` |
+| `face_track` | `trace_{trace_id}` | A tracked face identity over time | `trace_id`, `frame_count`, `status`, `avg_bbox`, `avg_yaw`, `avg_pitch`, `avg_roll`, `start_frame`, `end_frame`, `pose_count` |
 | `gaze_track` | `gaze_track_{id}` | Gaze direction over time | `direction` (frontal/left/right/up/down + diagonals) |
 | `lip_track` | `lip_track_{id}` | Lip movement synced with speech | `speaker_id`, `lip_area_range` |
 | `text_region` | `text_region_{id}` | Spoken text aligned to time | `speaker_id`, `text`, `start_time`, `end_time` |
@@ -426,4 +426,101 @@ curl -s "$API/api/v1/file/$FILE_UUID/processor-counts" \

 ---

-*Updated: 2026-06-25 17:00:00*
+### Trace Management
+
+Endpoints for managing face traces: list, delete, restore, and merge.
+
+#### `DELETE /api/v1/file/:file_uuid/trace/:trace_id`
+
+**Auth**: Required
+
+Soft-delete a face trace (default) or hard-delete with `{"hard_delete": true}`.
+
+Soft delete marks Qdrant points with `status: "deleted"` and TKG nodes with `status: "deleted"` in properties. Deleted traces are excluded from the traces list.
+
+Hard delete permanently removes Qdrant points and TKG nodes.
+
+**Request Body** (optional):
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `hard_delete` | boolean | `false` | Permanently delete instead of marking |
+
+**Example**:
+```bash
+# Soft delete
+curl -X DELETE "$API/api/v1/file/$FILE_UUID/trace/8" \
+  -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{}'
+
+# Hard delete
+curl -X DELETE "$API/api/v1/file/$FILE_UUID/trace/8" \
+  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
+  -d '{"hard_delete": true}'
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
+  "trace_id": 8,
+  "hard_delete": false,
+  "qdrant_marked": true,
+  "tkg_nodes_marked": 1
+}
+```
+
+---
+
+#### `POST /api/v1/file/:file_uuid/trace/:trace_id/restore`
+
+**Auth**: Required
+
+Undo a soft-deleted trace. Clears `status: "deleted"` from Qdrant points and TKG node properties.
+
+**Example**:
+```bash
+curl -X POST "$API/api/v1/file/$FILE_UUID/trace/8/restore" \
+  -H "X-API-Key: $KEY"
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
+  "trace_id": 8,
+  "qdrant_restored": true,
+  "tkg_nodes_restored": 1
+}
+```
+
+---
+
+#### `POST /api/v1/file/:file_uuid/trace/:source_trace_id/merge/:target_trace_id`
+
+**Auth**: Required
+
+Merge all face points from source trace into target trace. Updates Qdrant `trace_id` and deletes source TKG node.
+
+**Example**:
+```bash
+curl -X POST "$API/api/v1/file/$FILE_UUID/trace/16/merge/3" \
+  -H "X-API-Key: $KEY"
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "file_uuid": "9f6a9cd55a5809f977f5a6589b9045c5",
+  "source_trace_id": 16,
+  "target_trace_id": 3,
+  "points_moved": 58,
+  "tkg_nodes_deleted": 1
+}
+```
+
+---
+
+*Updated: 2026-07-21 01:00:00*
@@ -264,4 +264,5 @@ curl -s -X PUT "$API/api/v1/file-profile" \
 | `aliases` | `properties->'aliases'` | Multi-language name aliases |

 ---
+*Updated: 2026-07-21 — Fixed external_id matching (trace_N + face_track_N formats), fixed parameter ordering in UPDATE query*
 *Updated: 2026-07-18 — New profile module: trace-profile (GET, PUT, PUT group) and file-profile (GET, PUT)*