ZLData AI 量化交易平台 — 产品需求规格书 (PRD)

目录

1. 概述与迭代策略
2. 系统架构与部署拓扑
3. 技术栈与平台选型
4. 智能体团队设计
5. 核心功能模块与迭代路线图
6. 数据模型设计
7. API 接口设计
8. 数据流与工作流
9. 文档、知识库与反馈闭环集成
10. 安全设计
11. 监控与可观测性
12. 容错与弹性设计
13. 非功能需求
14. 项目结构
15. 实施路线图
16. 设计原则
17. 待细化事项 (TBD)

1. 概述与迭代策略

1.1 项目目标与演进路线

ZLData 是一个面向内部交易运维团队的 AI 量化投资分析平台。鉴于系统复杂性，我们采用 “模块化构建、垂直切片式迭代” 的策略，将宏大的目标分解为一系列可独立交付、验证价值的功能模块。

平台以多智能体协同为核心驱动，覆盖从市场数据采集、量化因子计算、策略回测验证、实时风险评估到交易决策生成的全流程。平台定位为 辅助决策系统，所有交易指令必须经过人类审批后方可执行，确保人类始终拥有最终控制权与完整审计追踪能力。

核心价值主张：

• 数据驱动决策：整合 QMT 实时行情、akshare 开源金融数据、定向爬虫新闻资讯和 Web 搜索引擎等多源异构数据，通过统一的标准化管道汇聚至中心数据库，消除信息孤岛。
• 智能体协同工作：通过专业化的 AI 智能体团队（数据分析师、量化策略师、风控官、新闻情绪分析师、组合经理等）分工协作，模拟真实投研团队的工作流，提升分析效率与决策质量。
• 可验证的量化策略：内置回测引擎支持历史策略验证，结合夏普比率、最大回撤、胜率等关键绩效指标，为策略上线提供数据支撑。
• 全面风险管控：多层次风险评估体系覆盖 VaR/CVaR、持仓集中度、流动性风险、行业敞口等多个维度，支持阈值预警与自动阻断。

演进路线图：

1.2 v1.0 里程碑：数据采集与可视化模块

为了快速验证价值并获得合作方反馈，v1.0 版本将聚焦于”数据采集模块”及其互动展示前端。此版本将作为一个完整的、可独立运行的产品进行开发。

• 核心目标：实现从 QMT/akshare 采集 A 股行情、财务、宏观数据，存入数据库，并通过一个 Web 仪表盘进行可视化展示。
• 交付物：
  1. 稳定运行的后端数据采集服务 (Python/FastAPI + APScheduler)。
  2. 部署于 Azure SQL 的数据库，包含完整的数据表结构。
  3. 部署于 Render 的 FastAPI 后端，提供数据查询 API。
  4. 部署于 Vercel 的 Next.js 前端仪表盘，支持数据源状态查看和 SQL 数据浏览。

1.3 目标用户

1.4 部署环境 (演进视图)

1.5 业务约束

• 纯手动交易决策：平台仅提供分析辅助与交易信号，人类保留所有执行控制权，不设自动交易通道。
• 完整审计追踪：所有数据获取、分析计算、信号生成、订单审批和执行记录均需持久化存储，支持审计回溯。
• 合规优先：数据采集和处理需遵守相关金融监管要求，敏感数据需脱敏存储。
• 单市场聚焦：v1 仅覆盖 A 股市场，跨境市场扩展留待后续版本。

2. 系统架构与部署拓扑

2.1 整体架构总览

此架构图明确了早期云部署的组件边界和通信关系，同时展示了完整的系统架构。

2.2 部署拓扑详情 (v1.0)

3. 技术栈与平台选型

4. 智能体团队设计 (v2.0+)

本章为 v2 核心设计。v1 阶段仅搭建目录结构和基础接口存根，v2 阶段逐步实现完整的多智能体协作系统。

4.1 智能体团队总览

