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.

Valid milestone 2 transitions:

• OPEN -> UNDER_REVIEW when an operator/admin takes the report.
• UNDER_REVIEW -> ASSIGNED when a team is assigned.
• ASSIGNED -> IN_PROGRESS.
• IN_PROGRESS -> RESOLVED.
• RESOLVED -> CLOSED.
• OPEN/UNDER_REVIEW/ASSIGNED/IN_PROGRESS -> REJECTED only for invalid reports.
• REJECTED -> CLOSED.

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/moderation flows.
• Area polygons stored as GeoJSON and matched by backend logic.
• Operator queues for assigned, open and other-operator reports.
• Local in-app notifications and reward points ledger.
• Public anonymized open-data report export.
• Basic and segmented stats for administration.

Out of Scope for the Local Backend MVP

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