# 智能公募基金系统 · 开发计划

> 依据：《需求文档-修改版.html》（v4.53）
> 版本：v1.0 ｜ 日期：2026-09-07 ｜ 状态：待评审

---

## 0. 约束与差异说明

本项目在需求文档基础上做三处**硬性调整**，其余遵循原文档：

| 项 | 需求文档原方案 | 本项目约定 | 说明 |
|---|---|---|---|
| 业务范围 | 全品类理财（基金/银行理财/保险/信托） | **仅公募基金** | 产品表、知识库、推荐逻辑均围绕公募基金 |
| 数据库 | MySQL + Milvus + Neo4j + Redis + **MinIO** | **仅 MySQL、Milvus、Neo4j、Redis** | MinIO 移除：原始文档正文改存 MySQL `raw_content`；对象文件（原始上传文件）存本地磁盘 `./data/files/`（磁盘不属于数据库，允许），仅记录路径。LLM/Embedding 为外部服务，不受四库约束 |
| 前端形态 | Streamlit/Gradio 演示 | **企业级 Web**（Vue3 + Element Plus + Pinia + Vite），四个入口：官网 / 客户Web端 / 投顾工作台 / 风控控制台 | 前后端分离，`/api` 统一网关 |

企业级要求：RBAC 权限、操作审计、数据脱敏、幂等下单、限流、链路追踪、SSE 流式、定时任务、消息中心、多级降级。

> 现状基础：工作目录 `Memory_demo` 已完成 FastAPI 骨架 + 四库懒连接单例（`config/database.py`）+ 一个跨四库的 memory 读写 demo，**可复用为 Phase 0 底座**，无需重写。

---

## 1. 总体架构

```
Vue3 前端
├─ 官网首页(可匿名)      ├─ 客户Web端(登录)   ├─ 投顾工作台(登录)   ├─ 风控控制台(登录)
        └────────────────────── FastAPI /api ──────────────────────┘
                                       │ Mock JWT · RBAC · 审计 · 限流
Agent 编排层(统一执行骨架: 记忆召回→意图路由→核心逻辑→结果输出→数据沉淀→事件广播)
 ├─ 客服Agent(匿名+客户)    ├─ 投顾Agent       ├─ 风控Agent      └─ 数据分析Agent(NL2SQL,加分项)
能力组件: RAG(Milvus) · GraphRAG(Neo4j) · NL2SQL(MySQL) · 规则引擎 · 画像研判 · 置信度 · 三层记忆
      工具层: 文档解析 · Embedding · 订单提交 · 净值计算 · 脱敏 · 事件发布
      数据层: MySQL(业务)  Milvus(向量)  Neo4j(图谱)  Redis(缓存/会话/事件/锁)
```

**四库职责分工（铁律：模块归属不清时按此表归位）**

| 数据库 | 存什么 | 谁读写 |
|---|---|---|
| **MySQL** | 用户/投顾关系/画像/基金产品/净值/订单/成交/持仓/风评问卷/预警/规则/工单/会话归档/画像变更日志/知识元数据+原文/审计/公告/站内信 | 业务服务、各 Agent 的持久化沉淀 |
| **Milvus** | ① FAQ 向量 ② 基金产品说明/政策法规 文档向量 ③ **客户长期记忆向量**（对话摘要+画像标签，按 `customer_id` 过滤） | RAG 检索、客户记忆召回/写入 |
| **Neo4j** | 客户-产品-行业-市场-基金经理-风险等级图谱 + 规则-业务实体关联 | GraphRAG、投顾推荐多跳查询、行业集中度分析 |
| **Redis** | 会话短期记忆、画像/产品热缓存、待处理预警 Set、Pub/Sub 事件总线、幂等锁、限流、Token 黑名单、验证码 | 所有 Agent 的短期记忆与实时事件 |

---

## 2. 业务需求

### 2.1 官网首页（首页 = 公司官网 + 客服Agent）
- 公司介绍、资质荣誉、团队、联系合作（静态区块，数据驱动）
- **基金产品展示**：列表 + 筛选（类型/风险等级/收益率/起投额）+ 产品详情（净值走势、基金经理、费率、投资策略）
- 公司公告栏
- **客服Agent 浮窗**：免登录可用，RAG 回答公募基金问题（FAQ / 产品说明 / 政策解读），**只做普通金融知识解答与公司产品介绍，绝不产生推荐清单**，来源引用 + 兜底转人工话术；识别到购买/开户意图时引导注册；**提出产品推荐诉求 → 引导注册并签约投资顾问**（签约后由投顾Agent 提供专业推荐）
- 注册/登录入口

