ADR

ADR-005: Версионирование JTBD, Offer, Experiment

ADR-005: Версионирование JTBD, Offer, Experiment

Статус: ✅ Accepted
Дата: 2026-06-11
Автор: openclaw-architect

Контекст

Три ключевые сущности SprosOS — JTBD (Job To Be Done), Offer (оффер), Experiment (эксперимент) — имеют критическое свойство: историчность.

  • JTBD-гипотеза может уточняться по мере сбора evidence
  • Оффер может меняться (цена, условия, упаковка)
  • Эксперимент ссылается на конкретные версии JTBD и оффера

Если сущности изменяются in-place, теряется audit trail и валидность экспериментов.

Рассматривались подходы:

  1. In-place обновление — проще модель данных, но нет истории
  2. Полный Event Sourcing — максимальная история, но высокая сложность
  3. Версионирование — каждая сущность имеет версии, immutable после публикации

Решение

Выбираем версионирование ключевых сущностей.

Модель

// JTBDConcept — контейнер для версий JTBD
interface JTBDConcept {
  id: string;
  projectId: string;
  currentVersionId: string;  // ссылка на текущую активную версию
  status: JTBDConceptStatus; // draft | published | superseded | retired
  createdAt: Date;
}

// JTBDVersion — неизменяемая версия JTBD
interface JTBDVersion {
  id: string;
  conceptId: string;
  versionNumber: number; // 1, 2, 3...
  body: string;
  functionalJob: string;
  emotionalJob?: string;
  socialJob?: string;
  outcomes: string[];
  context: string;
  status: VersionStatus; // draft | published | superseded
  publishedAt?: Date;
  supersededAt?: Date;
}

// Аналогично для Offer (Offer → OfferVersion)
// Аналогично для Experiment (Experiment → ExperimentVersion)

Правила

  1. После публикации — immutable. Опубликованная версия не может быть изменена.
  2. Изменения — через новую версию. Новая версия создаётся явно.
  3. Current version — указатель на активную версию.
  4. Superseded — версия помечается как заменённая, но не удаляется.
  5. Experiment ссылается на конкретную версию оффера/JTBD.

Последствия

Положительные (+)

  • Полный audit trail: Видно, что и когда менялось
  • Валидность экспериментов: Эксперимент всегда ссылается на конкретную версию
  • Исторический анализ: Можно анализировать, как менялось понимание JTBD
  • Воспроизводимость: Любой момент времени можно восстановить

Отрицательные (-)

  • Сложнее модель данных: Нужны concept + version сущности
  • Дополнительные операции: Создание версии — явный шаг
  • Чтение сложнее: Нужно знать, какую версию читать
  • Размер данных растёт: Каждое изменение — новая запись

Стратегия смягчения

  1. Шаблон "Versioned Entity" в domain layer
  2. Default read — текущая версия, explicit read — конкретная версия
  3. Background cleanup старых draft-версий (не опубликованных)
  4. Индексы по concept_id + version_number

Связанные документы

  • CORE_DOMAIN_MODEL.md (JTBDConcept, JTBDVersion, Offer, Experiment)
  • ARCHITECTURE_PRINCIPLES.md (Immutability by Design)
  • DECISION_LOG.md (#005)