Steps 1-11, still need to do 12
This commit is contained in:
253
.kiro/specs/scheduled-price-updates/design.md
Normal file
253
.kiro/specs/scheduled-price-updates/design.md
Normal file
@@ -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
|
||||
60
.kiro/specs/scheduled-price-updates/requirements.md
Normal file
60
.kiro/specs/scheduled-price-updates/requirements.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Requirements Document
|
||||
|
||||
## Introduction
|
||||
|
||||
This feature adds optional scheduling capabilities to the Shopify Price Updater, allowing users to schedule price updates or rollbacks to execute at specific future times. This enables store owners to set up promotional campaigns in advance without needing to manually execute the script at the exact moment the sale should begin or end.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement 1
|
||||
|
||||
**User Story:** As a store owner, I want to schedule a price update to run at a specific date and time, so that I can set up promotional campaigns in advance without staying up late or being available at the exact moment.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a user sets a SCHEDULED_EXECUTION_TIME environment variable THEN the system SHALL validate the datetime format and schedule the operation accordingly
|
||||
2. WHEN the scheduled time is reached THEN the system SHALL execute the configured price update or rollback operation automatically
|
||||
3. WHEN no SCHEDULED_EXECUTION_TIME is provided THEN the system SHALL execute immediately as it currently does
|
||||
4. WHEN an invalid datetime format is provided THEN the system SHALL display a clear error message and exit without scheduling
|
||||
|
||||
### Requirement 2
|
||||
|
||||
**User Story:** As a store owner, I want to see confirmation that my price update has been scheduled, so that I can be confident the operation will run at the correct time.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a scheduled operation is configured THEN the system SHALL display the scheduled execution time in a human-readable format
|
||||
2. WHEN a scheduled operation is waiting THEN the system SHALL show a countdown or status message indicating when it will execute
|
||||
3. WHEN the scheduled time arrives THEN the system SHALL log the start of the scheduled operation with a timestamp
|
||||
|
||||
### Requirement 3
|
||||
|
||||
**User Story:** As a store owner, I want to be able to cancel a scheduled operation before it executes, so that I can change my mind or correct mistakes.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN a scheduled operation is waiting THEN the system SHALL respond to standard interrupt signals (Ctrl+C) to cancel the operation
|
||||
2. WHEN a scheduled operation is cancelled THEN the system SHALL display a confirmation message and exit cleanly
|
||||
3. WHEN a scheduled operation is cancelled THEN the system SHALL NOT execute any price updates
|
||||
|
||||
### Requirement 4
|
||||
|
||||
**User Story:** As a store owner, I want flexible datetime input options, so that I can easily specify when my sale should start or end.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN specifying a scheduled time THEN the system SHALL accept ISO 8601 datetime format (YYYY-MM-DDTHH:MM:SS)
|
||||
2. WHEN specifying a scheduled time THEN the system SHALL accept timezone information or default to the system timezone
|
||||
3. WHEN the scheduled time is in the past THEN the system SHALL display an error and not schedule the operation
|
||||
4. WHEN the scheduled time is more than 7 days in the future THEN the system SHALL display a warning but still schedule the operation
|
||||
|
||||
### Requirement 5
|
||||
|
||||
**User Story:** As a store owner, I want the scheduled operation to handle errors gracefully, so that temporary issues don't prevent my promotional campaign from running.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
1. WHEN the scheduled time arrives AND there are network connectivity issues THEN the system SHALL retry the operation with exponential backoff
|
||||
2. WHEN the scheduled operation encounters API rate limits THEN the system SHALL handle them using the existing retry logic
|
||||
3. WHEN the scheduled operation fails after all retries THEN the system SHALL log detailed error information for troubleshooting
|
||||
4. WHEN the scheduled operation completes successfully THEN the system SHALL log the completion status and summary
|
||||
85
.kiro/specs/scheduled-price-updates/tasks.md
Normal file
85
.kiro/specs/scheduled-price-updates/tasks.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# Implementation Plan
|
||||
|
||||
- [x] 1. Create ScheduleService with core scheduling functionality
|
||||
|
||||
- Implement datetime parsing and validation methods
|
||||
- Add delay calculation logic for scheduling operations
|
||||
- Create countdown display functionality with user-friendly formatting
|
||||
- _Requirements: 1.1, 1.4, 4.1, 4.2, 4.3_
|
||||
|
||||
- [x] 2. Implement scheduling wait logic with cancellation support
|
||||
|
||||
- Add waitUntilScheduledTime method with Promise-based timing
|
||||
- Implement graceful cancellation handling during wait period
|
||||
- Create status display updates during countdown period
|
||||
- _Requirements: 2.2, 3.1, 3.2_
|
||||
|
||||
- [x] 3. Update environment configuration to support scheduling
|
||||
|
||||
- Add SCHEDULED_EXECUTION_TIME as optional environment variable to loadEnvironmentConfig
|
||||
- Implement validation logic for datetime format when scheduling is provided
|
||||
- Ensure backward compatibility when scheduling parameter is not set
|
||||
- _Requirements: 1.1, 4.1, 4.2, 4.3, 4.4_
|
||||
|
||||
- [x] 4. Integrate scheduling into main application flow
|
||||
|
||||
- Modify main execution function to check for scheduled execution time
|
||||
- Add scheduling confirmation display before entering wait period
|
||||
- Implement scheduled operation execution with existing ShopifyPriceUpdater logic
|
||||
- _Requirements: 1.2, 2.1, 2.3_
|
||||
|
||||
- [x] 5. Enhance signal handlers for scheduled operation cancellation
|
||||
|
||||
- Update SIGINT and SIGTERM handlers to support cancellation during wait period
|
||||
- Add clear cancellation confirmation messages for scheduled operations
|
||||
- Ensure cancellation does not interrupt operations once price updates begin
|
||||
- _Requirements: 3.1, 3.2, 3.3_
|
||||
|
||||
- [x] 6. Add comprehensive error handling for scheduling scenarios
|
||||
|
||||
- Implement error handling for invalid datetime formats with clear messages
|
||||
- Add validation for past datetime values with helpful error messages
|
||||
- Create warning system for distant future dates (>7 days)
|
||||
- _Requirements: 1.4, 4.3, 4.4_
|
||||
|
||||
- [x] 7. Update .env.example with scheduling configuration
|
||||
|
||||
- Add SCHEDULED_EXECUTION_TIME example with proper ISO 8601 format
|
||||
- Include comments explaining scheduling functionality and format requirements
|
||||
- Provide examples for different timezone specifications
|
||||
- _Requirements: 4.1, 4.2_
|
||||
|
||||
- [x] 8. Implement logging integration for scheduled operations
|
||||
|
||||
- Add scheduling event logging to existing Logger class methods
|
||||
- Log scheduling confirmation, countdown updates, and execution start
|
||||
- Integrate scheduled operation context into existing error logging
|
||||
- _Requirements: 2.1, 2.3, 5.3, 5.4_
|
||||
|
||||
- [x] 9. Create unit tests for ScheduleService functionality
|
||||
|
||||
- Write tests for datetime parsing with various valid and invalid formats
|
||||
- Test delay calculation accuracy and edge cases
|
||||
- Create tests for cancellation handling during wait periods
|
||||
- _Requirements: 1.1, 1.4, 3.1, 4.1, 4.2, 4.3_
|
||||
|
||||
- [x] 10. Write integration tests for scheduled execution workflow
|
||||
|
||||
- Test complete scheduling workflow with both update and rollback modes
|
||||
- Create tests for cancellation scenarios during countdown period
|
||||
- Verify backward compatibility when scheduling is not used
|
||||
- _Requirements: 1.2, 2.1, 3.1, 3.2, 5.1, 5.2_
|
||||
|
||||
- [x] 11. Add error handling tests for scheduling edge cases
|
||||
|
||||
- Test invalid datetime format handling with clear error messages
|
||||
- Create tests for past datetime validation and error responses
|
||||
- Test system behavior with distant future dates and warning display
|
||||
- _Requirements: 1.4, 4.3, 4.4, 5.3_
|
||||
|
||||
- [ ] 12. Update package.json scripts for scheduled operations
|
||||
|
||||
- Add npm scripts for common scheduling scenarios (e.g., schedule-update, schedule-rollback)
|
||||
- Include examples in script comments for typical scheduling use cases
|
||||
- Ensure existing scripts continue to work without scheduling
|
||||
- _Requirements: 1.1, 1.2_
|
||||
Reference in New Issue
Block a user