Воркфлоу задач

Статуси, переходи, автоматичне створення креативів, неймінг, сповіщення в Slack і Google Drive.

Документ описує, як працює виробничий воркфлоу задач на бекенді kumquat: статуси, переходи, автоматичне створення креативів, неймінг, сповіщення в Slack і роботу з Google Drive.

Основні файли:

• kumquat_tasks/enums.py — статуси, дозволені переходи (ALLOWED_TRANSITIONS), групи типів задач, стан автоматизації.
• kumquat_tasks/field_policy.py — які поля редагуються/обов’язкові/сховані для стану задачі.
• kumquat_tasks/workflow/transitions.py — перевірка переходів.
• kumquat_tasks/workflow/handlers.py — обробники статусів.
• kumquat_tasks/workflow/creative_factory.py — генерація креативів і неймінг.
• kumquat_tasks/workflow/legacy_remap.py — розбір Legacy Remap List.
• kumquat_tasks/notifications.py — сповіщення в Slack; kumquat_tasks/drive.py — папки Google Drive.
• kumquat_api/routes/tasks.py — ендпоінт зміни статусу.
• kumquat_api/worker/tasks.py — Celery-задача.

Задача і креатив

• Задача (Task) — одиниця виробництва. Вона групує креативи, які з неї виходять, і несе таксономію (продукт, тип задачі, медіатип, мову тощо), кількість, дедлайн, людей і статус.
• Креатив (Creative) — конкретна відео/статик-картка, що йде в тестування в рекламному кабінеті. Кожен креатив належить одній задачі (task_id).
• Зв’язки не дублюються масивами: «креативи задачі» — це запит find({task_id}), «похідні креативи» — запит по origin_ref. Джерело правди — сам документ, а не збережені списки id.
• Люди: Task Owner — постановник задачі; Assignee — виконавець.

Два поля-посилання на вихідні креативи:

• origin_creative_id — один вихідний креатив, обов’язковий для VAR/VARDES/VARAI.
• source_creative_ids — кілька вихідних креативів, для LOC/WHT/ADPT/RSZ.

Види задач (Task Type)

Task Type визначає, як автоматизація створює креативи і звідки бере дані.

LOC/WHT/ADPT/RSZ — похідні задачі: беруть готові креативи (Source Creatives) і роблять їхню локалізовану / відбілену / адаптовану / ресайзнуту версію. VAR/VARDES/VARAI — варіації від одного оригіналу (Origin Creative).

Робочі напрями (Work Stream)

Performance, Product, Web, Brand, SMM, HR. Автоматизація обробляє лише Performance; задачі інших напрямів ігноруються (задача повертається в backlog зі станом warning).

Довідники

• Продукти (product_id): PLT (PlantIn), CNI (CoinIn), RKI (RockIn), SPD (SportDex).
• Media Type: VID (відео), STA (статик), ANI (аніма/gif), WEB, LND (лендинг).
• Resolution (розмір готового файлу): 1080x1920, 1920x1080, 640x768, 800x800, 320x50, 1080x1350, 250x250, 300x250, 336x280, 200x200, 300x600, 1242x2688, 1080x1080, 600x800, 800x600.
• Source (рекламна платформа): META, TIK (TikTok), APL (AppLovin), GGL (Google), SNA (Snapchat), SKN, TAB, UNT (Unity).
• Language: EN, FR, DE, ES, PT, UA тощо — локаль креативу; для LOC кодує цільову мову (гео в назві не бере участі).
• Design Complexity / Marketing Complexity — 1–5 кожна: складність задачі окремо для дизайну й для маркетингу. У Points іде лише Design Complexity. Priority — 1–3 (🔴/🟡/⚪).
• Modifier (на креативі, зазвичай проставляється вручну): HK1/HK2/HK3 (варіант хука), UC, AI, RSIZ (ресайз), CTA1/CTA2, PX.
• Varied Element (що варіюється в задачі): hook, cta, body_concept, background, hook_script, voice, music, persona.

Два незалежні статуси

У задачі є два окремі статус-поля, які не пов’язані між собою:

• status (TaskStatus) — виробничий процес (від постановки задачі до здачі файлів).
• test_status (TestStatus) — стан у рекламному кабінеті (не тестувався / тестується / протестовано / на паузі).

Задача може бути done по виробництву і водночас tested у рекламі — це нормально. Автоматика описана нижче реагує тільки на status. test_status змінюється звичайним оновленням задачі.

Статуси і потік

backlog → ready_for_production → in_progress → tech_check / creative_check → done → archived

