Generate State Workflow

# Generate State Documentation

## Overview

**User Code:** `com.finmars.standard-workflow:generate-state`

This script is designed to generate state files for state managers. It processes input data to create a structured state file that includes information about workers and their respective states.

## Workflow Function

The main `workflow` function is a task that generates the state file based on the provided payload.

### Parameters:
- `payload`: A dictionary containing the necessary information for state generation.

### Process:
1. Validates the presence of a payload
2. Retrieves the input data from the specified path
3. Generates a new state file using the `generate_state_file` function
4. Saves the generated state file
5. Updates the status of the operation in the state file

## State File Generation

The `generate_state_file` function creates the structure of the state file.

### State File Structure:
```json
{
  "user_code": "string",
  "configuration_code": "string",
  "name": "string",
  "status": "string",
  "schedule": "object",
  "workers": [
    {
      "order": "integer",
      "configuration_code": "string",
      "name": "string",
      "user_code": "string",
      "status": "string",
      "state_type": "string",
      "data_options": "object",
      "import_options": "object",
      "calculation_options": "object",
      "download_options": "object",
      "state_options": "object",
      "state": "object"
    }
  ]
}
```

### Worker State Types:

1. **Fixed**: A single state for the worker.
2. **Files**: Multiple states based on files in a specified directory.
3. **Period**: Multiple states based on date ranges and portfolios.

## Field Values

### General Fields:
- `status`: "to-do", "in-progress", "done", "error"
- `state_type`: "fixed", "files", "period"

### Period-specific Fields:
- `periodicity`: "daily", "weekly", "monthly"
- `date_from`: A date string ("YYYY-MM-DD") or "first_transaction_date"
- `date_to`: A date string ("YYYY-MM-DD") or "now"

### Download Options:
- `type`: "day" or other (assumed to be a period)

## Helper Functions

1. `get_first_transaction_date`: Retrieves the earliest transaction date from the API.
2. `get_next_date`: Calculates the next date based on the given periodicity.
3. `get_period_end_date`: Calculates the end date of a period based on the start date and periodicity.
4. `build_url`: Constructs the full API URL for a given endpoint.
5. `get_headers`: Generates headers with authorization token for HTTP requests.
6. `log_message`: Logs a message with a timestamp.
7. `save_file`: Saves data to a specified file path in JSON format.
8. `get_files`: Lists files in the specified directory.
9. `get_folders`: Lists directories in the specified path.
10. `get_data`: Reads data from a JSON file.

## Error Handling

The script includes error handling for various scenarios, such as missing payloads, file read/write errors, and API communication issues. Errors are logged and, where appropriate, propagated to the state file.

## Notes

- The script uses the `finmars` module for storage operations and API communication.
- Date handling is done using the `pandas` library for consistency and ease of manipulation.
- The script is designed to be flexible, handling different worker state types and periodicities.