diff --git a/1c-analyst/SKILL.md b/1c-analyst/SKILL.md index 50664d3..bdccc18 100644 --- a/1c-analyst/SKILL.md +++ b/1c-analyst/SKILL.md @@ -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` --- diff --git a/1c-analyst/references/devprom-alm-api.md b/1c-analyst/references/devprom-alm-api.md new file mode 100644 index 0000000..328d698 --- /dev/null +++ b/1c-analyst/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:///pm//api/latest` +- **Аутентификация:** заголовок `Devprom-Auth-Key: ` (личный 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": "", # по документации; Description тоже принимается + "Priority": {"Id": "2"}, # 1=Критично, 2=Высокий, 3=Обычный + "Author": {"Id": ""}, + "Function": {"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 | обязательно | Описание. Разрешены: `