Дозволені переходи описані в ALLOWED_TRANSITIONS (kumquat_tasks/enums.py). З backlog є рівно один вихід — ready_for_production: це той перехід, що запускає автоматизацію, і без нього немає ні назви, ні папки Drive. Заборонено перестрибувати етапи (наприклад backlog → done); частина зворотних переходів дозволена для правок (наприклад done → in_progress); archived — кінцевий, виходів немає.

Як змінюється статус

Статус змінюється тільки через окремий ендпоінт:

PATCH /api/v1/tasks/{task_id}/status
{ "target_status": "ready_for_production" }

Поле status навмисно прибране зі звичайного PATCH /tasks/{id} — так зміна статусу завжди проходить через перевірки й запускає побічні ефекти.

З того самого міркування — і на крок далі — started_at / submitted_at / completed_at немає ні в TaskUpdate, ні в TaskCreate. Їх ставить сам воркфлоу: перше — перехід у in_progress, решту — хендлери за перевірками, і пишуть вони через репозиторій, який цими схемами не проходить. Тобто по HTTP їх не виставить ніхто — ні правкою, ні створенням задачі; клієнт, який їх усе одно надішле, отримає те саме, що й зі status — поля просто проігнорують (extra="ignore"), а не 422. У формі вони read-only.

TaskCreate тримає їх поза схемою окремо від TaskUpdate: новостворена задача сидить у backlog і за визначенням ще нікуди не рухалася, тож дати старту, здачі й завершення в неї бути не може. Виняток — легасі-імпорт (backend/scripts/backfill_creatives.py), який проставляє completed_at з вивантаженої таблиці; він збирає Task напряму й через цю схему не йде.

Поля, які схема пропускає, все одно проходять через політику полів (розділ нижче): те, що поле є в TaskUpdate, не означає, що його можна записати в будь-якому статусі.

Передумови входу в статус (REQUIRED_TO_ENTER)

Окрім графа переходів, статус може вимагати, щоб задача вже щось несла до моменту переїзду. Сьогодні їх два:

Перший пункт свідомо дублює те, що перевірить _validate, і робить це раніше: інакше задача переїжджає, прогон падає й _revert вертає її в Backlog з банером — довгий шлях, щоб сказати «заповніть два поля». Решту входів прогону так не піднято: вони питаються ще при створенні, тож задача без них — вже крайній випадок, і його ловить прогон.

in_progress навмисно не повторює обидві Complexity, хоч і стоїть за Ready for Production: кожен вхід у нього йде через двері RFP — прямий перехід або повернення з Tech / Creative Check, куди інакше як через RFP не потрапити. Друга копія того самого правила лише дала б їм нагоду розійтися. Ціна цього рішення відома: обидві Complexity лишаються редагованими до Creative Check (PLANNING_FIELDS), а required_fields віддається формі, а не перевіряється на записі — тож PATCH з явним null їх таки очистить, і задача доїде в In Progress без них. Наслідок видимий, але не фатальний: points_for_level без відповідної складності віддає None лише для тієї сторони — Execution Points чи Creation Points у картки просто немає, а форма показує рядок як обов’язковий незаповнений.

Це не політика полів: field_policy.py відповідає, що можна записати в статусі, який задача вже тримає, а це — умова прибуття. assignee_id лишається редагованим скрізь. Перевірка стоїть у transition_status поряд з assert_transition_allowed, до будь-якого запису, тож відмова не лишає ні рядка історії, ні напівзастосованого стану. Область та сама, що й у графа — тільки Performance.

Відмова — 409 MissingForStatusError з полем у тексті. Але доходити до неї не мало б: матриця віддається в status_schema.required_to_enter (GET /tasks/schema і meta.status_schema), тож селект статусу гасить пункт, а колонка дошки не приймає картку — та сама причина, з якої віддається граф переходів, і те саме правило, не друга його копія. Клієнт, який отримав відповідь без цього поля, не блокує нічого: сервер відмовить у будь-якому разі.

drive_url у Performance-задачі теж пише тільки автоматизація — разом із drive_folder_id, який жодна форма подати не може. Спроба виставити його руками (у POST /tasks чи в PATCH /tasks/{id}) відхиляється — DriveLinkNotEditableError, 422. Перевірка стоїть після дифу зі збереженою задачею, тож клієнт, який просто відлунює вже записане посилання, помилки не дістає; очищення (null) теж дозволене — це не вказівка на папку. Решта воркстрімів автоматизацію не запускає, тому для них поле лишається звичайним редагованим.

Обробка ділиться на дві частини.

Синхронна (в межах запиту, мілісекунди):

