backend/docs/API_SPEC.md

Visione API Spec

Base path: /api/v1

Auth Header

Authorization: Bearer <token>

Roles

• public: no auth
• authenticated: any valid user
• operator: reports.manage or admin
• admin: role/permission admin

HTTP Semantics

• 200: success
• 401: missing or invalid auth
• 403: authenticated but forbidden
• 404: missing resource or invalid public intervention token
• 409: workflow or ownership conflict
• 422: semantic payload/reference error

Technical

• GET /health
• GET /ready
• GET /openapi.json
• GET /docs

Auth + Profile

• POST /auth/register citizen registration
• POST /auth/otp/request sends OTP through Mailpit
• POST /auth/otp/verify consumes OTP, returns bearer token
• POST /auth/login/password password fallback login
• POST /auth/change-password authenticated password change, also clears must_change_password
• GET /me current user profile, roles, permissions, points
• PATCH /me editable fields today: first_name, last_name, phone

Public Reference / Public Access

• GET /areas active municipal areas
• GET /interventions/{token} public external-team summary link
• GET /open-data/reports anonymized reports in RESOLVED or CLOSED filtered to Bari municipal boundary

User Reference / Personal

• GET /report-categories active report categories, authenticated users only
• GET /notifications
• PATCH /notifications/{id}/read
• PATCH /notifications/read-all
• GET /me/rewards

Report Endpoints

• POST /reports create citizen report, optional inline media, area inferred by GeoJSON coordinates must stay inside allowed Bari municipal boundary
• GET /reports citizen sees own reports; operator/admin see all
• GET /reports/{id} detail + status history + media
• GET /reports/{id}/messages
• POST /reports/{id}/messages
• POST /reports/{id}/media max 5 total media, image/video only
• POST /reports/{id}/feedback only owner, only when status is RESOLVED

Operator Workflow

• GET /operator/teams active external intervention teams
• GET /operator/reports/open
• GET /operator/reports/assigned
• GET /operator/reports/others
• POST /reports/{id}/take OPEN -> UNDER_REVIEW
• PATCH /reports/{id}/status only owner operator or admin, valid transitions only
• POST /reports/{id}/assignments assign external team if report is OPEN, assignment can directly claim report and move to ASSIGNED
• GET /reports/{id}/intervention-summary operator/admin full summary with citizen contact data
• GET /reports/{id}/team-suggestions suggestions by category/team-category mapping and area
• POST /reports/{id}/intervention-link create/rotate public intervention token for current assignment
• DELETE /reports/{id}/intervention-link revoke active intervention token

Moderation

• POST /reports/{id}/flags operator flags owned report
• POST /reports/{id}/messages/{message_id}/flags operator flags owned report message
• GET /admin/moderation admin moderation queue
• PATCH /admin/moderation/{id} admin resolves/dismisses; may also reject report

Admin Reference Data

• POST /admin/categories
• PATCH /admin/categories/{id}
• POST /admin/areas
• PATCH /admin/areas/{id} area polygon must stay inside allowed Bari municipal boundary
• POST /admin/teams
• PATCH /admin/teams/{id}
• GET /admin/users
• PATCH /admin/users/{id}/roles
• PATCH /admin/users/{id}/ban
• GET /admin/stats/overview

Workflow Summary

Citizen

1. register/login
2. create OPEN report
3. watch status/history/media
4. chat with operator
5. receive notifications
6. leave feedback on RESOLVED

Operator

1. inspect open queue
2. take or assign team directly
3. own report through assigned_operator_id
4. update status / chat / moderate
5. generate public team link

Admin

1. manage reference data and users
2. resolve moderation
3. read global stats

Current Status Machine

• OPEN -> UNDER_REVIEW | REJECTED
• UNDER_REVIEW -> ASSIGNED | REJECTED
• ASSIGNED -> IN_PROGRESS | REJECTED
• IN_PROGRESS -> RESOLVED | REJECTED
• RESOLVED -> CLOSED
• REJECTED -> CLOSED

Important Current Truths

• External teams are not platform users.
• Platform owner is always reports.assigned_operator_id.
• assignments is historical external team linkage only.
• Feedback does not auto-close report.
• Public intervention summary exposes citizen phone by design, but not email or full surname.
• Report coordinates are constrained to Bari municipal boundary.
• Admin-created area polygons must stay inside Bari municipal boundary.