tasks: задачи спринта раздроблены до восьми гранулярных
- конверт и точки разложены на форму провода, точки за период и условный запрос; свёртка — на сетку, порог неполного ведра и предел размера ответа; тренировки и записи разъехались на два независимых маршрута - openapi-swagger разложена на спеку, гейт против расхождения и Swagger UI — все три вне набора, вместе с mcp-server - набор спринта 2026-08-04 — весь HTTP-слой чтения, восемь задач
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# Рукописная OpenAPI-спека
|
||||
|
||||
- **Секция:** ядро
|
||||
- **Зачем:** Потребителей три и один из них агент — контракт должен читаться машиной, а не пересказываться в чате
|
||||
- **Теги:** goal:read-api, sprint:2026-08-04
|
||||
|
||||
Контракт читается машиной: по спеке генерируется клиент, и сгенерированный
|
||||
клиент выполняет запрос к живому сервису.
|
||||
|
||||
**Решено владельцем 2026-08-04: спека пишется руками и она источник истины.**
|
||||
Для API из горстки ручек это честнее вывода из кода — контракт проектируется, а
|
||||
не фотографируется с того, что вышло: опечатка в имени поля иначе становится
|
||||
частью спеки. Совпадает с тем, как в проекте уже устроен OpenSpec: спека
|
||||
первична к коду. Плата названа — рукописная спека расходится с кодом молча, — и
|
||||
именно поэтому проверка расхождения вынесена в
|
||||
[отдельную задачу](openapi-gate-check.md), а не оставлена регламентом.
|
||||
|
||||
Заодно снимает вопрос, чем быть «схеме контракта API» из раздела самоописания:
|
||||
ею и будет OpenAPI-документ, а не собственный формат.
|
||||
|
||||
## Критерии приёмки
|
||||
|
||||
- по спеке генерируется клиент, и он выполняет запрос к живому сервису — оракул:
|
||||
прогон генератора плюс запрос сгенерированным клиентом
|
||||
- спека покрывает все существующие маршруты: приём, каталог, точки, тренировки,
|
||||
записи — оракул: сверка перечня путей спеки с таблицей маршрутов в
|
||||
`docs/architecture.md`
|
||||
- спека проходит валидатор OpenAPI 3.1 — оракул: прогон валидатора
|
||||
|
||||
## Рамки
|
||||
|
||||
Кода маршрутов не трогает: описывает то, что уже есть. `/stats` не описывается —
|
||||
его ещё нет, и его добавит [своя задача](stats-endpoint.md).
|
||||
Reference in New Issue
Block a user