migrated all pawprint work
This commit is contained in:
buenosairesam
171
station/monitors/databrowse/README.md
Normal file
171
station/monitors/databrowse/README.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user