desk-moloni/.specify/specs.md

📋 SPECIFICATIONS - desk-moloni

🎯 PROJECT OVERVIEW

Integração Bidirecional DeskCRM ↔ Moloni

Sistema de sincronização automática entre DeskCRM (Customer Relationship Management) e Moloni (Sistema de Faturação) para automatizar processos financeiros e melhorar eficiência operacional.

🏗️ ARCHITECTURE

Core Components

DeskMoloniIntegration
├── APIConnectors/
│   ├── DeskCRMConnector     # DeskCRM API integration
│   └── MoloniConnector      # Moloni API integration
├── DataMappers/
│   ├── CustomerMapper       # Customer field mappings
│   ├── InvoiceMapper        # Invoice field mappings  
│   └── PaymentMapper        # Payment field mappings
├── SyncEngines/
│   ├── CustomerSyncEngine   # Customer synchronization
│   ├── InvoiceSyncEngine    # Invoice synchronization
│   └── PaymentSyncEngine    # Payment synchronization
└── Utils/
    ├── Logger               # Comprehensive logging
    ├── Validator            # Data validation
    └── ConfigManager        # Configuration management

📡 API INTEGRATIONS

DeskCRM API v3

Endpoint: https://desk.descomplicar.pt/api/
Authentication: API Key + Bearer Token
Rate Limit: 1000 requests/hour

Entities:
- Customers (GET, POST, PUT)
- Invoices (GET, POST, PUT) 
- Payments (GET, POST)
- Projects (GET)

Moloni API

Endpoint: https://api.moloni.pt/v1/
Authentication: OAuth 2.0
Rate Limit: 10000 requests/day

Entities:
- Clients (GET, POST, PUT, DELETE)
- Documents (GET, POST, PUT)
- Products (GET, POST, PUT)
- Payments (GET, POST)

🔄 SYNCHRONIZATION FLOWS

1. Customer Sync (DeskCRM → Moloni)

Trigger: New customer created in DeskCRM
Process:
1. Fetch customer data from DeskCRM
2. Map fields to Moloni format
3. Validate required fields
4. Create/Update client in Moloni
5. Store mapping in sync_mappings table
6. Log operation result

2. Invoice Import (Moloni → DeskCRM)

Trigger: New invoice issued in Moloni
Process:
1. Fetch invoice data from Moloni
2. Identify corresponding DeskCRM customer
3. Map invoice fields to DeskCRM format
4. Create invoice record in DeskCRM
5. Update customer financial data
6. Log operation result

3. Payment Reconciliation (Bidirectional)

Trigger: Payment recorded in either system
Process:
1. Fetch payment data from source system
2. Find matching invoice in target system  
3. Update payment status
4. Reconcile balances
5. Generate reconciliation report

💾 DATABASE SCHEMA

Core Tables

