angel/site_aegisone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f06ecaabe3147cee46641b8a706b00775c6831fa
site_aegisone/AGENTS.md
T

12 KiB
Raw Blame History

Правила проекта AegisOne

Любой AI-агент ОБЯЗАН прочитать этот файл перед началом работы.

0. Базовые правила

0.1. Если что-то не знаешь — спроси! Не додумывай, не предполагай. 0.2. Любое общение только на русском языке. Код, комментарии, коммиты, CHANGELOG — всё по-русски. 0.3. Если предлагаешь варианты — обязательно указывай рекомендацию и пояснение.

0.4. Обязательные файлы для чтения

Перед началом работы агент ОБЯЗАН прочитать:

Файл Содержание Когда читать
AGENTS.md Правила проекта (этот файл) Всегда, перед началом работы
other/AI-EXISTING-TWO-PROJECT-INSTRUCTION.md Архитектура сервера, порты, Docker-проекты, команды Перед работой с сервером, деплоем, диагностикой
py_service/SERVICE_STYLE_GUIDE.md Стили UI, CSS-классы, паттерны шаблонов Перед работой с фронтендом портала

1. Архитектура проекта

Часть Домен Стек Статус
Публичная aegisone.ru PHP ✅ ГОТОВА — НЕ ТРОГАТЬ!
Сервисная service.aegisone.ru Python/FastAPI В разработке
Бот max.aegisone.ru Python/FastAPI В разработке

ВАЖНО: Публичная часть полностью готова и не подлежит изменениям!

Подробная архитектура сервера: other/AI-EXISTING-TWO-PROJECT-INSTRUCTION.md — порты, Docker-проекты, команды, troubleshooting.

2. Версионирование

  • Формат: Semantic Versioning (major.minor.patch)
    • major — ломающие изменения API/БД
    • minor — новый функционал
    • patch — исправления багов, косметические правки
  • Единый CHANGELOG: py_service/CHANGELOG.md
  • version.txt: py_service/version.txt и max_bot/version.txt — текущая версия
  • Агент ОБЯЗАН обновить version.txt и CHANGELOG.md перед каждым деплоем

Формат CHANGELOG

## X.Y.Z (ДД.ММ.ГГГГ)
### Новые функции
- **Описание:** что сделано
### Исправления
- **Код (описание):** что исправлено

Формат коммитов

vX.Y.Z: краткое описание изменений

Пример: v1.8.2: fix consent flow — split-based word matching, revoke consent

3. Workflow (порядок работы)

  1. Получаешь задачу
  2. Анализируешь код → предлагаешь варианты с рекомендацией и пояснением
  3. Пользователь одобряет
  4. Пишешь/переписываешь код с комментариями
  5. Удаляешь мусор из кода
  6. Запускаешь тесты локально
  7. Обновляешь version.txt и CHANGELOG.md
  8. Коммитишь
  9. Деплоишь на сервер
  10. Проверяешь логи
  • Ветвление: всё в main (без feature-веток)
  • Локальная копия = git clone. Правки сначала локально, потом деплой.
  • Не портить то что есть. Если сомневаешься — спроси.

4. Комментарии в коде (ОБЯЗАТЕЛЬНО)

Любой человек или AI-агент должны сразу понимать что за часть кода и для чего.

Требования:

  1. Каждый файл имеет шапку с описанием назначения файла
  2. Каждая функция имеет docstring: 
    async def handle_consent_yes(user_id: int, conv_id: int) -> None:
    """Обработка согласия пользователя на обработку ПД.

    Устанавливает consent_given=True, consent_date=now(),
    переводит диалог в состояние awaiting_contact.
    """
  3. Каждый неочевидный блок имеет комментарий: 
    # Проверяем, не истёк ли таймаут диалога (10 минут)
if conv.created_at and conv.created_at < stale_threshold:
    conv = BotConversation(...)  # Создаём новый диалог
  4. Импорты группируются и комментируются при необходимости
  5. Комментарии на русском языке

Что НЕ комментировать:

  • Очевидный код (if user: user.name = name)
  • Геттеры/сеттеры
  • Стандартные паттерны (async with session() as db:)

5. Тесты

  • Тесты ОБЯЗАНЫ пройти перед деплоем
  • Основное тестирование: локально (pytest)
  • CI (GitHub Actions): страховка при пуше в main

Как запускать тесты:

