docs: final compliance audit — uuid naming + start/end standardization

2026-05-14 18:00:51 +08:00
parent b5215f13e3
commit 54763ea88d
7 changed files with 14 additions and 14 deletions
--- a/docs_v1.0/API_V1.0.0/API_DOCUMENTATION.md
+++ b/docs_v1.0/API_V1.0.0/API_DOCUMENTATION.md
@@ -269,7 +269,7 @@ Response `200`:

 ```
 GET /api/v1/files
-Query: ?page=1&page_size=10&uuid=xxx
+Query: ?page=1&page_size=10&file_uuid=xxx
 ```

 Response `200`:
--- a/docs_v1.0/API_V1.0.0/RELEASE/PRODUCTION_TEST_REPORT_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/PRODUCTION_TEST_REPORT_V1.0.0.md
@@ -26,7 +26,7 @@ GET /health

 ### 2. Face Trace List ✅
 ```bash
-POST /api/v1/file/{uuid}/face_trace/sortby -d '{"sort_by":"face_count","limit":3}'
+POST /api/v1/file/{file_uuid}/face_trace/sortby -d '{"sort_by":"face_count","limit":3}'
 → 6892 traces, 108204 faces
  trace #3128: 1109 faces, conf=0.78
  trace #3126: 743 faces, conf=0.76
@@ -35,13 +35,13 @@ POST /api/v1/file/{uuid}/face_trace/sortby -d '{"sort_by":"face_count","limit":3

 ### 3. BM25 Search ✅
 ```bash
-POST /api/v1/search/universal -d '{"query":"name","mode":"bm25","uuid":"{uuid}"}'
+POST /api/v1/search/universal -d '{"query":"name","mode":"bm25","file_uuid":"{file_uuid}"}'
 → "What's your name?" (score=0.90)
 ```

 ### 4. Trace Faces (interpolation) ✅
 ```bash
-GET /api/v1/file/{uuid}/trace/2/faces?limit=5&interpolate=true
+GET /api/v1/file/{file_uuid}/trace/2/faces?limit=5&interpolate=true
 → Real + interpolated frames with linear bbox transition
 ```

--- a/docs_v1.0/API_V1.0.0/RELEASE/PRODUCTION_TEST_REPORT_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/PRODUCTION_TEST_REPORT_v1.0.0.md
@@ -26,7 +26,7 @@ GET /health

 ### 2. Face Trace List ✅
 ```bash
-POST /api/v1/file/{uuid}/face_trace/sortby -d '{"sort_by":"face_count","limit":3}'
+POST /api/v1/file/{file_uuid}/face_trace/sortby -d '{"sort_by":"face_count","limit":3}'
 → 6892 traces, 108204 faces
  trace #3128: 1109 faces, conf=0.78
  trace #3126: 743 faces, conf=0.76
@@ -35,13 +35,13 @@ POST /api/v1/file/{uuid}/face_trace/sortby -d '{"sort_by":"face_count","limit":3

 ### 3. BM25 Search ✅
 ```bash
-POST /api/v1/search/universal -d '{"query":"name","mode":"bm25","uuid":"{uuid}"}'
+POST /api/v1/search/universal -d '{"query":"name","mode":"bm25","file_uuid":"{file_uuid}"}'
 → "What's your name?" (score=0.90)
 ```

 ### 4. Trace Faces (interpolation) ✅
 ```bash
-GET /api/v1/file/{uuid}/trace/2/faces?limit=5&interpolate=true
+GET /api/v1/file/{file_uuid}/trace/2/faces?limit=5&interpolate=true
 → Real + interpolated frames with linear bbox transition
 ```

--- a/docs_v1.0/API_V1.0.0/RELEASE/PRODUCTION_VERIFICATION_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/PRODUCTION_VERIFICATION_V1.0.0.md
@@ -88,13 +88,13 @@ related_documents:
 | :--- | :--- | :--- | :--- | :--- | :--- |
 | `/api/v1/search` | POST | `{"query":"test", "limit":3}` | `200 OK` | `{"results": [], "query": "test"}` | ✅ **PASS** |
 | `/api/v1/search/hybrid` | POST | `{"query":"test", "limit":3}` | `200 OK` | `{"results": [], "query": "test"}` | ✅ **PASS** |
-| `/api/v1/search/visual/class`| POST | `{"uuid":"...", "object_class":"person"}`| `200 OK` | `{"chunks": [], "total": 0}` | ✅ **PASS** |
+| `/api/v1/search/visual/class`| POST | `{"file_uuid":"...", "object_class":"person"}`| `200 OK` | `{"chunks": [], "total": 0}` | ✅ **PASS** |

 ### 2.4 身份與人物管理 (Identity Management)
 | API Endpoint | Method | 測試參數 | HTTP 狀態 | 回應摘要 | 結果 |
 | :--- | :--- | :--- | :--- | :--- | :--- |
 | `/api/v1/identities` | GET | `page=1&page_size=2` | `200 OK` | `{"identities": [{"id": 2, "name": "Audrey Hepburn"}], "count": 2}` | ✅ **PASS** |
