a.tolmachev
290 lines
5.3 KiB
Markdown
290 lines
5.3 KiB
Markdown
# Схема БД
|
|
|
|
## 1. Назначение документа
|
|
|
|
Этот документ фиксирует целевую структуру хранения workspace-scoped конфигураций, агентов, ключей доступа и observability-данных. Базовая СУБД - `PostgreSQL`.
|
|
|
|
## 2. Общие принципы хранения
|
|
|
|
### 2.1. Версионирование обязательно
|
|
|
|
Конфигурация operation и agent не хранится только в одной "живой" записи. Каждое существенное изменение создает новую версию.
|
|
|
|
### 2.2. Published и draft разделяются логически
|
|
|
|
- `draft` может меняться;
|
|
- `published` всегда указывает на конкретную version;
|
|
- runtime читает только опубликованные представления.
|
|
|
|
### 2.3. Workspace scoping обязателен
|
|
|
|
Все продуктовые таблицы должны ссылаться на `workspaces`.
|
|
|
|
### 2.4. Артефакты и конфигурация не смешиваются
|
|
|
|
`.proto`, descriptor set, sample JSON и YAML payload не хранятся в тех же строках, что runtime-ready configuration.
|
|
|
|
### 2.5. Секреты не хранятся в открытом виде
|
|
|
|
- upstream secrets живут за `secret_ref`;
|
|
- platform API keys хранятся как hash.
|
|
|
|
## 3. Основные таблицы
|
|
|
|
- `workspaces`
|
|
- `users`
|
|
- `memberships`
|
|
- `invitation_tokens`
|
|
- `operations`
|
|
- `operation_versions`
|
|
- `published_operations`
|
|
- `operation_samples`
|
|
- `descriptors`
|
|
- `auth_profiles`
|
|
- `agents`
|
|
- `agent_versions`
|
|
- `agent_operation_bindings`
|
|
- `published_agents`
|
|
- `platform_api_keys`
|
|
- `invocation_logs`
|
|
- `usage_rollups`
|
|
- `yaml_import_jobs`
|
|
|
|
## 4. Operations
|
|
|
|
### `operations`
|
|
|
|
- `id`
|
|
- `workspace_id`
|
|
- `name`
|
|
- `display_name`
|
|
- `protocol`
|
|
- `status`
|
|
- `current_draft_version`
|
|
- `latest_published_version`
|
|
- `created_at`
|
|
- `updated_at`
|
|
- `published_at`
|
|
|
|
Ограничение:
|
|
|
|
- `unique (workspace_id, name)`
|
|
|
|
### `operation_versions`
|
|
|
|
- `operation_id`
|
|
- `version`
|
|
- `status`
|
|
- `target_json`
|
|
- `input_schema_json`
|
|
- `output_schema_json`
|
|
- `input_mapping_json`
|
|
- `output_mapping_json`
|
|
- `execution_config_json`
|
|
- `tool_description_json`
|
|
- `samples_json`
|
|
- `generated_draft_json`
|
|
- `config_export_json`
|
|
- `change_note`
|
|
- `created_at`
|
|
- `created_by`
|
|
|
|
### `published_operations`
|
|
|
|
- `operation_id`
|
|
- `version`
|
|
- `published_at`
|
|
- `published_by`
|
|
|
|
## 5. Operation artifacts
|
|
|
|
### `operation_samples`
|
|
|
|
- `id`
|
|
- `operation_id`
|
|
- `version`
|
|
- `sample_kind`
|
|
- `storage_ref`
|
|
- `content_type`
|
|
- `file_name`
|
|
- `created_at`
|
|
|
|
### `descriptors`
|
|
|
|
- `id`
|
|
- `operation_id`
|
|
- `version`
|
|
- `descriptor_kind`
|
|
- `storage_ref`
|
|
- `source_name`
|
|
- `package_index_json`
|
|
- `created_at`
|
|
|
|
### `yaml_import_jobs`
|
|
|
|
- `id`
|
|
- `source_sample_id`
|
|
- `status`
|
|
- `format_version`
|
|
- `mode`
|
|
- `result_operation_id`
|
|
- `result_version`
|
|
- `error_text`
|
|
- `created_at`
|
|
- `finished_at`
|
|
|
|
## 6. Upstream auth
|
|
|
|
### `auth_profiles`
|
|
|
|
- `id`
|
|
- `workspace_id`
|
|
- `name`
|
|
- `kind`
|
|
- `config_json`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
Ограничение:
|
|
|
|
- `unique (workspace_id, name)`
|
|
|
|
## 7. Workspaces and access layer
|
|
|
|
### `workspaces`
|
|
|
|
- `id`
|
|
- `slug`
|
|
- `display_name`
|
|
- `status`
|
|
- `settings_json`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
### `users`
|
|
|
|
- `id`
|
|
- `email`
|
|
- `display_name`
|
|
- `status`
|
|
- `created_at`
|
|
|
|
### `memberships`
|
|
|
|
- `workspace_id`
|
|
- `user_id`
|
|
- `role`
|
|
- `created_at`
|
|
|
|
### `invitation_tokens`
|
|
|
|
- `id`
|
|
- `workspace_id`
|
|
- `email`
|
|
- `role`
|
|
- `status`
|
|
- `token_hash`
|
|
- `expires_at`
|
|
- `created_at`
|
|
|
|
## 8. Agents
|
|
|
|
### `agents`
|
|
|
|
- `id`
|
|
- `workspace_id`
|
|
- `slug`
|
|
- `display_name`
|
|
- `description`
|
|
- `status`
|
|
- `current_draft_version`
|
|
- `latest_published_version`
|
|
- `created_at`
|
|
- `updated_at`
|
|
- `published_at`
|
|
|
|
Ограничение:
|
|
|
|
- `unique (workspace_id, slug)`
|
|
|
|
### `agent_versions`
|
|
|
|
- `agent_id`
|
|
- `version`
|
|
- `status`
|
|
- `instructions_json`
|
|
- `tool_selection_policy_json`
|
|
- `created_at`
|
|
|
|
### `agent_operation_bindings`
|
|
|
|
- `agent_id`
|
|
- `agent_version`
|
|
- `operation_id`
|
|
- `operation_version`
|
|
- `tool_name`
|
|
- `tool_title`
|
|
- `tool_description_override`
|
|
- `enabled`
|
|
|
|
### `published_agents`
|
|
|
|
- `agent_id`
|
|
- `version`
|
|
- `published_at`
|
|
- `published_by`
|
|
|
|
## 9. Platform access and observability
|
|
|
|
### `platform_api_keys`
|
|
|
|
- `id`
|
|
- `workspace_id`
|
|
- `name`
|
|
- `prefix`
|
|
- `secret_hash`
|
|
- `scopes_json`
|
|
- `status`
|
|
- `created_at`
|
|
- `last_used_at`
|
|
|
|
### `invocation_logs`
|
|
|
|
- `id`
|
|
- `workspace_id`
|
|
- `agent_id`
|
|
- `operation_id`
|
|
- `request_id`
|
|
- `level`
|
|
- `status`
|
|
- `duration_ms`
|
|
- `error_kind`
|
|
- `request_preview_json`
|
|
- `response_preview_json`
|
|
- `created_at`
|
|
|
|
### `usage_rollups`
|
|
|
|
- `workspace_id`
|
|
- `agent_id`
|
|
- `operation_id`
|
|
- `period_kind`
|
|
- `period_start`
|
|
- `calls_total`
|
|
- `calls_ok`
|
|
- `calls_error`
|
|
- `p50_ms`
|
|
- `p95_ms`
|
|
- `p99_ms`
|
|
|
|
## 10. Migration strategy
|
|
|
|
Переход от текущей схемы к целевой идет так:
|
|
|
|
1. добавить `workspaces` и заполнить default workspace;
|
|
2. добавить `workspace_id` в `operations` и `auth_profiles`;
|
|
3. добавить `agents` и `published_agents`;
|
|
4. внедрить `platform_api_keys`;
|
|
5. добавить `invocation_logs` и `usage_rollups`;
|
|
6. перевести MCP runtime на `published_agents`, а не на глобальный список operations.
|