# Process Studio — справочное руководство

Версия документации соответствует текущему веб-приложению Process Studio.

---

## 1. Запуск

```bash
cd process-studio
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,web]"
cp .env.example .env   # опционально OPENROUTER_API_KEY
python -m process_studio serve
```

Откройте: **http://127.0.0.1:8765/**

| URL | Назначение |
|-----|------------|
| `/` | Studio — каталог и работа с процессом |
| `/help` | Справка и FAQ |
| `/admin` | Администратор: участники, этапы, заявки |
| `/change/{source}/{file}` | Инициатор изменения |
| `/floor/{source}/{file}` | Формы хронометража на месте |
| `/floor/{source}/{file}/{step_id}` | Форма одного шага |
| `/docs/PRODUCT.md` | Описание продукта (файл) |
| `/docs/USER_GUIDE.md` | Это руководство (файл) |
| `/docs/PRICING.md` | Ценовой анализ (файл) |
| `/docs/ProcessStudio-customers.pptx` | PowerPoint для заказчиков |
| `/docs/ProcessStudio-director.pptx` | PowerPoint для директора |

`source`: `sample` (демо) или `workspace` (сохранённые модели).

---

## 2. Вход и роли

### 2.1. Вход (MVP-заглушка)

Кнопка **Войти** → форма входа / регистрации. Пароль и почта **не проверяются**.  
«Войти в MVP (полные права)» или любой логин → роль `admin`, cookie `ps_person_id`.  
Без входа (гость) на этапе **design** правки шагов разрешены. На `approved` / `change` нужны права и заявка.

Справочник по умолчанию (создаётся в `workspace/people.json`):

| id | Имя | access_role |
|----|-----|-------------|
| admin | Администратор | admin |
| owner1 | Владелец процесса | process_owner |
| analyst1 | Аналитик | analyst |
| initiator1 | Инициатор изменений | change_initiator |
| auditor1 | Аудитор | auditor |
| operator1 | Исполнитель | operator |

### 2.2. Системные роли (доступ)

| Роль | Основные права |
|------|----------------|
| `admin` | Участники, обзор, все процессы, утверждение |
| `process_owner` | Аудит/утверждение, владение процессом, утверждение хронометража |
| `analyst` | Правки в `design` и в заявке как участник |
| `change_initiator` | Открыть/вести/закрыть заявку на изменение |
| `auditor` | Аудит, возврат в design, ремарки |
| `operator` | Floor старт/стоп |
| `viewer` | Просмотр |

Роль **на шаге** (Кладовщик, Оператор и т.п.) — это роль исполнителя в модели, не access_role.

### 2.3. Матрица этап × действие (сжато)

| Действие | design | audit | approved | change |
|----------|--------|-------|----------|--------|
| Править шаги | analyst/owner/… | только owner | **нет** (нужна заявка) | участники заявки |
| На аудит | owner/analyst/admin | — | — | — |
| Утвердить процесс | из audit/design | да | — | сначала закрыть заявку |
| Открыть заявку | — | — | initiator/owner | — |
| Закрыть заявку | — | — | — | initiator/owner |
| Floor замеры | да | да | да (pending) | да |
| Утвердить норму времени | — | — | owner/admin | owner/admin |

---

## 3. Studio — каталог и панель процесса

### 3.1. Каталог слева

- Демо (`sample`) и сохранённые (`workspace`)
- Клик по процессу открывает детали
- Ссылка «Мастер: Word → процесс»

#### Дерево процессов (схема организации)

Узлы дерева — это **процессы** (не отдельная сущность «папка»). Группа вроде «Продажи» — обычный процесс-родитель; дочерние ссылаются на него.

| Поле | Назначение |
|------|------------|
| `name` | Подпись узла в каталоге |
| `category` | id секции: встроенные `mgmt` / `core` / `support`, свои, или пусто → «Прочее» |
| `parent_process_id` | Родитель в дереве; пусто — корень секции |
| `sort_order` | Порядок среди соседей (задаётся при создании; на ландшафте — «после») |
| `landscape_x` / `landscape_y` | Позиция узла на холсте «Ландшафт»; пусто — auto-layout |