### 2.2 注册、登录与账户
- 注册：手机号 + 短信验证码（Mock）+ 密码 → 创建客户账号 → 预置首次登录引导
- 登录：username/password → Mock JWT（HS256，24h，含 user_type/employee_role/customer_level）→ 按角色路由到对应工作台
- 密码安全：哈希存储（bcrypt），不落明文；Token 鉴权中间件；禁用账号校验
- RBAC：客户 / 投顾 / 风控专员 / 运营（管理员）四类角色，接口级权限依赖注入

### 2.3 客户Web端
| 模块 | 说明 |
|---|---|
| 产品浏览 | 列表/搜索/详情，净值走势图（折线图，数据来自净值表） |
| **风险评估问卷** | 购买前置：未完成问卷或问卷过期（1年）不可购买任何产品。问卷作答 → 计算总分 → C1-C5 风险等级 → 回写画像；**客户等级**（普通/金卡/白金/钻石/私行）由资产规模+风评自动评定，下载产品范围由风险等级控制 |
| **购买流程** | 选产品 → 适当性校验（C↔R 匹配，C1 仅 R1，逐级放宽，不匹配拦截 40105 错误）→ 是否已填问卷/在有效期 → 生成申购申请单 → 提交风控 Agent 实时检查 → 通过则按净值确认扣款并更新持仓；**命中规则则订单挂起等待风控处置**（见 2.5） |
| 持仓与交易 | 当前持仓（成本/市值/盈亏）、成交流水、在途申请单（可撤单未确认单） |
| 申诉与其他 | 撤单、风险等级复核（可重做问卷，一年一次） |
| **我的客服 Agent** | 登录态基金问答：RAG + 短期记忆（Redis）；**长期记忆**（Milvus `customer_memory`）；每次对话结束执行**主客观分类/观点提炼/行为推断**（§4）→ 更新记忆单元与用户画像（置信度+变更日志）。**职责边界：只答普通金融知识与介绍公司产品，不做任何推荐**；持仓/交易类问题引导至对应页面而非代答；**推荐诉求或高净值用户（钻石/私行 或 total_assets≥门槛，sys_config）→ 主动引导签约投资顾问（未签约）或转接专属投顾（已签约）** |
| 我的投顾 | 展示分配投顾信息；**未签约可发起「签约投顾」申请**（开通正式专业推荐服务）；已签约展示专属投顾与收到的推荐/调仓方案（可确认/拒绝）、通知 |
| 个人中心 | 资料、改密、脱敏展示身份证/手机号、消息中心（站内信）、我的公告 |

### 2.4 投顾工作台
| 模块 | 说明 |
|---|---|
| 客户管理 | 名下客户列表（搜索/按等级/风险分类）、客户详情（画像、风评历史、持仓、交易、聊天记录、规则命中等）、客户分配/转介 |
| 画像与研判 | 查看四维研判结果、画像标签置信度、手工修正画像（触发审计） |
| **签约与服务** | 接收客户「投顾签约」工单（客服Agent 引导而来或客户主动发起）→ 查看画像确认服务资格 → 认领/签约 → 客户关系状态置「已签约」并通知客户；**签约前投顾Agent 仅在内部使用，签约后推荐的推荐/调仓方案正式触达客户** |
| **投顾Agent** | 输入「给客户X推荐3只稳健基金」→ 读取画像 → 适当性过滤 → **GraphRAG 多跳增强**（行业集中度/同风格产品/经理关联）→ 综合排序 → 生成推荐理由与资产配置建议 → 产出推荐报告（**必须附免责声明**），投顾审核后通过站内信触达客户。AI **不直接代客下单** |
| **调仓与再平衡** | 画像风险等级 → 目标配置基准（portfolio_benchmark）→ 当前持仓市值归因 → 逐组合计算**偏离度**，超阈值（±X% 可配）自动生成**调仓建议**（超配→赎回清单 / 低配→申购清单 + 金额 + 适当性校验 + 图谱约束行业不过度集中）→ 投顾审核 → **客户 Web 端确认授权** → 生成交易申请单走风控Agent（§2.5）。**每日监测**：持仓变动/风险等级变化/市场异动后自动重算并提示。执行前 AI 不代客下单 |
| **基金深度分析** | 单基金深度分析：区间收益/最大回撤/夏普/波动率/年化（基于 fund_nav_history，定时任务缓存至 `fund_performance`）+ 基金经理/持仓风格/行业暴露/费率，GraphRAG 补充关联 |
| **多维对比与可视化** | 多基金对比（收益/风险/回撤/夏普/费率的雷达图+表格）、净值走势对比、组合配置饼图、持仓行业穿透（ECharts 可视化，数据后端计算） |
| **拦截触达客户** | 名下客户购买被风控拦截 → 工作台待办 + 站内信通知 → 查看订单/命中规则/预警详情 → **一键沟通**：站内信模板回复客户 或 标记「已电话联系」（回写沟通记录与工单），供风控处置留证 |
| 辅助工具 | 单一客户话术提示、待办（新增客户、**签约请求**、风评临期、**拦截待沟通**、风控事件涉及客户） |

