auto-claude: subtask-4-2 - Ensure README is developer-friendly

2026-01-10 09:53:49 +01:00 · 2026-01-10 09:53:49 +01:00 · eefda67411
commit eefda67411
parent 9258928e53
1 changed files with 566 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -6,6 +6,63 @@
 **🌐 URL:** https://nordabiznes.pl
 **📊 Coverage:** 80 member companies (100% of Norda Biznes membership)

+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Technology Stack](#technology-stack)
+- [Project Structure](#project-structure)
+- [Development Environment Setup](#development-environment-setup)
+- [Testing & Quality Assurance](#testing--quality-assurance)
+- [Deployment & Production](#deployment--production)
+- [API Documentation](#api-documentation)
+- [Common Commands Reference](#common-commands-reference)
+- [Contributing](#contributing)
+- [Troubleshooting](#troubleshooting)
+- [Resources & Documentation](#resources--documentation)
+- [Contact](#dane-kontaktowe-norda-biznes)
+
+---
+
+## Quick Start
+
+**For experienced developers who want to get running immediately:**
+
+```bash
+# 1. Clone and setup
+git clone https://github.com/pienczyn/nordabiz.git
+cd nordabiz
+python3 -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+
+# 2. Start PostgreSQL (Docker)
+docker compose up -d
+
+# 3. Initialize database
+docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql
+
+# 4. Configure environment
+cp .env.example .env
+# Edit .env and add your API keys (see Development Environment Setup for details)
+
+# 5. Run the application
+python3 app.py
+
+# 6. Open http://localhost:5000
+```
+
+**Required API Keys:**
+- **Google Gemini API** (for AI chat): https://ai.google.dev/ - Free tier: 200 req/day
+- **Google PageSpeed Insights** (for SEO audits): https://developers.google.com/speed/docs/insights/v5/get-started - Free tier: 25,000 req/day
+- **Google Places API** (for GBP audits): https://console.cloud.google.com/apis/credentials - Free tier: $200/month credit
+
+For detailed setup instructions, see [Development Environment Setup](#development-environment-setup).
+
+---
+
 ## Overview

 Norda Biznes Hub is a **Flask-powered web platform** built with PostgreSQL, featuring AI-driven search capabilities, comprehensive company profiles, and administrative tools for managing member data. The platform integrates Google Gemini AI for intelligent company recommendations, automated news monitoring via Brave Search API, and comprehensive SEO/social media auditing tools.
@ -1223,6 +1280,515 @@ For detailed information about specific features:
 - **Database Schema:** See `database/schema.sql` and `database.py`
 - **External APIs:** See `CLAUDE.md` for integration details

+## Common Commands Reference
+
+Quick reference for frequently used development, testing, and deployment commands.
+
+### Development Commands
+
+```bash
+# Start development environment
+source venv/bin/activate              # Activate virtual environment
+docker compose up -d                  # Start PostgreSQL container
+python3 app.py                        # Run Flask development server
+
+# Stop development environment
+docker compose down                   # Stop PostgreSQL container
+deactivate                            # Deactivate virtual environment
+```
+
+### Database Commands
+
+```bash
+# Database management
+docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql  # Apply schema
+psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "\dt"                          # List tables
+psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "SELECT COUNT(*) FROM companies;"  # Count companies
+
+# Database reset (⚠️ WARNING: Deletes all data!)
+docker compose down -v                # Remove volumes
+docker compose up -d                  # Recreate database
+docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql  # Reapply schema
+```
+
+### Testing Commands
+
+```bash
+# Run AI quality tests
+python run_ai_quality_tests.py         # Standard output
+python run_ai_quality_tests.py -v      # Verbose mode
+python run_ai_quality_tests.py -v -s   # Verbose + save results
+python run_ai_quality_tests.py -q      # Quick (high-priority only)
+
+# Run unit tests
+python -m pytest tests/                            # All tests
+python -m pytest tests/test_admin_seo_dashboard.py # Specific test
+python -m pytest tests/ -v                         # Verbose output
+python -m pytest tests/ --cov=.                    # With coverage
+
+# Data verification
+python verify_all_companies_data.py    # Check data quality
+```
+
+### Git & Deployment Commands
+
+```bash
+# Development: Push to both remotes
+git push origin master && git push inpi master
+
+# Production: Deploy to server
+ssh maciejpi@10.22.68.249
+cd /var/www/nordabiznes
+sudo -u www-data git pull
+sudo systemctl restart nordabiznes
+curl -I https://nordabiznes.pl/health  # Verify deployment
+```
+
+### Production Service Management
+
+```bash
+# Service control (on production server)
+sudo systemctl status nordabiznes      # Check status
+sudo systemctl restart nordabiznes     # Restart service
+sudo systemctl start nordabiznes       # Start service
+sudo systemctl stop nordabiznes        # Stop service
+
+# View logs
+sudo journalctl -u nordabiznes -f      # Follow logs (live)
+sudo journalctl -u nordabiznes -n 100  # Last 100 entries
+```
+
+### Health & Monitoring Commands
+
+```bash
+# Check application health
+curl http://localhost:5000/health                    # Local
+curl -I https://nordabiznes.pl/health                # Production
+
+# Test API endpoints
+curl http://localhost:5000/api/companies | jq '.total'          # Count companies
+curl http://localhost:5000/api/model-info | jq '.model_name'    # Check AI model
+
+# Check database connectivity
+psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "SELECT 1;"  # Development
+psql -U nordabiz_app -d nordabiz -h localhost -c "SELECT 1;"          # Production
+```
+
+### Audit Scripts
+
+```bash
+# Run audit scripts
+cd scripts/
+python seo_audit.py --company-id 26                    # Single company SEO audit
+python seo_audit.py --batch 1-10                       # Batch SEO audit
+python social_media_audit.py --company-id 26           # Social media audit
+```
+
+### Pre-Deployment Checklist Commands
+
+```bash
+# Before deployment, run these checks:
+python -m py_compile app.py                            # Syntax check
+python run_ai_quality_tests.py -v                      # AI quality (≥70%)
+python -m pytest tests/ -v                             # Unit tests
+python verify_all_companies_data.py                    # Data integrity
+curl http://localhost:5000/health                      # Health check
+```
+
+For more detailed command documentation, see [`CLAUDE.md`](CLAUDE.md) and [`deployment_checklist.md`](deployment_checklist.md).
+
+## Contributing
+
+We welcome contributions to improve the Norda Biznes Hub platform! Here's how you can help.
+
+### Development Workflow
+
+1. **Fork and clone** the repository
+2. **Create a feature branch**: `git checkout -b feature/your-feature-name`
+3. **Make your changes** following our code conventions (see below)
+4. **Test thoroughly**:
+   - Run AI quality tests: `python run_ai_quality_tests.py -v`
+   - Run unit tests: `python -m pytest tests/ -v`
+   - Verify manually in browser
+5. **Commit your changes**: Use clear, descriptive commit messages
+6. **Push to your fork**: `git push origin feature/your-feature-name`
+7. **Create a Pull Request** with detailed description of changes
+
+### Code Conventions
+
+**Python Code:**
+- Follow **PEP 8** style guide
+- Use **4 spaces** for indentation (no tabs)
+- **Type hints** where appropriate
+- **Docstrings** for all functions and classes
+- **No print statements** in production code (use `app.logger`)
+
+**Jinja2 Templates:**
+- **IMPORTANT**: The `{% block extra_js %}` in `base.html` is already inside a `<script>` tag
+- **DO NOT** add your own `<script>` tags inside `extra_js` blocks (causes nesting errors)
+- Correct: `{% block extra_js %}function foo() {...}{% endblock %}`
+- Wrong: `{% block extra_js %}<script>function foo() {...}</script>{% endblock %}`
+
+**Database Changes:**
+- **Never edit production database directly**
+- **Always test on development database** (Docker on port 5433) first
+- **Create migration scripts** for schema changes in `database/migrations/`
+- **Grant permissions** after creating new tables/sequences:
+  ```sql
+  GRANT ALL ON TABLE table_name TO nordabiz_app;
+  GRANT USAGE, SELECT ON SEQUENCE sequence_name TO nordabiz_app;
+  ```
+
+**Git Commits:**
+- Use **descriptive commit messages**
+- Format: `"category: brief description"` (e.g., `"fix: Correct SEO scoring algorithm"`)
+- Reference issue numbers when applicable: `"feat: Add GBP audit dashboard (#123)"`
+
+### Testing Requirements
+
+All contributions must include appropriate tests:
+
+- **New features**: Add AI quality test cases to `tests/ai_quality_test_cases.json` if AI-related
+- **Bug fixes**: Add regression tests to prevent future occurrences
+- **API changes**: Update API documentation in README.md
+- **All tests must pass** before PR can be merged (≥70% AI quality threshold)
+
+### Code Review Process
+
+1. All pull requests require review before merging
+2. Automated checks must pass (syntax, tests)
+3. Maintainers will review code for:
+   - Code quality and conventions
+   - Test coverage
+   - Documentation updates
+   - Security considerations
+4. Address review feedback promptly
+5. Once approved, maintainers will merge
+
+### Documentation
+
+When adding or modifying features:
+
+- **Update README.md** if user-facing changes
+- **Update CLAUDE.md** if architectural changes
+- **Add inline code comments** for complex logic
+- **Update API documentation** if endpoints change
+- **Update deployment_checklist.md** if deployment process changes
+
+### Questions or Need Help?
+
+- Check [`CLAUDE.md`](CLAUDE.md) for comprehensive project documentation
+- Review existing issues and pull requests
+- Contact: biuro@norda-biznes.info
+
+## Troubleshooting
+
+Comprehensive troubleshooting guide for common issues.
+
+### Development Environment Issues
+
+#### Database Connection Errors
+
+**Problem:** Cannot connect to PostgreSQL database
+
+```bash
+# Check if PostgreSQL container is running
+docker ps | grep nordabiz-postgres
+
+# If not running, start it
+docker compose up -d
+
+# Check logs for errors
+docker logs nordabiz-postgres
+
+# Test connection manually
+psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "SELECT 1;"
+```
+
+**Problem:** "FATAL: password authentication failed"
+
+```bash
+# Ensure you're using the correct credentials from docker-compose.yml
+# Development: nordabiz_app / dev_password on port 5433
+# Check your .env file DATABASE_URL matches docker-compose.yml
+```
+
+#### Port Already in Use
+
+**Problem:** Flask fails to start - port 5000 in use
+
+```bash
+# Option 1: Find and kill process using port 5000
+lsof -ti:5000 | xargs kill -9
+
+# Option 2: Use different port in .env
+echo "PORT=5001" >> .env
+python3 app.py
+```
+
+#### Missing Dependencies
+
+**Problem:** ImportError or ModuleNotFoundError
+
+```bash
+# Ensure virtual environment is activated
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+which python  # Should show path to venv/bin/python
+
+# Reinstall all dependencies
+pip install -r requirements.txt --force-reinstall
+
+# If specific package fails, try upgrading pip first
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+#### Database Schema Issues
+
+**Problem:** Missing tables or schema errors
+
+```bash
+# Reset database (⚠️ WARNING: Deletes all data!)
+docker compose down -v
+docker compose up -d
+docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql
+
+# Verify tables exist
+psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "\dt"
+```
+
+### Testing Issues
+
+#### AI Tests Failing
+
+**Problem:** AI quality tests below 70% threshold
+
+```bash
+# Check Gemini API key is configured
+grep GOOGLE_GEMINI_API_KEY .env
+
+# Verify database has companies data
+python -c "from database import SessionLocal, Company; db = SessionLocal(); print(f'Companies: {db.query(Company).count()}'); db.close()"
+# Expected: 80 companies
+
+# Check API rate limits (200 req/day)
+# Wait if limit exceeded, or use different API key
+```
+
+**Problem:** Import errors in tests
+
+```bash
+# Ensure all dependencies installed
+pip install -r requirements.txt
+
+# Verify virtual environment activated
+which python  # Should point to venv/bin/python
+
+# Try running from project root
+cd /path/to/nordabiz
+python run_ai_quality_tests.py -v
+```
+
+### Production Issues
+
+#### Application Not Responding
+
+**Problem:** nordabiznes.pl not loading
+
+```bash
+# SSH to production server
+ssh maciejpi@10.22.68.249
+
+# Check service status
+sudo systemctl status nordabiznes
+
+# If stopped, start it
+sudo systemctl start nordabiznes
+
+# Check logs for errors
+sudo journalctl -u nordabiznes -n 100
+
+# Restart if needed
+sudo systemctl restart nordabiznes
+
+# Verify health
+curl -I https://nordabiznes.pl/health
+```
+
+#### Redirect Loop / 502 Errors
+
+**Problem:** Browser shows redirect loop or 502 Bad Gateway
+
+**Cause:** NPM proxy forwarding to wrong port (80 instead of 5000)
+
+**Solution:**
+1. Access Nginx Proxy Manager: http://10.22.68.250:81
+2. Find Proxy Host for nordabiznes.pl (ID: 27)
+3. **Verify Forward Port is 5000** (NOT 80)
+4. Save and test: `curl -I https://nordabiznes.pl/health`
+
+See [`docs/INCIDENT_REPORT_20260102.md`](docs/INCIDENT_REPORT_20260102.md) for detailed incident analysis.
+
+#### Database Connection Issues in Production
+
+**Problem:** Application can't connect to database
+
+```bash
+# Check PostgreSQL is running
+sudo systemctl status postgresql
+
+# Test connection
+psql -U nordabiz_app -d nordabiz -h localhost -c "SELECT 1;"
+
+# Check logs
+sudo journalctl -u postgresql -n 50
+
+# Restart if needed
+sudo systemctl restart postgresql
+```
+
+#### Permission Denied Errors
+
+**Problem:** Git pull or file write errors
+
+**Cause:** Running commands as wrong user
+
+**Solution:**
+```bash
+# Always use www-data for application operations
+sudo -u www-data git pull
+sudo -u www-data python3 verify_all_companies_data.py
+
+# SSH as maciejpi (NOT root!)
+ssh maciejpi@10.22.68.249
+```
+
+### API & External Service Issues
+
+#### Google API Errors
+
+**Problem:** Gemini/PageSpeed/Places API errors
+
+```bash
+# Check API keys are configured
+grep GOOGLE .env
+
+# Verify API key validity at:
+# - Gemini: https://ai.google.dev/
+# - PageSpeed: https://developers.google.com/speed/docs/insights/v5/get-started
+# - Places: https://console.cloud.google.com/apis/credentials
+
+# Check rate limits:
+# - Gemini: 200 requests/day
+# - PageSpeed: 25,000 requests/day
+# - Places: $200/month credit
+```
+
+**Problem:** "Invalid API key" errors
+
+**Solution:** Regenerate API key in Google Cloud Console and update `.env`
+
+### Common Error Messages
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `sqlalchemy.exc.OperationalError` | Database not accessible | Check PostgreSQL is running, verify credentials |
+| `werkzeug.exceptions.NotFound` | Route doesn't exist | Check URL path, verify route in app.py |
+| `jinja2.exceptions.TemplateNotFound` | Missing template file | Verify template exists in templates/ directory |
+| `InFailedSqlTransaction` | Database transaction failed | Check database logs, ensure rollback after errors |
+| `flask_limiter.errors.RateLimitExceeded` | Too many requests | Wait for rate limit reset, or increase limits |
+
+### Getting Additional Help
+
+If issues persist after trying these solutions:
+
+1. **Check documentation**: [`CLAUDE.md`](CLAUDE.md) has extensive troubleshooting
+2. **Review logs**:
+   - Development: Check Flask console output
+   - Production: `sudo journalctl -u nordabiznes -n 200`
+3. **Database logs**: `docker logs nordabiz-postgres` (dev) or `sudo journalctl -u postgresql` (prod)
+4. **Check health endpoint**: `curl -I https://nordabiznes.pl/health`
+5. **Contact support**: biuro@norda-biznes.info
+
+For detailed database troubleshooting, see [`database/README.md`](database/README.md).
+
+## Resources & Documentation
+
+Additional documentation and resources for developers.
+
+### Project Documentation
+
+| Document | Description | Location |
+|----------|-------------|----------|
+| **CLAUDE.md** | Comprehensive project documentation for AI and developers | [`CLAUDE.md`](CLAUDE.md) |
+| **deployment_checklist.md** | Production deployment procedures | [`deployment_checklist.md`](deployment_checklist.md) |
+| **database/README.md** | Database schema and management guide | [`database/README.md`](database/README.md) |
+| **database/schema.sql** | Complete PostgreSQL schema | [`database/schema.sql`](database/schema.sql) |
+| **data/data-sources.md** | Data source documentation | [`data/data-sources.md`](data/data-sources.md) |
+
+### Incident Reports
+
+| Report | Date | Description |
+|--------|------|-------------|
+| **INCIDENT_REPORT_20260102.md** | 2026-01-02 | NPM proxy redirect loop incident | [`docs/INCIDENT_REPORT_20260102.md`](docs/INCIDENT_REPORT_20260102.md) |
+
+### Key Files Reference
+
+**Core Application:**
+- `app.py` - Main Flask application (routes, authentication, admin panels)
+- `database.py` - SQLAlchemy models (20+ tables)
+- `requirements.txt` - Python dependencies (16 packages)
+
+**Service Modules:**
+- `gemini_service.py` - Google Gemini AI integration
+- `nordabiz_chat.py` - AI chat engine with company context
+- `search_service.py` - Unified search service (FTS, fuzzy, synonyms)
+- `email_service.py` - Microsoft Graph email integration
+- `krs_api_service.py` - Polish business registry API
+- `gbp_audit_service.py` - Google Business Profile audit
+- `it_audit_service.py` - IT infrastructure audit
+
+**Configuration:**
+- `.env.example` - Environment variables template
+- `docker-compose.yml` - PostgreSQL development database
+- `.gitignore` - Git ignore patterns
+
+**Testing:**
+- `run_ai_quality_tests.py` - AI quality test runner
+- `tests/ai_quality_test_cases.json` - 15 test cases in 8 categories
+- `tests/ai_quality_evaluator.py` - AI testing framework
+
+### External Resources
+
+**API Documentation:**
+- [Google Gemini AI](https://ai.google.dev/) - AI chat and recommendations
+- [Google PageSpeed Insights API](https://developers.google.com/speed/docs/insights/v5/get-started) - SEO audits
+- [Google Places API](https://developers.google.com/maps/documentation/places/web-service/overview) - Business verification
+- [KRS Open API](https://api-krs.ms.gov.pl/) - Polish business registry
+- [Brave Search API](https://brave.com/search/api/) - News monitoring
+
+**Technology Documentation:**
+- [Flask 3.0](https://flask.palletsprojects.com/) - Web framework
+- [SQLAlchemy 2.0](https://docs.sqlalchemy.org/) - ORM
+- [PostgreSQL](https://www.postgresql.org/docs/) - Database
+- [Jinja2](https://jinja.palletsprojects.com/) - Template engine
+
+### Git Repositories
+
+| Repository | URL | Purpose |
+|------------|-----|---------|
+| **GitHub** (origin) | https://github.com/pienczyn/nordabiz | Cloud backup, public access |
+| **Gitea** (inpi) | https://10.22.68.180:3000/maciejpi/nordabiz | Internal backup, deployment source |
+
+### Production Environment
+
+- **Server:** NORDABIZ-01 (VM 249, IP: 10.22.68.249)
+- **Reverse Proxy:** R11-REVPROXY-01 (VM 119, IP: 10.22.68.250)
+- **URL:** https://nordabiznes.pl
+- **Status:** LIVE since 2025-11-23
+
+For production access and monitoring, see [Deployment & Production](#deployment--production).
+
 ## Roadmap & Future Enhancements

 While the platform is fully functional and in production, the following features are planned for future releases: