a.tolmachev
388 lines
8.7 KiB
Markdown
388 lines
8.7 KiB
Markdown
# Диаграммы
|
|
|
|
## 1. Назначение документа
|
|
|
|
Этот документ собирает диаграммы, которые фиксируют проект до начала разработки:
|
|
|
|
- компонентную структуру;
|
|
- связи между доменными сущностями;
|
|
- хранение данных в БД;
|
|
- основные runtime и admin-потоки.
|
|
|
|
Диаграммы даны в формате `Mermaid`, чтобы их можно было хранить прямо в репозитории и рендерить в Markdown-compatible tooling.
|
|
|
|
## 2. Компонентная диаграмма
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
UI[crank-ui]
|
|
ADMIN[admin-api]
|
|
MCP[mcp-server]
|
|
REG[crank-registry]
|
|
RUN[crank-runtime]
|
|
CORE[crank-core]
|
|
SCHEMA[crank-schema]
|
|
MAP[crank-mapping]
|
|
PROTO[crank-proto]
|
|
REST[adapter-rest]
|
|
GQL[adapter-graphql]
|
|
GRPC[adapter-grpc]
|
|
DB[(PostgreSQL)]
|
|
STORE[(Artifact Storage)]
|
|
|
|
UI --> ADMIN
|
|
MCP --> REG
|
|
MCP --> RUN
|
|
ADMIN --> REG
|
|
ADMIN --> RUN
|
|
ADMIN --> PROTO
|
|
|
|
REG --> DB
|
|
REG --> CORE
|
|
REG --> SCHEMA
|
|
REG --> MAP
|
|
|
|
RUN --> CORE
|
|
RUN --> SCHEMA
|
|
RUN --> MAP
|
|
RUN --> REST
|
|
RUN --> GQL
|
|
RUN --> GRPC
|
|
|
|
GRPC --> PROTO
|
|
PROTO --> STORE
|
|
ADMIN --> STORE
|
|
```
|
|
|
|
## 3. Диаграмма зависимостей crates
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
CORE[crank-core]
|
|
SCHEMA[crank-schema]
|
|
MAP[crank-mapping]
|
|
PROTO[crank-proto]
|
|
REG[crank-registry]
|
|
RUN[crank-runtime]
|
|
REST[crank-adapter-rest]
|
|
GQL[crank-adapter-graphql]
|
|
GRPC[crank-adapter-grpc]
|
|
ADMIN[apps/admin-api]
|
|
MCP[apps/mcp-server]
|
|
|
|
SCHEMA --> CORE
|
|
MAP --> CORE
|
|
PROTO --> CORE
|
|
PROTO --> SCHEMA
|
|
REG --> CORE
|
|
REG --> SCHEMA
|
|
REG --> MAP
|
|
REST --> CORE
|
|
GQL --> CORE
|
|
GRPC --> CORE
|
|
GRPC --> PROTO
|
|
RUN --> CORE
|
|
RUN --> SCHEMA
|
|
RUN --> MAP
|
|
RUN --> REST
|
|
RUN --> GQL
|
|
RUN --> GRPC
|
|
ADMIN --> CORE
|
|
ADMIN --> SCHEMA
|
|
ADMIN --> MAP
|
|
ADMIN --> PROTO
|
|
ADMIN --> REG
|
|
ADMIN --> RUN
|
|
MCP --> CORE
|
|
MCP --> REG
|
|
MCP --> RUN
|
|
```
|
|
|
|
## 4. Структурная диаграмма доменной модели
|
|
|
|
```mermaid
|
|
classDiagram
|
|
class Operation {
|
|
+id
|
|
+name
|
|
+display_name
|
|
+protocol
|
|
+status
|
|
+version
|
|
+target
|
|
+input_schema
|
|
+output_schema
|
|
+input_mapping
|
|
+output_mapping
|
|
+execution_config
|
|
+tool_description
|
|
+samples
|
|
+generated_draft
|
|
+config_export
|
|
}
|
|
|
|
class RestTarget {
|
|
+base_url
|
|
+method
|
|
+path_template
|
|
+static_headers
|
|
}
|
|
|
|
class GraphqlTarget {
|
|
+endpoint
|
|
+operation_type
|
|
+operation_name
|
|
+query_template
|
|
+response_path
|
|
}
|
|
|
|
class GrpcTarget {
|
|
+server_addr
|
|
+package
|
|
+service
|
|
+method
|
|
+descriptor_ref
|
|
+descriptor_set_b64
|
|
}
|
|
|
|
class Schema {
|
|
+type
|
|
+description
|
|
+fields
|
|
}
|
|
|
|
class MappingSet {
|
|
+rules[]
|
|
}
|
|
|
|
class MappingRule {
|
|
+source
|
|
+target
|
|
+required
|
|
+default_value
|
|
+transform
|
|
+condition
|
|
}
|
|
|
|
class ExecutionConfig {
|
|
+timeout_ms
|
|
+retry_policy
|
|
+auth_profile_ref
|
|
+headers
|
|
+protocol_options
|
|
}
|
|
|
|
class AuthProfile {
|
|
+id
|
|
+name
|
|
+kind
|
|
+config
|
|
}
|
|
|
|
class ToolDescription {
|
|
+title
|
|
+description
|
|
+tags
|
|
+examples
|
|
}
|
|
|
|
class Samples {
|
|
+input_json_sample_ref
|
|
+output_json_sample_ref
|
|
+proto_file_ref
|
|
+descriptor_ref
|
|
}
|
|
|
|
class GeneratedDraft {
|
|
+status
|
|
+source_types
|
|
+generated_at
|
|
+warnings
|
|
}
|
|
|
|
Operation --> RestTarget : target
|
|
Operation --> GraphqlTarget : target
|
|
Operation --> GrpcTarget : target
|
|
Operation --> Schema : input_schema
|
|
Operation --> Schema : output_schema
|
|
Operation --> MappingSet : input_mapping
|
|
Operation --> MappingSet : output_mapping
|
|
Operation --> ExecutionConfig : execution_config
|
|
Operation --> ToolDescription : tool_description
|
|
Operation --> Samples : samples
|
|
Operation --> GeneratedDraft : generated_draft
|
|
ExecutionConfig --> AuthProfile : auth_profile_ref
|
|
MappingSet --> MappingRule : contains
|
|
```
|
|
|
|
## 5. ER-диаграмма БД
|
|
|
|
```mermaid
|
|
erDiagram
|
|
OPERATIONS ||--o{ OPERATION_VERSIONS : has
|
|
OPERATIONS ||--o| PUBLISHED_OPERATIONS : publishes
|
|
OPERATIONS ||--o{ OPERATION_SAMPLES : owns
|
|
OPERATIONS ||--o{ DESCRIPTORS : may_use
|
|
OPERATIONS ||--o{ YAML_IMPORT_JOBS : may_create
|
|
AUTH_PROFILES ||--o{ OPERATION_VERSIONS : referenced_by
|
|
|
|
OPERATIONS {
|
|
text id PK
|
|
text name
|
|
text display_name
|
|
text protocol
|
|
text status
|
|
int current_draft_version
|
|
int latest_published_version
|
|
timestamptz created_at
|
|
timestamptz updated_at
|
|
timestamptz published_at
|
|
}
|
|
|
|
OPERATION_VERSIONS {
|
|
text operation_id FK
|
|
int version
|
|
text status
|
|
jsonb target_json
|
|
jsonb input_schema_json
|
|
jsonb output_schema_json
|
|
jsonb input_mapping_json
|
|
jsonb output_mapping_json
|
|
jsonb execution_config_json
|
|
jsonb tool_description_json
|
|
jsonb samples_json
|
|
jsonb generated_draft_json
|
|
jsonb config_export_json
|
|
timestamptz created_at
|
|
}
|
|
|
|
PUBLISHED_OPERATIONS {
|
|
text operation_id PK
|
|
int version
|
|
timestamptz published_at
|
|
text published_by
|
|
}
|
|
|
|
OPERATION_SAMPLES {
|
|
text id PK
|
|
text operation_id FK
|
|
int version
|
|
text sample_kind
|
|
text storage_ref
|
|
text content_type
|
|
text file_name
|
|
timestamptz created_at
|
|
}
|
|
|
|
DESCRIPTORS {
|
|
text id PK
|
|
text operation_id FK
|
|
int version
|
|
text descriptor_kind
|
|
text storage_ref
|
|
jsonb package_index_json
|
|
timestamptz created_at
|
|
}
|
|
|
|
YAML_IMPORT_JOBS {
|
|
text id PK
|
|
text source_sample_id
|
|
text status
|
|
text format_version
|
|
text mode
|
|
text result_operation_id
|
|
int result_version
|
|
text error_text
|
|
timestamptz created_at
|
|
timestamptz finished_at
|
|
}
|
|
|
|
AUTH_PROFILES {
|
|
text id PK
|
|
text name
|
|
text kind
|
|
jsonb config_json
|
|
timestamptz created_at
|
|
timestamptz updated_at
|
|
}
|
|
```
|
|
|
|
## 6. Sequence: создание и публикация operation
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant UI
|
|
participant API as admin-api
|
|
participant REG as registry
|
|
participant RUN as runtime
|
|
participant MCP as mcp-server
|
|
|
|
UI->>API: POST /operations
|
|
API->>REG: create operation v1
|
|
REG-->>API: created
|
|
API-->>UI: operation_id, version
|
|
|
|
UI->>API: upload samples / descriptors
|
|
API-->>UI: artifact refs
|
|
|
|
UI->>API: POST /drafts/generate
|
|
API->>REG: save generated draft metadata
|
|
API-->>UI: generated draft
|
|
|
|
UI->>API: POST /test-runs
|
|
API->>RUN: execute draft version
|
|
RUN-->>API: request_preview + response_preview
|
|
API-->>UI: test result
|
|
|
|
UI->>API: POST /publish
|
|
API->>REG: mark version as published
|
|
REG-->>API: published
|
|
API-->>MCP: reload signal
|
|
API-->>UI: published_version
|
|
```
|
|
|
|
## 7. Sequence: MCP tool execution
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as MCP Client
|
|
participant MCP as mcp-server
|
|
participant REG as registry/cache
|
|
participant RUN as runtime
|
|
participant ADP as protocol adapter
|
|
|
|
Client->>MCP: call tool(name, input)
|
|
MCP->>REG: resolve published runtime view
|
|
REG-->>MCP: runtime operation
|
|
MCP->>RUN: execute(operation, input)
|
|
RUN->>RUN: validate input schema
|
|
RUN->>RUN: apply input mapping
|
|
RUN->>ADP: execute prepared request
|
|
ADP-->>RUN: normalized response
|
|
RUN->>RUN: apply output mapping
|
|
RUN-->>MCP: output
|
|
MCP-->>Client: tool result
|
|
```
|
|
|
|
## 8. Sequence: YAML import
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant UI
|
|
participant API as admin-api
|
|
participant REG as registry
|
|
|
|
UI->>API: POST /operations/import (YAML)
|
|
API->>API: parse YAML
|
|
API->>API: validate schema, target, mapping
|
|
API->>REG: create or upsert new version
|
|
REG-->>API: operation_id, version
|
|
API-->>UI: import result
|
|
```
|
|
|
|
## 9. Что важно помнить
|
|
|
|
- Диаграммы фиксируют целевую архитектуру, а не точную реализацию каждого файла.
|
|
- Если меняется модель данных или поток исполнения, сначала нужно обновлять документы, потом код.
|
|
- Для старта разработки этого набора достаточно: компоненты, сущности, БД и ключевые sequence flows уже описаны.
|