### 2.5 风控控制台
| 模块 | 说明 |
|---|---|
| 实时监控 | 每笔申购申请单提交即进入风控 Agent；规则引擎逐条匹配（20 条规则：大额交易 / 频繁交易 / 快进快出 / 短期集中 / 洗钱特征等） |
| **阻断与处置闭环** | 命中规则 → 订单状态置「**风控挂起**」→ 生成预警记录（分级 蓝/黄/红 + 置信度）→ **控制台页面出现待处理卡片**（交易摘要+命中规则+关联信息）→ 风控专员处置：**放行**（订单继续确认）/ **拦截**（订单作废，通知客户）/ **冻结客户**（禁止交易，转工单复核）→ 处置结果回写订单与预警表 |
| 预警工作台 | 预警列表/详情/筛选（级别、状态、类型）、处置留痕、大屏统计（今日预警数、命中率、按规则分布） |
| 规则管理 | 规则启停、阈值配置（规则表驱动，可运营调整，改前留审计） |
| 事件联动 | **申购/赎回被拦截 → 广播 `event:purchase_blocked` → 该客户名下的投顾收到站内信 + 工作台提醒（红点/未读），主动沟通客户**；高等级预警同步提示投顾工作台与客服端「注意」；预警生成可疑交易上报工单。全部双写落 MySQL，Pub/Sub 只作实时通知 |

### 2.6 运营管理端（企业级新增）
- 产品管理：基金上架/下架、费率/风险等级/起投额维护、**净值维护（日更）**
- 公告管理、问卷与题目管理（题目/选项/分值可配，作答按版本记录）
- 知识库管理：文档上传（txt/md/docx）→ 解析分块（512 token/64 overlap）→ Embedding → Milvus 入库，元数据登记（含原文存 MySQL），FAQ 维护，删除/过期策略
- 员工与角色管理、规则管理（同上）、系统监控（接口/预警趋势/四库健康）

### 2.7 企业级公共能力
- 统一响应 `{code,message,data,trace_id}` + 全局异常 + 分级日志（info/error，日志脱敏）
- 操作审计（audit_log：谁在什么时间做了什么）
- 数据脱敏过滤器（身份证/手机/姓名/卡号，员工可见全量、客户前端脱敏）
- 幂等下单（Redis 分布式锁 + order_no 唯一键，防重复申购）
- Redis 限流（登录/客服接口）
- SSE 流式输出（客服/投顾回答打字机）
- 定时任务：净值更新、持仓市值重估、风评过期检测、置信度周期校准、知识过期清理（APScheduler）
- 多级降级：LLM 指数退避重试→备用模型→兜底话术；Milvus 超时→MySQL LIKE；Neo4j 超时→仅 RAG；Redis 挂→直连 MySQL

---

## 3. 四个数据库设计

### 3.1 MySQL 表（约 24 张，在原 10 张基础上扩展）

**沿用并调整：**

| 表 | 用途 | 关键调整 |
|---|---|---|
| `sys_user` | 统一用户（客户/员工） | password_hash 用 bcrypt；加 phone/nickname/status |
| `fin_customer_profile` | 客户画像 | 加 `profile_version`、`customer_level` |
| `fin_product` | 公募基金产品 | 字段改基金特征：fund_code、unit_nav、nav_date、fee_rate |
| `fin_transaction` | 成交流水 | 加 `order_id` 关联申请单 |
| `fin_holdings` | 持仓 | 不变 |
| `fin_risk_assessment` | 风评记录 | 加 `question_version` |
| `fin_risk_alert` | 风控预警 | 加 `order_id`、`confidence`、`handle_time` |
| `biz_work_order` | 通用工单 | 状态机沿用原文档 |
| `conversation_archive` | 会话归档 | 加索引 (user_id, agent_type, create_time) |
| `fin_knowledge_meta` | 知识元数据 | **加 `raw_content` LONGTEXT 替代 MinIO**；加 `file_path` 指向本地上传原文件 |

**新增：**

