Initial commit: sales analysis template

Co-authored-by: Cursor <cursoragent@cursor.com>

QUICK_START.md

@@ -0,0 +1,175 @@
+# Quick Start Guide
+
+**For Cursor Users:** This template is optimized for Cursor AI. Just ask: *"Create a revenue analysis using the template"* and the AI will handle everything.
+
+## 🚀 Get Started in 5 Minutes
+
+### Step 1: Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### Step 2: Run Setup Wizard
+```bash
+python setup_wizard.py
+```
+
+The wizard will ask you:
+- Company name
+- Data file location
+- Column names in your CSV
+- Date range
+- LTM configuration (if needed)
+
+### Step 3: 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')"
+```
+
+### Step 4: Run Example Analysis (Recommended)
+```bash
+# Try an example first to see how it works
+python examples/annual_revenue_trend.py
+```
+
+### Step 5: Create Your First Analysis
+```bash
+cp analysis_template.py my_analysis.py
+# Or copy an example
+cp examples/annual_revenue_trend.py my_analysis.py
+# Edit my_analysis.py
+python my_analysis.py
+```
+
+---
+
+## 📋 Essential Configuration Checklist
+
+Before running analyses, verify in `config.py`:
+
+- [ ] `COMPANY_NAME` - Your company name
+- [ ] `DATA_FILE` - Your CSV filename
+- [ ] `REVENUE_COLUMN` - Your revenue column name
+- [ ] `DATE_COLUMN` - Your date column name
+- [ ] `CUSTOMER_COLUMN` - Your customer column name
+- [ ] `ANALYSIS_YEARS` - Years to include
+- [ ] `MIN_YEAR` and `MAX_DATE` - Date range
+- [ ] `LTM_ENABLED` - Set to False if all years complete
+
+---
+
+## 💡 Common Patterns
+
+### Load Data
+```python
+from data_loader import load_sales_data
+from config import get_data_path
+
+df = load_sales_data(get_data_path())
+```
+
+### Calculate Annual Metrics
+```python
+from analysis_utils import calculate_annual_metrics, get_ltm_period_config
+from config import REVENUE_COLUMN
+
+ltm_start, ltm_end = get_ltm_period_config()
+
+def calculate_metrics(year_data):
+    return {'Revenue': year_data[REVENUE_COLUMN].sum()}
+
+annual_df = calculate_annual_metrics(df, calculate_metrics, ltm_start, ltm_end)
+```
+
+### Create Chart
+```python
+from analysis_utils import setup_revenue_chart, save_chart
+from config import CHART_SIZES
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots(figsize=CHART_SIZES['medium'])
+ax.plot(data / 1e6, ...)  # Divide by 1e6!
+setup_revenue_chart(ax)
+save_chart(fig, 'chart.png')
+plt.close()
+```
+
+---
+
+## ⚠️ Critical Rules
+
+1. **ALWAYS use `data_loader.py`** - Never `pd.read_csv()` directly
+2. **ALWAYS divide by 1e6** before plotting revenue
+3. **ALWAYS use `setup_revenue_chart()`** for revenue charts
+4. **ALWAYS use config values** - Never hardcode column names
+5. **ALWAYS validate data** after loading
+
+## 💡 New Utilities
+
+### Data Quality Check
+```bash
+python -c "from data_quality import generate_data_quality_report, print_data_quality_report; from data_loader import load_sales_data; from config import get_data_path; df = load_sales_data(get_data_path()); report = generate_data_quality_report(df); print_data_quality_report(report)"
+```
+
+### Configuration Validation
+```bash
+python config_validator.py
+```
+
+### Export Results
+```python
+from export_utils import export_to_excel
+export_to_excel(df, 'results.xlsx')
+```
+
+### Generate Sample Data
+```bash
+python generate_sample_data.py
+```
+
+---
+
+## 🐛 Quick Troubleshooting
+
+**"Data file not found"**
+→ Check `DATA_FILE` in config.py
+
+**"Column not found"**
+→ Update column mappings in config.py
+
+**Charts show 1e8 (scientific notation)**
+→ Divide by 1e6 before plotting: `ax.plot(data / 1e6, ...)`
+
+**"DataFrame is empty"**
+→ Check `MIN_YEAR`, `MAX_DATE`, and `ANALYSIS_YEARS` in config.py
+
+---
+
+## 🎯 Using Cursor AI (Recommended)
+
+This template is optimized for Cursor. Instead of manual setup, just ask:
+
+```
+"Create a revenue trend analysis using template patterns"
+```
+
+The AI will:
+- ✅ Use all template utilities automatically
+- ✅ Follow best practices
+- ✅ Include proper validation
+- ✅ Generate production-ready code
+
+**See:** `.cursor/rules/ai_assistant_guide.md` for complete prompt library
+
+## 📚 Next Steps
+
+- **Run examples:** Try `examples/annual_revenue_trend.py` to see it in action
+- **Check data quality:** Run `python data_quality.py` to analyze your data
+- **Validate config:** Run `python config_validator.py` to check configuration
+- **Read documentation:** See `README.md` for comprehensive guide
+- **Review patterns:** Check `.cursor/rules/` for detailed patterns
+- **See examples:** Check `EXAMPLES.md` for example script guide
+
+---
+
+**Need help?** Check `.cursor/rules/common_errors.md` for detailed troubleshooting.