Add Visione backend foundation

docs/API_SPEC.md

@@ -0,0 +1,37 @@
+# Visione API Spec
+
+Base path: `/api/v1`.
+
+## Technical
+- `GET /health`: process health.
+- `GET /ready`: MySQL readiness.
+
+## Auth
+- `POST /auth/register`: create a citizen account.
+- `POST /auth/otp/request`: send an OTP email through MailHog.
+- `POST /auth/otp/verify`: verify OTP and create an API token.
+- `POST /auth/login/password`: password login fallback.
+- `GET /me`: return the authenticated user.
+
+Protected endpoints use:
+
+```http
+Authorization: Bearer <token>
+```
+
+## Reports
+- `POST /reports`: create a report.
+- `GET /reports`: list reports with optional `status`, `category_id`, `area_id`.
+- `GET /reports/{id}`: report detail.
+- `PATCH /reports/{id}/status`: update status.
+- `POST /reports/{id}/messages`: write a report message.
+- `GET /reports/{id}/messages`: list report messages.
+- `POST /reports/{id}/assignments`: assign a team.
+- `POST /reports/{id}/feedback`: add citizen feedback.
+
+## Admin Reference Data
+- `GET|POST /admin/categories`
+- `GET|POST /admin/areas`
+- `GET|POST /admin/teams`
+- `GET /admin/stats/overview`
+