ТИ решаваш! - Документация

Възможности на платформата

Потребителско ръководство

Научете как да подадете сигнал за замърсяване на въздуха в 4 лесни стъпки.

Защо е нужно потвърждение по имейл?

Системата използва double opt-in механизъм за защита от злоупотреби:

• Предотвратява изпращане на сигнали от чужд имейл адрес
• Осигурява, че РИОСВ може да се свърже с вас
• Защитава системата от автоматизирани атаки

Инсталиране като приложение

Можете да инсталирате "ТИ решаваш!" като приложение на вашия телефон или компютър.

На Android (Chrome)

1. Отворете signal.tireshavashzavt.org
2. Натиснете бутона "Инсталирай" в горната част на сайта
3. Или: меню (⋮) → "Добави към начален екран"

На iPhone (Safari)

1. Отворете сайта в Safari
2. Натиснете бутона за споделяне (□↑)
3. Изберете "Add to Home Screen"

Често задавани въпроси

Архитектура на системата

Системата е изградена на принципа "serverless" с използване на Cloudflare инфраструктура.

Детайлна архитектурна диаграма

Пълна архитектурна диаграма на системата

Поток на данните (Double Opt-In)

Диаграма на потока от данни през системата

Технологичен стек

Сигурност и защита

Защита от спам

• Cloudflare Turnstile - невидима CAPTCHA, блокира ботове
• Double opt-in - изисква потвърждение от реален имейл
• Rate limiting - максимум 3 заявки и 1 потвърден сигнал на ден
• Token expiration - линковете изтичат след 24 часа

Защита на данните

• HTTPS only - целият трафик е криптиран
• No cookies - не се използват бисквитки за проследяване
• Minimal data - съхраняваме само необходимото
• Auto-delete - данните се изтриват след 24 часа

Token Security

Валидация на входните данни

Системата използва стриктна валидация на всички полета, както на frontend, така и на backend.

Защо е нужна кирилица за името?

Код за валидация (пример)

// Валидация на име - само кирилица
function validateName(name) {
  const cyrillicPattern = /^[А-Яа-яЁёЍѝ\s\-]+$/;
  if (!cyrillicPattern.test(name)) {
    return { valid: false, error: 'Моля, въведете името си на кирилица' };
  }
  const words = name.split(/\s+/).filter(w => w.length > 0);
  if (words.length < 2) {
    return { valid: false, error: 'Моля, въведете име и фамилия' };
  }
  return { valid: true };
}

// Sanitize на входни данни
function sanitizeInput(input) {
  return input
    .replace(/[<>]/g, '')           // Премахва HTML тагове
    .replace(/javascript:/gi, '')    // Премахва javascript: URLs
    .replace(/on\w+\s*=/gi, '')      // Премахва event handlers
    .replace(/[\x00-\x1F]/g, '')     // Премахва control chars
    .trim();
}

Статистически панел "Гласът на Велико Търново"

Интерактивен публичен панел, който визуализира анонимизирани данни от сигналите и мотивира гражданите да участват.

Концепция: "Заедно правим разлика"

Панелът е проектиран с фокус върху социалното доказателство и поведенческата психология, за да:

• Валидира преживяванията - показва, че проблемът е реален и споделен
• Създава чувство за общност - "Не си сам, 312 души като теб..."
• Мотивира за действие - gamification елементи и progress bars
• Демонстрира momentum - "Тази седмица +18% спрямо миналата"

Секции на панела

1. Hero секция - Емоционален импакт

2. Времева динамика - "Вълната расте"

3. Карта на кварталите - "Горещи точки"

4. Симптоми - "Споделени преживявания"

5. Gamification - "Общността расте"

6. Live feed - "Случва се сега"

Психологически принципи

Технически детайли

API Endpoint

GET /api/public-stats - Връща агрегирана анонимизирана статистика:

{
  "totals": {
    "signals": 847,
    "respondents": 312
  },
  "districts": [
    { "district": "Чолаковци", "count": 189 },
    { "district": "Бузлуджа", "count": 156 }
  ],
  "sources": [...],
  "symptoms": [...],
  "daily": [
    { "date": "2025-01-15", "count": 23 }
  ],
  "weeklyChange": 18,
  "recent": [
    { "time": "преди 3 мин", "district": "Чолаковци", "symptom": "миризма на лепило" }
  ],
  "milestones": {
    "achieved": [{ "target": 100, "name": "Първата искра", "icon": "🔥" }],
    "next": { "target": 1000, "name": "Не може да ни игнорират", "icon": "🎯" },
    "progress": 84,
    "remaining": 153
  }
}

Milestones (Постижения)

Съхранение на данни

-- D1 таблица за анонимизирани данни
CREATE TABLE anonymous_signals (
  id TEXT PRIMARY KEY,
  timestamp TEXT NOT NULL,
  source TEXT NOT NULL,
  district TEXT NOT NULL,
  symptoms TEXT NOT NULL,      -- JSON array
  email_hash TEXT NOT NULL,    -- SHA-256 hash
  created_at INTEGER NOT NULL
);

