172 lines
4.8 KiB
Markdown
172 lines
4.8 KiB
Markdown
# Data Browse Monitor
|
|
|
|
**Test-oriented data navigation for AMAR** - quickly find which users to log in as for different test scenarios.
|
|
|
|
## Purpose
|
|
|
|
When working on multiple tickets simultaneously, you need to quickly navigate to users in specific data states:
|
|
- New user with no data
|
|
- User with pets but no requests
|
|
- User with pending payment
|
|
- Vet with active requests
|
|
- Admin account
|
|
|
|
This monitor provides at-a-glance views of the database grouped by test-relevant states.
|
|
|
|
## Architecture
|
|
|
|
Follows pawprint **book/larder pattern**:
|
|
- **larder/** contains all data files (schema, views, scenarios)
|
|
- **main.py** generates SQL queries from view definitions
|
|
- Two modes: **SQL** (direct queries) and **API** (Django backend, placeholder)
|
|
|
|
### Key Concepts
|
|
|
|
**Schema** (`larder/schema.json`)
|
|
- AMAR data model with SQL table mappings
|
|
- Regular fields (from database columns)
|
|
- Computed fields (SQL expressions)
|
|
- Support for multiple graph generators
|
|
|
|
**Views** (`larder/views.json`)
|
|
- Define what to display and how to group it
|
|
- Each view targets an entity (User, PetOwner, Veterinarian, etc.)
|
|
- Can group results (e.g., by role, by data state, by availability)
|
|
- SQL is generated automatically from view configuration
|
|
|
|
**Scenarios** (`larder/scenarios.json`)
|
|
- Test scenarios emerge from actual usage
|
|
- Format defined, real scenarios added as needed
|
|
- Links scenarios to specific views with filters
|
|
|
|
## Available Views
|
|
|
|
1. **users_by_role** - All users grouped by USER/VET/ADMIN for quick login selection
|
|
2. **petowners_by_state** - Pet owners grouped by data state (has_pets, has_coverage, has_requests, has_turnos)
|
|
3. **vets_by_availability** - Vets grouped by availability status (available, busy, very busy, no availability)
|
|
4. **requests_pipeline** - Active service requests grouped by state (similar to turnos monitor)
|
|
|
|
## Running Locally
|
|
|
|
```bash
|
|
cd /home/mariano/wdir/ama/pawprint/ward/monitor/data_browse
|
|
python main.py
|
|
# Opens on http://localhost:12020
|
|
```
|
|
|
|
Or with uvicorn:
|
|
```bash
|
|
uvicorn ward.monitor.data_browse.main:app --port 12020 --reload
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
```bash
|
|
# Database connection (defaults to local dev)
|
|
export NEST_NAME=local
|
|
export DB_HOST=localhost
|
|
export DB_PORT=5433
|
|
export DB_NAME=amarback
|
|
export DB_USER=mariano
|
|
export DB_PASSWORD=""
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
```
|
|
GET / # Landing page
|
|
GET /view/{view_slug} # View display (HTML)
|
|
GET /health # Health check
|
|
GET /api/views # List all views (JSON)
|
|
GET /api/view/{view_slug} # View data (JSON)
|
|
GET /api/schema # Data model schema (JSON)
|
|
GET /api/scenarios # Test scenarios (JSON)
|
|
```
|
|
|
|
## Adding New Views
|
|
|
|
Edit `larder/views.json`:
|
|
|
|
```json
|
|
{
|
|
"name": "my_new_view",
|
|
"title": "My New View",
|
|
"slug": "my-new-view",
|
|
"description": "Description of what this shows",
|
|
"mode": "sql",
|
|
"entity": "PetOwner",
|
|
"group_by": "some_field",
|
|
"fields": ["id", "first_name", "last_name", "email"],
|
|
"display_fields": {
|
|
"id": {"label": "ID", "width": "60px"},
|
|
"first_name": {"label": "Name", "width": "120px"}
|
|
}
|
|
}
|
|
```
|
|
|
|
The SQL query is automatically generated from:
|
|
- Entity definition in `schema.json` (table name, columns)
|
|
- Fields list (regular + computed fields)
|
|
- Group by configuration (if specified)
|
|
- Filters (if specified)
|
|
|
|
## Adding Computed Fields
|
|
|
|
Edit `larder/schema.json` in the entity definition:
|
|
|
|
```json
|
|
"computed": {
|
|
"has_pets": {
|
|
"description": "Has at least one pet",
|
|
"sql": "EXISTS (SELECT 1 FROM mascotas_pet WHERE petowner_id = mascotas_petowner.id AND deleted = false)"
|
|
}
|
|
}
|
|
```
|
|
|
|
Computed fields can be used in views just like regular fields.
|
|
|
|
## Adding Test Scenarios
|
|
|
|
As you identify test patterns, add them to `larder/scenarios.json`:
|
|
|
|
```json
|
|
{
|
|
"name": "User with Pending Payment",
|
|
"slug": "user-pending-payment",
|
|
"description": "User with accepted request awaiting payment",
|
|
"role": "USER",
|
|
"entity": "ServiceRequest",
|
|
"view": "requests_pipeline",
|
|
"filters": {
|
|
"state": ["vet_accepted", "in_progress_pay"],
|
|
"has_payment": false
|
|
},
|
|
"test_cases": [
|
|
"Payment flow (MercadoPago)",
|
|
"Payment reminders",
|
|
"Payment timeout"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Files
|
|
|
|
```
|
|
data_browse/
|
|
├── larder/
|
|
│ ├── .larder # Larder marker (book pattern)
|
|
│ ├── schema.json # AMAR data model with SQL mappings
|
|
│ ├── views.json # View configurations
|
|
│ └── scenarios.json # Test scenarios
|
|
├── main.py # FastAPI app
|
|
├── index.html # Landing page
|
|
├── view.html # View display template
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Status
|
|
|
|
**Current:** SQL mode fully implemented, ready for local testing
|
|
**Next:** Test with local database, refine views based on usage
|
|
**Future:** See `workbench/data_browse_roadmap.md`
|