Add comprehensive README with setup and usage instructions
This commit is contained in:
parent
8f217a87c2
commit
f294ac155e
270
README.md
Normal file
270
README.md
Normal file
@ -0,0 +1,270 @@
|
|||||||
|
# Vendor Report Generator
|
||||||
|
|
||||||
|
A Python tool that generates comprehensive vendor punchlist reports from Excel files. The tool processes Excel data, normalizes vendor information, calculates metrics, and generates both JSON and interactive HTML reports.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Direct Excel Processing**: Reads Excel files directly using pandas (no LLM required)
|
||||||
|
- **Data Normalization**: Automatically normalizes vendor names, statuses, and priorities
|
||||||
|
- **24-Hour Updates**: Tracks items added, closed, or changed to monitor status in the last 24 hours (based on Baltimore/Eastern timezone)
|
||||||
|
- **Priority Tracking**: Groups items by priority levels (Very High, High, Medium, Low)
|
||||||
|
- **Oldest Unaddressed Items**: Identifies and highlights the oldest 3 unaddressed items per vendor
|
||||||
|
- **Interactive HTML Reports**: Generates searchable, filterable HTML reports with tabs and filters
|
||||||
|
- **JSON Export**: Exports structured JSON data for further processing
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Python 3.8 or higher
|
||||||
|
- Dependencies listed in `requirements.txt`
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
1. **Clone the repository**:
|
||||||
|
```bash
|
||||||
|
git clone https://gitea.lci.ge/ilia.gurielidze/vendor_report.git
|
||||||
|
cd vendor_report
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Create a virtual environment** (recommended):
|
||||||
|
```bash
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Install dependencies**:
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
1. **Prepare your Excel files**:
|
||||||
|
- Place your Excel files (`.xlsx` or `.xls`) in the `reports/` directory
|
||||||
|
- Ensure your Excel files have the following columns (in order):
|
||||||
|
- Column 0: Punchlist Name
|
||||||
|
- Column 1: Vendor
|
||||||
|
- Column 2: Priority
|
||||||
|
- Column 3: Description
|
||||||
|
- Column 4: Date Identified
|
||||||
|
- Column 5: Status Updates
|
||||||
|
- Column 6: Issue Image
|
||||||
|
- Column 7: Status
|
||||||
|
- Column 8: Date Completed (optional)
|
||||||
|
|
||||||
|
2. **Create necessary directories** (if they don't exist):
|
||||||
|
```bash
|
||||||
|
mkdir -p reports output
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
Generate a report from Excel files in the `reports/` directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 report_generator.py
|
||||||
|
```
|
||||||
|
|
||||||
|
This will:
|
||||||
|
- Process all Excel files in the `reports/` directory
|
||||||
|
- Generate a JSON report at `output/report.json`
|
||||||
|
- Generate an HTML report at `output/report.html`
|
||||||
|
- Save preprocessed data to `output/preprocessed_data.txt`
|
||||||
|
|
||||||
|
### Command-Line Options
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 report_generator.py [OPTIONS]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Options**:
|
||||||
|
- `--reports-dir DIR`: Directory containing Excel files (default: `reports`)
|
||||||
|
- `--output FILE`: Output JSON file path (default: `output/report.json`)
|
||||||
|
- `--verbose`: Print verbose output (default: True)
|
||||||
|
|
||||||
|
**Examples**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Use a custom reports directory
|
||||||
|
python3 report_generator.py --reports-dir /path/to/excel/files
|
||||||
|
|
||||||
|
# Specify custom output file
|
||||||
|
python3 report_generator.py --output /path/to/output/report.json
|
||||||
|
|
||||||
|
# Combine options
|
||||||
|
python3 report_generator.py --reports-dir my_reports --output my_output/report.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Programmatic Usage
|
||||||
|
|
||||||
|
You can also use the report generator in your own Python scripts:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from report_generator import generate_report
|
||||||
|
|
||||||
|
# Generate report with default settings
|
||||||
|
report_data = generate_report()
|
||||||
|
|
||||||
|
# Or with custom settings
|
||||||
|
report_data = generate_report(
|
||||||
|
reports_dir="my_reports",
|
||||||
|
output_file="my_output/report.json",
|
||||||
|
verbose=True
|
||||||
|
)
|
||||||
|
|
||||||
|
# report_data is a dictionary containing the full report structure
|
||||||
|
print(f"Processed {len(report_data['vendors'])} vendors")
|
||||||
|
```
|
||||||
|
|
||||||
|
## Report Structure
|
||||||
|
|
||||||
|
### JSON Report Structure
|
||||||
|
|
||||||
|
The generated JSON report follows this structure:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"report_generated_at": "2025-11-05T22:00:00",
|
||||||
|
"vendors": [
|
||||||
|
{
|
||||||
|
"vendor_name": "VendorName",
|
||||||
|
"total_items": 10,
|
||||||
|
"closed_count": 5,
|
||||||
|
"open_count": 3,
|
||||||
|
"monitor_count": 2,
|
||||||
|
"updates_24h": {
|
||||||
|
"added": [...],
|
||||||
|
"closed": [...],
|
||||||
|
"changed_to_monitor": [...]
|
||||||
|
},
|
||||||
|
"oldest_unaddressed": [...],
|
||||||
|
"very_high_priority_items": [...],
|
||||||
|
"high_priority_items": [...],
|
||||||
|
"closed_items": [...],
|
||||||
|
"monitor_items": [...],
|
||||||
|
"open_items": [...]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"summary": {
|
||||||
|
"total_vendors": 5,
|
||||||
|
"total_items": 50,
|
||||||
|
"total_closed": 25,
|
||||||
|
"total_open": 15,
|
||||||
|
"total_monitor": 10
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### HTML Report Features
|
||||||
|
|
||||||
|
The HTML report includes:
|
||||||
|
|
||||||
|
- **Summary Cards**: Overview statistics at the top
|
||||||
|
- **Vendor Tabs**: Quick navigation between vendors
|
||||||
|
- **Status Tabs**: Filter by status (All, Yesterday's Updates, Oldest Unaddressed, Closed, Monitor, Open)
|
||||||
|
- **Search & Filters**:
|
||||||
|
- Search by item name or description
|
||||||
|
- Filter by vendor, status, or priority
|
||||||
|
- **Quick Filters**:
|
||||||
|
- Show only vendors with yesterday's updates
|
||||||
|
- Show only vendors with oldest unaddressed items
|
||||||
|
- Show all vendors
|
||||||
|
- **Interactive Elements**: Click tabs to switch views, use filters to narrow down results
|
||||||
|
|
||||||
|
## Data Processing Details
|
||||||
|
|
||||||
|
### Vendor Name Normalization
|
||||||
|
|
||||||
|
The tool automatically normalizes vendor names:
|
||||||
|
- Handles case variations (e.g., "autstand" → "Autstand")
|
||||||
|
- Preserves intentional capitalization (e.g., "AutStand" stays as-is)
|
||||||
|
- Normalizes combined vendors (e.g., "Autstand/Beumer")
|
||||||
|
- Handles vendors in parentheses (e.g., "MFO (Amazon)")
|
||||||
|
|
||||||
|
### Status Normalization
|
||||||
|
|
||||||
|
Statuses are normalized to:
|
||||||
|
- **Complete**: Items with status containing "complete" or "complette"
|
||||||
|
- **Monitor**: Items with status containing "monitor" or "montor"
|
||||||
|
- **Incomplete**: All other items (default)
|
||||||
|
|
||||||
|
### Priority Classification
|
||||||
|
|
||||||
|
Priorities are classified as:
|
||||||
|
- **Very High**: Priority contains "(1) Very High" or "Very High"
|
||||||
|
- **High**: Priority contains "(2) High" or "High" (but not "Very High")
|
||||||
|
- **Medium**: Priority contains "(3) Medium" or "Medium"
|
||||||
|
- **Low**: Priority contains "(4) Low" or "Low"
|
||||||
|
|
||||||
|
### 24-Hour Window Calculation
|
||||||
|
|
||||||
|
The tool uses **Baltimore/Eastern timezone (America/New_York)** for calculating 24-hour updates:
|
||||||
|
- Items are considered "added in last 24h" if their `date_identified` falls on yesterday's date
|
||||||
|
- Items are considered "closed in last 24h" if their `date_completed` falls on yesterday's date
|
||||||
|
- Items are considered "changed to monitor" if their status is Monitor and the date falls within the 24-hour window
|
||||||
|
|
||||||
|
## Output Files
|
||||||
|
|
||||||
|
After running the generator, you'll find:
|
||||||
|
|
||||||
|
- `output/report.json`: Structured JSON report data
|
||||||
|
- `output/report.html`: Interactive HTML report (open in browser)
|
||||||
|
- `output/preprocessed_data.txt`: Human-readable preprocessed data (for debugging)
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
vendor_report/
|
||||||
|
├── report_generator.py # Main report generation script
|
||||||
|
├── data_preprocessor.py # Excel data preprocessing and normalization
|
||||||
|
├── html_generator.py # HTML report generation
|
||||||
|
├── models.py # Pydantic data models
|
||||||
|
├── excel_to_text.py # Utility for Excel to text conversion
|
||||||
|
├── requirements.txt # Python dependencies
|
||||||
|
├── reports/ # Directory for input Excel files
|
||||||
|
├── output/ # Directory for generated reports
|
||||||
|
└── README.md # This file
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### No Excel files found
|
||||||
|
|
||||||
|
Ensure your Excel files are in the `reports/` directory and have `.xlsx` or `.xls` extensions.
|
||||||
|
|
||||||
|
### Date parsing errors
|
||||||
|
|
||||||
|
The tool supports common date formats:
|
||||||
|
- `MM/DD/YY` (e.g., `10/14/25`)
|
||||||
|
- `MM/DD/YYYY` (e.g., `10/14/2025`)
|
||||||
|
- `YYYY-MM-DD` (e.g., `2025-10-17`)
|
||||||
|
- `YYYY-MM-DD HH:MM:SS` (e.g., `2025-10-17 00:00:00`)
|
||||||
|
|
||||||
|
### Permission errors
|
||||||
|
|
||||||
|
If you encounter permission errors, ensure you have write access to the `output/` directory.
|
||||||
|
|
||||||
|
### Missing dependencies
|
||||||
|
|
||||||
|
If you get import errors, ensure all dependencies are installed:
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## Timezone Notes
|
||||||
|
|
||||||
|
The tool uses **Baltimore/Eastern timezone (America/New_York)** for all date calculations. This ensures consistent 24-hour window calculations regardless of where the script is run. All dates are stored as timezone-aware datetime objects.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
[Add your license information here]
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
[Add contribution guidelines if applicable]
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
For issues or questions, please contact [your contact information or issue tracker URL].
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user