From 0091fe3ff6a07b301aa743f4ae0a480d9d769fc2 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Wed, 25 Mar 2026 17:43:15 -0400
Subject: [PATCH] Updates to the documentation about the id_random legacy.

---
 .../GUIDE__AE_API_V3_for_Frontend.md          | 24 +++++++++++++++++++
 src/lib/ae_archives/db_archives.ts            | 16 +++++--------
 2 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend.md b/documentation/GUIDE__AE_API_V3_for_Frontend.md
index d0fcbbc2..8bcec8c4 100644
--- a/documentation/GUIDE__AE_API_V3_for_Frontend.md
+++ b/documentation/GUIDE__AE_API_V3_for_Frontend.md
@@ -68,6 +68,30 @@ Modify data in the system.
     *   **Header:** `x-ae-ignore-extra-fields: true`
     *   **Behavior:** When set to `true`, the backend will automatically strip any fields from the payload that are not defined in the object's model before attempting to save to the database.
 
+### D. ID Fields in Responses (Vision ID Convention)
+
+> [!IMPORTANT]
+> **V3 responses always use random string IDs — never database integers.**
+
+After a successful `POST` create or any `GET`, the response contains:
+
+| Field | Type | Use |
+| :--- | :--- | :--- |
+| `{obj_type}_id` | `string` | **Primary public ID.** Use this for subsequent `PATCH` calls and UI routing. |
+| `{obj_type}_id_random` | `string` | Legacy alias. Same value as `{obj_type}_id`. Present for backward compat only. |
+
+**Example — create then immediately PATCH:**
+```ts
+const created = await postArchiveContent(archiveId, payload);
+const newId = created.data.archive_content_id; // random string e.g. "xK9mP3qRtL2"
+
+// Use it directly in the PATCH URL — no lookup needed
+await patchArchiveContent(newId, { name: 'Updated Name' });
+// PATCH /v3/crud/archive/{archive_id}/archive_content/{newId}
+```
+
+> **Note on `_id_random` suffix:** The `{obj_type}_id_random` field is a legacy artifact from the pre-Vision model. Once you confirm `{obj_type}_id` is a random string (length 11–22), you do not need `_id_random` as a fallback. New code should only read `{obj_type}_id`.
+
 ---
 
 ## 4. V3 Uniform Lookup System
diff --git a/src/lib/ae_archives/db_archives.ts b/src/lib/ae_archives/db_archives.ts
index d3189410..f83c7727 100644
--- a/src/lib/ae_archives/db_archives.ts
+++ b/src/lib/ae_archives/db_archives.ts
@@ -14,14 +14,14 @@ import type { key_val } from '$lib/stores/ae_stores';
  */
 export interface Archive {
     id: string;
-    // id_random: string;
+    // id_random: string; // NO LONGER USE "_random"
     archive_id: string;
-    // archive_id_random: string;
+    // archive_id_random: string; // NO LONGER USE "_random"
 
     code?: null | string;
 
     account_id: string;
-    // account_id_random: string;
+    // account_id_random: string; // NO LONGER USE "_random"
 
     // archive_type: string;
 
@@ -80,12 +80,12 @@ export interface Archive {
  */
 export interface Archive_Content {
     id: string;
-    // id_random: string;
+    // id_random: string; // NO LONGER USE "_random"
     archive_content_id: string;
-    // archive_content_id_random: string;
+    // archive_content_id_random: string; // NO LONGER USE "_random"
 
     archive_id: string;
-    // archive_id_random: string;
+    // archive_id_random: string; // NO LONGER USE "_random"
 
     archive_content_type: string;
 
@@ -169,10 +169,6 @@ export class MySubClassedDexie extends Dexie {
                 enable, hide, priority, sort, group, notes, created_on, updated_on, [group+priority+sort+updated_on]`
         });
 
-        // file_path,
-        // filename, file_extension,
-        // original_datetime, original_timezone, original_location, original_url, original_url_text,
-        // enable_for_public,
     }
 }