backend/docs/PROJECT_SPEC.md

Visione Project Spec

This file describes current implemented product shape, not aspirational backlog.

Goal

Visione lets citizens report urban issues and lets municipal staff manage report workflow, communicate with citizens, assign real external intervention teams, moderate abuse, and inspect operational stats.

Roles

• citizen register, login, create reports, read own reports, chat, upload media, read notifications, read rewards, leave feedback on resolved reports
• operator read all reports, take open reports, own workflow, assign external teams, change statuses, chat with citizens, create moderation flags, generate public intervention links
• admin all operator powers plus user/role management, reference data management, moderation approval, bans, stats

Product Model

• Citizens use platform directly.
• Operators use platform directly.
• External intervention teams do not authenticate to platform.
• Teams receive public read-only intervention summary through revocable link.

Implemented Features

Auth

• citizen registration
• OTP login through Mailpit
• bearer token auth
• profile read + limited self-edit (first_name, last_name, phone)

Reports

• create report with category, coordinates, address, description
• optional inline media on creation
• later media upload up to total 5 files
• coordinates must stay inside Bari municipal boundary
• area inferred by GeoJSON polygon match
• citizen report list/detail/history/media
• operator queues:
  • open unassigned
  • assigned to current operator
  • assigned to other operators

Workflow

• statuses: OPEN, UNDER_REVIEW, ASSIGNED, IN_PROGRESS, RESOLVED, REJECTED, CLOSED
• valid transitions enforced in backend
• take claims open report into UNDER_REVIEW
• team assignment can directly claim open report and move to ASSIGNED
• owner on platform remains operator, not team

Communication

• citizen/operator report chat
• local in-app notifications for status, assignment, messages, rewards

External Team Handling

• external teams are reference data, not platform accounts
• active teams filtered for operator list
• suggestion endpoint recommends compatible teams by category mapping and area
• operator/admin can create or revoke public intervention summary link
• public summary exposes operational info needed on field: location, description, media, assigned team, masked citizen identity, phone

Moderation

• operator can flag report or message on owned report
• admin resolves or dismisses flag
• admin can reject report during moderation decision

Rewards / Feedback

• reward events ledger
• points awarded on resolved/closed report, deduplicated by (report_id, reason)
• citizen feedback allowed only on RESOLVED
• feedback does not auto-close report

Admin

• create/update categories
• soft-delete categories
• create/update areas area polygons must stay inside Bari municipal boundary
• delete areas
• create/update teams
• soft-delete teams
• list users, update roles, ban/unban
• global stats including area/category/team resolution aggregates

Public Data

• area list
• anonymized resolved/closed open-data export
• public intervention token endpoint
• open-data output filtered to Bari municipal boundary

Current Workflow Summary

Citizen

1. register/login
2. create report
3. report starts OPEN
4. follow history/status
5. chat with operator if needed
6. receive notifications
7. leave feedback when resolved

Operator

1. inspect open queue
2. take or assign external team directly
3. become report owner on platform
4. update status / chat / flag abuse
5. generate public intervention link for team

Admin

1. manage users and reference data
2. approve moderation decisions
3. inspect stats

Out Of Scope Today

• real CIE/SPID integration
• production email/SMS/Telegram/WhatsApp notifications
• routing optimization for teams
• team platform accounts
• citizen-facing frontend in this repo
• hard-delete lifecycle for reference data

Product Truth Rules

• Code truth beats stale docs.
• Route truth: controller headers.
• Business truth: services.
• DB truth: migrations.