From b8b9ec75b3ed679311bc84ca9b1b28596525be7a Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Mon, 3 Aug 2026 01:32:44 +0300 Subject: [PATCH] refactor: organize repository around legal platform --- .gitattributes | 1 + README.md | 74 +++++++++++-------- docs/README.md | 27 +++++++ ...rules.md => 001-telegram-workspace-mvp.md} | 2 +- .../project-status.md} | 22 ++++-- .../operations/telegram-workspace-plan.md | 2 +- docs/product/project-overview.md | 47 ++++++++++++ docs/team/ai-skills-for-beginners.md | 2 +- .../telegram-bot/.env.example | 0 tools/telegram-bot/README.md | 51 +++++++++++++ bot.py => tools/telegram-bot/bot.py | 2 +- test_bot.py => tools/telegram-bot/test_bot.py | 0 12 files changed, 189 insertions(+), 41 deletions(-) create mode 100644 .gitattributes create mode 100644 docs/README.md rename docs/decisions/{001-mvp-boundaries-and-rules.md => 001-telegram-workspace-mvp.md} (99%) mode change 100755 => 100644 rename docs/{PROJECT_STATUS.md => operations/project-status.md} (81%) mode change 100755 => 100644 rename TEAM_AI_TELEGRAM_IMPLEMENTATION_PLAN.md => docs/operations/telegram-workspace-plan.md (99%) mode change 100755 => 100644 create mode 100644 docs/product/project-overview.md rename .env.example => tools/telegram-bot/.env.example (100%) create mode 100644 tools/telegram-bot/README.md rename bot.py => tools/telegram-bot/bot.py (99%) rename test_bot.py => tools/telegram-bot/test_bot.py (100%) diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6313b56 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto eol=lf diff --git a/README.md b/README.md index c59eb31..8ccd30a 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,58 @@ -# Акылдаш — бот-секретарь +# Акылдаш -Версия: `0.2.1` +Акылдаш — проект юридической информационно-аналитической платформы. Цель — +собирать правовые источники на законных основаниях, сохранять их происхождение +и версии, готовить данные для поиска и RAG, а затем предоставлять результаты +через API и пользовательский интерфейс со ссылками на первоисточники. -Бот сохраняет сообщения разрешённых тем Telegram в локальную SQLite-базу и -выгружает обсуждения в Markdown. Внешние Python-зависимости не требуются. +Telegram-бот — только часть рабочего окружения команды, а не основной продукт. -## Запуск +## Текущее состояние -Требуется Python 3.11 или новее. +Сейчас реализован Telegram-бот-секретарь версии `0.2.2`. Он сохраняет сообщения +рабочих тем, формирует Markdown-экспорты и отмечает завершённые обсуждения. -```bash -export TELEGRAM_BOT_TOKEN='...' -export TELEGRAM_CHAT_ID='-1004242041275' -export TELEGRAM_OWNER_ID='87262245' -export TELEGRAM_REPORT_THREAD_ID='37' -export TELEGRAM_ALLOWED_THREAD_IDS='0,2,4,6,8' -python3 bot.py +| Компонент | Версия | Состояние | +|---|---:|---| +| Telegram-бот | `0.2.2` | работает на Synology | +| Backend | — | ещё не создан | +| Frontend | — | ещё не создан | +| Сбор и обработка правовых данных | — | ещё не созданы | +| RAG и база знаний | — | ещё не созданы | + +## Структура репозитория + +```text +docs/ структурированная документация проекта + decisions/ принятые архитектурные и продуктовые решения + operations/ состояние проекта и рабочие процессы + product/ назначение, границы и развитие продукта + team/ материалы для команды +tools/ + telegram-bot/ бот рабочего Telegram-пространства ``` -Доступные команды: `/help`, `/status`, `/export`. -Экспорт доступен только пользователю с Telegram ID из `TELEGRAM_OWNER_ID`. -Первый `/export` выгружает всю сохранённую тему, последующие — сообщения после -предыдущей успешно созданной отсечки. -Markdown публикуется в теме `TELEGRAM_REPORT_THREAD_ID`, а в исходной теме -остаётся отсечка со ссылкой и общим хэштегом отчёта. +Каталоги для загрузки и обработки источников, RAG, backend и frontend будут +создаваться с первой реальной задачей в соответствующей области. Это позволит +выбрать структуру по фактическим требованиям, а не поддерживать пустой каркас. -База по умолчанию хранится в `data/secretary.sqlite3`. Сообщения из других -групп и тем не сохраняются. Полный ответ Telegram сохраняется в базе, поэтому -метаданные вложений остаются доступными для последующего скачивания. +Начать знакомство с проектом: [документация](docs/README.md) и +[обзор продукта](docs/product/project-overview.md). -## Проверка +## Конфиденциальные материалы + +Секреты, персональные данные, договоры и материалы по правовой защите проекта +не должны храниться в этом репозитории. Для них нужен отдельный закрытый +репозиторий или защищённое хранилище с минимально необходимыми правами доступа, +журналированием и резервным копированием. Здесь допустимы только несекретные +правила и ссылки на такие материалы без раскрытия их содержания. + +## Проверка Telegram-бота ```bash -python3 -m unittest -v +python3 -m unittest discover -s tools/telegram-bot -v ``` -## Synology - -Контейнер `akyldash-bot` работает на образе `python:3.11-slim` с политикой -перезапуска `unless-stopped`. Постоянные данные находятся в -`/volume1/docker/akyldash/data`. - --- -Акылдаш v0.2.1 +Акылдаш · Telegram-бот v0.2.2 · Backend — не создан · Frontend — не создан diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e279142 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,27 @@ +# Документация Акылдаш + +## Продукт + +- [Обзор проекта](product/project-overview.md) — назначение, основные области и + правила работы с данными. + +## Решения + +- [Решение 001](decisions/001-telegram-workspace-mvp.md) — границы MVP + Telegram-инфраструктуры. + +## Эксплуатация и рабочий процесс + +- [Текущий статус](operations/project-status.md) — выполненные шаги, риски и + ближайшие действия. +- [План Telegram-пространства](operations/telegram-workspace-plan.md) — темы, + роли и этапы развития командного окружения. + +## Команда + +- [Навыки работы с ИИ](team/ai-skills-for-beginners.md) — короткие практики для + начинающих. + +--- + +Акылдаш · Telegram-бот v0.2.2 · Backend — не создан · Frontend — не создан diff --git a/docs/decisions/001-mvp-boundaries-and-rules.md b/docs/decisions/001-telegram-workspace-mvp.md old mode 100755 new mode 100644 similarity index 99% rename from docs/decisions/001-mvp-boundaries-and-rules.md rename to docs/decisions/001-telegram-workspace-mvp.md index f3a4f2e..a7de588 --- a/docs/decisions/001-mvp-boundaries-and-rules.md +++ b/docs/decisions/001-telegram-workspace-mvp.md @@ -78,4 +78,4 @@ Telegram позволяет запретить пользователям отп --- -Акылдаш v0.2.1 +Акылдаш · Telegram-бот v0.2.2 diff --git a/docs/PROJECT_STATUS.md b/docs/operations/project-status.md old mode 100755 new mode 100644 similarity index 81% rename from docs/PROJECT_STATUS.md rename to docs/operations/project-status.md index 73bb1fd..a2dc2db --- a/docs/PROJECT_STATUS.md +++ b/docs/operations/project-status.md @@ -3,11 +3,13 @@ Последняя проверка: 2026-08-03 Назначение документа: быстро восстановить контекст проекта для участников команды и будущих агентов. -Версия приложения: `0.2.1` +- Telegram-бот: `0.2.2` +- Backend: не создан +- Frontend: не создан ## Краткий итог -Telegram-инфраструктура и первая версия бота-секретаря подготовлены. Бот сохраняет сообщения разрешённых тем в SQLite, экспортирует обсуждения в Markdown и постоянно запущен в Container Manager на Synology. +Репозиторий переориентирован с отдельного бота на весь проект юридической информационно-аналитической платформы. Telegram-бот выделен в инструмент рабочего окружения: он сохраняет сообщения разрешённых тем в SQLite, экспортирует обсуждения в Markdown и постоянно запущен в Container Manager на Synology. Ближайшая цель — 2026-08-04 зафиксировать MVP с командой, настроить резервное копирование SQLite и затем проверить полный рабочий цикл на реальном обсуждении. @@ -36,8 +38,9 @@ Telegram-инфраструктура и первая версия бота-се ### Документация и правила -- Подготовлен общий план реализации в `TEAM_AI_TELEGRAM_IMPLEMENTATION_PLAN.md`. -- Зафиксированы границы MVP и правила работы с данными в `docs/decisions/001-mvp-boundaries-and-rules.md`. +- Подготовлен общий план реализации в `docs/operations/telegram-workspace-plan.md`. +- Зафиксированы границы MVP и правила работы с данными в `docs/decisions/001-telegram-workspace-mvp.md`. +- Добавлены обзор всей платформы и единый индекс документации. - В MVP не входит автоматический вызов API языковой модели. - Анализ экспортов выполняется вручную в обычном ChatGPT. - Telegram используется как рабочий штаб, Git/Gitea — как источник утверждённых материалов. @@ -52,7 +55,8 @@ Telegram-инфраструктура и первая версия бота-се ### Репозиторий и приложение -- Реализован бот-секретарь версии `0.2.1` без внешних Python-зависимостей. +- Реализован бот-секретарь версии `0.2.2` без внешних Python-зависимостей. +- Код бота выделен из корня репозитория в `tools/telegram-bot`. - Сообщения и полные Telegram-метаданные сохраняются в SQLite. - Добавлены команды `/help`, `/status` и `/export`. - Экспорт доступен только владельцу, указанному в `TELEGRAM_OWNER_ID`. @@ -60,6 +64,7 @@ Telegram-инфраструктура и первая версия бота-се - Отчёты публикуются в закрытой теме `Отчеты` (`message_thread_id=37`). - Исходное обсуждение завершается заметной отсечкой со ссылкой и хэштегом отчёта. - Локальный Git-репозиторий восстановлен и привязан к Gitea. +- Репозиторий организован как основа всего проекта, а не отдельного бота. - Бот развёрнут в Container Manager на Synology; автозапуск после перезапуска менеджера проверен. ### Развёртывание @@ -67,6 +72,7 @@ Telegram-инфраструктура и первая версия бота-се - Бот постоянно запущен на Synology в контейнере `akyldash-bot`. - Используется официальный образ `python:3.11-slim` и long polling. - Контейнер работает без root, с read-only root filesystem и политикой `unless-stopped`. +- Доступ к Telegram Bot API идёт через отдельный закрытый прокси-контейнер без опубликованных наружу портов. - Код, закрытый env-файл и SQLite хранятся в `/volume1/docker/akyldash`. ## Пока не сделано @@ -120,6 +126,10 @@ Telegram-инфраструктура и первая версия бота-се ### 2026-08-03 +- Репозиторий перестроен под весь проект юридической платформы; Telegram-бот перенесён в `tools/telegram-bot`. +- Созданы обзор продукта и структурированный индекс документации; будущие каталоги решено создавать по фактическим задачам. +- Закрытые юридические материалы решено хранить отдельно от основного репозитория. +- Версия Telegram-бота обновлена до `0.2.2` из-за изменения структуры запуска. - Экспорт без параметров переведён с периода в семь дней на диапазон после предыдущей отсечки. - Бот развёрнут в Container Manager на Synology; автозапуск проверен перезапуском. - В теме `Работа с ИИ` опубликована первоначальная библиотека практик и отдельный материал о безопасной работе с Codex. @@ -151,4 +161,4 @@ Telegram-инфраструктура и первая версия бота-се --- -Акылдаш v0.2.1 +Акылдаш · Telegram-бот v0.2.2 · Backend — не создан · Frontend — не создан diff --git a/TEAM_AI_TELEGRAM_IMPLEMENTATION_PLAN.md b/docs/operations/telegram-workspace-plan.md old mode 100755 new mode 100644 similarity index 99% rename from TEAM_AI_TELEGRAM_IMPLEMENTATION_PLAN.md rename to docs/operations/telegram-workspace-plan.md index 50e9e93..d6d1969 --- a/TEAM_AI_TELEGRAM_IMPLEMENTATION_PLAN.md +++ b/docs/operations/telegram-workspace-plan.md @@ -398,4 +398,4 @@ Git сохраняет актуальную версию --- -Акылдаш v0.2.1 +Акылдаш · Telegram-бот v0.2.2 diff --git a/docs/product/project-overview.md b/docs/product/project-overview.md new file mode 100644 index 0000000..18d5ff7 --- /dev/null +++ b/docs/product/project-overview.md @@ -0,0 +1,47 @@ +# Обзор проекта + +## Назначение + +Акылдаш — юридическая информационно-аналитическая платформа. Она должна помочь +пользователю находить применимые нормы и материалы, понимать их актуальность и +получать ответ со ссылками на проверяемые первоисточники. Платформа не заменяет +профессиональное юридическое заключение. + +## Основные области + +1. Получение открытых или лицензированных законов, актов и иных правовых + источников. +2. Очистка, нормализация, связывание редакций и сохранение происхождения данных. +3. Хранение структурированных документов и поисковых индексов. +4. Формирование базы знаний и RAG с обязательными ссылками на источники. +5. Backend для доступа к данным и функциям платформы. +6. Frontend для поиска, анализа и работы с результатами. +7. Инструменты рабочего окружения команды, включая Telegram-бота. + +Физическая структура каждой области появится вместе с её первой задачей. До +этого список служит картой продукта, а не обещанием заранее выбранной +архитектуры. + +## Обязательные принципы + +- Источник, дата получения, редакция и лицензия документа должны быть + прослеживаемыми. +- Ответ системы должен отделять найденный факт от вывода модели и ссылаться на + конкретный первоисточник. +- Актуальность правовых данных должна проверяться до использования в ответе. +- Существенные юридические выводы проверяет человек. +- Секреты и персональные данные не попадают в Git, логи и тестовые наборы. +- Данные загружаются только при наличии законного основания и с соблюдением + условий источника. + +## Правовая защита проекта + +Договоры, заявки, материалы об интеллектуальной собственности и другие +закрытые юридические документы следует хранить отдельно от исходного кода: в +закрытом репозитории или защищённом документном хранилище. Доступ выдаётся +поимённо и только тем, кому он нужен. В основном репозитории можно хранить +несекретный реестр документов, правила доступа и ссылки на место хранения. + +--- + +Акылдаш · Telegram-бот v0.2.2 · Backend — не создан · Frontend — не создан diff --git a/docs/team/ai-skills-for-beginners.md b/docs/team/ai-skills-for-beginners.md index 96c4e49..9cdb473 100644 --- a/docs/team/ai-skills-for-beginners.md +++ b/docs/team/ai-skills-for-beginners.md @@ -180,4 +180,4 @@ --- -Акылдаш v0.2.1 +Акылдаш · Telegram-бот v0.2.2 diff --git a/.env.example b/tools/telegram-bot/.env.example similarity index 100% rename from .env.example rename to tools/telegram-bot/.env.example diff --git a/tools/telegram-bot/README.md b/tools/telegram-bot/README.md new file mode 100644 index 0000000..b8918af --- /dev/null +++ b/tools/telegram-bot/README.md @@ -0,0 +1,51 @@ +# Telegram-бот Акылдаш + +Версия: `0.2.2` + +Бот сохраняет сообщения разрешённых тем Telegram в локальную SQLite-базу и +выгружает обсуждения в Markdown. Внешние Python-зависимости не требуются. + +## Запуск + +Требуется Python 3.11 или новее. + +```bash +cd tools/telegram-bot +export TELEGRAM_BOT_TOKEN='...' +export TELEGRAM_CHAT_ID='-1004242041275' +export TELEGRAM_OWNER_ID='87262245' +export TELEGRAM_REPORT_THREAD_ID='37' +export TELEGRAM_ALLOWED_THREAD_IDS='0,2,4,6,8' +python3 bot.py +``` + +Доступные команды: `/help`, `/status`, `/export`. Экспорт доступен только +пользователю с Telegram ID из `TELEGRAM_OWNER_ID`. Первый `/export` выгружает +всю сохранённую тему, последующие — сообщения после предыдущей успешно +созданной отсечки. + +Markdown публикуется в теме `TELEGRAM_REPORT_THREAD_ID`, а в исходной теме +остаётся отсечка со ссылкой и общим хэштегом отчёта. + +База по умолчанию хранится в `data/secretary.sqlite3`. Сообщения из других +групп и тем не сохраняются. Полный ответ Telegram сохраняется в базе, поэтому +метаданные вложений остаются доступными для последующего скачивания. + +## Проверка + +```bash +python3 -m unittest -v +``` + +## Synology + +Контейнер `akyldash-bot` работает на образе `python:3.11-slim` через закрытый +прокси-контейнер, с политикой перезапуска `unless-stopped`. Постоянные данные +находятся в `/volume1/docker/akyldash/data`. + +При обновлении развёртывания файл `tools/telegram-bot/bot.py` копируется в +каталог контейнера как `bot.py`. + +--- + +Акылдаш · Telegram-бот v0.2.2 diff --git a/bot.py b/tools/telegram-bot/bot.py similarity index 99% rename from bot.py rename to tools/telegram-bot/bot.py index 36487c6..c0d2902 100755 --- a/bot.py +++ b/tools/telegram-bot/bot.py @@ -18,7 +18,7 @@ from zoneinfo import ZoneInfo, ZoneInfoNotFoundError APP_NAME = "Акылдаш" -APP_VERSION = "0.2.1" +APP_VERSION = "0.2.2" FOOTER = f"{APP_NAME} v{APP_VERSION}" diff --git a/test_bot.py b/tools/telegram-bot/test_bot.py similarity index 100% rename from test_bot.py rename to tools/telegram-bot/test_bot.py