# Visione API Spec

Base path: `/api/v1`

## Auth Header

```http
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 without password
- `POST /auth/otp/request`
  sends OTP email through configured SMTP provider
- `POST /auth/otp/verify`
  consumes OTP, returns bearer token
- `POST /auth/cie/start`
  creates local CIE login state and returns Django RP authorization URL
- `GET /auth/cie/session/{state}`
  frontend polling endpoint; returns final Visione bearer token on success
- `GET /me`
  current user profile, roles, permissions, points
- `PATCH /me`
  editable fields today: `first_name`, `last_name`, `phone`

## Public Reference / Public Access
- `GET /areas`
  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`, one feedback per report

## 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}`
- `DELETE /admin/categories/{id}`
- `POST /admin/areas`
- `PATCH /admin/areas/{id}`
- `DELETE /admin/areas/{id}`
  deletes area and clears linked `reports.area_id` and `teams.area_id`
  area polygon must stay inside allowed Bari municipal boundary
- `POST /admin/teams`
- `PATCH /admin/teams/{id}`
- `DELETE /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.