package jnpf.audit;

import jnpf.audit.fallback.AuditEventApiFallbackFactory;
import jnpf.audit.model.AuditEventDTO;
import jnpf.base.ActionResult;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

/**
 * 审计事件投递 Feign 接口：业务服务通过它把审计事件同步投递给 jnpf-audit。
 * path 走内部接收前缀 /Internal/audit（不经网关白名单暴露，见 AuditInternalController）。
 */
@FeignClient(name = AuditFeignName.AUDIT_SERVER_NAME, path = "/Internal/audit",
             fallbackFactory = AuditEventApiFallbackFactory.class)
public interface AuditEventApi {
    /**
     * 投递一条审计事件。
     *
     * <p><b>调用方契约（Task 7 SDK 的实施依据）</b>：调用方必须校验返回值：
     * {@code result == null || !ActionResultCode.SUCCESS.getCode().equals(result.getCode())}
     * 视为投递失败，抛 {@link jnpf.audit.AuditDeliveryException}（L013：成功码用平台常量
     * {@code jnpf.base.ActionResultCode.SUCCESS.getCode()} 判定，禁止硬编码 200）。
     * HTTP 层失败（网络/超时/服务不可用）由 {@link AuditEventApiFallbackFactory} 抛出；
     * 业务层失败（HTTP 200 + fail body，如落库校验不通过）必须靠本校验捕获——平台全局异常
     * 处理器会把服务端异常包装成 HTTP 200 的 {@code ActionResult.fail}，Feign 对非 void
     * 返回值同样不会因此抛异常，只有显式校验 code 才能感知。
     */
    @PostMapping("/events")
    ActionResult<Integer> record(@RequestBody AuditEventDTO dto);
}