feat: 迁移奶龙风控业务模块与演示文档

app/core/risk_contracts.py

@@ -0,0 +1,44 @@
+"""风控 Agent 只读工具的输入契约。"""
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+RISK_LEVEL = Literal["低", "中", "高"]
+
+
+class RiskAlertQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    customer_no: str | None = Field(default=None, max_length=64)
+    product_code: str | None = Field(default=None, max_length=64)
+    product_name: str | None = Field(default=None, max_length=128)
+    risk_level: RISK_LEVEL | None = None
+    rule_code: str | None = Field(default=None, pattern=r"^RW-[0-9]{3}$")
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+
+    @field_validator("customer_no", "product_code", "product_name", "rule_code")
+    @classmethod
+    def text_must_not_be_blank(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        value = value.strip()
+        if not value:
+            raise ValueError("查询条件不能为空")
+        return value
+
+
+class RiskAlertEvidenceQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    alert_no: str = Field(min_length=1, max_length=64, pattern=r"^[A-Za-z0-9_-]+$")
+
+    @field_validator("alert_no")
+    @classmethod
+    def alert_no_must_not_be_blank(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("预警编号不能为空")
+        return value

app/core/risk_cursor.py

@@ -0,0 +1,34 @@
+"""风控列表游标；对外是不透明字符串，内部保存页偏移。"""
+
+import base64
+import json
+from typing import Any
+
+from app.core.errors import InvalidCursorError
+
+__all__ = ["decode_offset_cursor", "encode_offset_cursor"]
+
+
+def encode_offset_cursor(offset: int) -> str:
+    if offset < 0:
+        raise ValueError("offset must be non-negative")
+    payload = json.dumps({"offset": offset}, separators=(",", ":")).encode("utf-8")
+    return base64.urlsafe_b64encode(payload).decode("ascii").rstrip("=")
+
+
+def decode_offset_cursor(raw: str | None) -> int:
+    if raw is None or not raw.strip():
+        return 0
+    value = raw.strip()
+    try:
+        padding = "=" * (-len(value) % 4)
+        payload = base64.urlsafe_b64decode((value + padding).encode("ascii"))
+        decoded: Any = json.loads(payload.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise InvalidCursorError("cursor 非法或已过期") from error
+    if not isinstance(decoded, dict) or set(decoded) != {"offset"}:
+        raise InvalidCursorError("cursor 非法或已过期")
+    offset = decoded["offset"]
+    if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+        raise InvalidCursorError("cursor 非法或已过期")
+    return offset