案例 15：银行卡交易反欺诈

本案例对应 JQuick-Java 仓库 USE-CASES.md 中的场景 15，面向实时风控领域的银行卡支付反欺诈。系统对每笔交易快照从金额、短时频次、地理位置、交易时段、设备、商户、无卡交易、鉴权失败、行为偏离/新账户九个风险维度独立计分，汇总后输出风险分并决定拦截（BLOCK）、强验证（STEP_UP，短信/人脸）或放行（PASS）；受信商户白名单在评分前短路放行，中风险境外交易与高风险交易实时预警，全部计分与路由口径由 JQuick-Java 的 XML 规则代理驱动。

行业场景

银行卡支付链路要求毫秒级风控决策。授权请求带来交易流水号、脱敏卡号、金额、交易小时（0-23）、渠道（POS / ATM / ONLINE / MOBILE）、是否境外/跨城市/报备出行、近 1 小时交易笔数与累计金额、是否新商户、是否更换设备、是否有卡交易、近 24 小时鉴权失败次数、账户开立天数、历史单笔最大金额，以及商户是否受信（白名单）。

决策入口首先是白名单短路：受信商户（trustedMerchant）交易直接给出 0 分、LOW、PASS，指标明细只留一条「受信商户白名单交易，直接放行」，九维评分完全不执行，保障水电缴费、大型平台等可信收款方的成功率与响应时延。

非白名单交易进入九维独立评分：金额按 ≥5 万/2 万/1 万/5 千给 30/20/12/6；频次维度先按 1 小时 ≥10/≥5/≥3 笔给 25/15/8，再叠加短时累计金额 ≥10 万/5 万的 +15/+8，维度内封顶 25；地理位置境外 25、异地未报备 15、已报备出行仅 5；时段 23 时-5 时 12 分、22 时与 6 时 6 分；设备变更 15；新商户 8；线上/移动无卡 10；24 小时鉴权失败 ≥3 次 10、≥1 次 5；行为偏离维度对金额达历史 5 倍/3 倍加 15/8，开户不足 7 天再 +15。

九维汇总后由 Service clamp 到 0-100，再映射风险等级与处置：≥75 为 HIGH 拦截，≥45 为 MEDIUM 强验证（短信/人脸），其余 LOW 放行。预警规则与处置并行：HIGH 必预警，MEDIUM 且境外交易预警。决策结果还携带按交易要素逐条组装的风险指标明细（境外交易、深夜时段、设备变更、无卡交易、金额偏离历史等），供风控后台核查与客服解释使用。

业务痛点

风险因子多且口径变化快：九个维度各自有金额档、笔数档、时段边界，风控运营调阈值频繁，硬编码在授权服务里每次调参都要走核心系统发版。
白名单必须最先执行且零误伤：受信商户交易即使夜间、无卡也应放行，若白名单判断混在评分之后，会叠加出高分误拦截，影响大客户交易成功率。
多维分数叠加易超过理论上限：九维满分之和超过 100，深夜境外大额用例原始分 126，不在 Java 侧 clamp 就会出现 126 分这类非法分值，等级阈值也随之失真。
倍数比较存在浮点误差隐患：金额偏离历史 3 倍/5 倍若用 amount / historicalMax >= 5.0 浮点比较，边界值可能因精度抖动错档。
频次维度是复合计分还要内部封顶：笔数档与短时累计金额档要相加，但维度贡献不能超过 25，这种「分档叠加 + 维度封顶」用普通配置表难以表达。
预警与处置是两条规则线且要求可审计：中风险境外要预警但中风险境内不强提醒，每笔拦截/强验证都必须能列出命中的风险指标；不少银行核心与支付网控仍在 JDK 8、信创环境，无法依赖重型实时规则平台。

方案架构

本案例采用「入参模型 + 决策结果模型 + 规则接口 + XML 规则脚本 + Service 编排 + JUnit 测试」六件套结构，九维计分、等级阈值、处置动作、预警口径全部外置在 XML 中，Service 负责白名单短路、总分 clamp 与风险指标明细组装：

