soleprint/artery/shunts/amar/README.md

# Amar (MOCK) Vein

Mock Amar API for testing - returns predictable test data for turnero flow testing.

## Purpose

Enables testing of the turnero flow (VET-535-540) without hitting the real Amar backend:
- Guest petowner creation (VET-536)
- Pet creation (VET-537)
- Cart creation and price calculation (VET-538)
- Service/category filtering (VET-539, VET-540)
- Service request creation

## Quick Start

```bash
# Install dependencies
pip install -r requirements.txt

# Start the mock server
python run.py

# API docs: http://localhost:8005/docs
# Health check: http://localhost:8005/health
```

## Configuration

Copy `.env.example` to `.env` and adjust:

```bash
API_PORT=8005                  # Server port
ENABLE_RANDOM_DELAYS=true      # Add realistic delays
MIN_DELAY_MS=100               # Minimum delay
MAX_DELAY_MS=500               # Maximum delay
ERROR_RATE=0.0                 # Error rate (0.0 to 1.0)
```

## API Endpoints

### Turnero Flow (VET-536-540)

```bash
# Create guest petowner (VET-536)
POST /api/v1/pet-owners/
{
  "address": "Av. Santa Fe 1234, Palermo"
}

# Create pet (VET-537)
POST /api/v1/pets/
{
  "owner_id": 1234,
  "name": "Luna",
  "species": "DOG",
  "age": 3,
  "age_unit": "years"
}

# Create cart (VET-538)
POST /api/v1/cart/
{
  "owner_id": 1234
}

# Add item to cart
POST /api/v1/cart/{cart_id}/items/
{
  "service_id": 1,
  "pet_id": 5678,
  "quantity": 1
}

# List services (VET-540)
GET /api/v1/services/?species=DOG&neighborhood_id=1

# List categories (VET-539)
GET /api/v1/categories/?species=DOG&neighborhood_id=1

# Create service request
POST /solicitudes/service-requests/?cart_id=12345
```

### Mock Control

```bash
# Get mock database stats
GET /mock/stats

# Reset mock database
GET /mock/reset
```

## Response Format

All responses include `_mock: true` to identify mock data:

```json
{
  "id": 1234,
  "address": "Av. Santa Fe 1234, Palermo",
  "is_guest": true,
  "_mock": true
}
```

## Testing Scenarios

### Complete Turnero Flow

```python
import requests

BASE_URL = "http://localhost:8005"

# Step 1: Create guest petowner
owner_resp = requests.post(f"{BASE_URL}/api/v1/pet-owners/", json={
    "address": "Av. Santa Fe 1234, Palermo"
})
owner = owner_resp.json()

# Step 2: Create pet
pet_resp = requests.post(f"{BASE_URL}/api/v1/pets/", json={
    "owner_id": owner["id"],
    "name": "Luna",
    "species": "DOG",
    "age": 3,
    "age_unit": "years"
})
pet = pet_resp.json()

# Step 3: Create cart
cart_resp = requests.post(f"{BASE_URL}/api/v1/cart/", json={
    "owner_id": owner["id"]
})
cart = cart_resp.json()

# Step 4: Get available services
services_resp = requests.get(
    f"{BASE_URL}/api/v1/services/",
    params={"species": "DOG", "neighborhood_id": owner["neighborhood"]["id"]}
)
services = services_resp.json()

# Step 5: Add service to cart
cart_resp = requests.post(f"{BASE_URL}/api/v1/cart/{cart['id']}/items/", json={
    "service_id": services[0]["id"],
    "pet_id": pet["id"],
    "quantity": 1
})
cart = cart_resp.json()
print(f"Cart total: ${cart['resume']['total']}")

# Step 6: Create service request
request_resp = requests.post(
    f"{BASE_URL}/solicitudes/service-requests/",
    params={"cart_id": cart["id"]}
)
service_request = request_resp.json()
print(f"Service request created: {service_request['id']}")
```

## Data Generator

This vein uses the independent `datagen` tool from `ward/tools/datagen/amar.py`.
See `ward/tools/datagen/README.md` for data generation details.

## Notes

- Mock database is in-memory (resets on server restart)
- Use `/mock/reset` to clear data during testing
- All IDs are randomly generated on creation
- Multi-pet discounts are automatically calculated