Федерация документации

Федерация документации#

green-robot не должен быть полным зеркалом всех инженерных деталей. Вместо этого используется федеративная модель: опубликованный контур и инженерные контуры синхронизируются по явным правилам.

1. Цель модели#

  • не дублировать одни и те же технические детали в пяти репозиториях;

  • сохранить один published-вход для пользователя и регистрации;

  • сохранить быстрый вход для агентов через README.md каждого repo;

  • избежать расхождения общих контрактов и архитектуры.

2. Слои документации#

2.1. Published layer (green-robot)#

Содержит:

  • Документы;

  • Продукты;

  • Платформа;

  • Применение.

Это слой для пользователя, аудитора, регистрационного контура и кросс-проектного согласования.

2.2. Engineering layer (product repos)#

Содержит:

  • код и реальные runtime artifacts;

  • внутреннюю архитектуру продукта;

  • build/test/deploy flow;

  • detailed operator/developer docs.

2.3. Agent layer (README.md)#

Содержит краткую инструкцию:

  • что это за repo;

  • какой продукт он реализует;

  • где published canonical в green-robot;

  • где engineering canonical внутри repo;

  • что агент обязан синхронизировать при изменениях.

3. Правила синхронизации#

  1. Изменение локальной реализации без смены published-смысла:

    • правится engineering repo;

    • green-robot меняется только если пользовательский/регистрационный смысл изменился.

  2. Изменение общего контракта, архитектуры или классификации продукта:

    • сначала правится green-robot;

    • затем связанные engineering repo.

  3. Изменение отраслевого решения:

    • сначала обновляются Применение и платформенные связи в green-robot;

    • затем прикладной product repo, если изменена реализация.

  4. Изменение обязанностей repo или source-of-truth:

    • обязательно обновляются README.md затронутых репозиториев.

  5. Изменение published contract project/monitoring/ws, auth/access, git-driven deploy chain или product-chain iP-1220 -> green-robot-go -> iP-1510:

    • published/product docs и engineering docs обновляются в одном push;

    • отложенная документационная синхронизация не допускается.

Дополнение по инженерным семействам:

  • iC-4, iO-5, iU-6 синхронизируются через ../ioot-pro-hardware как engineering owner;

  • iD-7 должен выделяться в отдельный контур механики и электрики с собственным repo и собственным agent-facing README.md.

4. Что проверять агенту перед правкой#

  1. Это published-изменение или локальная реализация?

  2. Затронут ли продуктовый идентификатор, платформенный контракт или отраслевую связность?

  3. Обновлен ли README.md репозитория, если изменились зоны ответственности?

  4. Нужна ли синхронизация в green-robot после локальной правки?

5. Практический результат#

Такая схема позволяет:

  • держать green-robot как каноническую публикацию и регистрационный контур;

  • не дублировать в нем полностью инженерную документацию из ioot-pro-*;

  • дать агентам быстрый и единый способ понять границы ответственности через README.md.

Содержание