| 表 | 用途 |
|---|---|
| `customer_relation` | 客户-投顾分配（customer_id, advisor_id, assign_time, end_time, status=已分配/已签约/已结束）——**签约状态**驱动客服引导与投顾服务范围，见 §2.3/2.4 |
| `fund_nav_history` | 净值历史（product_id, nav_date, unit_nav, accumulated_nav, daily_growth） |
| `trade_order` | **交易申请单**（order_no 唯一, order_type 申购/赎回, amount, status=待确认/风控挂起/已确认/已撤单/失败, risk_alert_id）——「挂起→处置→回写」闭环的主表 |
| `ops_questionnaire` | 问卷模板（类型：风险测评/投资者分类，version） |
| `ops_question` | 题目（问卷、题号、题干、选项JSON、分值JSON） |
| `risk_rule` | 风控规则（rule_id, 条件, 阈值, 风险级别, 权重, 状态）——规则引擎表驱动 |
| `customer_profile_change_log` | 画像变更审计（字段、旧值、新值、来源、置信度、原因） |
| `audit_log` | 操作审计（user, action, module, target, detail, ip, trace_id） |
| `sys_announcement` | 官网公告 |
| `sys_message` | 站内信/消息中心（user_id, type, is_read） |
| `memory_unit` | **记忆单元**（tag, content, info_type=FACT/OPINION, source, confidence, evidence/conflict/recall_count, status, valid_until）——记忆架构主体，见 §4 |
| `fund_performance` | 基金业绩指标缓存（近1月/3月/6月/1年/成立以来收益、年化波动率、最大回撤、夏普比率、计算日期）——定时任务从净值计算 |
| `portfolio_benchmark` | **组合基准配置**（risk_level → 目标资产类别权重，如 R1=货币50/债券40/股票10，可运营调整）——再平衡的参照系 |
| `sys_config` | 运营参数 KV（**高净值门槛**、偏离度阈值、风控开关等，免发版调整） |

### 3.2 Milvus 集合（3 个业务集 + 1 个记忆集）

| 集合 | 内容 | 维度 | 索引/度量 | TopK/阈值 |
|---|---|---|---|---|
| `fin_faq` | FAQ 问答对（40 组 + 扩展） | 1024（bge-large-zh） | HNSW / COSINE | 3 / 0.75 |
| `fin_fund_doc` | 基金产品说明、公司业务、政策法规 | 1024 | IVF_FLAT / COSINE | 5 / 0.7 |
| `fin_policy` | 政策法规 | 1024 | IVF_FLAT / COSINE | 5 / 0.7 |
| `customer_memory` | **客户长期记忆**：对话摘要/画像标签向量，metadata 含 `customer_id`，检索时 `expr: customer_id == X` 过滤 | 1024 | HNSW / COSINE | 5 / 0.6 |

### 3.3 Redis Key 设计

| Key | 类型 | TTL | 用途 |
|---|---|---|---|
| `session:{session_id}:messages` | List | 30min（最长24h） | 短期会话记忆，Token≤4096 截断 |
| `profile:{customer_id}` | Hash | 7d（访问续期） | 画像热缓存（Cache-Aside） |
| `product:list:{biz}` / `product:detail:{id}` | String/Hash | 1h | 产品缓存 |
| `order:lock:{order_no}` | String | 60s | 下单幂等锁 |
| `risk:alert:pending` | Set | 永久（伴随消费） | 待处理预警快速统计/去重 |
| `rate:limit:{user_id}:{action}` | String | 滑动窗口 | 登录/对话限流 |
| `token:blacklist:{jti}` | String | 剩余有效期 | 登出/封禁 |
| `verify:code:{phone}` | String | 5min | 短信验证码 Mock |
| **频道** | | | `event:risk_alert` / `event:profile_update` / `event:work_order_change` / `event:knowledge_update`（Pub/Sub 双写：事件同时落 MySQL 表保证不丢） |

### 3.4 Neo4j 图谱模型

- **节点**：`Customer`、`Product`、`FundManager`、`Industry`、`Market`、`RiskLevel`
- **关系**：`HAS_RISK_LEVEL`、`INVESTS_IN`、`BELONGS_TO(产品→行业)`、`MANAGED_BY(产品→经理)`、`SUITABLE_FOR(产品→风险等级)`、`LOCATED_IN(行业→市场)`
- 数据导入脚本：MySQL → 全量产品/客户/持仓/风评 → Cypher MERGE 导入；Mock 行业/市场/经理
- 封装 Cypher Tool：`get_customer_products` / `get_suitable_products` / `get_industry_distribution` / `get_manager_products` / `get_peer_products`

---

## 4. 记忆架构设计（依据《记忆架构设计.html》v2.3）

记忆的本质是**提取 → 存储 → 衰减 → 召回**闭环。核心约束/目标：客户 Agent 长期记忆、读聊天记录更新画像、画像不为一句情绪话而失真。

### 4.1 三层记忆与四库映射

