Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/joaoelian204/Portal-Ciudadano-Manta-web/llms.txt

Use this file to discover all available pages before exploring further.

​
Administrator Guide

This guide provides comprehensive instructions for administrators managing Portal Ciudadano Manta’s content and citizen engagement features.
Administrator access requires special permissions. Only users with tipo: 'administrador' in the database can access admin features.

​
Admin Panel Overview

​
Accessing the Admin Panel

Administrators can access the panel at /admin or /admin/panel.
1

Login with Admin Credentials

Use your administrator account credentials at /login
2

Navigate to Admin Panel

After login, you’re automatically redirected to /admin if you have admin privileges
3

View Dashboard

See real-time statistics and quick access to management sections

​
Admin Dashboard Features

The admin panel (AdminPanel.vue) displays:

Total Surveys

Count of all surveys in system

Active Surveys

Number of currently active surveys

Total Reports

All citizen reports submitted

Pending Reports

Reports awaiting administrator action

​
Quick Actions

Route: /admin/encuestas
  • Create new surveys
  • Edit existing surveys
  • Activate/deactivate surveys
  • View response analytics
  • Set location targeting

​
Managing Surveys

​
Creating a New Survey

Navigate to /admin/encuestas and click Nueva Encuesta.
1

Basic Information

Required Fields:
  • Título: Survey title (clear and concise)
  • Descripción: Detailed explanation of survey purpose
  • Tipo: Select survey type
    • opcion_multiple - Multiple Choice
    • calificacion - Rating Scale (1-5)
    • abierta - Open Response
2

Configure Options (Multiple Choice Only)

For multiple choice surveys:
  • Add at least 2 options
  • Each option should be clear and mutually exclusive
  • Maximum recommended: 6-8 options for usability
// Example options structure:
opciones: [
  "Muy satisfecho",
  "Satisfecho",
  "Neutral",
  "Insatisfecho",
  "Muy insatisfecho"
]
3

Set Geographic Targeting

Location-Based Distribution:
Leave Parroquia and Barrio empty✅ Visible to all users regardless of location
4

Set Timeline

  • Fecha Inicio: Start date (defaults to creation date)
  • Fecha Fin: End date (when survey closes)
Surveys automatically become inactive after fecha_fin. Users cannot respond after this date.
5

Activate Survey

  • Check Activa checkbox to make survey visible to citizens
  • Inactive surveys are hidden from citizen view but saved as drafts
6

Save and Publish

Click Guardar to create the survey and make it available

​
Survey Location Logic

The system implements sophisticated filtering logic (Encuestas.vue:218-252):
// Filtering algorithm:
if (!encuestaParroquia) {
  return true; // Global - visible to all
}

if (!userParroquia) {
  return false; // User has no location - only sees globals
}

if (encuestaParroquia !== userParroquia) {
  return false; // Different parish - not visible
}

if (!encuestaBarrio) {
  return true; // Parish-level - visible to all in parish
}

return encuestaBarrio === userBarrio; // Neighborhood match required
This ensures citizens only see relevant surveys for their location.

​
Editing Existing Surveys

1

Find Survey

Browse surveys list at /admin/encuestas
2

Click Edit

Select the survey to modify
3

Update Fields

Modify any field except:
  • Survey type (cannot change after creation)
  • Options (if responses already submitted)
4

Save Changes

Changes take effect immediately for new responses
Best Practice: If a survey has existing responses, avoid major changes to options or questions as this may invalidate previous data.

​
Viewing Survey Results

The admin panel displays:
  • Total response count
  • Response breakdown by option (multiple choice)
  • Average rating (rating surveys)
  • Individual responses (open-ended)
  • Response timestamps
  • Respondent location data (anonymized)

​
Managing News

​
Publishing News Articles

Navigate to /admin/noticias to manage municipal communications.
1

Create News Article

Click Nueva Noticia buttonRequired Fields:
  • Título: Headline (concise and descriptive)
  • Contenido: Full article text (supports line breaks)
  • Ámbito: Geographic scope
2

Set Geographic Scope

Ámbito Options:
Nationwide news visible to all usersUse for: National holidays, federal announcements
3

Add Featured Image (Optional)

  • Upload image for article preview
  • Recommended size: 1200x630px (Open Graph standard)
  • Supported formats: JPG, PNG
  • Images stored in Supabase Storage
// Image handling in storage.ts
const imageUrl = await uploadImage(file, 'noticias');
4

