Состав deliverables финального проекта — Стандарт качества

Введение

Этот документ — стандарт качества для всех артефактов финального проекта. Каждый артефакт проверяется на соответствие трём принципам:

1. Полнота — ничего не пропущено (все разделы заполнены, все сценарии описаны)
2. Связность (Traceability) — каждый элемент одного артефакта мапится на элемент другого
3. Проверяемость — по каждому требованию можно написать тест

Жёсткое правило: Если хотя бы один артефакт не соответствует стандарту, работа отправляется на доработку без оценки.

---

1. SRS-документ (Software Requirements Specification)

Спецификация требований по стандарту IEEE 830 (см. шаблон project-template/srs-template.md).

1.1. Обязательные разделы

Раздел	Что должно быть	Чего НЕ должно быть
1. Введение	Цель, область применения, глоссарий	«Воды», общих фраз
2. Общее описание	Контекст системы (As-Is / To-Be), пользователи, предположения, границы	Пустых таблиц
3. Функциональные требования	ID FR-001..FR-N, описание, приоритет (MoSCoW), Acceptance Criteria	«Система должна быть удобной»
4. Нефункциональные требования	ID NFR-001..NFR-N, категория, измеримая метрика	«Система должна быть быстрой»
5. Модель данных	ERD (изображение), Data Dictionary (таблица), описание связей	Таблицы без типов данных
6. API-контракты	OpenAPI-спецификация или таблица эндпоинтов с request/response	«REST API» без деталей
7. Диаграммы	Use Case, Activity/BPMN, Sequence, Class — PNG/PlantUML	Схемы от руки

1.2. Критические требования к SRS

Требование	Почему это важно
Каждое FR имеет Acceptance Criteria (минимум 3)	Иначе требование непроверяемо
Каждое NFR имеет измеримую метрику	«Быстрая система» = 0 баллов; «P95 < 2 сек» = балл
Глоссарий содержит минимум 10 терминов	Без глоссария термины трактуются по-разному
Data Dictionary описывает все сущности из ERD	Пропуск сущности = незавершённый артефакт
Все ID требований уникальны	FR-001, FR-002… без пропусков и дубликатов

---

2. UML-диаграммы (не менее 4 шт.)

2.1. Use Case Diagram

Что должно быть:

• Актёры (все роли из SRS: Администратор, Team Lead, Разработчик, HR)
• Use Cases (все ключевые функции: Создать задачу, Назначить исполнителя, Сменить статус, Посмотреть дашборд)
• Отношения (include / extend где необходимо)
• Границы системы

Чего НЕ должно быть:

• Актёров, не описанных в SRS (откуда они взялись?)
• Use Case без связи с FR (каждое US должно мапиться на минимум одно FR)
• Include ради include (без бизнес-смысла)

2.2. Activity Diagram (или BPMN)

Что должно быть:

• Основной процесс: «Создание и выполнение задачи»
• Роли (дорожки): Team Lead (ставит задачу), Разработчик (выполняет), Система (уведомляет)
• Все возможные ветвления: успех, ошибка, блокировка, возврат на доработку
• Начальное и конечное события

Чего НЕ должно быть:

• Линейной цепочки без ветвлений (это не процесс, а последовательность)
• Пропущенного Error Path (что если задача не прошла тестирование?)
• Ролей, не совпадающих с SRS

2.3. Sequence Diagram для ключевого сценария

Что должно быть:

• Сценарий: «Team Lead создаёт задачу → Система сохраняет → Уведомление разработчику»
• Участники: актёры + система + подсистемы (БД, брокер сообщений)
• Синхронные и асинхронные вызовы (REST стрелка сплошная, Kafka/RabbitMQ — пунктирная, ответная)
• Альтернативные фрагменты (alt) для ошибок: «если email не отправлен → логировать»

Чего НЕ должно быть:

• Только Happy Path (где Error Path?)
• Lifeline без сообщений (зачем объект на диаграмме, если он молчит?)
• Неправильных стрелок: асинхронные вызовы — открытая стрелка, синхронные — закрытая

2.4. Class Diagram

Что должно быть:

• Классы, соответствующие сущностям ERD (User, Task, Comment, Project, Notification)
• Атрибуты с типами (String, int, LocalDateTime, enum)
• Методы (хотя бы ключевые: createTask(), changeStatus(), assignUser())
• Связи: агрегация, композиция, наследование где необходимо
• Множественность (1.., 0.., 1)

Чего НЕ должно быть:

• Классов без атрибутов (пустая коробка не несёт информации)
• Несоответствия ERD (Class User — 5 полей, ERD User — 8 полей → ошибка)
• Всех возможных методов (достаточно ключевых, не надо 50 геттеров и сеттеров)

---

