Template
Рефакторинг схемы
This commit is contained in:
@@ -0,0 +1,35 @@
|
||||
# Паттерн FR: таблица базы данных
|
||||
|
||||
Применяй паттерн, когда FR описывает структуру таблицы БД, а не SQL-команду её создания.
|
||||
|
||||
## Формат
|
||||
|
||||
Используй заголовок вида `<requirement-id>.FR-NN [DB]: Таблица хранения <имя>` и назови таблицу и схему приложения перед таблицей полей.
|
||||
|
||||
Таблицу полей оформляй с колонками в этом порядке:
|
||||
|
||||
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
|
||||
| --- | --- | --- | --- |
|
||||
| `field_name` | `TYPE` | NULL или NOT NULL; при наличии DEFAULT укажи значение | Короткое назначение поля |
|
||||
|
||||
Одна строка описывает одно поле. Указывай точный тип, nullability, default и ограничения, которые влияют на хранение или чтение данных. Называй назначение каждого поля. Не используй `—` или пустые ячейки вместо явного `NULL`, `NOT NULL` или отсутствия default.
|
||||
|
||||
После таблицы перечисляй только ограничения таблицы, которых нет в строках: первичный и внешние ключи, уникальность, индексы, порядок выборки и владение данными. Не дублируй значения по умолчанию или назначение полей. Пиши DDL только если конкретный контракт невозможно выразить этой таблицей.
|
||||
|
||||
## Пример
|
||||
|
||||
```markdown
|
||||
##### AREA.CAP-01.FR-01 [DB]: Таблица хранения записей
|
||||
|
||||
Таблица `example_records` создаётся в схеме приложения и содержит:
|
||||
|
||||
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
|
||||
| --- | --- | --- | --- |
|
||||
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки |
|
||||
| `external_id` | `VARCHAR(64)` | NOT NULL | Идентификатор записи во внешней системе |
|
||||
| `status` | `VARCHAR(32)` | NOT NULL | Текущее состояние записи |
|
||||
| `created_at` | `TIMESTAMP` | NOT NULL | Время создания записи |
|
||||
| `updated_at` | `TIMESTAMP` | NULL | Время последнего изменения записи |
|
||||
|
||||
Индекс поддерживает выборку по `external_id` и `status`. Ограничение уникальности на `external_id` устанавливается, если внешняя система гарантирует его уникальность.
|
||||
```
|
||||
@@ -0,0 +1,57 @@
|
||||
# Паттерн сериализуемого контракта
|
||||
|
||||
Используй паттерн для полей сериализуемых request/response-контрактов.
|
||||
Для HTTP endpoint таблицы находятся в разделах Request и Response блока
|
||||
CONTRACT. Для асинхронного сообщения или технического лога контракт остаётся
|
||||
в типизированном FR [API].
|
||||
|
||||
## HTTP endpoint
|
||||
|
||||
Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные
|
||||
правила обработки указываются в FR, а контракт помещается в самом конце
|
||||
Requirement:
|
||||
|
||||
```markdown
|
||||
#### CONTRACT
|
||||
|
||||
##### Request
|
||||
|
||||
Метод: `POST`; путь: `/resource`. Для endpoint без тела явно укажи отсутствие тела.
|
||||
|
||||
##### Response
|
||||
|
||||
HTTP status: `200` при успешном выполнении.
|
||||
|
||||
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `field_name` | `JSON type` | Обязательное | Формат и допустимые значения | Короткое назначение поля | Источник или правило вычисления значения |
|
||||
```
|
||||
|
||||
Тело запроса при наличии описывай таблицей с пятью колонками:
|
||||
|
||||
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `field_name` | `JSON type` | Обязательное или опциональное | Формат, допустимые значения, nullable/default или явное отсутствие дополнительных ограничений и значений по умолчанию | Короткое назначение поля |
|
||||
|
||||
Для response используй эти же колонки и добавь последней «Формирование
|
||||
значения», чтобы для каждого поля указать источник значения или правило его
|
||||
вычисления.
|
||||
|
||||
Одна строка описывает одно поле. Указывай JSON-тип, а не тип языка реализации.
|
||||
Для вложенных полей используй путь из имён полей; для массивов указывай тип
|
||||
элемента. Обязательность задаёт наличие поля, а ограничения — nullability,
|
||||
формат, допустимые значения и default. Условие присутствия опционального поля
|
||||
укажи в ограничениях. Если дополнительных ограничений или значения по
|
||||
умолчанию нет, укажи это явно. Не оставляй ячейки пустыми и не используй тире.
|
||||
|
||||
Не создавай отдельные FR для HTTP request/response-контрактов. Не добавляй
|
||||
таблицу для отсутствующего тела запроса.
|
||||
|
||||
## Сообщение или технический лог в FR [API]
|
||||
|
||||
Заголовок FR: `<requirement-id>.FR-NN [API]: Контракт сообщения <имя>` либо
|
||||
Контракт запроса / Контракт ответа. Сразу после заголовка укажи
|
||||
`Тип контракта: request` для отправляемых данных или
|
||||
`Тип контракта: response` для возвращаемых данных. Для отправляемого сообщения
|
||||
используй request. Один FR описывает одно направление и содержит одну таблицу
|
||||
по формату выше.
|
||||
Reference in New Issue
Block a user