数据角色与运行边界

MARS 不从变量名或日期自动猜测业务角色。每次调用都应明确当前分析数据、可选基准数据、target、 特征范围和分组方式。

当前数据与基准数据

df 是本次需要画像、评估、筛选或监控的数据。benchmark_df 是可选基准期样本：它不并入 当前期 Total，也不会作为新的趋势分组。

在分箱评估和监控中，分箱规则来源优先级为：

1. 显式传入的已拟合 binner。
2. benchmark_df。
3. 当前 df。

benchmark_df 同时提供 PSI 的 expected distribution。监督分箱要求拟合规则的数据中至少存在 两个有效 target 类别。

Target 表现状态

target 使用 0 / False 表示好样本，1 / True 表示坏样本，空值表示尚未表现。字符串形式的 "0"、"1" 或其他非空类别不会被自动转换。

当前期 target 缺列或全空时，可以保留 target 名称并提供带标签的 benchmark_df。MARS 使用基准期 拟合监督规则，同时将当前期按无标签模式输出分布指标。

分组列与日期列

参数	职责
group_col	现有月份、渠道、客群等业务分组，决定报告面板和趋势列
time_col	原始日期，是风险图时间范围和按日缺失趋势的数据来源
time_grain	未提供 group_col 时，根据 time_col 生成日、周、月或窗口分组
dataset_flag_col	Modeling 的 train/val/oot 样本切片，不等同于业务趋势分组

同时存在月份分组和原始日期时，应同时传入 group_col 与 time_col，不要用月份字符串代替真实 日期范围。

单次运行边界

构造对象只保存可复用策略；原始 df、benchmark_df 和本次列角色不会被长期保存。需要再次生成 依赖基准样本的报告时，应在新调用中重新传入基准数据。