diff --git a/GEMINI.md b/GEMINI.md index e1563197..84761797 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -209,16 +209,16 @@ The activity logging functionality is now working as expected. While the origina **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. +- **Journals Module Migration:** Partially migrated `ae_journals` to V3 (List and Search). - **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. + - **Bug Fix (New Entry Button):** Fixed a runtime crash on the "New Entry" button in `+layout.svelte` by removing illegal `$effect` calls from the `onclick` handler and fixing incorrect `$derived` variable access. +- **Events - Badges Module Migration:** Partially migrated `ae_events__event_badge` to V3 (List and Search). - **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. + - **Filter Fixes:** Resolved issues with "print status" and "affiliations" filters by reverting to the standard `like` operator (as `ilike` and `contains` were unsupported by the backend) and ensuring `print_count` is included in the persistent schema. +- **Documentation & Planning:** Updated `TODO.md` with a comprehensive V3 integration roadmap and documented actionable feedback for the FastAPI backend. **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. +- **Backend Operator Support:** Always verify supported operators (`like`, `eq`, `gt`, etc.) in the backend FastAPI implementation. Using unsupported operators like `ilike` or `contains` will cause immediate backend `ValueError` crashes. diff --git a/TODO.md b/TODO.md index fdf6f5f6..e3f1e255 100644 --- a/TODO.md +++ b/TODO.md @@ -28,6 +28,27 @@ This is a list of tasks to be completed before the next event/show/conference. --- +## Aether API CRUD V3 Integration + +- [ ] **Core API Wrappers:** + - [x] Implement GET list and search wrappers (`get_ae_obj_li_v3`, `search_ae_obj_v3`). + - [ ] Implement Create (POST) wrappers (`create_ae_obj_v3`, `create_nested_obj_v3`). + - [ ] Implement Update (PATCH) wrappers (`update_ae_obj_v3`, `update_nested_obj_v3`). + - [ ] Implement Delete (DELETE) wrapper (`delete_ae_obj_v3`). + - [ ] Implement single object GET wrapper (`get_ae_obj_v3`). +- [ ] **Authentication & Security:** + - [ ] Standardize JWT usage in headers for all V3 calls. + - [ ] Update file download logic to support JWT in URL parameters. +- [ ] **Module Migration:** + - [x] **Journals:** Partially migrated (List and Search). + - [x] **Events - Badges:** Partially migrated (List and Search). + - [ ] Complete migration for Journals (Create, Update, Delete). + - [ ] Complete migration for Events - Badges (Create, Update, Delete). + - [ ] Migrate Core modules (Accounts, Sites, People). + - [ ] Migrate IDAA modules. + +--- + ## Codebase Standardization ### 1. Naming Conventions diff --git a/documentation/V3_FRONTEND_API_GUIDE.md b/documentation/V3_FRONTEND_API_GUIDE.md index c5719e4e..5bb0b855 100644 --- a/documentation/V3_FRONTEND_API_GUIDE.md +++ b/documentation/V3_FRONTEND_API_GUIDE.md @@ -94,6 +94,61 @@ The `op` property in a `SearchFilter` supports the following values: --- +## 3. Create, Update, & Delete (POST, PATCH, DELETE) + +V3 supports both top-level operations and nested parent/child operations. + +### A. Create (POST) +When creating objects, V3 strictly validates the incoming JSON against the `mdl_in` Pydantic model. + +```ts +// POST /v3/crud/{obj_type}/ +// POST /v3/crud/journal/ +export async function create_ae_obj_v3({ api_cfg, obj_type, data }) { + const endpoint = `/v3/crud/${obj_type}/`; + return await post_object({ api_cfg, endpoint, data }); +} + +// POST /v3/crud/{parent_obj_type}/{parent_obj_id}/{child_obj_type}/ +// POST /v3/crud/journal/EIAC-40-76-82/journal_entry/ +// Note: Parent ID is automatically injected into the child record. +export async function create_nested_obj_v3({ api_cfg, parent_type, parent_id, child_type, data }) { + const endpoint = `/v3/crud/${parent_type}/${parent_id}/${child_type}/`; + return await post_object({ api_cfg, endpoint, data }); +} +``` + +### B. Update (PATCH) +V3 uses `PATCH` for partial updates. Only the fields provided in the body will be modified in the database. + +```ts +// PATCH /v3/crud/{obj_type}/{obj_id} +export async function update_ae_obj_v3({ api_cfg, obj_type, obj_id, data }) { + const endpoint = `/v3/crud/${obj_type}/${obj_id}`; + return await patch_object({ api_cfg, endpoint, data }); +} + +// PATCH /v3/crud/{parent_type}/{parent_id}/{child_type}/{child_id} +// Verification: The backend ensures the child actually belongs to the parent before updating. +export async function update_nested_obj_v3({ api_cfg, parent_type, parent_id, child_type, child_id, data }) { + const endpoint = `/v3/crud/${parent_type}/${parent_id}/${child_type}/${child_id}`; + return await patch_object({ api_cfg, endpoint, data }); +} +``` + +### C. Delete (DELETE) +The `DELETE` method is used for removal. The backend may implement soft-delete (hide/disable) depending on the configuration. + +```ts +// DELETE /v3/crud/{obj_type}/{obj_id} +export async function delete_ae_obj_v3({ api_cfg, obj_type, obj_id }) { + const endpoint = `/v3/crud/${obj_type}/${obj_id}`; + return await delete_object({ api_cfg, endpoint }); +} +``` + +--- + ## 4. Authentication in V3 V3 supports multiple authentication methods. The backend resolves these automatically.