laravel-12-tech-specs/task01-task-manager.md

# Техническое задание: Система управления задачами (Task Manager)

## 1. Описание проекта

Веб-приложение для управления личными и командными задачами с возможностью назначения исполнителей, отслеживания статусаов и приоритетов. Проект закрепляет навыки CRUD, разграничения прав через Roles/Gates/Policies, совместной работы через Git.

**Команда:** 2–3 человека

---

## 2. Функциональные требования

### 2.1. Аутентификация и регистрация
- Регистрация, вход, выход (Laravel Breeze)
- Восстановление пароля (опционально)

### 2.2. Управление задачами
- Создание, просмотр, редактирование, удаление задач
- Поля задачи: название, описание, статус (новая, в работе, завершена), приоритет (низкий, средний, высокий, критический), дедлайн, исполнитель, автор
- Назначение исполнителя из списка пользователей
- Добавление комментариев к задаче
- Фильтрация по статусу, приоритету, исполнителю
- Сортировка по дате создания, приоритету, дедлайну
- Пагинация списка задач

### 2.3. Управление проектами
- Создание проектов (группировка задач)
- Привязка задач к проекту
- CRUD проектов

### 2.4. Панель администратора
- Управление пользователями (просмотр, блокировка, назначение ролей)
- Просмотр статистики (количество задач, проектов, пользователей)

### 2.5. Дашборд пользователя
- Мои задачи (назначенные мне)
- Созданные мной задачи
- Просроченные задачи
- Быстрая смена статуса

---

## 3. Структура базы данных

### Таблица `users`
| Поле | Тип | Описание |
|---|---|---|
| id | BIGINT UNSIGNED | Первичный ключ |
| name | VARCHAR(255) | Имя |
| email | VARCHAR(255) | Email (unique) |
| password | VARCHAR(255) | Хеш пароля |
| role | ENUM('admin', 'manager', 'executor') | Роль |
| is_blocked | BOOLEAN | Заблокирован ли |
| created_at | TIMESTAMP | Дата создания |
| updated_at | TIMESTAMP | Дата обновления |

### Таблица `projects`
| Поле | Тип | Описание |
|---|---|---|
| id | BIGINT UNSIGNED | Первичный ключ |
| name | VARCHAR(255) | Название проекта |
| description | TEXT | Описание |
| user_id | BIGINT UNSIGNED | Автор проекта (FK → users) |
| created_at | TIMESTAMP | |
| updated_at | TIMESTAMP | |

### Таблица `tasks`
| Поле | Тип | Описание |
|---|---|---|
| id | BIGINT UNSIGNED | Первичный ключ |
| title | VARCHAR(255) | Название задачи |
| description | TEXT | Описание |
| status | ENUM('new', 'in_progress', 'completed', 'cancelled') | Статус |
| priority | ENUM('low', 'medium', 'high', 'critical') | Приоритет |
| due_date | DATE | Дедлайн |
| author_id | BIGINT UNSIGNED | Автор (FK → users) |
| assignee_id | BIGINT UNSIGNED \| NULL | Исполнитель (FK → users) |
| project_id | BIGINT UNSIGNED \| NULL | Проект (FK → projects) |
| created_at | TIMESTAMP | |
| updated_at | TIMESTAMP | |

### Таблица `comments`
| Поле | Тип | Описание |
|---|---|---|
| id | BIGINT UNSIGNED | Первичный ключ |
| body | TEXT | Текст комментария |
| user_id | BIGINT UNSIGNED | Автор комментария (FK → users) |
| task_id | BIGINT UNSIGNED | Задача (FK → tasks) |
| created_at | TIMESTAMP | |
| updated_at | TIMESTAMP | |

---

## 4. Маршруты и контроллеры

### Route группы

