From 20f1f4ac97281095b05689bbfce6e2e2f3deb28b Mon Sep 17 00:00:00 2001
From: Joerg <joerg@dj7nt.de>
Date: Tue, 20 Jan 2026 08:29:56 +0100
Subject: [PATCH] working-status

---
 CLAUDE.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2db7b69..6409581 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -272,9 +272,14 @@ The award system is JSON-driven and located in `award-definitions/` directory. E
 - `fetchQSOsFromDCL(dclApiKey, sinceDate)`: Fetch from DCL API
 - API Endpoint: `https://dings.dcl.darc.de/api/adiexport`
 - Request: POST with JSON body `{ key, limit: 50000, qsl_since, qso_since, cnf_only }`
+  - `cnf_only: null` - Fetch ALL QSOs (confirmed + unconfirmed)
+  - `cnf_only: true` - Fetch only confirmed QSOs (dcl_qsl_rcvd='Y')
+  - `qso_since: DATE` - QSOs since this date (YYYYMMDD format)
+  - `qsl_since: DATE` - QSL confirmations since this date (YYYYMMDD format)
 - `parseDCLJSONResponse(jsonResponse)`: Parse example/test payloads
 - `syncQSOs(userId, dclApiKey, sinceDate, jobId)`: Sync QSOs to database
 - `getLastDCLQSLDate(userId)`: Get last QSL date for incremental sync
+- `getLastDCLQSODate(userId)`: Get last QSO date for incremental sync
 - Debug logging (when `LOG_LEVEL=debug`) shows API params with redacted key (first/last 4 chars)
 - Fully implemented and functional
 - **Note**: DCL API is a custom prototype by DARC; contact DARC for API specification details
@@ -431,8 +436,13 @@ The DOK award type supports filters to create award variants. Examples:
   - Required for DLD award
   - German amateur radio specific
   - Request format: POST JSON `{ key, limit, qsl_since, qso_since, cnf_only }`
+    - `cnf_only: null` - Fetch all QSOs (confirmed + unconfirmed)
+    - `cnf_only: true` - Fetch only confirmed QSOs
+    - `qso_since` - QSOs since this date (YYYYMMDD)
+    - `qsl_since` - QSL confirmations since this date (YYYYMMDD)
   - Response format: JSON with ADIF string in `adif` field
-  - Supports incremental sync by `qsl_since` parameter (format: YYYYMMDD)
+  - Syncs ALL QSOs (both confirmed and unconfirmed)
+  - Unconfirmed QSOs stored but don't count toward awards
   - Updates QSOs only if confirmation data has changed
 
 ### ADIF Format
@@ -530,6 +540,60 @@ Both LoTW and DCL return data in ADIF (Amateur Data Interchange Format):
 
 **Important**: DCL sync only updates DOK/grid fields when DCL provides non-empty values. This prevents accidentally clearing DOK data that was manually entered or imported from other sources.
 
+### DCL Sync Strategy
+
+**Current Behavior**: DCL syncs ALL QSOs (confirmed + unconfirmed)
+
+The application syncs both confirmed and unconfirmed QSOs from DCL:
+- **Confirmed QSOs**: `dclQslRstatus = 'Y'` - Count toward awards
+- **Unconfirmed QSOs**: `dclQslRstatus = 'N'` - Stored but don't count toward awards
+
+**Purpose of syncing unconfirmed QSOs**:
+- Users can see who they've worked (via "Not Confirmed" filter)
+- Track QSOs awaiting confirmation
+- QSOs can get confirmed later and will be updated on next sync
+
+**Award Calculation**: Always uses confirmed QSOs only (e.g., `dclQslRstatus === 'Y'` for DLD award)
+
+### DCL Incremental Sync Strategy
+
+**Challenge**: Need to fetch both new QSOs AND confirmation updates to old QSOs
+
+**Example Scenario**:
+1. Full sync on 2026-01-20 → Last QSO date: 2026-01-20
+2. User works 3 new QSOs on 2026-01-25 (unconfirmed)
+3. Old QSO from 2026-01-10 gets confirmed on 2026-01-26
+4. Next sync needs both: new QSOs (2026-01-25) AND confirmation update (2026-01-10)
+
+**Solution**: Use both `qso_since` and `qsl_since` parameters with OR logic
+
+```javascript
+// Proposed sync logic (requires OR logic from DCL API)
+const lastQSODate = await getLastDCLQSODate(userId);  // Track QSO dates
+const lastQSLDate = await getLastDCLQSLDate(userId);  // Track QSL dates
+
+const requestBody = {
+  key: dclApiKey,
+  limit: 50000,
+  qso_since: lastQSODate,  // Get new QSOs since last contact
+  qsl_since: lastQSLDate,  // Get QSL confirmations since last sync
+  cnf_only: null,          // Fetch all QSOs
+};
+```
+
+**Required API Behavior (OR Logic)**:
+- Return QSOs where `(qso_date >= qso_since) OR (qsl_date >= qsl_since)`
+- This ensures we get both new QSOs and confirmation updates
+
+**Current DCL API Status**:
+- Unknown if current API uses AND or OR logic for combined filters
+- **Action Needed**: Request OR logic implementation from DARC
+- Test current behavior to confirm API response pattern
+
+**Why OR Logic is Needed**:
+- With AND logic: Old QSOs getting confirmed are missed (qso_date too old)
+- With OR logic: All updates captured efficiently in one API call
+
 ### QSO Page Filters
 
 The QSO page (`src/frontend/src/routes/qsos/+page.svelte`) includes advanced filtering capabilities: