# Лабораторная 02: ПРОЕКТИРОВАНИЕ СИСТЕМЫ

> Спринт 2 · Недели 3–4 · 14 дней · 10 баллов

**Вопрос спринта:** Как будем решать?

Превратить понимание проблемы в чертежи: проживаемые use cases, C4-архитектура, прошедшая aact, контракты API и evals, написанные до кода.

## Формат сдачи

- Pull Request от каждой роли
- Ветка: `lab2-[role]-design`
- Заголовок PR: `Lab2: [Role] — Design Deliverables`

## Роли и шаги

### PRODUCT / VO — Use cases по правилам, роадмап и живой словарь

Отвечает за то, что проектируем то, что нужно сегменту, — и что это записано так, что понимают люди и агенты.

#### Шаг 1. Use cases по правилам (5–7 часов)

_UC — единственный артефакт, из которого выводится всё остальное: код, тесты, evals._

- UC по шаблону: актёр, цель, контекст, шаги, результат
- Use-case UML-диаграмма в PlantUML
- Тест «проживаемости»: человек не из команды разыгрывает UC без вопросов

**Сдаёшь:** Use cases as-code [документ] → `docs/use-cases/`

#### Шаг 2. Роадмап и скоуп MVP (3–4 часа)

_Роадмап отделяет «сейчас» от «потом» — иначе скоуп ползёт весь семестр._

- MVP-скоуп из use cases
- Не-скоуп — явно, списком
- Вехи до Demo Day

**Сдаёшь:** Роадмап с не-скоупом [документ] → `docs/roadmap.md`

#### Шаг 3. Глоссарий v2 (1–2 часа)

_Проектирование рождает новые термины — словарь должен успевать за ними._

- Термины из архитектуры и AI-пайплайна
- Синхронизация вслух с командой

**Сдаёшь:** Обновлённый глоссарий [документ] → `docs/glossary.md`

#### Шаг 4. Приёмка ADR (2–3 часа)

_Каждое решение спринта — с понятной ценой; без цены ADR не принимается._

- Ревью всех ADR команды
- Поле «Цена решения» заполнено везде
- Реестр решений актуален

**Сдаёшь:** Реестр ADR [документ] → `docs/adr/`

**Советы:** UC, который нельзя прожить, — не UC · Не-скоуп важнее скоупа · Новый термин без словаря — будущий баг согласования · Принимай по DoD, а не по красоте

### AI ENGINEER — Дизайн AI-пайплайна и спайки рисков

Отвечает за архитектуру AI-части: как данные и запросы проходят через модель — и что это реально сработает.

#### Шаг 1. Дизайн AI-пайплайна (4–6 часов)

_Архитектура AI-части определяет стоимость и качество всего продукта._

- Схема пайплайна (промпты / RAG / агент) в PlantUML
- Точки контроля качества и логирования
- Границы контекста: что модель видит и чего не видит

**Сдаёшь:** Схема AI-пайплайна [документ] → `docs/ai-pipeline.md`

#### Шаг 2. ADR: выбор моделей (2–3 часа)

_Модель — самое дорогое решение проекта; выбирается один раз и с ценой._

- Финальный выбор из кандидатов лабы 1
- План деградации на дешёвую модель
- Поле «Цена решения» заполнено

**Сдаёшь:** ADR-002 «Модели» [документ] → `docs/adr/002-models.md`

#### Шаг 3. Спайки рисков (4–6 часов)

_Самое страшное место пайплайна проверяется до строительства, а не после._

- 1–2 спайка самых рискованных допущений
- Результат честно: сработало / не сработало / сработало иначе

**Сдаёшь:** Ноутбук спайков [ноутбук] → `notebooks/spikes.ipynb`

#### Шаг 4. Контракт AI-эндпоинтов (2–3 часа)

_Команда строит вокруг контракта, а не вокруг надежд._

- Эндпоинты модели в OpenAPI (вместе с Delivery)
- Форматы структурированных выходов

**Сдаёшь:** Контракт AI-API [конфиг] → `api/openapi.yaml`

**Советы:** Спайк отвечает на один вопрос, не на все · Деградация проектируется заранее · Структурированный выход дешевле парсинга · Пайплайн без точек контроля — чёрный ящик

### DELIVERY — C4 as-code, прототип агентом и скелет системы

Отвечает за чертежи системы и их проверку машиной: C4 в PlantUML, aact без нарушений, скелет готов к лабе 3.

#### Шаг 1. C4 as-code + aact (5–6 часов)

_Право «вертеть проект на изях» зарабатывается пониманием архитектуры._

- Context- и container-диаграммы в PlantUML (вместе с Product)
- aact-конфиг с правилами в репозитории
- aact check — 0 violations

**Сдаёшь:** C4-диаграммы + aact-конфиг [документ] → `docs/architecture/`

#### Шаг 2. Прототип UI агентом (3–4 часа)

_Прототип за вечер агентом вместо недели в фигме — и сразу as-code._

