docs: update documentation for branding and DCL preparation
- Update application name to "Quickawards by DJ7NT" - Add DCL (DARC Community Logbook) preparation details - Document new DOK fields (my_darc_dok, darc_dok) for German awards - Update database schema documentation with DCL confirmation fields - Add DCL API endpoint to API documentation - Document multi-service confirmation display feature - Add awards system documentation - Update project structure with new services and routes Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
96
README.md
96
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
|
||||
|
||||
Reference in New Issue
Block a user