1. Перевірка переходу через assert_transition_allowed. Недозволений перехід → 409.
2. Запис нового статусу. Для in_progress проставляється started_at (лише якщо ще порожній). Для статусів із побічними ефектами automation.state ставиться в pending.
3. Запис рядка в колекцію task_transitions (аудит: звідки, куди, хто, коли).
4. Для статусів ready_for_production, tech_check, creative_check, done — постановка Celery-задачі tasks.transition у чергу (Redis).

Асинхронна (Celery-воркер, секунди):

Воркер (worker/tasks.py::run_task_transition) створює клієнтів (Mongo, Slack, Drive) через services/integrations/factory.py, дістає задачу і викликає відповідний обробник у TaskWorkflowHandlers. Обробники ніколи не падають через помилку Slack/Drive — такі збої логуються, а не зупиняють процес.

Ланцюжок kumquat_core не імпортує kumquat_api: постановку задачі в чергу робить залежність get_transition_enqueuer на рівні роута (той самий підхід, що й у графах — get_run_enqueuer).

Політика полів (field_policy.py)

Одна декларація відповідає на три питання про поле — редаговане / обов’язкове / сховане — для пари «стан задачі × хто питає». Її читають три місця: TasksService.update_task (enforcement), TaskWorkflowHandlers._validate (обов’язковість перед прогоном) і API, який віддає її фронтенду.

До цього правило «naming-поля Performance-задачі редагуються лише в Backlog» існувало тільки на фронтенді. PATCH /api/v1/tasks/{id} з {"product_id": "CNI"} на задачі в done приймався, і з цього моменту generated_name, назви карток креативів і папка {Product}/{TaskName} описували щось інше — без жодної помилки. Будь-яка інтеграція чи curl обходили замок повністю.

Групи полів

Кожне записуване поле TaskUpdate належить рівно одній групі. Це перевіряється тестом (set(TaskUpdate.model_fields) == ALL_WRITABLE_FIELDS у tests/tasks/test_field_policy.py), тому нове поле без групи — падіння тесту, а не тихо відкрите поле в кожному статусі.

Матриця

EDITABLE_BY_STATUS, для work_stream = Performance:

Поверх матриці — оверлеї, перший збіг виграє (editable_fields):

1. роль нижче creator → нічого;
2. deleted_at заповнений → нічого (вихід один — restore);
3. Task.automation_running → нічого (ширше за будь-який рядок: хендлер будує зі знімка);
4. work_stream != Performance → все (автоматизація не запускається, розсинхронювати нічого);
5. інакше — рядок матриці.

locked_fields() — доповнення до editable_fields(), де кожне поле несе причину (LockReason: status / role / deleted / automation_running / automation_owned). Причина потрібна UI: «автоматизація володіє цим полем» і «поверни задачу в Backlog» — різні тексти, і друге для drive_url було б тупиком.

Enforcement

TasksService._assert_fields_editable викликається в update_task після дифу зі збереженою задачею, поруч з _assert_drive_link_editable: клієнт, що відлунює незмінене значення, нічого не редагує, і taskUpdateDelta на фронті теж посилає лише те, що зрушило. Судиться проти збереженої задачі, не проти payload — status через цю схему не ходить, а work_stream сам лежить у NAMING_FIELDS, тож поза Backlog його не зрушити.

Порушення → TaskFieldLockedError → 409 з переліком полів і статусом, у який треба перемістити задачу. Помилка гучна навмисно: тихо відкинутий ключ лишає інтеграцію в переконанні, що запис відбувся.

Замок «прогон іде» тут не питається — він стоїть усередині самого запису (TasksRepository.update_unless_automation_running), де читання і перевірка не можуть розійтися.

Обов’язковість і видимість

required_fields(work_stream, task_type, has_legacy_remap=...) — те, що _validate перевіряє перед прогоном, і те, що форма малює зірочкою. Одне джерело замість двох: форма раніше не позначала execution_complexity / creation_complexity, і задача без них їхала в ready_for_production, щоб за секунду вернутись у backlog з Missing required fields.

number у наборі навмисно немає, хоч _validate його й перевіряє: його призначає next_task_number на створенні, тож зірочка стояла б на полі, яке ніхто не може заповнити. count і поля походження лишають собі власні повідомлення ("Count is empty or 0", "No origin creative") — «missing» про них сказало б менше.

