基金组合风险如何避免“一个分数说风险”，关键不是完成一次调用，而是让输入口径、处理状态和结果证据可以复核。本文围绕“如何校验基金持仓权重和历史样本，并解释组合波动、回撤、VaR 与风险贡献”给出一套面向真实业务流程的实现方式。

问题与结果

组合指标与数据质量同时展示，不可用基金、样本不足和陈旧数据不会被一个总分掩盖。

适用场景

• 基金组合风险看板
• 资产配置复盘
• 历史风险和分散度分析

实现前先确定边界

1. 基金代码以字符串保存，避免丢失前导零
2. 权重和误差必须在请求前校验
3. AnalysisStatus、CoverageRatio 和 NoDataReasons 与指标同等重要

请求前先验证组合

持仓数量、基金代码、权重、分析周期和置信水平应在客户端先校验。基金代码可先通过 基金信息列表核对，并始终保持六位字符串；权重全部大于零且总和满足接口允许误差。

from math import isclose

def validate_positions(positions: list[dict]) -> None:
    if not 2 <= len(positions) <= 10:
        raise ValueError("positions must contain 2 to 10 funds")
    codes = [item["FundCode"] for item in positions]
    if len(codes) != len(set(codes)):
        raise ValueError("fund codes must be unique")
    if not all(isinstance(code, str) and len(code) == 6 and code.isdigit() for code in codes):
        raise ValueError("fund codes must be six-digit strings")
    if not all(item["Weight"] > 0 for item in positions):
        raise ValueError("weights must be positive")
    if not isclose(sum(item["Weight"] for item in positions), 1.0, abs_tol=1e-6):
        raise ValueError("weights must sum to one")

调用与结果读取

curl -X POST "https://api.gugudata.com/ai/fund/portfolio-risk-analyses" \
  -H "Authorization: Bearer YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{"Positions":[{"FundCode":"012729","Weight":0.6},{"FundCode":"110022","Weight":0.4}],"Period":"1Y","ConfidenceLevel":0.95}'

基金组合风险分析的 基金组合风险分析的 基金组合风险分析的 HTTP 和业务状态成功后，仍需检查 Data.AnalysisStatus。报告同时展示样本区间、观察数、覆盖率、最新数据年龄和警告，再展示波动、最大回撤、VaR、CVaR、相关性和风险贡献。

任务状态与失败处理

生产接入至少区分 INPUT_INVALID、PENDING、RUNNING、SUCCEEDED、PARTIALLY_FAILED 和 FAILED。状态名称可以按业务调整，但不能把“任务已创建”“请求 HTTP 成功”和“结果可用”合并成一个成功状态。

参数错误应直接返回给调用方；频率或额度限制停止当前批次并保留下一次可执行条件；依赖服务失败可以进入有上限的退避重试；业务结果缺失、覆盖不足或引用不足则进入人工复核。每次尝试记录请求标识、开始和结束时间、业务状态、失败原因以及是否产生可用结果。

还应为重试设置幂等键和最大次数。相同输入、相同规则版本和相同业务目标不能因为网络超时重复写入多个正式结果；超过重试上限后保留最后错误和人工处理入口。

运行记录与回归检查

上线前保存一组脱敏固定样本，用于比较接口或规则升级前后的字段结构、状态流转和关键结果。回归测试不追求结果文本逐字一致，而是检查必填字段、来源证据、错误分类和能力边界是否稳定。

对于本文场景，重点回归以下约束：

• 基金代码以字符串保存，避免丢失前导零
• 权重和误差必须在请求前校验
• AnalysisStatus、CoverageRatio 和 NoDataReasons 与指标同等重要

监控指标至少包括成功结果数、失败数、处理中任务数、人工复核数和数据新鲜度。任何未采样指标都应显示“未采样”，不能默认为零。

数据契约与留痕

重试应新增尝试记录，不覆盖最后一次失败。派生结果必须关联输入版本、生成时间和业务状态。

验收清单

• 权重之和符合接口约束
• 组合指标使用全部基金的公共日期
• 不可计算指标显示 null 和原因而不是零

能力边界

历史风险指标描述过去样本，不预测未来收益，也不构成投资建议或资产配置结论。

示例中的 YOUR_APPKEY 仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中。