```php
// Публичные маршруты
Route::get('/', [DashboardController::class, 'index'])->name('dashboard');

// Аутентифицированные маршруты
Route::middleware('auth')->group(function () {
    // Задачи
    Route::resource('tasks', TaskController::class);
    Route::patch('tasks/{task}/status', [TaskController::class, 'updateStatus'])->name('tasks.status');

    // Комментарии
    Route::resource('tasks.comments', CommentController::class)->scoped(['tasks' => 'task']);

    // Проекты
    Route::resource('projects', ProjectController::class);

    // Админка
    Route::prefix('admin')->name('admin.')->group(function () {
        Route::resource('users', AdminUserController::class);
        Route::patch('users/{user}/block', [AdminUserController::class, 'toggleBlock'])->name('users.block');
        Route::patch('users/{user}/role', [AdminUserController::class, 'changeRole'])->name('users.role');
    });
});
```

### Контроллеры
- `TaskController` — CRUD задач + обновление статуса
- `CommentController` — CRUD комментариев (только создание и удаление)
- `ProjectController` — CRUD проектов
- `AdminUserController` — управление пользователями (только admin)
- `DashboardController` — дашборд с фильтрами

---

## 5. Роли, Gates и Policies

### Роли
| Роль | Описание |
|---|---|
| `admin` | Полный доступ ко всему |
| `manager` | Создание/редактирование проектов и задач, назначение исполнителей |
| `executor` | Просмотр назначенных задач, изменение статуса, комментарии |

### Gates (в `AuthServiceProvider`)

```php
Gate::define('access-admin-panel', function (User $user) {
    return $user->role === 'admin';
});

Gate::define('assign-tasks', function (User $user) {
    return in_array($user->role, ['admin', 'manager']);
});

Gate::define('manage-projects', function (User $user) {
    return in_array($user->role, ['admin', 'manager']);
});
```

### Policies

**TaskPolicy:**
- `view` — может видеть задачу, если автор или исполнитель, или имеет роль admin/manager
- `update` — автор, назначенный исполнитель (только статус), admin, manager
- `delete` — только автор задачи или admin
- `assign` — только admin или manager

**ProjectPolicy:**
- `view` — все аутентифицированные
- `update`, `delete` — автор проекта или admin

**CommentPolicy:**
- `create` — все аутентифицированные
- `delete` — автор комментария или admin

---

## 6. Требования к интерфейсу (Bootstrap 5)

### Компоненты
- **Навбар** — логотип, навигация, профиль пользователя
- **Карточки задач** — заголовок, бейджи статуса/приоритета, дедлайн, исполнитель
- **Таблица списка задач** — с сортировкой, фильтрами, пагинацией
- **Модальное окно** — быстрое создание/редактирование задачи
- **Формы** — валидация на клиенте и сервере, Bootstrap-классы `is-invalid`
- **Алерты** — flash-сообщения об успехе/ошибке (`alert-success`, `alert-danger`)
- **Дашборд** — сетка Bootstrap (`row`, `col-md-*`) с карточками статистики
- **Бейджи** — цветные индикаторы статуса и приоритета

### Цветовая схема статусов
- Новая — `bg-info`
- В работе — `bg-warning`
- Завершена — `bg-success`
- Отменена — `bg-secondary`

### Цветовая схема приоритетов
- Низкий — `bg-light text-dark`
- Средний — `bg-primary`
- Высокий — `bg-warning`
- Критический — `bg-danger`

---

## 7. Git-workflow для команды

### Распределение модулей (для 2 человек)

| Участник | Модуль | Ветки |
|---|---|---|
| **Участник A** | Аутентификация, пользователи, админка, задачи | `feature/auth-users`, `feature/tasks-crud` |
| **Участник B** | Проекты, комментарии, дашборд, UI | `feature/projects-crud`, `feature-task-comments` |

### Распределение модулей (для 3 человек)

| Участник | Модуль | Ветки |
|---|---|---|
| **Участник A** | Аутентификация, пользователи, админка | `feature/auth-users`, `feature/admin-panel` |
| **Участник B** | Задачи, комментарии, фильтры | `feature/tasks-crud`, `feature/task-comments` |
| **Участник C** | Проекты, дашборд, UI | `feature/projects-crud`, `feature/dashboard-ui` |

