group_fqcd_jr/README.md

# 南方基金智能业务平台

本项目是一个基于 FastAPI 和 MVC+S 架构的金融业务 Agent 平台，当前包含以下三项核心业务：

1. 场外基金申购/赎回运营流程
2. 产品推介材料与宣传海报生成
3. 金融自然语言转 SQL（NL2SQL）查询

项目中的场外基金运营、产品推介材料与场内基金模拟交易相互隔离。场外业务使用独立的
`offsite_fund_*` 数据表和接口，不写入场内交易表。

## 一、技术栈

- Python `3.13`
- FastAPI、Uvicorn
- SQLAlchemy 2.x、Alembic
- MySQL、Redis
- Pydantic v2
- JWT + RBAC
- `python-pptx`、OpenPyXL、Pillow、Matplotlib
- 可选：阿里云 DocMind/OCR、DeepSeek、SMTP、Milvus、Neo4j

## 二、项目结构

```text
group_fqcd_jr/
├── app/
│   ├── api/controllers/             # HTTP 路由和请求参数校验
│   ├── api/schemas/                # 请求/响应模型
│   ├── core/                       # 业务契约、配置和公共规则
│   ├── model/                      # SQLAlchemy 数据模型
│   ├── service/                    # 业务编排、规则和数据访问
│   ├── infrastructure/             # 数据库、缓存和外部基础设施适配
│   └── worker/                     # 异步 Worker
├── data/                            # 测试与演示数据集
├── docs/                            # 架构、接口、数据库和业务说明
├── tests/                           # 单元、契约、集成和环境测试
├── tools/                           # 迁移、种子、检查和测试工具
├── alembic/                         # 数据库迁移
├── hq.py                            # 南方基金行情数据适配模块
├── nl2sql_yc.py                     # 金融 NL2SQL 兼容入口和查询逻辑
├── .env.example                     # 环境变量模板
└── README.md
```

## 三、环境准备

项目要求 Python `>=3.13,<3.14`。建议使用独立虚拟环境：

```powershell
conda create -n jr_py313 python=3.13
conda activate jr_py313
pip install -r requirements.txt
```

复制配置文件：

```powershell
Copy-Item .env.example .env
```

然后根据本机环境修改 `.env`，至少配置：

```text
MYSQL_DSN
JWT_PRIVATE_KEY_PATH
JWT_PUBLIC_KEY_PATH
```

`.env`、JWT 私钥、模型密钥和真实外部服务凭据禁止提交到 Git。

## 四、启动服务

### 4.1 数据库迁移

请确保 MySQL 已启动，并且 `.env` 中的数据库连接可用：

```powershell
alembic upgrade head
python tools/audit_schema.py
```

### 4.2 启动 HTTP 服务

```powershell
python -m uvicorn app.main:app --host 127.0.0.1 --port 8099
```

服务地址：

```text
http://127.0.0.1:8099
```

OpenAPI 文档：

```text
http://127.0.0.1:8099/docs
```

### 4.3 启动 Worker

需要异步处理 Agent 运行或场外邮件时，另开终端：

```powershell
python -m app.worker
```

Worker 是否启用场外收信，取决于：

```text
OFFSITE_MAIL_WORKER_ENABLED
OFFSITE_IMAP_ENABLED
OFFSITE_WORKER_USER_ID
```

## 五、功能一：场外基金申购/赎回

### 5.1 功能说明

场外流程面向运营人员，主要处理：

```text
邮件接收
→ 附件保存
→ OCR/文档识别
→ 结构化字段提取
→ 申购/赎回规则计算
→ NL2SQL 查询资金和持仓数据
→ 运营人员确认
→ 创建通知
→ 发送或 dry-run
→ 审计和统计
```

支持的单据类型：

- `subscription`：申购
- `redemption`：赎回
- `summary`：汇总材料
- `other`：其他材料

系统保留原始邮件、附件、识别结果、查询记录、规则结果、人工修正记录和审计记录。
人工修正不会覆盖 Agent 原始识别值。

### 5.2 主要接口

基础路径：

```text
/api/v1/offsite-fund
```

