# Структура проекта Debian Repository Manager

## Обзор

```
repomanager/
├── 📁 repomanager/              # Основной пакет Python
│   └── __init__.py              # Package initialization
├── 📁 tests/                    # Тесты
│   └── __init__.py              # Tests initialization
├── 📁 .github/                  # GitHub Actions workflows (будет создан)
│   └── workflows/
│       ├── add-packages.yml
│       ├── cleanup-repo.yml
│       └── create-repo.yml
├── 📄 README.md                 # Основная документация и quick start
├── 📄 PLAN.md                   # План реализации по фазам с зависимостями
├── 📄 ARCHITECTURE.md           # Архитектурные решения и дизайн
├── 📄 IMPLEMENTATION_STEPS.md   # Пошаговая инструкция с примерами кода
├── 📄 CONFIG.md                 # Детальное описание конфигурации
├── 📄 DEVELOPMENT.md            # Руководство для разработчиков
├── 📄 CHANGELOG.md              # История изменений
├── 📄 LICENSE                   # MIT License
├── 📄 config.yaml.example       # Шаблон конфигурации
├── 📄 requirements.txt          # Python зависимости
├── 📄 setup.py                  # Установочный скрипт
├── 📄 pyproject.toml            # Конфигурация black, mypy, pytest
├── 📄 pytest.ini                # Конфигурация pytest
├── 📄 .flake8                   # Конфигурация flake8
├── 📄 Makefile                  # Команды для разработки
└── 📄 .gitignore                # Git ignore правила
```

## Документация

### Для пользователей

| Файл | Описание | Когда читать |
|------|----------|--------------|
| **README.md** | Основная документация, quick start, примеры использования | Первым делом для понимания проекта |
| **CONFIG.md** | Детальное описание всех параметров конфигурации | При настройке системы |
| **ARCHITECTURE.md** | Архитектурные решения, структура хранения | Для понимания как работает внутри |

### Для разработчиков

| Файл | Описание | Когда читать |
|------|----------|--------------|
| **PLAN.md** | План реализации по фазам, зависимости между модулями | Перед началом разработки |
| **IMPLEMENTATION_STEPS.md** | Пошаговая инструкция реализации каждого модуля с примерами кода | При реализации конкретного модуля |
| **DEVELOPMENT.md** | Setup окружения, code style, тестирование, workflow | Для настройки dev окружения |
| **CHANGELOG.md** | История изменений | Перед релизом или для понимания что изменилось |

## Модули (будут реализованы)

### Основные модули

```
repomanager/
├── __init__.py          # Package initialization, экспорт основных классов
├── cli.py               # CLI interface (click/argparse), entry point
├── config.py            # Configuration management (YAML loading, merging)
├── aptly.py             # Aptly wrapper (repo, snapshot, publish операции)
├── retention.py         # Retention policy logic
├── gpg.py               # GPG operations (signing, key management)
└── utils.py             # Utility functions (logging, version comparison, deb parsing)
```

### Тесты

```
tests/
├── __init__.py
├── test_config.py       # Тесты для config.py
├── test_aptly.py        # Тесты для aptly.py (с моками)
├── test_retention.py    # Тесты для retention.py
├── test_gpg.py          # Тесты для gpg.py (с моками)
├── test_utils.py        # Тесты для utils.py
└── test_cli.py          # Интеграционные тесты CLI
```

## Конфигурация проекта

### Python Package

- **setup.py**: Классический setup script для установки
- **pyproject.toml**: Современный конфиг (PEP 517/518) + настройки для black, mypy, pytest
- **requirements.txt**: Все зависимости (runtime + dev)

### Code Quality

- **.flake8**: Линтер (PEP 8 compliance)
- **pyproject.toml [tool.black]**: Автоформатирование кода
- **pyproject.toml [tool.mypy]**: Type checking
- **pytest.ini** / **pyproject.toml [tool.pytest]**: Конфигурация тестов

### Development Tools

