diff --git a/README.md b/README.md index 8a36cd2..5eba357 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Ham Radio Award Portal +# Quickawards by DJ7NT -A web application for amateur radio operators to track QSOs (contacts) and award progress using Logbook of the World (LoTW) data. +A web application for amateur radio operators to track QSOs (contacts) and award progress using Logbook of the World (LoTW) and DARC Community Logbook (DCL) data. ## Features @@ -10,12 +10,20 @@ A web application for amateur radio operators to track QSOs (contacts) and award - Incremental sync using last confirmation date - Wavelog-compatible download logic with proper validation - One sync job per user enforcement + - Confirmation date and service type displayed in QSO table +- **DCL Preparation**: Infrastructure ready for DARC Community Logbook (DCL) + - Database schema includes DCL confirmation fields (dcl_qsl_rdate, dcl_qsl_rstatus) + - DOK (DARC Ortsverband Kennung) fields: my_darc_dok, darc_dok + - Settings page includes DCL API key input (for future use) + - Note: DCL download API is not yet available - infrastructure is prepared for when they add it - **QSO Log**: View and manage confirmed QSOs - Pagination support for large QSO collections - - Filter by band, mode, and confirmation status + - Filter by band and mode - Statistics dashboard (total QSOs, confirmed, DXCC entities, bands) - Delete all QSOs with confirmation -- **Settings**: Configure LoTW credentials securely + - Displays DOK fields for German award tracking + - Multi-service confirmation display (LoTW, DCL) +- **Settings**: Configure LoTW and DCL credentials securely ## Tech Stack @@ -43,11 +51,13 @@ award/ │ │ │ └── logger.js # Pino logging configuration │ │ ├── db/ │ │ │ └── schema/ -│ │ │ └── index.js # Database schema (users, qsos, sync_jobs) +│ │ │ └── index.js # Database schema (users, qsos, sync_jobs, awards) │ │ ├── services/ │ │ │ ├── auth.service.js # User authentication │ │ │ ├── lotw.service.js # LoTW sync & QSO management -│ │ │ └── job-queue.service.js # Background job queue +│ │ │ ├── dcl.service.js # DCL sync stub (for future API) +│ │ │ ├── job-queue.service.js # Background job queue +│ │ │ └── awards.service.js # Award progress tracking │ │ └── index.js # API routes and server │ └── frontend/ │ ├── src/ @@ -60,8 +70,9 @@ award/ │ │ ├── auth/ │ │ │ ├── login/+page.svelte # Login page │ │ │ └── register/+page.svelte # Registration page -│ │ ├── qsos/+page.svelte # QSO log with pagination -│ │ └── settings/+page.svelte # Settings & LoTW credentials +│ │ ├── qsos/+page.svelte # QSO log with DOK fields and confirmations +│ │ ├── awards/+page.svelte # Awards progress tracking +│ │ └── settings/+page.svelte # Settings (LoTW & DCL credentials) │ └── package.json ├── award.db # SQLite database (auto-created) ├── drizzle.config.js # Drizzle ORM configuration @@ -146,10 +157,16 @@ The application will be available at: - `POST /api/auth/login` - Login user - `GET /api/auth/me` - Get current user profile - `PUT /api/auth/lotw-credentials` - Update LoTW credentials +- `PUT /api/auth/dcl-credentials` - Update DCL API key (for future use) ### LoTW Sync - `POST /api/lotw/sync` - Queue a LoTW sync job (returns job ID) +### Awards +- `GET /api/awards` - Get all available awards +- `GET /api/awards/:awardId/progress` - Get award progress +- `GET /api/awards/:awardId/entities` - Get entity breakdown + ### Jobs - `GET /api/jobs/:jobId` - Get job status - `GET /api/jobs/active` - Get user's active job @@ -157,7 +174,7 @@ The application will be available at: ### QSOs - `GET /api/qsos` - Get user's QSOs with pagination - - Query parameters: `?page=1&limit=100&band=20m&mode=CW&confirmed=true` + - Query parameters: `?page=1&limit=100&band=20m&mode=CW` - `GET /api/qsos/stats` - Get QSO statistics - `DELETE /api/qsos/all` - Delete all QSOs (requires confirmation) @@ -175,7 +192,9 @@ CREATE TABLE users ( callsign TEXT NOT NULL, lotwUsername TEXT, lotwPassword TEXT, - createdAt TEXT NOT NULL + dclApiKey TEXT, -- DCL API key (for future use) + createdAt TEXT NOT NULL, + updatedAt TEXT NOT NULL ); ``` @@ -190,9 +209,24 @@ CREATE TABLE qsos ( band TEXT, mode TEXT, entity TEXT, + entityId INTEGER, grid TEXT, - lotwQslRstatus TEXT, - lotwQslRdate TEXT, + gridSource TEXT, + continent TEXT, + cqZone INTEGER, + ituZone INTEGER, + state TEXT, + county TEXT, + satName TEXT, + satMode TEXT, + myDarcDok TEXT, -- User's DOK (e.g., 'F03', 'P30') + darcDok TEXT, -- QSO partner's DOK + lotwQslRstatus TEXT, -- LoTW confirmation status ('Y', 'N', '?') + lotwQslRdate TEXT, -- LoTW confirmation date (ADIF format: YYYYMMDD) + dclQslRstatus TEXT, -- DCL confirmation status ('Y', 'N', '?') + dclQslRdate TEXT, -- DCL confirmation date (ADIF format: YYYYMMDD) + lotwSyncedAt TEXT, + createdAt TEXT NOT NULL, FOREIGN KEY (userId) REFERENCES users(id) ); ``` @@ -670,6 +704,44 @@ Following Wavelog's proven approach: 4. **Timeout handling**: 30-second connection timeout 5. **Query parameters**: Matches Wavelog's LoTW download +### DOK Fields (DARC Ortsverband Kennung) + +The QSO table includes DOK fields for German amateur radio awards: +- **myDarcDok**: User's own DOK (e.g., 'F03', 'P30', 'G13') +- **darcDok**: QSO partner's DOK + +DOKs are local club identifiers used by DARC (German amateur radio club) for award tracking. +These fields are populated when syncing from LoTW if the ADIF data contains MY_DARC_DOK and DARC_DOK tags. + +### DCL Preparation + +The application is prepared for future DARC Community Logbook (DCL) integration: + +**Infrastructure in place:** +- Database schema includes DCL confirmation fields (`dcl_qsl_rdate`, `dcl_qsl_rstatus`) +- Backend service stub (`src/backend/services/dcl.service.js`) with TODO comments for implementation +- Settings page includes DCL API key input +- QSO table displays DCL confirmations alongside LoTW + +**Current status:** +- DCL does not provide a public download API (as of 2025) +- Manual ADIF export is available at https://dcl.darc.de/dml/export_adif_form.php +- When DCL adds an API endpoint, the existing infrastructure can be easily activated + +**Future implementation steps (when DCL API is available):** +1. Implement `fetchQSOsFromDCL()` in `dcl.service.js` +2. Add ADIF parser for DCL format +3. Implement `syncQSOs()` to store DCL confirmations +4. Add sync endpoint similar to LoTW + +### Confirmation Display + +The QSO table shows confirmations from multiple services: +- Each service is listed with its name (LoTW, DCL) and confirmation date +- Multiple confirmations per QSO are supported +- Empty state shows "-" when no confirmations exist +- Service types are color-coded and formatted for easy scanning + ### Pagination - Default page size: 100 QSOs per page diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md index 3843a4a..82f4ee2 100644 --- a/docs/DOCUMENTATION.md +++ b/docs/DOCUMENTATION.md @@ -1,4 +1,4 @@ -# Ham Radio Award Portal - Documentation +# Quickawards by DJ7NT - Documentation ## Table of Contents @@ -13,7 +13,7 @@ ### Overview -The Ham Radio Award Portal is a full-stack web application designed to help amateur radio operators track their award progress by syncing QSOs (contacts) from ARRL's Logbook of the World (LoTW). +Quickawards by DJ7NT is a full-stack web application designed to help amateur radio operators track their award progress by syncing QSOs (contacts) from ARRL's Logbook of the World (LoTW) and preparing for future integration with DARC Community Logbook (DCL). ### Technology Stack @@ -85,9 +85,13 @@ Main entry point that configures and starts the ElysiaJS server. - `POST /api/auth/login` - User login - `GET /api/auth/me` - Get current user - `PUT /api/auth/lotw-credentials` - Update LoTW credentials +- `PUT /api/auth/dcl-credentials` - Update DCL API key (for future use) - `POST /api/lotw/sync` - Sync QSOs from LoTW - `GET /api/qsos` - Get QSOs with filtering - `GET /api/qsos/stats` - Get QSO statistics +- `GET /api/awards` - Get all awards +- `GET /api/awards/:awardId/progress` - Get award progress +- `GET /api/awards/:awardId/entities` - Get entity breakdown #### 2. Database Schema (`src/backend/db/schema/index.js`) @@ -95,8 +99,9 @@ Defines the database structure using Drizzle ORM schema builder. **Tables:** -- **users**: User accounts, authentication credentials, LoTW credentials -- **qsos**: Amateur radio contacts in ADIF format with LoTW confirmation data +- **users**: User accounts, authentication credentials, LoTW credentials, DCL API key +- **qsos**: Amateur radio contacts in ADIF format with LoTW and DCL confirmation data, plus DOK fields +- **sync_jobs**: Background job queue for async operations - **awards**: Award definitions with JSON rule configurations - **award_progress**: Cached award progress for each user @@ -107,6 +112,7 @@ Defines the database structure using Drizzle ORM schema builder. - Password hashing with bcrypt - JWT token generation and validation - User profile management +- LoTW and DCL credentials management **LoTW Service** (`src/backend/services/lotw.service.js`) - Synchronization with ARRL's Logbook of the World @@ -116,6 +122,23 @@ Defines the database structure using Drizzle ORM schema builder. - Band/mode normalization - Error handling and retry logic +**DCL Service** (`src/backend/services/dcl.service.js`) +- Stub service for future DARC Community Logbook integration +- Prepared for when DCL provides a download API +- Includes TODO comments for implementation steps + +**Awards Service** (`src/backend/services/awards.service.js`) +- Award progress calculation +- Entity breakdown by band/mode +- Confirmation status tracking (LoTW, DCL) +- DXCC, WAS, VUCC award support + +**Job Queue Service** (`src/backend/services/job-queue.service.js`) +- Background job management +- Job status tracking +- One active job per user enforcement +- Progress reporting + #### 4. Configuration (`src/backend/config/`) - **database.js**: Database connection and client initialization @@ -126,11 +149,12 @@ Defines the database structure using Drizzle ORM schema builder. #### 1. Pages (SvelteKit Routes) -- **`/`**: Dashboard with welcome message +- **`/`**: Dashboard with welcome message and quick action cards - **`/auth/login`**: User login form - **`/auth/register`**: User registration form -- **`/qsos`**: QSO logbook with filtering and LoTW sync -- **`/settings`**: LoTW credentials management +- **`/qsos`**: QSO logbook with filtering, DOK fields, and multi-service confirmation display +- **`/awards`**: Awards progress tracking (DXCC, WAS, VUCC) +- **`/settings`**: LoTW and DCL credentials management #### 2. Layout (`+layout.svelte`)