feat: Implement Event File Hosted Data Fix and API Guide Update

Address critical data visibility issues for Event Files and enhance frontend documentation.

This commit resolves the persistent problem where top-level hosted file convenience fields
(e.g., , , ) were
returning as  in V3 Event File API responses, even when .

Key changes include:
- Refactored  Pydantic model:
    - Removed redundant  definitions from top-level hosted file convenience fields,
      allowing direct mapping from SQL view columns.
    - Simplified  to focus solely on conditionally loading the nested
       object, as top-level fields are now populated directly by Pydantic
      from the  view.
    - Added comprehensive comments to clarify data flow, Pydantic's behavior, and the
      expected origin of these convenience fields from SQL views.
- Updated :
    - Introduced a new section detailing how to retrieve Event File data, including the
      use of  to get both top-level convenience fields and a nested
       object.
    - Clarified all ID references as random string IDs.
    - Renumbered the troubleshooting section.
- Copied updated guide to .
- Continued ID Vision compliance audit, ensuring consistent handling of random string IDs
  across various core and event models (Account, Address, Contact, DataStore, Event Badge Template).
- Consolidated ID Vision E2E tests and updated related documentation.
- Minor updates to  and
  to support Event File data retrieval with .

app/models/address_models.py

@@ -14,15 +14,21 @@ class Address_Base(BaseModel):
     log.setLevel(logging.INFO) # DEBUG, INFO, WARNING, ERROR, EXCEPTION, CRITICAL
     log.debug(locals())
 
-    # --- Standardized Vision IDs (Strings) ---
+    # Standardized Vision IDs (Strings) ---
     id: Optional[str] = Field(None, **base_fields['address_id_random'])
     address_id: Optional[str] = Field(None, **base_fields['address_id_random'])
     account_id: Optional[str] = Field(None, **base_fields['account_id_random'])
     contact_id: Optional[str] = Field(None, **base_fields['contact_id_random'])
 
+    # Standardized Polymorphic Target
     for_type: Optional[str]
-    for_id_random: Optional[str]
-    for_id: Optional[int] = Field(None, exclude=True)
+    for_id: Optional[str] = Field(**base_fields['obj_id_random'])
+
+    # --- Standardized Legacy / Internal IDs (Excluded) ---
+    id_random: Optional[str] = Field(None, alias='address_id_random', exclude=True)
+    account_id_random: Optional[str] = Field(None, exclude=True)
+    contact_id_random: Optional[str] = Field(None, exclude=True)
+    for_id_random: Optional[str] = Field(None, exclude=True)
 
     #organization: Optional[Organization_Base] = Organization_Base()
 
@@ -42,7 +48,7 @@ class Address_Base(BaseModel):
     country_name: Optional[str] # From country lookup table
     country: Optional[str] # Avoid using
 
-    lu_time_zone_id: Optional[str]
+    lu_time_zone_id: Optional[str] = Field(None, exclude=True)
     timezone: Optional[str]
 
     latitude: Optional[str]
@@ -70,20 +76,47 @@ class Address_Base(BaseModel):
         Vision Transformer:
         Map DB keys to clean API keys and strip internal integers.
         """
-        # 1. Map Random Strings to Clean Names
+        # 1. Map Primary Object ID
         if rid := values.get('id_random') or values.get('address_id_random'):
             values['id'] = rid
             values['address_id'] = rid
             
-        if a_rid := values.get('account_id_random'):
-            values['account_id'] = a_rid
-        if c_rid := values.get('contact_id_random'):
-            values['contact_id'] = c_rid
-            
-        # 2. Prevent "Collision Population"
-        for k in ['id', 'account_id', 'contact_id']:
-            if k in values and not isinstance(values[k], str):
-                del values[k]
+        # 2. Map & Resolve Relational IDs
+        id_map = [
+            ('account_id', 'account'),
+            ('contact_id', 'contact'),
+        ]
+
+        for field, table in id_map:
+            r_val = values.get(f'{field}_random')
+            if r_val and isinstance(r_val, str):
+                values[field] = r_val
+            elif values.get(field) and isinstance(values[field], (int, str)):
+                is_random = isinstance(values[field], str) and len(values[field]) >= 11
+                if not is_random:
+                    resolved_rid = get_id_random(values[field], table)
+                    if resolved_rid:
+                        values[field] = resolved_rid
+                        values[f'{field}_random'] = resolved_rid
+
+        # 3. Handle Polymorphic for_id
+        if f_rid := values.get('for_id_random'):
+            values['for_id'] = f_rid
+        elif values.get('for_id') and values.get('for_type'):
+            # Resolve based on the for_type
+            is_random = isinstance(values['for_id'], str) and len(values['for_id']) >= 11
+            if not is_random:
+                resolved_for_rid = get_id_random(values['for_id'], values['for_type'])
+                if resolved_for_rid:
+                    values['for_id'] = resolved_for_rid
+                    values['for_id_random'] = resolved_for_rid
+
+        # 4. Final Vision Enforcement
+        for k in ['id', 'address_id', 'account_id', 'contact_id', 'for_id']:
+            val = values.get(k)
+            if val is not None:
+                if not isinstance(val, str) or len(val) < 11:
+                    values[k] = None
                 
         return values