# 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