tea-tool 0.1.0__py3-none-any.whl

tea_tool/datetime/formatter.py

@@ -0,0 +1,40 @@
+"""日期时间 strftime/strptime 格式化模板常量。
+
+常量按粒度组织：DATE（日）、TIME（时间）、DATE_TIME（日期时间）、MONTH（月）与
+YEAR 系压缩串（%Y%m%d…，常用于文件名/键）。同一粒度提供连字符（默认）、斜杠
+（_SLASH）、中文（_CN）分隔变体；后缀 _ZONE 携带 %z 时区偏移、_ISO 为 ISO 8601
+扩展 T 分隔。注意：%f 恒为 6 位微秒且 strftime 不支持截宽，故含 %f 的模板按
+微秒（MICROSECOND）命名；%z 输出形如 +0800 无冒号（近似 RFC 3339，非严格）。
+"""
+
+# 日期
+DATE_FORMAT = "%Y-%m-%d"
+DATE_FORMAT_SLASH = "%Y/%m/%d"
+DATE_FORMAT_CN = "%Y年%m月%d日"
+
+# 时间
+TIME_FORMAT = "%H:%M:%S"
+TIME_FORMAT_MINUTE = "%H:%M"
+TIME_FORMAT_SLASH = "%H/%M/%S"
+TIME_FORMAT_CN = "%H时%M分%S秒"
+
+# 日期时间
+DATE_TIME_FORMAT = "%Y-%m-%d %H:%M:%S"
+DATE_TIME_FORMAT_SLASH = "%Y/%m/%d %H:%M:%S"
+DATE_TIME_FORMAT_CN = "%Y年%m月%d日 %H时%M分%S秒"
+DATE_TIME_MICROSECOND = "%Y-%m-%d %H:%M:%S.%f"
+DATE_TIME_ZONE = "%Y-%m-%d %H:%M:%S%z"
+DATE_TIME_ISO = "%Y-%m-%dT%H:%M:%S"
+DATE_TIME_ISO_ZONE = "%Y-%m-%dT%H:%M:%S%z"
+
+# 月
+MONTH_FORMAT = "%Y-%m"
+
+# 年份系压缩串（无分隔符，常用于文件名/键）
+YEAR = "%Y"
+YEAR_TO_MONTH = "%Y%m"
+YEAR_TO_DAY = "%Y%m%d"
+YEAR_TO_HOUR = "%Y%m%d%H"
+YEAR_TO_MINUTE = "%Y%m%d%H%M"
+YEAR_TO_SECOND = "%Y%m%d%H%M%S"
+YEAR_TO_MICROSECOND = "%Y%m%d%H%M%S.%f"

tea_tool/datetime/timezone.py

@@ -0,0 +1,58 @@
+"""常用时区常量与本地时区获取。
+
+常量覆盖 UTC 及主流业务城市的 IANA 时区（UTC-12 ~ UTC+14 各主要时区带），
+命名统一全大写、多词下划线分隔，可直接作为 tzinfo 参数传入 datetime 相关
+构造与 tea_tool.datetime.util 各函数。依赖 zoneinfo（Python 3.9+ 内置），
+具体时区数据取自已安装的 tzdata。
+"""
+
+from datetime import datetime, tzinfo
+from zoneinfo import ZoneInfo
+
+UTC = ZoneInfo("UTC")
+
+# 亚洲
+SHANGHAI = ZoneInfo("Asia/Shanghai")
+SINGAPORE = ZoneInfo("Asia/Singapore")
+TOKYO = ZoneInfo("Asia/Tokyo")
+SEOUL = ZoneInfo("Asia/Seoul")
+HONG_KONG = ZoneInfo("Asia/Hong_Kong")
+BANGKOK = ZoneInfo("Asia/Bangkok")
+DUBAI = ZoneInfo("Asia/Dubai")
+KOLKATA = ZoneInfo("Asia/Kolkata")
+
+# 欧洲
+LONDON = ZoneInfo("Europe/London")
+PARIS = ZoneInfo("Europe/Paris")
+BERLIN = ZoneInfo("Europe/Berlin")
+AMSTERDAM = ZoneInfo("Europe/Amsterdam")
+MOSCOW = ZoneInfo("Europe/Moscow")
+
+# 美洲
+NEW_YORK = ZoneInfo("America/New_York")
+LOS_ANGELES = ZoneInfo("America/Los_Angeles")
+CHICAGO = ZoneInfo("America/Chicago")
+TORONTO = ZoneInfo("America/Toronto")
+SAO_PAULO = ZoneInfo("America/Sao_Paulo")
+
+# 大洋洲
+SYDNEY = ZoneInfo("Australia/Sydney")
+AUCKLAND = ZoneInfo("Pacific/Auckland")
+
+# 非洲
+JOHANNESBURG = ZoneInfo("Africa/Johannesburg")
+
+
+def local_tz() -> tzinfo:
+    """返回系统本地时区。
+
+    本地时区取自运行环境（TZ 环境变量或系统设置），与 datetime.now().astimezone()
+    的时区归属一致；系统时区可被识别为具体区域时返回 ZoneInfo，否则退化为固定
+    偏移时区。
+
+    Returns:
+        当前系统本地时区对应的 tzinfo 对象。
+    """
+    local = datetime.now().astimezone().tzinfo
+    assert local is not None
+    return local

