cfc/cfc-backend/src/main/java/com/etotem/cfc/service/AttributionAnalysisService.java

package com.etotem.cfc.service;

import com.etotem.cfc.dto.AttributionInput;
import com.etotem.cfc.dto.AttributionReportVO;

import java.util.Map;

/**
 * 家庭归因分析服务（B1）。
 *
 * <p>门面服务：内部 5 段确定性规则引擎（常模比对 → 指标解读 → 五维归因 → 主因链 → 被证伪）
 * + 1 段 AI 叙述（{@code AttributionNarrativeService}，失败规则兜底）。
 * 合规红线 RL01-RL10 由规则层硬注入，AI 不负责合规。
 *
 * @author 家庭归因阶段二（ATT-S2-B1）
 */
public interface AttributionAnalysisService {

    /**
     * 核心入口：档案 + 确认问卷 + 检测数据 + 常模 → 十节归因报告。
     *
     * @param input 归因入参
     * @return 归因报告视图（status=READY）
     */
    AttributionReportVO analyze(AttributionInput input);

    /**
     * 取报告（含十节结构）。
     *
     * @param attributionId 归因报告ID
     * @return 报告视图；不存在返回 null
     */
    AttributionReportVO getReport(Long attributionId);

    /**
     * ④调整后重算（B3 回填后调用；作废 ⑤ 由 AttributionPlanService 处理）。
     *
     * @param attributionId 归因报告ID
     * @param fieldDeltas   字段增量（回填后的中间态增量）
     * @return 重算后的报告视图；不存在返回 null
     */
    AttributionReportVO recompute(Long attributionId, Map<String, Object> fieldDeltas);
}