3. BPMN-диаграмма

Процесс: «Создание и выполнение задачи» (полный цикл).

Что должно быть:

• 2+ Pool (Team Lead, Разработчик, Система уведомлений)
• Start Event → User Task (создать задачу) → ... → End Event
• Gateway: исключающий (XOR) для ветвления по статусам
• Gateway: параллельный (AND) для одновременных уведомлений
• Message Flow между Pools (если разные участники)
• Error Boundary Event для обработки ошибок (email не отправился)
• Compensate для отката (если задача не прошла тестирование — вернуть в In Progress)

Чего НЕ должно быть:

• Pool без Lane (кто именно выполняет? непонятно)
• Task без назначения (не указано, чья это задача)
• Missing default flow (у gateway должен быть default, если ни одно условие не подошло)
• Пропущенных статусов (статус Blocked есть в SRS, но нет на BPMN)

---

4. ER-диаграмма и SQL-скрипты

4.1. ERD

Что должно быть:

• Все сущности: User, Task, Comment, Project, Notification, TaskStatus (enum)
• Атрибуты с типами (PK, FK, NOT NULL, DEFAULT)
• Связи с мощностью (1:1, 1:N, N:M с junction table где нужно)
• Crow's Foot нотация (или UML, но единообразно)

4.2. Data Dictionary

Сущность	Атрибут	Тип данных	PK/FK	NOT NULL	DEFAULT	Описание
User	id	UUID	PK	YES	gen_random_uuid()	Уникальный идентификатор пользователя
User	email	VARCHAR(255)	—	YES	—	Email для логина и уведомлений
Task	id	UUID	PK	YES	gen_random_uuid()	Идентификатор задачи
Task	assignee_id	UUID	FK(User)	NO	NULL	Исполнитель задачи
Task	status	VARCHAR(20)	—	YES	'To Do'	Текущий статус

Критические требования:

• Каждая сущность из ERD присутствует в Data Dictionary и наоборот
• Типы данных: UUID для PK, VARCHAR(N) для строк, TIMESTAMP для дат
• FK с указанием родительской таблицы
• NOT NULL для обязательных полей, DEFAULT где уместно
• enum-статусы вынесены в CHECK-constraint или отдельную таблицу

4.3. DDL-скрипты

Требования:

• CREATE TABLE для всех сущностей
• CREATE INDEX для FK и часто запрашиваемых полей (status, assignee_id, deadline)
• ALTER TABLE ADD CONSTRAINT для FK, CHECK (status), UNIQUE (email)
• Комментарии к таблицам и полям

Обязательные SQL-запросы (минимум 3, все с JOIN):

-- 1. Список задач с именем исполнителя и названием проекта
SELECT t.id, t.title, u.name AS assignee_name, p.name AS project_name
FROM Task t
JOIN "User" u ON t.assignee_id = u.id
JOIN Project p ON t.project_id = p.id
WHERE t.status = 'In Progress';

-- 2. Загрузка сотрудников: количество активных задач по каждому
SELECT u.id, u.name, COUNT(t.id) AS active_tasks
FROM "User" u
LEFT JOIN Task t ON u.id = t.assignee_id AND t.status NOT IN ('Done', 'Cancelled')
GROUP BY u.id, u.name
ORDER BY active_tasks DESC;

-- 3. Поиск просроченных задач с комментариями
SELECT t.id, t.title, t.deadline, COUNT(c.id) AS comments_count
FROM Task t
LEFT JOIN Comment c ON t.id = c.task_id
WHERE t.deadline < NOW() AND t.status NOT IN ('Done', 'Cancelled')
GROUP BY t.id, t.title, t.deadline
ORDER BY t.deadline;

---

5. API-контракт (OpenAPI 3.0)

5.1. Что должно быть

• Минимум: CRUD для Task, смена статуса, назначение исполнителя, список с фильтрацией
• OpenAPI в YAML (компилируемый — проверьте через Swagger Editor)
• Модели: Task, UserBrief, CreateTaskRequest, Pagination в components/schemas
• Аутентификация: Bearer JWT в components/securitySchemes
• Response codes: 200, 201, 204, 400, 401, 403, 404, 409, 422, 500
• operationId для каждого эндпоинта
• tags для группировки

5.2. Критические требования

• Язык спецификации — русский (поле description)
• Все типы данных размечены: format: date, format: date-time, format: email
• Для enum полей (status, priority) — type: string + enum: [...]
• Для nullable полей — nullable: true
• Ответ с пагинацией: { data: Task[], pagination: { page, limit, total } }

---

6. Тест-кейсы (минимум 5 шт.)

6.1. Структура каждого тест-кейса