tea_tool/datetime/util.py

@@ -0,0 +1,194 @@
+"""datetime 日期时间通用工具。
+
+提供日历运算（月份首末日、逐日序列）与时刻获取（日零点、当日时间范围、
+本地/UTC 当前时间、字符串解析）。日历运算中的月份首末日与逐日序列
+（get_month_start、get_month_end、list_days）仅接受 date；get_days_in_month
+接受 date/datetime（仅用其年月）。时刻类函数（get_day_start、get_day_range、
+get_local_time、get_utc_time、parse_datetime）产出 datetime：date 输入按该日
+提升，datetime 输入保留 naive/aware 属性。时区语义：本模块只做钟面解释
+（attach），不做跨时区换算；"本地时区"指系统时区，可用 timezone.local_tz()
+获取。
+"""
+
+from calendar import monthrange
+from datetime import UTC, date, datetime, time, timedelta, tzinfo
+
+from .timezone import local_tz
+
+
+def _shift_year_month(value: date | datetime, months: int) -> tuple[int, int]:
+    """计算 value 所在月偏移 months 个月后的 (年, 月)。
+
+    months 为负时同样正确（divmod 对负值取整向负无穷），例如 2026-01 偏移 -1
+    得到 (2025, 12)。
+
+    Args:
+        value: 基准日期或时间，取其所在年与月。
+        months: 月份偏移量。
+
+    Returns:
+        偏移后的 (年, 月) 二元组。
+    """
+    total = value.year * 12 + (value.month - 1) + months
+    year, month_index = divmod(total, 12)
+    return year, month_index + 1
+
+
+def get_month_start(value: date | datetime, months: int = 0) -> date:
+    """返回 value 所在月偏移 months 个月后的首日。
+
+    months 为正表示偏移到之后的月份、为负表示之前的月份，0（默认）即 value 所在
+    当月。value 无论 date 还是 datetime 均统一返回 date（datetime 仅取其年与月，
+    不带时分秒与时区），例如 2026-01-31 10:30 偏移 1 个月返回 2026-02-01。
+
+    Args:
+        value: 基准日期或时间，取其所在月。
+        months: 月份偏移量，正为后负为前，默认当月。
+
+    Returns:
+        目标月首日（date）。
+    """
+    year, month = _shift_year_month(value, months)
+    return date(year, month, 1)
+
+
+def get_month_end(value: date | datetime, months: int = 0) -> date:
+    """返回 value 所在月偏移 months 个月后的末日。
+
+    月份偏移语义与 get_month_start 一致（正后负前，0 为当月）；返回目标月的最后
+    一天，跨月取末日不受 value 原日影响，例如 2026-01-31 偏移 1 个月返回
+    2026-02-28。value 无论 date 还是 datetime 均统一返回 date（datetime 仅取其
+    年与月，不带时分秒与时区）。
+
+    Args:
+        value: 基准日期或时间，取其所在月。
+        months: 月份偏移量，正为后负为前，默认当月。
+
+    Returns:
+        目标月末日（date）。
+    """
+    year, month = _shift_year_month(value, months)
+    last = monthrange(year, month)[1]
+    return date(year, month, last)
+
+
+def get_days_in_month(value: date | datetime) -> int:
+    """返回 value 所在月的天数。
+
+    Args:
+        value: 基准日期或时间，取其所在月。
+
+    Returns:
+        所在月的天数（平年 2 月为 28、闰年为 29）。
+    """
+    return monthrange(value.year, value.month)[1]
+
+
+def get_day_start(value: date | datetime) -> datetime:
+    """返回 value 所在日的零点时刻。
+
+    时刻域函数：date 输入提升为当日 00:00 的 naive datetime；naive datetime 清零
+    时分秒与微秒；aware datetime 清零时刻但保留其 tzinfo（DST 切换日零点通常无
+    歧义，不做 fold 处理）。
+
+    Args:
+        value: 基准日期或时间，取其所在日。
+
+    Returns:
+        所在日零点对应的 datetime（naive 或保留输入的 aware 属性）。
+    """
+    if isinstance(value, datetime):
+        return value.replace(hour=0, minute=0, second=0, microsecond=0)
+    return datetime.combine(value, time.min)
+
+
+def get_day_range(
+    value: date | datetime, tz: tzinfo | None = None
+) -> tuple[datetime, datetime]:
+    """返回 value 所在日的时间范围 [当日零点, 次日零点)，左闭右开。
+
+    时刻域函数，返回值恒为 datetime 对。时区规则：
+    - tz 显式给出时，两端钟面时间 attach 该时区（覆盖 value 自带时区，不换算）；
+    - tz 缺省且 value 为 aware datetime 时，沿用 value 的时区；
+    - 其余情形（date / naive datetime）两端为 naive。
+    DST 切换日该范围的实际时长可能非 24 小时，但两端恒为该时区钟面零点。
+
+    Args:
+        value: 基准日期或时间，取其所在日。
+        tz: 目标时区；缺省时沿用输入时区或保持 naive。
+
+    Returns:
+        (当日零点, 次日零点) 元组。
+    """
+    if isinstance(value, datetime):
+        day = value.date()
+        resolved = tz if tz is not None else value.tzinfo
+    else:
+        day = value
+        resolved = tz
+    return (
+        datetime.combine(day, time.min, tzinfo=resolved),
+        datetime.combine(day + timedelta(days=1), time.min, tzinfo=resolved),
+    )
+
+
+def list_days(start: date, end: date) -> list[date]:
+    """返回 [start, end) 区间内逐日 date 序列，左闭右开不含 end。
+
+    start 等于或晚于 end 时返回空列表。
+
+    Args:
+        start: 起始日期（含）。
+        end: 结束日期（不含）。
+
+    Returns:
+        逐日 date 序列；start >= end 时为空列表。
+    """
+    result: list[date] = []
+    cursor = start
+    while cursor < end:
+        result.append(cursor)
+        cursor += timedelta(days=1)
+    return result
+
+
+def get_local_time() -> datetime:
+    """返回系统本地时区的当前时刻（aware）。
+
+    Returns:
+        带系统本地时区的当前 datetime。
+    """
+    return datetime.now().astimezone()
+
+
+def get_utc_time() -> datetime:
+    """返回 UTC 的当前时刻（aware）。
+
+    Returns:
+        带 UTC 时区的当前 datetime。
+    """
+    return datetime.now(UTC)
+
+
+def parse_datetime(text: str, fmt: str, tz: tzinfo | None = None) -> datetime:
+    """按格式化模板将时间字符串解析为 aware datetime。
+
+    结果为钟面解释：模板不含 %z 指令（字符串无时区信息）时，将解析出的钟面
+    时间 attach 到 tz（缺省为系统本地时区）；模板含 %z 指令时解析结果自带偏移
+    并直接返回，此时忽略 tz 参数。DST 歧义时刻按钟面解释，不做特殊折叠处理。
+
+    Args:
+        text: 待解析的时间字符串。
+        fmt: strptime 格式化模板，可复用 tea_tool.datetime.formatter 常量。
+        tz: attach 目标时区，缺省为系统本地时区；模板含 %z 时无效。
+
+    Returns:
+        解析得到的 aware datetime。
+
+    Raises:
+        ValueError: 当 text 与 fmt 不匹配时（strptime 原生异常）。
+    """
+    parsed = datetime.strptime(text, fmt)  # noqa: DTZ007 解析结果 naive 时后续按 tz 参数 attach 时区
+    if parsed.tzinfo is not None:
+        return parsed
+    return parsed.replace(tzinfo=tz if tz is not None else local_tz())

