# 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.