模块接口与字段映射

文档功能

本文档用于汇总风控业务模块向主项目提供的 REST 接口、主要筛选参数、响应字段和 Agent Run 接入方式，作为前后端联调和接口验收依据。

统一约定

路由前缀为 /api/v1/risk。
响应使用主项目 {data, meta} 信封。
列表接口的 data 为数组，next_cursor 和 has_more 放在 meta。
时间和日期使用 RFC 3339 或主项目约定格式。
金额、数量和主键按主项目字段映射返回字符串。
预警队列和其他证据列表每页最多 10 条。
未授权请求返回主项目统一权限错误。

列表响应格式：

{
  "data": [],
  "meta": {
    "trace_id": "trace-id",
    "next_cursor": "opaque-cursor",
    "has_more": false
  }
}

只读接口

方法	路径	功能	权限
GET	`/overview`	风险概览	`risk:alert:read`
GET	`/alerts`	预警队列	`risk:alert:read`
GET	`/alerts/{alert_no}`	预警详情	`risk:alert:read`
GET	`/evidence/{source}`	八类证据列表	`risk:alert:read`
GET	`/notifications`	通知记录	`risk:alert:read`

source 支持：

customers
products
transactions
capital_flows
holdings
login_records
alerts
notifications

预警筛选字段

字段	含义
`keyword`	预警、客户、产品或证据摘要关键字
`customer_no`	客户编号
`product_code`	产品代码
`product_name`	产品名称
`risk_level`	低、中、高
`rule_code`	`RW-###`
`start_time`	开始时间
`end_time`	结束时间
`cursor`	分页游标
`limit`	每页数量

写操作接口

方法	路径	功能	权限
POST	`/alerts/scan`	手动规则扫描	`risk:alert:scan`
POST	`/alerts/{alert_no}/acknowledgements`	确认接收	`risk:alert:write`
POST	`/alerts/{alert_no}/investigations`	进入调查	`risk:alert:write`
POST	`/alerts/{alert_no}/exclusions`	关闭误报	`risk:alert:write`
POST	`/alerts/{alert_no}/resolutions`	完成结案	`risk:alert:write`
POST	`/alerts/{alert_no}/escalations`	升级处理	`risk:alert:write`
POST	`/alerts/{alert_no}/evidence`	上传并归档证据	`risk:alert:write`

除证据上传外，上表写接口都必须携带 Idempotency-Key（16-128 位 ASCII，docs/05 §5.1）。同一用户、同一路径、同一键的重复请求直接回放首次响应；同一键换了请求正文返回 409 IDEMPOTENCY_CONFLICT。证据上传靠"同一预警只能归档一次"的冲突保护去重。

扫描通知与高风险邮件

POST /alerts/scan 同时用于手动扫描，定时扫描复用同一 RiskScanService。
高风险预警会创建站内通知和邮件通知。
邮件发送成功时通知状态为 已发送；发送失败时为 发送失败 并返回失败原因。
邮件发送失败不会改变扫描接口的成功状态，也不会回滚预警和站内通知。
notification_count 统计站内通知和邮件通知记录总数。
notification_failure 只表示通知记录创建失败，不表示 SMTP 邮件发送失败。
RISK_ALERT_MAIL_RECIPIENTS 当前只支持一个收件人，多个邮箱只取第一个。

日报和邮件

方法	路径	功能	权限
POST	`/daily-report`	生成结构化日报	`risk:alert:read`
POST	`/daily-report/stream`	流式生成日报	`risk:alert:read`
POST	`/daily-report/mail`	发送日报邮件	`risk:report:mail`

Agent Run

奶龙风控智能助手不单独定义业务对话接口，统一使用主项目：

方法	路径	功能
POST	`/api/v1/agent-runs`	创建风险 Agent 运行
GET	`/api/v1/agent-runs/{run_id}`	查询运行结果
GET	`/api/v1/agent-runs/{run_id}/events`	订阅 SSE 事件

创建运行时：

agent_type=risk。
用户需要 agent:run 和 risk:alert:read。
角色需要包含 risk_operator 或 admin。

主要响应字段

字段	含义
`alert_no`	预警编号
`customer_no`	客户编号
`customer_name`	脱敏客户姓名
`product_code`	产品代码
`product_name`	产品名称
`risk_level`	风险等级
`rule_codes`	命中规则
`evidence_summary`	证据摘要
`status`	处置状态
`ack_status`	确认状态
`created_at`	数据生成时间
`disposition_hint`	列表级只读研判提示
`disposition_assessment`	详情级只读研判草案
`evidence_truncated`	预警详情里被截断的证据类型名数组（`capital_flows` / `holdings` / `login_records`），空数组表示完整
`data_truncated`	日报是否因单次查询封顶而不完整；为 `true` 时日报计数偏低，不可当作全量口径

预警详情的证据列表（资金流水、持仓、登录记录）单次最多返回 200 条、日报每组最多 5000 条，超限时置位上面两个标记而不是静默截断。

预警详情客户对象

预警详情中的客户对象不使用内部数据库主键：

字段	含义
`customer_no`	业务客户编号，来源 `sys_user.user_no`
`customer_id`	兼容字段，值与 `customer_no` 相同，仅供既有前端继续使用

内部 fin_customer_profile.customer_id 和 sys_user.id 不向预警详情接口暴露。

时间参数

带时区的时间按自身时区解释。
不带时区的 REST 时间参数按 Asia/Shanghai 解释，再转换为 UTC 查询。
客户端不能继续假设裸时间是 UTC。

5.6 KiB Raw Blame History Unescape Escape