Назад к блогу
Архитектура 12 мин чтения

OpenSpec в разработке WMS/CRM для автозапчастей: сначала спецификация, потом код

Как spec-driven цикл OpenSpec удерживает AI-агента в рамках домена склада и CRM: резервы, ячейки, офферы. Разбор на реальном change — soft-reserve остатка при создании заказа.

OpenSpec в разработке WMS/CRM для автозапчастей: сначала спецификация, потом код

Зачем вообще OpenSpec, если есть Cursor

В магазине автозапчастей домен жёсткий: артикул, применяемость, оффер поставщика, ячейка на складе, резерв под заказ, отмена, возврат. Если просить AI «добавь резервирование» одним абзацем в чате, получите красивый сервис и три скрытых бага: двойной резерв, вечный soft-hold и рассинхрон CRM с WMS.

OpenSpec (Fission-AI) — это не ещё один генератор кода. Это лёгкий spec-driven цикл вокруг AI-ассистента: сначала фиксируете поведение в markdown, правите план, и только потом агент пишет код по чеклисту. Спеки лежат в репозитории рядом с кодом и живут в git.

идея → propose (план) → review → apply (код) → archive (спеки вливаются в source of truth)

Для WMS/CRM это особенно полезно: «готово» здесь — не «сборка зелёная», а набор сценариев, которые кассир, кладовщик и сайт должны переживать одинаково.

Как устроен цикл

После openspec init в корне появляется:

openspec/
├── specs/                 # правда о текущем поведении системы
│   └── inventory/
│       └── spec.md
├── changes/               # изменения в полёте
│   └── add-soft-reserve/
│       ├── proposal.md
│       ├── design.md      # только если нужны техрешения
│       ├── tasks.md
│       └── specs/         # delta: ADDED / MODIFIED / REMOVED
│           └── inventory/
│               └── spec.md
└── changes/archive/       # история завершённых change

В Cursor это обычно slash-команды вроде /opsx-propose, /opsx-apply, /opsx-archive (после openspec init --tools cursor). Сами артефакты — обычный markdown: их можно править руками или просить агента переписать кусок.

  • Explore — проговорить границы, не писать код.
  • Propose — папка change с proposal, delta-spec и tasks.
  • Review — вы правите требования, пока код ещё не существует.
  • Apply — агент идёт по tasks.md, отмечая чекбоксы.
  • Archive — delta вливается в openspec/specs/, change уезжает в archive.

Где это бьётся с автозапчастями

Типичный контур продажи запчасти:

Витрина / CRM  →  Оффер (цена, срок, источник)
                 →  Резерв на своём складе или заказ у внешнего
                 →  Сборка по ячейкам / отгрузка
                 →  Статус в CRM и уведомление клиенту

Боль боли — не CRUD справочников, а согласованность состояний. OpenSpec заставляет писать это как требования со сценариями WHEN / THEN, а не как «сделай endpoint».

Домены, которые удобно держать отдельными спеками:

  • catalog — карточка, кроссы, применяемость;
  • offers — цена/остаток/SLA поставщика;
  • inventory — ячейки, партии, резервы, инвентаризация;
  • orders — жизненный цикл заказа в CRM;
  • fulfillment — сборка, отгрузка, возврат на ячейку.

Реальный пример: soft-reserve при создании заказа

Задача из жизни склада автозапчастей. Менеджер в CRM создаёт заказ на BOSCH 0 986 479 123, источник исполнения — свой склад. Нужно:

  1. зарезервировать количество под заказ (soft-reserve);
  2. не отдавать этот остаток другому заказу;
  3. снять резерв, если заказ отменили или истек TTL (клиент «подумаю до вечера»);
  4. при сборке перевести soft → hard (привязка к конкретным ячейкам/штрихкодам).

Без спеки агент почти всегда забывает TTL или делает hard-reserve сразу — и кладовщик через час не может собрать «живой» заказ, потому что деталь висит на брошенной корзине.

1. Propose

В чате:

Propose a change add-order-soft-reserve:
soft-reserve собственного склада при создании заказа в CRM,
TTL 30 минут для web-корзины и 4 часа для менеджерского черновика,
освобождение при cancel, переход в hard-reserve на старте сборки.

Агент создаёт openspec/changes/add-order-soft-reserve/. Ключевой файл — delta-spec. Упрощённый фрагмент того, что должно получиться:

## ADDED Requirements

### Requirement: Soft reserve on order create
При создании заказа со источником «собственный склад» система SHALL
создать soft-reserve на доступный остаток. Доступный остаток =
on_hand − soft_reserved − hard_reserved.

