# Shopkeeper Vendor Sales Report

A Magento 2.4.x module that generates monthly vendor sales reports with automated email delivery.

## Features

- **Manual Report Generation**: Generate reports for any custom date range via admin interface
- **Preview Grid**: View report data before exporting
- **Automated Monthly Reports**: Automatic generation on the 1st of each month via cron
- **Email Delivery**: Automatically email reports with CSV attachment
- **Configurable**: 
  - Order status filtering
  - Email recipients
  - Email subject line
  - Email sender
- **State Abbreviation**: Automatically converts full state names to 2-letter codes
- **Cost Fallback**: Uses current product cost if order item cost is missing

## Installation

### Method 1: Manual Installation

1. **Upload the module files:**
   ```bash
   # From your Magento root directory
   mkdir -p app/code/Shopkeeper/VendorSalesReport
   # Upload all module files to app/code/Shopkeeper/VendorSalesReport/
   ```

2. **Enable the module:**
   ```bash
   php bin/magento module:enable Shopkeeper_VendorSalesReport
   php bin/magento setup:upgrade
   php bin/magento setup:di:compile
   php bin/magento setup:static-content:deploy -f
   php bin/magento cache:flush
   ```

3. **Set permissions (if needed):**
   ```bash
   chmod -R 755 app/code/Shopkeeper/
   ```

### Method 2: Composer Installation (if you package it)

```bash
composer require shopkeeper/module-vendor-sales-report
php bin/magento module:enable Shopkeeper_VendorSalesReport
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
```

## Configuration

### Admin Configuration Path
**Stores > Configuration > Shopkeeper > Vendor Sales Report**

### Settings

#### General Settings
- **Enable Automated Monthly Report**: Enable/disable automatic monthly report generation
- **Order Status Filter**: Select which order statuses to include (default: Complete)

#### Email Settings
- **Enable Email**: Enable/disable email delivery
- **Email Recipients**: Comma-separated list of email addresses
- **Email Subject**: Subject line for automated emails (use {{month}} and {{year}} placeholders for dynamic values)
- **Email Sender**: Choose which store email identity to use as sender

### Example Configuration

```
Enable Automated Monthly Report: Yes
Order Status Filter: complete
Enable Email: Yes
Email Recipients: vendor@example.com, admin@example.com
Email Subject: Monthly Thermo Report - {{month}} {{year}}
Email Sender: General Contact
```

## Usage

### Manual Report Generation

1. Go to **Reports > Sales > Vendor Sales Report**
2. Select date range using the date pickers
3. Click **Preview Report** to view data in a grid
4. Click **Export CSV** to download the report

The report will be downloaded as `FF_SAC_730_MCQUEEN.csv`

### Automated Monthly Reports

Once configured, the module will automatically:
1. Generate a report on the 1st of each month at 2:00 AM
2. Include all orders from the previous month
3. Email the report as a CSV attachment to configured recipients

### Report Format

The CSV file includes the following columns:

| Column | Description |
|--------|-------------|
| Date | Order date (MM/DD/YYYY format) |
| Vendor Product number | Product SKU |
| Description | Product name |
| Vendor code | (Empty - reserved for vendor use) |
| Vendor name | (Empty - reserved for vendor use) |
| Dealer product number | Order increment ID |
| Country | Shipping address country |
| City | Shipping address city |
| State | Shipping address state (abbreviated) |
| Zip code | Shipping address postal code |
| Quantity | Quantity ordered |
| Cost | Product cost (uses order item cost, falls back to current product cost if missing) |

## Cron Schedule

The automated report runs according to this schedule:
```
0 2 1 * *
```
Translation: At 2:00 AM on the 1st day of every month

To test the cron manually:
```bash
php bin/magento cron:run --group default
```

## Troubleshooting

### Reports not generating automatically

1. **Check if cron is enabled:**
   ```bash
   php bin/magento cron:run
   ```

2. **Check cron_schedule table:**
   ```sql
   SELECT * FROM cron_schedule 
   WHERE job_code = 'shopkeeper_vendorsalesreport_monthly' 
   ORDER BY scheduled_at DESC 
   LIMIT 10;
   ```

3. **Check module configuration:**
   - Ensure "Enable Automated Monthly Report" is set to Yes
   - Verify order status is configured

### Emails not sending

1. **Check email configuration:**
   - Verify email recipients are configured
   - Ensure "Enable Email" is set to Yes
   - Check Magento's email sending is working (test with other emails)

2. **Check logs:**
   ```bash
   tail -f var/log/system.log | grep "Vendor Sales Report"
   ```

### No data in report

1. **Check order status filter:**
   - Verify orders have the configured status (default: "complete")
   - Try including additional statuses like "processing"

2. **Verify date range:**
   - Ensure orders exist within the selected date range

### State abbreviations not working

- The module includes all US states, DC, and territories
- If international addresses appear, they'll show as-is (not abbreviated)
- Already abbreviated states (2 characters) are left unchanged

## Module Structure

```
Shopkeeper/VendorSalesReport/
├── Block/
│   └── Adminhtml/
│       └── Report.php
├── Controller/
│   └── Adminhtml/
│       └── Report/
│           ├── Export.php
│           ├── Grid.php
│           └── Index.php
├── Cron/
│   └── GenerateMonthlyReport.php
├── etc/
│   ├── acl.xml
│   ├── config.xml
│   ├── crontab.xml
│   ├── email_templates.xml
│   ├── module.xml
│   └── adminhtml/
│       ├── menu.xml
│       ├── routes.xml
│       └── system.xml
├── Helper/
│   └── Data.php
├── Model/
│   ├── EmailSender.php
│   └── ReportGenerator.php
├── view/
│   └── adminhtml/
│       ├── email/
│       │   └── report.html
│       ├── layout/
│       │   └── vendorsalesreport_report_index.xml
│       └── templates/
│           └── report/
│               └── view.phtml
└── registration.php
```

## Requirements

- Magento 2.4.x
- PHP 7.4 or higher
- MySQL 5.7 or higher

## Support

For issues or questions:
1. Check the troubleshooting section above
2. Review Magento logs: `var/log/system.log`
3. Verify module is enabled: `php bin/magento module:status`

## License

Proprietary - Shopkeeper

## Version

1.0.0

## Changelog

### Version 1.0.0
- Initial release
- Manual report generation with date range selector
- Preview grid functionality
- Automated monthly cron job
- Email delivery with CSV attachment
- Configurable order status filter
- State abbreviation support
- Cost fallback to current product cost