305 lines
11 KiB
Markdown
305 lines
11 KiB
Markdown
# PerfReviewSummarizer
|
||
|
||
ASP.NET Minimal API приложение для анализа git-коммитов и формирования summary за период (квартал/полугодие).
|
||
|
||
## Возможности
|
||
|
||
- Чтение коммитов из локального git-репозитория
|
||
- Анализ коммитов за указанный период (квартал, полугодие или произвольный период)
|
||
- Автоматическая категоризация коммитов по типам изменений
|
||
- Формирование статистики и summary
|
||
- **AI Summary с OpenAI** - получение интеллектуального резюме через GPT
|
||
- **Веб-интерфейс** для удобного взаимодействия с API
|
||
- **Swagger UI** для документации и тестирования API
|
||
|
||
## Технологии
|
||
|
||
- .NET 10
|
||
- ASP.NET Minimal API
|
||
- LibGit2Sharp для работы с git
|
||
- OpenAI API для генерации AI summaries
|
||
|
||
## Запуск
|
||
|
||
1. Убедитесь, что у вас установлен .NET 10 SDK
|
||
2. Получите API ключ от OpenAI (опционально, только для AI Summary функции)
|
||
3. Перейдите в директорию проекта:
|
||
```bash
|
||
cd PerfReviewSummarizer.Api
|
||
```
|
||
4. (Опционально) Добавьте OpenAI API ключ в `appsettings.json`:
|
||
```json
|
||
{
|
||
"OpenAI": {
|
||
"ApiKey": "your-openai-api-key-here"
|
||
}
|
||
}
|
||
```
|
||
Или установите переменную окружения: `OPENAI__APIKEY=your-api-key`
|
||
|
||
5. Запустите приложение:
|
||
```bash
|
||
dotnet run
|
||
```
|
||
|
||
Приложение будет доступно по адресу `http://localhost:5000` (или другому порту, указанному в launchSettings.json)
|
||
|
||
**Веб-интерфейс** будет доступен на главной странице (`http://localhost:5000/`)
|
||
**Swagger UI** будет доступен по адресу `http://localhost:5000/swagger`
|
||
|
||
## API Endpoints
|
||
|
||
### POST /api/summary
|
||
|
||
Получить summary за период.
|
||
|
||
**Тело запроса (JSON):**
|
||
```json
|
||
{
|
||
"repositoryPath": ".", // Путь к git репозиторию (опционально, по умолчанию текущая директория)
|
||
"startDate": "2024-01-01", // Начальная дата (опционально)
|
||
"endDate": "2024-06-30", // Конечная дата (опционально)
|
||
"period": "quarter" // Период: "quarter" или "halfyear" (опционально)
|
||
}
|
||
```
|
||
|
||
**Пример запроса для текущего квартала:**
|
||
```json
|
||
{
|
||
"period": "quarter"
|
||
}
|
||
```
|
||
|
||
**Пример запроса для текущего полугодия:**
|
||
```json
|
||
{
|
||
"period": "halfyear"
|
||
}
|
||
```
|
||
|
||
**Пример ответа:**
|
||
```json
|
||
{
|
||
"period": {
|
||
"startDate": "2024-01-01T00:00:00",
|
||
"endDate": "2024-03-31T00:00:00",
|
||
"description": "С 2024-01-01 по 2024-03-31"
|
||
},
|
||
"stats": {
|
||
"totalCommits": 150,
|
||
"totalFilesChanged": 450,
|
||
"totalAdditions": 5000,
|
||
"totalDeletions": 2000,
|
||
"uniqueContributors": 5
|
||
},
|
||
"categories": [
|
||
{
|
||
"category": "Новые функции",
|
||
"description": "Разработка и добавление новых возможностей",
|
||
"commitsCount": 45,
|
||
"keyChanges": ["Добавлена авторизация", "Реализован поиск"]
|
||
}
|
||
],
|
||
"topCommits": [...]
|
||
}
|
||
```
|
||
|
||
### POST /api/summary/ai
|
||
|
||
**⭐ Получить AI Summary через OpenAI GPT**
|
||
|
||
Генерирует интеллектуальное резюме на основе сообщений коммитов с использованием GPT.
|
||
|
||
**Требует:**
|
||
- OpenAI API ключ в конфигурации
|
||
|
||
**Тело запроса (JSON):**
|
||
```json
|
||
{
|
||
"repositoryPath": ".", // Путь к git репозиторию (опционально)
|
||
"startDate": "2024-01-01", // Начальная дата (опционально)
|
||
"endDate": "2024-06-30", // Конечная дата (опционально)
|
||
"period": "quarter" // Период: "quarter" или "halfyear" (опционально)
|
||
}
|
||
```
|
||
|
||
**Пример ответа:**
|
||
```json
|
||
{
|
||
"summary": "За текущий квартал была проведена значительная работа над новыми функциями...",
|
||
"periodInfo": {
|
||
"startDate": "2024-01-01T00:00:00",
|
||
"endDate": "2024-03-31T00:00:00",
|
||
"description": "С 2024-01-01 по 2024-03-31"
|
||
},
|
||
"commitsCount": 150,
|
||
"commitMessages": ["Fix: исправлена ошибка авторизации", "Feat: добавлена поддержка двухфакторной авторизации", ...]
|
||
}
|
||
```
|
||
|
||
### GET /api/commits
|
||
|
||
Получить список коммитов за период.
|
||
|
||
**Query параметры:**
|
||
- `repositoryPath` (опционально) - путь к git репозиторию
|
||
- `startDate` (опционально) - начальная дата
|
||
- `endDate` (опционально) - конечная дата
|
||
|
||
**Пример:**
|
||
```
|
||
GET /api/commits?startDate=2024-01-01&endDate=2024-06-30
|
||
```
|
||
|
||
### GET /health
|
||
|
||
Health check endpoint.
|
||
|
||
### GET /
|
||
|
||
Информация об API и доступных endpoints.
|
||
|
||
## Конфигурация
|
||
|
||
### appsettings.json
|
||
|
||
Пример конфигурации:
|
||
|
||
```json
|
||
{
|
||
"Logging": {
|
||
"LogLevel": {
|
||
"Default": "Information",
|
||
"Microsoft.AspNetCore": "Warning"
|
||
}
|
||
},
|
||
"AllowedHosts": "*",
|
||
"GitRepository": {
|
||
"DefaultPath": "."
|
||
},
|
||
"OpenAI": {
|
||
"ApiKey": "sk-... (ваш OpenAI API ключ)"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Переменные окружения
|
||
|
||
Альтернативно, можно установить переменные окружения:
|
||
- `OPENAI__APIKEY` - OpenAI API ключ
|
||
- `GITREPOSITORY__DEFAULTPATH` - путь к репозиторию по умолчанию
|
||
|
||
## Получение OpenAI API ключа
|
||
|
||
1. Перейдите на https://platform.openai.com
|
||
2. Создайте аккаунт или войдите в существующий
|
||
3. Перейдите в раздел API keys
|
||
4. Создайте новый ключ
|
||
5. Скопируйте ключ и добавьте в конфигурацию приложения
|
||
|
||
## Категории коммитов
|
||
|
||
Приложение автоматически категоризирует коммиты по следующим категориям:
|
||
|
||
- **Исправления ошибок** - коммиты с fix/bug
|
||
- **Новые функции** - коммиты с feat/add
|
||
- **Рефакторинг** - улучшение структуры кода
|
||
- **Тестирование** - добавление тестов
|
||
- **API изменения** - изменения в API
|
||
- **UI изменения** - изменения в интерфейсе
|
||
- **Конфигурация** - изменения настроек
|
||
- **Документация** - обновление документации
|
||
- **Оптимизация производительности** - улучшение производительности
|
||
- **Безопасность** - улучшения безопасности
|
||
- **Прочие изменения** - остальные коммиты
|
||
|
||
## Примеры использования
|
||
|
||
### Использование с curl
|
||
|
||
```bash
|
||
# Получить summary за текущий квартал
|
||
curl -X POST http://localhost:5000/api/summary \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"period": "quarter"}'
|
||
|
||
# Получить AI Summary за квартал
|
||
curl -X POST http://localhost:5000/api/summary/ai \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"period": "quarter"}'
|
||
|
||
# Получить summary за полугодие для конкретного репозитория
|
||
curl -X POST http://localhost:5000/api/summary \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"repositoryPath": "C:/Projects/MyProject", "period": "halfyear"}'
|
||
|
||
# Получить коммиты за период
|
||
curl "http://localhost:5000/api/commits?startDate=2024-01-01&endDate=2024-06-30"
|
||
```
|
||
|
||
### Использование с PowerShell
|
||
|
||
```powershell
|
||
# Получить summary за квартал
|
||
$body = @{
|
||
period = "quarter"
|
||
} | ConvertTo-Json
|
||
|
||
Invoke-RestMethod -Uri "http://localhost:5000/api/summary" -Method Post -Body $body -ContentType "application/json"
|
||
|
||
# Получить AI Summary за квартал
|
||
Invoke-RestMethod -Uri "http://localhost:5000/api/summary/ai" -Method Post -Body $body -ContentType "application/json"
|
||
```
|
||
|
||
## Веб-интерфейс
|
||
|
||
Приложение включает удобный веб-интерфейс с двумя вкладками:
|
||
|
||
### Traditional Summary
|
||
- **Форма для выбора параметров**: путь к репозиторию, период анализа
|
||
- **Визуализация статистики**: карточки с основными метриками (коммиты, файлы, строки)
|
||
- **Категории изменений**: группировка коммитов по типам с описаниями
|
||
- **Топ коммитов**: список самых значимых коммитов с детальной информацией
|
||
|
||
### AI Summary (OpenAI)
|
||
- **Интеллектуальное резюме**: анализ коммитов через GPT
|
||
- **Профессиональное описание**: автоматическое описание работы за период
|
||
- **Быстрая обработка**: получение summary в несколько секунд
|
||
|
||
**Адаптивный дизайн**: интерфейс работает на всех устройствах
|
||
|
||
Откройте `http://localhost:5000/` в браузере после запуска приложения.
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
PerfReviewSummarizer/
|
||
├── PerfReviewSummarizer.Api/
|
||
│ ├── Models/ # Модели данных
|
||
│ │ ├── CommitInfo.cs
|
||
│ │ ├── SummaryRequest.cs
|
||
│ │ ├── SummaryResponse.cs
|
||
│ │ └── OpenAiSummaryRequest.cs (новое)
|
||
│ ├── Services/ # Сервисы
|
||
│ │ ├── IGitService.cs
|
||
│ │ ├── GitService.cs
|
||
│ │ ├── IOpenAiService.cs (новое)
|
||
│ │ └── OpenAiService.cs (новое)
|
||
│ ├── wwwroot/ # Статические файлы
|
||
│ │ ├── index.html # Главная страница
|
||
│ │ ├── styles.css # Стили
|
||
│ │ └── app.js # JavaScript логика
|
||
│ ├── Program.cs # Точка входа и настройка API
|
||
│ └── appsettings.json # Конфигурация
|
||
└── README.md
|
||
```
|
||
|
||
## Что нового
|
||
|
||
### Версия с OpenAI интеграцией
|
||
|
||
- ✨ **OpenAI GPT интеграция** - использование GPT-4o-mini для генерации резюме
|
||
- 🎯 **AI Summary endpoint** - новый POST /api/summary/ai endpoint
|
||
- 📱 **Улучшенный веб-интерфейс** - вкладки для выбора типа анализа
|
||
- 🎨 **Стилизация AI результатов** - специальное оформление для AI саммари
|