ZLData 采用 专业化分工 + 中心化协调 的多智能体架构。每个智能体负责一个特定的业务领域，由主协调智能体（Main Coordinator）统一调度工作流程。智能体之间通过消息队列进行异步通信，通过共享数据库进行状态同步。

智能体在 Render 上的部署策略：

• Web Service (FastAPI)：轻量级，仅负责接收用户指令、进行参数校验、创建任务记录并发送至消息队列，绝不执行耗时的 Agent 逻辑。
• Background Worker (Render Worker)：部署一个独立的、长期运行的服务。它从 Redis 队列中拉取任务，加载对应的 Agent 逻辑，并调用 LLM API。这种方式将计算与请求处理解耦，保证了 API 的响应速度和系统的可扩展性。

4.2 智能体详细设计

4.2.1 主协调智能体 (Main Coordinator)

核心能力：

• 任务分解：将用户的高层请求（如”分析沪深300成分股近期走势”）分解为子任务，分配给对应智能体
• 工作流编排：按 DAG（有向无环图）管理任务依赖关系，支持串行、并行、条件分支执行
• 上下文管理：维护对话上下文和任务执行上下文，支持多轮交互
• 异常处理：监控子任务状态，处理超时、失败、结果质量不达标等异常
• 结果聚合：收集各智能体输出，综合判断后生成最终结论

任务编排示例 — 日常市场分析：

4.2.2 数据分析师 (Data Analyst)

具体职责：

• 根据分析需求确定需要的数据源和指标范围
• 从 QMT、akshare、爬虫等数据源获取原始数据
• 执行数据清洗：去重、缺失值检测、异常值标记、时间对齐
• 评估数据质量并生成数据质量报告（完整性、时效性、一致性）
• 当数据质量不满足分析要求时，主动上报异常并建议替代方案

4.2.3 量化策略师 (Quant Strategist)

具体职责：

• 根据数据分析师提供的标准化数据，计算技术指标（MA、MACD、RSI、KDJ、布林带等）
• 执行多因子分析（价值因子、动量因子、质量因子、波动率因子等）
• 基于指标和因子组合生成交易信号（买入/卖出/持有，含置信度）
• 将新策略提交给回测工程师进行历史验证
• 综合回测结果和实时信号，给出策略评估结论

4.2.4 风控官 (Risk Officer)

具体职责：

• 对量化策略师生成的交易信号进行独立风险评估
• 计算 VaR（在险价值）和 CVaR（条件在险价值），评估潜在损失
• 监控持仓集中度、行业敞口、流动性风险等维度
• 根据预设风控阈值进行实时监控，超阈值时生成告警
• 拥有一票否决权：当风险指标超出可接受范围时，可否决交易信号

4.2.5 新闻情绪分析师 (Sentiment Analyst)

具体职责：

• 从财经新闻、公告、社交媒体等来源采集与目标标的相关的内容
• 利用 LLM 对文本进行情绪分析和关键信息提取
• 识别重大事件（财报发布、政策变动、行业事件等）并评估影响
• 将情绪因子整合到量化分析框架中，辅助信号生成
• 维护舆情监控看板，对异常舆情及时预警

4.2.6 组合经理 (Portfolio Manager)

具体职责：

• 综合量化策略师的信号和风控官的风险评估，生成投资组合建议
• 根据风险偏好和资金约束，优化仓位分配比例
• 定期进行组合再平衡分析，提出调仓建议
• 执行投资组合绩效归因分析，识别收益和风险来源
• 所有交易建议均标注为”建议”，最终决策权归属人类交易员

4.2.7 回测工程师 (Backtest Engineer)

具体职责：

• 接收量化策略师提交的策略定义，执行历史数据回测
• 计算关键绩效指标：年化收益率、夏普比率、最大回撤、胜率、盈亏比、Sortino 比率等
• 执行参数敏感性分析和网格搜索优化
• 检测过拟合风险：样本内/样本外验证、Walk-forward Analysis
• 生成标准化的回测报告，为策略上线提供数据支撑

4.2.8 文档工程师 (Doc Engineer)