Секции дерева строятся по `category` корневых процессов. Встроенные: **Management / Core / Support**.

**Новая категория:** в диалоге процесса выберите «+ Новая категория…» (название + опционально код латиницей) — или **Админ → Категории каталога**. Хранение: `workspace/catalog_categories.json`. API: `GET/POST/PATCH/DELETE /api/catalog/categories`. Встроенные удалить нельзя; свою — только если ни один процесс её не использует.

**Создать узел:** кнопка **+ Создать** → название, категория, родитель в дереве, описание → `POST /api/processes` (файл в `workspace/processes/`).

**Изменить имя / категорию / родителя:** на строке процесса кнопка **✎** («Переименовать / дерево») → тот же диалог → `PATCH` метаданных (шаги модели не трогаются).

**Свернуть / развернуть:** ▾ Все / ▸ Все над поиском; клик по ▸/▾ у секции или у узла с детьми. Состояние свёртки хранится в браузере (`localStorage`).

**Архив:** галка «Архив» показывает процессы со статусом архива; по умолчанию в дереве их нет.

Массовый демо-реестр небольшой организации: `scripts/seed_small_org_catalog.py` (`--reset` / `--purge`).

> Не путать с **✎** в таблице шагов (§4) — там правится шаг схемы, а не узел каталога.

### 3.2. Шапка процесса

- **Войти** (форма / MVP полные права), **Админ**, **Заявка на изменение**
- Жизненный цикл: **На аудит** · **Вернуть в design** · **Утвердить** · **Открыть изменение**
- Параметры экспорта: шапка таблицы, тип схемы, режим документов, stubs ОИ/ДО
- Кнопки **Excel** / **Drawio** / **ZIP**

### 3.3. Вкладки

| Вкладка | Содержание |
|---------|------------|
| Таблица | Форма шага, список шагов, роли |
| Готовность | **Доводка** (очередь замечаний) + readiness, аудит, deep-audit, реконструкция, PEMM, хронометраж, журнал |
| Схема | SVG-превью, zoom/fullscreen, редактор отображения (тема по типам + override блока), Drawio / diagrams.net |
| Кампании | Кампании хронометража (инициатор, участники) |
| Автоматизация | Скоринг, ТЗ, roadmap, ROI |
| Документы | DocLink процесса и шагов |
| Соседи | Связанные процессы |
| ИИ | Патч модели инструкцией |
| Мастер | Word / текст → модель |

#### Доводка (Quality Run)

Блок **вверху** вкладки **Готовность** — цикл улучшения модели внутри Studio:

1. Очередь замечаний (error/warning; info — галка «Показать info»).
2. Выберите пункт → **Открыть шаг** или **К источнику**.
3. Исправьте → **Пересчитать**.
4. При `errors = 0` и R ≥ 85% — «Готово к аудиту» → **К кнопке «На аудит»**.

Нет нормы времени (пусто / «−» / «оперативно») — **warning**, не error: **К хронометражу** (Кампании / Floor) или экспертная «15 мин». Если замер **не нужен** или **не сейчас** — в форме шага поле **Норма времени** → «Не требуется» / «Не сейчас» (`timing_policy`).

**Ценность / чужой процесс** (глубокий анализ + Доводка): шаги без смены статуса документа, признаки зоны другого процесса (закупки в модели перевозок и т.п.) — вынести в NeighborLink или уточнить результат шага.

**Дубли:** по всему процессу — похожие названия и описания; один документ на разных шагах без смены статуса; усиленное сравнение соседних шагов (имя + описание + вх/вых). В мастере — kind `name` / `description` / `document` / `adjacent`.

**Ветвление / решение:** предложения шлюзов (Да/Нет, собственный/аренда, после контроля) и ссылка на **Реконструкцию потока** для параллельных разделов. В карточке Доводки — подписи веток; на шаге тип узла `gateway`.

