openapi: 3.0.3
info:
  title: Volatrade Indicator API
  version: 1.0.0
  description: |
    Volatrade 指标查询 API，由 `svc-indicatorsignal-bridge` 提供。

    用于替代 indicatorSignal 项目的 26 个分类指标 HTTP 接口。
    数据来源为 `svc-feature-materializer` 实时计算的 257 个 feature，
    通过 NATS `feature.values.*` 主题订阅并维护内存快照。

    主要用途：
    - 查询所有可用指标分类
    - 按分类查询所有交易对的指标值
    - 按交易对查询所有分类的指标值
servers:
  - url: /
    description: Current deployment root (proxied via nginx)
tags:
  - name: indicators
    description: 技术指标查询接口（26 个分类，覆盖 257 个 feature）
paths:
  /api/v1/indicators/categories:
    get:
      tags:
        - indicators
      summary: 获取所有指标分类
      description: |
        返回 26 个指标分类的元数据列表。

        每个分类包含名称、中文显示名和字段数量。
      operationId: listIndicatorCategories
      responses:
        "200":
          description: 分类列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CategoryMeta"
              examples:
                success:
                  summary: 返回分类列表
                  value:
                    - name: moving-averages
                      display_name: "均线与位置"
                      field_count: 20
                    - name: trend-strength
                      display_name: "趋势与强度"
                      field_count: 14
                    - name: momentum-strength
                      display_name: "动量强弱"
                      field_count: 13
  /api/v1/indicators/category/{category}:
    get:
      tags:
        - indicators
      summary: 按分类查询所有交易对的指标值
      description: |
        返回指定分类下所有 symbol 的最新指标值。

        可用分类名：
        `moving-averages`, `trend-strength`, `channel-breakout`, `linreg-quality`,
        `drawdown-structure`, `momentum-returns`, `momentum-strength`, `momentum-turning`,
        `momentum-accel`, `cross-sectional-momentum`, `atr`, `realized-volatility`,
        `bollinger`, `vol-of-vol`, `tail-jump`, `volume-strength`, `vwap-deviation`,
        `taker-intensity`, `volume-composite`, `leverage-crowding`, `liquidation-flow`,
        `mid-spread`, `depth`, `orderbook-imbalance`, `slippage-impact`, `effective-spread`
      operationId: getIndicatorCategory
      parameters:
        - name: category
          in: path
          required: true
          description: 指标分类名称（URL 安全格式）
          schema:
            type: string
            example: momentum-strength
      responses:
        "200":
          description: 该分类下所有 symbol 的指标值
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CategoryResult"
              examples:
                success:
                  summary: 返回 momentum-strength 分类数据
                  value:
                    - symbol: BTCUSDT
                      category: momentum-strength
                      updated_at_ms: 1744684800000
                      indicators:
                        rsi_14_5m: 55.3
                        rsi_14_15m: 52.1
                        rsi_14_1h: 48.7
                        rsi_14_4h: 51.2
                        rsi_14_1d: 49.8
                        stoch_k_14_1h: 65.2
                        stoch_k_14_4h: 58.9
                        stoch_k_14_1d: 42.1
                        cci_20_1h: 23.5
                        cci_20_4h: -15.8
                        cci_20_1d: 8.3
                        willr_14_1h: -34.8
                        willr_14_4h: -41.1
        "400":
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: 未知的分类名称
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                unknownCategory:
                  summary: 分类不存在
                  value:
                    error: unknown category
  /api/v1/indicators/symbol/{symbol}:
    get:
      tags:
        - indicators
      summary: 按交易对查询所有分类的指标值
      description: |
        返回指定交易对在所有 26 个分类中的最新指标值。

        symbol 格式为 Binance 标准格式，如 `BTCUSDT`、`ETHUSDT`。
      operationId: getSymbolIndicators
      parameters:
        - name: symbol
          in: path
          required: true
          description: |
            交易对标识。

            常见示例：
            - `BTCUSDT`
            - `ETHUSDT`
          schema:
            type: string
            example: BTCUSDT
      responses:
        "200":
          description: 该交易对的所有分类指标值
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/CategoryResult"
              examples:
                success:
                  summary: 返回 BTCUSDT 的所有指标
                  value:
                    moving-averages:
                      symbol: BTCUSDT
                      category: moving-averages
                      updated_at_ms: 1744684800000
                      indicators:
                        price_to_ema200_pct_1h: 125.3
                        ema20_ema50_spread_pct_1h: 45.2
                        ema20_gt_ema50_flag_1h: 1.0
                    momentum-strength:
                      symbol: BTCUSDT
                      category: momentum-strength
                      updated_at_ms: 1744684800000
                      indicators:
                        rsi_14_1h: 55.3
                        stoch_k_14_1h: 65.2
        "400":
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: 交易对不存在或暂无数据
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                notFound:
                  summary: 交易对暂无数据
                  value:
                    error: symbol not found
components:
  schemas:
    CategoryMeta:
      type: object
      description: 指标分类元数据
      required:
        - name
        - display_name
        - field_count
      properties:
        name:
          type: string
          description: 分类名称（URL 安全格式）
          example: momentum-strength
        display_name:
          type: string
          description: 分类中文显示名
          example: "动量强弱"
        field_count:
          type: integer
          description: 该分类包含的指标字段数量
          example: 13
    CategoryResult:
      type: object
      description: 单个交易对在某分类下的指标值
      required:
        - symbol
        - category
        - updated_at_ms
        - indicators
      properties:
        symbol:
          type: string
          description: 交易对标识
          example: BTCUSDT
        category:
          type: string
          description: 分类名称
          example: momentum-strength
        updated_at_ms:
          type: integer
          format: int64
          description: 最近更新时间，Unix 毫秒时间戳
          example: 1744684800000
        indicators:
          type: object
          description: |
            指标名到值的映射。

            value 为 `null` 时表示该指标尚未计算或数据不足。
            value 为数值时表示最新的计算结果。
          additionalProperties:
            type: number
            format: double
            nullable: true
          example:
            rsi_14_1h: 55.3
            rsi_14_4h: 51.2
            stoch_k_14_1h: 65.2
            cci_20_1h: null
    ErrorResponse:
      type: object
      description: 错误响应
      required:
        - error
      properties:
        error:
          type: string
          description: 错误信息
          example: unknown category
