Add report workflow

docs/API_SPEC.md

@@ -25,11 +25,12 @@ Authorization: Bearer <token>
 - `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}/take`: operator/admin takes an open report.
 - `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.
-- `POST /reports/{id}/photos`: upload one or more multipart files for a report.
+- `POST /reports/{id}/photos`: upload up to five JPEG/PNG/WebP multipart files.
 
 ## Admin Reference Data
 - `GET|POST /admin/categories`

docs/DATABASE_SCHEMA.md

@@ -11,14 +11,13 @@ Important tables:
 - `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.
+- `reports`: citizen reports with coordinates, address, status, area and assigned operator.
 - `report_status_history`: immutable status transition log.
 - `assignments`: report-to-team assignment history.
-- `report_photos`: uploaded photo metadata.
+- `report_photos`: uploaded photo URL, original filename, content type and size.
 - `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.
-

docs/MILESTONE_02.md

@@ -0,0 +1,19 @@
+# Milestone 02: Workflow Core and Hardening
+
+## Implemented in this milestone
+- Documentation/config fixes from Milestone 01 review.
+- Authorization context with roles, permissions and forced password-change state.
+- Authenticated password change endpoint.
+- Admin user listing, role assignment and ban/unban endpoints.
+- Report ownership workflow with assigned operator and take endpoint.
+- Valid report status transitions.
+- Citizen report filters scoped to own reports.
+- Report photo upload validation and metadata storage.
+
+## To do next
+- Add broader API tests once the frontend contracts stabilize.
+- Add notification delivery for status changes.
+- Add moderation flow for abusive reports/messages.
+- Add open-data exports and statistics refinements.
+- Design CIE/SPID integration.
+

docs/PROJECT_SPEC.md

@@ -23,6 +23,16 @@ or administrative APIs.
 - `REJECTED`: report was invalid or abusive.
 - `CLOSED`: administrative closure after feedback or final review.
 
+Valid milestone 2 transitions:
+
+- `OPEN -> UNDER_REVIEW` when an operator/admin 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`.
+
 ## MVP Scope
 - Local auth with email OTP delivered through MailHog.
 - MySQL persistence with migrations and seed data.