2. 需求分析：因子评分接口的功能需求、非功能需求、接口契约定义

因子评分接口是量化策略从研究走向实盘的关键桥梁。需求分析阶段需要明确接口做什么（功能需求）、做到什么程度（非功能需求），以及如何约定交互（接口契约）。本章从这三个维度展开，为后续的架构设计与编码实现奠定基础。

2.1 功能需求

功能需求描述接口必须提供的业务能力。因子评分接口的核心职责是：接收一组因子数据，输出每个标的的综合评分及排序。具体功能点如下：

2.2 非功能需求

非功能需求定义了接口的质量属性。对于低延迟评分接口，延迟和吞吐量是最核心的约束条件。

2.2.1 延迟需求

延迟指从请求发出到收到完整响应的时间间隔。量化交易场景下，延迟直接影响策略的时效性和收益。

2.2.2 吞吐量需求

吞吐量指单位时间内接口能处理的请求数量。高吞吐量意味着系统能支撑更大的策略规模和更密集的调用频率。

2.3 接口契约定义

接口契约是前后端、服务间协作的法律文件。本接口采用 RESTful 风格，使用 JSON 作为数据交换格式，通过 OpenAPI 3.0 规范进行描述。

2.3.1 核心端点

POST /api/v1/factor/score
Content-Type: application/json
Accept: application/json

2.3.2 请求体结构

{
  "symbols": ["600519.SH", "000858.SZ", "601318.SH"],
  "factors": {
    "pe_ttm": [25.3, 18.7, 12.1],
    "roe": [0.21, 0.15, 0.18],
    "momentum_20d": [0.035, -0.012, 0.028]
  },
  "weights": {
    "pe_ttm": 0.3,
    "roe": 0.4,
    "momentum_20d": 0.3
  },
  "options": {
    "normalize": "zscore",
    "clip_min": -3.0,
    "clip_max": 3.0,
    "use_cache": true
  }
}

2.3.3 响应体结构

{
  "code": 0,
  "message": "success",
  "data": {
    "scores": [
      {
        "symbol": "600519.SH",
        "total_score": 0.872,
        "sub_scores": {
          "pe_ttm": 0.65,
          "roe": 0.92,
          "momentum_20d": 0.78
        },
        "rank": 1,
        "warnings": []
      },
      {
        "symbol": "000858.SZ",
        "total_score": 0.534,
        "sub_scores": {
          "pe_ttm": 0.42,
          "roe": 0.55,
          "momentum_20d": 0.61
        },
        "rank": 2,
        "warnings": ["factor_pe_ttm_outlier"]
      }
    ],
    "meta": {
      "computation_time_ms": 2.3,
      "cache_hit": false,
      "normalized": true
    }
  }
}

2.3.4 错误码定义

2.4 需求分析总结：接口调用流程

下图展示了从客户端发起请求到最终返回评分的完整流程，涵盖了功能需求与非功能需求的落地位置。

2.5 需求优先级矩阵

综合功能需求与非功能需求，按业务价值和实现成本两个维度进行优先级排序，指导迭代计划。