feat: update API documentation and project specifications
This commit is contained in:
gabdevele
+134
-55
@@ -1,59 +1,110 @@
|
||||
# Visione API Spec
|
||||
|
||||
Base path: `/api/v1`.
|
||||
Base path: `/api/v1`
|
||||
|
||||
## Technical
|
||||
- `GET /health`: process health.
|
||||
- `GET /ready`: MySQL readiness.
|
||||
- `GET /openapi.json`: generated OpenAPI 3.0 JSON.
|
||||
- `GET /docs`: Swagger UI page backed by the generated spec.
|
||||
|
||||
## Auth
|
||||
- `POST /auth/register`: create a citizen account.
|
||||
- `POST /auth/otp/request`: send an OTP email through Mailpit.
|
||||
- `POST /auth/otp/verify`: verify OTP and create an API token.
|
||||
- `POST /auth/login/password`: password login fallback.
|
||||
- `POST /auth/change-password`: change the authenticated user's password.
|
||||
- `GET /me`: return the authenticated user.
|
||||
- `PATCH /me`: edit user informations.
|
||||
|
||||
Protected endpoints use:
|
||||
## Auth Header
|
||||
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
## Reports
|
||||
- `POST /reports`: create a report.
|
||||
- `GET /reports`: list reports with optional `status`, `category_id`, `area_id`.
|
||||
- `GET /report-categories`: list active report categories for authenticated users.
|
||||
- `GET /operator/teams`: list active intervention teams for operators/admins.
|
||||
- `GET /operator/reports/assigned`: list reports assigned to the current operator.
|
||||
- `GET /operator/reports/open`: list open unassigned reports.
|
||||
- `GET /operator/reports/others`: list reports assigned to other operators.
|
||||
- `GET /reports/{id}`: report detail.
|
||||
- `GET /reports/{id}/intervention-summary`: operator-facing report summary with
|
||||
citizen contact data, media and latest messages.
|
||||
- `GET /reports/{id}/team-suggestions`: suggest compatible teams by area/category.
|
||||
- `POST /reports/{id}/intervention-link`: create or rotate public team link.
|
||||
- `DELETE /reports/{id}/intervention-link`: revoke public team link.
|
||||
- `PATCH /reports/{id}/status`: update status.
|
||||
- `POST /reports/{id}/take`: assigned-queue operator takes an open report.
|
||||
- `POST /reports/{id}/messages`: write a report message.
|
||||
- `GET /reports/{id}/messages`: list report messages.
|
||||
- `POST /reports/{id}/messages/{message_id}/flags`: assigned operator flags a
|
||||
report message for moderation.
|
||||
- `POST /reports/{id}/assignments`: assign a team.
|
||||
- `POST /reports/{id}/feedback`: add citizen feedback.
|
||||
- `POST /reports/{id}/flags`: assigned operator flags a report for moderation.
|
||||
- `POST /reports/{id}/media`: upload up to five multipart media files. Supported
|
||||
types are JPEG, PNG, WebP, MP4, WebM and QuickTime.
|
||||
## Roles
|
||||
- public: no auth
|
||||
- authenticated: any valid user
|
||||
- operator: `reports.manage` or admin
|
||||
- admin: role/permission admin
|
||||
|
||||
## User
|
||||
- `GET /notifications`: list authenticated user notifications.
|
||||
- `PATCH /notifications/{id}/read`: mark one notification as read.
|
||||
- `PATCH /notifications/read-all`: mark all authenticated user notifications as read.
|
||||
- `GET /me/rewards`: return current points and reward event history.
|
||||
## 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`
|
||||
|
||||
## 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
|
||||
- `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`
|
||||
@@ -62,15 +113,43 @@ Authorization: Bearer <token>
|
||||
- `PATCH /admin/areas/{id}`
|
||||
- `POST /admin/teams`
|
||||
- `PATCH /admin/teams/{id}`
|
||||
- `GET /admin/stats/overview`
|
||||
- `GET /admin/moderation`: list moderation flags with optional `status`.
|
||||
- `PATCH /admin/moderation/{id}`: resolve or dismiss a moderation flag, optionally
|
||||
rejecting the related report.
|
||||
- `GET /admin/users`
|
||||
- `PATCH /admin/users/{id}/roles`
|
||||
- `PATCH /admin/users/{id}/ban`
|
||||
- `GET /admin/stats/overview`
|
||||
|
||||
## Public Data
|
||||
- `GET /areas`: list active municipal areas.
|
||||
- `GET /interventions/{token}`: public intervention summary for external teams.
|
||||
- `GET /open-data/reports`: anonymized resolved/closed report export.
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user