Отчёты, шаблоны, вложения и доставки

ReportSurveyTemplate

Префикс: rprts_ Таблица: report_survey_template Файл: garden/modules/report/models/report.py

Шаблон отчёта в формате SurveyJS.

Constraints:

• uq_template_name_version — одно сочетание (name, version) уникально.
• uq_only_one_default_template — ровно один шаблон может иметь is_default=True (partial unique constraint).

Если при сохранении шаблону ставится is_default=True, метод save() автоматически снимает флаг с остальных.

Дефолтный шаблон создаётся командой:

python manage.py seed_report_templates

Report

Префикс: rprt_ Таблица: report Файл: garden/modules/report/models/report.py

Отчёт по наряду. Связь с нарядом — 1:1 через OneToOneField.

History подключена с excluded_fields=["survey_data", "template_json_snapshot"] — JSON-поля не пишутся в historical_report, чтобы не раздувать историю.

Снимок шаблона

В момент создания отчёта (когда Report._state.adding истинный, а template_json_snapshot пустой) метод save() копирует весь шаблон в snapshot-поля:

self.template_name_snapshot = tpl.name
self.template_version_snapshot = tpl.version
self.template_json_snapshot = tpl.template_json

Зачем это нужно. Если потом изменить шаблон в ReportSurveyTemplate.template_json — уже созданные отчёты продолжат использовать ту версию схемы, по которой их собирали. Это:

1. Гарантирует валидность данных — survey_data всегда соответствует своему шаблону.
2. Поддерживает обратную совместимость — старые отчёты со старыми полями (*-person-count / *-hours-count) корректно отображаются и считаются.
3. Делает шаблоны иммутабельными для исторических данных.

Статусная машина

Поле sent_to_client поднимается отдельно — через POST /reports/{id}/survey/send-to-client/. Это действие отправляет REPORT_READY контактным лицам.

Эндпоинты отчёта

FileAttachment

Префикс: file_ Таблица: file_attachment

Файл, прикреплённый к отчёту.

URL не хранится. Метод build_presigned_url(expires_seconds=3600) генерирует подписанную ссылку на лету. Это даёт короткоживущие ссылки и не требует публичности bucket.

ReportDelivery

Префикс: rprtdel_ Таблица: report_delivery Файл: garden/modules/report/models/delivery.py

Запись о попытке доставки уведомления — фиксирует канал, статус, время, ошибки и payload.

Constraint delivery_has_report_or_service_visit:

CheckConstraint(
    check=Q(report__isnull=False) | Q(service_visit__isnull=False),
    name="delivery_has_report_or_service_visit",
)

Хотя бы одно из двух полей должно быть заполнено. Для большинства топиков заполнены оба (через report.service_visit); для work_started / work_completed — только service_visit (отчёта ещё / уже нет в фокусе).

Жизненный цикл доставки

opened достижим напрямую из sent, потому что Resend tracking pixel может сработать до (или вместо) события delivered.

Эндпоинт report-summary

GET /api/reports/{id}/report-summary/ — публичный (для авторизованных и для держателей прямой ссылки) — возвращает агрегированный отчёт:

{
  "service_visit": {...},
  "object": {...},
  "client": {...},
  "blocks": {
    "standard_care": {
      "is_active": true,
      "people": 3,
      "hours": 10.0,
      "comment": "..."
    },
    "topiary_cut": {...},
    "materials": [...],
    "services": [...]
  },
  "files": [...]
}

Расчёт людей и часов — через утилиту calculate_man_hours(survey_data, work_type):

def calculate_man_hours(survey_data, work_type):
    workers_key      = f"{work_type}-workers"
    person_count_key = f"{work_type}-person-count"
    hours_count_key  = f"{work_type}-hours-count"

    if workers_key in survey_data:
        # Новый формат — массив {worker_id, hours}
        workers = survey_data[workers_key]
        return len(workers), sum(w.get("hours", 0) for w in workers)
    elif person_count_key in survey_data:
        # Старый формат — people × hours
        p = survey_data.get(person_count_key, 0)
        h = survey_data.get(hours_count_key, 0)
        return p, p * h
    return 0, 0.0

Это поддерживает обе версии формы (со слайдерами и с matrixdynamic) одновременно, без миграции данных.