Enhance suitability assessment and documentation

- Implemented `check_suitability` method in `CoreReadOnlyRepository` for suitability determination based on customer and product risk levels. - Added `build_suitability_log_row` function in `suitability.py` for mapping suitability check results to `risk_suitability_log`. - Updated `AGENTS.md`, `ENVIRONMENT.md`, and `FLOW.md` to reflect changes in suitability assessment processes and documentation. - Revised `FRAMEWORK.md` and `MEMORY.md` to clarify project structure and data flow related to suitability checks. - Expanded `TODO.md` with tasks related to logging and auditing suitability assessments.
2026-09-07 11:15:30 +08:00
parent 1ddd44a6cb
commit 3fb0ceb334
44 changed files with 7479 additions and 250 deletions
@@ -14,7 +14,7 @@
 | 内部员工 | 分析、运营、合规 | 问数、报表、抽检会话、协同风控 |
 | 风控 / 合规官 | 风控专员 | 监测大额/适当性/AML；人工审核，不自动冻户 |

-**L0 权威来源（本项目）：** MySQL `jinrong_core` 模拟库 — 客户、C1~C5、持仓、流水、产品、代理人-客户归属。Agent 代码经 `CoreReadOnlyRepository` **只读 SELECT**，不提供 HTTP Core API。
+**L0 权威来源（本项目）：** MySQL `jinrong_core` 模拟库 — KYC、正式 C1~C5、C×R 适当性矩阵、持仓、流水、产品（起购/期限）、代理人-客户归属。Agent 经 `CoreReadOnlyRepository` **只读 SELECT**；R-02 计算在 `check_suitability()`，落库契约见表设计/07。

 ------

@@ -32,7 +32,7 @@ Agent **尚未上线**；后端为脚手架 + 模拟数据，无生产接入。
 ## 3. 主路径（现状 → 模拟后）

 1. 开户/测评 → Core（模拟：`core_customer` + `core_customer_risk`）写 L0
-2. 交易 → Core 流水（模拟：`core_trade`）；交易前适当性（R-02 待实现）
+2. 交易 → Core 流水（模拟：`core_trade`）；交易前适当性：`check_suitability` 已实现，风控 service 落 log 待做（R-02）
 3. 同步 → `sync_advisor_rel.py` 写入 agent 库 `customer_advisor_rel`；`sync_neo4j.py` 灌关系图
 4. 代理人服务 → 查 Core RO + 口头沟通（L2 画像表待业务实现）
 5. 风控 → 规则/人工台账；合规事后抽检
@@ -43,7 +43,7 @@ Agent **尚未上线**；后端为脚手架 + 模拟数据，无生产接入。

 | 名称 | 含义 | 本项目存储 |
 | --- | --- | --- |
-| L0 正式档案 | customer_id、C1~C5、年龄、职业、advisor | `jinrong_core.core_*` |
+| L0 正式档案 | customer_id、KYC、C1~C5、风评过期、advisor | `jinrong_core.core_customer` / `core_customer_risk` |
 | 持仓/流水 | 产品、份额、盈亏 | `core_holding` / `core_trade` |
 | 代理人-客户归属 | 服务关系 | Core 种子 → 同步 `jinrong_agent.customer_advisor_rel` |
 | Agent 会话/画像/审计 | 平台业务数据 | `jinrong_agent`（11 共用表 + agent 专用表） |
@@ -1,7 +1,7 @@
 # 实现流程

 > To-Be 端到端链路；As-Is 见 `ENVIRONMENT.md`  
-> 画像分层见 `docs/项目框架设计/表设计/00-架构总览.md`
+> 画像分层见 `docs/项目框架设计/表设计/06-用户画像L1-L3设计.md` · 适当性见 `07-risk_suitability_log说明.md`

 ------

@@ -19,7 +19,7 @@

 ③ Core 模拟库（L0）
   .\scripts\core\reset.ps1
-   → 创建 jinrong_core + 28 客户 / 12 产品 / 持仓交易种子
+   → 创建 jinrong_core + **33 客户** / **14 产品** / 持仓交易种子（含 CUST-DEMO-* 手册示范）

 ④ Agent 共用底座（若库未建）
   mysql -u root -p < docs/项目框架设计/表设计/01-mysql-共用底座.sql
