backend/docs/PROJECT_SPEC.md

Visione Project Spec

Goal

Visione lets citizens report urban problems and lets municipal staff manage, assign and resolve interventions while preserving history and basic analytics.

Roles

• citizen: registers, requests OTP login, creates reports, follows own reports, sends messages and leaves feedback after resolution.
• operator: views reports, takes open reports, assigns teams, updates managed reports and messages citizens.
• admin: manages users, roles, reference data, teams, areas and all reports.

The system admin seed must change password before using protected operational or administrative APIs.

Report Statuses

• OPEN: created and waiting for review.
• UNDER_REVIEW: an operator is checking the report.
• ASSIGNED: a team has been assigned.
• IN_PROGRESS: intervention is active.
• RESOLVED: intervention was completed.
• REJECTED: report was invalid or abusive.
• CLOSED: administrative closure after feedback or final review.

MVP Scope

• Local auth with email OTP delivered through MailHog.
• MySQL persistence with migrations and seed data.
• Report creation/list/detail/status/message/assignment/feedback flows.
• Area polygons stored as GeoJSON and matched by backend logic.
• Basic stats for administration.

Out of Scope for Milestone 1

• Real CIE integration.
• Real SMTP provider, SMS, Telegram or WhatsApp notifications.
• Route optimization.
• Public open data export.
• Full Docker packaging of the backend.