Add POS service

services/pos/README.md

@@ -0,0 +1,138 @@
+# POS Integration Service
+
+This service handles integration with external Point of Sale (POS) systems for the Bakery IA platform.
+
+## Supported POS Systems
+
+- **Square POS** - Popular payment and POS solution with strong API support
+- **Toast POS** - Restaurant-focused POS system with comprehensive features
+- **Lightspeed Restaurant** - Full-featured restaurant management system
+
+## Features
+
+- **Real-time webhook handling** from POS systems
+- **Bidirectional data synchronization** with sales service
+- **Secure credential management** with encryption
+- **Multi-tenant support** with tenant-specific configurations
+- **Comprehensive transaction logging** and audit trails
+- **Automatic duplicate detection** and handling
+- **Rate limiting and retry mechanisms** for reliability
+
+## Architecture
+
+The POS service follows the established microservices architecture:
+
+```
+POS Service
+├── API Layer (FastAPI)
+├── Business Logic (Services)
+├── Data Access (Repositories)
+├── External Integrations (POS Providers)
+├── Webhook Handlers
+└── Background Sync Jobs
+```
+
+## API Endpoints
+
+### Configuration Management
+- `GET /api/v1/tenants/{tenant_id}/pos/configurations` - List POS configurations
+- `POST /api/v1/tenants/{tenant_id}/pos/configurations` - Create new configuration
+- `PUT /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}` - Update configuration
+- `DELETE /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}` - Delete configuration
+
+### Webhook Handling
+- `POST /api/v1/webhooks/{pos_system}` - Receive webhooks from POS systems
+- `GET /api/v1/webhooks/{pos_system}/status` - Get webhook status
+
+### Data Synchronization
+- `POST /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}/sync` - Trigger sync
+- `GET /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}/sync/status` - Get sync status
+- `GET /api/v1/tenants/{tenant_id}/pos/transactions` - Get POS transactions
+
+## Database Schema
+
+### Core Tables
+- `pos_configurations` - POS system configurations per tenant
+- `pos_transactions` - Transaction data from POS systems
+- `pos_transaction_items` - Individual items within transactions
+- `pos_webhook_logs` - Webhook event logs
+- `pos_sync_logs` - Synchronization operation logs
+
+## Environment Variables
+
+See `app/core/config.py` for all configuration options. Key variables include:
+
+```bash
+# Database
+POS_DATABASE_URL=postgresql+asyncpg://pos_user:pos_pass123@pos-db:5432/pos_db
+
+# POS Provider Credentials
+SQUARE_APPLICATION_ID=your_square_app_id
+SQUARE_ACCESS_TOKEN=your_square_token
+TOAST_CLIENT_ID=your_toast_client_id
+LIGHTSPEED_CLIENT_ID=your_lightspeed_client_id
+
+# Webhook Configuration
+WEBHOOK_BASE_URL=https://your-domain.com
+WEBHOOK_SECRET=your_webhook_secret
+```
+
+## Development
+
+### Running the Service
+
+```bash
+# Using Docker Compose (recommended)
+docker-compose up pos-service
+
+# Local development
+cd services/pos
+pip install -r requirements.txt
+uvicorn app.main:app --reload --port 8000
+```
+
+### Database Migrations
+
+```bash
+# Create migration
+alembic revision --autogenerate -m "Description"
+
+# Apply migrations
+alembic upgrade head
+```
+
+### Testing
+
+```bash
+# Run tests
+pytest tests/
+
+# Run with coverage
+pytest --cov=app tests/
+```
+
+## Security Considerations
+
+- POS credentials are encrypted before storage
+- Webhook signatures are verified for authenticity
+- All API endpoints require tenant-based authentication
+- Rate limiting prevents abuse
+- Sensitive data is logged with appropriate redaction
+
+## Monitoring
+
+The service includes comprehensive monitoring:
+
+- Health check endpoints
+- Prometheus metrics
+- Structured logging
+- Performance tracking
+- Error rate monitoring
+
+## Integration Flow
+
+1. **Configuration**: Set up POS system credentials via API
+2. **Webhook Registration**: Register webhook URLs with POS providers
+3. **Real-time Events**: Receive and process webhook events
+4. **Data Sync**: Periodic synchronization of transaction data
+5. **Sales Integration**: Forward processed data to sales service