feat: update API documentation and project specifications
This commit is contained in:
gabdevele
+114
-40
@@ -1,51 +1,125 @@
|
||||
# Visione Project Spec
|
||||
|
||||
This file describes current implemented product shape, not aspirational backlog.
|
||||
|
||||
## Goal
|
||||
Visione lets citizens report urban problems and lets municipal staff manage,
|
||||
assign and resolve interventions while preserving history and basic analytics.
|
||||
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`: 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, messages citizens and flags abusive/fake citizen content on managed
|
||||
reports.
|
||||
- `admin`: manages users, roles, reference data, teams, areas and all reports.
|
||||
- `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
|
||||
|
||||
The system admin seed must change password before using protected operational
|
||||
or administrative APIs.
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
## 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`)
|
||||
|
||||
Valid milestone 2 transitions:
|
||||
### Reports
|
||||
- create report with category, coordinates, address, description
|
||||
- optional inline media on creation
|
||||
- later media upload up to total 5 files
|
||||
- area inferred by GeoJSON polygon match
|
||||
- citizen report list/detail/history/media
|
||||
- operator queues:
|
||||
- open unassigned
|
||||
- assigned to current operator
|
||||
- assigned to other operators
|
||||
|
||||
- `OPEN -> UNDER_REVIEW` when an operator 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`.
|
||||
### 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
|
||||
|
||||
## MVP Scope
|
||||
- Local auth with email OTP delivered through Mailpit.
|
||||
- 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.
|
||||
### Communication
|
||||
- citizen/operator report chat
|
||||
- local in-app notifications for status, assignment, messages, rewards
|
||||
|
||||
## 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.
|
||||
### 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
|
||||
- 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
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user