| 层 | 存储 | 内容 | 生命周期 |
|---|---|---|---|
| 短期 | Redis `session:{id}:messages` | 会话上下文 | 30min TTL（最长24h），Token≤4096 截断 |
| 中期 | MySQL `memory_unit` + Redis 热缓存 | **记忆单元**（事实 FACT / 观点 OPINION 分离） | 缓存 Cache-Aside 7d 续期；单元常驻可审计 |
| 长期 | Milvus `customer_memory`（语义经验）+ Neo4j 图谱（关系记忆） | 经验向量、客户-产品关系 | 遗忘周期管理（§4.5） |

一句话：不同价值的信息用不同存储策略——购物小票（会话）和房产证（长期记忆）不放进同一个抽屉。

### 4.2 记忆单元数据模型（`memory_unit` 表，核心）

| 字段 | 说明 |
|---|---|
| id / customer_id | UUID / 归属客户 |
| tag / content | 标签名（如 `risk_preference`）/ 内容（如"偏好稳健型"） |
| info_type | `FACT` 客观事实 / `OPINION` 主观观点 |
| source | 风评问卷 / 行为推断 / AI对话提取 / 用户自述 / 系统默认 |
| source_confidence | 来源初始置信度 |
| confidence | 当前置信度（动态计算） |
| evidence_count / conflict_count / recall_count | 证据数 / 冲突数 / 召回次数 |
| create/update/last_recall_time | 创建 / 更新 / 最后召回时间 |
| status | active / demoted / archived / deleted |
| valid_until | 有效期（过期需重新验证） |

### 4.3 信息提取层（写入侧）

- **主客观分类器**：LLM 判定 FACT/OPINION。**红线：主观观点绝不冒充客观事实入库**——"我觉得基金都不好"只存为低置信 OPINION，可衰减、可修正，不直接改变客户风险等级或可购产品范围；可被系统验证的（年龄/交易/风评）才入 FACT。
- **观点提炼**：对话 → 结构化标签 `{tag, type, confidence, evidence}`；输出错误走六维校验（枚举值/数值范围/时间逻辑/来源/标签/格式）。
- **行为推断**（初始置信 0.8，**行为比语言真实**）：频繁查看某基金净值→"关注该基金"；连续赎回同类产品→"对该类失去信心"；风评得分逐年上升→"风险承受能力提升"；多次咨询养老产品→"有养老规划需求"；多次询问产品推荐/投顾服务→"有专业投顾服务意愿"（触发签约引导，§2.3）。
- **去重合并**：向量相似度判同一观点 → `evidence_count+1` → 重算置信度；新观点则新建单元。
- **矛盾检测**：opinion 两两 LLM 判定或向量相似度+情感极性 → 双方 `conflict_count+1`、置信下降（如"喜欢高风险" vs "高风险太吓人"，两条都真、带时间戳并存，不覆盖、不无限累积）。

### 4.4 置信度引擎

- 来源初始值：风评问卷 0.90 / 行为推断 0.80 / AI 对话提取 0.60 / 用户自述 0.40 / 系统默认 0.20
- 公式：`score = (base + min(evidence×0.05, 0.30) − conflict×0.10) × max(0, 1 − age_days/365×0.20)`，钳制 [0,1]
- 时效性分（重排用）：`exp(−age_days/180)`（半年半衰期，指数衰减更符合记忆衰退直觉）
- 全部参数配置化，随业务校准，不硬编码

### 4.5 遗忘机制（每周维护任务）

| 当前置信度 | 年龄 | 命运 |
|---|---|---|
| ≥ 0.7 | — | active，保留并进入长期 |
| 0.3 ~ 0.7 | — | demoted，降权、减少召回 |
| < 0.3 | > 180 天 | archived 归档（可回溯） |
| < 0.3 | > 270 天 | deleted 删除 |

与原有"置信度周期校准"调度合并为同一每周任务：**重算置信度 → 矛盾检测 → 遗忘决策 → 更新存储**，周期复检（CHECK_INTERVAL=7d）。

### 4.6 记忆编排器（MemoryOrchestrator 服务组件）

- `process_dialogue`：主客观分类 → 事实/观点提炼 + 行为推断 → 矛盾检测 → 置信度计算 → 六维校验 → 写 MySQL `memory_unit` + Milvus `customer_memory` + 失效 Redis 缓存 → 同步短期记忆 → Pub/Sub `event:profile_update`
- `recall` 召回：Milvus 向量 + `memory_unit` 精确查询 → `recall_count+1` → **综合重排**（置信分 × 场景权重 × 时效性，场景权重沿用原需求文档 F4.3 FinalConfidenceRank：产品推荐/风险研判/客户画像/知识检索）→ TopK
- 写入触发源：客服/投顾对话结束（异步）、交易申购/赎回（行为）、风评答卷（结构化）
- 召回场景：客服 Agent 回复前、投顾 Agent 推荐前