**Объединённый вид:** собирает подпроцессы в одну таблицу и схему. Источники: шаги `call` + **дочерние** процессы каталога (`parent_process_id` = корень). Если у родителя заданы **`flow_links`** — compose строит **граф стыков** (порядок секций и `order` шагов = топология стыков; gateway при ветвлении; fan-out от `__start__`); иначе legacy — последовательно по I/O. После правки стыков таблица и схема обновляются автоматически (включается объединённый вид). Панель «Стыки детей» остаётся доступной. Правки шагов — в отдельных моделях.

#### Перетаскивание и стыки в каталоге

Строки workspace в сайдбаре можно перетаскивать:

| Зона drop | Результат |
|------|-----------|
| **Середина** | Вложить: `parent_process_id` = целевой процесс |
| **Верх/низ** | Порядок + `flow_link` kind=`sequence` на общем родителе |
| **Alt + середина** соседа (тот же parent) | `flow_link` kind=`parallel` (без цепочки) |

У открытого **родителя** с детьми — панель **«Стыки детей»** (как Signavio value chain): шевроны смотрят вправо. **Приставьте блок справа** = `sequence`; **снизу** = `parallel`; **Shift + снизу** = `branch`; клик по **шву** — подпись / отстыковать; **+ Старт** / **Старт → все** / **Расставить**. API: `PUT/POST .../flow-links`.

Циклы в дереве и в графе стыков запрещены. Демо не перетаскивается.

**Мастер доводки:** пошагово одно замечание: рекомендация → **Принять** (с патчем — применяет в модель) / **Отклонить** / **Вручную** (открыть шаг, затем «Готово — далее»). Решения сессии — «Сбросить решения». **Пересчитать** обновляет очередь.

**Вопросы:** всегда в очереди мастера; классификация + при необходимости **Спросить ИИ** (OpenRouter); сохранение только через Принять / правку шага.

API: `GET /api/processes/{source}/{file}/quality-run`.

---

## 4. Работа с шагами

### 4.1. Быстрый ввод

Нижняя строка таблицы: название, роль, вход/выход, work/wait → **Enter** или ✓.

### 4.2. Подробная форма

- Кнопка **+** или **✎** на строке, или клик по строке  
- Поля: тип узла, подшаг для (parent), ветки Да/Нет (для gateway), описание, система, work/wait  

### 4.3. Отображение схемы

На вкладке **Схема** кнопка **Отображение** открывает панель темы процесса:

- **Типы** — форма/цвета для task, gateway, start, end, call (вся схема) → `PATCH .../diagram-theme`
- **Стрелки** — цвет, толщина, режим подписей (авто / mid / offset)
- **Текст** — размер шрифта, выравнивание, размещение подписей шлюзов, фон пула/дорожек
- **Документы** — образцы compact / labeled / artifacts (только превью, через `#docs-display`)
- **Блок** — точечный override: клик по узлу → форма/цвета шага → `PATCH .../steps/{id}/diagram-style`

Тема хранится в `process.diagram_theme`; override — в полях шага. Оба попадают в SVG и Drawio. На classic длинные названия переносятся внутри блока, подписи стрелок сдвигаются от узлов.

- **↑ / ↓** — порядок среди соседних  
- **⧉** — копия как новый шаг  
- Сохранение пишет в **workspace**

### 4.3. Утверждённый процесс

Прямое сохранение шага вернёт ошибку. Нужно:

1. Открыть `/change/...` под ролью initiator/owner  
2. Создать заявку (основание, участники)  
3. Править шаги в статусе `change`  
4. Закрыть заявку → снова `approved`, version++

В Studio при `approved`/`change` видна панель регистрации (автор / основание) — для совместимости; ключевой механизм — **заявка**.

---

## 5. Жизненный цикл процесса

```
design ──На аудит──► audit ──Утвердить──► approved
  ▲                    │                     │
  └──── Вернуть ───────┘                     │
                                             ▼
                                      change (заявка)
                                             │
                                    Утвердить изменение
                                             ▼
                                         approved
```

Legacy-статус `draft` обрабатывается как `design`.

**Журнал изменений** — блок в «Готовность и хронометраж»: записи structure / timing / approve / lifecycle / change.

