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/account_models.py

@@ -1,7 +1,7 @@
 import datetime, pytz
 
-from typing import Dict, List, Optional, Set, Union
-from pydantic import BaseModel, EmailStr, Field, Json, PrivateAttr, ValidationError, validator
+from typing import Dict, List, Optional, Set, Union, ClassVar
+from pydantic import BaseModel, EmailStr, Field, Json, PrivateAttr, ValidationError, validator, root_validator
 
 from app.db_sql import redis_lookup_id_random
 from app.lib_general import log, logging
@@ -22,16 +22,12 @@ class Account_Base(BaseModel):
     log.setLevel(logging.WARNING) # DEBUG, INFO, WARNING, ERROR, EXCEPTION, CRITICAL
     log.debug(locals())
 
-    id_random: Optional[str] = Field(
-        **base_fields['account_id_random'],
-        alias = 'account_id_random',
-        # default_factory = lambda:secrets.token_urlsafe(default_num_bytes),
-    )
-    id: Optional[int] = Field(
-        alias = 'account_id'
-    )
-    # account_id: Optional[int] = Field(
-    # )
+    # --- Standardized Vision IDs (Strings) ---
+    id: Optional[str] = Field(None, **base_fields['account_id_random'])
+    account_id: Optional[str] = Field(None, **base_fields['account_id_random'])
+
+    # --- Standardized Legacy / Internal IDs (Excluded) ---
+    id_random: Optional[str] = Field(None, alias='account_id_random', exclude=True)
 
     code: Optional[str]
     name: Optional[str]
@@ -77,28 +73,29 @@ class Account_Base(BaseModel):
 
     _processed_at: datetime.datetime = PrivateAttr(default_factory=datetime.datetime.now)
 
-    @validator('id', always=True)
-    def account_id_lookup(cls, v, values, **kwargs):
-        log.setLevel(logging.WARNING)
-        log.debug(locals())
-
-        if values['id_random']:
-            log.debug(values['id_random'])
-            return redis_lookup_id_random(record_id_random=values['id_random'], table_name='account')
-        return None
-
-    # @validator('account_id', always=True)
-    # def account_id_duplicate(cls, v, values, **kwargs):
-    #     log.setLevel(logging.DEBUG)
-    #     log.debug(locals())
-
-    #     if values['id']:
-    #         log.debug(values['id'])
-    #         return values['id']
-    #     return None
+    @root_validator(pre=True)
+    def map_v3_ids(cls, values):
+        """
+        Vision Transformer:
+        Map DB keys to clean API keys and strip internal integers.
+        """
+        # 1. Map Random Strings to Clean Names
+        if rid := values.get('id_random') or values.get('account_id_random'):
+            values['id'] = rid
+            values['account_id'] = rid
+            
+        # 2. Final Vision Enforcement: Strip internal integers from public fields
+        for k in ['id', 'account_id']:
+            val = values.get(k)
+            if val is not None:
+                # If it's not a valid random string ID
+                if not isinstance(val, str) or len(val) < 11:
+                    values[k] = None
+                
+        return values
 
     class Config:
         underscore_attrs_are_private = True
+        allow_population_by_field_name = False
         fields = base_fields
-        allow_population_by_field_name = True
 # ### END ### API Account Models ### Account_Base() ###