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`).
This commit is contained in:
Scott Idem
2025-11-19 22:47:28 -05:00
parent d1021e2822
commit 4b1db3afff
4 changed files with 66 additions and 25 deletions

View File

@@ -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.
## 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.