tea_tool/masking/__init__.py

@@ -0,0 +1,39 @@
+"""通用脱敏工具：机制与内容分离。
+
+本包提供脱敏机制——策略（strategies）、文本发现规则（rules）与编排器
+（Masker），不内置任何"哪些信息敏感、脱成什么样"的业务默认。规则与
+格式由使用方显式定义，可选用 presets 模块的预置规则集。
+
+典型用法（业务侧全局定义一次后复用）::
+
+    from tea_tool.masking import Masker, KeepStrategy
+    from tea_tool.masking.presets import CN_PII_RULES
+
+    phone_mask = KeepStrategy(prefix=3, suffix=4)
+    masker = Masker(rules=CN_PII_RULES)
+
+    masker.mask("13812345678", phone_mask)          # 138****5678
+    masker.mask_text("联系 13812345678")            # 联系 ***********
+    masker.mask_dict(data, fields={"phone": phone_mask})
+"""
+
+from .core import Masker
+from .rules import MaskMatch, MaskRule
+from .strategies import (
+    HashStrategy,
+    KeepStrategy,
+    MaskStrategy,
+    RemoveStrategy,
+    ReplaceStrategy,
+)
+
+__all__ = [
+    "HashStrategy",
+    "KeepStrategy",
+    "MaskMatch",
+    "MaskRule",
+    "MaskStrategy",
+    "Masker",
+    "RemoveStrategy",
+    "ReplaceStrategy",
+]