### Правила
1. Каждый участник работает в своей фич-ветке от `develop`
2. Перед мёржем в `develop` — Pull Request с код-ревью от другого участника
3. Минимум 3 PR на каждого участника за проект
4. Коммиты по Conventional Commits: `feat:`, `fix:`, `refactor:`, `docs:`
5. `main` — защищённая ветка, мёрж только из `develop`

### Визуализация workflow (2 участника)

```mermaid
gitGraph
   commit id: "init" tag: "v1.0"
   branch develop
   checkout develop
   branch feature/auth-users
   checkout develop
   branch feature/projects-crud
   checkout feature/auth-users
   commit id: "feat: add registration and login"
   commit id: "feat: add admin panel"
   checkout feature/projects-crud
   commit id: "feat: add projects CRUD"
   commit id: "feat: add comments to tasks"
   checkout develop
   merge feature/auth-users tag: "PR + review"
   merge feature/projects-crud tag: "PR + review"
   checkout main
   merge develop tag: "release v1.1"
```

### Визуализация workflow (3 участника)

```mermaid
gitGraph
   commit id: "init" tag: "v1.0"
   branch develop
   checkout develop
   branch feature/auth-users
   checkout develop
   branch feature/tasks-crud
   checkout develop
   branch feature/projects-crud
   checkout feature/auth-users
   commit id: "feat: add auth + admin panel"
   commit id: "feat: add user management"
   checkout feature/tasks-crud
   commit id: "feat: add task CRUD"
   commit id: "feat: add task filters"
   checkout feature/projects-crud
   commit id: "feat: add projects CRUD"
   commit id: "feat: add dashboard UI"
   checkout develop
   merge feature/auth-users tag: "PR + review"
   merge feature/tasks-crud tag: "PR + review"
   merge feature/projects-crud tag: "PR + review"
   checkout main
   merge develop tag: "release v1.1"
```

### Пример командной работы
```bash
# Создание фич-ветки
git checkout develop
git checkout -b feature/tasks-crud

# После разработки
git add .
git commit -m "feat: add task CRUD with validation"
git push origin feature/tasks-crud

# Создание Pull Request через GitHub/GitLab
# Код-ревью от другого участника → Approve → Merge
```

---

## 8. Критерии приёмки

### Обязательно
- [ ] Регистрация и вход работают
- [ ] CRUD задач с валидацией (название обязательно, дедлайн — дата)
- [ ] CRUD проектов
- [ ] Комментарии к задачам (создание + удаление)
- [ ] Фильтрация задач по статусу и приоритету
- [ ] Роли работают: executor не может удалять чужие задачи
- [ ] Policies корректно ограничивают доступ
- [ ] Admin-панель доступна только admin
- [ ] Bootstrap-вёрстка адаптивная (проверка на мобильном)
- [ ] Flash-сообщения при создании/редактировании/удалении
- [ ] Пагинация списка задач
- [ ] Git-история: минимум 3 ветки от каждого участника, слитые через PR

### Дополнительно (бонусные баллы)
- [ ] Drag-and-drop для смены статуса задач (kanban-доска)
- [ ] Уведомления (email при назначении задачи)
- [ ] Экспорт задач в CSV
- [ ] Поиск задач по названию/описанию
- [ ] Прикрепление файлов к задачам

---

## 9. Дополнительные задания (для продвинутых)

1. **Kanban-доска:** визуальное отображение задач по колонкам (новая, в работе, завершена) с drag-and-drop
2. **Уведомления:** отправка email при назначении задачи или изменении статуса
3. **API:** RESTful API для задач (resource-маршруты с JSON-ответами)
4. **Тесты:** PHPUnit Feature-тесты для TaskController (минимум 5 тестов)
5. **Queues:** асинхронная отправка уведомлений через очереди Laravel
6. **Soft Deletes:** мягкое удаление задач и проектов

---

## 10. Рекомендуемые материалы

- Laravel Docs: https://laravel.com/docs/12.x
- Laravel Authorization (Gates & Policies): https://laravel.com/docs/12.x/authorization
- Bootstrap 5 Documentation: https://getbootstrap.com/docs/5.3
- Git Flow: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
- Conventional Commits: https://www.conventionalcommits.org/