PriceUpdaterAppv2/.kiro/specs/price-rollback/requirements.md

Requirements Document

Introduction

This feature involves adding a rollback functionality to the existing Shopify price updater application that reverses pricing changes by setting the main product price to the current compare-at price and removing the compare-at price. This allows store administrators to easily revert promotional pricing back to original prices for products filtered by specific tags. The solution will extend the existing Shopify GraphQL API infrastructure and provide both price updating and rollback capabilities within the same application.

Requirements

Requirement 1

User Story: As a store administrator, I want to rollback product prices for products with specific tags, so that I can easily revert promotional pricing to original prices.

Acceptance Criteria

1. WHEN the rollback script is executed THEN the system SHALL connect to Shopify using GraphQL API
2. WHEN connecting to Shopify THEN the system SHALL authenticate using existing API credentials from environment variables
3. WHEN querying products THEN the system SHALL filter products by a configurable tag
4. WHEN a matching product is found THEN the system SHALL check if it has a compare-at price
5. WHEN a product has a compare-at price THEN the system SHALL set the main price to the compare-at price value
6. WHEN setting the new price THEN the system SHALL remove the compare-at price (set to null)
7. WHEN a product has no compare-at price THEN the system SHALL skip the product and log a warning

Requirement 2

User Story: As a store administrator, I want to configure the rollback script through environment variables, so that I can easily specify which products to rollback without modifying code.

Acceptance Criteria

1. WHEN the rollback script starts THEN the system SHALL load Shopify API credentials from existing .env file
2. WHEN loading configuration THEN the system SHALL read the target product tag from environment variables
3. IF required environment variables are missing THEN the system SHALL display an error message and exit gracefully
4. WHEN the tag is specified THEN the system SHALL use it to filter products for rollback
5. WHEN no tag is specified THEN the system SHALL display an error and require tag specification

Requirement 3

User Story: As a store administrator, I want to see detailed feedback about the rollback process, so that I can verify the changes were applied correctly.

Acceptance Criteria

1. WHEN the rollback script starts THEN the system SHALL display the configuration being used
2. WHEN products are found THEN the system SHALL display the count of matching products
3. WHEN rolling back each product THEN the system SHALL log the product name, current price, compare-at price, and new price
4. WHEN a product is skipped THEN the system SHALL log the reason (no compare-at price)
5. WHEN all rollbacks are complete THEN the system SHALL display a summary of total products updated and skipped

Requirement 4

User Story: As a store administrator, I want the rollback script to handle errors gracefully, so that partial failures don't prevent other products from being rolled back.

Acceptance Criteria

1. WHEN API rate limits are encountered THEN the system SHALL implement appropriate retry logic
2. WHEN a product rollback fails THEN the system SHALL log the error and continue with remaining products
3. WHEN network errors occur THEN the system SHALL retry the operation with exponential backoff
4. WHEN invalid product data is encountered THEN the system SHALL skip the product and log a warning
5. WHEN the script completes THEN the system SHALL exit with appropriate status codes

Requirement 5

User Story: As a developer, I want the rollback script to reuse existing Shopify API infrastructure, so that I can maintain consistency and reduce code duplication.

Acceptance Criteria

1. WHEN implementing the rollback solution THEN the system SHALL use existing Shopify service components
2. WHEN querying products THEN the system SHALL use existing GraphQL query patterns
3. WHEN updating products THEN the system SHALL use existing GraphQL mutation infrastructure
4. WHEN handling API responses THEN the system SHALL reuse existing error handling patterns
5. WHEN managing API connections THEN the system SHALL use existing authentication and session management

Requirement 6

User Story: As a store administrator, I want the rollback script to validate data before making changes, so that I can avoid unintended price modifications.

Acceptance Criteria

1. WHEN processing a product THEN the system SHALL verify the product has variants with compare-at prices
2. WHEN a compare-at price exists THEN the system SHALL validate it is a positive number
3. WHEN rolling back prices THEN the system SHALL ensure the compare-at price is different from current price
4. WHEN a product variant has no compare-at price THEN the system SHALL skip that variant and log the reason
5. WHEN validation fails THEN the system SHALL skip the product and continue processing others

Requirement 7

User Story: As a developer, I want the rollback script to maintain a progress log, so that I can track what rollback operations have been completed and reference them later.

Acceptance Criteria

1. WHEN the rollback script starts THEN the system SHALL create or append to a Progress.md file
2. WHEN each product is processed THEN the system SHALL log the rollback operation details to Progress.md
3. WHEN the script completes THEN the system SHALL write a summary to Progress.md with timestamp
4. WHEN errors occur THEN the system SHALL log error details to Progress.md for debugging
5. WHEN the script runs multiple times THEN the system SHALL append new progress entries without overwriting previous runs

Requirement 8

User Story: As a store administrator, I want to run the rollback as an additional mode within the existing application, so that I can use both price updating and rollback functionality from the same tool.

Acceptance Criteria

1. WHEN running the application THEN the system SHALL support both price update and rollback modes
2. WHEN rollback mode is specified THEN the system SHALL perform rollback operations instead of price updates
3. WHEN logging progress THEN the system SHALL distinguish rollback entries from regular price update entries in the same Progress.md file
4. WHEN displaying console output THEN the system SHALL use clear messaging that indicates which operation mode is active
5. WHEN the rollback completes THEN the system SHALL provide a summary specific to rollback operations while maintaining compatibility with existing functionality

Requirement 9

User Story: As a store administrator, I want to choose between price update and rollback modes when running the application, so that I can perform both operations using the same tool and configuration.

Acceptance Criteria

1. WHEN starting the application THEN the system SHALL determine the operation mode based on configuration or command line parameters
2. WHEN price update mode is selected THEN the system SHALL perform the existing price adjustment functionality
3. WHEN rollback mode is selected THEN the system SHALL perform the rollback functionality
4. WHEN no mode is specified THEN the system SHALL default to price update mode for backward compatibility
5. WHEN either mode is executed THEN the system SHALL use the same environment configuration and Shopify API infrastructure