129 lines
4.1 KiB
Markdown
129 lines
4.1 KiB
Markdown
# 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
|
|
- password login fallback
|
|
- bearer token auth
|
|
- forced first password change for seed admin
|
|
- 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
|
|
- create/update areas
|
|
area polygons must stay inside Bari municipal boundary
|
|
- create/update teams
|
|
- list users, update roles, ban/unban
|
|
- global stats including area/category/team resolution aggregates
|
|
|
|
### Public Data
|
|
- active 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.
|