docs: Improve sync interval documentation and logging

.env.example

@@ -7,6 +7,8 @@ CHATBOT_PHONE_NUMBER="1234567890"
 PORT="3007"
 WEBHOOK_URL="https://example-url.com/webhook"
 
-# Group sync interval in milliseconds (default: 24h)
-# Set lower during development (e.g. 60000 = 1 minute)
+# Group sync interval in milliseconds (default: 24h = 86400000ms)
+# - Set lower during development (e.g. 60000 = 1 minute)
+# - Minimum 10000ms (10s) enforced in development
+# - Format: plain number without quotes
 # GROUP_SYNC_INTERVAL_MS=86400000

src/services/group-sync.ts

@@ -10,6 +10,18 @@ type EvolutionGroup = {
 };
 
 export class GroupSyncService {
+  /**
+   * Gets the sync interval duration in milliseconds.
+   * 
+   * Priority:
+   * 1. GROUP_SYNC_INTERVAL_MS environment variable if set
+   * 2. Default 24 hour interval
+   * 
+   * In development mode, enforces minimum 10 second interval
+   * to prevent accidental excessive API calls.
+   * 
+   * @returns {number} Sync interval in milliseconds
+   */
   private static get SYNC_INTERVAL_MS(): number {
     const interval = process.env.GROUP_SYNC_INTERVAL_MS
       ? Number(process.env.GROUP_SYNC_INTERVAL_MS)
@@ -51,7 +63,14 @@ export class GroupSyncService {
 
   private static shouldSync(): boolean {
     const timeSinceLastSync = Date.now() - this.lastSyncAttempt;
-    return timeSinceLastSync > this.SYNC_INTERVAL_MS;
+    const shouldSync = timeSinceLastSync > this.SYNC_INTERVAL_MS;
+    
+    if (!shouldSync && process.env.NODE_ENV !== 'test') {
+      const nextSyncIn = this.SYNC_INTERVAL_MS - timeSinceLastSync;
+      console.debug(`Next sync available in ${Math.round(nextSyncIn/1000)} seconds`);
+    }
+    
+    return shouldSync;
   }
 
   private static async fetchGroupsFromAPI(): Promise<EvolutionGroup[]> {