层次	职责	对应文件
领域模型	交易快照、风控决策（风险分/等级/处置/预警/指标明细）	BankTransaction.java、FraudDecision.java
规则集与 XML	九维风险因子 + 等级/处置/预警（12 个方法）	TransactionFraudRules.java、transaction-fraud.xml
编排服务	白名单短路、九维汇总 0-100 clamp、风险指标明细组装	TransactionFraudService.java
测试	6 组交易形态（日常、高危、报备、强验证、新账户、白名单）	TransactionFraudServiceTest.java

规则方法拆分

规则接口共 12 个方法，九个风险因子各自独立计分，等级、处置、预警顺序路由：

规则方法	口径	分值/输出
`scoreAmount`	金额 ≥50000 给 30 / ≥20000 给 20 / ≥10000 给 12 / ≥5000 给 6 / 否则 0	0 ~ 30
`scoreVelocity`	1 小时笔数 ≥10/≥5/≥3 给 25/15/8；累计金额 ≥10 万 +15、≥5 万 +8；维度内封顶 25	0 ~ 25
`scoreGeo`	境外 25；异地且未报备（travelMode == false）15；异地已报备 5；同城 0	0 ~ 25
`scoreTime`	小时 ≥23 或 `<5` 给 12；≥22 或 ≤6 给 6；其余 0	0 ~ 12
`scoreDevice`	设备变更给 15，否则 0	0 / 15
`scoreMerchant`	新商户首笔给 8，否则 0	0 / 8
`scoreCardNotPresent`	无卡且渠道为 ONLINE 或 MOBILE 给 10，否则 0	0 / 10
`scoreFailure`	24h 鉴权失败 ≥3 次给 10 / ≥1 次给 5 / 否则 0	0 ~ 10
`scoreDeviation`	历史最大 >0 时，金额达 5 倍给 15、达 3 倍给 8（交叉相乘比较）；开户 `<7` 天再 +15	0 ~ 30
`riskLevel`	≥75 HIGH / ≥45 MEDIUM / 其余 LOW	等级字符串
`fraudAction`	HIGH→BLOCK；MEDIUM→STEP_UP；LOW→PASS	处置字符串
`needAlert`	HIGH 必预警；MEDIUM 且境外交易预警；其余不预警	boolean

代码实现（完整可运行）

将以下六个文件按源码原包名放入 JQuick-Java 的测试工程：两个模型放在 com.github.paohaijiao.demo.model，规则接口与测试类放在 com.github.paohaijiao.demo，编排服务放在 com.github.paohaijiao.demo.service，XML 脚本放入 src/test/resources/demo/。保持目录与包名不变后，在工程根目录执行 mvn test -Dtest=TransactionFraudServiceTest 即可运行。

BankTransaction.java

package com.github.paohaijiao.demo.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * 银行卡交易要素（实时风控所需的交易快照）
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class BankTransaction {

    /**
     * 交易流水号
     */
    private String txnNo;

    /**
     * 银行卡号（脱敏）
     */
    private String cardNo;

    /**
     * 交易金额
     */
    private double amount;

    /**
     * 交易小时（0-23）
     */
    private int txnHour;

    /**
     * 交易渠道：POS / ATM / ONLINE / MOBILE
     */
    private String channel;

    /**
     * 是否境外交易
     */
    private boolean overseas;

    /**
     * 是否跨城市交易
     */
    private boolean crossCity;

    /**
     * 是否报备出行模式
     */
    private boolean travelMode;

    /**
     * 近 1 小时交易笔数
     */
    private int txnCount1h;

    /**
     * 近 1 小时累计交易金额
     */
    private double txnAmount1h;

    /**
     * 是否新商户
     */
    private boolean newMerchant;

    /**
     * 是否更换设备
     */
    private boolean deviceChanged;

    /**
     * 是否有卡交易（刷卡/插卡）
     */
    private boolean cardPresent;

    /**
     * 近 24 小时鉴权失败次数
     */
    private int failCount24h;

    /**
     * 账户开立天数
     */
    private int accountAgeDays;

    /**
     * 历史单笔最大金额
     */
    private double historicalMaxAmount;

    /**
     * 是否受信商户（白名单）
     */
    private boolean trustedMerchant;
}

FraudDecision.java