В MVP журнал и счётчик `version` **не восстанавливают** модель: повторный импорт Excel с тем же `id` перезаписывает JSON. Перед большой правкой в Excel сохраните копию файла. Восстанавливаемые снимки — следующий шаг (см. PRODUCT.md).

**Ремарки аудита** — API `POST .../audit-remarks` (текст замечания на этапах audit/design).

---

## 6. Готовность (readiness)

Раскрывающийся блок «Готовность и хронометраж»:

- Сводный score и чек-лист критериев (роли, документы, шлюзы, соседи…)  
- Аудит несоответствий, зрелость PEMM, хронометраж, журнал  
- **Скачать PPTX** — презентация по текущей модели (готовность + аудит + PEMM + хронометраж)

Используйте перед передачей на аудит и утверждением.  
Презентация *изменений между версиями* — отдельно: кнопка **Версии** → «Презентация изменений».

### 6.1. Документы из модели

На вкладке **Готовность** — блок «Документы из модели»:

- **Черновик правок регламента** — Markdown + Word по diff с предыдущим снимком версии (добавить / исключить / изменить пункты). Исходный файл НРД **не** перезаписывается.
- **Обновить ОИ/ДО** — содержательные операционные и должностные инструкции (и шпаргалка) из шагов модели.
- Ссылки на файлы и **Скачать ZIP** — как у Freeze (`/api/runs/...`).

API: `POST /api/processes/{source}/{file}/docs/generate`  
тело: `{ from_version?: int, kinds?: ["reglament_changes","oi","di","cheat_sheet"], save?: bool }`.  
При закрытии заявки опционально `auto_docs: true`.

---

## 7. Хронометраж

### 7.1. Показатели в Studio

- Process time, Lead time, доля ожидания  
- Узкие места по work/wait  
- Таймер **Старт/Стоп** на строке шага (ручной замер в Studio)

### 7.2. Кампании (вкладка «Кампании»)

Поля: название, цель, **инициатор** (ФИО + роль), **участники** (ФИО + роль), заметки.  
Одновременно одна **открытая** кампания. Замеры floor привязываются к ней.

### 7.3. Floor (рабочее место)

URL вида `/floor/workspace/purchase_request.json` или с `/{step_id}`.

- Указать оператора  
- **Начал** / **Завершил** (можно сразу следующий цикл)  
- На `approved`: сессия закрывается с `approval: pending`, норма шага **не** меняется автоматически  
- На `design`: возможна автоагрегация медианы в `work_minutes`

### 7.4. Утверждение замеров

В блоке «Замеры на утверждении»:

- **Утвердить** — медиана → `work_minutes`, запись в change_log, version++  
- **Отклонить** — pending → rejected, модель не трогается  

Права: process_owner / admin.

---

## 8. Кейс автоматизации

Вкладка **Автоматизация**:

1. Система считает score по шагам (система, work/wait, документы)  
2. Кандидаты получают путь: RPA / BPMS / интеграция / полуавто / вручную  
3. Задайте допущения ROI (ставка, объём, внедрение, лицензии, горизонт) → **Пересчитать и сохранить**  
4. **Скачать ТЗ (.md)** — черновик для ИТ/подрядчика  
5. Roadmap: стабилизация AS-IS → ТЗ → пилот → масштаб → контроль эффекта  

### Как выбирается путь шага

Score 0–100: база 20 + бонусы за систему (+25), work (+15), wait (+5…+15), документы (+10), описание/I-O (+5).  
Старт / конец / gateway → путь «пропуск», score 0.

| Сигнал на шаге | Путь |
|----------------|------|
| Ожидание ≥ 15 мин | BPMS / workflow |
| Есть система + work ≥ 5 мин + документы | Интеграция систем |
| Нет системы + work ≥ 8 мин | RPA / робот UI |
| Есть система, work &lt; 5 и wait &lt; 10 | Полуавтомат (формы / подсказки) |
| Score &lt; 40 или слабые данные | Оставить вручную |
| Иначе при наличии системы | Интеграция (если есть docs) или полуавтомат |
| Иначе без системы | RPA при work ≥ 5, иначе вручную |

Кандидаты = шаги с путями полуавто / RPA / BPMS / интеграция, сортировка по score и work+wait (топ до 12).