-| `/api/v1/identities/:uuid`| GET | `uuid: a9a90105...` | `200 OK` | `{"success": true, "uuid": "...", "name": "Trace 2 Fixed Format"}` | ✅ **PASS** |
+| `/api/v1/identities/:identity_uuid`| GET | `identity_uuid: a9a90105...` | `200 OK` | `{"success": true, "file_uuid": "...", "name": "Trace 2 Fixed Format"}` | ✅ **PASS** |
 | `/api/v1/identities/bind` | POST | `{"identity_id": 2, ...}` | `200 OK` | `{"success": true, "message": "Bound face 'release_test_final' to Identity..."}` | ✅ **PASS** |

 ### 2.5 臉部與快照 (Face & Snapshots)
@@ -106,7 +106,7 @@ related_documents:
 ### 2.6 任務與代理人 (Jobs & Agents)
 | API Endpoint | Method | 測試參數 | HTTP 狀態 | 回應摘要 | 結果 |
 | :--- | :--- | :--- | :--- | :--- | :--- |
-| `/api/v1/progress/:uuid` | GET | `uuid: 232b98...` | `200 OK` | `{"uuid": "...", "overall_progress": 0, "processors": [...]}` | ✅ **PASS** |
+| `/api/v1/progress/:file_uuid` | GET | `file_uuid: 232b98...` | `200 OK` | `{"file_uuid": "...", "overall_progress": 0, "processors": [...]}` | ✅ **PASS** |
 | `/api/v1/assets/:uuid/process`| POST | `uuid: 232b98...` | `400 Bad Request` | `{"message": "Total frames unknown. Run probe first."}` (預期邏輯檢查) | ✅ **PASS** |

 ---
--- a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_V1.0.0.md
@@ -94,7 +94,7 @@ curl -X POST $BASE/api/v1/files/register -H "$KEY" \
 ```bash
 curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
  -H "Content-Type: application/json" \
-  -d '{"query":"name","limit":2,"mode":"bm25","uuid":"$FILE"}'
+  -d '{"query":"name","limit":2,"mode":"bm25","file_uuid":"$FILE"}'
 ```
 ```json
 {"count":1,"results":[{"text":"What's your name?","score":0.90}]}
--- a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_API_REFERENCE_v1.0.0.md
@@ -94,7 +94,7 @@ curl -X POST $BASE/api/v1/files/register -H "$KEY" \
 ```bash
 curl -X POST $BASE/api/v1/search/universal -H "$KEY" \
  -H "Content-Type: application/json" \
-  -d '{"query":"name","limit":2,"mode":"bm25","uuid":"$FILE"}'
+  -d '{"query":"name","limit":2,"mode":"bm25","file_uuid":"$FILE"}'
 ```
 ```json
 {"count":1,"results":[{"text":"What's your name?","score":0.90}]}
--- a/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_VERIFICATION_V1.0.0.md
+++ b/docs_v1.0/API_V1.0.0/RELEASE/RELEASE_VERIFICATION_V1.0.0.md
@@ -138,7 +138,7 @@ curl -H "X-API-Key: muser_test_001" "http://localhost:3002/api/v1/files/53e3a229
 #### `POST /api/v1/search`
 ```bash
 curl -X POST -H "X-API-Key: muser_test_001" -H "Content-Type: application/json" \
-  -d '{"query":"test", "uuid":"53e3a229bf68878b7a799e811e097f9c"}' \
+  -d '{"query":"test", "file_uuid":"53e3a229bf68878b7a799e811e097f9c"}' \
  "http://localhost:3002/api/v1/search"
 ```
 **結果**: ✅ **200 OK**
@@ -152,7 +152,7 @@ curl -X POST -H "X-API-Key: muser_test_001" -H "Content-Type: application/json"
 #### `POST /api/v1/search/visual/class`
 ```bash
 curl -X POST -H "X-API-Key: muser_test_001" -H "Content-Type: application/json" \
-  -d '{"uuid":"53e3a229bf68878b7a799e811e097f9c", "object_class":"person"}' \
+  -d '{"file_uuid":"53e3a229bf68878b7a799e811e097f9c", "object_class":"person"}' \
  "http://localhost:3002/api/v1/search/visual/class"
 ```
 **結果**: ✅ **200 OK**