hidden_fields(work_stream, task_type) — TAXONOMY_FIELDS без varied_elements для LOC/WHT/ADPT/RSZ у Performance: ці типи будують картку з таксономії оригінального креативу, тож редагувати їх на задачі нічого не дає. Тест стежить, щоб схований набір не перетинався з обов’язковим — обов’язкове поле, якого форма не малює, це блокер без виходу.

Що віддається клієнту

Друге не дублює перше: обидва генеруються з тієї самої декларації, як TASK_STATUS_SCHEMA віддає ALLOWED_TRANSITIONS. Матриця потрібна саме тому, що статус у чернетці змінюється раніше, ніж приходить перечитування, — без неї користувач має кадр, у який можна друкувати в поле, що вже закрите. Усі осі перелічені (по типу задачі, з "" для «ще не обрано»), щоб клієнт робив пошук по таблиці, а не виводив правило заново — виведене правило і було б другою копією.

Фронтенд-половина — frontend/src/modules/tasks/model/task-field-policy.ts: resolveFieldPolicy() (пошук по матриці) плюс мапа camelCase ⇄ snake_case, бо форма ключує рядки по-своєму. Своїх правил там немає; canEditPerformanceFields, lockedSideKeys, HIDDEN_FOR_MULTI_ORIGIN і дзеркало requiredEntries прибрані.

Автоматизація (run_automation)

Запускається при переході в ready_for_production. Кроки:

1. Якщо work_stream != Performance — хендлер ставить automation.state = ok і виходить, статусу не торкаючись. Автоматика обробляє лише Performance.
2. Для VAR/VARDES/VARAI — успадкування порожніх полей таксономії з задачі оригінального креативу (_inherit_from_origin): якщо в задачі поле порожнє, а в оригінала є — копіюється.
3. Валідація обов’язкових полів — набір бере field_policy.required_fields() (розділ «Політика полів»), плюс number, який перевіряється тут: product_id, task_type, media_type, execution_complexity, creation_complexity, resolution, source. language і geo обов’язкові теж, але не для WHT/ADPT/RSZ (GEO_LANGUAGE_EXEMPT_TASK_TYPES): ці типи варіюють лише одне поле (Source для WHT/ADPT, Resolution для RSZ — той самий resolution, що обов’язковий уже для всіх типів вище), а мову й гео беруть з оригінала. source натомість обов’язковий завжди — Task.source має дефолт (Source.META), тож порожнім не буває. Для типів із лічильником карток (NEW, VAR, NEWDES, VARDES, DES, VARAI, CLN) — count > 0. Для LOC/WHT/ADPT/RSZ — має бути хоч один source_creative. Для VAR/VARDES/VARAI — має бути заданий Origin Creative (або legacy remap, що на нього резолвиться) — інакше помилка No origin creative.
4. Захист від дублів — дві незалежні перевірки: якщо для задачі вже є креативи — помилка (щоб не створити дублікати при повторному запуску); якщо серед похідних карток оригінала вже є така сама — теж помилка (розділ «Дублікати варіантів»).
5. Побудова Task Name, створення креативів (розділ «Неймінг»).
6. Створення папки в Google Drive.
7. Оновлення задачі: generated_name, drive_url, drive_folder_id, automation.state = ok. Статус не пишеться — задача вже в ready_for_production.
8. Для VAR/LOC/WHT/ADPT/RSZ/VARAI — Slack Task Owner про успіх.

Якщо на будь-якому кроці помилка — задача повертається в backlog (compare-and-set проти ready_for_production, щоб не затерти ручне переміщення), automation.state = error з описом, і Task Owner отримує Slack.

Дублікати варіантів (LOC/WHT/ADPT/RSZ)

Похідна задача не має вдруге робити те, що для цього оригінала вже зроблено: другу локалізацію на ту саму пару Language+Geo, другий вайтенінг чи адаптацію на той самий Source, або другий ресайз у той самий Resolution. Вирішує це find_duplicate_variant (creative_factory.py) — по вже наявних похідних картках оригінала (CreativesRepository.list_variants, запит по origin_ref._id).

Вісь порівняння повторює те, що картка насправді варіює:

RSZ звіряється по Resolution, не по Aspect Ratio: піксельний розмір — це те, що ресайз насправді змінює, а дві RSZ-картки можуть ділити один Aspect Ratio і при цьому бути різного розміру (800x800 і 250x250 — обидва 1x1). resolution = None ніколи не збігається сам із собою — на відміну від Source, він не має дефолту на рівні CreativeVariant (лише на Task), тож старі RSZ-сусіди, зняті до появи цього поля, можуть нести None; без цього застереження вони позначались би дублікатами цілі, якої насправді ще нема.

