База данных (schema v8)

Один SQLite-файл на все скиллы. 20+ таблиц, junction-механика для multi-project. Все скиллы пишут/читают сюда. Кто owner, кто reader, как scope'ить запросы — здесь.

Где лежит и как открыть

~/video-projects/director.db    # ← одна shared БД для ВСЕХ скиллов и ВСЕХ проектов

Открыть руками:

sqlite3 ~/video-projects/director.db
sqlite> .tables                                  # список всех таблиц
sqlite> .schema clips                            # схема таблицы clips
sqlite> SELECT COUNT(*) FROM clips;              # количество клипов
sqlite> SELECT * FROM projects;                  # все проекты

Или GUI: DBeaver, TablePlus, DB Browser for SQLite.

Архитектура: ресурсы + junction-таблицы

Главная идея multi-project: один ресурс (например клип) может принадлежать нескольким проектам. Это реализовано через junction-таблицы (many-to-many between projects и ресурсами).

Таблицы (ownership)

Junction-таблицы (multi-project linking)

Каждая junction = (project_id, resource_id, linked_at). Они дают many-to-many между проектами и ресурсами.

Key relationships (schema v8)

Полная chain traceability: проект → текст → озвучка → видео → performance metrics.

projects.id ← project_clips.project_id → clips.id
projects.id ← project_videos.project_id → videos.id
projects.id ← project_voices.project_id → voices.id
projects.id ← project_music.project_id → music.id
projects.id ← project_texts.project_id → generated_texts.id
projects.id ← project_voiceovers.project_id → voiceover_history.id
projects.id ← project_transcriptions.project_id → transcriptions.id
projects.id ← project_reference_images.project_id → reference_images.id
projects.id ← project_models.project_id → models_3d.id
projects.id ← project_creative_posters.project_id → creative_posters.id

generated_texts.id ← voiceover_history.generated_text_id
voiceover_history.id ← videos.voiceover_id
generated_texts.id ← videos.generated_text_id
clips.id ← video_clips.clip_id
videos.id ← video_clips.video_id
reference_images.id → clips.reference_image_ids (JSON-массив)
competitor_refs.id ← generated_texts.competitor_ref_id
voices.id ← voiceover_history.voice_db_id

Project scoping в SQL-запросах

Все db.py скрипты берут slug проекта из имени папки (os.path.basename(project_dir)), резолвят project.id и фильтруют через junction:

Insert: ресурс + junction-линк

# Python (упрощённо)
clip_id = insert_clip(path, description, duration, ...)
_link_to_project(conn, "project_clips", "clip_id", clip_id, project_dir)

Query: фильтр по проекту

SELECT c.*
FROM clips c
JOIN project_clips pc ON c.id = pc.clip_id
WHERE pc.project_id = ?

Schema management

schema.py — single source of truth по схеме. Копия лежит в каждом скилле в scripts/schema.py (одинаковая). Версия меняется атомарно одной правкой во всех копиях.

python schema.py init <project-dir>      # создать с нуля все таблицы
python schema.py migrate <project-dir>   # обновить существующую (идемпотентно)
python schema.py info <project-dir>      # показать tables, columns, row counts

Migration history

v8 — текущая. schema.py migrate работает на любую v6+ базу.

Competitor research pipeline (separate tool)

Standalone TypeScript-инструмент в agents-monorepo/tools/dentistry-research/ заполняет competitor_refs реальными креативами конкурентов (с FB Ad Library).

Source data: data/research.sqlite (отдельная БД, НЕ director.db).

Stage 6 import command

cd agents-monorepo/tools/dentistry-research
npm run stage6 -- \
  --director-db ~/video-projects/director.db \
  [--min-creatives 5] \
  [--niche dentistry] \
  [--reclassify] \
  [--dry-run]

• Auto-runs schema.py migrate если БД на pre-v8
• UPSERT по fb_ad_archive_id (идемпотентно, повторные запуски не дублируют)
• Фильтр по активности клиники (--min-creatives, default 5)
• Кеширует dental_categories из stage4 (Gemini классификатор только для непроклассифицированных)
• Maps project slugs → global DENTAL_CATEGORIES (например braces → orthodontics)
• Шипит info_score и score_breakdown для каждой строки

Info_score 0..100 — для приоритизации референсов

Считается в tools/dentistry-research/stage4c-score.ts и приходит в director.db через stage6. Видеокопирайтер использует для выбора лучших конкурентских креативов.

Default --min-score 50 отсекает короткие image-ads и неоттестированные one-offs. ≥70 — редко (~1% — топовые креативы крупных клиник).

Типичные запросы (для разработчика)

Все ресурсы проекта

-- сколько чего у проекта 'apparatus'
SELECT
  (SELECT COUNT(*) FROM project_clips pc JOIN projects p ON pc.project_id = p.id WHERE p.slug = 'apparatus') AS clips,
  (SELECT COUNT(*) FROM project_voices pv JOIN projects p ON pv.project_id = p.id WHERE p.slug = 'apparatus') AS voices,
  (SELECT COUNT(*) FROM project_texts pt JOIN projects p ON pt.project_id = p.id WHERE p.slug = 'apparatus') AS texts,
  (SELECT COUNT(*) FROM project_videos pv JOIN projects p ON pv.project_id = p.id WHERE p.slug = 'apparatus') AS videos;

Какие клипы давно не использовались (для rotation)

SELECT c.id, c.path, MAX(v.created_at) AS last_used_at
FROM clips c
JOIN project_clips pc ON c.id = pc.clip_id
JOIN projects p ON pc.project_id = p.id
LEFT JOIN video_clips vc ON c.id = vc.clip_id
LEFT JOIN videos v ON vc.video_id = v.id
WHERE p.slug = 'apparatus'
GROUP BY c.id
ORDER BY last_used_at ASC NULLS FIRST
LIMIT 10;

Winners report по статике (CPL)

SELECT cp.id, cp.path, cp.style, cp.preset, perf.cpl, perf.ctr, perf.conversions
FROM creative_posters cp
JOIN project_creative_posters pcp ON cp.id = pcp.poster_id
JOIN projects p ON pcp.project_id = p.id
JOIN creative_performance perf ON cp.id = perf.poster_id
WHERE p.slug = 'apparatus' AND perf.cpl IS NOT NULL
ORDER BY perf.cpl ASC
LIMIT 10;

Бэкап и восстановление

# бэкап
sqlite3 ~/video-projects/director.db ".backup '/tmp/director_backup_$(date +%Y%m%d).db'"

# восстановить из бэкапа
cp /tmp/director_backup_20260516.db ~/video-projects/director.db

# экспорт всей БД в SQL-дамп
sqlite3 ~/video-projects/director.db .dump > director_dump.sql

Куда дальше

• Multi-project архитектура — как организован filesystem уровень
• 7 пайплайнов — flow-диаграммы кто что вызывает
• video-project-setup — как новый проект попадает в БД