Основы за пять минут

Вы пишете инструмент командной строки или интеграцию для агента, которая читает или пишет общее хранилище WireCat. За пять минут эта страница даёт вам модель: какие бывают записи, как они связаны и какие правила не дают вашему инструменту сломать другие. Следующие страницы показывают, как добавить источник, хранить свои данные, входить в сервис и соответствовать стандартам.

Общее хранилищеCopy Anchor Link

Каждый инструмент WireCat хранит данные в одном файле SQLite на компьютере владельца — wirecat.db. Этим файлом владеет пакет @wirecat/cli-core: его таблицы, миграции и код, который их читает и пишет. Инструмент обращается к файлу только через cli-core и никогда — своим SQL (правила хранилища).

Сущности и записи источниковCopy Anchor Link

• Сущность — это то, что владелец имеет в виду на самом деле: человек, событие, документ. В ней нет id провайдера.
• Запись источника — то, что о сущности знает один источник: пользователь Telegram, адрес почты, встреча Zoom, запись календаря, файл Drive. В ней есть аккаунт, откуда она пришла, и собственный id провайдера.

Одна сущность собирает записи из нескольких источников. Одна встреча в Zoom и в двух календарях — одно событие. Один человек в Telegram и в почте — один человек. Ваш инструмент пишет записи источников; cli-core связывает их с сущностями.

external_idCopy Anchor Link

Id, который провайдер дал записи, хранится в external_id и уникален в пределах аккаунта. Второй id, который провайдер тоже использует, получает свою именованную колонку, например ical_uid. Никогда не колонка с именем провайдера и никогда не только внутри metadata (WC-DATA-3).

СвязиCopy Anchor Link

Связь записи источника с её сущностью помнит, как она создана, насколько надёжна, кто и когда её сделал. Каждое изменение пишется в журнал, поэтому ошибочную связь можно отменить. Везде действуют три правила:

1. Связь, сделанную владельцем, никогда не заменяет автоматическая.
2. Два одинаково подходящих кандидата не дают связи.
3. Совпадение названия или пересечение по времени само по себе никогда не связывает две записи.

Это правило WC-DATA-6. Как связи выглядят для читателя — на странице Как всё связано.

Общие сущности и ваши таблицыCopy Anchor Link

Запись, которая может понадобиться не одному инструменту, — общая сущность: её таблица живёт в cli-core. Таблица, нужная только вашему инструменту, — контрольная точка синхронизации, кэш — живёт в собственном файле SQLite вашего инструмента, и другие инструменты её не читают (WC-DATA-1). Подробнее — Хранить свои данные.

Ещё в хранилищеCopy Anchor Link

• Реестр провайдеров. Ваш инструмент при каждом запуске записывает своего провайдера (имя, вид, псевдонимы, команду) в хранилище, и все остальные инструменты узнают о новом источнике без выпуска cli-core. Строки провайдера, которого ни один инструмент не записал, пропускаются с пояснением и никогда не ищутся как сообщения. См. Добавить источник.
• Список на проверку. Пары, которые инструменты не могут различить, например два события для одной встречи, ждут там решения владельца.
• Записи календаря и файлы — записи источников для событий и документов, а у каждой учётной записи может быть адрес почты, чтобы один адрес объединял одного человека.

Что сломается, если это пропуститьCopy Anchor Link

Id провайдера только в metadata нельзя обновить по ключу, и каждая синхронизация создаёт дубль. Связь по одному названию соединяет две разные встречи, и владелец видит чужую запись. SQL к общему файлу ломается на следующей миграции cli-core.

Дальше: Добавить источник.