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.

Use your administrator account credentials at /login

Navigate to Admin Panel

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

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

Surveys Management
News Management
Reports Management

Route: /admin/encuestas

Create new surveys
Edit existing surveys
Activate/deactivate surveys
View response analytics
Set location targeting

Route: /admin/noticias

Publish news articles
Edit/update content
Set geographic scope
Upload featured images
Manage publication status

Route: /admin/reportes

Review citizen reports
Update report status
Add administrator responses
Set priority levels
Mark as resolved
Generate PDF reports

Managing Surveys

Creating a New Survey

Navigate to /admin/encuestas and click Nueva Encuesta.

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

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"
]

Set Geographic Targeting

Location-Based Distribution:

Global Survey
Parish-Level
Neighborhood-Level

Leave Parroquia and Barrio empty✅ Visible to all users regardless of location

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.

Activate Survey

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

Save and Publish

Click Guardar to create the survey and make it available

Survey Location Logic

Understanding Survey Visibility Rules

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

Find Survey

Browse surveys list at /admin/encuestas

Click Edit

Select the survey to modify

Update Fields

Modify any field except:

Survey type (cannot change after creation)
Options (if responses already submitted)

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.

Create News Article

Click Nueva Noticia buttonRequired Fields:

Título: Headline (concise and descriptive)
Contenido: Full article text (supports line breaks)
Ámbito: Geographic scope

Set Geographic Scope

Ámbito Options:

Nacional
Provincial
Cantonal
Parroquial
Barrio

Nationwide news visible to all usersUse for: National holidays, federal announcements

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');

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

Update Published News

Find article in news management list
Click edit icon
Modify content (all fields editable)
Save changes - updates immediately
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:

Pendiente (Pending)

Initial Status

Report just submitted by citizen
Awaiting administrator review
Action: Review report details and assign

En Revisión (Under Review)

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

En Proceso (In Progress)

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

Resuelto (Resolved)

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

Rechazado (Rejected)

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

Reviewing Individual Reports

Each report contains:

Report Information Fields

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

Open Report

Click on report in admin reports list

Review Details

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

Update Status

Select appropriate status from workflow (see above)

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.

Set Resolution Date (if resolved)

When marking as “Resuelto”:

Set fecha_resolucion to current date
Provide resolution details in respuesta_admin

Save Changes

Click Guardar - citizen sees updated status immediately

Report Priority Guidelines

Urgente (Urgent)

Criteria:

Immediate safety hazards
Exposed electrical wires
Major water main breaks
Structural collapse risks
Severe traffic hazards

Response Time: 24-48 hours

Alta (High)

Criteria:

Significant infrastructure issues
Multiple citizens affected
Service disruptions (water, sewage)
Major potholes on primary roads
Public safety concerns

Response Time: 3-5 days

Media (Medium)

Criteria:

Standard maintenance issues
Single street light outages
Minor road damage
Park maintenance
Localized problems

Response Time: 1-2 weeks

Baja (Low)

Criteria:

Cosmetic issues
Non-urgent beautification
Minor signage
Suggestions for improvement

Response Time: 2-4 weeks

Generating PDF Reports

Administrators can export comprehensive reports:

Access Admin Panel

From main admin dashboard (/admin)

Click Export Button

Find “Descargar Informe PDF” button in Reports section

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();

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:

Navigate to Dashboard

Go to /dashboard while logged in as admin

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”)

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

Survey Design

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)

Location Targeting

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

Response Analysis

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

Response Time Guidelines

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

Communication with Citizens

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

Handling Rejections

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:

encuestas
noticias
reportes
usuarios

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

News ArticlesKey fields:

id (UUID)
titulo, contenido
ambito (nacional | provincial | cantonal | parroquial | barrio)
parroquia_destino, barrio_destino
imagen_url
created_at

Citizen ReportsKey fields:

id (UUID)
usuario_id (FK to usuarios)
categoria
descripcion
estado (pendiente | en_revision | en_proceso | resuelto | rechazado)
prioridad (baja | media | alta | urgente)
ubicacion_* (location fields)
respuesta_admin
fecha_resolucion

User AccountsKey fields:

id (UUID, links to Supabase Auth)
nombres, apellidos
cedula, email
tipo (ciudadano | administrador)
parroquia, barrio
activo (boolean)

Authentication & Authorization

Security is implemented through:

Row Level Security (RLS)

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

Route Guards

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

Can't access admin panel

Check:

User tipo field in database = ‘administrador’
Account is activo = true
Logged in with correct credentials
Browser cache cleared
No JavaScript errors in console

Database Query:

SELECT id, email, tipo, activo
FROM usuarios
WHERE email = '[email protected]';

Surveys not appearing for citizens

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

PDF generation fails

Solutions:

Check browser allows downloads
Verify reports exist in database
Check console for JavaScript errors
Try with smaller date range
Ensure useReportePDF composable loaded

Report status not updating

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

System Orientation

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

Hands-On Training

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

Shadow Experienced Admin

Observe report processing workflow
Learn response templates
Understand escalation procedures

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

encuestas Table

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()
);

reportes Table

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)

Get Started

Core Features

User Guides

Development

​Administrator Guide

​Admin Panel Overview

​Accessing the Admin Panel

​Admin Dashboard Features

Total Surveys

Active Surveys

Total Reports

Pending Reports

​Quick Actions

​Managing Surveys

​Creating a New Survey

​Survey Location Logic

​Editing Existing Surveys

​Viewing Survey Results

​Managing News

​Publishing News Articles

​News Filtering Logic

​Editing News Articles

​Managing Citizen Reports

​Reports Dashboard

View All Reports

Update Status

Respond to Citizens

​Report Status Workflow

​Reviewing Individual Reports

​Responding to Reports

​Report Priority Guidelines

​Generating PDF Reports

​User Management

​Administrator Privileges

​Viewing Citizen Dashboard as Admin

​Best Practices for Administrators

​Survey Management

​News Publishing

​Report Management

​System Administration

​Database Access

​Authentication & Authorization

​Analytics and Reporting

​Dashboard Statistics

​Key Metrics to Monitor

Engagement

Service Quality

Content Performance

System Health

​Troubleshooting Admin Issues

​Security Best Practices

​Training and Support

​For New Administrators

​Getting Technical Support

System Administration Contact

​Appendix: Database Schema Reference

​Complete Table Structures

Build docs developers (and LLMs) love

Administrator Guide

Admin Panel Overview

Accessing the Admin Panel

Admin Dashboard Features

Quick Actions

Managing Surveys

Creating a New Survey

Survey Location Logic

Editing Existing Surveys

Viewing Survey Results

Managing News

Publishing News Articles

News Filtering Logic

Editing News Articles

Managing Citizen Reports

Reports Dashboard

Report Status Workflow

Reviewing Individual Reports

Responding to Reports

Report Priority Guidelines

Generating PDF Reports

User Management

Administrator Privileges

Viewing Citizen Dashboard as Admin

Best Practices for Administrators

Survey Management

News Publishing

Report Management

System Administration

Database Access

Authentication & Authorization

Analytics and Reporting

Dashboard Statistics

Key Metrics to Monitor

Troubleshooting Admin Issues

Security Best Practices

Training and Support

For New Administrators

Getting Technical Support

Appendix: Database Schema Reference

Complete Table Structures