Add core database support and enhance documentation
- Introduced `MYSQL_CORE_DATABASE` in `.env.example` and `settings.py` for core database configuration. - Added `CoreReadOnlyRepository` for read-only access to the `jinrong_core` database. - Updated `AGENTS.md`, `README.md`, and various documentation files to reflect new agent onboarding processes and project structure. - Revised requirements in `requirements.txt` to include `langgraph` and `langchain-core`. - Enhanced `FLOW.md` with local bootstrap instructions for setting up the core simulation environment. - Added new scripts for database creation and seeding for the core simulation library. - Improved overall documentation for clarity on project architecture and memory management. - Updated `TODO.md` to reflect current development priorities and tasks.
This commit is contained in:
@@ -0,0 +1,264 @@
|
||||
# Core 模拟底座方案（无真实 Core、无 HTTP API）
|
||||
|
||||
> 状态：**已落地**（2026-09-05）
|
||||
> 详见 [01-表结构与种子说明.md](./01-表结构与种子说明.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 要解决什么问题
|
||||
|
||||
| 需求 | 没有 Core 时的问题 | 本方案 |
|
||||
| --- | --- | --- |
|
||||
| C-01/A-01 查持仓 | 无数据 | 种子持仓表 |
|
||||
| R-02 适当性 | 无 C1~C5 / 产品 R 等级 | 种子测评 + 产品风险等级 |
|
||||
| F-01 代理人只看名下客户 | 无归属 | 种子归属 + 同步到 `customer_advisor_rel` |
|
||||
| D-01 分析 Agent 查数 | 无宽表 | Core 库可被只读 SQL 查（同 MySQL 实例） |
|
||||
| R-01 大额监测 | 无交易流 | 种子交易 + 可选「注入脚本」模拟新交易 |
|
||||
| Neo4j 关系图 | 无源 | 从 Core 库 **同步脚本** 灌图 |
|
||||
|
||||
**不做什么：**
|
||||
|
||||
- 不模拟真实 TA/清算/报盘
|
||||
- 不提供 HTTP Core API（以后有真 Core 再换 Adapter，Repository 接口不变）
|
||||
- 不让 Agent 写 Core 库（无 UPDATE/INSERT 权限或代码层禁止）
|
||||
|
||||
---
|
||||
|
||||
## 2. 推荐架构（方案 A · 首选）
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ MySQL 8.0（本机 :3306，同一实例两个库） │
|
||||
├─────────────────────────┬───────────────────────────────┤
|
||||
│ jinrong_core │ jinrong_agent │
|
||||
│ 【模拟 Core · L0 权威】 │ 【Agent 平台 · 已有 16 表】 │
|
||||
│ 客户/产品/持仓/流水/测评 │ 会话/画像/预警/审计 │
|
||||
│ ★ Agent 只读 SELECT │ Agent 读写 │
|
||||
└───────────┬─────────────┴───────────────┬───────────────┘
|
||||
│ │
|
||||
│ scripts/sync/*.py │
|
||||
└──────────► customer_advisor_rel (agent 库)
|
||||
└──────────► Neo4j (可选 sync_neo4j.py)
|
||||
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ app/repository/core_ro.py │
|
||||
│ 只读 SQL · 禁止写 · 供 Tool / 分析 Agent 白名单 schema │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 为何不用 API、不用 JSON 文件？
|
||||
|
||||
| 方案 | 优点 | 缺点 | 结论 |
|
||||
| --- | --- | --- | --- |
|
||||
| **A. 独立库 jinrong_core + SQL 种子** | 贴近真 Core；D-01 可直接 SELECT；易 reset | 多一套 DDL | **推荐** |
|
||||
| B. JSON/YAML fixtures | 简单 | 分析 Agent 难 SQL；大数据量慢 | 仅适合单元测试 |
|
||||
| C. 全塞进 agent 库 | 一张库 | 违反「Core / Agent 分治」；合规演示不清 | 不推荐 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 库与目录规划
|
||||
|
||||
```text
|
||||
scripts/
|
||||
└── core/
|
||||
├── 00-create-database.sql # CREATE DATABASE jinrong_core
|
||||
├── 01-ddl.sql # Core 表结构
|
||||
├── 02-seed-base.sql # 产品、代理人、风险等级字典
|
||||
├── 03-seed-customers.sql # 客户 L0 + 测评
|
||||
├── 04-seed-holdings.sql # 持仓
|
||||
├── 05-seed-trades.sql # 流水/交易（含 R-01 大额样例）
|
||||
├── 06-seed-nav.sql # 净值/行情（C-05）
|
||||
├── reset.ps1 # Windows：drop 数据 + 重跑 seed
|
||||
└── README.md # 执行顺序
|
||||
|
||||
scripts/sync/
|
||||
├── sync_advisor_rel.py # core → jinrong_agent.customer_advisor_rel
|
||||
└── sync_neo4j.py # core → Neo4j（P0 可选第二批）
|
||||
|
||||
app/
|
||||
└── repository/
|
||||
├── __init__.py
|
||||
└── core_ro.py # 只读查询封装（无 HTTP）
|
||||
|
||||
docs/项目框架设计/Core模拟底座/
|
||||
├── 00-方案总览.md # 本文件
|
||||
└── 01-表结构与种子说明.md # 确认后补充字段级文档
|
||||
```
|
||||
|
||||
**执行顺序（开发/答辩前）：**
|
||||
|
||||
```text
|
||||
1. mysql < scripts/core/00-create-database.sql
|
||||
2. mysql < scripts/core/01-ddl.sql
|
||||
3. mysql < scripts/core/02~06-seed-*.sql
|
||||
4. mysql < docs/.../01-mysql-共用底座.sql # agent 库（若未建）
|
||||
5. python scripts/sync/sync_advisor_rel.py
|
||||
6. python scripts/sync/sync_neo4j.py # 可选
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Core 库表设计（P0 最小集）
|
||||
|
||||
> 命名前缀 `core_`，与 agent 库表 **绝不重名**。
|
||||
|
||||
| 表名 | 对应 L0 能力 | P0 场景 |
|
||||
| --- | --- | --- |
|
||||
| `core_advisor` | 理财师/员工 | F-01、A-01 |
|
||||
| `core_customer` | 客户主档（脱敏字段） | 全 Agent |
|
||||
| `core_customer_risk` | 正式 C1~C5 + 测评时间 | R-02、C-07 |
|
||||
| `core_customer_advisor` | 客户-代理人归属 | F-01 → 同步 agent 库 |
|
||||
| `core_product` | 基金/产品 + R1~R5 | C-02、R-02 |
|
||||
| `core_holding` | 持仓份额、成本、市值、盈亏% | C-01、A-01、C-04 |
|
||||
| `core_trade` | 申购/赎回/转换流水 | R-01、D-01 |
|
||||
| `core_cash_flow` | 资金进出 | C-01 |
|
||||
| `core_product_nav` | 最新净值/日涨跌 | C-05 |
|
||||
|
||||
**P1 可加：** `core_industry`、`core_dividend`、`core_aml_list`（R-03 名单）
|
||||
|
||||
### 4.1 关键字段约定
|
||||
|
||||
- 主键统一字符串：`CUST-xxxx`、`STAFF-xxxx`、`PROD-xxxx`、`TRD-xxxx`
|
||||
- 金额 `DECIMAL(18,2)`；份额 `DECIMAL(18,4)`；盈亏比例 `DECIMAL(8,4)`
|
||||
- 所有事实表带 `as_of DATE` 或 `updated_at`，展示时必须带「数据截至」
|
||||
- `core_customer_risk.is_authoritative = 1` 表示 L0 正式等级（Agent 不可写此表）
|
||||
|
||||
---
|
||||
|
||||
## 5. 种子数据设计（演示用 personas）
|
||||
|
||||
建议 **少而全**：6 个客户 + 2 代理人 + 8~10 产品，覆盖 P0 验收。
|
||||
|
||||
| customer_id | 正式等级 | 代理人 | 用途 |
|
||||
| --- | --- | --- | --- |
|
||||
| `CUST-9527` | C3 | STAFF-10086 | 主 demo：正常持仓、问持仓/净值 |
|
||||
| `CUST-1001` | C1 | STAFF-10086 | R-02：尝试买 R5 应阻断 |
|
||||
| `CUST-1002` | C2 | STAFF-10086 | 亏损接近阈值 C-04 |
|
||||
| `CUST-2001` | C4 | STAFF-10087 | 跨代理人：10086 不能查 |
|
||||
| `CUST-3001` | C3 | STAFF-10086 | R-01：单笔 50 万+ 交易 seed |
|
||||
| `CUST-4001` | C5 | STAFF-10087 | 高龄 + 高风险产品冲突（R-02） |
|
||||
|
||||
| advisor_id | 名下客户 |
|
||||
| --- | --- |
|
||||
| `STAFF-10086` | 9527, 1001, 1002, 3001 |
|
||||
| `STAFF-10087` | 2001, 4001 |
|
||||
|
||||
| product_id | 风险 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `PROD-110022` | R2 | 债基，C1 可买 |
|
||||
| `PROD-005827` | R3 | 混合 |
|
||||
| `PROD-161725` | R4 | 行业主题 |
|
||||
| `PROD-XYZ999` | R5 | 用于适当性拒单 demo |
|
||||
|
||||
**Milvus 产品文档**仍走 `data/kb/` + 向量库；Core 的 `core_product` 只放 **结构化字段**（代码、名称、R 等级、费率摘要），与 RAG 文档通过 `product_id` 关联。
|
||||
|
||||
---
|
||||
|
||||
## 6. 应用层：只读 Repository（非 API）
|
||||
|
||||
```python
|
||||
# app/repository/core_ro.py 职责边界
|
||||
|
||||
class CoreReadOnlyRepository:
|
||||
"""仅 SELECT jinrong_core.*；连接只读账号或同一连接但方法内禁止写。"""
|
||||
|
||||
def get_customer_l0(customer_id: str) -> CustomerL0
|
||||
def list_holdings(customer_id: str) -> list[Holding]
|
||||
def list_trades(customer_id: str, since: date) -> list[Trade]
|
||||
def get_product(product_id: str) -> Product
|
||||
def get_latest_nav(product_id: str) -> NavQuote
|
||||
def list_customers_by_advisor(advisor_id: str) -> list[str] # 归属
|
||||
```
|
||||
|
||||
- **Tool 层**（agent_service）只调 Repository，不拼裸 SQL。
|
||||
- **数据分析 Agent**：SQL 网关白名单仅允许 `jinrong_core` + `jinrong_agent` 指定表；默认禁止 JOIN 跨库写。
|
||||
- **以后有真 Core**：新增 `CoreHttpAdapter` 实现同一接口，种子库保留作集成测试。
|
||||
|
||||
---
|
||||
|
||||
## 7. 同步脚本（模拟「Core → Agent/Neo4j」）
|
||||
|
||||
### 7.1 `sync_advisor_rel.py`
|
||||
|
||||
```text
|
||||
读 core_customer_advisor (status=active)
|
||||
→ UPSERT jinrong_agent.customer_advisor_rel
|
||||
→ 供 JWT 归属校验 / F-01
|
||||
```
|
||||
|
||||
### 7.2 `sync_neo4j.py`（第二批）
|
||||
|
||||
```text
|
||||
core_customer / core_advisor / core_product / core_holding
|
||||
→ Neo4j Customer/Advisor/Product/HOLDS/ASSIGNED_TO/HAS_RISK_LEVEL/REQUIRES_MIN_RISK
|
||||
```
|
||||
|
||||
同步频率：**开发期手动跑**；README 写「改 seed 后必跑 sync」。
|
||||
|
||||
### 7.3 `inject_trade.py`（可选）
|
||||
|
||||
```text
|
||||
命令行：模拟一笔新交易写入 core_trade
|
||||
→ 触发风控 Agent 测试 R-01（不必真 API）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 权限与安全（开发期）
|
||||
|
||||
| 项 | 做法 |
|
||||
| --- | --- |
|
||||
| MySQL 用户 | `agent_app`：对 `jinrong_agent` 读写；对 `jinrong_core` **仅 SELECT** |
|
||||
| 代码 | Repository 内仅 `session.execute(text("SELECT ..."))` |
|
||||
| 测试 | 断言无 `INSERT/UPDATE/DELETE` 指向 `jinrong_core` |
|
||||
|
||||
答辩环境可共用 root；生产模拟仍建议分权限。
|
||||
|
||||
---
|
||||
|
||||
## 9. 与现有文档的用语对齐
|
||||
|
||||
| 原说法 | 落地后 |
|
||||
| --- | --- |
|
||||
| Core 只读 API | **Core 只读 Repository（查 jinrong_core）** |
|
||||
| Core 同步 | **scripts/sync/*.py** |
|
||||
| L0 | **jinrong_core 表内正式字段** |
|
||||
| F-04 | Agent 不写 core 库，只 SELECT |
|
||||
|
||||
建议在 `业务记忆管理手册.md` §8 加一句：「开发期 Core = `jinrong_core` 模拟库」。
|
||||
|
||||
---
|
||||
|
||||
## 10. 实施分期
|
||||
|
||||
| 阶段 | 交付 | 工期估 |
|
||||
| --- | --- | --- |
|
||||
| **P0-1** | DDL + base/customer/holding seed + sync_advisor_rel | 1~2 天 |
|
||||
| **P0-2** | core_ro.py + 2 个 Tool（持仓/产品）+ C-01/A-01 可 demo | 1~2 天 |
|
||||
| **P0-3** | trade seed + inject_trade + R-01/R-02 联调 | 1 天 |
|
||||
| **P1** | sync_neo4j + nav seed + D-01 跨表 SQL | 1~2 天 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 验收清单
|
||||
|
||||
- [ ] `jinrong_core` 与 `jinrong_agent` 同实例不同库，Agent 代码无 core 写操作
|
||||
- [ ] 客户 CUST-9527 可查持仓；CUST-2001 代理人 10086 查不到（403）
|
||||
- [ ] CUST-1001（C1）买 PROD-XYZ999（R5）→ R-02 阻断记录
|
||||
- [ ] `reset.ps1` 一键清空并重灌 seed，同步 rel 后代理人权限仍正确
|
||||
- [ ] 分析 Agent 可对 `jinrong_core.core_holding` 做 COUNT/GROUP BY
|
||||
|
||||
---
|
||||
|
||||
## 12. 待你确认的点
|
||||
|
||||
~~已确认：28 客户、RBAC 多角色、Neo4j P0、静态净值。~~
|
||||
|
||||
---
|
||||
|
||||
## 13. 关联文档
|
||||
|
||||
- [05-多Agent共用底座清单.md](../表设计/05-多Agent共用底座清单.md) §七 Core 只读接口 → 本方案替代实现
|
||||
- [04-neo4j-model.md](../表设计/04-neo4j-model.md)
|
||||
- [业务记忆管理手册.md](../../业务记忆管理/业务记忆管理手册.md) §8 M4 官方事实
|
||||
- [业务场景优先级清单.md](../../需求拆解/业务场景优先级清单.md) P0 场景
|
||||
Reference in New Issue
Block a user