Spencer Grimes
1e6881ba86
- Full Node.js application with Shopify GraphQL API integration - Compare At price support for promotional pricing - Comprehensive error handling and retry logic - Progress tracking with markdown logging - Complete test suite with unit and integration tests - Production-ready with proper exit codes and signal handling
95 lines
5.7 KiB
Markdown
95 lines
5.7 KiB
Markdown
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
This feature involves creating a Node.js script that connects to Shopify's GraphQL API to update product prices based on specific criteria. The script will filter products by a preset tag and adjust their prices by a configurable percentage (either increase or decrease). The solution will use Shopify's official Node.js API package and store configuration in environment variables for security and flexibility.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1
|
|
|
|
**User Story:** As a store administrator, I want to bulk update product prices for products with specific tags, so that I can efficiently manage pricing across my inventory.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the script is executed THEN the system SHALL connect to Shopify using GraphQL API
|
|
2. WHEN connecting to Shopify THEN the system SHALL authenticate using 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 update its price by the specified percentage
|
|
5. WHEN updating prices THEN the system SHALL support both price increases and decreases based on percentage value
|
|
6. WHEN updating a product price THEN the system SHALL set the original price as the "Compare At" price
|
|
7. WHEN the original price exists THEN the system SHALL preserve it as the Compare At price before applying the adjustment
|
|
|
|
### Requirement 2
|
|
|
|
**User Story:** As a store administrator, I want to configure the script through environment variables, so that I can easily change settings without modifying code.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the script starts THEN the system SHALL load Shopify API credentials from .env file
|
|
2. WHEN loading configuration THEN the system SHALL read the target product tag from environment variables
|
|
3. WHEN loading configuration THEN the system SHALL read the price adjustment percentage from environment variables
|
|
4. IF required environment variables are missing THEN the system SHALL display an error message and exit gracefully
|
|
5. WHEN percentage is positive THEN the system SHALL increase prices
|
|
6. WHEN percentage is negative THEN the system SHALL decrease prices
|
|
|
|
### Requirement 3
|
|
|
|
**User Story:** As a store administrator, I want to see detailed feedback about the price update process, so that I can verify the changes were applied correctly.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the 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 updating each product THEN the system SHALL log the product name, old price, new price, and Compare At price
|
|
4. WHEN all updates are complete THEN the system SHALL display a summary of total products updated
|
|
5. IF errors occur during updates THEN the system SHALL log error details and continue processing other products
|
|
|
|
### Requirement 4
|
|
|
|
**User Story:** As a store administrator, I want the script to handle errors gracefully, so that partial failures don't prevent other products from being updated.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN API rate limits are encountered THEN the system SHALL implement appropriate retry logic
|
|
2. WHEN a product update 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 script to use Shopify's official Node.js package and GraphQL API, so that I can leverage well-maintained and efficient tools.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN implementing the solution THEN the system SHALL use Shopify's official Node.js API package
|
|
2. WHEN querying products THEN the system SHALL use GraphQL queries for efficient data retrieval
|
|
3. WHEN updating products THEN the system SHALL use GraphQL mutations for price updates
|
|
4. WHEN handling API responses THEN the system SHALL properly parse GraphQL response structures
|
|
5. WHEN managing API connections THEN the system SHALL follow Shopify's best practices for authentication and session management
|
|
|
|
### Requirement 6
|
|
|
|
**User Story:** As a store administrator, I want the script to set Compare At prices to show customers the original price before adjustment, so that I can create effective promotional pricing displays.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN a product price is being updated THEN the system SHALL capture the current price as the Compare At price
|
|
2. WHEN the Compare At price is set THEN the system SHALL use the original price value before any percentage adjustment
|
|
3. WHEN updating product variants THEN the system SHALL set both the new price and Compare At price in the same operation
|
|
4. WHEN a product already has a Compare At price THEN the system SHALL replace it with the current price before adjustment
|
|
5. WHEN logging price updates THEN the system SHALL include the Compare At price in the progress tracking
|
|
|
|
### Requirement 7
|
|
|
|
**User Story:** As a developer, I want the script to maintain a progress log, so that I can track what operations have been completed and reference them later.
|
|
|
|
#### Acceptance Criteria
|
|
|
|
1. WHEN the 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 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
|