@@ -64,10 +64,11 @@ memory_service：Redis 读最近 N 轮；异步写 agent_message     【待做
 agent_service：LangGraph StateGraph + DeepSeek；按 Agent 类型选 Tool 节点  【待做】
 ↓
 Tool 示例：
-  - CoreReadOnlyRepository：持仓/流水/L0（自动注入 customer_id）  【Repository 已有，Tool 未接】
+  - CoreReadOnlyRepository：持仓/流水/L0 + check_suitability（R-02 计算）  【Repository 已有，Tool 未接】
+  - model/suitability：check → risk_suitability_log 行映射              【已实现，风控 service 未接】
  - milvus_tool：产品规则 RAG + source_refs                   【待做】
  - memory_service：读/写 L1/L2/L3（ProfileGuard）              【待做】
-  - 风控 service 账号：R-02 适当性（无会话）                    【待做】
+  - 风控 service 账号：R-02 适当性 → check_suitability + INSERT log（无会话）  【待做】
 ↓
 输出：assistant 消息 + has_disclaimer（客户/对外）
 ↓
@@ -105,7 +106,8 @@ admin/knowledge 上传 → document_parser → embedding_tool(Ollama bge-m3)
 | 会话 | session_id | Redis ctx + MySQL session | actor_id 一致 |
 | RAG | question + product_id? | chunks + source_doc_id | 必须溯源 |
 | 画像读 | customer_id | L1/L2/L3 JSON | RBAC 矩阵 §8 |
-| Core RO | customer_id | L0/持仓/流水 | 只读 jinrong_core |
+| Core RO | customer_id + product_id? | L0/持仓/流水；适当性判定 dict | 只读 jinrong_core；R-02 见 07 文档 |
+| 适当性落库 | check_suitability 输出 | risk_suitability_log 行 | build_suitability_log_row |
 | 审计 | 任意判定 | audit_log INSERT | 不可删改 |

 ------
@@ -113,6 +115,8 @@ admin/knowledge 上传 → document_parser → embedding_tool(Ollama bge-m3)
 ## 6. 关键数据约定

 - Agent 库 SQL：`docs/项目框架设计/表设计/01-mysql-共用底座.sql`、`02-mysql-agent专用.sql`
+- 画像 L1/L2/L3：`docs/项目框架设计/表设计/06-用户画像L1-L3设计.md`
+- 适当性 log：`docs/项目框架设计/表设计/07-risk_suitability_log说明.md`
 - Core 模拟：`scripts/core/01-ddl.sql` · 说明 `docs/项目框架设计/Core模拟底座/01-表结构与种子说明.md`
 - Redis Key：`docs/项目框架设计/表设计/02-redis-keys.md`
 - Milvus：`kb_product_rules`、`kb_business_ops`；向量 **1024** 维
@@ -39,7 +39,7 @@
 | 代理人助手 Agent | L2 画像、RAG、草稿 | L1 只读、Milvus | 空壳 service |
 | 数据分析 Agent | NL→SQL→解读 | Core RO、画像只读 | 空壳 service |
 | 风控监测 Agent | 预警、L3、R-02 适当性 | 交易事件、AML 名单 | 空壳 service |
-| Core 只读层 | L0 事实查询 | `jinrong_core` | **core_ro.py 已实现** |
+| Core 只读层 | L0 查询 + R-02 适当性计算 | `jinrong_core` | **core_ro.py + suitability.py 已实现** |
 | 共用底座 | 会话、审计、输入防护 | MySQL 11 表 + Redis | SQL 已定；代码未接 |
 | 同步脚本 | 归属、Neo4j | Core → agent / 图库 | **sync_*.py 已实现** |

@@ -52,7 +52,7 @@ api/          → 路由（chat、knowledge、admin）；薄，不含业务
 service/      → agent_service、rag_service、memory_service           【空壳】
 tool/         → document_parser、embedding_tool、milvus_tool          【空壳】
 repository/   → core_ro（Core 只读）；后续 agent 库 Repository       【core_ro 已实现】
-model/        → schemas（Pydantic）、entities（ORM）                  【占位】
+model/        → suitability（R-02 log 映射）；schemas 占位           【suitability 已实现】
 config/       → settings、database                                     【settings 已实现】
 utils/        → response、exceptions、logger                           【占位】
 main.py       → FastAPI 入口；当前仅 /health                          【部分】