### 4.7 合规边界（企业级新增）

- **主客观分离防误导**：一句情绪话不改变客户等级与适当性范围；可用产品由风评/行为/交易事实决定
- **被遗忘权**：用户可申请遗忘 → 删除/降权主观观点；客观交易/风评数据按法定保存期保留并脱敏，操作留审计
- **元认知**：置信度低或矛盾多时，Agent 主动确认（"我可能记得不太清楚，您能确认一下吗？"，置信度阈值可配置）

---

## 5. Agent 设计

**统一执行骨架**（四 Agent 共用）：输入接收 → 记忆召回（短/中/长）→ 意图路由 → 核心逻辑（RAG/GraphRAG/NL2SQL/规则）→ 结果输出（SSE）→ 数据沉淀（会话归档）→ 事件广播。

| Agent | 服务对象 | 核心逻辑 | 记忆 | 关键合规 |
|---|---|---|---|---|
| 客服Agent | 匿名访客、登录客户 | 意图识别 + RAG + 多轮；**仅普通金融知识 + 公司产品介绍，不推荐** | 短:Redis；长:customer_memory；对话→画像标签抽取 | 推荐诉求 / 高净值用户 → **引导签约投顾（§2.3/2.4）**；持仓账户类问题引导至对应页面；无法回答→转人工话术 |
| 投顾Agent | 投顾（内部） | 画像 + 适当性过滤 + GraphRAG 排序 → 推荐报告；**组合偏离度计算与调仓方案生成（§2.4）+ 每日组合监控** | 中:画像缓存；长:图谱+memory_unit | 调仓方案须投顾审核 + 客户确认才生成交易申请单；报告附免责声明；C1 绝不推 R4+；**不代客下单** |
| 风控Agent | 风控专员 | 20 条规则引擎 + 置信度分级 → 阻断/预警 | 短:事件缓存；长期:预警记录 | 阻断即挂起订单，人工处置才放行 |
| 数据分析Agent(加分) | 运营/投顾 | NL2SQL：动态 Schema 注入 + 安全校验(仅SELECT) + 结果解读 | 中:MySQL+Redis | 只读；结果含自然语言解读；面向客户报告附免责 |

**画像更新链路**（客户Agent 核心需求，详见 §4）：对话 → **主客观分类** → 事实/观点提炼 + 行为推断 → 矛盾检测 → 置信度计算（§4.4 公式）→ 写 `memory_unit` + `customer_memory` 向量 + 失效 Redis 缓存 → 变更日志 + Pub/Sub `event:profile_update` → 投顾端感知。

**事件协作**：风控→投顾（**申购被拦截→通知投顾联系客户**、高预警提示）、客服→风控（高风险意图上报）、画像变更→投顾。全部双写保证不丢。

---

## 6. 分阶段开发计划（约 6 周）

### Phase 0｜基础设施（第 1 周 · 前 3 天）
- **复用现有 `Memory_demo` 骨架**：四库懒连接单例（已验通）
- docker-compose 一键起 MySQL/Milvus/Neo4j/Redis（含本地 Embedding 模型可选）
- 全量建表（3.1 节 ~24 张）+ Mock 数据生成（5 位测试客户、40 只基金、20 条规则、净值 90 天序列、FAQ）；Mock 数据需符合原文档 1.4 节约束（收益率区间/交易时间线/金额合理）
- 统一响应/全局异常/日志/路由前缀规范
- **验收**：四库 `/health/ready` 全 ok；20 张表建齐；Mock 数据可查询

### Phase 1｜官网 + 注册登录 + 知识库 + 客服Agent（第 1 周后半 ~ 第 2 周）
- 前端工程初始化（Vue3+Vite+Element Plus），四入口路由雏形
- 官网首页：公司介绍/产品展示（列表/详情/净值图）/公告/客服浮窗
- 注册（验证码 Mock）→ **自动分配投顾**；登录 → JWT + RBAC → 角色路由
- 知识库搭建：文档解析（txt/md/docx）→ 分块 → Embedding → Milvus 入库，`fin_knowledge_meta` 原文 + 元数据登记，上传/列表/删除/检索接口
- 客服Agent：意图识别 + RAG 检索 + Redis 短期记忆 + 兜底策略 + SSE；**职责边界内置：产品推荐诉求仅引导注册+签约投顾，不直接推荐**
- **验收**：官网可匿名浏览并能与客服Agent 对话（≥5 类基金问题准确率≥80%）；注册后自动分配到投顾；登录按角色跳到对应端

