refactor: organize repository around legal platform

docs/operations/project-status.md

@@ -0,0 +1,164 @@
+# Статус проекта
+
+Последняя проверка: 2026-08-03
+Назначение документа: быстро восстановить контекст проекта для участников команды и будущих агентов.
+
+- Telegram-бот: `0.2.2`
+- Backend: не создан
+- Frontend: не создан
+
+## Краткий итог
+
+Репозиторий переориентирован с отдельного бота на весь проект юридической информационно-аналитической платформы. Telegram-бот выделен в инструмент рабочего окружения: он сохраняет сообщения разрешённых тем в SQLite, экспортирует обсуждения в Markdown и постоянно запущен в Container Manager на Synology.
+
+Ближайшая цель — 2026-08-04 зафиксировать MVP с командой, настроить резервное копирование SQLite и затем проверить полный рабочий цикл на реальном обсуждении.
+
+## Уже сделано
+
+### Telegram
+
+- Создана супергруппа `Акылдаш`.
+- Создан бот `help_clerk_bot`.
+- Бот добавлен в супергруппу с необходимыми правами.
+- Privacy Mode бота отключён.
+- Созданы и проверены рабочие темы.
+- Проверено подключение к Telegram Bot API.
+- Webhook у бота не установлен; доступен режим long polling через `getUpdates`.
+
+### ID тем
+
+| Тема | `message_thread_id` | Состояние |
+|---|---:|---|
+| Общее | отсутствует | приветствие закреплено, тема закрыта |
+| MVP | `2` | подтверждено тестовым сообщением |
+| Решения | `4` | подтверждено тестовым сообщением |
+| Обсуждение | `6` | подтверждено тестовым сообщением |
+| Работа с ИИ | `8` | материалы опубликованы, тема закрыта |
+| Отчеты | `37` | экспорт проверен, тема закрыта |
+
+### Документация и правила
+
+- Подготовлен общий план реализации в `docs/operations/telegram-workspace-plan.md`.
+- Зафиксированы границы MVP и правила работы с данными в `docs/decisions/001-telegram-workspace-mvp.md`.
+- Добавлены обзор всей платформы и единый индекс документации.
+- В MVP не входит автоматический вызов API языковой модели.
+- Анализ экспортов выполняется вручную в обычном ChatGPT.
+- Telegram используется как рабочий штаб, Git/Gitea — как источник утверждённых материалов.
+- Подготовлены и опубликованы краткие навыки работы с ИИ для начинающих.
+- В `Общее` опубликовано и закреплено приветствие с назначением тем и описанием бота.
+
+### Доступы
+
+- Локальные доступы находятся в `credentials.json`.
+- `credentials.json` добавлен в `.gitignore`.
+- Секреты нельзя добавлять в Git, логи, экспорты или сообщения бота.
+
+### Репозиторий и приложение
+
+- Реализован бот-секретарь версии `0.2.2` без внешних Python-зависимостей.
+- Код бота выделен из корня репозитория в `tools/telegram-bot`.
+- Сообщения и полные Telegram-метаданные сохраняются в SQLite.
+- Добавлены команды `/help`, `/status` и `/export`.
+- Экспорт доступен только владельцу, указанному в `TELEGRAM_OWNER_ID`.
+- Первый `/export` охватывает всю сохранённую тему, последующие начинаются после последней успешно созданной отсечки.
+- Отчёты публикуются в закрытой теме `Отчеты` (`message_thread_id=37`).
+- Исходное обсуждение завершается заметной отсечкой со ссылкой и хэштегом отчёта.
+- Локальный Git-репозиторий восстановлен и привязан к Gitea.
+- Репозиторий организован как основа всего проекта, а не отдельного бота.
+- Бот развёрнут в Container Manager на Synology; автозапуск после перезапуска менеджера проверен.
+
+### Развёртывание
+
+- Бот постоянно запущен на Synology в контейнере `akyldash-bot`.
+- Используется официальный образ `python:3.11-slim` и long polling.
+- Контейнер работает без root, с read-only root filesystem и политикой `unless-stopped`.
+- Доступ к Telegram Bot API идёт через отдельный закрытый прокси-контейнер без опубликованных наружу портов.
+- Код, закрытый env-файл и SQLite хранятся в `/volume1/docker/akyldash`.
+
+## Пока не сделано
+
+### Развёртывание и сопровождение
+
+- Docker-конфигурация развёртывания не хранится в репозитории.
+- Не настроен CI/CD.
+
+### Хранилище
+
+- PostgreSQL не подключён; первая версия использует SQLite.
+- Не утверждена окончательная схема PostgreSQL.
+- Не определены сроки хранения сообщений, вложений и экспортов.
+
+### Функции бота
+
+- Скачивание файлов вложений; сейчас сохраняются их Telegram-метаданные.
+- Ручная пометка отдельных сообщений для экспорта.
+- Формирование готовой инструкции для ручной загрузки в ChatGPT.
+- Возврат отчёта пользователя в Telegram.
+
+### Группа и рабочий процесс
+
+- Не проверены сценарии закрытия темы `MVP` после фиксации состава первой версии.
+- Не настроены уведомления Gitea.
+- Не проведён полный пользовательский тест: сообщение → сохранение → экспорт → анализ в ChatGPT → возврат отчёта.
+
+## Важные неизвестные
+
+По мере реального использования нужно принять решения по следующим вопросам:
+
+1. Адрес и параметры PostgreSQL для разработки и Synology.
+2. Правила хранения и удаления сообщений и вложений.
+3. Нужен ли webhook после постоянного развёртывания; первая версия работает через long polling.
+
+## Следующий этап
+
+### Фиксация MVP и проверка полного цикла
+
+Рекомендуемый порядок:
+
+1. Настроить резервное копирование `/volume1/docker/akyldash/data`.
+2. Зафиксировать состав MVP с командой и закрыть тему `MVP`.
+3. Провести одно реальное обсуждение с ответами, правками и вложением.
+4. Экспортировать обсуждение и вручную проанализировать Markdown в ChatGPT.
+5. Вернуть подтверждённый итог в тему `Решения` и зафиксировать его в Git/Gitea.
+6. Записать обнаруженные неудобства и только после этого выбирать следующую доработку.
+
+## История изменений статуса
+
+### 2026-08-03
+
+- Репозиторий перестроен под весь проект юридической платформы; Telegram-бот перенесён в `tools/telegram-bot`.
+- Созданы обзор продукта и структурированный индекс документации; будущие каталоги решено создавать по фактическим задачам.
+- Закрытые юридические материалы решено хранить отдельно от основного репозитория.
+- Версия Telegram-бота обновлена до `0.2.2` из-за изменения структуры запуска.
+- Экспорт без параметров переведён с периода в семь дней на диапазон после предыдущей отсечки.
+- Бот развёрнут в Container Manager на Synology; автозапуск проверен перезапуском.
+- В теме `Работа с ИИ` опубликована первоначальная библиотека практик и отдельный материал о безопасной работе с Codex.
+- В `Общее` опубликовано и закреплено приветствие; тема закрыта для сообщений.
+- Локальный файл доступов переведён из `credentials.txt` в `credentials.json`.
+
+### 2026-08-02
+
+- Экспорт ограничен Telegram ID владельца бота.
+- Технические ответы на корневое сообщение темы исключены из Markdown.
+- Экспорт перенесён в тему `Отчеты`, добавлены отсечки и навигационные хэштеги.
+- Проверена живая публикация отчёта и отсечки через Telegram Bot API.
+- Бот версии `0.2.0` развёрнут в Container Manager на Synology.
+- Версия приложения обновлена до `0.2.0`.
+
+### 2026-08-01
+
+- Восстановлена связь локального каталога с репозиторием Gitea.
+- Реализован бот-секретарь версии `0.1.0` с SQLite и Markdown-экспортом.
+- Проверены токен `help_clerk_bot` и доступ к супергруппе `Акылдаш`.
+
+### 2026-07-31
+
+- Создана супергруппа и добавлен бот.
+- Отключён Privacy Mode.
+- Определены ID тем: `2`, `4`, `6`, `8`.
+- Подтверждено отсутствие webhook.
+- Зафиксировано, что код бота и хранилище ещё не реализованы.
+
+---
+
+Акылдаш · Telegram-бот v0.2.2 · Backend — не создан · Frontend — не создан