| 方法 | 路径 | 用途 |
|---|---|---|
| `GET` | `/mails` | 分页查询场外邮件 |
| `GET` | `/mails/{mail_id}` | 查看邮件详情 |
| `POST` | `/mails/{mail_id}/deletions` | 软删除邮件 |
| `GET` | `/mails/{mail_id}/recognition-fields` | 查看 OCR 识别字段 |
| `PUT` | `/mails/{mail_id}/recognition-fields` | 保存 OCR 字段人工修正 |
| `GET` | `/documents/{task_id}/nl2sql-fields` | 查看 NL2SQL 返回字段 |
| `PUT` | `/documents/{task_id}/nl2sql-fields` | 保存 NL2SQL 字段人工修正 |
| `GET` | `/documents/{task_id}/rule-results` | 查看规则判定结果 |
| `POST` | `/documents/{task_id}/rule-results/recalculations` | 使用已有结果重新判定 |
| `GET` | `/mailbox-status` | 查看收件游标状态 |
| `POST` | `/mailbox-status/recoveries` | 恢复被阻塞的收件游标 |
| `GET` | `/attachments/{attachment_id}/file` | 预览或下载原始附件 |
| `POST` | `/documents/{task_id}/confirmations` | 运营人员确认单据 |
| `POST` | `/documents/{task_id}/recognition-retries` | 重试识别异常单据 |
| `POST` | `/documents/{task_id}/notifications` | 创建运营通知 |
| `POST` | `/notifications/{notification_id}/send` | 发送通知 |
| `POST` | `/settlement-statistics/recalculate` | 重算结算统计 |

触发场外单据 NL2SQL 核对的接口为：

```text
POST /api/tasks/{task_id}/trigger-agent-nl2sql
```

### 5.3 权限与安全

- 读取权限：`offsite:read`
- 写入权限：`offsite:write`
- 确认权限：`offsite:confirm`
- NL2SQL 权限：`offsite:nl2sql`
- 通知权限：`offsite:notify`
- 请求中的 `operator_id` 必须与 JWT 身份一致
- 所有写操作都进行权限校验、操作人校验、审计和状态流转校验
- 通知发送支持幂等，SMTP 默认关闭并使用 dry-run

## 六、功能二：产品推介材料与宣传海报生成

### 6.1 功能说明

该模块用于新产品的结构化资料整理和宣传材料生成。当前生成链路为：

```text
创建任务
→ 填写产品、经理、团队、策略、费用、业绩和风险资料
→ 上传经理照片、业绩数据、来源证据或模板
→ 合规检查
→ 生成 PPTX、宣传海报和可选 PDF
→ 审核
→ 发送给指定投顾
```

支持的输入附件：

- `manager_photo`：基金经理照片
- `performance_data`：CSV/XLSX 业绩数据
- `source_evidence`：来源证据
- `template_file`：材料模板

支持的输出格式：

- `pptx`
- `poster`
- `pdf`，需要配置 LibreOffice/`soffice` 等转换器

模块会执行风险披露、费用结构、业绩数据、输入完整性和生成文本合规检查。
合规阻断时返回具体 findings 和补齐建议，不继续生成材料。

### 6.2 主要接口

基础路径：

```text
/api/v1/fund-promotion-materials
```

| 方法 | 路径 | 用途 |
|---|---|---|
| `POST` | `/` | 创建推介材料任务 |
| `PUT` | `/{task_no}/inputs` | 保存结构化输入资料 |
| `POST` | `/{task_no}/attachments` | 上传照片、业绩文件或证据 |
| `POST` | `/{task_no}/generations` | 生成推介材料 |
| `GET` | `/{task_no}/compliance-checks` | 查看合规检查结果 |
| `GET` | `/{task_no}` | 查询任务和已审核材料 |
| `POST` | `/{task_no}/reviews` | 审核、驳回或要求修改 |
| `POST` | `/{task_no}/deliveries` | 发送给投顾 |

创建任务和写入操作必须提供请求头：

```text
Idempotency-Key: <唯一请求键>
```

### 6.3 权限与状态

主要权限：

- `promotion:write`
- `promotion:read`
- `promotion:review`
- `promotion:deliver`

材料任务状态包括：

```text
draft
→ input_ready
→ generating
→ generated
→ pending_review
→ approved
→ sent
```

异常状态包括：

```text
compliance_failed
rejected
failed
```

生成的文件默认保存到：

```text
data/promotion_materials/
```

## 七、功能三：金融 NL2SQL

### 7.1 功能说明

NL2SQL 将自然语言问题转换为经过权限、业务域、表白名单和只读校验的 SQL。
业务 Agent 不直接连接数据库，而是通过公共只读工具调用：

```text
业务 Agent
→ BaseAgent.call_tool
→ ToolExecutor
→ query_financial_data
→ 只读金融数据表
```

工具名称：

```text
query_financial_data
```

权限码：

```text
financial:nl2sql:read
```

### 7.2 支持范围

当前纳入查询范围的主要表：

```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
```

支持：

- 基金净值、行情和历史收益查询
- 费率和费用查询
- 客户风险测评和画像查询
- 持仓、交易、订单、账户和资金流水查询
- 历史范围查询
- 最多跨三个业务域查询
- 结果行数限制，默认 50，最大 200
- SQL dry-run