### Phase 2｜客户Web端（第 3 周 ~ 第 4 周前半）
- 风险测评问卷（16 题，题目/评分可配）→ C1-C5 → 客户等级评定；购买前置拦截（未问卷/过期不可购买）
- 产品浏览 + 适当性校验 + **申购申请单**（幂等锁）→ 净值确认 → 更新持仓；赎回/撤单/持仓/交易/在途查询
- 画像系统：四维研判引擎 + 标签置信度 + 冲突策略 + 变更日志
- **客户Agent 增强**：长期记忆（customer_memory 写入/读取）+ **主客观分类/观点提炼/行为推断（§4.3）** → 记忆单元与画像更新链路
- **客服边界与签约引导**：客服不产生推荐；识别**推荐诉求**或**高净值客户**（customer_level=钻石/私行 或 total_assets≥sys_config 门槛）→ 未签约引导发起「签约投顾」申请（生成工单），已签约引导转接专属投顾
- 个人中心（脱敏、改密、消息中心、我的投顾）
- **验收**：新客户首次购买被问卷拦截；填完问卷 C1 客户不可购 R3+；申购→（直接放行路径）持仓更新成功；Agent 多轮对话后画像出现新标签（查看变更日志）；**主客观分类正确**——"我觉得债券稳"存为可衰减 OPINION、"我35岁/买了10万"存为 FACT，情绪话不改变风险等级（§4）；**客服边界**：请求推荐时客服只引导签约不列清单；高净值（钻石/私行或资产≥门槛）未签约客户收到签约引导提示

### Phase 3｜投顾工作台（第 4 周后半 ~ 第 5 周前半）
- Neo4j 图谱构建 + MySQL 导入脚本 + 图谱统计/可视化接口
- 客户管理：名下客户列表/详情（画像/持仓/风评/交易/聊天记录）、分配与转介
- **签约请求处理**：客户发起（或客服Agent 引导发起）的「投顾签约」工单 → 查看画像确认资格 → 认领/签约 → `customer_relation.status=已签约` → 通知客户；**签约后投顾Agent 的推荐/调仓方案正式触达客户，未签约仅供内部参考**
- **投顾Agent**：画像读取 → 适当性过滤 → GraphRAG 增强 → 推荐排序 → 推荐理由 + 资产配置建议 + 免责声明 → 生成报告 → 站内信触达；审核后才算完成
- **组合诊断与调仓（再平衡）**：portfolio_benchmark 目标配置 → 当前持仓市值归因 → 偏离度计算 → 超阈值自动生成调仓建议（超配赎回/低配申购清单 + 金额 + 适当性校验）→ 投顾审核 → **客户 Web 端确认** → 生成交易申请单（走风控 Agent）；图谱辅助约束行业集中度、推荐同风格替代基金
- **基金深度分析 / 多维对比 / 可视化**：净值 → 业绩指标（区间收益/最大回撤/夏普/波动率，定时任务缓存 fund_performance）+ GraphRAG 补充 → 单基金深度分析、多基金对比、ECharts 可视化（净值走势 / 收益-风险散点 / 配置雷达 / 行业穿透）
- **验收**：图谱节点>300/关系>2000；投顾Agent 推荐不越适当性红线（对 5 位测试客户逐一验证）；推荐理由引用画像；报告附免责声明；风控事件涉及客户时工作台出现提示（含拦截待沟通待办）；**构造偏离样例（如债券超配/股基低配）→ 自动生成调仓清单、金额正确、不越适当性红线，客户确认后生成交易申请单并进入风控监控**；**签约闭环：客户提交签约申请 → 投顾认领后客户侧显示专属投顾、客服不再引导签约（customer_relation.status 正确流转）**

### Phase 4｜风控控制台（第 5 周后半 ~ 第 6 周前半）
- 20 条规则引擎（risk_rule 表驱动）+ 三级预警分级 + 置信度（参考 F4.3 公式）
- 交易实时接入：申购/赎回提交即进风控 Agent
- **阻断与处置闭环**：命中 → 订单「风控挂起」→ 预警卡片 → 页面待处理列表 → 专员 放行/拦截/冻结 → 回写订单与客户状态
- 预警工作台 + 趋势统计 + 规则管理页（启停/阈值）
- Redis Pub/Sub 事件联动 + 可疑交易上报工单
- **验收**：用 10 组 Mock 异常交易验证 20 条规则；命中后订单在页面出现且客户侧显示「审核中」；放行后订单继续确认、拦截后作废并通知；高等级预警触发投顾/客服端提示；**拦截子场景**：客户申购被拦截 → 该客户名下投顾工作台出现待办+站内信 → 投顾查看预警详情并标记「已联系客户」 → 回写沟通记录至工单（全链路可查）