#### Scenario: Успешный резерв
- WHEN менеджер создаёт заказ на 2 шт. артикула с available ≥ 2
- THEN создаётся reserve со status=SOFT, order_id, qty=2
- AND available уменьшается на 2 для последующих заказов

#### Scenario: Недостаточно остатка
- WHEN available < requested qty
- THEN заказ не создаётся (или линия помечается backorder — по policy)
- AND новый soft-reserve не пишется

### Requirement: Soft reserve TTL
Система SHALL освобождать SOFT-резервы с истекшим expires_at
фоновым job не реже раза в минуту.

#### Scenario: Истек TTL web-корзины
- WHEN soft-reserve создан с TTL 30 минут и время вышло
- THEN status становится RELEASED
- AND available возвращается

### Requirement: Promote to hard reserve on pick start
При старте сборки система SHALL перевести связанные SOFT в HARD
с привязкой к ячейкам пик-листа.

#### Scenario: Старт сборки
- WHEN кладовщик открывает задание на сборку заказа
- THEN soft-reserve переходит в HARD
- AND в резерве появляются cell_id / barcode единиц

2. Review — здесь и ловится экспертиза

До кода я обычно вычёркиваю лишнее и дописываю доменные края:

  • частичный резерв по мультибрендовой корзине (свой склад + внешний оптовик в одном заказе);
  • идемпотентность: повторный POST /orders с тем же Idempotency-Key не должен съесть остаток дважды;
  • инвентаризация: нельзя «тихо» увеличить available поверх незакрытого HARD;
  • отмена после начала сборки — отдельный change, не тащить в этот.

Именно review отличает OpenSpec от «агент сам всё придумал». Спека — контракт между вами и будущим собой (и следующим агентом в новом чате).

3. Apply

В новом чате: Apply the add-order-soft-reserve change. Агент читает change-папку и идёт по tasks.md примерно так:

- [ ] Миграция: reserve(id, order_id, sku, qty, status, expires_at, cell_id)
- [ ] Сервис AvailableQty = on_hand - soft - hard
- [ ] Создание soft при OrderCreated (свой склад)
- [ ] Job ReleaseExpiredSoftReserves
- [ ] Promote soft→hard на PickStarted
- [ ] Тесты сценариев из spec.md
- [ ] Метрики: soft_active, soft_expired, reserve_conflict

Если контекст кончился — новый чат и снова Apply: прогресс в чекбоксах, скрытого state нет.

4. Archive

Когда tasks закрыты: Archive the add-order-soft-reserve change. Требования из delta попадают в openspec/specs/inventory/spec.md. Следующий change — например, «возврат на ячейку после отказного клиента» — уже видит soft/hard как часть текущего поведения, а не как устную договорённость в старом PR.

Что даёт на практике в WMS/CRM

  • Меньше «умного» хаоса от AI. Агент не размазывает резерв по трём сервисам «как показалось удобнее» — у него есть delta и tasks.
  • Онбординг. Новый разработчик (или новый чат) читает openspec/specs/ и понимает, что система делает, а не только как названы классы.
  • Резанный scope. Легче сказать «это отдельный change», чем откатывать половину сгенерированного PR.
  • Регрессии в голове. Перед следующей фичей видно, какие сценарии нельзя сломать: TTL, идемпотентность, promote на сборке.

Антипаттерны, которые я ловил

  • Спека размером с ТЗ на всю CRM. OpenSpec любит маленькие change. «Склад целиком» — это пять–семь архивов, не один proposal на 40 страниц.
  • Design.md вместо требований. Схема БД без WHEN/THEN не ловит двойной резерв.
  • Apply без review. Тогда это снова vibe-coding, только с лишними файлами в openspec/.
  • Спеки не коммитить. Если delta жила только локально, следующий агент её не увидит — смысл пропадает.

С чего начать в своём репо

  1. Поставить CLI (installation) и в корне проекта: openspec init --tools cursor.
  2. Не описывать всю систему. Взять один болевой контур: резерв, приёмка на ячейку, или смена поставщика в линии заказа.
  3. Прогнать полный цикл до archive — даже на небольшой фиче. Мышца review важнее идеальной первой спеки.
  4. Держать домены тонкими: inventory отдельно от orders, иначе delta превратится в простыню.

Итог

OpenSpec не заменяет знание домена автозапчастей. Он даёт место, куда это знание положить до генерации кода, и цикл, в котором AI обязан следовать согласованным сценариям. Для склада и CRM, где ошибка в остатках бьёт по деньгам и доверию клиента, «сначала spec, потом apply» — не бюрократия, а страховка.

Если уже есть микросервис поставщиков и свой WMS — начните со soft-reserve: это короткий change, сразу видны плюсы review, и спека потом переиспользуется в сборке, отменах и инвентаризациях.