Spaces:
Sleeping
Sleeping
| # Backend API (FastAPI) | |
| The frontend app now lives in `frontend/` and should be started from there. | |
| ## 1) Install and start API | |
| ```bash | |
| python3 -m venv .venv | |
| source .venv/bin/activate | |
| pip install -r backend/requirements.txt | |
| uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000 | |
| ``` | |
| Health check: | |
| ```bash | |
| curl -s http://localhost:8000/health | jq . | |
| ``` | |
| ## 2) Seed command (with valid CSV path) | |
| ```bash | |
| python3 scripts/seed_db.py \ | |
| --db backend/app/db/local.db \ | |
| --csv data/students_base.csv \ | |
| --seed 42 \ | |
| --reset | |
| ``` | |
| Alternative via API: | |
| ```bash | |
| curl -X POST http://localhost:8000/admin/reset-and-seed \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "csv_path": "data/students_base.csv", | |
| "seed": 42, | |
| "reset": true | |
| }' | |
| ``` | |
| ## 3) Sample curl calls | |
| List leads: | |
| ```bash | |
| curl -s "http://localhost:8000/leads?fair_id=1&limit=20&offset=0&sort_by=total_score&sort_order=desc" | jq . | |
| ``` | |
| Lead detail: | |
| ```bash | |
| curl -s "http://localhost:8000/leads/1" | jq . | |
| ``` | |
| Lead score: | |
| ```bash | |
| curl -s "http://localhost:8000/leads/1/score" | jq . | |
| ``` | |
| Fair KPIs: | |
| ```bash | |
| curl -s "http://localhost:8000/kpis/fair/1" | jq . | |
| ``` | |
| Stand KPIs: | |
| ```bash | |
| curl -s "http://localhost:8000/kpis/stands?fair_id=1&period=all" | jq . | |
| ``` | |
| Conference KPIs: | |
| ```bash | |
| curl -s "http://localhost:8000/kpis/conferences?fair_id=1&period=all" | jq . | |
| ``` | |
| Create one event and recompute: | |
| ```bash | |
| curl -X POST "http://localhost:8000/events?recompute=true" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "fair_id": 1, | |
| "student_id": 1, | |
| "event_type": "site_page_view", | |
| "source_channel": "web", | |
| "payload": {"page": "programme"} | |
| }' | jq . | |
| ``` | |
| Bulk events: | |
| ```bash | |
| curl -X POST "http://localhost:8000/events/bulk" \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "events": [ | |
| {"fair_id": 1, "student_id": 1, "event_type": "check_in"}, | |
| {"fair_id": 1, "student_id": 1, "event_type": "stand_tap", "stand_id": 1} | |
| ] | |
| }' | jq . | |
| ``` | |
| Manual recompute: | |
| ```bash | |
| curl -X POST http://localhost:8000/model/recompute | jq . | |
| ``` | |
| DB stats: | |
| ```bash | |
| curl -s http://localhost:8000/admin/db-stats | jq . | |
| ``` | |
| ## 4) Troubleshooting | |
| ### FileNotFoundError / CSV path issues | |
| - Use an absolute path for `--csv` and `csv_path`. | |
| - Confirm file exists: | |
| ```bash | |
| ls -lh /absolute/path/to/your/students_base.csv | |
| ``` | |
| - Required CSV headers: `row_id,audience_type,grade,student_subgroup,visited_site,used_ORI,took_test,digital_experience` | |
| ### Empty DB responses | |
| If seeding has not run or failed: | |
| - `GET /leads` returns `{ "data": [], "total": 0, ... }` | |
| - `GET /kpis/fair/{fair_id}` returns zero metrics instead of server errors. | |
| Use: | |
| ```bash | |
| curl -s http://localhost:8000/admin/db-stats | jq . | |
| ``` | |
| to verify row counts by table. | |