Steps 1-11, still need to do 12

2025-08-07 15:29:23 -05:00
parent b66a516d20
commit 4019e921d3
15 changed files with 3731 additions and 55 deletions
--- a/.kiro/specs/scheduled-price-updates/design.md
+++ b/.kiro/specs/scheduled-price-updates/design.md
@@ -0,0 +1,253 @@
+# Design Document
+
+## Overview
+
+The scheduled price updates feature extends the existing Shopify Price Updater with optional scheduling capabilities. This allows users to configure price updates or rollbacks to execute at specific future times without requiring manual intervention. The design maintains backward compatibility while adding a new scheduling layer that wraps the existing application logic.
+
+## Architecture
+
+### High-Level Architecture
+
+The scheduling functionality will be implemented as a wrapper around the existing `ShopifyPriceUpdater` class, using Node.js's built-in `setTimeout` for scheduling and the `node-cron` library for more advanced scheduling patterns if needed in the future.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Scheduled Execution Layer                │
+├─────────────────────────────────────────────────────────────┤
+│  ScheduleManager                                           │
+│  - Parse scheduled time                                     │
+│  - Validate scheduling parameters                           │
+│  - Handle countdown display                                 │
+│  - Manage cancellation signals                              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 Existing Application Layer                  │
+├─────────────────────────────────────────────────────────────┤
+│  ShopifyPriceUpdater (unchanged)                           │
+│  - Product fetching and validation                          │
+│  - Price update/rollback operations                         │
+│  - Error handling and logging                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Integration Approach
+
+The scheduling feature will be integrated at the entry point (`src/index.js`) with minimal changes to existing code:
+
+1. **Environment Configuration**: Add `SCHEDULED_EXECUTION_TIME` to environment validation
+2. **Execution Flow**: Modify the main execution flow to check for scheduling before running operations
+3. **Scheduling Service**: Create a new `ScheduleService` to handle all scheduling logic
+4. **Graceful Cancellation**: Enhance existing signal handlers to support scheduled operation cancellation
+
+## Components and Interfaces
+
+### 1. ScheduleService
+
+**Location**: `src/services/schedule.js`
+
+**Responsibilities**:
+
+- Parse and validate scheduled execution times
+- Calculate delay until execution
+- Display countdown and status messages
+- Handle cancellation signals during waiting period
+- Execute the scheduled operation at the specified time
+
+**Interface**:
+
+```javascript
+class ScheduleService {
+  constructor(logger)
+
+  // Parse and validate scheduled time from environment variable
+  parseScheduledTime(scheduledTimeString): Date
+
+  // Calculate milliseconds until scheduled execution
+  calculateDelay(scheduledTime): number
+
+  // Display scheduling confirmation and countdown
+  displayScheduleInfo(scheduledTime): Promise<void>
+
+  // Wait until scheduled time with cancellation support
+  waitUntilScheduledTime(scheduledTime, onCancel): Promise<boolean>
+
+  // Execute the scheduled operation
+  executeScheduledOperation(operationCallback): Promise<number>
+}
+```
+
+### 2. Environment Configuration Updates
+
+**Location**: `src/config/environment.js`
+
+**Changes**:
+
+- Add `SCHEDULED_EXECUTION_TIME` as optional environment variable
+- Add validation for datetime format when provided
+- Ensure backward compatibility when scheduling is not used
+
+**New Configuration Properties**:
+
+```javascript
+{
+  // ... existing properties
+  scheduledExecutionTime: string | null, // ISO 8601 datetime or null
+  isScheduled: boolean // derived property for convenience
+}
+```
+
+### 3. Main Application Updates
+
+**Location**: `src/index.js`
+
+**Changes**:
+
+- Integrate ScheduleService into the main execution flow
+- Add scheduling logic before existing operation execution
+- Enhance signal handlers to support scheduled operation cancellation
+- Maintain all existing functionality when scheduling is not used
+
+## Data Models
+
+### Scheduled Execution Configuration
+
+```javascript
+{
+  scheduledTime: Date,           // Parsed execution time
+  originalTimeString: string,    // Original input for logging
+  delayMs: number,              // Milliseconds until execution
+  timezone: string,             // Detected or specified timezone
+  isValid: boolean,             // Validation result
+  validationError: string | null // Error message if invalid
+}
+```
+
+### Schedule Status
+
+```javascript
+{
+  status: 'waiting' | 'executing' | 'cancelled' | 'completed',
+  scheduledTime: Date,
+  currentTime: Date,
+  remainingMs: number,
+  countdownDisplay: string
+}
+```
+
+## Error Handling
+
+### Scheduling-Specific Errors
+
+1. **Invalid DateTime Format**
+
+   - Error: Clear message explaining expected format (ISO 8601)
+   - Action: Exit with status code 1
+   - Logging: Log error to console and progress file
+
+2. **Past DateTime**
+
+   - Error: Message indicating scheduled time is in the past
+   - Action: Exit with status code 1
+   - Logging: Log error with current time for reference
+
+3. **System Clock Issues**
+   - Error: Handle cases where system time is unreliable
+   - Action: Display warning but continue if reasonable
+   - Logging: Log warning about potential timing issues
+
+### Execution-Time Errors
+
+1. **Network Issues During Scheduled Execution**
+
+   - Behavior: Use existing retry logic from ShopifyPriceUpdater
+   - Enhancement: Add context that this was a scheduled operation
+   - Logging: Include scheduling information in error logs
+
+2. **Cancellation During Execution**
+   - Behavior: Allow graceful cancellation during waiting period
+   - Restriction: Cannot cancel once actual price updates begin
+   - Logging: Log cancellation with timestamp and reason
+
+## Testing Strategy
+
+### Unit Tests
+
+1. **ScheduleService Tests**
+
+   - DateTime parsing with various formats
+   - Delay calculation accuracy
+   - Validation logic for edge cases
+   - Cancellation handling
+
+2. **Environment Configuration Tests**
+
+   - Optional scheduling parameter handling
+   - Backward compatibility verification
+   - Invalid datetime format handling
+
+3. **Integration Tests**
+   - End-to-end scheduling workflow
+   - Cancellation during waiting period
+   - Scheduled execution with both update and rollback modes
+
+### Test Scenarios
+
+1. **Valid Scheduling Scenarios**
+
+   - Schedule update operation 5 minutes in future
+   - Schedule rollback operation with timezone specification
+   - Schedule operation without timezone (use system default)
+
+2. **Error Scenarios**
+
+   - Invalid datetime formats
+   - Past datetime values
+   - Extremely distant future dates (>7 days warning)
+
+3. **Cancellation Scenarios**
+
+   - Cancel during countdown period
+   - Attempt to cancel during execution (should not interrupt)
+   - Multiple cancellation signals
+
+4. **Backward Compatibility**
+   - Run existing operations without scheduling
+   - Ensure no performance impact when scheduling not used
+   - Verify all existing environment variables still work
+
+## Implementation Considerations
+
+### DateTime Handling
+
+- **Primary Format**: ISO 8601 (YYYY-MM-DDTHH:MM:SS)
+- **Timezone Support**: Accept timezone suffixes or default to system timezone
+- **Validation**: Strict parsing with clear error messages for invalid formats
+- **Edge Cases**: Handle daylight saving time transitions
+
+### Performance Impact
+
+- **Minimal Overhead**: Scheduling logic only active when `SCHEDULED_EXECUTION_TIME` is set
+- **Memory Usage**: Minimal additional memory for scheduling state
+- **CPU Usage**: Efficient countdown display (update every 30 seconds, not every second)
+
+### User Experience
+
+- **Clear Feedback**: Immediate confirmation of scheduled time
+- **Progress Indication**: Countdown display showing time remaining
+- **Cancellation**: Clear instructions on how to cancel (Ctrl+C)
+- **Logging**: All scheduling events logged to Progress.md file
+
+### Security Considerations
+
+- **Input Validation**: Strict datetime parsing to prevent injection attacks
+- **Resource Limits**: Reasonable limits on future scheduling (warning for >7 days)
+- **Process Management**: Proper cleanup of timers and resources on cancellation
+
+### Deployment Considerations
+
+- **Dependencies**: Minimal new dependencies (prefer built-in Node.js features)
+- **Environment Variables**: Optional configuration maintains backward compatibility
+- **Process Management**: Works with existing process managers and containers
+- **Logging**: Scheduling events integrate with existing logging infrastructure