@@ -75,12 +75,15 @@ scripts/dev/        → rbac-seed-reference.md（联调账号）

 | 层 | 存储 | 说明 |
 | --- | --- | --- |
-| L0 | `jinrong_core` 只读 | 正式 C1~C5、持仓、流水（模拟） |
-| L1/L2/L3 | MySQL 画像表（agent 库） | 客户/代理人/风控 enrich |
+| L0 | `jinrong_core` 只读 | KYC、正式 C1~C5、C×R 矩阵、持仓/产品（对齐客户手册） |
+| L1/L2/L3 | MySQL 画像表（agent 库） | 客户/代理人/风控 enrich；**禁止覆盖 L0** |
+| 适当性审计 | `risk_suitability_log` | 风控写；客户/代理人读；契约见表设计/07 |
 | 会话 | Redis + MySQL | 窗口 + 永久审计 |
 | RAG | Milvus + `data/kb/` | kb_product_rules 等 |
 | 关系 | Neo4j | 客户-产品-代理人（Core 同步） |

+**画像 JSON 约定：** [06-用户画像L1-L3设计.md](../项目框架设计/表设计/06-用户画像L1-L3设计.md)
+
 ------

 ## 5. 骨架一句话
@@ -8,3 +8,6 @@
 | 2026-09-05 | Core 模拟库 jinrong_core + 扩大种子 + Neo4j 同步 | 无真实 Core | FRAMEWORK / FLOW / ENVIRONMENT |
 | 2026-09-05 | Agent 编排依赖改为 LangGraph 为主 | 状态图 + Tool 节点 | FRAMEWORK |
 | 2026-09-05 | memory 全量刷新：§0 新 Agent 交接清单 + 实现状态表 + bootstrap | 脚手架已落地，便于无上下文交接 | MEMORY / FRAMEWORK / FLOW / TODO / REQUIREMENTS / ENVIRONMENT |
+| 2026-09-07 | Core 表结构对齐客户资料手册（KYC/风评/适当性矩阵/AML/产品起购期限） | 用户要求与手册一致 | FRAMEWORK / Core模拟底座 / core_ro |
+| 2026-09-07 | risk_suitability_log 扩展 P0 字段，与 check_suitability 一一映射 | 避免 R-02 接入大规模返工 | 表设计/07 · suitability.py · core_ro |
+| 2026-09-07 | 画像 L1/L2/L3 框架文档 06 + memory/业务记忆管理同步 | 用户要求先定文档 | 表设计/06 · MEMORY · FLOW · 业务记忆管理手册 |
@@ -9,7 +9,7 @@

 **项目是什么：** 金融四 Agent（客户财富 / 代理人 / 数据分析 / 风控）共用数据层与合规底座；**不**互调 LLM，跨 Agent 走 L1/L2/L3 画像与预警表。

-**当前进度：** 需求与表设计已定 · 后端 **脚手架 + Core 模拟库脚本** 已落地 · **业务 API / JWT / LangGraph 图尚未实现**（多为空壳模块）。
+**当前进度：** 需求与表设计已定 · **Core 模拟库 + L0 KYC/适当性矩阵 + R-02 计算与 log 契约** 已落地 · **业务 API / JWT / LangGraph 图尚未实现**（多为空壳模块）。

 **仓库地图：**

@@ -18,12 +18,13 @@
 | `app/main.py` | 可跑 | 仅 `/health`；路由未挂载 |
 | `app/api/*.py` | 空壳 | chat / knowledge / admin 待实现 |
 | `app/service/*.py` | 空壳 | agent / rag / memory 待实现 |
-| `app/repository/core_ro.py` | **已实现** | Core 只读 SELECT（jinrong_core） |
+| `app/repository/core_ro.py` | **已实现** | Core 只读 + `check_suitability`（R-02 计算） |
+| `app/model/suitability.py` | **已实现** | R-02 → `risk_suitability_log` 行映射 |
 | `app/config/settings.py` | **已实现** | 双库 `jinrong_agent` + `jinrong_core` |