具体职责：

• 将各智能体的分析结果汇总为结构化报告
• 维护和更新平台功能说明文档、数据处理逻辑文档
• 管理分析报告的版本历史和归档
• 支持自然语言查询历史文档和分析记录

4.3 智能体通信机制

通信协议规范：

消息格式标准：

{
  "message_id": "uuid-v4",
  "from_agent": "quant_strategist",
  "to_agent": "risk_officer",
  "task_id": "task-20260403-001",
  "message_type": "signal_review_request",
  "payload": {
    "signal_type": "BUY",
    "target": "600519.SH",
    "confidence": 0.78,
    "factors": { "momentum": 0.8, "value": 0.6, "quality": 0.7 },
    "suggested_position": 50000
  },
  "timestamp": "2026-04-03T10:30:00+08:00",
  "priority": "high",
  "reply_to": "coord.agent.replies"
}

4.4 智能体生命周期管理

5. 核心功能模块与迭代路线图

5.1 数据采集模块 (Data Collection)

v1.0 核心功能：

关键设计要点：

1. 双源冗余：关键数据（行情、财务）同时从 QMT 和 akshare 采集，互为备份
2. 幂等写入：所有数据写入操作支持重复执行，避免重复数据
3. 增量更新：仅采集新增数据，减少网络传输和存储开销
4. 并行采集：多数据源并行采集，提升效率
5. 错误重试：网络异常时自动重试，超过阈值后告警

5.2 量化分析模块 (Quantitative Analysis)

v1.5 核心功能：

5.3 风险评估模块 (Risk Assessment)

v2.5 核心功能：

5.4 回测引擎模块 (Backtest Engine)

v2.5 核心功能：

5.5 交易决策模块 (Trading Decision)

v2.5+ 核心功能：

5.6 文档管理模块 (Documentation Support)

v1.0+ 核心功能：

6. 数据模型设计

6.1 数据模型 ER 图

6.2 核心数据表规格

6.2.1 股票基础信息表 (stock_info)

索引：

• idx_stock_industry ON (industry)
• idx_stock_exchange ON (exchange)

6.2.2 日行情数据表 (market_daily)

索引：

• idx_market_stock_date ON (stock_code, trade_date) UNIQUE
• idx_market_date ON (trade_date)

约束：

• UNIQUE (stock_code, trade_date)

6.2.3 财务数据表 (financial_data)

索引：

• idx_financial_stock_date ON (stock_code, report_date)
• idx_financial_date ON (report_date)

6.2.4 新闻数据表 (news_data)

索引：

• idx_news_stock_time ON (stock_code, publish_time)
• idx_news_time ON (publish_time)

6.2.5 技术指标表 (tech_indicators)

索引：

• idx_tech_stock_date ON (stock_code, trade_date) UNIQUE

6.2.6 因子数据表 (factor_data)

索引：

• idx_factor_stock_date_name ON (stock_code, calc_date, factor_name)
• idx_factor_type ON (factor_type)

6.2.7 研报数据表 (research_report)

索引：

• idx_report_stock_date ON (stock_code, publish_date)
• idx_report_institution ON (institution)

6.2.8 宏观指标定义表 (macro_indicator)

6.2.9 宏观数据表 (macro_data)

索引：

• idx_macro_indicator_date ON (indicator_code, data_date)

6.2.10 利率类型定义表 (interest_rate)

6.2.11 利率数据表 (rate_data)

索引：

• idx_rate_type_date ON (rate_type, data_date)

7. API 接口设计

7.1 数据采集模块 API (v1.0)

详细接口规格：

7.1.1 查询数据源连接状态

请求：

GET /api/v1/dc/status

响应：

{
  "status": "success",
  "data": {
    "qmt": {
      "status": "healthy",
      "last_check": "2026-04-16T10:30:00+08:00",
      "latency_ms": 45
    },
    "akshare": {
      "status": "healthy",
      "last_check": "2026-04-16T10:30:00+08:00",
      "latency_ms": 120
    },
    "crawler": {
      "status": "degraded",
      "last_check": "2026-04-16T10:30:00+08:00",
      "error": "Rate limit exceeded"
    }
  }
}

