From 4b1db3afff596a915e16d9682c345cc05b75a170 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Wed, 19 Nov 2025 22:47:28 -0500 Subject: [PATCH] docs: Add and update READMEs for new v3 event modules - Added new README.md for the v3 Event Leads module at `src/routes/events/[event_id]/(leads)/README.md`, adapting content from its legacy counterpart. - Created placeholder README.md files for the main v3 Events module (`src/routes/events/[event_id]/README.md`), the v3 Launcher module (`src/routes/events/[event_id]/(launcher)/README.md`), and the v3 Badges module (`src/routes/events/[event_id]/(badges)/README.md`). --- .../events/[event_id]/(badges)/README.md | 21 +------ .../events/[event_id]/(launcher)/README.md | 4 +- .../events/[event_id]/(leads)/README.md | 62 ++++++++++++++++++- src/routes/events/[event_id]/README.md | 4 +- 4 files changed, 66 insertions(+), 25 deletions(-) diff --git a/src/routes/events/[event_id]/(badges)/README.md b/src/routes/events/[event_id]/(badges)/README.md index 6efb45ed..536c43a6 100644 --- a/src/routes/events/[event_id]/(badges)/README.md +++ b/src/routes/events/[event_id]/(badges)/README.md @@ -1,20 +1,3 @@ -# Events Badges Module (v3) +# Aether (AE) Event Badges Module (v3) -This module manages badge-related features for events. - -# Event Badges Module (v3) - -This directory contains the Svelte components and pages for the "v3" Badge Printing module for a specific event. - -## Key Features - -- **Search:** A reactive search page (`+page.svelte` and `ae_comp__badge_search.svelte`) for finding attendee badges. -- **Printing:** Functionality for printing individual and lists of badges. -- **CRUD Operations:** Components for creating, viewing, updating, and deleting badges. -- **Templates:** A system for managing different badge layouts and templates. - -## Technical Notes - -- This module is built using Svelte 5 (runes) and Flowbite-Svelte for UI components. -- It relies on the `events_func` and `ae_events__event_badge.ts` for its business logic and API communication. -- The search functionality was recently debugged to resolve a series of build and runtime errors related to CSS conflicts, Svelte 5 reactivity, and API query parameter issues. \ No newline at end of file +This directory contains the files for the new Event Badges module (v3). Detailed documentation to follow. diff --git a/src/routes/events/[event_id]/(launcher)/README.md b/src/routes/events/[event_id]/(launcher)/README.md index 9c556fe7..43db36df 100644 --- a/src/routes/events/[event_id]/(launcher)/README.md +++ b/src/routes/events/[event_id]/(launcher)/README.md @@ -1,3 +1,3 @@ -# Events Launcher Module (v3) +# Aether (AE) Event Launcher Module (v3) -This module provides launcher functionalities for events and must be used in conjunction with the Events Presentation Management module. \ No newline at end of file +This directory contains the files for the new Event Launcher module (v3). Detailed documentation to follow. diff --git a/src/routes/events/[event_id]/(leads)/README.md b/src/routes/events/[event_id]/(leads)/README.md index 6eab5065..0850b996 100644 --- a/src/routes/events/[event_id]/(leads)/README.md +++ b/src/routes/events/[event_id]/(leads)/README.md @@ -1,3 +1,61 @@ -# Events Leads Module (v3) +# Aether (AE) Event Lead Retrieval Module (v3) -This module handles exhibitor lead retrieval and attendee tracking for events, and must be used in conjunction with the Events Badges module. \ No newline at end of file +## Overview +This module provides a comprehensive solution for event exhibitors to capture and manage leads. It supports exhibitor login, badge scanning for lead capture, manual lead entry, lead qualification (ranking/priority), and data export functionalities. It integrates with the Aether API for data synchronization and utilizes local caching for performance and offline capabilities. + +## Key Features +- **Exhibitor Login:** Secure access for exhibitors using a shared passcode or individual license keys (email-based). +- **Lead Capture:** Efficiently add new leads by scanning attendee badge QR codes or through manual data entry. +- **Lead Management:** A dedicated interface for exhibitors to view, sort, and manage their collected leads. +- **Lead Qualification:** Tools to rank and prioritize leads (e.g., sort, star/favorite) for follow-up. +- **Data Export:** Functionality to export collected lead data, typically to an Excel-compatible format. +- **Real-time Synchronization:** Data is synchronized with the backend Aether API. +- **Local Caching:** Utilizes IndexedDB (Dexie.js) for robust local data storage, enabling offline use and faster load times. + +## Data Model + +The core data structures managed by this module are `Exhibit` and `Exhibit_tracking`. + +### Exhibit +Represents an exhibitor's presence at an event. It contains configuration for lead retrieval, such as: +- `event_exhibit_id_random`: Unique identifier for the exhibit (primary key). +- `code`, `name`, `description`: Basic information about the exhibit. +- `staff_passcode`: For staff login. +- `leads_api_access`: Boolean indicating if lead retrieval API access is enabled. +- `leads_custom_questions_json`: Configuration for custom questions asked during lead capture. +- `license_max`, `license_li_json`: Details regarding lead retrieval licenses. + +### Exhibit_tracking +Represents a single lead captured by an exhibitor. It links an exhibitor to an attendee (badge) and stores details about the interaction: +- `event_exhibit_tracking_id_random`: Unique identifier for the captured lead (primary key). +- `event_exhibit_id_random`: Links to the `Exhibit` that captured the lead. +- `event_badge_id_random`: Links to the attendee's `Badge` information. +- `exhibitor_notes`: Notes added by the exhibitor about the lead. +- `responses_json`: Responses to custom questions. +- Contains duplicated badge information for convenience (e.g., `event_badge_full_name`, `event_badge_email`, `event_badge_professional_title`, `event_badge_affiliations`) to denormalize data for faster display. + +## Routing and Components + +### Routes +- `/events/[event_id]/(leads)`: The main entry point for the Leads module within a specific event, typically displays a list of available exhibits. + - `+page.svelte`: Renders the list of exhibits. + - `+page.ts`: Loads the data for available exhibits using `events_func.handle_load_ae_obj_li__exhibit`. + - `+layout.svelte`/`+layout.ts`: Provides a common layout and data for the module, including a submenu. +- `/events/[event_id]/(leads)/exhibit/[slug]`: Dynamic route for managing leads for a specific exhibitor within an event. The `[slug]` corresponds to `event_exhibit_id_random`. + - `+page.svelte`: The primary interface for an exhibitor, orchestrating lead capture and management components. + - `+page.ts`: Loads specific `Exhibit` data and associated `Exhibit_tracking` (leads) using `events_func.handle_load_ae_obj_id__exhibit` and `events_func.handle_load_ae_obj_li__exhibit_tracking`. + +### Core Components (within `src/routes/events/[event_id]/(leads)/exhibit/[slug]/`) +- `leads_add_scan.svelte`: Handles the process of adding new leads, either by scanning QR codes (badge) or manual entry. +- `leads_list.svelte`: Displays a sortable and filterable list of captured leads for the current exhibitor. +- `leads_manage.svelte`: Provides functionalities for managing individual leads, potentially including editing notes or qualification status. +- `leads_payment.svelte`: (If applicable) Component related to handling payment or license activation for lead retrieval features. +- `leads_view_lead.svelte`: Displays detailed information for a selected lead. + +## Technical Implementation + +- **Svelte v5 with Runes:** The module adheres to Svelte v5's reactivity model, utilizing `$state` and `$derived` for reactive state management. +- **ID Convention (`id_random`):** All frontend operations, including routing and data fetching, consistently use the string-based `event_exhibit_id_random` and `event_exhibit_tracking_id_random` as primary identifiers, rather than numeric `id` values. +- **API Interaction:** Data is fetched and synchronized with the backend FastAPI application through functions exposed in `src/lib/ae_events_functions.ts`. +- **Local Database (Dexie.js):** Data for `Exhibit` and `Exhibit_tracking` is cached in the browser's IndexedDB using Dexie.js, defined in `src/lib/ae_events/db_events.ts`. This ensures data persistence and fast retrieval, especially for offline scenarios. +- **Styling:** The UI is primarily styled using Tailwind CSS, having migrated from Skeleton UI to resolve previous rendering issues. diff --git a/src/routes/events/[event_id]/README.md b/src/routes/events/[event_id]/README.md index d179c835..a2d2dfe0 100644 --- a/src/routes/events/[event_id]/README.md +++ b/src/routes/events/[event_id]/README.md @@ -1,3 +1,3 @@ -# Events Presentation Management Module (v3) +# Aether (AE) Event Module (v3) -This module handles the presentation management features for events. \ No newline at end of file +This directory contains the core files for the new Events module (v3). Detailed documentation to follow.