-| `scripts/core/*.sql` + `reset.ps1` | **已实现** | Core 模拟库 DDL + 种子 |
+| `scripts/core/*.sql` + `reset.ps1` | **已实现** | Core 模拟库 DDL + 种子（33 客户 / 14 产品） |
 | `scripts/sync/*.py` | **已实现** | 归属同步 + Neo4j 全图 |
 | `docs/需求拆解/` | 已定 | 场景 P0、矩阵、合规原文 |
-| `docs/项目框架设计/表设计/` | 已定 | Agent 共用 11 表 + agent 专用 SQL |
+| `docs/项目框架设计/表设计/` | 已定 | Agent 共用 11 表 + 画像/适当性说明 06/07 |
 | `docs/项目框架设计/Core模拟底座/` | 已定 | 无真实 Core 时的 L0 方案 |
 | `web/` | **不存在** | 前端 React 待 init |

@@ -41,7 +42,7 @@

 **下一步开发（见 TODO）：** T-01 JWT 中间件 → 挂载 api → LangGraph agent_service → Wave 0 验收。

-**禁止（改代码前必记）：** Core 正式 C1~C5 不可被画像覆盖 · 审计表只 INSERT · 代理人草稿不外发 · 仅 R-02 可阻断交易 · 四 Agent 不互调 LLM。
+**禁止（改代码前必记）：** Core 正式 C1~C5 不可被画像覆盖 · 审计表只 INSERT · 代理人草稿不外发 · 仅 R-02 可阻断交易 · 四 Agent 不互调 LLM · **客户 Agent 可做适当性匹配说明，禁止营销式推荐/买卖指导**。

 ------

@@ -95,8 +96,8 @@ audit_log 等审计表（只 INSERT）

 ```text
 四 Agent 不互调 LLM；跨 Agent 走 L1/L2/L3 画像与预警表
-客户 Agent：无投资建议/收益承诺/自动下单
-代理人：不对 C 端直发
+客户 Agent：允许按 C1~C5 与产品 R 等级做「是否匹配」说明（C-07/C-11，联动 R-02）；禁止营销推荐、买卖指导、收益承诺、自动下单
+代理人：不对 C 端直发；禁止对比优劣、推荐产品（A-02）
 数据分析：仅 SELECT，不处置预警
 画像不得覆盖 L0 正式测评
 ```