- **Makefile**: Удобные команды для разработки
  ```bash
  make install-dev    # Установка с dev зависимостями
  make test           # Запуск тестов
  make lint           # Линтинг
  make format         # Форматирование
  make check-all      # Все проверки
  ```

## Workflow разработки

### 1. Первоначальная настройка

```bash
# Клонирование
git clone <repo-url>
cd repomanager

# Setup окружения
python3 -m venv venv
source venv/bin/activate

# Установка
make install-dev

# Проверка
make check-all
```

### 2. Разработка нового модуля

1. Читаем **PLAN.md** → понимаем какой модуль в какой фазе
2. Читаем **IMPLEMENTATION_STEPS.md** → смотрим API и примеры
3. Пишем тесты (TDD)
4. Реализуем модуль
5. Запускаем `make check-all`
6. Commit & Push

### 3. Интеграция GitHub Actions

После реализации CLI команд:

1. Создаём workflow файлы в `.github/workflows/`
2. Настраиваем GitHub Secrets
3. Тестируем workflows
4. Документируем использование в README

## Зависимости модулей

```
config.py (базовый, независимый)
    ↓
    ├─→ aptly.py (зависит от config)
    │       ↓
    │   add/create-repo/delete-repo команды
    │
    ├─→ retention.py (зависит от config)
    │       ↓
    │   cleanup команда
    │
    └─→ gpg.py (зависит от config)
            ↓
        используется в aptly.py для signing
```

## Порядок реализации (рекомендуемый)

### Фаза 1: Core (неделя 1)
1. ✅ Структура проекта + документация
2. ⏳ `config.py` - загрузка конфигурации
3. ⏳ `utils.py` - вспомогательные функции
4. ⏳ `aptly.py` - базовый wrapper

### Фаза 2: CLI Basic (неделя 2)
5. ⏳ `cli.py` - основная структура CLI
6. ⏳ Команда `add` - добавление пакетов
7. ⏳ Команда `create-repo` - создание репозитория
8. ⏳ Команда `list` - просмотр репозиториев

### Фаза 3: Retention & Cleanup (неделя 3)
9. ⏳ `retention.py` - логика retention policy
10. ⏳ Команда `cleanup` - очистка старых пакетов
11. ⏳ `gpg.py` - GPG интеграция

### Фаза 4: GitHub Actions (неделя 4)
12. ⏳ Workflow `add-packages.yml`
13. ⏳ Workflow `cleanup-repo.yml`
14. ⏳ Workflow `create-repo.yml`
15. ⏳ Тестирование в реальном окружении

## Текущий статус

- ✅ Документация полностью готова
- ✅ Структура проекта создана
- ✅ Конфигурационные файлы настроены
- ⏳ Модули Python (в процессе реализации)
- ⏳ Тесты (будут написаны)
- ⏳ GitHub Actions workflows (будут созданы)

## Быстрый старт для контрибьюторов

```bash
# 1. Fork и клонирование
git clone <your-fork-url>
cd repomanager

# 2. Setup
make install-dev

# 3. Выбрать задачу из PLAN.md (смотрим независимые шаги)
# 4. Прочитать IMPLEMENTATION_STEPS.md для выбранного модуля
# 5. Написать тесты
# 6. Реализовать
# 7. Проверить
make check-all

# 8. Commit & PR
git checkout -b feature/my-feature
git commit -m "Add feature X"
git push origin feature/my-feature
```

## Полезные команды

```bash
# Разработка
make test              # Запуск тестов
make test-coverage     # Тесты с coverage
make lint              # Линтинг
make format            # Форматирование кода
make type-check        # Type checking
make check-all         # Все проверки сразу

# Очистка
make clean             # Удалить build артефакты

# Помощь
make help              # Показать все доступные команды
```

## Контакты и поддержка

- **Issues**: https://github.com/jethome/repomanager/issues
- **Discussions**: https://github.com/jethome/repomanager/discussions
- **Email**: support@jethome.ru

## Лицензия

MIT License - см. [LICENSE](LICENSE)