不支持或会被拒绝：

- 非白名单表
- 非 `SELECT` 查询
- 未通过客户数据范围校验的查询
- 当前快照表的历史时点查询
- 模糊且未确认查询范围、指标口径或时间条件的问题

### 7.3 调用示例

```python
result = await self.call_tool(
    "query_financial_data",
    {
        "question": "查询基金代码 000001 最近 30 天的净值",
        "dry_run": False,
        "limit": 50,
    },
    intent="financial_query",
    context=context,
)
```

模糊问题会返回：

```json
{
  "status": "need_confirmation",
  "message": "请确认查询范围、指标口径和时间条件。"
}
```

工具结果包含查询计划、SQL、参数、权限检查和执行摘要，并进入统一审计和运行持久化链路。

## 八、测试数据集

测试数据位于：

```text
data/
```

当前数据集概况：

| 类型 | 数量 | 用途 |
|---|---:|---|
| `.eml` | 13 | 场外邮件及附件识别 |
| `.csv` / `.xlsx` | 8 | 推介材料业绩数据 |
| `.png` / `.jpg` | 35 | 经理照片、宣传图和测试图片 |
| `.pptx` | 10 | 推介材料结构检查 |
| `.pdf` | 9 | PDF 文件有效性检查 |

测试数据只用于本地测试和演示，不应直接作为生产业务数据导入。

## 九、测试与代码检查

### 9.1 运行完整测试

普通单元和契约测试：

```powershell
python -m pytest tests/unit tests/contract -q -p no:cacheprovider
```

使用独立 MySQL 测试库并执行测试数据隔离：

```powershell
python -m tools.run_tests_on_test_db tests -p no:cacheprovider
```

### 9.2 运行三项功能定向测试

```powershell
python -m pytest `
  tests/integration/test_offsite_fund_api.py `
  tests/integration/test_offsite_nl2sql_fields.py `
  tests/integration/test_offsite_notification_send.py `
  tests/integration/test_promotion_material_api.py `
  tests/unit/service/test_suitability_service.py `
  tests/contract/test_financial_nl2sql_tool_contract.py `
  -q -p no:cacheprovider
```

### 9.3 代码质量检查

```powershell
python -m ruff check app tests tools alembic
python -m mypy app
git diff --check
```

### 9.4 测试基线

最近一次项目回归记录：

```text
关键三项功能定向测试：85 passed
全量自动化测试：559 passed, 1 skipped
```

Redis、真实 IMAP/OCR/DeepSeek/SMTP、Neo4j、Milvus 和浏览器 E2E 是否能执行，
取决于本机服务和凭据配置。外部服务关闭或不可用时，测试使用本地数据集、Mock 或 dry-run。

## 十、配置开关

场外邮件和外部识别：

```text
OFFSITE_IMAP_ENABLED=false
OFFSITE_MAIL_WORKER_ENABLED=false
OFFSITE_OCR_ENABLED=false
OFFSITE_DEEPSEEK_ENABLED=false
OFFSITE_SMTP_ENABLED=false
OFFSITE_SMTP_DRY_RUN=true
```

产品推介材料：

```text
PROMOTION_MATERIAL_STORAGE_DIR=data/promotion_materials
PROMOTION_PDF_ENABLED=false
PROMOTION_PDF_CONVERTER_PATH=
```

启用真实服务前，请先完成网络、凭据、权限、数据脱敏和回滚方案确认。

## 十一、安全与开发约束

- 所有业务请求都应经过统一 JWT、RBAC、客户范围和审计链路。
- 不在业务 Agent 中自行读取密钥、直接连接数据库或绕过 `ToolExecutor`。
- 场外业务不能写入场内交易表。
- 数据库结构只能通过 Alembic 迁移修改。
- 不删除、重命名或复用已有表和字段；历史结构不足时新增字段、新表或兼容读写。
- 所有写接口应设计幂等键、状态机和重复提交保护。
- 真实外部服务默认关闭，测试优先使用本地数据、Mock 和 dry-run。

## 十二、相关文档

- `docs/MVC/MVC架构.md`：项目架构和目录职责
- `docs/00-新数据库基线设计.md`：数据库业务基线
- `docs/05-接口文档.md`：接口权威说明
- `docs/14-Agent组员统一接入说明书.md`：Agent 接入规范
- `docs/15-金融NL2SQL工具接入说明.md`：NL2SQL 工具规范
- `product_promotion_to_do_list.md`：推介材料模块开发记录
- `测试报告/2026-09-12.md`：三项功能数据集测试报告