tea_tool/masking/core.py

@@ -0,0 +1,246 @@
+"""脱敏编排层：Masker 门面，提供单值、文本、结构化三种脱敏入口。
+
+Masker 只持有使用方注入的规则列表，不含内置规则与类型注册表——何种文本
+是敏感信息、各类数据脱成什么样，均由使用方显式定义：可选用
+tea_tool.masking.presets 的预置规则，或在业务侧建立脱敏配置常量后复用
+同一实例（如项目配置文件中的模块级 Masker）。
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from .rules import MaskMatch, MaskRule
+from .strategies import MaskStrategy
+
+
+def _is_namedtuple(value: Any) -> bool:
+    """判断是否为具名元组（其构造器不接受序列重建）。
+
+    Args:
+        value: 待判断对象。
+
+    Returns:
+        value 为具名元组（含 _fields 的 tuple 子类）时返回 True。
+    """
+    return isinstance(value, tuple) and hasattr(type(value), "_fields")
+
+
+class Masker:
+    """通用脱敏编排器。
+
+    用法示例（文本自动识别，规则来自预置集）::
+
+        from tea_tool.masking.presets import CN_PII_RULES
+
+        masker = Masker(rules=CN_PII_RULES)
+        masker.mask_text("联系 13812345678")  # 联系 ***********
+
+    规则列表为空时 mask_text 不做自动识别；mask 与 mask_dict 不依赖规则，
+    按调用处显式传入的策略工作。
+    """
+
+    def __init__(self, *, rules: list[MaskRule] | None = None) -> None:
+        """构造脱敏器。
+
+        Args:
+            rules: 初始文本识别规则；未传时为空列表（可稍后经
+                register_rule 追加）。
+        """
+        self._rules: list[MaskRule] = list(rules or [])
+
+    # ------------------------------------------------------------------
+    # 注册
+    # ------------------------------------------------------------------
+
+    def register_rule(self, rule: MaskRule) -> None:
+        """追加一条文本识别规则。
+
+        Args:
+            rule: 待追加的规则。
+        """
+        self._rules.append(rule)
+
+    # ------------------------------------------------------------------
+    # 单值
+    # ------------------------------------------------------------------
+
+    def mask(self, value: Any, strategy: MaskStrategy) -> str | None:
+        """对单个值按指定策略脱敏。
+
+        None 原样返回（"无数据"无需脱敏）；非字符串值先转字符串再脱敏，
+        因此输出恒为字符串形态（int/float 等原始类型不保留）。
+
+        Args:
+            value: 待脱敏值，可为任意类型。
+            strategy: 采用的脱敏策略。
+
+        Returns:
+            脱敏后的字符串；value 为 None 时返回 None。
+        """
+        if value is None:
+            return None
+
+        return strategy.mask(value if isinstance(value, str) else str(value))
+
+    # ------------------------------------------------------------------
+    # 文本
+    # ------------------------------------------------------------------
+
+    def mask_text(
+        self,
+        text: str,
+        *,
+        rules: list[MaskRule] | None = None,
+    ) -> str:
+        """对自由文本做自动识别脱敏。
+
+        文本被全部规则扫描，命中区间先按优先级消解重叠，再按起始位置
+        单趟线性拼接、原位替换为所属规则的策略输出——命中互不重叠，
+        策略输出变长或删除时不影响其他命中的替换。
+
+        Args:
+            text: 待脱敏文本。
+            rules: 本次调用使用的规则列表；未传时使用构造时注入的规则
+                （可传空列表临时禁用识别）。
+
+        Returns:
+            脱敏后的文本；text 为空时原样返回。
+        """
+        if not text:
+            return text
+
+        active_rules = self._rules if rules is None else rules
+
+        matches: list[MaskMatch] = []
+        for rule in active_rules:
+            matches.extend(rule.find(text))
+
+        resolved = self._resolve_overlaps(matches)
+        if not resolved:
+            return text
+
+        # 命中互不重叠且按起始位置升序：一次遍历拼接新文本，避免逐命中
+        # 重建文本的平方级开销（替换串长度变化不影响其他区间）
+        parts: list[str] = []
+        pos = 0
+        for match in resolved:
+            parts.append(text[pos : match.start])
+            parts.append(match.strategy.mask(match.value))
+            pos = match.end
+        parts.append(text[pos:])
+        return "".join(parts)
+
+    # ------------------------------------------------------------------
+    # 结构化数据
+    # ------------------------------------------------------------------
+
+    def mask_dict(
+        self,
+        data: Mapping[str, Any],
+        fields: Mapping[str, MaskStrategy],
+        *,
+        recursive: bool = True,
+    ) -> dict[str, Any]:
+        """对 dict 按字段映射脱敏，未声明字段原样保留。
+
+        fields 为字段名到脱敏策略的映射，例如::
+
+            masker.mask_dict(
+                {"phone": "13812345678", "remark": "无"},
+                fields={"phone": KeepStrategy(prefix=3, suffix=4)},
+            )
+
+        同一份字段映射会应用到嵌套层级：recursive 为 True 时，嵌套 dict
+        与 list/tuple 会被递归处理，嵌套 dict 中同名命中的字段同样脱敏；
+        嵌套容器内未命中的字段原样保留。
+
+        Args:
+            data: 待脱敏的 dict，仅处理顶层字符串键。
+            fields: 字段名到脱敏策略的映射。
+            recursive: 是否递归处理嵌套 dict 与 list/tuple，默认 True。
+
+        Returns:
+            脱敏后的新 dict；原始 data 不被修改。
+        """
+        result: dict[str, Any] = {}
+
+        for key, value in data.items():
+            if key in fields:
+                result[key] = self.mask(value, fields[key])
+            elif recursive and isinstance(value, Mapping):
+                result[key] = self.mask_dict(value, fields=fields)
+            elif recursive and isinstance(value, (list, tuple)):
+                if _is_namedtuple(value):
+                    # 具名元组按字段结构存在，序列重建会破坏其形状，原样保留
+                    result[key] = value
+                else:
+                    result[key] = self._mask_collection(value, fields=fields)
+            else:
+                result[key] = value
+
+        return result
+
+    # ------------------------------------------------------------------
+    # 内部方法
+    # ------------------------------------------------------------------
+
+    def _mask_collection(
+        self,
+        value: list[Any] | tuple[Any, ...],
+        fields: Mapping[str, MaskStrategy],
+    ) -> list[Any] | tuple[Any, ...]:
+        """递归脱敏集合元素：dict 元素按字段映射，嵌套集合继续深入。
+
+        Args:
+            value: 待脱敏的列表或元组。
+            fields: 字段名到脱敏策略的映射（与 mask_dict 相同）。
+
+        Returns:
+            与原容器同类型的新容器，元素已按字段映射脱敏。
+        """
+        result: list[Any] = []
+
+        for item in value:
+            if isinstance(item, Mapping):
+                result.append(self.mask_dict(item, fields=fields))
+            elif isinstance(item, (list, tuple)) and not _is_namedtuple(item):
+                result.append(self._mask_collection(item, fields=fields))
+            else:
+                result.append(item)
+
+        return type(value)(result)
+
+    @staticmethod
+    def _resolve_overlaps(matches: list[MaskMatch]) -> list[MaskMatch]:
+        """消除多规则命中的区间重叠。
+
+        排序键依次为优先级高、起始靠前、区间长，再依序贪心选取不与已选
+        命中重叠的区间——重叠时保留排序靠前者，保证身份证等长区间规则
+        不被银行卡等子串规则拆分。
+
+        候选起点不小于已选命中最大右端点时，与全部已选必然不重叠（其
+        右端点均不超过该最大值），可直接接受：避免大文本大量命中时
+        逐个比较的平方级开销。
+
+        Args:
+            matches: 全部规则产生的命中列表。
+
+        Returns:
+            互不重叠的命中列表，按起始位置升序排列。
+        """
+        ordered = sorted(
+            matches,
+            key=lambda item: (-item.priority, item.start, -item.length),
+        )
+
+        selected: list[MaskMatch] = []
+        max_end = -1
+        for match in ordered:
+            if match.start >= max_end or not any(
+                match.start < current.end and match.end > current.start
+                for current in selected
+            ):
+                selected.append(match)
+                max_end = max(max_end, match.end)
+
+        return sorted(selected, key=lambda item: item.start)

tea_tool/masking/presets.py

@@ -0,0 +1,86 @@
+"""显式选用的预置规则集：中国大陆常见个人信息的文本识别规则。
+
+预置规则只做"识别 + 全星"这一最安全的默认：每条规则绑定无参
+KeepStrategy()（整段掩码），不含保留位等业务格式断言——具体格式由使用方
+按需派生，例如::
+
+    phone_rule = PHONE_RULE.with_strategy(
+        KeepStrategy(prefix=3, suffix=4)
+    )
+
+本模块不自动生效，须显式传入 Masker::
+
+    from tea_tool.masking import Masker
+    from tea_tool.masking.presets import CN_PII_RULES
+
+    masker = Masker(rules=CN_PII_RULES)
+
+已知局限：
+
+- IP_RULE 无法区分 IPv4 与四段点分十进制数字，版本号等（如 "1.2.3.4"）
+  会被误判为 IP；
+- BANK_CARD_RULE 只按 13~19 位纯数字串识别，不做 Luhn 校验，生产环境建议
+  叠加 Luhn 或更严格的上下文约束；
+- ID_CARD_RULE 仅覆盖中国大陆 18 位身份证格式（含末位 X/x）。
+"""
+
+from .rules import MaskRule
+from .strategies import KeepStrategy
+
+# 中国大陆手机号：1[3-9] 开头共 11 位。
+PHONE_RULE = MaskRule(
+    pattern=r"(?<!\d)1[3-9]\d{9}(?!\d)",
+    strategy=KeepStrategy(),
+    priority=100,
+)
+
+# 18 位身份证：优先级高于银行卡，避免纯数字身份证被银行卡规则拆分命中。
+ID_CARD_RULE = MaskRule(
+    pattern=r"(?<!\d)\d{17}[\dXx](?!\d)",
+    strategy=KeepStrategy(),
+    priority=200,
+)
+
+# 邮箱。
+EMAIL_RULE = MaskRule(
+    pattern=(
+        r"(?<![\w.+-])"
+        r"[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+"
+        r"@"
+        r"[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+"
+        r"(?![\w.-])"
+    ),
+    strategy=KeepStrategy(),
+    priority=80,
+)
+
+# IPv4。
+IP_RULE = MaskRule(
+    pattern=(
+        r"(?<![\d.])"
+        r"(?:"
+        r"(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\."
+        r"){3}"
+        r"(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)"
+        r"(?![\d.])"
+    ),
+    strategy=KeepStrategy(),
+    priority=50,
+)
+
+# 银行卡：只负责发现 13~19 位数字串，不做 Luhn 校验（见模块 docstring）。
+BANK_CARD_RULE = MaskRule(
+    pattern=r"(?<!\d)\d{13,19}(?!\d)",
+    strategy=KeepStrategy(),
+    priority=150,
+)
+
+# 中国大陆常见个人信息规则组合，按优先级降序：
+# 身份证(200) > 银行卡(150) > 手机号(100) > 邮箱(80) > IP(50)。
+CN_PII_RULES = [
+    ID_CARD_RULE,
+    BANK_CARD_RULE,
+    PHONE_RULE,
+    EMAIL_RULE,
+    IP_RULE,
+]