7.1.2 查询最近采集任务

请求：

GET /api/v1/dc/jobs?limit=10

响应：

{
  "status": "success",
  "data": {
    "jobs": [
      {
        "job_id": "job-20260416-001",
        "job_type": "market_daily",
        "status": "completed",
        "started_at": "2026-04-16T09:00:00+08:00",
        "completed_at": "2026-04-16T09:15:23+08:00",
        "records_processed": 4500,
        "error_message": null
      },
      {
        "job_id": "job-20260416-002",
        "job_type": "financial",
        "status": "failed",
        "started_at": "2026-04-16T09:30:00+08:00",
        "completed_at": "2026-04-16T09:32:45+08:00",
        "records_processed": 120,
        "error_message": "Connection timeout"
      }
    ],
    "total": 2
  }
}

7.1.3 手动触发数据采集

请求：

POST /api/v1/dc/trigger
Content-Type: application/json
 
{
  "job_type": "market",
  "params": {
    "stock_codes": ["600519.SH", "000858.SZ"],
    "start_date": "2026-04-01",
    "end_date": "2026-04-16"
  }
}

响应：

{
  "status": "success",
  "data": {
    "job_id": "job-20260416-003",
    "message": "Job triggered successfully"
  }
}

7.1.4 SQL 数据浏览器

请求：

GET /api/v1/data-viewer/query?sql=SELECT%20*%20FROM%20stock_info%20LIMIT%2010

响应：

{
  "status": "success",
  "data": {
    "columns": ["stock_code", "stock_name", "exchange", "industry", "list_date"],
    "rows": [
      ["600519.SH", "贵州茅台", "SSE", "食品饮料", "2001-08-27"],
      ["000858.SZ", "五粮液", "SZSE", "食品饮料", "1998-04-27"]
    ],
    "row_count": 2
  }
}

7.2 量化分析模块 API (v1.5)

7.3 风险评估模块 API (v2.5)

7.4 回测引擎模块 API (v2.5)

7.5 交易决策模块 API (v2.5+)

8. 数据流与工作流

8.1 数据采集流程

8.2 量化分析流程

8.3 风控审批流程

9. 文档、知识库与反馈闭环集成

本章节阐述如何将 doc.zldata.ai-time.net (Nextra), comment.zldata.ai-time.net (Waline) 和 zldata.ai-time.net (主平台) 集成为一个有机的生态系统。

9.1 集成架构图

9.2 详细集成设计

10. 安全设计

10.1 API 通信安全

• HTTPS 加密：前端与后端之间使用 HTTPS 加密传输。
• CORS 配置：后端 FastAPI 启用 CORS，仅允许 zldata.ai-time.net 和 doc.zldata.ai-time.net 两个源。
• API 认证：v1.0 阶段暂不实现用户认证，v2.0 引入 JWT Token 认证机制。

10.2 数据查询安全

• SQL 注入防护：/api/v1/data-viewer/query 接口必须严格校验 SQL 语句，仅允许 SELECT 操作。
• 表访问控制：限制可查询的表，禁止访问系统表和敏感表。
• 返回行数限制：单次查询最多返回 1000 行数据。

10.3 密钥管理

• 环境变量注入：所有密钥（数据库连接串、LLM API Key）通过 Render 和 Vercel 的 Environment Variables 功能注入。
• 代码库安全：代码库中不包含任何硬编码密钥，.env 文件已加入 .gitignore。
• 密钥轮换：定期轮换敏感密钥（建议每季度一次）。

10.4 数据安全

• 敏感数据脱敏：财务数据中的敏感字段（如具体金额）在日志中脱敏显示。
• 访问日志：记录所有数据访问操作，支持审计追踪。
• 备份策略：数据库每日自动备份，保留 7 天备份记录。

11. 监控与可观测性

11.1 监控架构