Поле	Обязательно?	Пример
ID	✅	TC-001
Title	✅	Успешное создание задачи с назначением исполнителя
Preconditions	✅	Пользователь авторизован, исполнитель с id=5 существует
Test Data	✅	title: «Настроить CI/CD», assignee_id: 5
Steps	✅	1. POST /api/v1/tasks с телом {...} 2. Проверить статус 201
Expected Result	✅	Статус 201, в ответе id задачи, assignee.name = «Мария»
Actual Result	❌ (заполняется при прогоне)
Status	❌ (заполняется при прогоне)

6.2. Покрытие

№	Техника	Сценарий
1	Happy Path	Создание задачи (все поля валидны) → 201
2	Error Path	Создание задачи без title → 422
3	Boundary Value	Смена статуса с In Progress на Done → 200
4	Edge Case	Смена статуса с To Do на Done (неразрешённый переход) → 422
5	Security	GET /api/tasks без токена → 401
6	State-Transition	Блокировка → разблокировка → выполнение → тестирование → готово

---

7. Презентация (10 слайдов)

См. шаблон project-template/presentation-template.md.

Структура:

1. Титульный слайд
2. Цель и контекст (проблема → цель → ожидаемый эффект)
3. Стейкхолдеры и их боли (таблица)
4. Границы системы (In Scope / Out of Scope)
5. Ключевые функциональные требования (5–7 FR с приоритетами)
6. Use Case Diagram
7. BPMN / Activity Diagram ключевого процесса
8. ER-диаграмма и Data Dictionary (фрагмент)
9. API (основные эндпоинты в таблице)
10. Заключение (что сделано, какие техники применены, вывод)

---

8. Сквозная трассируемость (Traceability Matrix)

8.1. Золотое правило трассируемости

Каждый элемент одного артефакта должен мапиться на элемент другого артефакта. Ни один элемент не существует в вакууме.

8.2. Цепочка трассируемости

FR-001 (Создание задачи)
    │
    ├──→ Use Case: «Создать задачу» (Use Case Diagram)
    ├──→ Activity: шаг «Создать задачу» (Activity Diagram)
    ├──→ Entity: Task (ERD + Data Dictionary)
    ├──→ Endpoint: POST /api/v1/tasks (OpenAPI)
    ├──→ Тест-кейс: TC-001 (Happy Path создания)
    └──→ BPMN: Task «Создать задачу» (Pool: Team Lead)

NFR-001 (Время отклика < 2 сек)
    │
    ├──→ Sequence: стрелка «запрос к БД» (Sequence Diagram)
    └──→ Тест-кейс: TC-007 (Проверка производительности)

8.3. Таблица трассируемости (должна быть в SRS)

FR ID	Use Case	ERD Entity	API Endpoint	Тест-кейсы
FR-001	Создать задачу	Task	POST /api/v1/tasks	TC-001, TC-002
FR-002	Назначить исполнителя	Task → User	PATCH /tasks/{id}/assign	TC-003
FR-003	Фильтрация списка	—	GET /api/v1/tasks?status=...	TC-004
FR-004	Комментарии	Comment	GET/POST /tasks/{id}/comments	TC-005
FR-005	Смена статуса	Task.status	PATCH /tasks/{id}/status	TC-006
FR-006	Уведомления	Notification	— (асинхронно, Kafka)	TC-007
FR-007	Дашборд загрузки	—	GET /api/v1/dashboard	TC-008

8.4. Маппинг: ERD → OpenAPI → SRS

Принцип: Сущность из ERD должна мапироваться на схему в OpenAPI и на функциональное требование в SRS.

ERD: сущность User (id, name, email, role, created_at)
    │
    ├──→ OpenAPI: schema UserBrief (id, name, email) — для списков
    ├──→ OpenAPI: schema UserFull (id, name, email, role, created_at) — для деталей
    │
    ├──→ SRS: FR-008 (Регистрация пользователя)
    ├──→ SRS: FR-009 (Авторизация)
    └──→ SRS: FR-010 (Ролевая модель)

Проверка:

• Каждый атрибут в ERD имеет назначение (для чего нужен бизнесу?)
• Каждое поле в OpenAPI schema можно найти в ERD (откуда оно берётся?)
• Каждый эндпоинт в OpenAPI соответствует FR (зачем он нужен?)

8.5. Антипаттерны трассируемости

Антипаттерн	Пример	Почему плохо
Phantom Entity	Сущность в ERD, которой нет в SRS	Непонятно, зачем она нужна бизнесу
Orphan Endpoint	Эндпоинт в OpenAPI, который не нужен ни для одного FR	Лишняя работа, раздувание API
Untestable FR	FR в SRS, на который нет тест-кейсов	Требование не проверено
Dead Use Case	Use Case на диаграмме, которого нет в SRS	Откуда он взялся?
Mismatched Type	VARCHAR(50) в ERD, maxLength: 100 в OpenAPI	Расхождение валидации

