diff --git a/GEMINI.md b/GEMINI.md index db0e155..69c1bf1 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -15,24 +15,26 @@ I am the **primary orchestrator and main helper** for the development of the **U - **V3 Implementation:** Modern parallel CRUD and Search endpoints under `/v3/crud`. - **Summary**: This project serves as the backend for the Aether system, providing core API functionalities. -### Key Technical Learnings (Cumulative) +### Key Technical Hack/Learnings (Cumulative) - **Circular Dependencies Fixed**: Successfully resolved the fragile startup dependency chain by isolating Auth models and using strictly deferred DB imports in a dedicated `dependencies_v3.py` module. - **Bootstrap Paradox Solved**: Implemented a guest-access exception for `site_domain` search, allowing the frontend to resolve site context without a JWT. - **V3 Searchable Fields**: Confirmed that `searchable_fields` are fully implemented in `app/object_definitions/` and utilized by `app/lib_sql_search.py` for dynamic query generation. -- **Environment Sync Clarification**: Critical understanding that the `/home/scott/OSIT_dev/` directory is **NOT** a synchronized directory across different machines (e.g., Workstation vs. Laptop). This means virtual environments and installed dependencies are environment-specific and do not propagate via Syncthing. This is crucial for debugging cross-machine environment issues. -- **Circular Import Sensitivity**: Importing `JSONResponse` from `fastapi` in `app/routers/api.py` triggers a circular dependency crash. It is safer to rely on FastAPI's default dict-to-JSON serialization or use `mk_resp` without explicit `JSONResponse` typing in that specific file. +- **ID Vision Mapping Stability**: Resolved a critical conflict in `app/lib_sql_search.py` where backend-injected integer filters (e.g., `account_id`) were being incorrectly mapped to `_random` string columns. Mapping now only occurs for non-integer values. +- **API Error Transparency**: Modified `sql_select` to return `False` on hard database errors (instead of empty results). Updated the V3 search endpoint to return a `500 Internal Server Error` in these cases, preventing "silent failures" where frontend developers would see `200 OK` with zero results during system errors. +- **NULL Logic in Filters**: Confirmed that explicit frontend filters like `hide: false` will FAIL to match `NULL` database values in standard SQL equality. It is more robust to rely on the API's built-in `hidden=not_hidden` URL parameter, which handles `(hide = false OR hide IS NULL)` automatically. -## Session Summary & Progress (Jan 16, 2026) +## Session Summary & Progress (Jan 21, 2026) -This session focused on infrastructure automation and resolving critical environment configuration issues. +This session focused on stabilizing the V3 search engine and enhancing the "ID Vision" developer experience. -* **Aether Field Manager (ae_field_manage.py):** - * Developed a "Vertical Slice" automation tool in `~/agents_sync/scripts/` to handle field additions across DB, SQL Views, Pydantic Models, and Search Registries. - * Implemented multi-layer safety: Timestamped backups, syntax pre-verification, and mandatory `--execute` flag. - * Verified "Dry Run" logic for both `person` and `site` objects. -* **Hosted File Path Bugfix:** - * Identified and resolved a "Bootstrap Paradox" in `app/lib_config_v3.py` where database-stored paths (for production) were overwriting local Docker container paths. - * Ensured `FILES_PATH` remains controlled by the container environment variables, restoring functionality to file downloads. +* **V3 Search Engine Enhancements:** + * **Comprehensive ID Vision:** Expanded `vision_fields` mapping to include almost all major Aether objects (Event, Journal, Order, Product, etc.), allowing clean names in frontend filters. + * **Error Handling Refactor:** Standardized SQL error bubbling to return `500` status codes with DB details instead of misleading `200` successes. + * **Status Filter Consistency:** Added `not_enabled` alias for the `enabled` status parameter to align with `not_hidden`. +* **Object Definitions:** + * Whitelisted clean ID names (e.g., `event_id`, `account_id`) in `searchable_fields` for Events, Badges, and Journals to support the new mapping logic. +* **Database Synchronization:** + * Verified and resolved `v_journal_entry` missing column errors after user updated the view to include `account_id`. ## Current To-Do List @@ -46,10 +48,6 @@ This session focused on infrastructure automation and resolving critical environ ### 3. Other Agent Tasks - [ ] **Review and process new messages from various agents.** (ID: 134908245) - In Progress (Internal gemini_cli task). -- [x] **[scott_wks] Perform Initial System Health Audit** (ID: 131939030) - Done. -- [x] **[API-V3] Implement Error Bubbling and Validation Endpoint** (ID: 163752448) - Done. -- [x] **[API] Modularize main.py and extract Core Registries** - Done Jan 15. -- [x] **[API] Stabilize Logging and Configuration Bootstrap** - Done Jan 15. ### Workflow & Collaboration @@ -71,4 +69,4 @@ This session focused on infrastructure automation and resolving critical environ * Inspect the live log stream for regressions: 1 "tail -n 20 ~/OSIT_dev/aether_container_env/logs/ae_api/aether_api.log" -6. Finalize: Once verified, commit the changes with a descriptive message and sync relevant documentation. \ No newline at end of file +6. Finalize: Once verified, commit the changes with a descriptive message and sync relevant documentation.