docs: 新增四大 Agent 流程实现拆解（客服/投顾/风控/场外运营）

对四份需求文档（智能客服方案 v1.3、基金运营流程、风控模块详细业务流程、投资顾问流程）
与现有底座逐项比对后的实现拆解，用于开工前明确边界、工作量与决策点。

核心结论：可实现。底座 52 张表与流程设计高度吻合——风控的
ack_status/is_escalated/close_reason/trigger_rule_codes、客服的 svc_handover_ticket.confidence、
投顾的 client_facing_content.review_status、biz_work_order 的双录与风险揭示字段均已在位；
客服方案的七步骨架与 BaseAgent 骨架完全一致；适当性 C1-C5/R1-R5 已实现且不接受调用方传值；
风控文档定义的 SSE 事件（start/tools/delta/replace/done）与底座现有实现完全一致。

文档内容：
1. 覆盖度总览 + 四模块逐项拆解（已就绪 / 需新写 / 必须业务补充）。
2. 指出两处真实缺口：邮件 SMTP 在 app/ 中零实现；规则引擎只有 trigger_rule_codes 字段
   而无引擎本体（风控明确要求"规则引擎产生预警、Agent 不产生"，属确定性逻辑，不能用模型代替）。
3. 指出场外运营是唯一需要新建表的模块（底座 15 张 fin_* 全为场内模拟交易，
   AGENTS.md 要求场外流程独立，不得写入场内交易表）。
4. 列出 6 个必须先决策的事项：接口形态（底座异步 + SSE vs 方案的同步 chat/customer）、
   模型与 embedding 维度（直接决定 Milvus 集合 schema）、RAG 混合判定公式（方案未给）、
   规则引擎的承载方式、场外运营排期、合规校验前置还是后置。
5. 建议开工顺序：客服 → 投顾 → 风控（规则引擎宜单独立项）→ 场外运营（缺真实单据样本）。

说明：本提交只含拆解文档，不含需求原文。需求原文的纯文本提取物位于 _flows/（未跟踪），
是否入库待定；临时提取脚本已删除。

docs/22-四大Agent流程实现拆解.md