---

9. Чек-лист самопроверки студента перед отправкой

Перед отправкой работы на ревью пройдите по каждому пункту. Если хотя бы один пункт — ❌, работа НЕ ПРИНИМАЕТСЯ.

SRS

№	Проверка	Статус
1	Все разделы SRS заполнены (не пустые)	❓
2	Каждое FR имеет уникальный ID и Acceptance Criteria (минимум 3)	❓
3	Каждое NFR имеет измеримую метрику (не «быстрая», а «< 2 сек»)	❓
4	Глоссарий содержит минимум 10 определений	❓
5	Data Dictionary содержит все сущности из ERD с типами данных	❓
6	Нет слов-паразитов («быстро», «удобно», «надёжно» без метрик)	❓
7	Описаны границы системы (In Scope / Out of Scope)	❓
8	FR и NFR разделены (функциональные ≠ нефункциональные)	❓

UML и BPMN

№	Проверка	Статус
9	Use Case Diagram: все актёры из SRS присутствуют	❓
10	Activity/BPMN: есть хотя бы один Gateway (ветвление)	❓
11	Activity/BPMN: есть Error Path (альтернативный поток)	❓
12	Sequence Diagram: есть синхронные и асинхронные вызовы	❓
13	Sequence Diagram: есть alt/opt фрагмент (обработка ошибки)	❓
14	Class Diagram: классы соответствуют сущностям ERD	❓
15	BPMN: есть Pool для каждого участника процесса	❓
16	BPMN: у каждого Gateway есть default flow	❓

ERD и SQL

№	Проверка	Статус
17	ERD содержит все сущности, упомянутые в SRS	❓
18	Все PK и FK явно указаны на ERD	❓
19	Мощность связей указана (1:N, M:N с junction table)	❓
20	DDL-скрипты синтаксически валидны (можно запустить в psql)	❓
21	Есть CREATE INDEX для FK и часто запрашиваемых полей	❓
22	Минимум 3 SELECT-запроса с JOIN корректны и имеют пояснения	❓
23	Data Dictionary: для каждого FK указана родительская таблица	❓

OpenAPI

№	Проверка	Статус
24	OpenAPI-спецификация компилируется (проверено через Swagger Editor)	❓
25	Все модели вынесены в components/schemas с $ref	❓
26	Добавлена security схема (Bearer JWT)	❓
27	Для каждого эндпоинта указан operationId	❓
28	Описаны ответы: 200, 201, 400, 401, 404, 422, 500	❓
29	Для enum полей (status, priority) — type: string + enum	❓
30	Формат дат: format: date-time, format: email	❓

Тест-кейсы

№	Проверка	Статус
31	Минимум 5 тест-кейсов	❓
32	Каждый тест-кейс имеет Preconditions, Steps, Expected Result	❓
33	Покрыты: Happy Path, Error Path, Edge Case, Security	❓
34	Тест-кейсы мапятся на FR (можно определить, что тестируется)	❓

Трассируемость

№	Проверка	Статус
35	Каждое FR мапится на Use Case + API + Тест-кейс	❓
36	Каждая сущность ERD мапится на Data Dictionary + OpenAPI schema	❓
37	Все ID требований уникальны (FR-001, FR-002… без дублей)	❓
38	Нет «orphan» артефактов (сущности без FR, эндпоинты без Use Case)	❓

Презентация

№	Проверка	Статус
39	10 слайдов по структуре из шаблона	❓
40	На слайдах есть ключевые диаграммы (UML, BPMN, ERD)	❓
41	Слайды не перегружены текстом (максимум 30 слов на слайд)	❓
42	Указаны ФИО студента на титульном слайде	❓

Общие требования

№	Проверка	Статус
43	Все файлы в формате Markdown или PDF (не .docx, не .pages)	❓
44	Диаграммы — в виде изображений (PNG) или PlantUML-кода	❓
45	OpenAPI — в виде YAML-блока, а не ссылки на внешний редактор	❓
46	Работа сдана одним архивом с правильным именованием	❓
47	Нет плагиата (текст написан самостоятельно, а не скопирован из курса)	❓

---

10. Процесс приёмки

Студент завершил работу
        │
        ▼
Самопроверка по чек-листу (47 пунктов)
   ┌────┴────┐
   │ Все ✅  │  Есть ❌
   │         │
   ▼         ▼
Сдать     Доработать → исправить ❌ → снова пройти чек-лист
   │
   ▼
Ревью экзаменатором (по критериям из 09-03-evaluation-criteria.md)
   ┌────┴────┐
   │ Pass   │  Fail
   │         │
   ▼         ▼
Защита   Доработка + повторное ревью