A web-based bill management and data analysis tool supporting multi-platform bill import, AI-powered data extraction, cross-year summary reports, batch processing, and visual analytics.

• 📦 Batch Processing: Process multiple ZIP archives and PDF files at once
• 🔐 Password Support: Handle password-protected ZIP files and PDFs
• 📊 Visual Analytics: Generate comprehensive HTML reports with interactive charts
• 📈 Data Visualization: Monthly trends, category breakdowns, merchant rankings
• 🎨 Export Options: Export to Excel and PNG images
• 🔍 Data Validation: Built-in data quality checks and validation
• 📝 Logging: Comprehensive logging for debugging and monitoring

• Python 3.11 or higher
• Chrome/Chromium browser (for PNG export, optional)

pip install -e .

pip install -e ".[dev]"

1. Create an input/ directory
2. Place your WeChat Pay bill ZIP files or PDFs in the directory
3. Run the analyzer:

python main.py

4. Find the results in the output/ directory:
   • Excel files (.xlsx)
   • HTML reports (.html)
   • Full-page PNG screenshots (optional)

bill-hub/
├── input/          # Place your ZIP/PDF files here
├── output/         # Generated reports will appear here
├── main.py         # Main entry point
├── utils.py        # Utility functions (ZIP, PDF parsing)
├── visualize.py    # Visualization and report generation
├── logger_config.py # Logging configuration
└── tests.py        # Unit tests

Run the test suite:

python tests.py

Or using pytest:

pytest

Run tests with coverage:

pytest --cov=.

The tool generates:

• Excel files: Transaction data in .xlsx format with proper datetime formatting
• HTML reports: Interactive visualizations including:
  • Financial summary dashboard
  • Monthly income/expense trends
  • Category breakdown (pie charts)
  • Top merchant rankings (bar charts)
  • Transaction time analysis
  • Merchant frequency analysis
• PNG screenshots: Full-page screenshots of reports (requires Chrome)

The tool uses Python's logging module. Default configuration outputs to console. You can customize logging by modifying logger_config.py.

The tool automatically validates transaction data and checks for:

• Empty datasets
• Missing required columns (交易时间, 金额(元))
• Null transaction dates
• Negative amounts

• Uses type hints throughout for better IDE support
• Comprehensive error handling
• Logging instead of print statements for better debugging

1. Add type hints to new functions
2. Include unit tests in tests.py
3. Update this README with new features
4. Ensure logging is used for debugging information

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

[Add your license here]

See PRD.md for detailed requirements and future features.