@@ -0,0 +1,169 @@
+# 四大 Agent 流程实现拆解（基于现有底座）
+
+> 输入：`智能客服Agent专项设计方案`(v1.3, 1664 行)、`基金运营流程`、`风控模块详细业务流程`、`投资顾问流程`。
+> 目的：在动手前说清「哪些能直接用底座、哪些要新写、哪些必须你们先定」。
+
+## 0. 一句话结论
+
+**能实现。** 决定性原因是：**底座的 52 张表与这几份流程的设计高度吻合**，
+绝大部分工作是「填 Service / Agent 逻辑」，而不是「重建表结构」——后者才是真正贵的部分。
+
+举几个直接对上的例子（均为实际字段名）：
+
+| 流程要求 | 底座已有的字段 |
+| --- | --- |
+| 风控「确认接收 / 关闭误报 / 升级处理」 | `fin_risk_alert.ack_status / handler_id / is_escalated / escalation_reason / close_reason / trigger_rule_codes` |
+| 风控「站内通知 + 邮件，发送失败不影响预警」 | `fin_risk_notification.channel / send_status / fail_reason / receiver_email` |
+| 客服「转人工携带意图与置信度」 | `svc_handover_ticket.intent / confidence / reason_code / conversation_summary / source_references` |
+| 投顾「输出为草稿，须投顾审核签发」 | `client_facing_content.draft_content / review_status / reviewer_user_id / published_at` |
+| 投顾「双录 / 风险揭示 / 二次确认」 | `biz_work_order.recording_reference / risk_disclosure_ack_at / second_confirmation_at / risk_rule_hits` |
+| 投顾「C1-C5 ↔ R1-R5 最严口径」 | **已实现**：`app/service/suitability_service.py`（255 行，风险等级只取最新测评、不接受调用方传值） |
+| 客服「7 个负面词零容忍」 | `agent_negative_word` 表 + 底座合规检查步骤 |
+| 客服「回复模板 / 免责声明话术」 | `agent_reply_template` 表 |
+| 客服「同义问法」 | `agent_faq_synonym` 表 |
+| 客服「意图阈值 0.6」 | `agent_intent_config.confidence_threshold`（已生效） |
+
+另外，客服方案的**七步骨架（①输入鉴权②记忆召回③意图路由④核心逻辑⑤结果生成⑥数据沉淀⑦事件广播）与底座的
+`BaseAgent` 骨架完全一致**——这份方案就是按底座设计的，`__init_subclass__` 已强制⑥⑦不可被子类绕过。
+
+## 1. 覆盖度总览
+
+| 模块 | 所需表 | Service 现状 | 主要缺口 | 相对工作量 |
+| --- | --- | --- | --- | --- |
+| **智能客服** | 全部就绪 | 覆盖最好（意图/知识/转人工/负面词/模板/会话） | 三集合知识检索、客服 Agent 本体、脱敏工具、状态机 | 中 |
+| **投资顾问** | 全部就绪 | 适当性已实现；组合/报告无 | 策略配置、组合构建、报告生成、审核签发流 | 中 |
+| **风控监测** | 全部就绪 | **几乎为零**（`risk_alert` 仅 4 处命中，多为 ORM） | **规则引擎**、扫描服务、预警处置 API、日报、邮件 | 大 |
+| **基金运营（场外）** | **无场外表** | 无 | 需新建独立表 + 单据解析 + 核对规则 | 大（且缺样本） |
+
+## 2. 智能客服 Agent
+
+### 2.1 底座直接可用的
+
+七步骨架、鉴权与画像、RBAC、审计、幂等、限流、事件（Outbox 现成）、配置发布、
+意图配置与阈值、负面词、回复模板、同义问法、转人工工单、会话与消息、SSE 流式、
+记忆读写、知识元数据表。
+
+> 值得注意：风控文档定义的 SSE 事件 `start / tools / delta / replace / done`
+> **与底座现有实现完全一致**；而客服方案通篇只写「SSE 流式」、未定义事件类型——
+> 这一项以底座现成为准即可，不需要新设计。
+
+### 2.2 需要新写的
+
+1. **三集合知识检索**：`fin_faq_collection`(TopK 3) / `fin_product_collection`(TopK 5) /
+   `fin_policy_collection`(TopK 5)。底座的 Milvus 适配器目前服务于**记忆向量**，
+   知识检索的集合 schema、三级路由、按 `score` 排序、md5 去重、`expire_date` 过滤都要新写。
+   维度 1024 / `COSINE` / `IVF_FLAT`(nlist=128, nprobe=16) 已在方案里给定。
+2. **客服 Agent 本体**：5 类意图分支（product_inquiry / policy_explain / faq / chitchat / transfer_human），
+   `faq` 走「检索直返不经 LLM」，其余走 RAG + 生成 + 来源引用。
+3. **强制免责声明注入**：方案要求「基类强制注入、子类不得绕过」——需挂到底座的结果生成阶段。
+4. **脱敏工具 `mask_tool`**：身份证/卡号/手机号不回显，仅掩码。
+5. **会话状态机 5 态**：`idle / processing / clarifying / answering / transferring`。
+6. **三档兜底判定**：高/中/低置信分别对应直接回答 / 加不完整提示 / 兜底话术+转人工。
+7. **澄清机制**：≤2 轮、每轮追问 1 个槽位；**闲聊边界**：≤3 轮后强制引导业务。
+8. **suggestions 生成**：接口已有该字段但无生成逻辑。
+
+### 2.3 方案自己写了「未明确」、必须你们补的
+
+| 项 | 说明 |
+| --- | --- |
+| 「RAG 混合判定」公式与阈值 | 方案写「绝对阈值 AND（相对间隙 OR 分布优势）」，**公式、数值、三档分数区间全文未给** |
+| 熔断次数 N | 「连续失败 N 次熔断」，N 未给 |
+| QPS 限流阈值 | 只写「令牌桶/滑动窗口」，数值未给 |
+| 业务侧表名 | 方案只写「MySQL LIKE 检索」「画像直连 MySQL」，**未给任何表名** |
+| 跨 Agent 联动规则 | 客服识别「高净值/大额意愿/敏感话题」后的联动规则未定义 |
+| 合规校验是否前置 | §0.4 评审点自己提出「是否应前置到答案生成之前」，**未定论** |
+
+### 2.4 ⚠️ 与底座接口形态的冲突（必须决策）
+
+方案设计的是 **`POST /api/chat/customer`，同步返回 `reply`**；
+底座 `docs/05` 规定的是 **`POST /api/v1/agent-runs` → 202 + `run_id` → SSE 订阅结果**。
+
+两者不是简单改名，是**调用模型不同**：底座是「受理即返回、Worker 异步执行」，方案是「同步等答案」。
+
+- 采用底座形态：前端要改成「提交后订阅 SSE」，但天然获得审计、重试、限流、可观测、多 Worker 扩展。
+- 采用方案同步形态：与底座现有 `docs/05` 冲突，且长耗时请求会占满连接。
+
+**建议采用底座形态**，把「同步返回」作为 SSE 的首包体验（首 token <800ms 目标可达成），
+但这需要你确认，因为会影响前端联调方式。
+
+## 3. 投资顾问 Agent
+
+| 流程步骤 | 现状 |
+| --- | --- |
+| 1 客户认知 / 问卷采集 | 表就绪（`fin_customer_profile`、`fin_risk_assessment`），问卷入口需新写 |
+| 2 风险测评与适当性匹配 | **已实现**（`suitability_service`，C1-C5 × R1-R5 硬约束） |
+| 3 投资目标与期限 | 需新写（目标书、回撤约束、期限分档） |
+| 4 匹配投顾策略 | 需新写（保守/稳健/平衡/进取/激进 + 大类资产配置比例） |
+| 5 筛选基金构建组合 | 需新写（核心+卫星、集中度检查、重复持仓检查、推荐理由） |
+| 6 签署协议与授权范围 | 表就绪（`biz_work_order` 的授权/双录字段），流程需新写 |
+| 7 申购赎回 | **底座是场内模拟交易**（`fin_sim_order`）；投顾流程的申赎若指场外，需与运营模块统一 |
+| 8 持续监控 | 表就绪（`fin_holding`、`fin_nav_history`），监控看板需新写 |
+| 9 调仓再平衡 | 需新写（偏离阈值、调仓建议、**重新适当性校验**） |
+| 10 报告与陪伴 | 表就绪（`client_facing_content`），报告生成+审核签发需新写 |
+
+**合规要点都已映射到表**：草稿态 + 投顾审核（`review_status`）、免责声明、脱敏、
+留痕（操作人/时间/输入/输出/判断依据/审批意见）。
+
+## 4. 风控监测 Agent —— 表最全，但代码最少
+
+底座有 `fin_risk_alert`(29 列) / `fin_risk_notification`(14 列) / `biz_work_order`(30 列) /
+`fin_capital_flow` / `fin_transaction` / `fin_holding` / `sys_login_record` / `interaction_audit`，
+**风控文档 §2 要求的七类数据源全部覆盖**。
+
+但代码侧几乎为零，必须新写：
+
+1. **规则引擎**（核心，且是**确定性逻辑**）。风控文档明确写「**规则引擎负责判断是否生成预警，
+   Agent 不负责生成预警**」——这条与底座设计一致（Agent 只读），但引擎本身要新做：
+   规则定义与存储、规则执行、命中写入 `fin_risk_alert.trigger_rule_codes`、优先级计算。
+   **底座目前没有规则表**，只有 `trigger_rule_codes` 这个字段。
+2. **扫描服务**（读七类数据 → 执行规则 → 未命中/命中分支 → 高风险生成通知）。
+3. **预警处置 API**：确认接收 / 关闭误报（理由 1-500 字）/ 升级（文档注明「后端已有接口，前端弹窗未接入」）。
+4. **日报生成**：前八项**确定性统计**，只有第 9 项「建议优化方向」用模型（超时/空/异常时用规则化建议）。
+5. **邮件 SMTP**：`grep MAIL|SMTP` 在 `app/` 中**零匹配**，完全没实现；要求「发送失败只记日志，不影响预警和站内通知」。
+6. **风控 Agent 对话**：只读工具（预警/证据/风险概览/预警列表），流式 + 模板降级。
+
+## 5. 基金运营（场外）—— 唯一需要新建表的模块
+
+底座 15 张 `fin_*` 全是**场内模拟交易**；运营流程是**场外申购赎回**，
+而 `AGENTS.md` 明确「场外基金运营流程独立，不得写入场内交易表」
+→ 因此**必须新建场外一组表**，不能复用场内表。
+
+流程本身可拆成三段：
+1. **单据采集与解析**：从运营邮箱取中国结算邮件 → 解析申购/赎回单扫描件 → 关键字段提取 + 格式校验。
+   涉及邮件收取（另一处 SMTP/IMAP 缺口）与文档解析（底座无此能力）。
+2. **核对规则**（文档已给全字段）：申购后单一持有比例上限、单日申购金额上限、金额格式（两位小数/万元）、
+   日期格式、巨额赎回、赎回金额 vs 可用金额、最低申购金额、是否在开放期、反洗钱嫌疑。
+   其中 `fin_product.single_investor_max_holding_ratio / min_amount / open_period_start/end` 已就绪，**但场外产品需要独立表**。
+3. **人在回路**：NL2SQL 确认 → 汇总统计 → 是否上报风控 → 是否给资金清算岗 → 回单给中国结算。
+
+⚠️ **文档自己写了「待工作：不同的申购赎回单子，以作实际操作案例」** —— 也就是说**缺样本数据**。
+没有真实单据样本，解析规则只能靠猜，建议先把这段挂起或只做「字段定义 + 表结构 + 人工录入」版本。
+
+## 6. 你必须先决策的 6 件事
+
+| # | 决策点 | 影响 |
+| --- | --- | --- |
+| 1 | **接口形态**：底座异步 `agent-runs` + SSE，还是方案里的同步 `chat/customer` | 决定前端联调方式；建议用底座的 |
+| 2 | **模型选型**：方案写 `qwen-turbo`(意图) + Qwen Embedding(1024 维)；底座现配 `deepseek-flash` | **embedding 维度直接决定 Milvus 集合 schema**，定错了要重建知识库 |
+| 3 | **RAG 混合判定公式与三档分数区间** | 方案未给，是客服模块的核心算法 |
+| 4 | **规则引擎的规则从哪来**：代码常量、数据库表，还是管理界面配置 | 决定风控模块的架构，也决定业务人员能否自己加规则 |
+| 5 | **场外运营是否排在首批** | 它缺样本数据，且要新建一组表 |
+| 6 | **合规校验前置还是后置**（方案 §0.4 自己提的待评审点） | 影响链路结构与首响时延 |
+
+## 7. 建议开工顺序
+
+| 顺序 | 模块 | 理由 |
+| --- | --- | --- |
+| 1 | **智能客服 Agent** | 底座覆盖度最高（表全 + 机制全），最容易做出可演示闭环；缺的只是三集合检索与 Agent 本体 |
+| 2 | **投资顾问 Agent** | 硬约束（适当性）已实现，`client_facing_content` 现成，主要补生成与审核流 |
+| 3 | **风控 Agent** | 表最全但代码最少，且**规则引擎是全新架构**（确定性逻辑，不能用模型代替），建议单独立项 |
+| 4 | **场外运营** | 唯一要新建表 + 缺样本，建议等有真实单据样本再动 |
+
+**每个模块我都建议按同一个节奏交付**：先做只读最小闭环（端到端脚本 + 审计可见）→ 你们验业务逻辑 →
+再扩分支与边界；涉及写数据的（风控处置、调仓、场外核对）先给事务/并发/幂等方案再动手。
+
+## 8. 这份拆解的边界
+
+- 四个模块的**表结构就绪度**是我逐表查库确认的（不是读文档推断）。
+- 每份需求文档里的**具体业务规则**（阈值、公式、话术）我只做了提取与对照，**正确性未经业务确认**。
+- 「工作量」是相对量级（中/大），不是人日估算——那需要先定第 6 节的 6 件事。