package com.github.paohaijiao.demo.model;

import lombok.Data;

import java.util.ArrayList;
import java.util.List;

/**
 * 银行卡交易风控决策结果
 */
@Data
public class FraudDecision {

    /**
     * 交易流水号
     */
    private String txnNo;

    /**
     * 风险分（0-100）
     */
    private int riskScore;

    /**
     * 风险等级：HIGH / MEDIUM / LOW
     */
    private String riskLevel;

    /**
     * 处置动作：BLOCK-拦截 / STEP_UP-强验证 / PASS-放行
     */
    private String action;

    /**
     * 是否实时预警
     */
    private boolean needAlert;

    /**
     * 命中风险指标
     */
    private List<String> indicators = new ArrayList<String>();

    public void addIndicator(String indicator) {
        this.indicators.add(indicator);
    }
}

TransactionFraudRules.java

package com.github.paohaijiao.demo;

import com.github.paohaijiao.xml.param.Param;

/**
 * 场景 15：银行卡交易反欺诈规则集
 * <p>
 * 九维风险因子独立计分，汇总后决定拦截、强验证或放行：
 * 金额、频次、地理位置、时段、设备、商户、无卡交易、鉴权失败、行为偏离与新账户。
 * 规则脚本见 {@code src/test/resources/demo/transaction-fraud.xml}。
 */
public interface TransactionFraudRules {

    int scoreAmount(@Param("amount") double amount);

    int scoreVelocity(@Param("txnCount1h") int txnCount1h,
                      @Param("txnAmount1h") double txnAmount1h);

    int scoreGeo(@Param("overseas") boolean overseas,
                 @Param("crossCity") boolean crossCity,
                 @Param("travelMode") boolean travelMode);

    int scoreTime(@Param("txnHour") int txnHour);

    int scoreDevice(@Param("deviceChanged") boolean deviceChanged);

    int scoreMerchant(@Param("newMerchant") boolean newMerchant);

    int scoreCardNotPresent(@Param("cardNotPresent") boolean cardNotPresent,
                            @Param("channel") String channel);

    int scoreFailure(@Param("failCount24h") int failCount24h);

    int scoreDeviation(@Param("amount") double amount,
                       @Param("historicalMaxAmount") double historicalMaxAmount,
                       @Param("accountAgeDays") int accountAgeDays);

    String riskLevel(@Param("riskScore") int riskScore);

    String fraudAction(@Param("riskLevel") String riskLevel);

    boolean needAlert(@Param("riskLevel") String riskLevel,
                      @Param("overseas") boolean overseas);
}

ransaction-fraud.xml

class="header">

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE javas PUBLIC "-//PAOHAIJIAO//DTD API JAVA 1.0//EN"
        "classpath:paohaijiao/dtd/Jquick-java.dtd">
