{ "openapi": "3.1.0", "info": { "title": "api-gateway", "description": "", "license": { "name": "" }, "version": "0.1.0" }, "paths": { "/api/v1/analysis-results": { "get": { "tags": [ "api" ], "summary": "[GET /v1/analysis-results?symbol=...]", "operationId": "get_analysis_results_by_symbol", "parameters": [ { "name": "symbol", "in": "query", "description": "Optional symbol to filter results", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of analysis results", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AnalysisResultDto" } } } } } } } }, "/api/v1/analysis-results/{id}": { "get": { "tags": [ "api" ], "summary": "[GET /api/v1/analysis-results/:id]", "operationId": "get_analysis_result_by_id", "parameters": [ { "name": "id", "in": "path", "description": "Analysis result ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisResultDto" } } } }, "404": { "description": "Not found" } } } }, "/api/v1/configs/analysis_template_sets": { "get": { "tags": [ "api" ], "summary": "[GET /api/v1/configs/analysis_template_sets]", "operationId": "get_analysis_template_sets", "responses": { "200": { "description": "Analysis template sets configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisTemplateSets" } } } } } }, "put": { "tags": [ "api" ], "summary": "[PUT /api/v1/configs/analysis_template_sets]", "operationId": "update_analysis_template_sets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisTemplateSets" } } }, "required": true }, "responses": { "200": { "description": "Updated analysis template sets configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisTemplateSets" } } } } } } }, "/api/v1/configs/data_sources": { "get": { "tags": [ "api" ], "summary": "[GET /api/v1/configs/data_sources]", "operationId": "get_data_sources_config", "responses": { "200": { "description": "Data sources configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourcesConfig" } } } } } }, "put": { "tags": [ "api" ], "summary": "[PUT /api/v1/configs/data_sources]", "operationId": "update_data_sources_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourcesConfig" } } }, "required": true }, "responses": { "200": { "description": "Updated data sources configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourcesConfig" } } } } } } }, "/api/v1/configs/llm/test": { "post": { "tags": [ "api" ], "summary": "[POST /v1/configs/llm/test]", "operationId": "test_llm_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestLlmConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "LLM config test result (JSON)" } } } }, "/api/v1/configs/llm_providers": { "get": { "tags": [ "api" ], "summary": "[GET /api/v1/configs/llm_providers]", "operationId": "get_llm_providers_config", "responses": { "200": { "description": "LLM providers configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmProvidersConfig" } } } } } }, "put": { "tags": [ "api" ], "summary": "[PUT /api/v1/configs/llm_providers]", "operationId": "update_llm_providers_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmProvidersConfig" } } }, "required": true }, "responses": { "200": { "description": "Updated LLM providers configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmProvidersConfig" } } } } } } }, "/api/v1/configs/test": { "post": { "tags": [ "api" ], "summary": "[POST /api/v1/configs/test]\nForwards a configuration test request to the appropriate downstream service.", "operationId": "test_data_source_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "Configuration test result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestConnectionResponse" } } } } } } }, "/api/v1/discover-models": { "post": { "tags": [ "api" ], "summary": "[POST /api/v1/discover-models]\nPreview discovery without persisting provider configuration.", "operationId": "discover_models_preview", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverPreviewRequest" } } }, "required": true }, "responses": { "200": { "description": "Discovered models (JSON)" }, "502": { "description": "Provider error" } } } }, "/api/v1/discover-models/{provider_id}": { "get": { "tags": [ "api" ], "summary": "[GET /api/v1/discover-models/:provider_id]", "operationId": "discover_models", "parameters": [ { "name": "provider_id", "in": "path", "description": "Provider ID to discover models for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Discovered models (JSON)" }, "404": { "description": "Provider not found" }, "502": { "description": "Provider error" } } } }, "/api/v1/registry/providers": { "get": { "tags": [ "api" ], "summary": "[GET /api/v1/registry/providers]\nReturns metadata for all registered data providers.", "operationId": "get_registered_providers", "responses": { "200": { "description": "Registered providers metadata", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderMetadata" } } } } } } } }, "/api/v1/tools/resolve-symbol": { "post": { "tags": [ "api" ], "summary": "[POST /v1/tools/resolve-symbol]\nResolves and normalizes a symbol without starting a workflow.", "operationId": "resolve_symbol", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolResolveRequest" } } }, "required": true }, "responses": { "200": { "description": "Symbol resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolResolveResponse" } } } } } } }, "/api/v1/workflow/start": { "post": { "tags": [ "api" ], "summary": "[POST /v1/workflow/start]\nInitiates a new analysis workflow via the Orchestrator.", "operationId": "start_workflow", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRequest" } } }, "required": true }, "responses": { "202": { "description": "Workflow started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestAcceptedResponse" } } } } } } }, "/health": { "get": { "tags": [ "api" ], "operationId": "health_check", "responses": { "200": { "description": "Service healthy" } } } }, "/tasks/{request_id}": { "get": { "tags": [ "api" ], "summary": "[GET /v1/tasks/:request_id]\nAggregates task progress from all downstream provider services.", "operationId": "get_task_progress", "parameters": [ { "name": "request_id", "in": "path", "description": "Request ID to query tasks for", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Task progress list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaskProgress" } } } } }, "404": { "description": "Tasks not found" } } } } }, "components": { "schemas": { "AnalysisModuleConfig": { "type": "object", "required": [ "name", "dependencies", "context_selector", "analysis_prompt", "output_type" ], "properties": { "analysis_prompt": { "type": "string" }, "context_selector": { "$ref": "#/components/schemas/ContextSelectorConfig" }, "dependencies": { "type": "array", "items": { "type": "string" } }, "id": { "type": [ "string", "null" ] }, "llm_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmConfig" } ] }, "name": { "type": "string" }, "output_type": { "type": "string" } }, "additionalProperties": false }, "AnalysisResultDto": { "type": "object", "description": "Represents a persisted analysis result read from the database.", "required": [ "id", "request_id", "symbol", "template_id", "module_id", "content", "meta_data", "created_at" ], "properties": { "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "meta_data": { "$ref": "#/components/schemas/Value" }, "module_id": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" }, "symbol": { "type": "string" }, "template_id": { "type": "string" } }, "additionalProperties": false }, "AnalysisTemplateSet": { "type": "object", "description": "A single, self-contained set of analysis modules representing a complete workflow.\ne.g., \"Standard Fundamental Analysis\"", "required": [ "name", "modules" ], "properties": { "modules": { "type": "object", "description": "All analysis modules contained within this template set.\nKey: Module ID (e.g., \"fundamental_analysis\")", "additionalProperties": { "$ref": "#/components/schemas/AnalysisModuleConfig" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Human-readable name for the template set." } }, "additionalProperties": false }, "AnalysisTemplateSets": { "type": "object", "description": "Top-level configuration object for all analysis templates.\nKey: Template ID (e.g., \"standard_fundamentals\")", "additionalProperties": { "$ref": "#/components/schemas/AnalysisTemplateSet" }, "propertyNames": { "type": "string" } }, "CanonicalSymbol": { "type": "string", "description": "CanonicalSymbol 是系统内部唯一的股票代码标识符类型\n它封装了一个标准化的字符串（遵循 Yahoo Finance 格式）\n使用 newtype 模式防止与普通 String 混淆", "example": "600519.SS" }, "ConfigFieldSchema": { "type": "object", "description": "单个配置字段的定义", "required": [ "key", "label", "field_type", "required" ], "properties": { "default_value": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "field_type": { "$ref": "#/components/schemas/FieldType" }, "key": { "$ref": "#/components/schemas/ConfigKey" }, "label": { "type": "string" }, "options": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Options for 'Select' type" }, "placeholder": { "type": [ "string", "null" ] }, "required": { "type": "boolean" } }, "additionalProperties": false }, "ConfigKey": { "type": "string", "description": "配置键枚举 - 强类型定义所有可能的配置项", "enum": [ "ApiKey", "ApiToken", "ApiUrl", "BaseUrl", "SecretKey", "Username", "Password", "SandboxMode", "Region" ] }, "ContextSelectorConfig": { "allOf": [ { "$ref": "#/components/schemas/SelectionMode" } ] }, "DataRequest": { "type": "object", "required": [ "symbol", "template_id" ], "properties": { "market": { "type": [ "string", "null" ] }, "symbol": { "type": "string" }, "template_id": { "type": "string" } }, "additionalProperties": false }, "DataSourceConfig": { "type": "object", "required": [ "provider", "enabled" ], "properties": { "api_key": { "type": [ "string", "null" ] }, "api_url": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "provider": { "$ref": "#/components/schemas/DataSourceProvider" } }, "additionalProperties": false }, "DataSourceProvider": { "type": "string", "enum": [ "Tushare", "Finnhub", "Alphavantage", "Yfinance" ] }, "DataSourcesConfig": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataSourceConfig" }, "propertyNames": { "type": "string" } }, "DiscoverPreviewRequest": { "type": "object", "required": [ "api_base_url", "api_key" ], "properties": { "api_base_url": { "type": "string" }, "api_key": { "type": "string" } }, "additionalProperties": false }, "FieldType": { "type": "string", "description": "字段类型枚举", "enum": [ "Text", "Password", "Url", "Boolean", "Select" ] }, "HealthStatus": { "type": "object", "required": [ "module_id", "status", "version", "details" ], "properties": { "details": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "module_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/ServiceStatus" }, "version": { "type": "string" } }, "additionalProperties": false }, "LlmConfig": { "type": "object", "properties": { "max_tokens": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "model_id": { "type": [ "string", "null" ] }, "temperature": { "type": [ "number", "null" ], "format": "float" } }, "additionalProperties": false }, "LlmModel": { "type": "object", "required": [ "model_id", "is_active" ], "properties": { "is_active": { "type": "boolean" }, "model_id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "LlmProvider": { "type": "object", "required": [ "name", "api_base_url", "api_key", "models" ], "properties": { "api_base_url": { "type": "string" }, "api_key": { "type": "string" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/LlmModel" } }, "name": { "type": "string" } }, "additionalProperties": false }, "LlmProvidersConfig": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LlmProvider" }, "propertyNames": { "type": "string" } }, "ObservabilityTaskStatus": { "type": "string", "enum": [ "Queued", "InProgress", "Completed", "Failed" ] }, "ProviderMetadata": { "type": "object", "description": "服务元数据", "required": [ "id", "name_en", "name_cn", "description", "config_schema", "supports_test_connection" ], "properties": { "config_schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConfigFieldSchema" }, "description": "该服务需要的配置字段列表" }, "description": { "type": "string" }, "icon_url": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name_cn": { "type": "string" }, "name_en": { "type": "string" }, "supports_test_connection": { "type": "boolean", "description": "是否支持“测试连接”功能" } }, "additionalProperties": false }, "RequestAcceptedResponse": { "type": "object", "required": [ "request_id", "symbol", "market" ], "properties": { "market": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" }, "symbol": { "type": "string" } }, "additionalProperties": false }, "SelectionMode": { "oneOf": [ { "type": "object", "required": [ "Manual" ], "properties": { "Manual": { "type": "object", "required": [ "rules" ], "properties": { "rules": { "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "required": [ "Auto" ], "properties": { "Auto": { "type": "object", "properties": { "llm_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmConfig" } ] } } } } }, { "type": "object", "required": [ "Hybrid" ], "properties": { "Hybrid": { "type": "object", "required": [ "selection_prompt" ], "properties": { "llm_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LlmConfig" } ] }, "selection_prompt": { "type": "string" } } } } } ] }, "ServiceStatus": { "type": "string", "enum": [ "Ok", "Degraded", "Unhealthy" ] }, "StartWorkflowCommand": { "type": "object", "description": "Command to initiate a new workflow.\nPublished by: `api-gateway`\nConsumed by: `workflow-orchestrator`", "required": [ "request_id", "symbol", "market", "template_id" ], "properties": { "market": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" }, "symbol": { "$ref": "#/components/schemas/CanonicalSymbol" }, "template_id": { "type": "string" } }, "additionalProperties": false }, "SymbolResolveRequest": { "type": "object", "required": [ "symbol" ], "properties": { "market": { "type": [ "string", "null" ] }, "symbol": { "type": "string" } }, "additionalProperties": false }, "SymbolResolveResponse": { "type": "object", "required": [ "symbol", "market" ], "properties": { "market": { "type": "string" }, "symbol": { "type": "string" } }, "additionalProperties": false }, "TaskDependency": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "additionalProperties": false }, "TaskMetadata": { "type": "object", "description": "Metadata produced by a task execution.", "properties": { "execution_log_path": { "type": [ "string", "null" ], "description": "The execution trace log path" }, "output_path": { "type": [ "string", "null" ], "description": "The primary output file path (e.g. analysis report)" } }, "additionalProperties": false }, "TaskNode": { "type": "object", "required": [ "id", "name", "type", "initial_status" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "initial_status": { "$ref": "#/components/schemas/TaskStatus" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/TaskType" } }, "additionalProperties": false }, "TaskProgress": { "type": "object", "required": [ "request_id", "task_name", "status", "progress_percent", "details", "started_at" ], "properties": { "details": { "type": "string" }, "progress_percent": { "type": "integer", "format": "int32", "minimum": 0 }, "request_id": { "type": "string", "format": "uuid" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/ObservabilityTaskStatus" }, "task_name": { "type": "string" } }, "additionalProperties": false }, "TaskStatus": { "type": "string", "enum": [ "Pending", "Scheduled", "Running", "Completed", "Failed", "Skipped" ] }, "TaskType": { "type": "string", "enum": [ "DataFetch", "DataProcessing", "Analysis" ] }, "TestConfigRequest": { "type": "object", "required": [ "type", "data" ], "properties": { "data": {}, "type": { "type": "string" } }, "additionalProperties": false }, "TestConnectionResponse": { "type": "object", "required": [ "success", "message" ], "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } }, "additionalProperties": false }, "TestLlmConfigRequest": { "type": "object", "required": [ "api_base_url", "api_key", "model_id" ], "properties": { "api_base_url": { "type": "string" }, "api_key": { "type": "string" }, "model_id": { "type": "string" } }, "additionalProperties": false }, "Value": {}, "WorkflowDag": { "type": "object", "required": [ "nodes", "edges" ], "properties": { "edges": { "type": "array", "items": { "$ref": "#/components/schemas/TaskDependency" } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/TaskNode" } } }, "additionalProperties": false }, "WorkflowEvent": { "oneOf": [ { "type": "object", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "required": [ "timestamp", "task_graph" ], "properties": { "task_graph": { "$ref": "#/components/schemas/WorkflowDag" }, "timestamp": { "type": "integer", "format": "int64" } } }, "type": { "type": "string", "enum": [ "WorkflowStarted" ] } } }, { "type": "object", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "required": [ "task_id", "task_type", "status", "timestamp" ], "properties": { "input_commit": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "output_commit": { "type": [ "string", "null" ] }, "progress": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "task_id": { "type": "string" }, "task_type": { "$ref": "#/components/schemas/TaskType" }, "timestamp": { "type": "integer", "format": "int64" } } }, "type": { "type": "string", "enum": [ "TaskStateChanged" ] } } }, { "type": "object", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "required": [ "task_id", "content_delta", "index" ], "properties": { "content_delta": { "type": "string" }, "index": { "type": "integer", "format": "int32", "minimum": 0 }, "task_id": { "type": "string" } } }, "type": { "type": "string", "enum": [ "TaskStreamUpdate" ] } } }, { "type": "object", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "required": [ "task_id", "level", "message", "timestamp" ], "properties": { "level": { "type": "string" }, "message": { "type": "string" }, "task_id": { "type": "string" }, "timestamp": { "type": "integer", "format": "int64" } } }, "type": { "type": "string", "enum": [ "TaskLog" ] } } }, { "type": "object", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "required": [ "end_timestamp" ], "properties": { "end_timestamp": { "type": "integer", "format": "int64" }, "result_summary": {} } }, "type": { "type": "string", "enum": [ "WorkflowCompleted" ] } } }, { "type": "object", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "required": [ "reason", "is_fatal", "end_timestamp" ], "properties": { "end_timestamp": { "type": "integer", "format": "int64" }, "is_fatal": { "type": "boolean" }, "reason": { "type": "string" } } }, "type": { "type": "string", "enum": [ "WorkflowFailed" ] } } }, { "type": "object", "required": [ "payload", "type" ], "properties": { "payload": { "type": "object", "required": [ "timestamp", "task_graph", "tasks_status", "tasks_output", "tasks_metadata" ], "properties": { "task_graph": { "$ref": "#/components/schemas/WorkflowDag" }, "tasks_metadata": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TaskMetadata" }, "propertyNames": { "type": "string" } }, "tasks_output": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "propertyNames": { "type": "string" } }, "tasks_status": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TaskStatus" }, "propertyNames": { "type": "string" } }, "timestamp": { "type": "integer", "format": "int64" } } }, "type": { "type": "string", "enum": [ "WorkflowStateSnapshot" ] } } } ], "description": "Unified event stream for frontend consumption." } } }, "tags": [ { "name": "workflow", "description": "Workflow management endpoints" }, { "name": "config", "description": "Configuration management endpoints" }, { "name": "tools", "description": "Utility tools" }, { "name": "observability", "description": "System observability" } ] }