RSZ додатково: якщо цільовий Resolution збігається з тим, який оригінал уже має сам — запит відхиляється так само, як дублікат, тільки звірка йде не з сусідньою карткою, а з самим джерелом (TasksService._assert_no_duplicate_variants / TaskWorkflowHandlers._reject_duplicate_variants). Інакше ресайз у той самий розмір минав би цю перевірку, бо в оригінала ще нема жодної RSZ-картки, з якою звіряти.

Порівнюються лише картки того самого Task Type — WHT-картка ніколи не вважається дублікатом для LOC. Власні попередні картки задачі виключаються (exclude_task_id), тож повторне збереження задачі з тими самими значеннями дублікатом не є.

Перевірка стоїть у двох місцях, і це не дублювання:

• Рання, у TasksService — на створенні й апдейті задачі. Бачить лише явні source_creative_ids, зате відповідає синхронно: DuplicateVariantError → 409 на POST /api/v1/tasks і PATCH /api/v1/tasks/{task_id}.
• Авторитетна, у run_automation (_reject_duplicate_variants у handlers.py) — після _source_origins, тобто коли набір оригіналів уже повний, включно з тими, що прийшли через legacy remap і синхронно не резолвляться. Помилка тут — звичайний WorkflowError: задача вертається в backlog зі automation.state = error.

Фронтенд читає той самий набір карток через GET /api/v1/creatives/variants?origin_ids=... (до 50 оригіналів за запит), щоб показати конфлікт до сабміту, а не після.

Неймінг

Реалізовано в creative_factory.py. Дефолти не приховуються — сегмент зі значенням показується завжди. Локаль кодується парою Geo+Language в кінці назви; ці два сегменти ходять разом і є єдиними необов’язковими: для WHT/ADPT/RSZ задача їх не має (успадковуються з оригінала), і тоді вони просто відсутні, а не підставляються літералом None.

Source не входить у жодну назву, Resolution — тільки в назву креативу. Задача називається тим, що вона замовляє; розмір готового файлу — властивість того, що з неї виходить, тож він належить картці. Саме тому назва креативу більше не є назвою задачі з префіксом: два шаблони збігаються головою і різняться одним сегментом, і пишуть їх дві функції — build_task_name та build_creative_name.

Цим сегментом раніше був Aspect Ratio, і він називав форму, а не файл: саме лише 1x1 покриває 800x800, 250x250 і 200x200, тож три картки різного розміру планували три однакові назви, і дві з них відхиляв _reject_planned_collisions. Resolution — це сам розмір, тож назва розрізняє те, чого співвідношення сторін розрізнити не могло.

Уже видані назви не переписуються. Назва креативу — це те, як його називає рекламний кабінет і на що зав’язаний кожен рядок аналітики нижче за течією, тож сегмент _9x16_ на старих картках лишається як є; новий сегмент діє для назв, що будуються від цього моменту. Перепланувати назви задач, які ще не пішли в роботу (Backlog, Ready for Production), уміє backend/scripts/rename_to_new_naming_scheme.py.

Task Name:

