Add Visione backend foundation
This commit is contained in:
gabdevele
@@ -0,0 +1,37 @@
|
||||
# Visione API Spec
|
||||
|
||||
Base path: `/api/v1`.
|
||||
|
||||
## Technical
|
||||
- `GET /health`: process health.
|
||||
- `GET /ready`: MySQL readiness.
|
||||
|
||||
## Auth
|
||||
- `POST /auth/register`: create a citizen account.
|
||||
- `POST /auth/otp/request`: send an OTP email through MailHog.
|
||||
- `POST /auth/otp/verify`: verify OTP and create an API token.
|
||||
- `POST /auth/login/password`: password login fallback.
|
||||
- `GET /me`: return the authenticated user.
|
||||
|
||||
Protected endpoints use:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
## Reports
|
||||
- `POST /reports`: create a report.
|
||||
- `GET /reports`: list reports with optional `status`, `category_id`, `area_id`.
|
||||
- `GET /reports/{id}`: report detail.
|
||||
- `PATCH /reports/{id}/status`: update status.
|
||||
- `POST /reports/{id}/messages`: write a report message.
|
||||
- `GET /reports/{id}/messages`: list report messages.
|
||||
- `POST /reports/{id}/assignments`: assign a team.
|
||||
- `POST /reports/{id}/feedback`: add citizen feedback.
|
||||
|
||||
## Admin Reference Data
|
||||
- `GET|POST /admin/categories`
|
||||
- `GET|POST /admin/areas`
|
||||
- `GET|POST /admin/teams`
|
||||
- `GET /admin/stats/overview`
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# Visione Backend Architecture
|
||||
|
||||
## Layout
|
||||
- `controllers/`: Drogon `HttpController` classes.
|
||||
- `services/`: application/business logic.
|
||||
- `repositories/`: database helpers and migrations.
|
||||
- `common/`: reusable HTTP, auth, crypto, email and validation utilities.
|
||||
- `migrations/`: versioned SQL files.
|
||||
- `docs/`: product, API, schema and milestone documentation.
|
||||
|
||||
## Drogon Usage
|
||||
Controllers use Drogon route macros and return JSON with
|
||||
`HttpResponse::newHttpJsonResponse`. Database access uses Drogon's MySQL client
|
||||
with parameterized SQL placeholders.
|
||||
|
||||
The codebase starts with raw SQL repositories because the schema is still
|
||||
evolving. Drogon ORM/codegen can be introduced later after the database model
|
||||
stabilizes.
|
||||
|
||||
## Local Email
|
||||
OTP emails are sent to MailHog over SMTP. MailHog keeps messages local and
|
||||
inspectable through its web UI.
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# Visione Database Schema
|
||||
|
||||
The schema is stored in `migrations/001_initial_schema.sql`.
|
||||
|
||||
Important tables:
|
||||
|
||||
- `users`: identity, personal data, password hash, points and moderation flags.
|
||||
- `roles`, `permissions`, `role_permissions`, `user_roles`: authorization.
|
||||
- `otp_challenges`: local OTP login flow.
|
||||
- `api_tokens`: bearer tokens for the local API.
|
||||
- `report_categories`: report classification.
|
||||
- `areas`: named city areas with GeoJSON polygon boundaries.
|
||||
- `team_categories`, `teams`: municipal intervention teams.
|
||||
- `reports`: citizen reports with coordinates, address, status and area.
|
||||
- `report_status_history`: immutable status transition log.
|
||||
- `assignments`: report-to-team assignment history.
|
||||
- `report_photos`: uploaded photo metadata.
|
||||
- `messages`: citizen/operator report conversation.
|
||||
- `feedback`: citizen rating and comment after resolution.
|
||||
- `reward_events`: indirect gamification points ledger.
|
||||
|
||||
GeoJSON is intentionally used instead of MySQL Spatial in milestone 1 to keep
|
||||
the local setup simple and portable.
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# Visione Backend LLM Context
|
||||
|
||||
Visione is a C++20/Drogon backend for a municipal urban issue reporting system.
|
||||
Citizens create reports with category, position, address, description and photos.
|
||||
Operators manage reports, assign teams, update status and chat with citizens.
|
||||
Admins manage roles, users, areas, teams and reference data.
|
||||
|
||||
The project runs locally on the host machine. Docker is used only for external
|
||||
services such as MySQL and MailHog. Real production deployment and Dockerizing
|
||||
the backend are later delivery tasks.
|
||||
|
||||
Important conventions:
|
||||
|
||||
- Code and database identifiers are English.
|
||||
- The webapp is Italian-facing, so labels or seeded category names may be Italian.
|
||||
- Use Drogon references from `/home/gabdevele/Projects/snitchitaly/backend/drogon`
|
||||
and `https://drogonframework.github.io/drogon-docs/`.
|
||||
- `AGENTS.md` is the durable agent instruction entrypoint.
|
||||
- `docs/MILESTONE_01.md` describes what has been implemented and what comes next.
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# Milestone 01: Local Backend Foundation
|
||||
|
||||
## Implemented in this milestone
|
||||
- Project identity and documentation for Visione.
|
||||
- Root `AGENTS.md` for future coding agents.
|
||||
- Local Docker services for MySQL and MailHog.
|
||||
- Initial MySQL schema and seed data.
|
||||
- Drogon backend structure for auth, reports, admin data and stats.
|
||||
- OTP email delivery through MailHog.
|
||||
- Focused regression tests for technical endpoints and core validation helpers.
|
||||
|
||||
## To do next
|
||||
- Harden password hashing with Argon2id or bcrypt before production.
|
||||
- Add real email provider configuration for non-local environments.
|
||||
- Add CIE/SPID integration design and provider adapters.
|
||||
- Expand frontend-driven API coverage as Vue screens are implemented.
|
||||
- Add file upload handling for real multipart photo upload.
|
||||
- Add notification channels, route optimization and open-data exports.
|
||||
- Dockerize the backend only for final delivery/deployment.
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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 flows.
|
||||
- Area polygons stored as GeoJSON and matched by backend logic.
|
||||
- Basic stats for administration.
|
||||
|
||||
## Out of Scope for Milestone 1
|
||||
- Real CIE integration.
|
||||
- Real SMTP provider, SMS, Telegram or WhatsApp notifications.
|
||||
- Route optimization.
|
||||
- Public open data export.
|
||||
- Full Docker packaging of the backend.
|
||||
|
||||
Reference in New Issue
Block a user