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

# 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:

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)

# 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

# Get mock database stats
GET /mock/stats

# Reset mock database
GET /mock/reset

Response Format

All responses include _mock: true to identify mock data:

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

Testing Scenarios

Complete Turnero Flow

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