255 lines
6.8 KiB
Markdown
255 lines
6.8 KiB
Markdown
# 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 (supports {{month}} and {{year}} placeholders)
|
|
- **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
|