{Task#}_{Product}_{TaskType}_{MediaType}[_{Geo}_{Language}]
52_CNI_NEW_VID_US_EN

Креатив, звичайний (NEW, VAR, NEWDES, VARDES, DES, VARAI):

{Variation#}-{Task#}_{Product}_{TaskType}_{MediaType}_{Resolution}[_{Geo}_{Language}]
1-52_CNI_NEW_VID_1080x1920_US_EN

Кількість карток = count задачі. Метадані копіюються з задачі, Assignee при створенні не проставляється (його ставлять пізніше на Tech/Creative Check). VARAI — те саме, плюс успадкування кількох полів з оригінала (розділ «Автоматизація», крок 2): один Origin Creative, count карток проставляє креативниця (зазвичай 4).

Креатив LOC/WHT/ADPT/RSZ (Case A — оригінал є карткою):

{Variation#, від оригіналу}-{Task#, від оригіналу}_{Product}_{LOC|WHT|ADPT|RSZ}_{MediaType}_{Resolution}_{Geo}_{Language}
1-45_CNI_LOC_VID_1080x1920_FR_FR    ← LOC: Geo+Language → цільова локаль; Resolution — оригіналу
1-45_CNI_WHT_VID_1080x1920_US_EN    ← WHT: Geo+Language і Resolution з оригіналу; платформа в назву не входить
1-45_CNI_ADPT_VID_1080x1920_FR_FR   ← ADPT: решта — з оригіналу; платформа в назву не входить
1-45_CNI_RSZ_VID_800x800_US_EN      ← RSZ: Resolution → цільовий розмір, решта — з оригіналу

Одна картка на кожен source_creative. Variation#/Task# у назві беруться від оригінального креативу (для трасування), Task Type — власний (LOC/WHT/ADPT/RSZ, а не тип оригінала). Product, Media Type — з задачі. Assignee/Task Owner — з оригінала. Заповнюється origin_ref на оригінал.

Resolution у Case A — оригіналу, а не задачі (_delivered_resolution у creative_factory.py). LOC/WHT/ADPT пікселів не міняють: локалізація, вайтенінг і адаптація — той самий файл того самого розміру, тож розмір подорожує з оригіналом так само, як Geo+Language для WHT/ADPT. Одна задача може нести кілька оригіналів різного розміру, тому це читається на кожну картку, а не з єдиного поля задачі. Task.resolution лишається фолбеком для оригінала, який свого розміру не має (легасі-картка або знята до появи поля) — без нього сегмент просто зник би з назви. RSZ — єдиний тип, який бере розмір із задачі, бо зміна розміру і є його роботою; тому Resolution питається (і показується у формі) лише в нього — RESOLUTION_EXEMPT_TASK_TYPES у kumquat_tasks/enums.py, field_policy.required_fields/hidden_fields.

Якщо оригінал сам є scratch-карткою (NEW/VAR/…), Variation#/Task# беруться з її власних полів (variation_num, номер її задачі). Якщо ж оригінал сам є нелегасі похідною карткою (LOC/WHT/ADPT/RSZ, побудованою за тим самим правилом раніше) — своїх variation_num вона не має, і пара Variation#-Task# парситься назад із префіксу її власної назви (_borrow_prefix у creative_factory.py). Оскільки цей префікс зберігається незмінним через увесь ланцюжок, це працює на будь-якій глибині (NEW → LOC → WHT → ADPT → RSZ → …), поки кожна ланка нелегасі.

LOC/WHT беруть з оригінала Resolution і, залежно від типу, Source або пару Geo+Language (сам Source у назві не з’являється, але лишається полем картки) — решта таксономії (funnel, hypothesis, subject, …) йде з полів задачі. ADPT і RSZ ідуть далі: з задачі береться тільки одне поле — Source для ADPT (ціль адаптації, теж не в назві), Resolution для RSZ (ціль ресайзу — і цей сегмент, на відміну від Source, у назві лишається) — а весь інший контент, включно з Language/Geo та (для ADPT) розміром, копіюється з оригінального креативу. WHT додатково ставить is_whitened = true; ADPT/RSZ цей прапорець не ставлять.

Креатив LOC/WHT/ADPT/RSZ (Case B — legacy-оригінал, або нема що позичити):

{OriginName}_{Geo}_{Language}   (LOC)   |   {OriginName}_{Source}   (WHT/ADPT)   |   {OriginName}_{Resolution}   (RSZ)
CoinIn_3150_9256_Var_Vid_9x16_Sell_FR_FR    ← LOC: локаль допискою в кінець
CoinIn_legacy_wht_APL                       ← WHT/ADPT: цільова платформа допискою в кінець
CoinIn_legacy_rsz_800x800                   ← RSZ: розмір допискою в кінець

Якщо оригінал — легасі (origin.is_legacy, задача з is_legacy=true) або з його назви взагалі неможливо розпізнати {Variation#}-{Task#} — нова назва не перебудовується, а просто дописує в кінець існуючої назви оригіналу ту вісь, яку задача змінює: Geo+Language для LOC, Source для WHT/ADPT, Resolution для RSZ. Source у структурованій назві (Case A) не з’являється — але Case B структурованою назвою і не є: у ній немає й сегмента TaskType, тож без дописки вона була б назвою оригіналу без змін, і кожен вайтенінг чи адаптація легасі-оригінала стикався б із карткою, з якої робиться. Resolution, на відміну від Source, лишається сегментом і в структурованій назві (Case A) — тож RSZ дописує його в Case B з тієї самої причини, з якої він там лишається: без нього два RSZ від одного легасі-оригінала до різних розмірів спланували б однакову назву. is_legacy завжди переважає Case A, навіть якщо в легасі-оригінала є заповнені variation_num/номер задачі — вони проставлені бекфілом для фільтрації, а не для запозичення в нову назву.

Міграція вже згенерованих назв. Назви, які автоматизація опублікувала до зміни конвенції, переписує backend/scripts/rename_to_new_naming_scheme.py (за замовчуванням dry-run, пише з --apply). Він бере тільки задачі в Backlog і Ready for Production — саме вони ще нічого не опублікували назовні: картки з’являються на Done, а рекламні кабінети й уся аналітика нижче пишуться проти назв карток. Для кожної задачі він перебудовує generated_name і planned_creative_names, переносить галочки planned_creatives_done, перейменовує папку на Drive і файли в ній (gdrive-sync зв’язує файл із карткою за точним stem). Задачу, чий новий план уже зайнятий, скрипт пропускає цілком і називає в звіті — назву їй треба дати руками. Скрипт ідемпотентний: другий запуск нічого не пише.

Дві WHT- (чи дві ADPT-) задачі від одного нелегасі-оригінала на різні платформи планують один рядок. Структурований шаблон Case A платформи не називає, а TaskType у них однаковий — різниці в назві не лишається. Такий план відхиляється _reject_planned_collisions на Ready for Production (задача повертається в Backlog з поясненням), а не мінтить дублікат; другій потрібна назва руками. Легасі-оригіналів це не стосується — Case B дописує Source.

CLN автоматично картки не генерує.

Task #. Назва завжди починається з номера задачі. Номер призначається автоматично при створенні задачі (TasksRepository.next_task_number) — глобальний атомарний лічильник у колекції counters (документ _id: "task_number"), який при першому використанні стартує від поточного максимуму. Якщо number вже задано (наприклад, із синку) — не перезаписується.

Призначення виконавця (tech_check / creative_check)

• tech_check (NEW/VAR): Assignee задачі проставляється на всі креативи задачі, submitted_at, Slack відповідальному за Tech Check.
• creative_check (NEWDES/VARDES): те саме; якщо Assignee задачі порожній — береться Task Owner і записується в Assignee задачі. Slack іде Task Owner тільки якщо він не збігається з Assignee.
• LOC/WHT/ADPT/RSZ: Assignee не чіпається — атрибуція збережена з оригінала ще при створенні.

Done (on_done)

1. Якщо completed_at порожній — проставляється (один раз, не перезаписується).
2. Якщо manual_launch = true — Slack у UAM-канал. Папка Drive нікуди не переміщується: вона лишається там, де її створила автоматизація.

Slack

Транспорт — kumquat_tasks/notifications.py. WorkflowNotifier містить таблицю маршрутизації.

Task Owner і Assignee резолвляться по email: Clerk-id → email (колекція users) → users.lookupByEmail у Slack → DM. Відповідальний за Tech Check задається напряму як Slack user id (SLACK__TECH_CHECK_USER_ID), без резолву по email.

Єдина подія в цій таблиці, що не прив’язана до переходу статусу — призначення виконавця. Її пильнує TasksService.update_task (kumquat_tasks/service.py): якщо PATCH /tasks/{id} міняє assignee_id на нове значення, поки задача вже стоїть у ready_for_production, сервіс ставить у Celery-чергу tasks.io.task_assigned (kumquat_api/worker/tasks.py). Воркер перечитує задачу заново перед відправкою — якщо її вже перепризначили ще раз або вона встигла зрушити зі статусу, сповіщення тихо не йде.

Формат повідомлення. Кожне сповіщення — один Block Kit блок card (task_message у kumquat_tasks/notifications.py):

52_CNI_NEW_VID_US_EN                 ← клікабельна назва
🔍 Ready for Tech Check
*Status* 🔧 Tech Check  ·  *Assignee* Denys Koval
*Product* CNI  ·  *Media* VID
*Type* NEW

Заголовок веде на {APP_BASE_URL}/tasks/{id} і є єдиним переходом. Окремої кнопки картка не має: посилання в заголовку читається і там, де кнопки не видно — у прев’ю пуш-нотифікації, у вузькому мобільному клієнті, у згорнутій картці в треді.

Статус — тег, як на дошці. На фронтенді статус це підфарбована іконка плюс лейбл (optionIcons поля status). Кольорового фону всередині тексту Slack не має, тож тег переїжджає як емодзі, найближче до тієї іконки, зі збереженим кольором там, де він є:

Кружечок беруть лише ті два статуси, які й на дошці намальовані кружечками (Backlog і Ready for Production). Решта — емодзі: у Slack немає кружечка на кожен відтінок, яким фарбує дошка, і рожевий Creative Check, округлений до найближчого, злився б з іншим статусом в один тег. Статус без запису в таблиці друкується як є, а не ламає повідомлення.

Назву задачі вводять руками, тож перед вставкою в <url|назва> вона екранується (&, <, >) і обрізається під бюджет 150 - len(url) - 3 — незакритий > обірвав би посилання й вивалив сирий URL у текст.

body наповнюється, поки вкладається в 200 символів: рядки додаються попарно й обриваються цілими, тому довге ім’я виконавця прибирає Type, а не ріже значення посередині.

Порожній APP_BASE_URL означає «без переходу»: заголовок лишається звичайним текстом. Це свідомо тихо — краще сповіщення без посилання, ніж зламане.

Кожна подія має свій колір — смужка ліворуч від картки:

Кольорова смужка існує лише в attachments, тому кольорове повідомлення кладе блоки всередину attachment, а прев’ю — у його fallback. Верхньорівневий text при цьому не надсилається: поруч з attachment Slack його рендерить, і повідомлення дублювалося б.

Колір задається на рівні транспорту, а не блоків: task_message його не приймає, смужку навколо блоків малює _payload у kumquat_core/integrations/slack.py.

Імʼя виконавця резолвиться з дзеркала users за Clerk-id (одне читання на сповіщення); якщо виконавця немає — рядок фактів його просто не містить.

Поруч із блоками завжди йде плоский текст ("{назва}\n{подія}") — Slack показує його в превʼю сповіщення і там, де блоки не рендеряться.

APP_BASE_URL — публічний URL фронтенду, різний для кожного середовища (локально http://localhost:3000, у кластері задається через config.appBaseUrl у чарті kumquat-celery-worker — саме він виконує обидва Celery-таски, що шлють у Slack). Якщо змінна порожня — повідомлення йде без переходу, а не з битим посиланням.

Сповіщення про згадку в коментарі має той самий вигляд і додатково цитує сам коментар (обрізаний до 280 символів).

Google Drive

Клієнт — kumquat_tasks/drive.py. Структура спирається на одну батьківську папку в Shared Drive (DRIVE__ROOT_FOLDER_ID), усередині — {Product}/{TaskName}.

• Автоматизація: {Product}/{TaskName} (find-or-create, тому повторний прогон перевикористає ту саму папку).
• Done: папка лишається на місці — переміщень немає.

Воркфлоу тільки створює папки, ніколи не переміщує й не видаляє. Сервіс-акаунту достатньо прав content-manager у Shared Drive.

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

Змінні середовища (nested delimiter __):

APP_BASE_URL
SLACK__ENABLED
SLACK__BOT_TOKEN
SLACK__CREATIVE_CHANNEL
SLACK__UAM_CHANNEL
SLACK__TECH_CHECK_USER_ID
SLACK__BOT_DISPLAY_NAME
SLACK__BOT_ICON_URL
DRIVE__CREDENTIALS_JSON
DRIVE__ROOT_FOLDER_ID

Якщо SLACK__BOT_TOKEN не задано — використовується LoggingNotifier (повідомлення лише в лог). Якщо DRIVE__CREDENTIALS_JSON не задано — NoopDriveClient (операції з папками лише в лог). Це дозволяє ганяти весь воркфлоу локально без реальних інтеграцій.

SLACK__ENABLED — вимикач для випадку, коли блок заповнений повністю. false лишає LoggingNotifier попри наявний токен; за замовчуванням true, тож прод нічого додавати не мусить. Потрібен там, де секрет спільний з продом: dev тягне ті самі SLACK__* з ml/dev/kumquat-secrets, і без прапорця вибір був би між «вирізати чотири значення із секрету» та «слати DM живим людям». Вимкнений notifier усе одно бачить creative_channel, uam_channel і tech_check_user_id, тому в лог іде й маршрут, який повідомлення отримало б — на відміну від повністю знятого блоку, де ці id порожні.

Прапорець сам по собі блоку не створює: SLACK__ENABLED без решти SLACK__* — це та сама помилка «Field required» на старті, що й будь-яке інше часткове заповнення.

Слати в Slack можуть лише воркери (kumquat_api/worker/tasks.py) — API тільки ставить задачу в чергу, тому змінна живе в configmap чартів kumquat-worker і kumquat-celery-worker (config.slackEnabled), а не в kumquat-api. У values-dev.yaml обох чартів вона вже виставлена в "false".

SLACK__BOT_DISPLAY_NAME / SLACK__BOT_ICON_URL — опційні, за замовчуванням порожні. Задані — підмінюють ім’я й аватар відправника на кожному повідомленні (username/icon_url у chat.postMessage, SlackNotifier у kumquat_core/integrations/slack.py); порожні — лишають брендування самого Slack-застосунку. Підміна працює лише за наявності скоупу chat:write.customize на SLACK__BOT_TOKEN — без нього Slack мовчки її ігнорує, без помилки.