Review and Publish

  • Preview how article appears to citizens
  • Check location targeting is correct
  • Click Publicar to make live

​
News Filtering Logic

News visibility is determined by ámbito and location fields: 
// News filtering (NoticiaDetalle.vue implementation)
function isNewsVisible(news, user) {
  switch(news.ambito) {
    case 'nacional':
      return true; // All users
    case 'provincial':
      return user.provincia === 'Manabí';
    case 'cantonal':
      return user.canton === 'Manta';
    case 'parroquial':
      return user.parroquia === news.parroquia_destino;
    case 'barrio':
      return user.parroquia === news.parroquia_destino &&
             user.barrio === news.barrio_destino;
  }
}

​
Editing News Articles

  1. Find article in news management list
  2. Click edit icon
  3. Modify content (all fields editable)
  4. Save changes - updates immediately
  5. Consider notification: Major changes may warrant new article
Important: Editing published news updates it for all users immediately. No draft mode for edits.

​
Managing Citizen Reports

​
Reports Dashboard

Access at /admin/reportes to view all citizen-submitted problem reports.

View All Reports

Complete list with filtering options

Update Status

Change report workflow state

Respond to Citizens

Add official responses visible to reporter

​
Report Status Workflow

Reports follow a defined lifecycle:
1

Pendiente (Pending)

Initial Status
  • Report just submitted by citizen
  • Awaiting administrator review
  • Action: Review report details and assign
2

En Revisión (Under Review)

  • Report is being evaluated
  • Checking legitimacy and scope
  • Action: Validate report, assess resources needed
3

En Proceso (In Progress)

  • Work has started on the issue
  • Municipal teams assigned
  • Action: Monitor progress, update citizen
4

Resuelto (Resolved)

  • Issue has been fixed
  • Set fecha_resolucion to current date
  • Action: Add resolution notes, close report
5

Rechazado (Rejected)

  • Report rejected (invalid, duplicate, or out of scope)
  • Action Required: Add explanation in respuesta_admin

​
Reviewing Individual Reports

Each report contains:
Problem Details:
  • categoria: Problem type (alumbrado, baches, etc.)
  • descripcion: Citizen’s description (includes título + descripción)
  • prioridad: Urgency level set by citizen
  • imagen_url: Photo evidence (if provided)
Location Data:
  • ubicacion_parroquia: Parish
  • ubicacion_barrio: Neighborhood
  • ubicacion_direccion: Street address
  • ubicacion_lat / ubicacion_lng: GPS coordinates
Citizen Information:
  • Reporter name and email (from usuarios table)
  • Contact phone (if provided)
  • Submission timestamp
Administrative:
  • estado: Current status
  • respuesta_admin: Your response to citizen
  • fecha_resolucion: Date resolved (if applicable)
  • created_at: Submission date

​
Responding to Reports

1

Open Report

Click on report in admin reports list
2

Review Details

  • Check location on integrated map
  • View uploaded photos
  • Assess priority and category
3

Update Status

Select appropriate status from workflow (see above)
4

Add Administrator Response

In respuesta_admin field, provide:
  • Acknowledgment of report
  • Expected timeline for resolution
  • Additional information needed (if any)
  • Final resolution notes (when closing)
Response appears on citizen’s Dashboard in a blue highlighted box. Be clear and professional.
5

Set Resolution Date (if resolved)

When marking as “Resuelto”:
  • Set fecha_resolucion to current date
  • Provide resolution details in respuesta_admin
6

Save Changes

Click Guardar - citizen sees updated status immediately

​
Report Priority Guidelines

Criteria:
  • Immediate safety hazards
  • Exposed electrical wires
  • Major water main breaks
  • Structural collapse risks
  • Severe traffic hazards
Response Time: 24-48 hours
Criteria:
  • Significant infrastructure issues
  • Multiple citizens affected
  • Service disruptions (water, sewage)
  • Major potholes on primary roads
  • Public safety concerns
Response Time: 3-5 days
Criteria:
  • Standard maintenance issues
  • Single street light outages
  • Minor road damage
  • Park maintenance
  • Localized problems
Response Time: 1-2 weeks
Criteria:
  • Cosmetic issues
  • Non-urgent beautification
  • Minor signage
  • Suggestions for improvement
Response Time: 2-4 weeks

​
Generating PDF Reports

Administrators can export comprehensive reports:
1

Access Admin Panel

From main admin dashboard (/admin)
2

Click Export Button

Find “Descargar Informe PDF” button in Reports section
3

Wait for Generation