- Генерация прототипа ключевых экранов (Vibe / v0)
- Скриншоты закоммичены рядом с кодом
- Фигма и миро не используются — только as-code

**Сдаёшь:** Прототип UI: код + скрины [код] → `frontend/prototype/`

#### Шаг 3. Схема данных (3–4 часа)

_Схема данных — контракт хранения; меняется дороже всего._

- ERD в PlantUML
- Заготовка схемы и миграций

**Сдаёшь:** Схема БД + ERD [конфиг] → `database/schema.sql`

#### Шаг 4. Compose-скелет v2 (2–3 часа)

_Скелет compose в лабе 2 — спокойная лаба 3._

- Сервисы будущей системы как заглушки
- Сети, volumes, health checks

**Сдаёшь:** Compose-скелет [конфиг] → `compose.dev.yml`

**Советы:** aact ругается — значит архитектура врёт · Диаграмма без исходника в репо не существует · Прототип — для проверки UC, не для красоты · ERD рисуется до первой миграции

### QUALITY & SAFETY — DoD, тест-план, evals до кода и threat model

Отвечает за то, что «готово» определено до того, как начали строить: DoD, eval-набор и модель угроз.

#### Шаг 1. DoD всех артефактов (3–4 часа)

_DoD — спека для автопроверки: что проверит judge, решаете вы._

- DoD каждого артефакта команды: есть/нет, число, ссылка
- Согласовано с Product и командой

**Сдаёшь:** DoD артефактов [документ] → `docs/quality/dod.md`

#### Шаг 2. Eval-набор из use cases (4–6 часов)

_Evals пишутся до кода — прямо из use cases._

- 30–50 пар вход → эталон из UC
- Формат, читаемый DeepEval
- Владелец и процесс пополнения

**Сдаёшь:** Golden dataset v1 [документ] → `docs/quality/golden-dataset/`

#### Шаг 3. Тест-план (2–3 часа)

_План тестирования проектируется вместе с системой, а не после неё._

- Что тестируем на каждом уровне: unit, интеграция, evals
- Что гоняем в CI с лабы 3

**Сдаёшь:** Тест-план [документ] → `docs/quality/test-plan.md`

#### Шаг 4. Threat model (3–4 часа)

_Prompt injection проектируется против — а не чинится после._

- OWASP LLM Top-10 применительно к проекту
- Точки входа недоверенного текста
- Что проверим LLAMATOR в лабе 4

**Сдаёшь:** Модель угроз [документ] → `docs/quality/threat-model.md`

**Советы:** Критерий DoD либо проверяем машиной, либо переписывается · Плохой эталон хуже отсутствия эталона · Тест-план на страницу лучше тома на полке · Каждое поле ввода — точка входа атаки

## Definition of Done

Те же критерии видит автопроверка. Лаба сдана, когда выполнены все группы.

### Продукт

- [ ] Каждый UC прожит человеком не из команды — без вопросов
- [ ] Use-case диаграмма в PlantUML лежит в репозитории
- [ ] Роадмап содержит скоуп MVP и явный не-скоуп
- [ ] Все ADR имеют заполненное поле «Цена решения»

### Архитектура

- [ ] C4 (context + container) в PlantUML в репозитории
- [ ] aact check проходит с 0 violations
- [ ] ERD и контракт AI-API в репозитории
- [ ] compose.dev.yml поднимает заглушки сервисов

### Качество

- [ ] DoD написан для каждого артефакта команды
- [ ] Golden dataset: ≥30 пар вход → эталон в формате DeepEval
- [ ] Тест-план: уровни тестирования и что идёт в CI
- [ ] Threat model перечисляет точки входа недоверенного текста

## Чек-лист перед PR

### Продукт и архитектура

- [ ] UC прожиты человеком не из команды
- [ ] Не-скоуп записан явно
- [ ] C4 в PlantUML, aact — 0 violations
- [ ] ERD и контракт API в репо
- [ ] ADR — все с ценой решения
- [ ] Глоссарий пополнен терминами спринта

### Качество и готовность

- [ ] DoD каждого артефакта написан
- [ ] ≥30 eval-пар в формате DeepEval
- [ ] Тест-план согласован
- [ ] Threat model покрывает все входы
- [ ] Спайки рисков прогнаны честно
- [ ] Compose-скелет поднимается

## Материалы к лабе

- [UC-ДИАГРАММА](/materials/use-cases/uml) — Правила UML и ошибки
- [C4 И ADR](/materials/architecture/c4-levels) — Уровни, as-code, цена решения
- [AACT](/materials/architecture/aact) — Проверка архитектуры машиной
- [ОЦЕНИВАНИЕ](/materials/labs/grading-system) — Как считаются баллы
- [ВСЕ МАТЕРИАЛЫ](/materials) — База материалов курса

---

_К концу спринта у команды чертежи, которым можно верить: use cases проживаются, C4 проходит aact, evals написаны до кода. Строить — по чертежам._

Человеческая версия: /labs/lab2