feat(1c-analyst): режим «Пожелания из совещания» + Devprom ALM API reference

- Новый режим работы: извлечение Пожеланий из транскрипции совещания с заказчиком и загрузка в Devprom ALM через REST API. Один POST на одно Пожелание (без PUT), без привязки к требованиям — она остаётся за пользователем в UI. Границы режима описаны явно: скрипт не создаёт Company, Feature, IssueAuthor, документы требований. - references/meeting-wishes-extraction.md — методика: критерии отбора (что становится Пожеланием, а что нет), 8-шаговый pipeline, HTML-шаблон Description с блоками «Заказчик / Описание / Источники / Цитаты / Предметная область / Источник», Python-шаблон скрипта, антипаттерны. - references/devprom-alm-api.md — шпаргалка Devprom ALM REST API: таблица сущностей со ссылкой на /pm/all/apidocs/list (issue=Пожелание строка 45, request=Доработка строка 18), каноническое имя сущности issue для пожеланий, полный справочник полей, алгоритм POST, ограничения прав (IssueAuthor/User — только UI, DELETE на request заблокирован), порядок подготовки проекта (UI vs API), curl-примеры.
2026-04-21 23:48:51 +00:00
parent 8213ff750a
commit dd1a85fc01
3 changed files with 560 additions and 1 deletions
@@ -12,7 +12,8 @@ description: >
  «1С», «1C», «КА», «ERP», «УПП», «УТ», «ЗУП», «Бухгалтерия», «Комплексная автоматизация»,
  «infostart», «its.1c.ru», «BSL», «встроенный язык 1С» в контексте аналитики, консалтинга
  или внедрения. Также триггерится на «предпроектное обследование ERP», «gap-анализ»,
-  «функциональные требования к ERP», «карта доработок».
+  «функциональные требования к ERP», «карта доработок», «извлечь пожелания из совещания»,
+  «транскрипция встречи с заказчиком», «загрузить пожелания в Devprom», «Devprom ALM API».
 ---

 # 1С-Аналитик — Системный аналитик внедрения 1С
@@ -41,6 +42,7 @@ description: >
 | **Архитектура** | Выбор конфигурации или топологии | Сравнительный анализ конфигураций, одно-/многобазовая архитектура | Word-отчёт или записка |
 | **Миграция** | Переход между конфигурациями | План миграции, риски, переходный период, стратегия переноса остатков | Word-план миграции |
 | **Код/Отчёт** | Нужен конкретный код BSL | Внешний отчёт, обработка, расширение конфигурации | Код BSL с комментариями + спецификация |
+| **Пожелания из совещания** | Есть транскрипция встречи с заказчиком | Извлечение, кластеризация, классификация и загрузка Пожеланий в Devprom ALM | Набор U-пожеланий в Devprom + таблица-сводка |

 ---

@@ -166,6 +168,60 @@ description: >

 **Фаза 5 — Ревью и документирование.** Проверить соответствие плану. Создать описание доработки для передачи клиенту/разработчику.

