From 20d8a6975dfb581f6423e3195d2dda32fc22a6dc Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Tue, 5 May 2026 13:31:19 -0400 Subject: [PATCH] Align journal docs with current model --- documentation/AE__Aether_API_objects.md | 2 ++ documentation/AE__Architecture.md | 15 ++++++++--- documentation/AE__Components.md | 14 +++++----- documentation/AE__Data_Structures.md | 26 +++++++++++++------ documentation/AE__Naming_Conventions.md | 6 ++--- documentation/AE__Permissions_and_Security.md | 6 +++++ .../MODULE__AE_Events_Exhibitor_Leads.md | 4 +-- ...JECT__AE_UI_Journals_module_update_2026.md | 18 +++++++++++-- 8 files changed, 66 insertions(+), 25 deletions(-) diff --git a/documentation/AE__Aether_API_objects.md b/documentation/AE__Aether_API_objects.md index 429f646e..c08a048d 100644 --- a/documentation/AE__Aether_API_objects.md +++ b/documentation/AE__Aether_API_objects.md @@ -1211,6 +1211,8 @@ This document provides a reference for the data structures of the core Aether AP **Source Model:** `Journal_Entry_Base` in `models/journal_entry_models.py` +**UI note:** The current Journals Entry Config modal treats `summary` as metadata, keeps `alert` and `alert_msg` as separate fields, and uses `priority` as a boolean flag while `sort` remains the numeric ordering field. + - `id_random`: `Optional[str]` - `id`: `Optional[int]` - `journal_id_random`: `Optional[str]` diff --git a/documentation/AE__Architecture.md b/documentation/AE__Architecture.md index 1546ec3a..2fad60e4 100644 --- a/documentation/AE__Architecture.md +++ b/documentation/AE__Architecture.md @@ -22,6 +22,15 @@ The Aether project is a Svelte and SvelteKit based application, utilizing Tailwi - **Markdown Parsing:** `marked` library - **State Management:** Svelte stores, potentially with `liveQuery` from Dexie for reactive IndexedDB interactions. +### 2.1. Journals as the Canonical Frontend Pattern + +The Journals module is the current frontend reference for configuration modal structure and journal-entry field semantics. When other docs disagree, Journals should be treated as the implementation target until proven otherwise. + +- Entry Config modal sections now follow `Metadata`, `Status & Security`, `Privacy Flags`, `Alerts & Messaging`, and `Admin`. +- `summary` is a first-class journal-entry field and belongs with metadata. +- `alert` and `alert_msg` are separate fields: the flag and its text payload. +- `priority` is a boolean flag in the object model, while `sort` remains the numeric ordering field. + ## 3. Module Structure The Aether project is organized into several modules, categorized as Core, Extended, and Custom. @@ -77,7 +86,7 @@ Used for more structured client-side data storage, often for caching and offline Standardized sorting orders are applied across various data lists. -- **Default/General:** `group > priority > sort > updated_on/created_on` +- **Default/General:** `group > priority (flag) > sort > updated_on/created_on` - **Specific (e.g., Events):** `type > start_date/time > code or name` ## 6. Object Properties and Fields @@ -95,8 +104,8 @@ These fields are expected to be present in most Aether objects. - `name`: Display name. - `enable`: Boolean for active/inactive status. - `hide`: Boolean for visibility. -- `priority`: Numeric value for ordering. -- `sort`: Numeric value for ordering. +- `priority`: Boolean/tinyint(1) ordering flag used by the object model. +- `sort`: Numeric value for ordering within a priority group. - `group`: Categorization string. - `notes`: General notes/comments. - `created_on`: Timestamp of creation. diff --git a/documentation/AE__Components.md b/documentation/AE__Components.md index 45114b9a..3a54a3fd 100644 --- a/documentation/AE__Components.md +++ b/documentation/AE__Components.md @@ -89,13 +89,13 @@ A standardized menu for interacting with objects. - **Actions:** `create`, `view`, `edit`, `update`, `hide`, `disable`, `delete`, `alert` (message), `archive` (not yet ready). - **Future Actions:** `copy`, `import`. - **Sort Options:** - - `[default]`: `group > priority > sort (ASC/DESC) > alert > name` - - `[sort_updated]`: `group > priority > sort (ASC/DESC) > alert > updated_on > created_on` - - `[priority_updated]`: `group > priority > updated_on (ASC/DESC) > created_on` - - `[priority_name]`: `group > priority > name (ASC/DESC) > sort > alert > updated_on > created_on` - - `[name]`: `priority > name (ASC/DESC) > sort > alert > updated_on > created_on` - - `[created_on]`: `priority > created_on (ASC/DESC)` - - `[updated_on]`: `priority > updated_on (ASC/DESC) > created_on` + - `[default]`: `group > priority (flag) > sort (ASC/DESC) > alert > name` + - `[sort_updated]`: `group > priority (flag) > sort (ASC/DESC) > alert > updated_on > created_on` + - `[priority_updated]`: `group > priority (flag) > updated_on (ASC/DESC) > created_on` + - `[priority_name]`: `group > priority (flag) > name (ASC/DESC) > sort > alert > updated_on > created_on` + - `[name]`: `priority (flag) > name (ASC/DESC) > sort > alert > updated_on > created_on` + - `[created_on]`: `priority (flag) > created_on (ASC/DESC)` + - `[updated_on]`: `priority (flag) > updated_on (ASC/DESC) > created_on` ## 2. Pop-ups diff --git a/documentation/AE__Data_Structures.md b/documentation/AE__Data_Structures.md index 58121fba..22c6bad5 100644 --- a/documentation/AE__Data_Structures.md +++ b/documentation/AE__Data_Structures.md @@ -8,21 +8,31 @@ This document outlines the key data structures and their properties used within These fields are expected to be present in most Aether objects, providing a consistent base structure. -- `id`: Primary key for an object (internal use, often a UUID). +- `id`: Primary key for an object (internal use, often *returned* by the API as a randomized string value in place of the actual DB autonum). - `id_random`: Randomly generated ID for an object (often used for external exposure or URL parameters). - `_id_random`: Specific random ID for an object (e.g., `person_id_random`). - `code`: Short, unique identifier. - `name`: Display name. - `enable`: Boolean for active/inactive status. - `hide`: Boolean for visibility. -- `priority`: Numeric value for ordering. -- `sort`: Numeric value for ordering. +- `priority`: Boolean/tinyint(1) ordering flag used by the object model. +- `sort`: Numeric value for ordering within a priority group. - `group`: Categorization string. - `notes`: General notes/comments. - `created_on`: Timestamp of creation. - `updated_on`: Timestamp of last update. -### 1.2. Special Use Fields +### 1.2. Journal Entry Fields + +Journal entries use the shared object fields plus a few content-specific fields that matter in the UI and config modal. + +- `summary`: Short entry summary shown in metadata and list contexts. +- `content`: Main body text for the entry. +- `alert`: Boolean flag used to highlight an entry as an alert. +- `alert_msg`: Supporting alert text shown when the alert flag is enabled. +- `private` / `public` / `personal` / `professional`: Visibility and audience flags used by the Entry Config modal. + +### 1.3. Special Use Fields Fields with specific purposes or conditional usage across different object types. @@ -32,7 +42,7 @@ Fields with specific purposes or conditional usage across different object types - `passcode`: A password or access code associated with an object. - `external_id`: An identifier from an external system. -### 1.3. Configuration and JSON Fields +### 1.4. Configuration and JSON Fields Fields designed to store structured data in JSON format. @@ -40,7 +50,7 @@ Fields designed to store structured data in JSON format. - `data_json`: General purpose data for an object, stored as a JSON string. - `linked_li_json`: A list of linked items, stored as a JSON string. -### 1.4. Special Generated Fields (Client-side) +### 1.5. Special Generated Fields (Client-side) These fields are generated on the client-side, primarily for facilitating UI logic, such as sorting. They are not typically stored in the backend database. @@ -48,7 +58,7 @@ These fields are generated on the client-side, primarily for facilitating UI log - `tmp_sort_2`: Temporary sort field 2. - `tmp_sort_3`: Temporary sort field 3. -### 1.5. Future Standard Fields +### 1.6. Future Standard Fields A list of potential future standard fields, often prefixed with `obj_`. These are conceptual and represent planned expansions to the data model. @@ -58,7 +68,7 @@ A list of potential future standard fields, often prefixed with `obj_`. These ar Standardized sorting orders are applied across various data lists to ensure consistent presentation. -- **Default/General Sorting:** `group > priority > sort > updated_on/created_on` +- **Default/General Sorting:** `group > priority (flag) > sort > updated_on/created_on` - **Specific Sorting (e.g., for time-based events):** `type > start_date/time > code or name` ## 3. Data Storage Mechanisms diff --git a/documentation/AE__Naming_Conventions.md b/documentation/AE__Naming_Conventions.md index 99262e75..9d9ce57c 100644 --- a/documentation/AE__Naming_Conventions.md +++ b/documentation/AE__Naming_Conventions.md @@ -47,8 +47,8 @@ - `description`: Longer text description. - `enable`: Boolean for active/inactive status. - `hide`: Boolean for visibility. - - `priority`: Numeric value for ordering. - - `sort`: Numeric value for ordering. + - `priority`: Boolean/tinyint(1) ordering flag used by the object model. + - `sort`: Numeric value for ordering within a priority group. - `group`: Categorization string. - `notes`: General notes/comments. - `created_on`: Timestamp of creation. @@ -76,7 +76,7 @@ ## 9. Data Sorting -- **Standard Order:** `group > priority > sort > updated_on/created_on` +- **Standard Order:** `group > priority (flag) > sort > updated_on/created_on` - **Specific Order:** `type > start_date/time > code or name` ## 10. Local Storage and IndexedDB Keys diff --git a/documentation/AE__Permissions_and_Security.md b/documentation/AE__Permissions_and_Security.md index 2a955ea0..b9141d34 100644 --- a/documentation/AE__Permissions_and_Security.md +++ b/documentation/AE__Permissions_and_Security.md @@ -187,6 +187,12 @@ This pattern lives in `ae_comp__badge_obj_li.svelte` — move to `ae_utils` if n ## Module-Specific Permission Patterns +### Journals — Entry Config Admin Actions +- Entry configuration admin controls are gated to `trusted_access` and above. +- `manager_access` and `administrator_access` see the Delete action, which performs a hard delete. +- `trusted_access` users see Remove instead, which follows disable semantics rather than a hard delete. +- The Admin section is the place for staff notes, enabled/default access state, and destructive entry actions; visibility/privacy flags remain separate. + ### Events — Badges | Scenario | Visibility | Print Action | Review Actions | diff --git a/documentation/MODULE__AE_Events_Exhibitor_Leads.md b/documentation/MODULE__AE_Events_Exhibitor_Leads.md index 0b1d1921..8e061cf4 100644 --- a/documentation/MODULE__AE_Events_Exhibitor_Leads.md +++ b/documentation/MODULE__AE_Events_Exhibitor_Leads.md @@ -23,7 +23,7 @@ Key capabilities: - **Badge scanning** — QR scan or text search (name, email, affiliations, badge ID) - **Lead list** — filterable/sortable, per-exhibitor or per-staff-member view -- **Lead detail** — custom question responses, notes (rich text), priority flag, hide/unhide +- **Lead detail** — custom question responses, notes (rich text), priority boolean flag, hide/unhide - **Export** — CSV/XLSX download of all leads for an exhibit - **License management** — assign staff accounts (email + passcode) per max license count - **Custom questions** — configurable per-exhibit follow-up questions (ratings, dropdowns, text) @@ -109,7 +109,7 @@ The main lead management view. Exhibit configuration and app settings. **Admin Tools** (manager_access only): -- Payment status toggle (`priority` field) +- Payment status toggle (`priority` boolean field) - Max licenses, small/large device counts **Booth Profile** (all signed-in users): diff --git a/documentation/PROJECT__AE_UI_Journals_module_update_2026.md b/documentation/PROJECT__AE_UI_Journals_module_update_2026.md index 957d9d8b..a34cdbf7 100644 --- a/documentation/PROJECT__AE_UI_Journals_module_update_2026.md +++ b/documentation/PROJECT__AE_UI_Journals_module_update_2026.md @@ -1,7 +1,7 @@ # Aether Journals UI Update (2026) -> **Status:** 🚧 Phase 4 Active (Security/Encryption Blockers remain; Style pass complete) -> **Last Updated:** 2026-03-06 +> **Status:** 🚧 Phase 4 Active (Security/Encryption Blockers remain; Journal Entry config rework in progress) +> **Last Updated:** 2026-05-05 > **Primary Agent:** Frontend SvelteKit Agent ## 1. Project Overview @@ -72,6 +72,10 @@ This document outlines the modernization of the Journals module UI in the Svelte - [x] Implement Auto-Save toggle and visual status indicators. - [x] Extract decryption workflow to non-reactive helper. - [x] **Standardize Configuration Modals:** Refactored Module, Journal, and Entry configuration into a unified tabbed UI. +- [x] **Journal Entry Config cleanup:** Summary now lives in Metadata; Alert lives in its own Alerts & Messaging section; Privacy Flags is visibility-only; Admin controls are split out and gated to trusted-access and above. +- [x] **Shared Flags widget:** `AE_Object_Flags` now shows visible button text and hover titles instead of icon-only controls. +- [x] **Modal sizing:** Entry config modal now expands to viewport height instead of stopping at a fixed 60vh body cap. +- [x] **Delete/Remove behavior:** Entry config Admin section now uses the real delete helper. Managers/admins see Delete (hard delete); trusted access sees Remove (disable semantics). - [x] **RESOLVED:** Decryption workflow stability (Fixed via dependency isolation). - [x] **Style Standardization (2026-03-06):** Full Skeleton v4 `preset-*` class pass across all 17 journal components. See style token table in Lessons Learned below. - [x] **Dark mode fixes:** Entry content hover, journal view section/description background and text colors. @@ -100,6 +104,7 @@ We have established a unified design language for configuration interfaces and a * **Close button:** Always use `dismissable={false}` on the `` and add an explicit `