aatex-orders - SKILL.md Agent Skill

name: aatex-orders description: Создание и управление заказами (order type) в ЦУП ААТех. Применяй когда пользователь говорит "создай заказ", "новый order", "договор с клиентом", "закупка от поставщика", "привяжи контрагента к заказу". Заказы ТРЕБУЮТ buyer и seller контрагентов — это специфика типа order, отличающаяся от обычных карточек.

Создание заказов (order type)

Когда использовать

Специализированный скилл для работы с карточками типа order. Используй его, а не общий aatex-cards, когда:

Пользователь явно говорит «заказ», «договор», «order»
Нужно привязать контрагентов (покупателя/продавца)
Создаётся структура «заказ → позиции → документация»

Что обязательно для заказа

Поле	Источник
`boardId` (primary)	`list_all_boards` или `list_boards`
`spaceId`	оттуда же
`columnId`	`get_board_columns(boardId)`
`title`	от пользователя
`cardType: "order"`	константа
`typeSpecificData.buyerContragentId`	`list_contragents(search="...")`
`typeSpecificData.sellerContragentId`	`list_contragents(search="...")`

КРИТИЧЕСКИ ВАЖНО: без обоих контрагентов заказ создать нельзя — API вернёт ошибку.

Полный пример создания заказа

Шаг 1. Собрать контрагентов

# Ищем покупателя:
list_contragents(search="ООО Ромашка")
→ [{id: "cg_abc", name: "ООО Ромашка", inn: "7707..."}, ...]
→ buyerContragentId = "cg_abc"

# Если не нашли — создать:
search_contragent_by_inn(inn: "7707083893")  # данные из ЕГРЮЛ
create_contragent(name, inn, kpp, ogrn, legalAddress)
→ contragentId

# Ищем продавца (себя):
list_contragents(search="название своей орги")
→ sellerContragentId

Шаг 2. Найти доску

list_all_boards
→ ищем спейс "Продажи" или "Заказы", тип primary
→ boardId, spaceId

get_board_columns(boardId)
→ находим колонку "Новые" или "Черновик"
→ columnId

Шаг 3. Создать заказ

create_card({
  boardId,
  spaceId,
  columnId,
  title: "Заказ №15 — ООО Ромашка",
  cardType: "order",
  description: "...",                    // опционально
  responsibleUserId: "...",               // кто ведёт заказ
  typeSpecificData: {
    buyerContragentId,
    sellerContragentId,
    contractNumber: "15/2026",            // номер договора
    contractDate: "2026-04-15",           // дата (YYYY-MM-DD)
    contractLink: "https://...",          // опционально
    specificationNumber: "SP-001",        // опционально
    specificationDate: "2026-04-16",
    buyerContactPersonIndex: 0,           // индекс контакта в contragent.contacts
    sellerContactPersonIndex: 0,
  },
  productionStartDatePlanned: "2026-05-01",
  productionEndDatePlanned: "2026-06-30",
})

Шаг 4. (Опционально) добавить позиции

# Для каждой позиции:
create_card({
  boardId, spaceId, columnId,
  title: "Позиция 1 — Продукт X",
  cardType: "position",
  parentCardId: orderCardId,           // привязка к заказу
  description: "...",
})

typeSpecificData — поля для order

Поле	Тип	Назначение
`buyerContragentId`	string	Обязательно — покупатель
`sellerContragentId`	string	Обязательно — продавец
`contractNumber`	string	Номер договора
`contractDate`	`YYYY-MM-DD`	Дата договора
`contractLink`	string	URL документа
`buyerContactPersonIndex`	number	Индекс контакта покупателя (0-based)
`buyerContactPersonIndexes`	number[]	Несколько контактов покупателя
`sellerContactPersonIndex`	number	Индекс контакта продавца
`sellerContactPersonIndexes`	number[]	Несколько контактов продавца
`specificationNumber`	string	Номер спецификации
`specificationDate`	`YYYY-MM-DD`	Дата спецификации
`specificationLink`	string	URL спецификации

Контактные лица

У контрагента в contacts — массив [{name, phone, email, position}, ...]. Индекс — позиция в этом массиве.

Чтобы привязать конкретное контактное лицо:

1. get_contragent(buyerContragentId) → contragent.contacts
2. Нашли нужного человека на индексе N
3. create_card(..., typeSpecificData: {..., buyerContactPersonIndex: N})

Обновление существующего заказа

update_card(orderCardId, {
  typeSpecificData: {
    buyerContragentId: "новый_id",      // заменить покупателя
    contractNumber: "15-upd/2026",
  }
})

Важно: typeSpecificData в update — merge, а не replace. Только переданные поля меняются, остальные остаются.

Для полной очистки — typeSpecificData: null.

Типичные ошибки

Ошибка	Причина
`buyerContragentId and sellerContragentId are required for order type`	Забыл контрагентов в typeSpecificData
`Contragent not found`	ID неправильный или контрагент в другой орге
`Invalid date format`	Дата не в `YYYY-MM-DD`
Заказ создан, но тип не order	Забыл `cardType: "order"`
`Cannot create card on dispatch board`	Используется dispatch вместо primary

Связь с другими скиллами

aatex-contragents — поиск, создание контрагентов, ЕГРЮЛ
aatex-navigation — найти подходящую доску и колонку
aatex-cards — после создания заказа, работа с позициями
aatex-files — прикрепить скан договора к карточке заказа

Пример полного диалога

Пользователь: «Создай заказ №42 для ООО Авангард, договор 42/2026 от 15 апреля»

1. list_contragents(search="Авангард") → cg_buyer_id
2. list_contragents(search="<своя орга>") → cg_seller_id
3. list_all_boards → boardId="...", spaceId="..." (доска Продажи, primary)
4. get_board_columns(boardId) → columnId="col_new"
5. create_card({
     boardId, spaceId, columnId,
     title: "Заказ №42 — ООО Авангард",
     cardType: "order",
     typeSpecificData: {
       buyerContragentId: "cg_buyer_id",
       sellerContragentId: "cg_seller_id",
       contractNumber: "42/2026",
       contractDate: "2026-04-15"
     }
   })
   → заказ создан, показать id