+### Режим: Пожелания из совещания
+
+Превращение транскрипции встречи с заказчиком в набор формализованных
+Пожеланий в Devprom ALM. Подробная методика — в
+`references/meeting-wishes-extraction.md`. API-шпаргалка Devprom —
+в `references/devprom-alm-api.md`.
+
+**Краткий алгоритм:**
+
+1. **Выделение тем и спикеров** — по транскрипции для каждой обсуждаемой
+   темы фиксируем инициатора, подтверждающих, таймкоды и ключевые цитаты.
+2. **Кластеризация** — одну тему, упомянутую в разных местах совещания,
+   объединяем в одно Пожелание; все таймкоды идут в блок «Источники».
+3. **Отсев по критериям** — оставляем только то, что станет конкретной
+   задачей разработчику/настройщику. Методика работы заказчика,
+   нерешённые бизнес-вопросы и оргмоменты идут в протокол, не в Devprom.
+4. **Классификация** — Caption (одна ёмкая фраза), Priority (1/2/3
+   по акцентам речи), Function (подсистема), предметная область.
+5. **Формирование Description** — строгий шаблон HTML: Заказчик →
+   Описание → Источники → Цитаты (обязательно прямые!) → Предметная
+   область → Источник (файл транскрипции).
+6. **Загрузка через API** — один POST на одно Пожелание в
+   `/issue/items`. Никаких PUT, никакой привязки к требованиям.
+   См. `references/devprom-alm-api.md`, раздел «Алгоритм создания
+   Пожелания».
+7. **Верификация** — все UID с префиксом `U-`, карточка открывается
+   в UI-разделе `/module/requirements/issues`.
+8. **Сводка** — таблица «UID / Функция / Приоритет / Название / Ссылка»
+   + отдельный список того, что намеренно **не стало** Пожеланием.
+
+**Границы режима:**
+
+- **Не создавать** через API документы требований, Company, IssueAuthor,
+  Feature. Всё это готовит владелец проекта/аналитик вручную через UI
+  один раз при заведении проекта. Режим извлечения только **читает**
+  справочники (получает Id нужной Function, Author, Company) и создаёт
+  Пожелания.
+- **Не привязывать Пожелания к требованиям.** Поля `Requirement`
+  и `RequirementDocument` при POST не передаём — они остаются пустыми.
+  Если у Пожелания в будущем появится профильное требование,
+  пользователь привяжет его вручную в UI. Это сознательный
+  процесс согласования с заказчиком, а не автоматический шаг.
+
+**Критически важно:**
+
+- `/request/items` для создания Пожеланий НЕ использовать — даст
+  префикс `I-`, попадёт в «Заявки» (`/issues/board`), а не в «Пожелания».
+  Только `/issue/items`.
+- `IssueAuthor` (автор) через API создать нельзя — если нужен новый
+  автор (например, представитель заказчика), заводить через UI.
+  До этого момента временно использовать автора-себя.
+- DELETE через API работает только для записей, созданных через
+  `/issue/items`. Зомби с префиксом `I-` чистятся только в UI.
+
 ---

 ## Справочник типовых механизмов
@@ -179,6 +235,8 @@ description: >
 > - `references/migration-plan.md` — шаблон плана миграции
 > - `references/tz-review-checklist.md` — чек-лист экспертизы ТЗ
 > - `references/customization-catalog.md` — каталог типов доработок с трудозатратами и артефактами
+> - `references/meeting-wishes-extraction.md` — методика извлечения Пожеланий из транскрипции совещания
+> - `references/devprom-alm-api.md` — справочник Devprom ALM REST API (пожелания, требования, attachments)

 ### Ключевые механизмы КА 2.5 (краткая сводка)

@@ -271,6 +329,7 @@ description: >
 5. **Не давать абстрактных рекомендаций** — каждая рекомендация = конкретное действие
 6. **Не забывать про переходный период** — особенно при миграции
 7. **Не смешивать аналитику с кодингом** — если нужен код BSL, это отдельный режим
+8. **Не использовать `/request/items` для создания Пожеланий в Devprom** — даст префикс `I-` и попадание в «Заявки». Только `/issue/items`, двухшаговая схема POST+PUT. См. `references/devprom-alm-api.md`

 ---

