袁聪的第一次提交，包含nl2sql,行情数据,场外申购

2026-09-10 09:23:22 +08:00
parent 46fc976b24
commit 5907fcd6d2
49 changed files with 6801 additions and 33 deletions
@@ -0,0 +1,105 @@
+# 金融 NL2SQL 工具接入说明
+
+## 1. 工具定位
+
+`query_financial_data` 是运营和投顾共用的金融只读 NL2SQL 工具。业务 Agent 只负责判断是否调用工具，不直接连库、不读取密钥、不自行写审计。
+
+调用链固定为：
+
+```text
+业务 Agent -> BaseAgent.call_tool -> ToolExecutor -> query_financial_data -> 金融只读表
+```
+
+## 2. 工具声明
+
+业务 Agent 的 `AgentDefinition.allowed_tools` 需要包含：
+
+```python
+allowed_tools=("query_financial_data",)
+supported_intents=("financial_query", "general")
+```
+
+发布配置需要按意图开启工具白名单：
+
+```json
+{
+  "namespace": "agent_tools",
+  "config_key": "<agent_type>:financial_query",
+  "value_json": {"allowed_tools": ["query_financial_data"]}
+}
+```
+
+工具权限码：
+
+```text
+financial:nl2sql:read
+```
+
+允许角色：
+
+```text
+advisor、operator、admin、super_admin
+```
+
+## 3. 调用示例
+
+```python
+result = await self.call_tool(
+    "query_financial_data",
+    {"question": request.message, "dry_run": False, "limit": 50},
+    intent="financial_query",
+    context=context,
+)
+```
+
+低置信度或模糊问题会返回：
+
+```json
+{"status": "need_confirmation", "message": "请确认查询范围、指标口径和时间条件。"}
+```
+
+Agent 应把 `message` 原样返回给用户，等待用户补充或确认后再次调用，并传入 `confirmation`。
+
+## 4. MVP 范围
+
+当前纳入 NL2SQL 的表：
+
+```text
+sys_customer_assignment
+fin_customer_profile
+fin_risk_assessment
+fin_product
+fin_fee_rule
+fin_market_price
+fin_nav_history
+fin_holding
+fin_transaction
+fin_sim_order
+fin_sim_account
+fin_cash_ledger
+client_facing_content
+```
+
+第一期只支持只读查询；支持跨两个或三个业务域查询；支持历史范围查询。历史时点查询如果依赖当前快照表，例如 `fin_holding`、`fin_sim_account`、`sys_customer_assignment`，会拒绝执行。
+
+## 5. 审计与持久化
+
+工具输出包含 `audit`，其中有：
+
+- `query_plan`：查询计划；
+- `generated_sql`：生成 SQL；
+- `permission_check`：权限校验结果；
+- `execution`：执行状态和返回行数。
+
+`ToolExecutor` 会把这些摘要写入 `ToolCallRecord.output_summary`，公共运行持久化会最终写入 `conversation_message.tool_calls`。
+
+## 6. 接入验收
+
+运营或投顾 Agent 接入时至少验证：
+
+- AgentDefinition 声明了 `query_financial_data`；
+- 发布配置按目标意图放行该工具；
+- 调用方角色具备 `financial:nl2sql:read`；
+- 模糊问题会先要求确认；
+- 生成 SQL 只包含 `SELECT`，且表名均在白名单内；
+- `conversation_message.tool_calls` 能看到查询计划、SQL 和权限校验摘要。
@@ -0,0 +1,82 @@
+# 场外基金外部服务灰度与回滚方案
+
+## 1. 当前实现边界
+
+当前代码已经提供 IMAP、OCR/DeepSeek 和 SMTP 适配层，但所有真实外部调用均由配置开关控制：
+
+- `OFFSITE_IMAP_ENABLED=false`：不连接收件邮箱。
+- `OFFSITE_MAIL_WORKER_ENABLED=false`：不启动场外邮件自动编排。
+- `OFFSITE_OCR_ENABLED=false`：OCR 使用本地 Mock。
+- `OFFSITE_DEEPSEEK_ENABLED=false`：字段识别使用本地 Mock。
+- `OFFSITE_SMTP_ENABLED=false`：不创建真实 SMTP 发送连接。
+- `OFFSITE_SMTP_DRY_RUN=true`：即使发送接口被调用，也只生成待发送结果，不标记发送成功。
+
+通知创建接口只创建待发送记录。真正发送必须调用独立发送接口，并传递运营确认状态。
+
+场外 Worker 另受以下安全条件约束：
+
+- `OFFSITE_MAIL_WORKER_ENABLED=true` 只是允许编排，不代表可以绕过身份校验。
+- `OFFSITE_WORKER_USER_ID` 必须是数据库中已存在、经过实时角色和权限解析的操作用户；为空或无权限时自动写入失败关闭。
+- Worker 使用 `offsite_mail_cursor` 持久化 INBOX UID、失败 UID、重试时间和租约；失败邮件不推进后续 UID。
+- 当前实现使用健康检查加轮询增量补偿；IMAP IDLE 仍需单独联调，不能把轮询版本描述为已完成 IDLE。
+
+## 2. 上线前检查
+
+上线前必须由技术和运营共同确认：
+
+1. 收件邮箱、授权码、发件人白名单和 SMTP 发件地址均使用密钥管理系统注入，不写入代码、日志或 Git。
+2. IMAP 账号只能访问指定收件箱，服务账号不使用登录密码，使用邮箱授权码。
+3. 原始 `.eml` 和附件目录有容量、权限、备份和保留期限方案。
+4. OCR 网关已确认请求格式、签名方式、超时和费用上限。
+5. DeepSeek 模型、配额、超时、结构化 JSON 格式和敏感数据处理策略已确认。
+6. SMTP 收件人、回复原邮件规则、附件重新附加规则已经过运营验收。
+7. 监控至少能发现 IMAP 连接失败、邮件解析失败、OCR/模型失败、SMTP 失败、重试耗尽和磁盘写入失败。
+
+## 3. 灰度顺序
+
+### 阶段一：离线验证
+
+保持所有真实开关关闭，使用 Mock 邮件、OCR、DeepSeek 和 SMTP。验证重复邮件、白名单、附件哈希、识别异常、规则核对和审计。
+
+### 阶段二：真实 IMAP、业务发送关闭
+
+仅打开 `OFFSITE_IMAP_ENABLED=true` 和 `OFFSITE_MAIL_WORKER_ENABLED=true`，保持 OCR、DeepSeek 和 SMTP 关闭，并配置已核验的 `OFFSITE_WORKER_USER_ID`。先只做收件箱健康检查和增量扫描，确认 UID 不回退、断线后能补偿、非白名单邮件不进入业务队列；IMAP IDLE 未联调前按轮询模式验收。
+
+### 阶段三：真实识别、发送保持 dry-run
+
+打开 `OFFSITE_OCR_ENABLED=true` 和 `OFFSITE_DEEPSEEK_ENABLED=true`，保持 `OFFSITE_SMTP_ENABLED=false` 或 `OFFSITE_SMTP_DRY_RUN=true`。使用已脱敏测试附件验证字段、置信度、页面证据、缺失字段和失败降级。
+
+### 阶段四：单收件人真实 SMTP
+
+打开 `OFFSITE_SMTP_ENABLED=true`，保持 `OFFSITE_SMTP_DRY_RUN=false`，只允许运营选择的一封测试邮件和一个确认收件人。核对 `Message-ID`、`In-Reply-To`、附件内容、发送状态和 provider message ID。
+
+### 阶段五：小流量业务灰度
+
+先限定单个业务时段或有限业务邮件，持续观察一个完整业务周期。未完成发送、失败重试和人工确认记录不得直接计入资金清算统计。
+
+### 阶段六：正式运行
+
+只有阶段五无未解释失败、重复发送、错发收件人、原始文件覆盖或统计污染后，才扩大到正式业务范围。
+
+## 4. 回滚操作
+
+发生错发、重复发送、认证失败、外部费用异常、识别结果大面积异常或存储故障时：
+
+1. 立即将 `OFFSITE_SMTP_ENABLED=false`，停止新的真实发送。
+2. 如收件范围或解析异常，将 `OFFSITE_IMAP_ENABLED=false`，暂停收件扫描。
+3. 如识别服务异常，只关闭 `OFFSITE_OCR_ENABLED` 或 `OFFSITE_DEEPSEEK_ENABLED`，保留原始邮件和附件，禁止用不完整识别结果自动核对。
+4. 保留 `offsite_notification`、原始 `.eml`、附件和审计记录，不执行删除、覆盖或数据库降级迁移。
+5. 将发送中的通知交由运营核对邮箱实际投递结果；不得仅依据本地请求超时再次发送。
+6. 修复后先回到 dry-run 和单收件人灰度，再恢复正式发送。
+
+## 5. 回滚后的数据处理
+
+- `发送成功` 不自动重发，重复调用只返回已有成功状态。
+- `发送失败` 只按剩余重试次数重试，超过上限转人工处理。
+- `待发送` 记录保留，恢复服务后由运营重新确认。
+- 原始识别值、原始查询值、程序计算值和运营最终发送正文不得互相覆盖。
+- 统计必须重新执行并核对范围，未成功正常返回的邮件不纳入资金清算统计。
+
+## 6. 验收记录
+
+每次灰度至少记录：部署版本、配置开关、测试邮件标识、测试附件哈希、操作人、开始结束时间、实际收件人、发送状态、provider message ID、失败原因和回滚结论。
@@ -0,0 +1,38 @@
+# 场外基金申购赎回工作流程图
+
+```mermaid
+flowchart TD
+    A[收件箱收到邮件] --> B[IMAP IDLE 事件]
+    B --> C[按 UID 拉取完整 MIME 和附件]
+    C --> D{发件人和邮件认证通过}
+    D -- 否 --> D1[记录告警并停止进入业务队列]
+    D -- 是 --> E[保存原始 EML 和附件哈希]
+    E --> F[OCR/Document AI 一次识别]
+    F --> G[DeepSeek 分类与字段抽取]
+    G --> H{附件类型}
+    H -- other --> H1[只归档]
+    H -- summary/subscription/redemption --> I[生成 mail_id 和 attachment_id]
+    I --> J[SSE 推送新业务邮件事件]
+    J --> K[生成查询/计算/核对三阶段执行计划]
+    K --> L[调用 nl2sql_yc 只读查询]
+    L --> M[确定性金额、份额、比例计算]
+    M --> N[固定申购/赎回规则核对]
+    N --> O{识别或查询是否异常}
+    O -- 是 --> P[运营人工确认异常或未处理]
+    O -- 否 --> Q[运营确认正常]
+    P --> R[独立邮件返回或风控通知候选]
+    Q --> S[正常邮件返回]
+    S --> T[资金清算统计重算]
+    R --> U[发送状态、重试和审计]
+    T --> U
+    U --> V{邮件内单据均有最终人工状态}
+    V -- 否 --> W[保持待处理]
+    V -- 是 --> X[邮件完成并保留全链路审计]
+```
+
+## 边界
+
+- 本流程只覆盖后端、Agent、数据、接口、异步事件和审计。
+- 反洗钱和开放期规则不纳入本次实现。
+- 邮件返回、风控通知和资金清算通知互相独立，不自动联动。
+