@@ -106,8 +107,9 @@ audit_log 等审计表（只 INSERT）
 ## 4. 入口与运行

 ```text
-后端入口：app/main.py · 配置 app/config/settings.py · Core 只读 app/repository/core_ro.py
+后端入口：app/main.py · 配置 app/config/settings.py · Core 只读 app/repository/core_ro.py · 适当性映射 app/model/suitability.py
 Agent 库 SQL：docs/项目框架设计/表设计/01-mysql-共用底座.sql
+画像/适当性：表设计/06-用户画像L1-L3设计.md · 表设计/07-risk_suitability_log说明.md
 Core 模拟：scripts/core/reset.ps1 · 文档 docs/项目框架设计/Core模拟底座/
 依赖：requirements.txt（LangGraph + langchain-core/openai + FastAPI + SQLAlchemy）
 启动：uvicorn app.main:app --reload → GET /health
@@ -9,7 +9,8 @@
 ## 本轮范围

 - **目的：** 四 Agent 服务四类人群，统一数据层 + 合规底座，可对话闭环。
- **明确不做：** 自动交易、营销推荐、Agent 互调 LLM、自动冻户、Streamlit、P3 平台能力。
+- **明确不做：** 自动交易、**营销式**推荐（千人千面话术/优劣对比/「强烈推荐」）、Agent 互调 LLM、自动冻户、Streamlit、P3 平台能力。
+- **允许（客户 Agent）：** 按客户 C1~C5 与产品 R 等级/期限/起购做 **适当性匹配说明**（C-07 P1、C-11 P2），须联动风控 R-02；**不是**投顾式推荐或买卖指导。

 ------

@@ -20,11 +21,11 @@
 | F-01 | JWT + RBAC + 数据归属 | 越权 403 + audit；JWT 手册 §13 | 未做 | T-01 |
 | F-02 | 全量审计留痕 | trace_id 可还原 | 未做 | T-02 |
 | F-03 | 输入防护 | input_guard_log | 未做 | T-03 |
-| F-04 | Core 只读层 | 不改 Core 账；Repository 只 SELECT | **部分** | T-04 |
-| R0-DB | MySQL 共用 11 表 + Redis | 01-mysql-共用底座.sql | SQL 已定；灌库待验 | T-05 |
-| R0-CORE | Core 模拟 + 同步 | reset.ps1 + sync 脚本 | **脚本已落地** | T-05 |
+| F-04 | Core 只读层 | 不改 Core 账；Repository 只 SELECT | **大部分** | T-04 |
+| R0-DB | MySQL 共用 11 表 + Redis | 01-mysql-共用底座.sql；`risk_suitability_log` P0 字段已定 | SQL 已定；灌库待验 | T-05 |
+| R0-CORE | Core 模拟 + 同步 | reset.ps1 + sync；33 客户 / 14 产品 / KYC / C×R 矩阵 | **脚本已落地** | T-05 |

-**F-04 部分完成说明：** `app/repository/core_ro.py` + `scripts/core/*` + `settings.mysql_core_database` 已有；尚未接入 api/service Tool 与归属校验。
+**F-04 大部分完成说明：** `core_ro.py`（含 `check_suitability`）+ `scripts/core/*` + `settings.mysql_core_database` 已有；`suitability.py` 映射 log 行已定。尚未接入 api/service Tool 与归属校验。

 ## Wave 1 · 内部 Agent P0

@@ -38,13 +39,15 @@
 | ID | 需求 | 验收对照 | 状态 | TODO |
 | --- | --- | --- | --- | --- |
 | R-01 | 大额预警 | risk_alert pending_review | 未做 | T-30 |
-| R-02 | 适当性阻断请求 | 唯一阻断场景 | 未做 | T-31 |
+| R-02 | 适当性阻断请求 | 唯一阻断场景；log 表 + 映射代码已定 | **契约已定** | T-31 |
 | R-03 | AML 命中通知 | 不自动冻户 | 未做 | T-32 |

 ## Wave 3 · 客户 P0

 | ID | 需求 | 验收对照 | 状态 | TODO |
 | --- | --- | --- | --- | --- |
-| C-01~C-05 | 持仓/产品/规则/阈值/净值 | 无买卖指导 | 未做 | T-40 |
+| C-01~C-05 | 持仓/产品/规则/阈值/净值 | 无买卖指导；P0 不含匹配推荐 | 未做 | T-40 |
+| C-07 | 风格测评 + 同类方向事实清单 | 须 R-02 适当性；无买卖指令 | 未做 | T-41 |
+| C-11 | 按风险/期限/起购做匹配说明 | 非营销话术；不替代投顾 | 未做 | T-42 |

 P1+ 见 `docs/需求拆解/业务场景优先级清单.md` §3。
@@ -15,6 +15,7 @@
 - [ ] T-06 挂载 `app.api` 路由到 `main.py`；chat 最小闭环
 - [ ] T-07 LangGraph `agent_service` StateGraph 骨架 + DeepSeek
 - [ ] T-04 Core RO 封装为 Tool 节点；A-01 归属校验
+- [ ] T-31 R-02 风控 service：check_suitability → build_suitability_log_row → INSERT log + audit
 - [ ] T-21 Milvus Lite + kb_product_rules 首批入库
 - [ ] 前端 React 多 Agent 入口（HashRouter，`web/` init）

@@ -26,4 +27,6 @@
 - [x] 2026-09-05 Core 模拟库 `scripts/core/*` + `reset.ps1` + 文档
 - [x] 2026-09-05 `core_ro.py` + `settings.mysql_core_database` + sync 脚本
 - [x] 2026-09-05 Agent 编排依赖改为 LangGraph（requirements.txt）
- [x] 2026-09-05 memory 文件夹更新（新 Agent 交接清单）
+- [x] 2026-09-07 Core DDL/种子对齐客户手册（KYC、风评、C×R 矩阵、AML、产品起购期限；33 客户 / 14 产品）
+- [x] 2026-09-07 `check_suitability` + `risk_suitability_log` P0 字段 + `app/model/suitability.py` + 表设计/07
+- [x] 2026-09-07 画像框架文档 `表设计/06-用户画像L1-L3设计.md` + memory 同步