@@ -0,0 +1,278 @@
+# Devprom ALM REST API — рабочая шпаргалка
+
+Справочник для загрузки Пожеланий, Заявок, Требований и вложений в Devprom ALM
+через REST API. Имена сущностей сверены с официальной таблицей справочника
+разработчика: `/pm/all/apidocs/list` (например,
+[artsaterra.myalm.ru/pm/all/apidocs/list](https://artsaterra.myalm.ru/pm/all/apidocs/list)),
+где каждая строка — одна сущность с её `ReferenceName` (используется в REST API)
+и русским именем. Ключевые строки, участвующие в режиме Пожеланий из совещания:
+
+| №  | ReferenceName    | Сущность           |
+|----|------------------|--------------------|
+| 45 | `issue`          | **Пожелание**      |
+| 18 | `request`        | Доработка (заявка с типом) |
+| 81 | `requesttype`    | Тип пожелания      |
+| 92 | `requirement`    | Требование         |
+| 57 | `attachment`     | Приложение (файл)  |
+| 33 | `company`        | Компания           |
+| 46 | `user`           | Пользователь       |
+
+Дополнительные эмпирические детали (поведение, которое в публичной
+документации не раскрыто явно) проверены на инстансе `artsaterra.myalm.ru`
+и отмечаются в тексте курсивом _(проверено эмпирически)_.
+
+Связанные ресурсы:
+- Публичная документация Devprom: [docs.myalm.ru](https://docs.myalm.ru/)
+- Раздел про управление пожеланиями: [artsaterra.myalm.ru/docs/8835.html](https://artsaterra.myalm.ru/docs/8835.html)
+
+---
+
+## 0. Базовое
+
+- **Хост:** `https://<host>/pm/<project-slug>/api/latest`
+- **Аутентификация:** заголовок `Devprom-Auth-Key: <hex>` (личный API-ключ пользователя)
+- **Content-Type:** `application/json`
+- **Ответ:** HTTP 200 всегда, ошибки валидации приходят в теле как `{"error":"…"}`
+- **PATCH не поддерживается** — HTTP 405. Обновление только через PUT.
+- **Успешный ответ на создание:** иногда возвращается как объект, иногда — как массив с одним элементом. Учитывать оба случая.
+
+## 1. Пожелания vs Заявки — КРИТИЧНО
+
+В официальной схеме Devprom это **две разные сущности** с разными
+`ReferenceName` (см. таблицу выше):
+
+- **`issue` (Пожелание)** — сущность из строки 45. Создаётся без типа,
+  UID с префиксом `U-`. В UI живёт в разделе «Пожелания»
+  (`/module/requirements/issues`).
+- **`request` (Доработка)** — сущность из строки 18. Создаётся с обязательным
+  типом (Доработка / Ошибка), UID с префиксом `I-`. В UI живёт на доске
+  заявок (`/issues/board`).
+
+| Логический класс             | Эндпоинт          | Префикс UID | Поле Type       | UI-раздел                          |
+|------------------------------|-------------------|-------------|-----------------|------------------------------------|
+| **Пожелание** (`issue`)      | `/issue/items`    | `U-`        | пусто           | `/module/requirements/issues`      |
+| **Доработка** (`request`)    | `/request/items`  | `I-`        | 397 (Доработка) / 398 (Ошибка) | `/issues/board`     |
+
+_Проверено эмпирически:_ GET на `/issue/items/{id}` и `/request/items/{id}`
+возвращает **одну и ту же запись** (разные виды на один ресурс — внутренне
+это один класс `pm_ChangeRequest`). Разница проявляется при POST — сервер
+применяет разную логику автозаполнения в зависимости от эндпоинта.
+
+### Почему попасть в «Доску пожеланий» можно только через `/issue/items`
+
+_Проверено эмпирически:_ `/request/items` при POST **всегда принудительно
+проставляет `Type=397`** (Доработка), даже если передать `Type: null`,
+`Type: {}` или `Type: {"Id":""}`. Все варианты PUT тоже бессильны — сервер
+восстанавливает 397. Подтверждено на 8 вариантах тела.
+
+Поэтому для создания «чистого» Пожелания (с пустым Type и префиксом `U-`)
+используется эндпоинт именно сущности `issue` — **POST на `/issue/items`**.
+
+## 2. Алгоритм создания Пожелания (рабочий рецепт)
+
+Один POST на одно Пожелание. Без PUT, без привязки к требованиям.
+
+```python
+post_body = {
+    "Caption":  "<заголовок>",
+    "Content":  "<html-описание>",        # по документации; Description тоже принимается
+    "Priority": {"Id": "2"},                # 1=Критично, 2=Высокий, 3=Обычный
+    "Author":   {"Id": "<issueauthor.id>"},
+    "Function": {"Id": "<feature.id>"},     # подсистема (группировка)
+    "Company":  {"Id": "<company.id>"},     # опционально: клиент-источник
+}
+# POST {BASE}/issue/items → {UID: "U-xxxx", Id: "xxxx", ...}
+```
+
+Поля `Requirement` и `RequirementDocument` в теле **не передаются**:
+привязка к документу требований — задача пользователя в UI, не API.
+На этапе создания Пожелания она и не нужна — заказчик подтверждает
+пожелания, формализует требования и уже потом вручную связывает одно
+с другим.
+
+> **Примечание для других сценариев.** Если всё-таки нужно привязать
+> Пожелание к существующему требованию из API (например, массовая
+> миграция из внешней системы), это делается вторым шагом через
+> `PUT /issue/items/{id}` с тем же телом + `Requirement.Id`
+> — в одном POST эти поля молча игнорируются. Для режима «Пожелания
+> из совещания» этот путь не нужен.
+
+### Retry-политика
+
+Egress-прокси периодически роняет запросы с HTTP 502/503/504 («DNS cache overflow»). Всегда оборачивать вызов в цикл `retries=3` с `sleep(2..3)`. Это не связано с Devprom — лечится только ретраями.
+
+## 3. Поля Пожелания — полный справочник
+
+| Поле                  | Тип / формат                 | Обязательность | Комментарий |
+|-----------------------|------------------------------|----------------|-------------|
+| `Caption`             | string                       | обязательно    | Заголовок пожелания |
+| `Content`             | HTML-string                  | обязательно    | Описание. Разрешены: `<p> <b> <ul> <ol> <li> <a> <blockquote> <code>`. Поле `Description` на входе тоже принимается как алиас. |
+| `Priority.Id`         | "1" / "2" / "3"              | по смыслу      | 1=Критично, 2=Высокий, 3=Обычный |
+| `Author.Id`           | issueauthor.id               | обязательно    | Автор пожелания. Справочник инстанс-уровня. |
+| `Function.Id`         | feature.id                   | рекомендовано  | Группировка по подсистемам (создаются через `/feature/items`) |
+| `Company.Id`          | company.id                   | опционально    | Клиент-источник пожелания. Принимается в POST напрямую. |
+| `Requirement.Id`      | requirement.id               | **не передавать в режиме Пожелания из совещания** | Привязка к документу требований — задача пользователя в UI. Для других сценариев (миграция) — только через отдельный PUT после POST. |
+| `RequirementDocument` | —                            | —              | **Не передавать**, заполняется сервером автоматически по родителю `Requirement` |
+| `Type.Id`             | requesttype.id / пусто       | **НЕ передавать для пожелания** | Любая попытка обнулить через API бесполезна; если передать — получится «Заявка» с префиксом I- |
+
+## 4. Удаление
+
+| Эндпоинт              | DELETE работает? | Поведение |
+|-----------------------|------------------|-----------|
+| `/issue/items/{id}`   | **ДА**           | HTTP 200, запись пропадает из листинга и GET возвращает пустые поля |
+| `/request/items/{id}` | **НЕТ**          | HTTP 200 с `{"error":"Unable access entity"}`, запись остаётся в БД в битом виде (зомби) |
+| `/requirement/items/{id}` | Не проверялось | — |
+
+**Практический вывод:** если пожелание создано через `/issue/items` — его можно удалить API. Если случайно создано через `/request/items` — чистить только через UI.
+
+## 5. Справочные эндпоинты (read-only для нашего ключа)
+
+| Эндпоинт                      | Назначение                         |
+|-------------------------------|------------------------------------|
+| `/requesttype/items`          | Типы заявок: Доработка, Ошибка     |
+| `/priority/items`             | Приоритеты                         |
+| `/feature/items`              | Подсистемы/функции (**имя "feature", не "function"!**) |
+| `/issueauthor/items`          | Авторы пожеланий (инстанс-справочник) |
+| `/user/items`                 | Пользователи проекта               |
+| `/company/items`              | Компании-клиенты                   |
+| `/requirement/items`          | Требования и документы требований  |
+| `/state/items`                | Состояния                          |
+
+## 6. Что НЕ работает через API (заблокировано политикой прав)
+
+| Операция                              | Ответ API                          | Обход |
+|---------------------------------------|------------------------------------|-------|
+| POST `/issueauthor/items`             | HTTP 200 + `{"error":"Lack of permissions to create object of IssueAuthor"}` | Только UI: `/pm/<project>/issueauthor` или inline-форма в карточке пожелания |
+| POST `/user/items`                    | То же                              | Только UI |
+| DELETE `/request/items/{id}`          | `{"error":"Unable access entity"}` | Только UI |
+
+Пытаться обойти через write-only ключ проекта, `api/v1`, `api/v2`, инстанс-путь без `/pm/<project>/` — **бесполезно**, все варианты дают тот же отказ.
+
+## 7. Создание документа требований
+
+> ⚠️ **В режиме «Пожелания из совещания» этот путь НЕ используется.**
+> Структуру документов требований (`requirement`, строка 92 таблицы сущностей)
+> выстраивает владелец проекта/аналитик вручную через UI Devprom —
+> постепенно, по мере формализации требований, согласованных с заказчиком.
+> Привязку Пожеланий (`issue`) к требованиям пользователь тоже делает
+> вручную в UI. Режим извлечения пожеланий в эту структуру не вмешивается.
+> Раздел оставлен для справки — на случай других задач (миграция требований,
+> импорт из внешней системы и т.п.).
+
+```python
+POST /requirement/items
+body = {
+    "Caption": "Корневой документ",
+    "Content": "<p>описание</p>",
+    # "ParentPage": {"Id": "..."}  # если создаём подстраницу
+}
+```
+
+Корневой документ — без `ParentPage`. Подстраница — с `ParentPage.Id = <id_корня>`. UID корневых документов присваивается по правилам шаблона проекта (например, `О-1`, `R-35`).
+
+## 8. Attachment (приложить файл)
+
+По [официальной документации](https://artsaterra.myalm.ru/docs/8835.html):
+
+```python
+POST /attachment/items
+body = {
+    "FileExt":     "transcript.txt",
+    "ObjectId":    "<request.id>",
+    "ObjectClass": "Request",          # именно Request — общий класс для issue и request
+    "File":        "<base64 содержимого>",
+}
+```
+
+## 9. Альтернативные и несуществующие эндпоинты
+
+Тестировались, но возвращают `{"error":"Unknown entity: ..."}`:
+
+- `/userwish/items`, `/wish/items`, `/userrequest/items`, `/suggestion/items`
+- `/admin/request/items`, `/api/latest/admin/request/items`
+- `/pmcustomclass/items`, `/customclass/items`, `/class/items`
+
+Существующие служебные варианты:
+
+- `/api/v1/request/items`, `/api/v2/request/items` — принимают POST,
+  но принудительная логика `Type=397` та же, что на `/api/latest/request/items`;
+  использовать не нужно.
+
+> Примечание: эндпоинт `/issue/items` — не алиас `/request/items`,
+> а отдельная сущность `issue` (Пожелание) из таблицы сущностей Devprom,
+> строка 45. Под капотом они указывают на один и тот же класс
+> `pm_ChangeRequest`, но серверная логика автозаполнения при POST
+> у них разная (см. раздел 1).
+
+## 10. Порядок подготовки проекта для загрузки пожеланий
+
+Граница ответственности: **структуру проекта готовит человек через UI,
+пожелания загружает скрипт через API**. Скрипт не создаёт Company,
+Feature, документы требований, IssueAuthor — только читает их.
+
+### Делается вручную через UI (один раз на проект, силами аналитика)
+
+1. **Company** для каждого клиента, который генерирует пожелания.
+   - Пример: «АРД» с доменом `alreadycom.ru`.
+2. **Feature** (подсистемы) — 3–5 на проект по подсистемам целевой
+   конфигурации. Можно создать и скриптом (`POST /feature/items`) —
+   на `feature` ограничений API нет, но обычно удобнее через UI.
+   - Пример для КА 2.5: «НСИ и администрирование», «Продажи», «Склад»,
+     «Казначейство», «Производство».
+3. **IssueAuthor** для представителей заказчика — если нужно, чтобы
+   автором пожелания был сам клиент, а не аналитик. Только через UI.
+4. **Документы требований** — структуру требований клиент/аналитик
+   выстраивает постепенно, по мере работы над проектом. Режим
+   извлечения Пожеланий в неё не вмешивается.
+
+### Делается скриптом через API (каждое новое совещание)
+
+5. **Цикл по Пожеланиям** — для каждого: один POST `/issue/items`
+   с полями Caption, Content, Priority, Author, Function и опционально
+   Company. `Requirement` не передаётся.
+6. **GET** `/issue/items/{id}` — верификация, что UID начинается
+   на `U-`.
+7. **Привязка Пожеланий к требованиям** — **вне скрипта**,
+   это ручная работа пользователя в UI, когда требования появятся
+   и согласованы с заказчиком.
+
+---
+
+## Appendix — примеры curl
+
+### Создание пожелания (как в документации, с Type=Доработка)
+```bash
+curl -X POST \
+  -H "Devprom-Auth-Key: <KEY>" -H "Content-Type: application/json" \
+  https://<host>/pm/<proj>/api/latest/request/items \
+  -d '{"Caption":"Новая доработка","Content":"<p>Описание</p>","Type":{"Id":"397"}}'
+# → UID=I-xxxx, Type=Доработка
+```
+
+### Создание пожелания без типа (рекомендуемый путь)
+```bash
+curl -X POST \
+  -H "Devprom-Auth-Key: <KEY>" -H "Content-Type: application/json" \
+  https://<host>/pm/<proj>/api/latest/issue/items \
+  -d '{"Caption":"Пожелание","Content":"<p>Описание</p>","Priority":{"Id":"2"},"Author":{"Id":"1"},"Function":{"Id":"190"},"Company":{"Id":"146"}}'
+# → UID=U-xxxx, Type=пусто
+```
+
+### Привязка к документу требований (не нужна в режиме «Пожелания из совещания»)
+
+Используется только для миграционных сценариев:
+
+```bash
+curl -X PUT \
+  -H "Devprom-Auth-Key: <KEY>" -H "Content-Type: application/json" \
+  https://<host>/pm/<proj>/api/latest/issue/items/6179 \
+  -d '{"Caption":"Пожелание","Content":"<p>Описание</p>","Priority":{"Id":"2"},"Author":{"Id":"1"},"Function":{"Id":"190"},"Requirement":{"Id":"4378"}}'
+```
+
+### Удаление
+```bash
+curl -X DELETE \
+  -H "Devprom-Auth-Key: <KEY>" \
+  https://<host>/pm/<proj>/api/latest/issue/items/6179
+# → HTTP 200, []
+```
@@ -0,0 +1,222 @@
+# Извлечение Пожеланий из транскрипции совещания
+
+Методика превращения транскрипции рабочего совещания с заказчиком
+в набор формализованных Пожеланий в Devprom ALM. Проверена на совещании
+с главбухом АРД (21.04.2026).
+
+Связанные файлы:
+- `references/devprom-alm-api.md` — как писать в Devprom через API
+- Скилл `docx` — для возможного экспорта сводки в Word
+
+---
+
+## Критерии отбора: что становится Пожеланием, а что нет
+
+### Становится Пожеланием
+
+1. **Доработка конфигурации** — новый реквизит, новое правило, новая форма, интеграция.
+   _Пример: «Допреквизит „Доступно для менеджера" в справочнике номенклатуры»._
+2. **Изменение бизнес-процесса с цифровым следом** — новая цепочка документов, автоматизация этапа, блокировка операции.
+   _Пример: «Запрет проведения отгрузки при отрицательном остатке»._
+3. **Типовая настройка с конкретным целевым эффектом** — использование типового механизма там, где клиент раньше работал руками.
+   _Пример: «Использовать типовой механизм Номенклатура контрагентов»._
+4. **Интеграция с внешней системой** — ЭДО, клиент-банк, маркетплейс, CRM, АТС.
+   _Пример: «Автоматическая отправка отгрузочных документов в Диадок»._
+
+### НЕ становится Пожеланием
+
+1. **Методика внутренней работы заказчика** — как они сейчас живут в Excel, как главбух разбирает почту.
+2. **Нерешённые бизнес-вопросы** без автоматизационного следа — «надо решить, кто отвечает за ставку НДС», «КП оформляем в Word или в 1С».
+3. **Оргмоменты и ответственность** — назначение ролей, регламент согласований без запроса автоматизации.
+4. **Общие рассуждения и отступления** — истории про то, как раньше работали.
+
+### Проверочный вопрос
+
+_«Если бы это пожелание взял в работу разработчик конфигурации — что конкретно он бы сделал?»_ Если ответ неконкретный («поговорил с главбухом», «уточнил процесс», «подумал») — это **не пожелание**, а открытый вопрос в протокол совещания.
+
+---
+
+## Пайплайн
+
+### Шаг 1 — Выделение тем и спикеров
+
+Читаем транскрипцию целиком. Для каждой темы фиксируем:
+
+- **Тему** (1 фраза)
+- **Инициатора** (кто первым её подняла + таймкод)
+- **Подтверждающих** (кто согласился, уточнил, добавил детали)
+- **Открытые вопросы** (если обсуждение заблокировалось)
+
+Нотация: `[Спикер тайм-код] → ключевая мысль`.
+
+### Шаг 2 — Кластеризация
+
+Одна тема может обсуждаться несколько раз в разных частях совещания — в начале, в середине (уточнение), в конце («а ещё мы забыли...»). Все упоминания одной темы объединяем в **одно** Пожелание. В `Источники` блока перечисляем все таймкоды всех спикеров.
+
+### Шаг 3 — Отсев по критериям
+
+Применяем проверочный вопрос из раздела «Критерии отбора». Оставшееся — кандидаты на Пожелания. То, что отсеяли, записываем отдельным списком в сопроводительную заметку («Для обсуждения на внутреннем совещании заказчика») — это протокол, а не Devprom.
+
+### Шаг 4 — Классификация
+
+Для каждого Пожелания-кандидата:
+
+- **Caption** — одна ёмкая фраза, суть. 10–15 слов. Можно цитировать термин конфигурации («допреквизит», «заказ покупателя»).
+- **Priority** — по акцентам речи:
+  - `1` (Критично) — заказчик повторил несколько раз, сказал «100%», «без этого работать нельзя», или речь про блокировку ошибок/убытков.
+  - `2` (Высокий) — инициатор явно настаивал, есть конкретная цель.
+  - `3` (Обычный) — обсудили, согласились, без нажима.
+- **Function** — подсистема КА 2.5 / ERP 2.5. См. `references/ka25-capabilities.md`. Типично: НСИ, Продажи, Закупки, Склад, Казначейство, Производство, Бухгалтерия, Управленческий учёт.
+- **Предметная область** — уточнение внутри подсистемы («Управление доступом менеджеров к НСИ», «Контроль остатков»).
+
+### Шаг 5 — Формирование Description
+
+Единый шаблон HTML для поля `Content` в Devprom:
+
+```html
+<p><b>Заказчик:</b> ФИО, должность (email)</p>
+<p><b>Описание:</b></p>
+<p>Полное описание пожелания в свободной форме — что должно делать,
+какие условия, какие границы. 3–7 предложений.</p>
+<p><b>Источники:</b></p>
+<ul>
+<li>ФИО спикер-1, должность — роль в обсуждении (тайм-коды)</li>
+<li>ФИО спикер-2, роль — (тайм-коды)</li>
+</ul>
+<p><b>Цитаты:</b></p>
+<blockquote>Спикер (тайм-код): «прямая цитата».</blockquote>
+<blockquote>Спикер (тайм-код): «прямая цитата».</blockquote>
+<p><b>Предметная область:</b> Подсистема / Конкретика</p>
+<p><b>Примечание:</b> (опционально) — например, «функционал типовой,
+требует настройки процесса, без разработки»</p>
+<p><b>Источник:</b> Совещание от DD.MM.YYYY, файл
+<code>transcript.txt</code></p>
+```
+
+Правила по содержимому:
+
+- **Цитаты — обязательны**, 1–3 штуки на пожелание. Без цитат будущий разработчик не поймёт контекст.
+- **Цитаты прямые** — без редактуры речи. Сохранять разговорный стиль, паузы, просторечия. Это контекст, а не литература.
+- **Описание в повествовательной форме** — не «пользователь хочет, чтобы», а прямое «Система должна…», «В справочнике номенклатуры ввести…». Подлежащим делаем объект системы, не пользователя.
+- **Никаких оценок объёма и сроков** — это предмет gap-анализа, не этапа извлечения пожеланий.
+- **Никаких архитектурных решений** — если пожелание порождает архитектурные вопросы, они идут отдельным Пожеланием с типом «Архитектурное решение» или в протокол совещания.
+
+### Шаг 6 — Загрузка через API
+
+Один POST на одно Пожелание. Никакой привязки к требованиям,
+никаких PUT. Поля `Requirement` и `RequirementDocument` остаются
+пустыми — пользователь вручную прикрепит их в UI, если/когда
+появится профильное требование.
+
+```python
+post_body = {
+    "Caption":  wish["caption"],
+    "Content":  CUSTOMER_NOTE + wish["description"] + SOURCE_NOTE,
+    "Priority": {"Id": wish["priority"]},    # "1"/"2"/"3"
+    "Author":   {"Id": AUTHOR_ID},
+    "Function": {"Id": wish["function_id"]},
+    "Company":  {"Id": COMPANY_ID},          # опционально
+}
+# POST /issue/items → {UID: "U-xxxx", ...}
+```
+
+Подробный справочник полей и поведение API — в
+`references/devprom-alm-api.md`.
+
+### Шаг 7 — Верификация
+
+После загрузки:
+
+- Открыть `/pm/<project>/module/requirements/issues` → все загруженные пожелания должны отображаться одним списком.
+- UID у всех — префикс **`U-`**.
+- У каждого заполнены `Priority`, `Function`, `Author`. Поля `Requirement`
+  и `RequirementDocument` пустые — это норма, привязку делает
+  пользователь вручную в UI.
+- Открыть одну карточку случайно — проверить форматирование HTML, работу ссылок (mailto:), наличие цитат.
+
+### Шаг 8 — Сводка для пользователя
+
+После загрузки отдать:
+
+- Таблица «№ / UID / Функция / Приоритет / Название / Ссылка»
+- Список того, что намеренно **НЕ стало Пожеланиями** — короткие формулировки с причиной («методика», «открытый вопрос», «оргмомент»).
+
+---
+
+## Скрипт-шаблон (Python, без внешних зависимостей)
+
+Шаблон есть в `templates/wishes-upload.py` (при наличии). Ключевые моменты:
+
+```python
+import json, urllib.request, urllib.error, ssl, time
+
+HDR = {"Devprom-Auth-Key": "<KEY>",
+       "Content-Type": "application/json",
+       "Accept": "application/json"}
+BASE = "https://<host>/pm/<project>/api/latest"
+
+def call(method, path, body=None, retries=3):
+    """urllib + ретраи по 502/503/504 от egress-прокси."""
+    data = json.dumps(body, ensure_ascii=False).encode("utf-8") if body else None
+    for attempt in range(1, retries+1):
+        req = urllib.request.Request(f"{BASE}/{path}", data=data,
+                                     headers=HDR, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=25,
+                                        context=ssl.create_default_context()) as r:
+                return r.status, r.read().decode("utf-8")
+        except urllib.error.HTTPError as e:
+            if e.code in (502, 503, 504) and attempt < retries:
+                time.sleep(3 * attempt); continue
+            return e.code, e.read().decode("utf-8")
+
+for wish in WISHES:
+    post_body = {
+        "Caption":  wish["caption"],
+        "Content":  CUSTOMER_NOTE + wish["description"] + SOURCE_NOTE,
+        "Priority": {"Id": wish["priority"]},
+        "Author":   {"Id": AUTHOR_ID},
+        "Function": {"Id": wish["function"]},
+        "Company":  {"Id": COMPANY_ID},      # опционально
+    }
+    code, text = call("POST", "issue/items", post_body)
+    r = json.loads(text); r = r[0] if isinstance(r, list) else r
+    issue_id = r["Id"]
+    # проверка
+    _, t = call("GET", f"issue/items/{issue_id}")
+    g = json.loads(t)
+    assert g["UID"].startswith("U-"), f"префикс не U-: {g['UID']}"
+```
+
+---
+
+## Анти-паттерны
+
+1. **Создание через `/request/items`** — даст префикс I- и попадание в «Заявки».
+   _Использовать только `/issue/items`._
+2. **Создание документов требований, Company, Feature или IssueAuthor
+   из этого режима** — `POST /requirement/items`, `POST /company/items`
+   и т.п. в режиме извлечения Пожеланий **не вызывать**. Эти справочники
+   готовит владелец проекта вручную через UI Devprom заранее. Если нужных
+   записей нет (например, нет подходящей Function) — остановиться,
+   запросить их создание, и только после этого продолжать загрузку.
+3. **Привязка Пожелания к документу требований при создании** — поля
+   `Requirement` и `RequirementDocument` в теле POST не передавать.
+   Пользователь сам прикрепит пожелание к нужному требованию в UI,
+   когда это требование появится. Попытка «сразу правильно» привязать
+   ломает процесс согласования с заказчиком.
+4. **Цитаты в пересказе** — обезличивают пожелание, делают его неотличимым от прочих. _Только прямые цитаты в blockquote._
+5. **Смешение в одном Пожелании двух разных требований** — потом невозможно оценить объём и трассировать. _Один атомарный запрос — одно Пожелание._
+6. **Создание IssueAuthor через API** — заблокировано на уровне прав. _Только через UI._
+7. **Попытка удалить DELETE-ом запись с префиксом I-** — сервер отвечает 200 + error, запись остаётся зомби. _Чистить через UI._
+
+---
+
+## Memo для будущих расширений
+
+Потенциальные улучшения, если появится потребность:
+
+- **Автопривязка транскрипции** к пожеланию через `/attachment/items` (прикрепление `.txt` файла с полной транскрипцией к одному «главному» Пожеланию или к документу требований).
+- **Экспорт сводки в Word** через скилл `docx` — для отправки клиенту или приобщения к протоколу.
+- **Автоопределение Priority по акцентам** — через LLM-классификацию фраз типа «100%», «критично», «можем обсудить позже».
+- **Автоопределение Function** — словарь ключевых слов → подсистема (см. `references/ka25-capabilities.md`).