OSIT-AE-App-Svelte/documentation/PROJECT__Use_AE_API_V3_CRUD_upgrade.md

Project: CRUD V3 Final Migration

Status: 🟡 Surgical Cleanup (90% Complete — Events Module Fully Migrated) Last Updated: 2026-05-21 Goal: Eliminate all dependency on legacy API wrappers (create_ae_obj_crud, get_ae_obj_id_crud, etc.) and ensure 100% adoption of the V3 Standard (/v3/crud/...).

---

1. Executive Summary

While the Journals and Identity (User/Account) modules have been successfully migrated to the V3 architecture, a significant portion of the Events, Sponsorships, and IDAA modules still rely on legacy V1/V2 wrappers. This document serves as the master checklist to reach 100% V3 compliance.

Why this matters:

• Security: V3 enforces strict multi-tenant isolation via JWT.
• Maintenance: Legacy wrappers in api.ts contribute to technical debt and "God Object" anti-patterns.
• Performance: V3 offers optimized search and partial updates (PATCH) that legacy endpoints lack.

---

2. Migration Audit (Findings)

The following files have been identified as using legacy CRUD wrappers.

🔴 High Priority: Events Module

• src/lib/ae_events/ae_events__event_session.ts (Migrated 2026-01-30)
• src/lib/ae_events/ae_events__event_presenter.ts (Migrated 2026-01-30)
• src/lib/ae_events/ae_events__event_presentation.ts (Migrated 2026-01-30)
• src/lib/ae_events/ae_events__event_location.ts (Migrated 2026-01-30)
• src/lib/ae_events/ae_events__event_badge_template.ts (Migrated 2026-01-30)
• src/lib/ae_events/ae_events__event_device.ts (Migrated 2026-01-30)
• src/lib/ae_events/ae_events__exhibit.ts (Migrated 2026-01-28)
• src/lib/ae_events/ae_events__event_file.ts (Migrated 2026-01-30)

🟠 Medium Priority: Core & Sponsorships

Legacy patterns persisting in core logic and config modules.

• src/lib/ae_sponsorships/ae_sponsorships_functions.ts
• src/lib/ae_core/core__hosted_files.ts (Migrated 2026-01-20)
• src/lib/ae_core/core__site.ts (Migrated 2026-01-26)
• src/lib/ae_core/core__site_domain.ts (STILL USES get_ae_obj_id_crud for bootstrap)
• src/lib/ae_core/ae_core_functions.ts (STILL USES get_ae_obj_id_crud / update_ae_obj_id_crud)
• src/lib/ae_core/core__country_subdivisions.ts
• src/lib/ae_core/core__time_zones.ts
• src/lib/ae_core/core__countries.ts

🟡 Low Priority: UI Components & Routes

Specific UI components that make direct API calls instead of using store functions.

• src/lib/elements/element_data_store.svelte (Direct create_ae_obj_crud)
• src/lib/elements/element_data_store_v2.svelte
• src/routes/events/[event_id]/event_page_menu.svelte
• src/routes/events/[event_id]/(pres_mgmt)/session/ae_comp__event_session_alert.svelte (Migrated to update_ae_obj)
• src/routes/events/ae_comp__event_session_obj_li.svelte
• src/routes/idaa/(idaa)/recovery_meetings/ae_idaa_comp__event_obj_id_edit.svelte
• src/routes/events/[event_id]/(pres_mgmt)/presenter/[presenter_id]/ae_comp__event_presenter_form_agree.svelte (STILL USES update_ae_obj_id_crud)

---

3. Migration Procedure

For each file listed above, follow this standard refactoring pattern:

1. Imports:

   • Remove imports of create_ae_obj_crud, update_ae_obj_id_crud, etc.
   • Import V3 helpers: get_ae_obj, create_ae_obj, update_ae_obj, delete_ae_obj, search_ae_obj.

2. Pattern Replacement:

   • Get (Single):

     • Old: get_ae_obj_id_crud({ api_cfg, obj_type: 'event_session', obj_id: '...' })
     • New: get_ae_obj({ api_cfg, obj_type: 'event_session', obj_id: '...' })

   • Get (List):

     • Old: get_ae_obj_li_for_obj_id_crud_v2(...)
     • New: get_ae_obj_li(...) or search_ae_obj(...) if complex filtering is needed.

   • Update:

     • Old: update_ae_obj_id_crud({ ..., fields: { name: 'New Name' } })
     • New: update_ae_obj({ ..., data: { name: 'New Name' } })
     • Note: Ensure payload whitelisting is applied! V3 will 400 Error on unknown columns.

   • Create:

     • Old: create_ae_obj_crud({ ..., fields: { ... } })
     • New: create_ae_obj({ ..., data: { ... } })

3. Verification:

   • Verify the module still loads data (check Network tab for /v3/ requests).
   • Verify saving works (check for 400 Bad Request errors).

4. Standard Practices (V3)

A. Permissive Update Mode

To simplify frontend state management, V3 supports ignoring unknown fields in update payloads.

• Header: x-ae-ignore-extra-fields: true (Enabled by default in api_patch_object).
• Use Case: Allows syncing objects that contain read-only metadata (e.g. created_on, _lq_id) without manual scrubbing.

B. Structured Error Handling

V3 returns detailed error metadata in the meta.details object.

• Implementation: Core helpers automatically extract this metadata.
• FastAPI Fallback: Standard {"detail": "..."} responses are automatically wrapped into the meta.details format by the frontend helpers.

---

5. Known Pitfalls

A. The "Integer Trap" (Search Mapping)

Issue: The backend automatically maps certain fields (like account_id) from string IDs to internal integers. Symptom: Providing a string ID in a search body that the backend maps to an integer can result in Zero Results if the underlying view expects a string.

Final Solution (Body + Header Injection):

1. Body: Inject the raw field name (e.g. account_id) into the search_query.and array to bypass automatic backend mapping.
2. Headers: Pass headers: { 'x-account-id': ... } manually to provide context for Auth validation.
3. Isolation (IDAA): Due to specific bugs in the IDAA module, it has been temporarily isolated to a legacy V2 search function (qry_ae_obj_li__event_v2) using default_qry_str for text searching, while the main module continues to use the V3 implementation.

---

6. Final Cleanup

Once all checkboxes above are completed:

1. Remove legacy exports from src/lib/api/api.ts.
2. Delete src/lib/ae_api/api_get__crud_obj_li_v1.ts.
3. Delete src/lib/ae_api/api_get__crud_obj_li_v2.ts.
4. Delete src/lib/ae_api/api_get__crud_obj_id.ts (Legacy version).