PDF generation uses useReportePDF composable:
  • Fetches all reports from database
  • Formats data with statistics
  • Generates professional PDF
// From AdminPanel.vue:404
const resultado = await generarInformePDF();
4

Download File

PDF downloads automatically with format: Informe_Reportes_[Date].pdf
PDF includes:
  • Summary statistics by status
  • Category breakdown
  • Priority distribution
  • Recent reports with details
  • Charts and visualizations

​
User Management

​
Administrator Privileges

Users with tipo: 'administrador' have access to:
  • Full admin panel at /admin
  • All management routes (/admin/*)
  • CRUD operations on surveys, news, reports
  • View all citizen data
  • Generate system reports
  • Preview citizen dashboard (special banner shown)

​
Viewing Citizen Dashboard as Admin

Administrators can preview citizen experience:
1

Navigate to Dashboard

Go to /dashboard while logged in as admin
2

Special Preview Mode

Purple banner appears at top:
“👁️ Modo Previsualización: Estás viendo el portal como lo vería un ciudadano”
(“Preview Mode: You’re viewing the portal as a citizen would”)
3

Return to Admin

Click “Volver al Panel” button to return to admin interface
This feature (from Dashboard.vue:19-105) helps administrators understand the citizen experience without needing a separate account.

​
Best Practices for Administrators

​
Survey Management

Effective Surveys:
  • Clear, unambiguous questions
  • Reasonable number of options (4-6 for multiple choice)
  • Appropriate survey type for data needed
  • Realistic timeframes (2-4 weeks typical)
Avoid:
  • Leading questions
  • Too many open-ended questions (response fatigue)
  • Overlapping answer choices
  • Very short deadlines (<1 week)
Strategy:
  • Use global surveys for city-wide topics
  • Parish-level for infrastructure planning
  • Neighborhood-level for very localized issues
Examples:
  • Budget priorities → Global
  • New park location → Parish-level
  • Street paving order → Neighborhood-level
  • Review responses regularly (weekly recommended)
  • Look for patterns across demographics
  • Compare responses across locations
  • Use data to inform municipal decisions
  • Share results with community (publish as news)

​
News Publishing

Quality Standards:
  • Accurate, fact-checked information
  • Professional tone and formatting
  • High-quality images with proper attribution
  • Correct geographic scope to avoid spam
  • Regular updates (aim for 2-3 articles/week)
  • Mix of topics (events, services, alerts)

​
Report Management

Acknowledge Quickly:
  • Initial response within 48 hours for all reports
  • Update status even if resolution takes time
  • Set realistic expectations in responses
Status Updates:
  • Change status as work progresses
  • Don’t leave reports in “Pendiente” >1 week
  • Use “En Proceso” to show active work
Professional Responses:
  • Acknowledge receipt and thank reporter
  • Explain what will be done
  • Provide estimated timeline
  • Use formal but friendly tone
  • Sign with department/name
Example Response:
Estimado/a ciudadano/a,

Gracias por reportar el problema de alumbrado en Av. Principal.
Hemos programado una inspección para esta semana y esperamos
resolver el problema en un plazo de 10 días laborables.

Le mantendremos informado del progreso.

Atentamente,
Departamento de Obras Públicas
GAD Municipal de Manta
When rejecting a report:
  • Always explain why in respuesta_admin
  • Common reasons:
    • Duplicate report (reference original)
    • Outside municipal jurisdiction
    • Insufficient information
    • Not a valid issue
  • Offer alternative action if possible
  • Be respectful and constructive

​
System Administration

​
Database Access

Administrators work with these Supabase tables:
Survey DataKey fields:
  • id (UUID)
  • titulo, descripcion
  • tipo (opcion_multiple | calificacion | abierta)
  • opciones (JSONB array)
  • parroquia_destino, barrio_destino
  • activa (boolean)
  • fecha_inicio, fecha_fin

​
Authentication & Authorization

Security is implemented through:
Supabase RLS policies control data access:
-- Example: Only admins can modify reports
CREATE POLICY "Admins can update reports"
ON reportes FOR UPDATE
USING (
  EXISTS (
    SELECT 1 FROM usuarios
    WHERE usuarios.id = auth.uid()
    AND usuarios.tipo = 'administrador'
  )
);
  • Citizens can only read their own reports
  • Admins have full CRUD access
  • Surveys/news follow similar patterns
Frontend protection (router/index.ts:186-234):
// Admin route protection
if (isAdminRoute && isAuthenticated && !isAdmin) {
  return next({ name: 'Dashboard' });
}
  • Checks authStore.isAdministrador()
  • Redirects non-admins to citizen dashboard
  • Validates on every navigation

​
Analytics and Reporting

​
Dashboard Statistics

The admin panel shows real-time counts: 
// Statistics from AdminPanel.vue:371-398
const totalReportes = ref(0);
const reportesPendientes = ref(0);
const encuestasActivas = computed(() => {
  return encuestas.value.filter(e => e.activa).length;
});

​
Key Metrics to Monitor

Engagement

  • Survey response rates
  • Average response time
  • User participation trends
  • Geographic distribution

Service Quality

  • Report resolution time by priority
  • Pending report backlog
  • Citizen satisfaction (from surveys)
  • Repeat reports (same issue)

Content Performance

  • News article views
  • Most engaged neighborhoods
  • Survey completion rates
  • Peak usage times

System Health

  • Active user count
  • New registrations
  • Platform errors
  • Response times

​
Troubleshooting Admin Issues

Check:
  1. User tipo field in database = ‘administrador’
  2. Account is activo = true
  3. Logged in with correct credentials
  4. Browser cache cleared
  5. No JavaScript errors in console
Database Query:
SELECT id, email, tipo, activo
FROM usuarios
WHERE email = 'your@email.com';
Common causes:
  • Survey not marked as activa = true
  • Location targeting too specific
  • End date (fecha_fin) has passed
  • Citizens don’t have location set in profile
Test:
  • Create test survey with no location
  • Verify it appears for all users
  • Check browser console for filtering errors
Solutions:
  • Check browser allows downloads
  • Verify reports exist in database
  • Check console for JavaScript errors
  • Try with smaller date range
  • Ensure useReportePDF composable loaded
Verify:
  • Database connection active
  • RLS policies allow admin updates
  • No validation errors on save
  • respuesta_admin not exceeding text limit
  • Refresh page after save to confirm

​
Security Best Practices

Administrator Account Security
  • Use strong, unique passwords
  • Enable 2FA if available
  • Never share admin credentials
  • Log out when finished
  • Monitor audit logs for suspicious activity
  • Review user permissions regularly
Data Protection:
  • Citizens’ personal data is protected by RLS
  • Only access data necessary for your role
  • Don’t export citizen data unnecessarily
  • Follow GDPR/data privacy regulations
  • Report security concerns immediately

​
Training and Support

​
For New Administrators

1

System Orientation

  • Review this guide completely
  • Explore admin panel interface
  • Test all features in staging environment
2

Hands-On Training

  • Create test survey (mark inactive)
  • Publish test news article
  • Process sample citizen report
  • Generate PDF report
3

Shadow Experienced Admin

  • Observe report processing workflow
  • Learn response templates
  • Understand escalation procedures
4

Independent Practice

  • Handle 5-10 reports under supervision
  • Create actual survey with review
  • Publish news with editing review

​
Getting Technical Support

System Administration Contact

For technical issues beyond this guide:
  • Database access problems
  • Permission configuration
  • System errors or bugs
  • Feature requests
Contact: Technical team via internal channels

​
Appendix: Database Schema Reference

​
Complete Table Structures

CREATE TABLE encuestas (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  titulo TEXT NOT NULL,
  descripcion TEXT NOT NULL,
  tipo TEXT NOT NULL CHECK (tipo IN ('opcion_multiple', 'calificacion', 'abierta')),
  opciones JSONB,
  parroquia_destino TEXT,
  barrio_destino TEXT,
  activa BOOLEAN DEFAULT true,
  fecha_inicio TIMESTAMP DEFAULT NOW(),
  fecha_fin TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE reportes (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  usuario_id UUID REFERENCES usuarios(id),
  categoria TEXT NOT NULL,
  descripcion TEXT NOT NULL,
  estado TEXT DEFAULT 'pendiente',
  prioridad TEXT DEFAULT 'media',
  ubicacion_parroquia TEXT,
  ubicacion_barrio TEXT,
  ubicacion_direccion TEXT,
  ubicacion_lat DECIMAL(10, 8),
  ubicacion_lng DECIMAL(11, 8),
  imagen_url TEXT,
  respuesta_admin TEXT,
  fecha_resolucion TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);
Document Version: 1.0
Last Updated: Based on Portal Ciudadano Manta v1.0.0
Platform Standards: ISO 9241-11 (Usability), ISO 9241-210 (Human-Centered Design)