docs: define Telegram AI infrastructure MVP

2026-07-31 23:06:43 +03:00
commit 811272e6a7
3 changed files with 482 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,12 @@
+# Local credentials and secrets
+credentials.txt
+
+# Python/runtime artifacts (for the upcoming bot implementation)
+__pycache__/
+.venv/
+*.py[cod]
+
+# Local environment files
+.env
+.env.*
+!.env.example
--- a/TEAM_AI_TELEGRAM_IMPLEMENTATION_PLAN.md
+++ b/TEAM_AI_TELEGRAM_IMPLEMENTATION_PLAN.md
@@ -0,0 +1,395 @@
+# План реализации командной инфраструктуры Telegram + ИИ
+
+## 1. Назначение проекта
+
+Создать удобную рабочую среду для небольшой команды юристов и разработчиков, в которой:
+
+- Telegram используется как место ежедневного общения, обсуждений, задач и уведомлений;
+- ИИ помогает переводить обычные формулировки участников в документы, задачи и технические действия;
+- Git/Gitea остаётся источником истины для документации проекта, MVP, планов, требований, архитектуры и принятых решений;
+- бот собирает информацию из Telegram вручную, автоматически или по запросу и подготавливает её для последующего анализа через обычную подписку ChatGPT;
+- результаты анализа возвращаются в Telegram в виде отчёта, проекта решения или уточняющих вопросов.
+
+Проект не должен превращать Telegram в репозиторий или заменять Git. Telegram — рабочий штаб, Git — память и источник актуальных материалов, ИИ — помощник и переводчик между человеком и сложными инструментами.
+
+---
+
+## 2. Целевая модель работы
+
+```text
+Команда
+   ↓
+Telegram-супергруппа с темами
+   ↓
+Бот: уведомления, сбор материалов, экспорт, запросы на анализ
+   ↓
+ChatGPT через ручную загрузку подготовленных файлов
+   ↓
+Отчёт, проект решения или вопросы для уточнения
+   ↓
+Подтверждённый результат переносится в Git/Gitea
+```
+
+ИИ не принимает окончательные решения самостоятельно. Он выделяет позиции, аргументы, противоречия и варианты действий. Решение подтверждает команда, после чего оно фиксируется в Git или в соответствующей задаче.
+
+---
+
+## 3. Роли основных компонентов
+
+### Telegram
+
+- ежедневные обсуждения;
+- оперативные вопросы;
+- работа со спринтами и задачами;
+- обсуждение требований и идей;
+- подтверждение решений;
+- получение уведомлений от бота;
+- доступ к готовым сценариям работы с ИИ.
+
+### Бот
+
+- принимает сообщения и команды;
+- учитывает темы, авторов, даты и ответы;
+- сохраняет выбранные сообщения и вложения;
+- экспортирует обсуждения в Markdown или другой удобный формат;
+- формирует материалы для загрузки в ChatGPT;
+- возвращает в группу отчёты и вопросы;
+- отправляет уведомления о PR, задачах, дедлайнах и других событиях;
+- по возможности помогает оформить решение или задачу.
+
+### Git/Gitea
+
+- документация проекта;
+- описание MVP;
+- пошаговые планы по направлениям;
+- требования и пользовательские сценарии;
+- архитектура и структура данных;
+- принятые решения;
+- история изменений;
+- задачи, pull request и результаты разработки.
+
+### ChatGPT
+
+- анализирует экспортированные обсуждения;
+- выделяет факты, мнения, аргументы и спорные вопросы;
+- готовит краткие и подробные сводки;
+- предлагает проект решения;
+- выделяет задачи, риски и зависимости;
+- помогает подготовить изменения в документации и проверить PR;
+- работает с юридическими и проектными материалами в рамках обычной подписки.
+
+---
+
+## 4. Предлагаемая структура Telegram-группы
+
+Количество тем на старте следует держать небольшим. Темы можно добавлять по мере появления устойчивой потребности.
+
+### Общее
+
+Организационные сообщения и вопросы, которые пока не относятся к другой теме.
+
+### Задачи и спринты
+
+Текущие задачи, сроки, блокеры, распределение ответственности и статус спринта.
+
+### Обсуждение MVP
+
+Идеи, требования, пользовательские сценарии и обсуждение границ первой версии продукта.
+
+### Юридические вопросы
+
+Рабочие обсуждения правовой модели, источников, классификации документов и судебной практики.
+
+### Решения
+
+Только проекты и подтверждённые решения команды. Подробный результат после утверждения переносится в Git.
+
+### Работа с ИИ и командные сценарии
+
+Живая библиотека готовых промптов и сценариев. Здесь не объясняются технологии ради технологий; здесь показывается, что написать ИИ для получения нужного результата.
+
+### Уведомления бота
+
+Автоматические сообщения о новых PR, изменениях статуса задач, дедлайнах, сборках и отчётах.
+
+### Техническое обсуждение
+
+Архитектура, реализация, инфраструктура и вопросы, которые в первую очередь нужны разработчикам.
+
+---
+
+## 5. FAQ как библиотека рабочих сценариев
+
+FAQ должен отвечать не на вопрос «что такое Git», а на вопрос «что написать ИИ, чтобы выполнить нужную работу».
+
+Каждая запись желательно оформляется по шаблону:
+
+```text
+Название сценария
+
+Когда использовать:
+...
+
+Готовый промпт:
+...
+
+Что проверить в результате:
+...
+
+Связанные документы или сценарии:
+...
+```
+
+### Минимальный набор сценариев
+
+1. Обновить документацию проекта на основе нового решения.
+2. Найти связанные документы и проверить противоречия.
+3. Подготовить изменение в формате diff.
+4. Сформировать задачу из обычного описания проблемы.
+5. Подготовить техническое требование из юридического описания.
+6. Проанализировать идею и определить, относится ли она к MVP.
+7. Провести проверку pull request.
+8. Исправить замечания по pull request после согласования плана.
+9. Разобрать ошибку или непонятное поведение системы.
+10. Проанализировать конфликт Git и предложить безопасный вариант объединения.
+11. Сформировать проект решения команды по итогам обсуждения.
+12. Проанализировать обсуждение Telegram.
+13. Выделить из обсуждения задачи, сроки, риски и открытые вопросы.
+14. Проанализировать юридический документ или сравнить две его редакции.
+
+Правило для сценариев, которые меняют файлы или код: сначала анализ и план, затем подтверждение, затем изменение, после чего — diff и краткое объяснение результата.
+
+---
+
+## 6. Объём минимальной версии
+
+### Telegram и бот
+
+- создать и настроить бота;
+- добавить его в супергруппу;
+- определить права и список разрешённых тем;
+- принимать сообщения из выбранных тем;
+- сохранять текст, автора, дату, тему и связи ответов;
+- сохранять доступные вложения;
+- поддержать ручную пометку сообщений для экспорта;
+- экспортировать обсуждение в Markdown;
+- отправлять готовый файл или ссылку на него;
+- предоставить базовые команды справки и состояния.
+
+### Экспорт для ChatGPT
+
+Экспорт должен быть понятен человеку и удобен для загрузки в ChatGPT. Рекомендуемая структура:
+
+```markdown
+# Обсуждение
+
+Тема:
+Период:
+Участники:
+
+## Сообщения по времени
+
+Автор — дата и время:
+Текст сообщения
+
+## Контекст для анализа
+
+Связанные ссылки, файлы и примечания
+```
+
+Дополнительно можно формировать готовый файл-запрос с задачей для ChatGPT: «выдели решения, открытые вопросы, задачи, риски и спорные позиции».
+
+### Уведомления
+
+На первом этапе достаточно уведомлений о:
+
+- создании и обновлении pull request;
+- запросе на проверку PR;
+- объединении или закрытии PR;
+- создании и закрытии задачи;
+- приближении и наступлении дедлайна;
+- сбое сборки или другой важной автоматической проверки.
+
+Не следует включать все push и все комментарии без фильтрации: это создаст шум и снизит полезность группы.
+
+### Git/Gitea
+
+Подготовить базовую структуру документации, например:
+
+```text
+docs/
+├── mvp/
+├── roadmap/
+├── requirements/
+├── architecture/
+├── decisions/
+└── team/
+    ├── ai-workflow.md
+    ├── prompts-library.md
+    └── team-rules.md
+```
+
+Содержимое этих файлов должно редактироваться и проходить обычную проверку через Git/Gitea.
+
+---
+
+## 7. Режимы сбора информации
+
+### Ручной сбор
+
+Участник явно отмечает сообщения, тему или диапазон для последующего экспорта. Это основной и самый безопасный режим на старте.
+
+### Автоматический сбор
+
+Бот сохраняет сообщения из заранее определённых рабочих тем. Для каждой темы можно задать срок хранения и правила исключения технического шума.
+
+### Сбор по запросу
+
+Команды или кнопки позволяют запросить:
+
+- краткий итог текущего обсуждения;
+- экспорт темы за период;
+- список нерешённых вопросов;
+- проект решения;
+- список задач;
+- подборку сообщений по ключевому слову.
+
+---
+
+## 8. Обмен с ChatGPT без API
+
+На первом этапе не требуется подключать API языковой модели. Бот готовит структурированные файлы, а участник загружает их в ChatGPT вручную.
+
+Рабочий цикл:
+
+1. Бот собирает или получает выбранные сообщения.
+2. Бот формирует Markdown-файл и задачу для анализа.
+3. Участник загружает файл в ChatGPT Project.
+4. ChatGPT подготавливает сводку, решение, вопросы или список задач.
+5. Участник возвращает результат в Telegram.
+6. Команда обсуждает и подтверждает результат.
+7. Подтверждённые материалы переносятся в Git/Gitea.
+
+Почтовый сервер может использоваться как дополнительный канал доставки экспортов и отчётов, но не как основное хранилище обсуждений.
+
+---
+
+## 9. Этапы реализации
+
+### Этап 0. Границы и правила
+
+- утвердить назначение Telegram, Git, бота и ChatGPT;
+- выбрать темы, которые бот слушает;
+- определить, что можно собирать автоматически;
+- определить правила обработки персональных и конфиденциальных данных;
+- определить формат решений, задач и экспортов.
+
+### Этап 1. Рабочая Telegram-группа
+
+- создать супергруппу и темы;
+- подготовить закреплённые сообщения;
+- создать первоначальный FAQ;
+- согласовать правила обсуждений и фиксации решений.
+
+### Этап 2. Бот-архиватор
+
+- реализовать приём сообщений;
+- сохранить метаданные и вложения;
+- добавить ручную отметку для экспорта;
+- сформировать Markdown-экспорт;
+- проверить работу с темами и ответами.
+
+### Этап 3. Уведомления
+
+- подключить события Gitea;
+- настроить фильтрацию;
+- направлять уведомления в отдельную тему;
+- добавить напоминания о задачах и сроках.
+
+### Этап 4. ИИ-подготовка без API
+
+- добавить шаблоны запросов для анализа;
+- создавать готовые файлы для загрузки в ChatGPT;
+- добавить возврат отчёта в Telegram;
+- проверить несколько реальных обсуждений.
+
+### Этап 5. Связка с Git/Gitea
+
+- подготовить структуру документации;
+- настроить ссылки на задачи, PR и документы;
+- определить процесс переноса подтверждённых решений в Git;
+- добавить сценарии обновления документации через ИИ.
+
+### Этап 6. Улучшение по фактическому использованию
+
+- удалить невостребованные функции;
+- расширить FAQ реальными сценариями команды;
+- улучшить формат отчётов;
+- добавить новые уведомления только при наличии потребности;
+- оценить необходимость API и автоматического ИИ-анализа.
+
+---
+
+## 10. Критерии готовности первой версии
+
+Первая версия считается пригодной к работе, если:
+
+- команда может общаться по темам без технических препятствий;
+- участник может найти нужный рабочий сценарий для ИИ;
+- бот сохраняет сообщения из согласованных тем;
+- выбранное обсуждение экспортируется в читаемый Markdown;
+- экспорт можно загрузить в ChatGPT и получить структурированный результат;
+- отчёт можно вернуть в Telegram;
+- уведомления о PR и задачах приходят в отдельную тему без лишнего шума;
+- подтверждённые решения и изменения документации фиксируются в Git;
+- участникам не нужно изучать внутреннюю реализацию бота.
+
+---
+
+## 11. Что сознательно не входит в первую версию
+
+- автоматическое принятие решений ИИ;
+- полноценный ИИ-чат с API;
+- сложная векторная база и RAG;
+- автоматическое изменение кода без подтверждения;
+- попытка хранить всю базу проекта в Telegram;
+- обязательное обучение юристов Git-командам;
+- чрезмерное количество тем, команд и уведомлений;
+- автоматическая обработка всех сообщений без правил приватности и фильтрации.
+
+---
+
+## 12. Возможности следующего этапа
+
+После того как команда накопит опыт работы, можно добавить:
+
+- автоматические ежедневные и недельные сводки;
+- кнопку «проанализировать обсуждение»;
+- интерактивное подтверждение проекта решения;
+- автоматическое выделение задач и дедлайнов;
+- поиск по архиву обсуждений;
+- проверку согласованности документов проекта;
+- автоматическую подготовку pull request для документации;
+- интеграцию с API языковой модели;
+- поиск по проектной документации и истории решений;
+- аналитику нерешённых вопросов и повторяющихся проблем.
+
+Переход к API имеет смысл только тогда, когда ручной процесс станет понятным и появится регулярная потребность в автоматических отчётах или поиске.
+
+---
+
+## 13. Главный принцип проекта
+
+Команда должна формулировать рабочую задачу обычным языком. Telegram и готовые сценарии снижают порог входа, ИИ помогает перевести намерение в структурированный результат, а Git сохраняет утверждённую версию проекта.
+
+```text
+Человек формулирует намерение
+        ↓
+Telegram и ИИ помогают его оформить
+        ↓
+Команда проверяет и принимает результат
+        ↓
+Git сохраняет актуальную версию
+```
+
+Цель инфраструктуры — не заставить специалистов изучать больше технологий, а сделать технологии удобным продолжением их профессиональной работы.
--- a/docs/decisions/001-mvp-boundaries-and-rules.md
+++ b/docs/decisions/001-mvp-boundaries-and-rules.md
@@ -0,0 +1,75 @@
+# Решение 001: границы и правила первой версии Telegram-инфраструктуры
+
+Статус: рабочий черновик, требует подтверждения команды  
+Дата: 2026-07-31
+
+## Цель
+
+Проверить рабочий цикл «обсуждение в Telegram → экспорт → ручной анализ в ChatGPT → подтверждение → фиксация в Git/Gitea» на небольшом и безопасном объёме.
+
+Telegram не является хранилищем проекта, а бот и ChatGPT не принимают окончательных решений и не изменяют репозиторий без подтверждения команды.
+
+## Что входит в MVP
+
+- Telegram-супергруппа с темами `Общее` (стандартная тема), `MVP`, `Решения`, `Обсуждение` и `Работа с ИИ`.
+- Тема `MVP` используется только для обсуждения границ первой версии. После фиксации MVP тема закрывается.
+- Тема `Обсуждение` используется для рабочих гипотез и вопросов, которые ещё не стали подтверждёнными решениями.
+- В теме `Решения` бот публикует итоговые сводки и подтверждённые решения после завершения обсуждения. Сообщения бота являются единственным редактируемым источником итогового текста; пользователи не редактируют сообщения бота.
+- Тема `Работа с ИИ` закрытая: в ней публикуются только сообщения бота о корректных подходах, best practice, типичных ошибках и недопустимых формулировках при работе с ИИ. Отдельный FAQ будет подготовлен позднее как библиотека таких практик.
+- Бот принимает сообщения только из явно разрешённых тем.
+- Для сообщения сохраняются текст, автор, дата и время, тема, идентификатор сообщения и связь с ответом.
+- Экспорт выполняется по ручной отметке участника или по явно заданному диапазону темы.
+- Экспорт формируется в Markdown и включает контекст, сообщения по времени, ссылки и доступные вложения.
+- Участник вручную загружает экспорт в ChatGPT и возвращает результат в Telegram.
+- Gitea-уведомления на старте можно публиковать в `Общее` либо в отдельную тему после появления такой потребности. События ограничиваются PR, задачами, дедлайнами и сбоями важных проверок.
+- Подтверждённые решения и изменения документации фиксируются в Git/Gitea обычным review-процессом.
+
+## Что не входит в MVP
+
+- API-интеграция с языковой моделью и автоматический ИИ-чат.
+- Автоматическое принятие решений, изменение кода или создание PR без подтверждения.
+- Сбор всех сообщений группы по умолчанию.
+- Полнотекстовый поиск, RAG, векторная база и сложная аналитика.
+- Уведомление о каждом push, комментарии или техническом событии.
+
+## Правила данных и приватности
+
+1. Автоматически собираются только сообщения из согласованных рабочих тем.
+2. Ручной экспорт имеет приоритет над автоматическим сбором.
+3. Вложения экспортируются только если бот имеет к ним доступ и их включение разрешено правилами темы.
+4. Конфиденциальные, персональные и юридически чувствительные данные не отправляются во внешний сервис без отдельного разрешения команды.
+5. Срок хранения сообщений, вложений и экспортов должен быть утверждён до включения автоматического режима.
+6. Доступ к боту, архиву и уведомлениям получают только участники из согласованного списка.
+
+## Утверждённые решения
+
+- Используются темы `MVP`, `Решения`, `Обсуждение` и `Работа с ИИ`; тема `Общее` остаётся стандартной.
+- `MVP` закрывается после фиксации состава первой версии.
+- Итог обсуждения формирует бот и публикует в `Решения`.
+- `Работа с ИИ` предназначена только для публикаций бота и будет содержать best practice, а не обычный FAQ.
+- Остальные параметры первой версии из этого документа считаются утверждёнными, если команда не изменит их отдельным решением.
+
+## Граница между ботом и ИИ
+
+- Бот без обращения к API языковой модели полностью выполняет сбор сообщений, сортировку, добавление метаданных, подготовку вложений и формирование Markdown-экспорта.
+- Бот добавляет к экспорту готовую инструкцию для ручной загрузки в обычный ChatGPT.
+- Выделение решений, задач, рисков, противоречий и открытых вопросов выполняется в ChatGPT вручную через подписку участника.
+- Бот может принять возвращённый человеком отчёт, опубликовать его в Telegram и связать с исходным обсуждением.
+- Бот не выдаёт эвристический или шаблонный результат за выполненный ИИ-анализ. Поиск ключевых слов и ручные метки допустимы только как вспомогательная навигация.
+
+## Техническое замечание о правах тем
+
+Telegram позволяет запретить пользователям отправку сообщений в закрытой теме, но не даёт отдельного режима «пользователи обсуждают, а затем только бот публикует» внутри одной и той же открытой темы. Поэтому завершение обсуждения в `Решения` должно оформляться закрытием темы или переключением прав группы. В любом случае пользователи не смогут редактировать сообщения, отправленные ботом.
+
+## Инфраструктурные предпосылки
+
+- Доступы для настройки находятся в `credentials.txt`; секреты из этого файла нельзя включать в Git, логи CI/CD, экспорт Telegram или сообщения бота.
+- Для проекта можно создать открытый репозиторий в Gitea.
+- В Gitea необходимо настроить защиту `main`: прямые push запрещены, изменения проходят через pull request и проверки CI/CD.
+- Развёртывание бота планируется на Docker-инфраструктуре Synology.
+- PostgreSQL будет использоваться как хранилище бота; параметры доступа к базе будут предоставлены отдельно.
+- Почта может использоваться как дополнительный канал доставки файлов и отчётов, но не как основное хранилище.
+
+## Критерий завершения Stage 0
+
+Границы MVP, состав тем и правила работы с данными подтверждены. Остаётся реализовать жизненный цикл тем и экспортов, после чего можно проектировать схему хранения и команды бота, не меняя назначение первой версии по ходу реализации.