11.2 关键监控指标

11.3 日志规范

日志级别：

• DEBUG：详细的调试信息（仅开发环境）
• INFO：关键业务操作（数据采集完成、策略生成等）
• WARNING：潜在问题（数据质量警告、性能下降等）
• ERROR：错误但系统可继续运行（API 调用失败、数据解析错误等）
• CRITICAL：严重错误导致系统不可用（数据库连接失败、服务崩溃等）

日志格式（JSON）：

{
  "timestamp": "2026-04-16T10:30:00.123+08:00",
  "level": "INFO",
  "logger": "zldata.data_collector",
  "message": "Market data collection completed",
  "context": {
    "job_id": "job-20260416-001",
    "stock_count": 4500,
    "duration_ms": 923000
  },
  "trace_id": "abc-123-def",
  "span_id": "span-456"
}

12. 容错与弹性设计

12.1 数据采集容错

12.2 API 服务容错

12.3 智能体容错

13. 非功能需求

13.1 性能需求

13.2 可用性需求

13.3 可扩展性需求

13.4 可维护性需求

14. 项目结构

14.1 Monorepo 目录结构

zldata/
├── frontend/                    # Next.js 前端应用
│   ├── app/                     # App Router 页面
│   │   ├── (dashboard)/        # 数据看板页面组
│   │   ├── api/                # API Routes
│   │   └── layout.tsx          # 根布局
│   ├── components/             # React 组件
│   │   ├── ui/                 # 基础 UI 组件
│   │   ├── charts/             # 图表组件
│   │   └── dashboard/          # 看板组件
│   ├── lib/                    # 工具库
│   ├── styles/                 # 样式文件
│   ├── package.json
│   └── next.config.js
│
├── backend/                     # FastAPI 后端应用
│   ├── app/
│   │   ├── api/                # API 路由
│   │   │   ├── v1/            # v1 版本 API
│   │   │   │   ├── data_collection.py
│   │   │   │   ├── quantitative.py
│   │   │   │   └── risk.py
│   │   ├── core/               # 核心配置
│   │   │   ├── config.py      # 配置管理
│   │   │   ├── database.py    # 数据库连接
│   │   │   └── security.py    # 安全相关
│   │   ├── models/             # SQLAlchemy 模型
│   │   ├── schemas/            # Pydantic 模型
│   │   ├── services/           # 业务逻辑层
│   │   │   ├── data_collector/
│   │   │   ├── quant_analyzer/
│   │   │   └── risk_assessor/
│   │   ├── agents/             # 智能体模块 (v2.0+)
│   │   │   ├── coordinator/
│   │   │   ├── data_analyst/
│   │   │   ├── quant_strategist/
│   │   │   └── risk_officer/
│   │   └── workers/            # 后台任务
│   ├── tests/                  # 测试文件
│   ├── requirements.txt
│   └── main.py
│
├── doc-site/                    # Nextra 文档站
│   ├── pages/                  # MDX 页面
│   │   ├── index.mdx
│   │   ├── getting-started.mdx
│   │   └── api-reference.mdx
│   ├── theme.config.jsx        # Nextra 配置
│   └── package.json
│
├── scripts/                     # 脚本工具
│   ├── init_db.py              # 数据库初始化
│   ├── seed_data.py            # 种子数据
│   └── backup.sh               # 备份脚本
│
├── docker/                      # Docker 配置
│   ├── Dockerfile.backend
│   ├── Dockerfile.frontend
│   └── docker-compose.yml
│
├── .github/                     # GitHub 配置
│   └── workflows/              # CI/CD 工作流
│
├── docs/                        # 项目文档
│   ├── design/                 # 设计文档
│   └── api/                    # API 文档
│
├── .env.example                # 环境变量示例
├── .gitignore
├── README.md
└── Makefile                    # 常用命令

14.2 关键模块说明

14.2.1 数据采集模块 (backend/app/services/data_collector/)

