Migrate Journals and Badges modules to Aether API V3 CRUD endpoints and fix Svelte 5 / Dexie integration issues.

GEMINI.md

@@ -203,13 +203,22 @@ The activity logging functionality is now working as expected. While the origina
     *   **Root Cause:** The `data` prop, passed from SvelteKit's `load` function, is not reliably scoped or available inside asynchronous callbacks fired by external, third-party libraries.
     *   **Solution:** The robust solution is to use SvelteKit's dedicated `$page` store. By importing `import { page } from '$app/stores';` and using `$page.url`, we can reliably access the current URL information from anywhere in the component, including async callbacks.
 
-### Jitsi Break-out Link (2025-12-16)
+### Session Learnings (2026-01-02)
 
-**Context:** Added a feature to provide a "break out" link for Jitsi meetings, allowing users to open the current meeting outside of the Novi iframe context.
+**Context:** Migrated the Journals and Events - Badges modules to the new Aether API V3 CRUD endpoints and resolved several Svelte 5 / Dexie integration issues.
 
-**Implementation:**
-*   **Component:** The `MyClipboard` component (`$lib/app_components/e_app_clipboard.svelte`) was imported into `src/routes/idaa/(idaa)/video_conferences/+page.svelte`.
-*   **Placement:** The `MyClipboard` component was added to the Jitsi tools section within the `+page.svelte` file.
-*   **Functionality:** The component is configured to copy the full URL of the current page (`$page.url.href`) to the clipboard, encoded for safety.
-*   **Styling:** Tailwind CSS classes (`mt-2 px-2 py-1 bg-indigo-400 text-white rounded hover:bg-indigo-500`) were applied to the button for visual consistency with other elements in the tools panel.
-*   **Layout:** The container `div` for the buttons was updated with `flex-wrap` to ensure proper layout if multiple buttons are present.
+**Key Accomplishments:**
+- **Aether API V3 Frontend Implementation:** Created robust TypeScript wrappers for V3: `get_ae_obj_v3`, `get_ae_obj_li_v3`, `get_nested_obj_li_v3`, and `search_ae_obj_v3`. These support the new nested URL structure, hybrid filtering (query params + POST body), and global keyword search (`q` property).
+- **Journals Module Migration:** Fully migrated `ae_journals` to V3.
+    - **Bug Fix (Missing Parent ID):** Discovered that V3 nested routes often omit the parent ID in response objects. Implemented automatic parent ID injection in the data processor (`process_ae_obj__journal_entry_props`) to maintain local Dexie relationships.
+    - **Bug Fix (Illegal Effects):** Fixed a runtime crash caused by using `$effect` inside `onclick` event handlers. Moved logic to direct function calls.
+- **Events - Badges Module Migration:** Migrated `ae_events__event_badge` to V3 search and list endpoints.
+    - **Search Optimization:** Refined the `search_query` structure to utilize the backend's new `q` property for global text search and standard `and` filters for specific fields like `badge_type_code` and `print_count`.
+    - **Operator Refinement:** Verified that the backend V3 currently prefers the `like` operator with wildcards over `ilike` or `contains` for certain textual fields.
+- **Backend Recommendations:** Documented actionable feedback for the FastAPI backend in `documentation/Aether_API_CRUD_V3_beta_recommendations.md`, focusing on "view" selection and hybrid search efficiency.
+
+**Key Learnings:**
+- **Svelte 5 & Dexie LiveQuery:** Remember that while Svelte 5 runes (`$state`, `$derived`) don't use the `$` prefix, **Dexie `liveQuery` results are observables** and still require the `$` prefix (e.g., `$lq__obj`) to access their reactive value in the template and script.
+- **API V3 Implicit Context:** When using nested API routes (e.g., `/v3/crud/parent/{id}/child/`), the child objects returned may not contain the `parent_id`. The frontend must proactively inject this ID during processing if it's required for local database indexing or filtering.
+- **Search Logic Construction:** When building complex V3 `search_query` objects, avoid including empty `and` or `or` arrays, as some backend parsers may strictly validate their presence or content. Only attach these properties if they contain at least one filter.
+- **Backend Error Propagation:** Always check FastAPI logs when a V3 search returns 0 unexpected results; it often indicates an "Unsupported search operator" or a Pydantic validation error in the hybrid parameter parsing.

documentation/V3_FRONTEND_API_GUIDE.md

@@ -73,9 +73,56 @@ Use the `q` property in your search body for a general keyword search across ind
 }
 ```
 
+### D. Supported Search Operators
+The `op` property in a `SearchFilter` supports the following values:
+
+| Operator | SQL equivalent | Description |
+| --- | --- | --- |
+| `eq` | `=` | Equal to |
+| `ne` | `!=` | Not equal to |
+| `gt` | `>` | Greater than |
+| `gte` | `>=` | Greater than or equal to |
+| `lt` | `<` | Less than |
+| `lte` | `<=` | Less than or equal to |
+| `in` | `IN (...)` | Matches any value in a provided list |
+| `is_null` | `IS NULL` | Field is null (ignores `value`) |
+| `is_not_null` | `IS NOT NULL` | Field is not null (ignores `value`) |
+| `like` | `LIKE` | Standard SQL LIKE (requires manual `%` in `value`) |
+| `contains` | `LIKE %val%` | Wraps value in `%` automatically |
+| `startswith` | `LIKE val%` | Appends `%` to value automatically |
+| `endswith` | `LIKE %val` | Prepends `%` to value automatically |
+
 ---
 
-## 3. Best Practices for V3
+## 4. Authentication in V3
+
+V3 supports multiple authentication methods. The backend resolves these automatically.
+
+### A. Standard Requests (Header)
+For most API calls, use the standard Bearer token in the `Authorization` header.
+
+```ts
+// Example: Setting the JWT in headers
+headers: {
+    "Authorization": `Bearer ${user_jwt_token}`
+}
+```
+
+### B. Secure File Downloads (URL Parameter)
+**Crucial for `hosted_file` and `event_file`**: To allow browsers to download files without complex header modifications, you can pass the JWT directly in the URL.
+
+```ts
+// Example: Creating a secure download link
+// GET /v3/crud/hosted_file/{id}/?jwt={token}
+const downloadUrl = `${BASE_URL}/hosted_file/${fileId}/?jwt=${jwtToken}`;
+```
+
+### C. Legacy Fallback (X-Account-ID)
+For development and backward compatibility, the `X-Account-ID` header is still supported but should be phased out in favor of JWT.
+
+---
+
+## 5. Best Practices for V3
 
 1.  **Use `view` for Rich Data**: Instead of manually joining data in separate calls, use `?view=enriched` or `?view=detail` if defined in the backend.
 2.  **Hybrid Search**: Use query parameters for simple toggles (enabled/hidden) and the POST body for complex logic.