-- Sync mappings between systems
sync_mappings (
    id INT PRIMARY KEY AUTO_INCREMENT,
    deskcrm_type VARCHAR(50),     # customer, invoice, payment
    deskcrm_id VARCHAR(50),       # DeskCRM entity ID
    moloni_type VARCHAR(50),      # client, document, payment
    moloni_id VARCHAR(50),        # Moloni entity ID
    sync_status ENUM('synced', 'pending', 'failed'),
    last_sync TIMESTAMP,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

-- Sync operations log
sync_operations (
    id INT PRIMARY KEY AUTO_INCREMENT,
    operation_type VARCHAR(50),   # create, update, delete
    entity_type VARCHAR(50),      # customer, invoice, payment
    entity_id VARCHAR(50),        # Entity identifier
    source_system VARCHAR(20),    # deskcrm, moloni
    target_system VARCHAR(20),    # moloni, deskcrm
    status ENUM('success', 'failed', 'pending'),
    error_message TEXT,
    execution_time DECIMAL(10,3), # Execution time in seconds
    created_at TIMESTAMP
);

-- Configuration settings
sync_config (
    id INT PRIMARY KEY AUTO_INCREMENT,
    config_key VARCHAR(100) UNIQUE,
    config_value TEXT,
    description TEXT,
    updated_at TIMESTAMP
);

⚙️ CONFIGURATION

Environment Variables

# DeskCRM Configuration
DESKCRM_API_URL=https://desk.descomplicar.pt/api/
DESKCRM_API_KEY=your_api_key
DESKCRM_BEARER_TOKEN=your_bearer_token

# Moloni Configuration
MOLONI_CLIENT_ID=your_client_id
MOLONI_CLIENT_SECRET=your_client_secret
MOLONI_ACCESS_TOKEN=your_access_token
MOLONI_COMPANY_ID=your_company_id

# Database Configuration
DB_HOST=localhost
DB_NAME=desk_moloni
DB_USER=deskcrm_user
DB_PASS=secure_password

# Sync Configuration
SYNC_BATCH_SIZE=100
SYNC_RATE_LIMIT=50
LOG_LEVEL=INFO
DEBUG_MODE=false

🎯 FUNCTIONAL REQUIREMENTS

FR1: Customer Synchronization

• Priority: HIGH
• Description: Automatic sync of customer data from DeskCRM to Moloni
• Acceptance Criteria:
  • New DeskCRM customers appear in Moloni within 5 minutes
  • Customer updates are reflected in both systems
  • Field mappings are configurable
  • Duplicate detection and handling

FR2: Invoice Management

• Priority: HIGH
• Description: Import Moloni invoices into DeskCRM
• Acceptance Criteria:
  • Moloni invoices create corresponding DeskCRM records
  • Invoice status updates are synchronized
  • Payment tracking across both systems
  • Tax and financial data accuracy

FR3: Reporting & Monitoring

• Priority: MEDIUM
• Description: Comprehensive sync monitoring and reporting
• Acceptance Criteria:
  • Real-time sync status dashboard
  • Error reporting and notifications
  • Performance metrics tracking
  • Audit trail maintenance

FR4: Configuration Management

• Priority: MEDIUM
• Description: Dynamic configuration of sync parameters
• Acceptance Criteria:
  • Web-based configuration interface
  • Field mapping customization
  • Sync frequency settings
  • Error handling preferences

🛡️ NON-FUNCTIONAL REQUIREMENTS

Performance

• Response Time: <2 seconds for individual operations
• Throughput: 500+ sync operations per day
• Batch Processing: 100 records per batch
• Memory Usage: <512MB during operation

Reliability

• Uptime: 99.9% availability
• Error Rate: <0.5% failed operations
• Recovery Time: <5 minutes for service restoration
• Data Consistency: 100% accuracy requirement

Security

• Authentication: OAuth 2.0 and API Key based
• Encryption: HTTPS for all API communications
• Data Protection: GDPR compliant data handling
• Audit Trail: Complete operation logging

Maintainability

• Code Quality: PSR-12 compliance
• Documentation: 100% PHPDoc coverage
• Testing: 80%+ code coverage
• Modularity: Component-based architecture

🧪 TESTING STRATEGY

Unit Testing

Tests/Unit/
├── APIConnectors/
├── DataMappers/
├── SyncEngines/
└── Utils/

Integration Testing

Tests/Integration/
├── DeskCRMIntegrationTest
├── MoloniIntegrationTest
└── EndToEndSyncTest

Performance Testing

• Load testing with 1000+ concurrent operations
• Memory leak detection
• API rate limit compliance
• Database performance optimization

🚀 DEPLOYMENT STRATEGY

Development Environment

• Local PHP 8.4+ with MySQL 8.0/MariaDB 10.6+
• PHPUnit 12.3+ with modern attribute syntax
• Docker containers for isolation
• Git-based version control with pre-commit hooks
• Automated testing with coverage reporting

Production Environment

• LAMP stack on dedicated server
• SSL certificates for HTTPS
• Database backups and replication
• Application monitoring and logging

CI/CD Pipeline

Stages:
1. Code Quality Check (PHPStan level 8, PSR-12)
2. Unit Tests (PHPUnit 12.3+ with PHP 8.4 attributes)
3. Integration Tests (MockWebServer framework)
4. Security Scan (OWASP + vulnerability analysis)
5. Performance Tests (Memory profiling + load testing)
6. Coverage Report (80%+ requirement)
7. Deployment to Staging
8. Production Deployment (manual approval)

---

Version: 1.1 | Last Update: 2025-09-12 23:30 | Status: ✅ PHP 8.4 Ready