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:
2026-01-17 10:31:06 +01:00
parent 47738c68a9
commit 287d1fe972
2 changed files with 115 additions and 19 deletions

View File

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