data_collector/
├── __init__.py
├── base.py              # 基础采集器抽象类
├── qmt_collector.py     # QMT 数据采集器
├── akshare_collector.py # akshare 数据采集器
├── crawler.py           # 爬虫采集器
├── validator.py         # 数据校验器
├── normalizer.py        # 数据标准化器
└── scheduler.py         # 调度器

14.2.2 量化分析模块 (backend/app/services/quant_analyzer/)

quant_analyzer/
├── __init__.py
├── indicators.py        # 技术指标计算
├── factors.py           # 因子计算
├── signals.py           # 信号生成
├── backtest.py          # 回测引擎
└── performance.py       # 绩效计算

14.2.3 智能体模块 (backend/app/agents/)

agents/
├── __init__.py
├── base.py              # 基础智能体抽象类
├── coordinator/         # 主协调智能体
│   ├── __init__.py
│   ├── agent.py
│   └── workflows.py
├── data_analyst/        # 数据分析师
├── quant_strategist/    # 量化策略师
├── risk_officer/        # 风控官
├── sentiment_analyst/   # 新闻情绪分析师
├── portfolio_manager/   # 组合经理
├── backtest_engineer/   # 回测工程师
└── doc_engineer/        # 文档工程师

15. 实施路线图

15.1 v1.0 实施计划 (2026 Q2)

目标：数据采集与可视化模块上线

15.2 v1.5 实施计划 (2026 Q3)

目标：基础量化分析引擎

15.3 v2.0 实施计划 (2026 Q4)

目标：智能体试点

16. 设计原则

16.1 架构设计原则

1. 模块化与解耦：各功能模块独立开发、独立部署，通过清晰的接口通信。
2. 渐进式演进：从简单到复杂，每个版本都有完整可用的交付物。
3. 云原生优先：早期采用云服务快速验证，后期迁移至自托管环境。
4. 可观测性设计：从第一天起就内置监控、日志和追踪能力。
5. 安全优先：所有设计决策都需考虑安全影响。

16.2 代码设计原则

1. 类型安全：使用 Pydantic 和 TypeScript 确保类型安全。
2. 异步优先：I/O 密集型操作使用异步编程。
3. 测试驱动：核心业务逻辑必须有单元测试覆盖。
4. 文档即代码：API 文档自动生成，代码注释清晰。
5. 配置外部化：所有配置通过环境变量注入。

16.3 数据设计原则

1. 单一数据源：每个数据项有唯一的数据源标识。
2. 不可变记录：数据记录只增不改，保留完整历史。
3. 时间戳完整：所有记录包含创建时间和更新时间。
4. 索引优化：根据查询模式设计合理的索引策略。
5. 分区策略：大表按时间分区，提升查询性能。

16.4 智能体设计原则

1. 单一职责：每个智能体专注于一个业务领域。
2. 人类监督：所有关键决策需人类确认。
3. 可解释性：智能体的推理过程可追溯、可解释。
4. 失败降级：LLM 不可用时降级至规则引擎。
5. 上下文管理：合理管理对话上下文，避免内存溢出。

17. 待细化事项 (TBD)

17.1 技术细节待定

• QMT API 具体调用方式和认证机制
• LLM 提示词模板库设计
• 智能体工作流 DAG 的可视化编辑器
• 数据备份与恢复的详细流程
• 多租户隔离方案（如需支持多团队）

17.2 业务规则待定

• 具体的风控阈值参数（VaR 限额、集中度上限等）
• 交易信号的置信度阈值
• 数据质量评估的详细标准
• 用户权限和角色定义
• 审批流程的具体规则

17.3 运维相关待定

• 生产环境的监控告警渠道配置
• 故障应急响应流程
• 数据迁移和升级策略
• 容量规划和扩容触发条件
• 安全审计流程

附录

A. 术语表

B. 参考文档

• FastAPI 官方文档 
• Next.js 官方文档 
• SQLAlchemy 2.0 文档 
• Nextra 文档框架 
• Waline 评论系统 
• akshare 文档 

C. 变更历史

文档结束 | **故障