Initial commit: Vendor Sales Report Magento 2 module
This commit is contained in:
shopkeeperdev
254
README.md
Normal file
254
README.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user