161 lines
4.6 KiB
Markdown
161 lines
4.6 KiB
Markdown
# 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 through Mailpit
|
|
- `POST /auth/otp/verify`
|
|
consumes OTP, returns bearer token
|
|
- `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`
|
|
|
|
## 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.
|