### Phase 5｜运营后台 + 企业级加固 + 集成联调（第 6 周后半 ~ 第 7 周）
- 运营后台：产品/净值/公告/问卷/知识库/员工与角色/系统监控页面
- 公共能力落地：审计日志、脱敏、幂等、限流、SSE、事件双写补全
- 定时任务：净值更新、持仓重估、**组合每日监控（偏离度盘点 → 超阈值自动生成调仓建议并通知投顾，§2.4）**、风评过期检测、**记忆每周维护（置信度重算 + 矛盾检测 + 遗忘归档淘汰，§4.5）**、知识过期清理
- 数据分析Agent（NL2SQL，正式实现，作为加分项）+ 系统监控大屏
- **端到端联调**：官网注册→问卷→购买→风控命中→处置→投顾推荐 全链路演示；5 位测试客户 + 边界 case（无画像、超长对话、SQL 注入、并发、适当性违规）
- 性能达标：RAG<2s、Agent 回答<5s（SSE）；降级路径逐一验证
- 交付：README（目录/启动/配置）、API 文档、数据库文档、演示脚本、答辩 PPT、会议纪要

---

## 7. 里程碑与交付物

| 里程碑 | 时间 | 交付物 |
|---|---|---|
| M0 基建就绪 | 第 1 周 | 四库 docker-compose、建表脚本、Mock 数据、骨架可启动 |
| M1 官网可注册 + 客服Agent可用 | 第 2 周末 | 官网/注册登录/知识库/客服对话 |
| M2 客户可购买 | 第 4 周前 | 问卷+适当性+申购闭环 |
| M3 投顾可推荐 | 第 5 周前 | Neo4j 图谱、投顾Agent 报告 |
| M4 风控可拦截处置 | 第 6 周前 | 规则引擎、阻断闭环、预警工作台 |
| M5 全链路可演示 | 第 7 周 | 运营后台、审计/监控、端到端演示、答辩材料 |

## 8. 团队分工（可按实际人数合并）

| 角色 | 负责 |
|---|---|
| 后端/架构 | FastAPI、四库接入、订单/交易/画像核心链路、审计/脱敏/限流 |
| AI/Agent | RAG、NL2SQL、客服Agent、画像抽取、置信度 |
| 图谱/数据 | Neo4j 构建、GraphRAG、Mock 数据、定时任务 |
| 业务/风控 | 风评问卷、画像研判、20 条规则引擎、阻断闭环 |
| 前端 | Vue3 四端页面、SSE 流式、图表 |
| 集成 | 事件总线、端到端联调、演示、文档 |

## 9. 风险与对策

| 风险 | 对策 |
|---|---|
| 四库集群资源占用大（Milvus/Neo4j 内存） | docker-compose 资源限制；小数据量集合用存量数据起步；本地 bge-large-zh 避免 API 费用 |
| LLM 延迟/不稳 | 指数退避重试 + 备用模型 + 兜底话术；检索/图谱超时降级 |
| 适当性红线被绕过 | 购买下单服务内强制校验（不依赖前端）+ 单测覆盖 C1→R3+ 用例 |
| 订单与风控状态一致性 | `trade_order` 单一状态机 + 处置接口幂等 + 审计留痕 |
| 时间不足功能裁剪 | 硬优先级：M1-M4 主链路优先；运营后台、NL2SQL、监控大屏为后置项 |

## 附录 A：需求 → 四库映射

| 需求 | MySQL | Milvus | Neo4j | Redis |
|---|---|---|---|---|
| 官网产品展示 | 产品表/净值表 | — | — | 产品缓存 |
| 客服Agent FAQ/政策回答 | 会话归档 | fin_faq/fin_policy | — | 短记忆/限流 |
| 客户长期记忆/画像更新 | memory_unit/画像/变更日志 | customer_memory | — | 画像缓存/事件 |
| 投顾推荐 | 画像+持仓 | 文档向量 | 图谱多跳 | 画像缓存/事件 |
| 购买适当性校验 | 风评/产品 | — | SUITABLE_FOR | 画像缓存 |
| 风控拦截+投顾触达 | trade_order/预警/工单/站内信 | — | 规则-实体 | 事件/pending Set/通知 |
| 调仓与组合监控 | 持仓/基准/业绩指标/订单 | — | 行业集中度/替代基金 | 每日监控锁/待办/通知 |
| 客服引导签约投顾 | customer_relation/工单 | — | — | 画像/记忆缓存 |
| 审计/脱敏/公告/消息 | 对应表 | — | — | 缓存 |