### Вердикт по процессу

| Условие | Вердикт |
|---------|---------|
| Нет кандидатов | Сначала доберите данные |
| Readiness &lt; 45% | Сначала стабилизируйте AS-IS |
| Payback ≤ 18 мес и ROI ≥ 50% | Идите в пилот |
| Payback ≤ 36 мес | Пилот с осторожным бюджетом |
| Иначе | Сначала без тяжёлого BPMS (ручная оптимизация) |

API: `GET .../automation-case`, `POST .../automation-case/assumptions`, `GET .../automation-case/tz.md`.

---

## 9. Администратор (`/admin`)

Требуется роль **admin**.

1. **Участники** — создать/править/удалить (ФИО, access_role, подразделение)  
2. **Процессы по этапам** — колонки design / audit / approved / change / …  
3. **Открытые заявки** — ссылки на change desk  

Назначение владельца процесса: API `POST .../owner` с `owner_id` (из админ-сессии).

---

## 10. Инициатор изменения (`/change/{source}/{file}`)

1. Войти как `change_initiator` или owner/admin  
2. **Открыть заявку**: основание*, цель, участники + роль в заявке  
3. **Редактировать шаги** — переход в Studio  
4. **Утвердить и закрыть** — статус процесса → `approved`

Роли в заявке: `analyst`, `auditor`, `process_owner`, `change_initiator`.

---

## 11. Мастер и ИИ

### 10.1. Word → процесс

Вкладка / кнопка мастера: загрузка `.docx` → модель → сохранение в workspace → Freeze.

Режимы извлечения зависят от наличия `OPENROUTER_API_KEY` (правила / auto / ai).

### 10.2. Текст и AI-patch

- Извлечение процесса из текста  
- Инструкция «поправить модель»: добавить шаг, сменить роль и т.п.

Повторный **Run/экспорт** из JSON не тратит токены LLM.

---

## 12. Шапка таблицы (header_preset)

| Пресет | Назначение |
|--------|------------|
| `basic` | №, Шаг, Роль, Вход, Выход |
| `full` | + Система, Документ, сосед |
| `bpm` | + Тип узла |
| `plant` | Эталон производства: вх/вых документ, откуда/как, описание, результат, кто дальше, длительность, ожидание |

---

## 13. Типы схемы (diagram_type)

| Тип | Описание |
|-----|----------|
| `flowchart` | Вертикальный поток |
| `swimlane` | Дорожки по ролям |
| `bpmn` | BPMN-lite |
| `vsm` | Value stream lite |
| `org` | Оргструктура по ролям |

Режимы документов на схеме: `labeled` · `compact` · `artifacts`.

---

## 14. Справочник API (основные)

База: `/api/...`. Cookie сессии или заголовок `X-Person-Id`.

### Сессия и люди
- `GET/POST /api/session`  
- `GET/POST /api/people`, `DELETE /api/people/{id}`  
- `GET /api/admin/overview`

### Процесс
- `GET /api/processes` — каталог (в т.ч. `landscape_x` / `landscape_y`)  
- `GET /api/processes/{source}/{file}` — модель + capabilities  
- `PATCH /api/processes/{source}/{file}` — метаданные каталога / `flow_links`  
- `PUT/POST /api/processes/.../flow-links` — граф стыков детей  
- `POST /api/landscape/group` — объединить процессы в узел-родитель  
- `POST .../steps`, `.../steps/{id}/move`, `DELETE .../steps/{id}`  
- `POST .../approve`, `.../lifecycle/submit-audit`, `.../lifecycle/return-design`  
- `POST .../change-request`, `PATCH .../change-request/{id}`, `POST .../change-request/close`  
- `GET .../readiness`, `GET .../quality-run`, `GET .../chronometry`, `GET .../change-log`  
- `POST .../docs/generate` — черновик правок НРД + ОИ/ДО  
- `GET .../export/{xlsx|drawio|zip}`, `GET .../preview.svg`