<javas namespace="com.github.paohaijiao.demo.TransactionFraudRules">
 <!-- 单笔金额评分 -->
    <java name="scoreAmount" returnClass="int">
        <![CDATA[
            int def scoreAmount(double:amount) {
                if (amount >= 50000.0) {
                    return 30;
                } else if (amount >= 20000.0) {
                    return 20;
                } else if (amount >= 10000.0) {
                    return 12;
                } else if (amount >= 5000.0) {
                    return 6;
                } else {
                    return 0;
                }
            }
        ]]>
    </java>
 <!-- 交易频次评分：笔数档位 + 短时累计金额，封顶 25 -->
    <java name="scoreVelocity" returnClass="int">
        <![CDATA[
            int def scoreVelocity(int:txnCount1h, double:txnAmount1h) {
                int score = 0;
                if (txnCount1h >= 10) {
                    score = 25;
                } else if (txnCount1h >= 5) {
                    score = 15;
                } else if (txnCount1h >= 3) {
                    score = 8;
                }
                if (txnAmount1h >= 100000.0) {
                    score = score + 15;
                } else if (txnAmount1h >= 50000.0) {
                    score = score + 8;
                }
                if (score > 25) {
                    score = 25;
                }
                return score;
            }
        ]]>
    </java>
 <!-- 地理位置评分：境外 25，异地未报备 15，报备出行 5 -->
    <java name="scoreGeo" returnClass="int">
        <![CDATA[
            int def scoreGeo(boolean:overseas, boolean:crossCity, boolean:travelMode) {
                if (overseas) {
                    return 25;
                } else if (crossCity && travelMode == false) {
                    return 15;
                } else if (crossCity) {
                    return 5;
                } else {
                    return 0;
                }
            }
        ]]>
    </java>
 <!-- 交易时段评分：深夜 12，夜间 6 -->
    <java name="scoreTime" returnClass="int">
        <![CDATA[
            int def scoreTime(int:txnHour) {
                if (txnHour >= 23 || txnHour < 5) {
                    return 12;
                } else if (txnHour >= 22 || txnHour <= 6) {
                    return 6;
                } else {
                    return 0;
                }
            }
        ]]>
    </java>
 <!-- 设备更换评分 -->
    <java name="scoreDevice" returnClass="int">
        <![CDATA[
            int def scoreDevice(boolean:deviceChanged) {
                if (deviceChanged) {
                    return 15;
                } else {
                    return 0;
                }
            }
        ]]>
    </java>
 <!-- 新商户评分 -->
    <java name="scoreMerchant" returnClass="int">
        <![CDATA[
            int def scoreMerchant(boolean:newMerchant) {
                if (newMerchant) {
                    return 8;
                } else {
                    return 0;
                }
            }
        ]]>
    </java>
 <!-- 无卡交易评分：线上/移动端且无卡现场景加 10 -->
    <java name="scoreCardNotPresent" returnClass="int">
        <![CDATA[
            int def scoreCardNotPresent(boolean:cardNotPresent, str:channel) {
                if (cardNotPresent && (channel == "ONLINE" || channel == "MOBILE")) {
                    return 10;
                } else {
                    return 0;
                }
            }
        ]]>
    </java>
 <!-- 鉴权失败评分 -->
    <java name="scoreFailure" returnClass="int">
        <![CDATA[
            int def scoreFailure(int:failCount24h) {
                if (failCount24h >= 3) {
                    return 10;
                } else if (failCount24h >= 1) {
                    return 5;
                } else {
                    return 0;
                }
            }
        ]]>
    </java>
 <!-- 行为偏离与新账户评分：金额偏离历史 3 倍/5 倍，开户不足 7 天加 15 -->
    <java name="scoreDeviation" returnClass="int">
        <![CDATA[
            int def scoreDeviation(double:amount, double:historicalMaxAmount, int:accountAgeDays) {
                int score = 0;
                if (historicalMaxAmount > 0.0) {
                    if (amount * 10 >= historicalMaxAmount * 50) {
                        score = 15;
                    } else if (amount * 10 >= historicalMaxAmount * 30) {
                        score = 8;
                    }
                }
                if (accountAgeDays < 7) {
                    score = score + 15;
                }
                return score;
            }
        ]]>
    </java>
 <!-- 风险等级 -->
    <java name="riskLevel" returnClass="java.lang.String">
        <![CDATA[
            str def riskLevel(int:riskScore) {
                if (riskScore >= 75) {
                    return "HIGH";
                } else if (riskScore >= 45) {
                    return "MEDIUM";
                } else {
                    return "LOW";
                }
            }
        ]]>
    </java>
 <!-- 处置动作 -->
    <java name="fraudAction" returnClass="java.lang.String">
        <![CDATA[
            str def fraudAction(str:riskLevel) {
                if (riskLevel == "HIGH") {
                    return "BLOCK";
                } else if (riskLevel == "MEDIUM") {
                    return "STEP_UP";
                } else {
                    return "PASS";
                }
            }
        ]]>
    </java>
 <!-- 实时预警：高风险必预警，中风险境外交易预警 -->
    <java name="needAlert" returnClass="boolean">
        <![CDATA[
            boolean def needAlert(str:riskLevel, boolean:overseas) {
                if (riskLevel == "HIGH") {
                    return true;
                } else if (riskLevel == "MEDIUM" && overseas) {
                    return true;
                } else {
                    return false;
                }
            }
        ]]>
    </java>
 style="--0:#7FDBCA"></javas>

java">TransactionFraudService.java