@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/patterns/patterns-state-duplicate-prevention.md

@@ -1,385 +1,385 @@
-# Pattern: State Management & Duplicate Prevention
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Focused guide on preventing duplicate processing and managing state
-
-**Type**: Reusable Pattern
-
-**Complexity**: Low-Medium
-
-**Lines**: ~120 lines
-
-## When to Use This Pattern
-
-- **File processing workflows**: Track which files have been processed
-- **Idempotent operations**: Ensure operations can be safely retried
-- **Checkpoint/resume capabilities**: Save progress and resume after failures
-- **Distributed processing**: Prevent multiple instances from processing the same data
-- **Preventing duplicate records**: Avoid sending duplicate batches to Fluent Commerce
-
-## SDK Methods
-
-### StateService (Full-Featured)
-
-- `StateService(logger)` - Comprehensive state management service
-- `stateService.isFileProcessed(kv, fileName, workflowId?)` - Check file status
-- `stateService.updateSyncState(kv, processedFiles, workflowId?)` - Update sync state
-- `stateService.getSyncState(kv, workflowId?)` - Get current sync state
-- `stateService.acquireLock(lockName, kv, timeoutMinutes)` - Distributed locking
-- `stateService.releaseLock(lockName, kv)` - Release lock
-- `stateService.getDailyJob(kv, workflowId)` - Get daily job (for DAILY strategy)
-- `stateService.setDailyJob(kv, workflowId, jobId, expirationHours)` - Store daily job
-
-### VersoriFileTracker (Simplified)
-
-- `VersoriFileTracker(versoriKV, prefix)` - Simple file tracking for Versori
-- `tracker.wasFileProcessed(fileName)` - Check if file was processed
-- `tracker.markFileProcessed(fileName, metadata?)` - Mark file as processed
-- `tracker.getLastProcessedFile()` - Get last processed file name
-- `tracker.setLastProcessedFile(fileName)` - Update last processed file
-
-### VersoriKVAdapter (Bridge)
-
-- `VersoriKVAdapter(versoriKV)` - Adapts Versori KV to StateService's KVStore interface
-- Enables using full StateService functionality in Versori platform
-
----
-
-## Pattern 1: File Duplicate Prevention (Simple)
-
-**Use Case**: Prevent processing the same file twice in Versori workflows
-
-```typescript
-// FC Connect SDK (latest)
-// Install: npm install @fluentcommerce/fc-connect-sdk@latest
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-// In your Versori workflow
-fn('process-files', async ({ openKv }) => {
-  const kv = openKv();
-  const tracker = new VersoriFileTracker(kv, 'inventory-ingestion');
-
-  const files = await s3Client.listFiles({ bucket: 'inventory-files' });
-
-  for (const file of files) {
-    // Check if already processed
-    const wasProcessed = await tracker.wasFileProcessed(file.name);
-    if (wasProcessed) {
-      console.log(`Skipping already processed file: ${file.name}`);
-      continue;
-    }
-
-    try {
-      // Process file
-      await processInventoryFile(file);
-
-      // Mark as processed with metadata
-      await tracker.markFileProcessed(file.name, {
-        recordCount: file.recordCount,
-      });
-
-      console.log(`Successfully processed: ${file.name}`);
-    } catch (error) {
-      console.error(`Failed to process ${file.name}:`, error);
-      // Don't mark as processed on error - allow retry
-    }
-  }
-});
-```
-
-**Key Benefits**:
-
-- Simple API designed specifically for Versori
-- Automatic timestamping of processed files
-- Metadata tracking for audit trails
-
----
-
-## Pattern 2: Checkpoint Save/Restore
-
-**Use Case**: Save processing progress and resume after failures
-
-```typescript
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-fn('batch-processing-with-checkpoints', async ({ openKv, logger }) => {
-  const kv = new VersoriKVAdapter(openKv());
-  const stateService = new StateService(logger);
-
-  // Get last checkpoint
-  const syncState = await stateService.getSyncState(kv, 'batch-processor');
-  const lastProcessed = syncState.lastProcessedTimestamp;
-  logger.info('Resuming from checkpoint', { lastProcessed });
-
-  // Fetch records newer than last checkpoint
-  const records = await fetchRecordsSince(lastProcessed);
-  const processedFiles = [];
-
-  for (const batch of chunk(records, 1000)) {
-    try {
-      // Process batch
-      await sendBatchToFluent(batch);
-
-      // Save checkpoint after each successful batch
-      processedFiles.push({
-        fileName: `batch-${batch[0].id}-${batch[batch.length - 1].id}`,
-        lastModified: new Date().toISOString(),
-        recordCount: batch.length,
-      });
-
-      // Update checkpoint state
-      await stateService.updateSyncState(kv, processedFiles, 'batch-processor');
-
-      logger.info('Checkpoint saved', {
-        batchSize: batch.length,
-        totalProcessed: processedFiles.length,
-      });
-    } catch (error) {
-      logger.error('Batch failed, checkpoint preserved for retry', error);
-      throw error; // Workflow will resume from last successful checkpoint
-    }
-  }
-});
-```
-
-**Key Benefits**:
-
-- Resume exactly where you left off after failures
-- Incremental sync tracking with timestamps
-- Detailed processing history per file/batch
-
----
-
-## Pattern 3: Distributed Locking
-
-**Use Case**: Prevent multiple workflow instances from running concurrently
-
-```typescript
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-fn('exclusive-ingestion', async ({ openKv, logger }) => {
-  const kv = new VersoriKVAdapter(openKv());
-  const stateService = new StateService(logger);
-
-  const lockName = 'inventory-ingestion';
-  const timeoutMinutes = 15;
-
-  // Try to acquire lock
-  const acquired = await stateService.acquireLock(lockName, kv, timeoutMinutes);
-
-  if (!acquired) {
-    logger.warn('Another instance is running, aborting');
-    return { skipped: true, reason: 'Lock held by another instance' };
-  }
-
-  try {
-    logger.info('Lock acquired, starting ingestion');
-
-    // Perform exclusive work
-    await performIngestion();
-
-    logger.info('Ingestion completed');
-    return { success: true };
-  } finally {
-    // Always release lock, even on error
-    await stateService.releaseLock(lockName, kv);
-    logger.info('Lock released');
-  }
-});
-```
-
-**Key Benefits**:
-
-- Prevents race conditions in distributed systems
-- Automatic stale lock detection (overrides expired locks)
-- Safe cleanup with finally blocks
-
----
-
-## Pattern 4: Idempotency Keys
-
-**Use Case**: Ensure batch operations can be safely retried
-
-```typescript
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-fn('idempotent-batch-submission', async ({ openKv, logger }) => {
-  const tracker = new VersoriFileTracker(openKv(), 'batch-submissions');
-  const batches = prepareBatches();
-
-  for (const batch of batches) {
-    // Generate idempotency key from batch content
-    const batchKey = `job-${batch.jobId}-batch-${batch.batchIndex}`;
-
-    // Check if batch was already sent
-    if (await tracker.wasFileProcessed(batchKey)) {
-      logger.info(`Batch already sent, skipping: ${batchKey}`);
-      continue;
-    }
-
-    try {
-      // Send batch to Fluent Commerce
-      const response = await fluentClient.sendBatch(batch.jobId, {
-        entities: batch.entities,
-      });
-
-      // Mark as sent with response metadata
-      await tracker.markFileProcessed(batchKey, {
-        recordCount: batch.entities.length,
-        batchId: response.id,
-        status: response.status,
-      });
-
-      logger.info(`Batch sent successfully: ${batchKey}`);
-    } catch (error) {
-      logger.error(`Batch submission failed: ${batchKey}`, error);
-      // Don't mark as processed - will retry on next run
-      throw error;
-    }
-  }
-});
-```
-
-**Key Benefits**:
-
-- Safe retries after network failures
-- Prevents duplicate batch submissions
-- Audit trail of all batch submissions
-
----
-
-## Pattern 5: Daily Job Reuse (DAILY Strategy)
-
-**Use Case**: Reuse a single Fluent job for an entire day's batches
-
-```typescript
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-fn('daily-job-strategy', async ({ openKv, logger }) => {
-  const kv = new VersoriKVAdapter(openKv());
-  const stateService = new StateService(logger);
-  const workflowId = 'inventory-sync';
-
-  // Check if we have a valid job for today
-  let dailyJob = await stateService.getDailyJob(kv, workflowId);
-
-  if (!dailyJob) {
-    // Create new job for today
-    const job = await fluentClient.createJob({
-      name: `inventory-sync-${new Date().toISOString().split('T')[0]}`,
-      retailerId: 'my-retailer',
-    });
-
-    // Store job for reuse (expires in 24 hours)
-    await stateService.setDailyJob(kv, workflowId, job.id, 24);
-    logger.info('Created new daily job', { jobId: job.id });
-    dailyJob = { jobId: job.id };
-  } else {
-    logger.info('Reusing existing daily job', { jobId: dailyJob.jobId });
-  }
-
-  // Use the job for batch submission
-  await fluentClient.sendBatch(dailyJob.jobId, {
-    entities: inventoryData,
-  });
-});
-```
-
-**Key Benefits**:
-
-- Reduces job creation overhead
-- All daily batches grouped under single job
-- Automatic expiration and renewal
-
----
-
-## Best Practices
-
-### State Key Naming
-
-```typescript
-// ✅ GOOD: Scoped, descriptive keys
-const fileKey = `inventory-ingestion:processed-files:${fileName}`;
-const lockKey = `locks:inventory-sync:${workflowId}`;
-const checkpointKey = `checkpoints:extraction:${connectionId}`;
-
-// ❌ BAD: Generic, collision-prone keys
-const fileKey = fileName;
-const lockKey = 'lock';
-const checkpointKey = 'state';
-```
-
-### Error Handling
-
-```typescript
-// ✅ GOOD: Don't mark as processed on error
-try {
-  await processFile(file);
-  await tracker.markFileProcessed(file.name);
-} catch (error) {
-  logger.error('Processing failed, will retry', error);
-  // Don't mark as processed - allow retry
-}
-
-// ❌ BAD: Marking as processed before completion
-await tracker.markFileProcessed(file.name); // Too early!
-await processFile(file); // Might fail, but already marked
-```
-
-### Lock Cleanup
-
-```typescript
-// ✅ GOOD: Always release locks with finally
-const acquired = await stateService.acquireLock('sync', kv, 15);
-if (!acquired) return;
-try {
-  await performWork();
-} finally {
-  await stateService.releaseLock('sync', kv);
-}
-
-// ❌ BAD: Lock might not be released on error
-const acquired = await stateService.acquireLock('sync', kv, 15);
-await performWork();
-await stateService.releaseLock('sync', kv); // Skipped if performWork throws!
-```
-
-### Metadata Tracking
-
-```typescript
-// ✅ GOOD: Rich metadata for debugging
-await tracker.markFileProcessed(fileName, {
-  recordCount: records.length,
-  processingTime: Date.now() - startTime,
-  sourceSystem: 'SAP',
-  batchId: batchResponse.id,
-});
-
-// ❌ BAD: No metadata
-await tracker.markFileProcessed(fileName);
-```
-
----
-
-## Common Pitfalls
-
-1. **Forgetting to release locks**: Always use `finally` blocks
-2. **Marking files processed too early**: Mark only after successful completion
-3. **Not handling stale state**: Use lock timeouts and expiration
-4. **Poor key naming**: Use descriptive, scoped keys to avoid collisions
-5. **Missing error logging**: Track why processing failed for debugging
-
----
-
-## See Also
-
-- [Batch Processing Pattern](../../03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-02-batch-processing.md)
-- [Error Handling Pattern](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
-- [StateService API Reference](../../02-CORE-GUIDES/api-reference/modules/api-reference-10-utilities.md)
-- [VersoriFileTracker API Reference](../../04-REFERENCE/platforms/versori/modules/platforms-versori-06-kv-storage.md)
+# Pattern: State Management & Duplicate Prevention
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Focused guide on preventing duplicate processing and managing state
+
+**Type**: Reusable Pattern
+
+**Complexity**: Low-Medium
+
+**Lines**: ~120 lines
+
+## When to Use This Pattern
+
+- **File processing workflows**: Track which files have been processed
+- **Idempotent operations**: Ensure operations can be safely retried
+- **Checkpoint/resume capabilities**: Save progress and resume after failures
+- **Distributed processing**: Prevent multiple instances from processing the same data
+- **Preventing duplicate records**: Avoid sending duplicate batches to Fluent Commerce
+
+## SDK Methods
+
+### StateService (Full-Featured)
+
+- `StateService(logger)` - Comprehensive state management service
+- `stateService.isFileProcessed(kv, fileName, workflowId?)` - Check file status
+- `stateService.updateSyncState(kv, processedFiles, workflowId?)` - Update sync state
+- `stateService.getSyncState(kv, workflowId?)` - Get current sync state
+- `stateService.acquireLock(lockName, kv, timeoutMinutes)` - Distributed locking
+- `stateService.releaseLock(lockName, kv)` - Release lock
+- `stateService.getDailyJob(kv, workflowId)` - Get daily job (for DAILY strategy)
+- `stateService.setDailyJob(kv, workflowId, jobId, expirationHours)` - Store daily job
+
+### VersoriFileTracker (Simplified)
+
+- `VersoriFileTracker(versoriKV, prefix)` - Simple file tracking for Versori
+- `tracker.wasFileProcessed(fileName)` - Check if file was processed
+- `tracker.markFileProcessed(fileName, metadata?)` - Mark file as processed
+- `tracker.getLastProcessedFile()` - Get last processed file name
+- `tracker.setLastProcessedFile(fileName)` - Update last processed file
+
+### VersoriKVAdapter (Bridge)
+
+- `VersoriKVAdapter(versoriKV)` - Adapts Versori KV to StateService's KVStore interface
+- Enables using full StateService functionality in Versori platform
+
+---
+
+## Pattern 1: File Duplicate Prevention (Simple)
+
+**Use Case**: Prevent processing the same file twice in Versori workflows
+
+```typescript
+// FC Connect SDK (latest)
+// Install: npm install @fluentcommerce/fc-connect-sdk@latest
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+// In your Versori workflow
+fn('process-files', async ({ openKv }) => {
+  const kv = openKv();
+  const tracker = new VersoriFileTracker(kv, 'inventory-ingestion');
+
+  const files = await s3Client.listFiles({ bucket: 'inventory-files' });
+
+  for (const file of files) {
+    // Check if already processed
+    const wasProcessed = await tracker.wasFileProcessed(file.name);
+    if (wasProcessed) {
+      console.log(`Skipping already processed file: ${file.name}`);
+      continue;
+    }
+
+    try {
+      // Process file
+      await processInventoryFile(file);
+
+      // Mark as processed with metadata
+      await tracker.markFileProcessed(file.name, {
+        recordCount: file.recordCount,
+      });
+
+      console.log(`Successfully processed: ${file.name}`);
+    } catch (error) {
+      console.error(`Failed to process ${file.name}:`, error);
+      // Don't mark as processed on error - allow retry
+    }
+  }
+});
+```
+
+**Key Benefits**:
+
+- Simple API designed specifically for Versori
+- Automatic timestamping of processed files
+- Metadata tracking for audit trails
+
+---
+
+## Pattern 2: Checkpoint Save/Restore
+
+**Use Case**: Save processing progress and resume after failures
+
+```typescript
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+fn('batch-processing-with-checkpoints', async ({ openKv, logger }) => {
+  const kv = new VersoriKVAdapter(openKv());
+  const stateService = new StateService(logger);
+
+  // Get last checkpoint
+  const syncState = await stateService.getSyncState(kv, 'batch-processor');
+  const lastProcessed = syncState.lastProcessedTimestamp;
+  logger.info('Resuming from checkpoint', { lastProcessed });
+
+  // Fetch records newer than last checkpoint
+  const records = await fetchRecordsSince(lastProcessed);
+  const processedFiles = [];
+
+  for (const batch of chunk(records, 1000)) {
+    try {
+      // Process batch
+      await sendBatchToFluent(batch);
+
+      // Save checkpoint after each successful batch
+      processedFiles.push({
+        fileName: `batch-${batch[0].id}-${batch[batch.length - 1].id}`,
+        lastModified: new Date().toISOString(),
+        recordCount: batch.length,
+      });
+
+      // Update checkpoint state
+      await stateService.updateSyncState(kv, processedFiles, 'batch-processor');
+
+      logger.info('Checkpoint saved', {
+        batchSize: batch.length,
+        totalProcessed: processedFiles.length,
+      });
+    } catch (error) {
+      logger.error('Batch failed, checkpoint preserved for retry', error);
+      throw error; // Workflow will resume from last successful checkpoint
+    }
+  }
+});
+```
+
+**Key Benefits**:
+
+- Resume exactly where you left off after failures
+- Incremental sync tracking with timestamps
+- Detailed processing history per file/batch
+
+---
+
+## Pattern 3: Distributed Locking
+
+**Use Case**: Prevent multiple workflow instances from running concurrently
+
+```typescript
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+fn('exclusive-ingestion', async ({ openKv, logger }) => {
+  const kv = new VersoriKVAdapter(openKv());
+  const stateService = new StateService(logger);
+
+  const lockName = 'inventory-ingestion';
+  const timeoutMinutes = 15;
+
+  // Try to acquire lock
+  const acquired = await stateService.acquireLock(lockName, kv, timeoutMinutes);
+
+  if (!acquired) {
+    logger.warn('Another instance is running, aborting');
+    return { skipped: true, reason: 'Lock held by another instance' };
+  }
+
+  try {
+    logger.info('Lock acquired, starting ingestion');
+
+    // Perform exclusive work
+    await performIngestion();
+
+    logger.info('Ingestion completed');
+    return { success: true };
+  } finally {
+    // Always release lock, even on error
+    await stateService.releaseLock(lockName, kv);
+    logger.info('Lock released');
+  }
+});
+```
+
+**Key Benefits**:
+
+- Prevents race conditions in distributed systems
+- Automatic stale lock detection (overrides expired locks)
+- Safe cleanup with finally blocks
+
+---
+
+## Pattern 4: Idempotency Keys
+
+**Use Case**: Ensure batch operations can be safely retried
+
+```typescript
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+fn('idempotent-batch-submission', async ({ openKv, logger }) => {
+  const tracker = new VersoriFileTracker(openKv(), 'batch-submissions');
+  const batches = prepareBatches();
+
+  for (const batch of batches) {
+    // Generate idempotency key from batch content
+    const batchKey = `job-${batch.jobId}-batch-${batch.batchIndex}`;
+
+    // Check if batch was already sent
+    if (await tracker.wasFileProcessed(batchKey)) {
+      logger.info(`Batch already sent, skipping: ${batchKey}`);
+      continue;
+    }
+
+    try {
+      // Send batch to Fluent Commerce
+      const response = await fluentClient.sendBatch(batch.jobId, {
+        entities: batch.entities,
+      });
+
+      // Mark as sent with response metadata
+      await tracker.markFileProcessed(batchKey, {
+        recordCount: batch.entities.length,
+        batchId: response.id,
+        status: response.status,
+      });
+
+      logger.info(`Batch sent successfully: ${batchKey}`);
+    } catch (error) {
+      logger.error(`Batch submission failed: ${batchKey}`, error);
+      // Don't mark as processed - will retry on next run
+      throw error;
+    }
+  }
+});
+```
+
+**Key Benefits**:
+
+- Safe retries after network failures
+- Prevents duplicate batch submissions
+- Audit trail of all batch submissions
+
+---
+
+## Pattern 5: Daily Job Reuse (DAILY Strategy)
+
+**Use Case**: Reuse a single Fluent job for an entire day's batches
+
+```typescript
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+fn('daily-job-strategy', async ({ openKv, logger }) => {
+  const kv = new VersoriKVAdapter(openKv());
+  const stateService = new StateService(logger);
+  const workflowId = 'inventory-sync';
+
+  // Check if we have a valid job for today
+  let dailyJob = await stateService.getDailyJob(kv, workflowId);
+
+  if (!dailyJob) {
+    // Create new job for today
+    const job = await fluentClient.createJob({
+      name: `inventory-sync-${new Date().toISOString().split('T')[0]}`,
+      retailerId: 'my-retailer',
+    });
+
+    // Store job for reuse (expires in 24 hours)
+    await stateService.setDailyJob(kv, workflowId, job.id, 24);
+    logger.info('Created new daily job', { jobId: job.id });
+    dailyJob = { jobId: job.id };
+  } else {
+    logger.info('Reusing existing daily job', { jobId: dailyJob.jobId });
+  }
+
+  // Use the job for batch submission
+  await fluentClient.sendBatch(dailyJob.jobId, {
+    entities: inventoryData,
+  });
+});
+```
+
+**Key Benefits**:
+
+- Reduces job creation overhead
+- All daily batches grouped under single job
+- Automatic expiration and renewal
+
+---
+
+## Best Practices
+
+### State Key Naming
+
+```typescript
+// ✅ GOOD: Scoped, descriptive keys
+const fileKey = `inventory-ingestion:processed-files:${fileName}`;
+const lockKey = `locks:inventory-sync:${workflowId}`;
+const checkpointKey = `checkpoints:extraction:${connectionId}`;
+
+// ❌ BAD: Generic, collision-prone keys
+const fileKey = fileName;
+const lockKey = 'lock';
+const checkpointKey = 'state';
+```
+
+### Error Handling
+
+```typescript
+// ✅ GOOD: Don't mark as processed on error
+try {
+  await processFile(file);
+  await tracker.markFileProcessed(file.name);
+} catch (error) {
+  logger.error('Processing failed, will retry', error);
+  // Don't mark as processed - allow retry
+}
+
+// ❌ BAD: Marking as processed before completion
+await tracker.markFileProcessed(file.name); // Too early!
+await processFile(file); // Might fail, but already marked
+```
+
+### Lock Cleanup
+
+```typescript
+// ✅ GOOD: Always release locks with finally
+const acquired = await stateService.acquireLock('sync', kv, 15);
+if (!acquired) return;
+try {
+  await performWork();
+} finally {
+  await stateService.releaseLock('sync', kv);
+}
+
+// ❌ BAD: Lock might not be released on error
+const acquired = await stateService.acquireLock('sync', kv, 15);
+await performWork();
+await stateService.releaseLock('sync', kv); // Skipped if performWork throws!
+```
+
+### Metadata Tracking
+
+```typescript
+// ✅ GOOD: Rich metadata for debugging
+await tracker.markFileProcessed(fileName, {
+  recordCount: records.length,
+  processingTime: Date.now() - startTime,
+  sourceSystem: 'SAP',
+  batchId: batchResponse.id,
+});
+
+// ❌ BAD: No metadata
+await tracker.markFileProcessed(fileName);
+```
+
+---
+
+## Common Pitfalls
+
+1. **Forgetting to release locks**: Always use `finally` blocks
+2. **Marking files processed too early**: Mark only after successful completion
+3. **Not handling stale state**: Use lock timeouts and expiration
+4. **Poor key naming**: Use descriptive, scoped keys to avoid collisions
+5. **Missing error logging**: Track why processing failed for debugging
+
+---
+
+## See Also
+
+- [Batch Processing Pattern](../../03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-02-batch-processing.md)
+- [Error Handling Pattern](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+- [StateService API Reference](../../02-CORE-GUIDES/api-reference/modules/api-reference-10-utilities.md)
+- [VersoriFileTracker API Reference](../../04-REFERENCE/platforms/versori/modules/platforms-versori-06-kv-storage.md)