218 lines
8.7 KiB
Markdown
218 lines
8.7 KiB
Markdown
# Forensic Analysis: API Model to Ordinary YAML
|
|
|
|
## Цель
|
|
|
|
Исследовать существующую цепочку:
|
|
|
|
```text
|
|
API model
|
|
↓
|
|
ordinary generator
|
|
↓
|
|
API YAML
|
|
```
|
|
|
|
Цель этапа — получить подтверждённую картину движения данных и установить, что сохраняется, преобразуется или теряется до формирования API YAML.
|
|
|
|
Этот документ предназначен для передачи Opus перед анализом.
|
|
|
|
## Строгие ограничения
|
|
|
|
На этом этапе запрещено:
|
|
|
|
- изменять файлы;
|
|
- писать код;
|
|
- менять ordinary generator;
|
|
- проектировать `ModifierSpec`;
|
|
- проектировать `modifiers.yaml`;
|
|
- проектировать `delete_rule`;
|
|
- проектировать output layout или orchestration;
|
|
- обсуждать inverse и dependency ordering;
|
|
- придумывать API identifiers;
|
|
- придумывать `parameter_path`;
|
|
- придумывать HTTP method или payload structure;
|
|
- считать API YAML полным источником данных без доказательства.
|
|
|
|
Если факт невозможно установить, его нужно обозначить как `unknown` или как требующий проверки фактическим API. Нельзя закрывать неизвестность архитектурным предположением.
|
|
|
|
## Что исследовать
|
|
|
|
### 1. Исходная API-модель
|
|
|
|
Установить:
|
|
|
|
- где находится canonical API model;
|
|
- в каком формате она представлена;
|
|
- как представлены services и operations;
|
|
- как представлены параметры;
|
|
- как представлены nested objects и arrays;
|
|
- как представлены типы параметров;
|
|
- существует ли стабильный operation ID;
|
|
- существует ли стабильный parameter ID;
|
|
- какие данные доступны до запуска ordinary generator.
|
|
|
|
### 2. Ordinary generator
|
|
|
|
Установить:
|
|
|
|
- какой input получает generator;
|
|
- где он читает API-модель;
|
|
- какие внутренние структуры строит;
|
|
- какие преобразования выполняет;
|
|
- какие поля нормализует или переименовывает;
|
|
- какие поля вычисляет;
|
|
- какие поля отбрасывает;
|
|
- где формируется API YAML;
|
|
- где именно могут происходить потери данных.
|
|
|
|
Обязательно различать:
|
|
|
|
```text
|
|
данные отсутствуют уже в API
|
|
```
|
|
|
|
и:
|
|
|
|
```text
|
|
данные присутствуют в API, но теряются ordinary generator
|
|
```
|
|
|
|
### 3. API YAML
|
|
|
|
Установить:
|
|
|
|
- какие поля сохраняются;
|
|
- какие поля представлены иначе, чем в API-модели;
|
|
- сохраняются ли nested objects и arrays;
|
|
- сохраняются ли типы;
|
|
- сохраняются ли operation identity и parameter identity;
|
|
- сохраняются ли HTTP method и path, если они есть в исходной модели;
|
|
- какие данные доступны будущему modifier layer;
|
|
- какие данные потенциально доступны только в исходной API-модели.
|
|
|
|
## Обязательные трассировки
|
|
|
|
### `vc_org`
|
|
|
|
Отдельно проследить `vIPConfigure` и `count`:
|
|
|
|
```text
|
|
API model
|
|
→ generator input
|
|
→ internal generator representation
|
|
→ generator transformation
|
|
→ API YAML
|
|
```
|
|
|
|
Для каждого этапа указать:
|
|
|
|
- присутствует ли `vIPConfigure`;
|
|
- присутствует ли `count`;
|
|
- в каком типе они представлены;
|
|
- в какой структуре находятся;
|
|
- изменяются ли их имена или типы;
|
|
- теряются ли они;
|
|
- если теряются, в какой точке.
|
|
|
|
Не считать заранее известной структуру `vIPConfigure` или `count`.
|
|
|
|
### `vc_nsxt`
|
|
|
|
Отдельно проследить `ipSpaceName` и связанные параметры по той же цепочке:
|
|
|
|
```text
|
|
API model
|
|
→ generator input
|
|
→ internal generator representation
|
|
→ generator transformation
|
|
→ API YAML
|
|
```
|
|
|
|
Установить:
|
|
|
|
- где появляется `ipSpaceName`;
|
|
- к какой operation или структуре он относится;
|
|
- в каком типе представлен;
|
|
- является ли обычным полем, nested field или частью массива;
|
|
- какие связанные параметры находятся рядом;
|
|
- сохраняется ли он в API YAML;
|
|
- изменяются ли его значение или тип;
|
|
- теряются ли связанные поля.
|
|
|
|
## Требования к доказательности
|
|
|
|
Каждый вывод разделять на:
|
|
|
|
- **Подтверждённый факт** — непосредственно виден из кода, структуры данных, фактического API input, generator input или API YAML.
|
|
- **Неизвестное** — информация отсутствует или неоднозначна.
|
|
- **Предположение** — не использовать как основание для архитектуры; только явно перечислять как неподтверждённое.
|
|
|
|
Для каждого важного вывода указывать конкретное основание: файл, функцию, структуру, входной документ или фрагмент YAML/JSON. Если точное место невозможно назвать, это указать как ограничение анализа.
|
|
|
|
## Формат итогового отчёта
|
|
|
|
Отчёт должен содержать только следующие разделы:
|
|
|
|
1. **Подтверждённые факты**
|
|
2. **Исходная API-модель**
|
|
3. **Как ordinary generator читает модель**
|
|
4. **Как формируется API YAML**
|
|
5. **Цепочка данных для `vc_org.vIPConfigure.count`**
|
|
6. **Цепочка данных для `vc_nsxt.ipSpaceName` и связанных параметров**
|
|
7. **Что сохраняется**
|
|
8. **Что преобразуется или нормализуется**
|
|
9. **Что теряется**
|
|
10. **Где происходят потери**
|
|
11. **Какие данные доступны в API YAML**
|
|
12. **Какие данные доступны только в API-модели**
|
|
13. **Неизвестные места**
|
|
14. **Что необходимо проверить фактическим API**
|
|
|
|
## Критерий завершения
|
|
|
|
Forensic analysis завершён только тогда, когда для каждого потенциально необходимого modifier-элемента можно проследить происхождение:
|
|
|
|
```text
|
|
API model
|
|
→ generator input
|
|
→ internal representation
|
|
→ transformation
|
|
→ API YAML
|
|
```
|
|
|
|
без неизвестных промежуточных преобразований.
|
|
|
|
Для `vc_org` и `vc_nsxt` должны быть подтверждены:
|
|
|
|
```text
|
|
operation identity
|
|
parameter identity
|
|
parameter structure
|
|
parameter type
|
|
API model representation
|
|
generator representation
|
|
YAML representation
|
|
transformation
|
|
loss or absence
|
|
```
|
|
|
|
Если на существенном этапе остаётся `???`, исследование не завершено. Этот пункт нужно зафиксировать как `unknown`, а не проектировать решение.
|
|
|
|
## Главный принцип
|
|
|
|
Сначала:
|
|
|
|
```text
|
|
исследовать
|
|
↓
|
|
зафиксировать факты
|
|
↓
|
|
зафиксировать неизвестное
|
|
↓
|
|
отличить отсутствие данных от потери данных
|
|
```
|
|
|
|
Только после отдельного согласования forensic report можно переходить к проектированию `ModifierSpec`, `modifiers.yaml`, `delete_rule`, modifier generator, output boundary и orchestration.
|
|
|
|
На текущем этапе никаких решений по этим компонентам принимать нельзя.
|