# py_service
cd py_service && pytest -v --tb=short -x

# max_bot
cd max_bot && pytest -v --tb=short -x

# Линтер
ruff check py_service/
  • Если тестов нет для нового функционала — пишем
  • Минимальный тест: проверка что код не падает с ошибкой

6. Миграции БД

  • SQL-файлы в migrations/ (формат: 001_description.sql)
  • Таблица _applied_migrations для отслеживания
  • Автоприменение при старте приложения
  • Пользователь НЕ лазает на сервер вручную

Backup:

  • Делать pg_dump только при рисках сломать данные
  • Не засорять сервер старыми бэкапами и логами
  • При низком риске — мигрируем без бэкапа

7. Безопасность

  1. Секреты только в .env — никогда в коде, коммитах, логах
  2. Валидация входящих данных — любые данные проверяются перед использованием
  3. Защита от SQL-инъекций — SQL через ORM, никогда через конкатенацию строк
  4. Безопасность логов — логи НЕ содержат пароли, токены, персональные данные

8. Обработка ошибок

try:
    # операция
except Exception as e:
    logger.exception(f"Описание ошибки: {e}")
    # Пользователю — понятное сообщение, НЕ стектрейс
  • try/except с логированием + пользовательское сообщение
  • Никогда не показывать стектрейс пользователю
  • logger.exception для исключений (автоматически добавляет стектрейс в лог)
  • logger.error для ошибок бизнес-логики

9. Деплой

Сервер: angel@81.177.141.34

Контейнеры:

Контейнер Назначение Порт
max_bot Бот 8002
aegisone-app Сервисный портал 8000
aegisone-postgres PostgreSQL 5432

Порядок деплоя:

# 1. scp файлов на сервер
scp file.py angel@81.177.141.34:/home/angel/deploy/

# 2. docker cp в контейнер
# ВАЖНО: max_bot — путь /app/app/, НЕ /app/!
docker cp /home/angel/deploy/file.py max_bot:/app/app/file.py
docker cp /home/angel/deploy/file.py aegisone-app:/app/app/file.py

# 3. Очистка __pycache__
docker exec max_bot rm -rf /app/app/handlers/__pycache__ /app/app/__pycache__

# 4. Перезапуск
docker restart max_bot
docker restart aegisone-app

# 5. Проверка
docker ps
docker logs max_bot --tail 10
docker logs aegisone-app --tail 10

Кодировка:

  • Все файлы UTF-8
  • scp / docker cp сохраняют кодировку
  • НЕ использовать sed / echo для изменения файлов в контейнере

10. Код

  • ruff — линтер для Python (запускать перед коммитом)
  • UTF-8 — кодировка всех файлов
  • Комментарии — ОБЯЗАТЕЛЬНЫ (см. раздел 4)
  • Следуй существующему стилю кода
  • Удаляй неиспользуемый код при изменениях
  • Не добавляй лишних зависимостей без необходимости

11. Стили UI (сервисный портал)

  • Единый гайд: py_service/SERVICE_STYLE_GUIDE.md — читать перед работой с фронтендом
  • Нельзя использовать confirm(), alert(), prompt() — только showNotification() и кастомные модалки
  • Удаление: простая модалка (Variant A), кнопки: Действие (слева) → Отмена (справа)
  • Иконки: ✕ = удалить, ✎ = редактировать, + = создать
  • Модалки: .modal-overlay + .modal, открытие через classList.add('open')
  • Структура страницы: card > card-header > filter-bar > table-wrap > table
  • CSS классы кнопок: .btn-primary (создать), .btn-secondary (редактировать), .btn-danger (удалить), .btn-success (выполнено)
  • Сортировка таблиц: sort-table.js подключён глобально в base.html, автоматически сортирует все <table> по клику на <th> (текст/число/дата)
  • Number input: спиннеры скрыты глобально через CSS (service.css), type="number" выглядит как обычный input

12. Идеи

  • Страница: /service/ideas
  • Агент может: видеть список идей, добавлять новые, менять статус, предлагать к реализации, реализовывать
  • Статусы: normal → in_progress → completed → normal
  • API: POST /service/ideas/create (title, description), POST /service/ideas/status (id), POST /service/ideas/delete (id)
  • Агент может добавить идею по просьбе пользователя через API
  • Агент может реализовать идею, создав/изменив код, и предложить к реализации
Reference in New Issue View Git Blame Copy Permalink