docs/operations/telegram-workspace-plan.md

@@ -0,0 +1,401 @@
+# План реализации командной инфраструктуры 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. Этапы реализации
+
+Обозначения: `[x]` — выполнено, `[ ]` — ещё не выполнено.
+
+### Этап 0. Границы и правила
+
+- [x] утвердить назначение Telegram, Git, бота и ChatGPT;
+- [x] выбрать темы, которые бот слушает;
+- [x] определить, что можно собирать автоматически;
+- [x] определить правила обработки персональных и конфиденциальных данных;
+- [x] определить формат решений, задач и экспортов.
+
+### Этап 1. Рабочая Telegram-группа
+
+- [x] создать супергруппу и темы;
+- [x] подготовить и закрепить приветствие с навигацией;
+- [x] создать первоначальную библиотеку практик работы с ИИ;
+- [x] согласовать правила обсуждений и фиксации решений.
+
+### Этап 2. Бот-архиватор
+
+- [x] реализовать приём сообщений;
+- [x] сохранять сообщения и метаданные вложений;
+- [ ] добавить ручную отметку отдельных сообщений для экспорта;
+- [x] сформировать Markdown-экспорт;
+- [x] проверить работу с темами и ответами.
+
+### Этап 3. Уведомления
+
+- [ ] подключить события Gitea;
+- [ ] настроить фильтрацию;
+- [ ] направлять уведомления в отдельную тему;
+- [ ] добавить напоминания о задачах и сроках.
+
+### Этап 4. ИИ-подготовка без API
+
+- [ ] добавить шаблоны запросов для анализа;
+- [x] создавать готовые файлы для загрузки в ChatGPT;
+- [ ] добавить возврат отчёта в Telegram;
+- [ ] проверить несколько реальных обсуждений.
+
+### Этап 5. Связка с Git/Gitea
+
+- [x] подготовить структуру документации;
+- [ ] настроить ссылки на задачи, PR и документы;
+- [x] определить процесс переноса подтверждённых решений в Git;
+- [ ] добавить сценарии обновления документации через ИИ.
+
+### Этап 6. Улучшение по фактическому использованию
+
+- [ ] удалить невостребованные функции;
+- [ ] расширить библиотеку практик реальными сценариями команды;
+- [ ] улучшить формат отчётов;
+- [ ] добавить новые уведомления только при наличии потребности;
+- [ ] оценить необходимость API и автоматического ИИ-анализа.
+
+---
+
+## 10. Критерии готовности первой версии
+
+Первая версия считается пригодной к работе, если:
+
+- команда может общаться по темам без технических препятствий;
+- участник может найти нужный рабочий сценарий для ИИ;
+- бот сохраняет сообщения из согласованных тем;
+- выбранное обсуждение экспортируется в читаемый Markdown;
+- экспорт можно загрузить в ChatGPT и получить структурированный результат;
+- отчёт можно вернуть в Telegram;
+- уведомления о PR и задачах приходят в отдельную тему без лишнего шума;
+- подтверждённые решения и изменения документации фиксируются в Git;
+- участникам не нужно изучать внутреннюю реализацию бота.
+
+---
+
+## 11. Что сознательно не входит в первую версию
+
+- автоматическое принятие решений ИИ;
+- полноценный ИИ-чат с API;
+- сложная векторная база и RAG;
+- автоматическое изменение кода без подтверждения;
+- попытка хранить всю базу проекта в Telegram;
+- обязательное обучение юристов Git-командам;
+- чрезмерное количество тем, команд и уведомлений;
+- автоматическая обработка всех сообщений без правил приватности и фильтрации.
+
+---
+
+## 12. Возможности следующего этапа
+
+После того как команда накопит опыт работы, можно добавить:
+
+- автоматические ежедневные и недельные сводки;
+- кнопку «проанализировать обсуждение»;
+- интерактивное подтверждение проекта решения;
+- автоматическое выделение задач и дедлайнов;
+- поиск по архиву обсуждений;
+- проверку согласованности документов проекта;
+- автоматическую подготовку pull request для документации;
+- интеграцию с API языковой модели;
+- поиск по проектной документации и истории решений;
+- аналитику нерешённых вопросов и повторяющихся проблем.
+
+Переход к API имеет смысл только тогда, когда ручной процесс станет понятным и появится регулярная потребность в автоматических отчётах или поиске.
+
+---
+
+## 13. Главный принцип проекта
+
+Команда должна формулировать рабочую задачу обычным языком. Telegram и готовые сценарии снижают порог входа, ИИ помогает перевести намерение в структурированный результат, а Git сохраняет утверждённую версию проекта.
+
+```text
+Человек формулирует намерение
+        ↓
+Telegram и ИИ помогают его оформить
+        ↓
+Команда проверяет и принимает результат
+        ↓
+Git сохраняет актуальную версию
+```
+
+Цель инфраструктуры — не заставить специалистов изучать больше технологий, а сделать технологии удобным продолжением их профессиональной работы.
+
+---
+
+Акылдаш · Telegram-бот v0.2.2