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

# Project: CRUD V3 Final Migration

> **Status:** Active / In Progress
> **Last Updated:** 2026-01-20
> **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
The entire `ae_events` library is heavily dependent on legacy `v2` list and `v1` CRUD wrappers.

- [ ] `src/lib/ae_events/ae_events__event_session.ts`
- [ ] `src/lib/ae_events/ae_events__event_presenter.ts`
- [ ] `src/lib/ae_events/ae_events__event_presentation.ts`
- [ ] `src/lib/ae_events/ae_events__event_location.ts`
- [ ] `src/lib/ae_events/ae_events__event_badge_template.ts`
- [ ] `src/lib/ae_events/ae_events__event_device.ts`
- [ ] `src/lib/ae_events/ae_events__exhibit.ts`
- [ ] `src/lib/ae_events/ae_events__event_file.ts`

### 🟠 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` (Uses `get_ae_obj_id_crud`)
- [ ] `src/lib/ae_core/core__site.ts` (Uses `get_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`
- [ ] `src/routes/events/ae_comp__event_session_obj_li.svelte`
- [ ] `src/routes/idaa/(idaa)/recovery_meetings/ae_idaa_comp__event_obj_id_edit.svelte`

---

## 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_v3`, `create_ae_obj_v3`, `update_ae_obj_v3`, `delete_ae_obj_v3`, `search_ae_obj_v3`.

2.  **Pattern Replacement:**

    *   **Get (Single):**
        *   *Old:* `get_ae_obj_id_crud({ api_cfg, obj_type: 'event_session', obj_id: '...' })`
        *   *New:* `get_ae_obj_v3({ 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_v3(...)` or `search_ae_obj_v3(...)` if complex filtering is needed.

    *   **Update:**
        *   *Old:* `update_ae_obj_id_crud({ ..., fields: { name: 'New Name' } })`
        *   *New:* `update_ae_obj_v3({ ..., 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_v3({ ..., 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_random`) 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).