### Хронометраж
- `POST .../timing/campaign/start|close`, `GET .../timing/campaigns`  
- `GET .../timing/pending`, `POST .../timing/approve/{step_id}`, `.../reject/{step_id}`  
- `POST /api/floor/.../steps/{id}/start|stop`

### Автоматизация
- `GET .../automation-case`  
- `POST .../automation-case/assumptions`  
- `GET .../automation-case/tz.md`

Полный список маршрутов — в `process_studio/web.py`.

---

## 15. Файлы данных

| Путь | Содержание |
|------|------------|
| `samples/*.json` | Демо-процессы |
| `workspace/processes/*.json` | Сохранённые модели |
| `workspace/catalog_categories.json` | Пользовательские секции каталога |
| `workspace/people.json` | Участники и access_role |
| `workspace/timing/*.json` | Журнал сессий и кампаний |
| `out/` | Результаты Freeze/CLI |

---

## 16. Типовые сценарии

### А. Новый процесс с нуля
1. Открыть демо или Мастер Word  
2. Войти как analyst → править шаги в таблице  
3. Проверить готовность → **На аудит** → **Утвердить**

### Б. Хронометраж утверждённого процесса
1. Вкладка **Кампании** → открыть кампанию  
2. Планшет: `/floor/workspace/...`  
3. Несколько циклов на шаге  
4. В Studio: **Утвердить** pending → норма в модели

### В. Изменение утверждённого
1. `/change/...` → заявка + участники  
2. Analyst правит шаги  
3. Initiator **Утвердить и закрыть**

### Г. Freeze для регламента
1. Выбрать схему и шапку  
2. Excel + Drawio + ZIP  
3. Артефакты без повторного вызова LLM

---

## 17. Ограничения MVP

- Нет паролей / SSO — только выбор участника  
- Floor без жёсткой привязки operator ↔ access_role (доверие к ФИО на форме)  
- BPMN — lite, не полный Camunda-совместимый DI  
- Нет email-уведомлений по заявкам  

---

## 18. FAQ

Те же ответы доступны в UI: страница `/help`.

**Как создать узел или заголовок в дереве процессов?**  
**+ Создать** → название, категория, родитель. «Заголовок» секции — это категория (встроенная или своя через «+ Новая категория…» / Админ); группа вроде «Закупки» — процесс-родитель. Правка: **✎** на строке каталога. Подробнее — §3.1.

**Как добавить свою категорию (секцию) каталога?**  
В диалоге процесса: категория → «+ Новая категория…», либо Админ → «Категории каталога». Код — латиница (`projects`); если пусто — из названия.

**Как довести процесс до аудита?**  
Вкладка **Готовность** → блок **Доводка**: очередь → открыть шаг → исправить → Пересчитать. При 0 error и R≥85% — «К кнопке На аудит». Подробнее — §3.3.

**Чем Studio отличается от BPMS?**  
BPMS исполняет процессы (задачи, маршруты). Studio моделирует и отлаживает AS-IS: шаги, готовность, хронометраж, изменения. Не заменяет runtime BPMS.

**Почему нельзя править approved прямо в таблице?**  
Нужна заявка на `/change/...` с основанием и участниками. После закрытия — снова `approved`, version++.

**Как войти?**  
Кнопка «Войти» → форма. MVP-заглушка: почта/пароль не проверяются, выдаются полные права (`admin`).

**Как утвердить норму после Floor?**  
На `approved` замер → `pending` → в Studio «Утвердить» / «Отклонить» (owner/admin).

**Нужен ли ключ ИИ?**  
Нет для правил и экспорта. `OPENROUTER_API_KEY` — только для LLM extract/patch. Freeze из JSON без токенов.

**Где данные?**  
`samples/`, `workspace/processes/`, `workspace/people.json`, `workspace/timing/`, `out/`.

**Что за вкладка «Автоматизация»?**  
Скоринг шагов → ТЗ.md → roadmap → ROI. Вердикт «пилот / подождать». Не runtime BPMS. Правила пути и вердикта — §8 выше.

**Откуда ROI?**  
Work/wait кандидатов × доля экономии по пути × объём × ставка − внедрение − лицензии. Допущения на вкладке.

См. также: [Описание продукта](PRODUCT.md).