Автоматично обновяване

• Данните се кешират за 60 секунди (Cache-Control header)
• Фронтенд панелът се обновява автоматично на всяка минута
• Live feed показва последните 10 сигнала

GDPR съответствие

Жизнен цикъл на личните данни в системата

Какви данни събираме

Правно основание

Обработката на данни се извършва на основание:

• Член 6(1)(a) GDPR - Съгласие (чрез изпращане на формата)
• Член 6(1)(e) GDPR - Обществен интерес (сигнали за замърсяване)

Права на субектите

Съхранение в Postal SMTP сървър

Изпратените имейли се обработват през Postal SMTP сървър със следните политики за съхранение:

Изисквания за инсталация

Необходими акаунти

• Cloudflare акаунт (безплатен) - за Pages, Workers, KV, Turnstile
• Postal Server - self-hosted или друг SMTP доставчик
• GitHub акаунт (опционално) - за автоматичен deploy

Локални инструменти

# Node.js 18+
node --version

# npm или yarn
npm --version

# Wrangler CLI
npm install -g wrangler
wrangler --version

Cloudflare услуги

Инсталация стъпка по стъпка

git clone https://github.com/your-org/signal2riosv_vt.git
cd signal2riosv_vt

npm install

wrangler login

# Създайте namespace
wrangler kv:namespace create PENDING_SIGNALS

# Копирайте ID-то и го добавете в wrangler.toml
# [[kv_namespaces]]
# binding = "PENDING_SIGNALS"
# id = "your-namespace-id"

# Turnstile secret key
wrangler pages secret put TURNSTILE_SECRET_KEY

# Postal API key
wrangler pages secret put POSTAL_API_KEY

# Stats key (за /api/stats endpoint)
wrangler pages secret put STATS_KEY

name = "signal-riosv"
pages_build_output_dir = "."

[[kv_namespaces]]
binding = "PENDING_SIGNALS"
id = "your-namespace-id"

[vars]
RIOSV_EMAIL = "riosvt-vt@riosvt-vt.org"
FROM_EMAIL = "noreply@yourdomain.com"
FROM_NAME = "ТИ решаваш!"
POSTAL_API_URL = "https://postal.yourdomain.com"

wrangler pages deploy .

Конфигурация

Променливи на средата

Rate Limiting

Настройките за rate limiting се намират в functions/api/submit.js:

// Rate limiting constants
const MAX_PENDING_PER_DAY = 3;    // Непотвърдени заявки
const MAX_CONFIRMED_PER_DAY = 1;  // Потвърдени сигнали

Turnstile Site Key

Намерете в index.html и заменете:

<div class="cf-turnstile"
     data-sitekey="YOUR_SITE_KEY"
     data-callback="onTurnstileSuccess">
</div>

Deployment стратегии

# Deploy към production
wrangler pages deploy .

# Preview deploy (за тестване)
wrangler pages deploy . --branch=preview

# Build command: (оставете празно)
# Build output directory: /
# Root directory: /

Обновяване на версия

1. Променете версията в index.html (comment + footer)
2. Увеличете cache версията в sw.js
3. Deploy

# index.html
<!-- version 0.3.7 -->

# sw.js
const CACHE_NAME = 'ti-reshavash-v14';

POST /api/submit

Изпраща сигнал и генерира confirmation имейл.

Request

{
  "turnstileToken": "string (required)",
  "signalData": {
    "source": "string",
    "customSource": "string (optional)",
    "district": "string",
    "whenVal": "string (ISO date)",
    "address": "string (optional)",
    "subject": "string (optional)",
    "name": "string (required)",
    "email": "string (required)",
    "phone": "string (optional)",
    "desc": "string (optional)",
    "checks": ["string array"]
  },
  "docxBase64": "string (base64 encoded DOCX)",
  "letterText": "string (plain text of letter)"
}

Response - Success (200)

{
  "success": true,
  "message": "Изпратихме имейл за потвърждение на user@example.com"
}

Response - Rate Limited (429)

{
  "success": false,
  "error": "Достигнахте максималния брой заявки за деня (3).",
  "rateLimited": true
}

Response - Turnstile Failed (400)

{
  "success": false,
  "error": "Turnstile верификацията е неуспешна (timeout-or-duplicate)."
}

GET /api/confirm/:token

Потвърждава сигнала и го изпраща към РИОСВ.

Parameters

Response - Success (200)

HTML страница с потвърждение:

<!DOCTYPE html>
<html>
  <body>
    <h1>Сигналът е изпратен!</h1>
    <p>Ще получите отговор на: user@example.com</p>
  </body>
</html>

Response - Token Expired (404)

HTML страница с грешка и линк за нов сигнал.

Response - Rate Limited (429)

HTML страница: "Вече имате потвърден сигнал за днес."