# 主项目接入清单

## 文档功能

本文档用于说明主项目需要提供哪些公共能力，以及风控模块需要向主项目注册哪些业务入口，作为代码合并和联调检查清单。

## 主项目需要提供

| 能力 | 要求 |
|---|---|
| 身份认证 | 提供有效 JWT 和统一登录流程 |
| RBAC | 从数据库加载有效角色、权限和数据范围 |
| 数据库 | 提供基线表、连接池和事务能力 |
| 路由 | 支持追加风控 Controller |
| Agent 工厂 | 支持追加注册业务 Agent 和只读工具 |
| Worker | 支持 Agent Run 和业务异步任务 |
| Outbox | 支持业务领域事件可靠投递 |
| 审计 | 支持追加 `interaction_audit` |
| 模型服务 | 提供模型端点解析和调用入口 |
| Redis | 作为可选缓存，不可用时可降级 |
| Milvus | 作为可选语义记忆，不可用时可降级 |
| 配置发布 | 支持 Agent 工具白名单和意图配置 |

## 本模块需要注册

| 注册项 | 内容 |
|---|---|
| 路由前缀 | `/api/v1/risk` |
| Agent 类型 | `agent_type=risk` |
| Agent 展示名 | 奶龙风控智能助手 |
| 允许角色 | `risk_operator`、`admin` |
| 允许入口 | `api` |
| 只读工具 | 风险概览、预警查询、预警证据 |
| 权限 | `agent:run`、`risk:alert:read`、`risk:alert:write`、`risk:alert:scan`、`risk:report:mail` |

## 数据库依赖

主项目需要确保以下类别表已经存在：

- 账号和 RBAC：`sys_user`、`sys_role`、`sys_permission`、`sys_user_role`、`sys_role_permission`、`sys_customer_assignment`。
- 风控业务：`fin_risk_alert`、`fin_risk_notification`、`biz_work_order`。
- 金融数据：客户画像、风险测评、产品、交易、资金、持仓和登录记录。
- 平台审计：`interaction_audit`。

本模块不负责新增数据库表或执行演示数据初始化。演示机数据准备规则见
`26-演示机数据插入规则.md`。

## 接入验收点

- 主项目路由能够访问本模块只读查询接口。
- 风控账号拥有角色和对应权限。
- 风控写接口和扫描接口支持并携带 `Idempotency-Key`。
- 风控账号具有有效的客户归属数据。
- Agent Run 能够调用本模块工具。
- 工具调用、处置和权限拒绝能够写入审计。
- Redis 或 Milvus 不可用时，结构化风控功能仍可用。