# Quick Start Guide - TaxCore Implementation

## Start the Services

### Option 1: Docker (Recommended) 🐳

```bash
# Start all services with Docker Compose
docker-compose up --build -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f taxcore-service

# Should show:
# [TaxCore Service] Service started on port 3001
# [TaxCore Service] Certificate found at: /usr/src/app/certs/...
```

**See full Docker documentation:** `docs/TaxCore_Docker_Setup.md`

### Option 2: Manual (Development)

```bash
# Terminal 1: Start Node.js TaxCore Service
cd /var/www/html/TAF/websocket-server
npm run taxcore

# Should show:
# [TaxCore Service] Service started on port 3001
# [TaxCore Service] Certificate found at: /var/www/html/TAF/FRCS_Certs_Install/...
```

## Test Basic Connectivity

```bash
# Health check
curl http://localhost:3001/health
# Returns: {"status":"ok","service":"TaxCore Service"}

# Get tax rates
curl http://localhost:3001/tax-rates
# Returns: {"success":true,"data":[...]}
```

## Browser Setup

### Auto-Configuration (Default) ⭐

**No setup needed!** The POS module automatically detects the environment.

Just open the browser and check:
```javascript
// Verify current user is logged in
console.log(window.currentUser);
// Expected: { full_name: "Your Name", user_id: "uuid", ... }
```

### Manual Configuration (Optional)

Only needed if you want to override defaults:

```javascript
// Force Direct Mode (default anyway)
localStorage.setItem('taxcore_direct', 'true');
localStorage.setItem('taxcore_service_url', 'http://localhost:3001');

// Or use Proxy Mode (via PHP)
localStorage.setItem('taxcore_direct', 'false');
```

The system will log the mode in the console:
```
🔌 TaxCore Connection Mode: DIRECT to Node.js
📡 Endpoint: http://localhost:3001/sale
```

## Complete a Test Sale

1. **Add Products to Cart**
   - Search for products
   - Click to add to cart
   - Verify tax labels show (A, G, etc.)

2. **Click Pay Button**
   - Select payment method
   - Click submit

3. **Watch Console Logs**
   ```
   ✓ Added cashier info to sale data: {name: "Your Name", id: "uuid"}
   ✓ Step 1: Sending to TaxCore...
   ✓ Step 2: TaxCore receipt received: [invoice#]
   ✓ Step 3: Saving TaxCore receipt to database...
   ✓ Step 4: Sending sale data to PHP backend...
   ✓ Step 5: Saving sale data to database...
   ✓ ✅ Sale completed successfully - all data saved
   ```

4. **Verify Receipt Modal**
   - Should display receipt
   - Should show your name as cashier
   - Should show customer if selected
   - Should show all items and payments

## Verify in Database

```sql
-- Get latest sale
SELECT 
    sr.sales_receipt_id,
    sr.type,
    sr.invoiceNumber,
    sr.journal LIKE '%Cashier%' as has_cashier,
    lp.line_items,
    lp.payments
FROM sales_receipts sr
LEFT JOIN lineitems_payments lp ON sr.sales_receipt_id = lp.sales_receipt_id
ORDER BY sr."createdAt" DESC
LIMIT 1;
```

## Check Logs

```bash
# Node.js Service Logs
tail -f /usr/src/logs/taxcore-service.log

# Should show:
# Received sale request: {...}
# Using cashier from payload: Your Name
# TaxCore response: {...}

# PHP Logs
tail -f /var/log/apache2/error.log | grep POS

# Should show:
# Using cashierName: Your Name (cashier_id: uuid)
```

## Troubleshooting

### "TaxCore request failed: Connection refused"
- Node.js service not running
- Solution: `npm run taxcore` in websocket-server directory

### "Cashier: Unknown" in receipt
- Not logged in or `window.currentUser` not set
- Solution: Log in again, check console for `window.currentUser`

### "No tax labels for product"
- Product missing tax configuration
- Solution: Console shows warning, defaults to G (0%)
- Fix: Update product with correct tax labels

### Receipt saved but no sale in database
- PHP backend save failed
- Check: `/api/POS/sale` endpoint in Network tab
- Check: PHP error logs

### Sale in database but no TaxCore receipt
- TaxCore service or API failed
- Check: Node.js logs for errors
- Check: Certificate and credentials

## Quick Reference

### Browser to Node.js Payload
```javascript
{
  sales_receipt_id: "uuid-v7",
  items: [
    {
      product_id: "uuid",
      name: "Product Name",
      qty: 2,
      price: 10.50,
      unit: "each",
      labels: ["A", "G"]
    }
  ],
  payments: [
    { method: "Cash", amount: 21.00 }
  ],
  total: 21.00,
  pay: 21.00,
  type: "Normal",
  cashier_name: "John Doe",  // ← Added by browser
  cashier_id: "uuid-123",    // ← Added by browser
  customer: { name: "Customer", tin: "123456789" }
}
```

### Node.js Transforms to TaxCore Format
```javascript
{
  Items: [  // ← Transformed
    {
      Name: "Product Name",
      Quantity: 2,
      UnitPrice: 10.50,
      TotalAmount: 21.00,
      Labels: ["A", "G"]
    }
  ],
  payment: [  // ← Transformed
    { paymentType: "1", amount: 21.00 }
  ],
  Cashier: "John Doe",  // ← From cashier_name
  Buyer: { Name: "Customer" },
  buyerId: "123456789",
  DateAndTimeOfIssue: "2025-10-02T10:30:00+12:00",
  invoiceType: 0,
  transactionType: "Sale",
  Options: {
    omitTextualRepresentation: 0,
    omitQRCodeGen: 0
  }
}
```

### Payment Method Codes
```
0 = Other
1 = Cash
2 = Card/EFTPOS
3 = Check/Cheque
4 = Wire Transfer/Bank Transfer
5 = Voucher
6 = Mobile Money/M-Paisa
```

### Sale Types
```
Normal    → invoiceType: 0
Proforma  → invoiceType: 1
Copy      → invoiceType: 2
Training  → invoiceType: 3
Advance   → invoiceType: 4
```

## Support

- **Issues**: Check `docs/TaxCore_Implementation_Checklist.md`
- **Architecture**: See `docs/TaxCore_Current_Architecture.md`
- **Full Docs**: See `websocket-server/TAXCORE_SERVICE.md`

---

**Ready to Test!** 🚀