151 lines
4.9 KiB
Markdown
151 lines
4.9 KiB
Markdown
# Sales Analysis Template - Overview
|
|
|
|
**Start here for a high-level understanding of the template.**
|
|
|
|
For detailed setup, see `QUICK_START.md`. For complete documentation, see `README.md`.
|
|
|
|
## 🎯 Purpose
|
|
|
|
This template provides a **production-ready, reusable framework** for analyzing sales invoice detail data from any company. It's designed to be:
|
|
|
|
- **Flexible:** Works with different column names, date formats, and data structures
|
|
- **Automated:** Interactive setup wizard configures everything
|
|
- **AI-Optimized:** Fully optimized for Cursor AI - just ask and the AI generates complete analyses
|
|
- **Best-in-Class:** Based on proven patterns from 24+ production analyses
|
|
|
|
## 📦 What's Included
|
|
|
|
### Core Framework
|
|
- **`config.py`** - Centralized configuration (customize for your company)
|
|
- **`data_loader.py`** - Intelligent data loading with fallback logic
|
|
- **`analysis_utils.py`** - Common utilities (formatters, LTM, helpers)
|
|
- **`validate_revenue.py`** - Revenue validation utility
|
|
|
|
### Templates & Tools
|
|
- **`analysis_template.py`** - Template for creating new analyses
|
|
- **`run_all_analyses.py`** - Batch runner for all scripts
|
|
- **`setup_wizard.py`** - Interactive setup wizard
|
|
|
|
### Documentation
|
|
- **`README.md`** - Comprehensive documentation
|
|
- **`QUICK_START.md`** - Quick reference guide
|
|
- **`.cursor/rules/`** - Cursor IDE rules for automation
|
|
|
|
### Configuration
|
|
- **`requirements.txt`** - Python dependencies
|
|
- **`.gitignore`** - Git ignore patterns
|
|
|
|
## 🚀 Quick Start
|
|
|
|
1. **Run setup wizard:**
|
|
```bash
|
|
python setup_wizard.py
|
|
```
|
|
|
|
2. **Test data loading:**
|
|
```bash
|
|
python -c "from data_loader import load_sales_data; from config import get_data_path; df = load_sales_data(get_data_path()); print(f'✓ Loaded {len(df):,} rows')"
|
|
```
|
|
|
|
3. **Create your first analysis:**
|
|
```bash
|
|
cp analysis_template.py my_analysis.py
|
|
# Edit my_analysis.py
|
|
python my_analysis.py
|
|
```
|
|
|
|
## 🎨 Key Features
|
|
|
|
### 1. Flexible Data Loading
|
|
- Handles different column names via configuration
|
|
- Fallback logic for date parsing (100% coverage)
|
|
- Automatic validation
|
|
|
|
### 2. LTM Support
|
|
- Automatic Last Twelve Months calculation
|
|
- Apples-to-apples comparison with full years
|
|
- Configurable periods
|
|
|
|
### 3. Standardized Formatting
|
|
- Automatic millions formatter for revenue
|
|
- Consistent chart styling
|
|
- Professional output
|
|
|
|
### 4. Exclusion Filters
|
|
- Easy configuration for excluding segments
|
|
- Useful for test accounts, business units, etc.
|
|
|
|
### 5. AI Automation
|
|
- Comprehensive Cursor rules
|
|
- Automated agent assistance
|
|
- Best practices enforcement
|
|
|
|
## 📊 Analysis Types Supported
|
|
|
|
This template supports all standard sales analyses:
|
|
|
|
- **Revenue:** Annual trends, monthly analysis, by segment
|
|
- **Customer:** Segmentation, concentration, churn, CLV
|
|
- **Product:** Performance, lifecycle, BCG matrix
|
|
- **Financial:** Price elasticity, margins
|
|
- **Advanced:** Seasonality, forecasting, predictions
|
|
|
|
## 🔧 Customization Points
|
|
|
|
All customization happens in `config.py`:
|
|
|
|
1. **Company Info:** Name, analysis date
|
|
2. **Data File:** Location, filename
|
|
3. **Column Mappings:** Revenue, date, customer, product, etc.
|
|
4. **Date Range:** Years, LTM configuration
|
|
5. **Filters:** Exclusion rules
|
|
6. **Chart Settings:** Sizes, styles, DPI
|
|
|
|
## 📚 Documentation Structure
|
|
|
|
- **`README.md`** - Complete guide (start here)
|
|
- **`QUICK_START.md`** - Quick start (includes Cursor tips)
|
|
- **`EXAMPLES.md`** - Example scripts guide
|
|
- **`TEMPLATE_SUMMARY.md`** - Comprehensive template overview
|
|
- **`.cursor/rules/`** - Detailed patterns for AI agents (auto-loaded by Cursor)
|
|
- **`config.py`** - Heavily commented configuration
|
|
|
|
## 🎓 Learning Path
|
|
|
|
1. **Read:** `QUICK_START.md` (5 minutes)
|
|
2. **Run:** `setup_wizard.py` (2 minutes)
|
|
3. **Test:** Data loading (1 minute)
|
|
4. **Create:** First analysis using `analysis_template.py` (15 minutes)
|
|
5. **Explore:** `.cursor/rules/` for patterns (as needed)
|
|
|
|
## 💡 Best Practices
|
|
|
|
1. **Always use utilities** - Don't reinvent the wheel
|
|
2. **Use config values** - Never hardcode column names
|
|
3. **Validate data** - After loading and after analysis
|
|
4. **Follow patterns** - See `.cursor/rules/analysis_patterns.md`
|
|
5. **Test incrementally** - Test data loading before full analysis
|
|
|
|
## 🔍 What Makes This "Best-in-Class"
|
|
|
|
1. **Proven Patterns:** Based on 24+ production analyses
|
|
2. **Flexibility:** Works with any data structure
|
|
3. **Automation:** Setup wizard + AI-friendly rules
|
|
4. **Documentation:** Comprehensive guides and examples
|
|
5. **Error Handling:** Validation and troubleshooting built-in
|
|
6. **Consistency:** Standardized formatting and patterns
|
|
|
|
## 📈 Next Steps
|
|
|
|
1. Run `setup_wizard.py` to configure for your company
|
|
2. Review `config.py` to understand all options
|
|
3. Create your first analysis using `analysis_template.py`
|
|
4. Explore `.cursor/rules/` for detailed patterns
|
|
5. Build your analysis suite
|
|
|
|
---
|
|
|
|
**Template Version:** 1.0
|
|
**Last Updated:** January 2026
|
|
**Status:** Production Ready
|