Initial commit

东方财富资金扩展需求文档.md

@@ -0,0 +1,408 @@
+# 东方财富资金扩展需求文档
+
+## 1. 文档目标
+
+本需求文档用于定义项目下一阶段基于东方财富数据口径的资金扩展能力。
+
+本阶段只做两件事：
+
+- 数据获取
+- 数据展示
+
+不做内容：
+
+- 不做自定义指标推导
+- 不做非东方财富口径命名
+- 不做人为归并后的新分类口径
+
+所有指标命名、分类方式、展示分组、数据库字段命名，应尽量与东方财富页面和接口返回口径保持一致。
+
+## 2. 总体原则
+
+### 2.1 数据源原则
+
+- 主数据源统一为东方财富
+- 所有展示字段优先使用东方财富原始字段含义
+- 若东方财富接口字段与页面文案不同，前端展示名称按东方财富页面标准，数据库保留原始字段和标准展示字段
+- 所有原始请求参数、原始响应 payload、抓取时间、来源 URL 必须保留
+
+### 2.2 功能范围
+
+本阶段仅覆盖以下三类资金数据：
+
+- 个股资金流
+- 板块资金流
+- 指数资金流
+
+### 2.3 存储原则
+
+- 所有数据进入 MySQL
+- JSON 文件可作为调试缓存，但不能作为主存储
+- 所有数据支持按交易日查询
+- 所有数据支持按最新时间查询
+- 所有数据支持后续前端图表和列表直接读取
+
+## 3. 东方财富标准指标范围
+
+## 3.1 个股资金流
+
+以东方财富个股资金流页面和接口口径为准，优先支持以下标准分类与指标：
+
+### 3.1.1 分类
+
+- 主力净流入
+- 超大单净流入
+- 大单净流入
+- 中单净流入
+- 小单净流入
+
+说明：
+
+- 本项目不再使用“机构、大户、散户”作为正式展示分类
+- 若业务侧后续需要做映射，必须作为派生分析口径，不能覆盖东方财富标准分类
+
+### 3.1.2 标准展示字段
+
+- 交易日期
+- 股票代码
+- 股票名称
+- 最新价
+- 涨跌幅
+- 主力净流入
+- 主力净占比
+- 超大单净流入
+- 超大单净占比
+- 大单净流入
+- 大单净占比
+- 中单净流入
+- 中单净占比
+- 小单净流入
+- 小单净占比
+- 更新时间
+- 来源地址
+
+### 3.1.3 展示要求
+
+- 以列表和图表结合展示
+- 图表优先展示主力净流入、超大单净流入、大单净流入
+- 列表字段名称全部使用东方财富标准名称
+- 支持按主力净流入排序
+- 支持按涨跌幅排序
+
+## 3.2 板块资金流
+
+以东方财富板块资金流页面和接口口径为准。
+
+### 3.2.1 分类
+
+板块分类按东方财富现有板块体系展示，不自行改名。至少支持：
+
+- 行业板块
+- 概念板块
+- 地域板块
+
+若东方财富接口可明确区分板块类型，则数据库和前端均保留该分类字段。
+
+### 3.2.2 标准展示字段
+
+- 交易日期
+- 板块代码
+- 板块名称
+- 板块类型
+- 最新价或指数值
+- 涨跌幅
+- 主力净流入
+- 主力净占比
+- 超大单净流入
+- 超大单净占比
+- 大单净流入
+- 大单净占比
+- 中单净流入
+- 中单净占比
+- 小单净流入
+- 小单净占比
+- 领涨股
+- 领涨股涨跌幅
+- 更新时间
+- 来源地址
+
+### 3.2.3 展示要求
+
+- 默认展示主力净流入排名
+- 支持按行业板块、概念板块、地域板块切换
+- 支持 Top N 排行
+- 支持横向条形图或排行榜展示
+- 所有标题和字段名按东方财富标准文案展示
+
+## 3.3 指数资金流
+
+以东方财富指数资金流页面和接口口径为准。
+
+### 3.3.1 覆盖范围
+
+优先覆盖东方财富常见宽基指数与主流指数，包括但不限于：
+
+- 上证指数
+- 深证成指
+- 创业板指
+- 沪深300
+- 中证500
+- 中证1000
+- 科创50
+
+最终以东方财富接口可稳定获取的指数集合为准。
+
+### 3.3.2 标准展示字段
+
+- 交易日期
+- 指数代码
+- 指数名称
+- 最新点位
+- 涨跌额
+- 涨跌幅
+- 主力净流入
+- 主力净占比
+- 超大单净流入
+- 超大单净占比
+- 大单净流入
+- 大单净占比
+- 中单净流入
+- 中单净占比
+- 小单净流入
+- 小单净占比
+- 更新时间
+- 来源地址
+
+### 3.3.3 展示要求
+
+- 支持指数列表展示
+- 支持主力净流入横向对比图
+- 支持按涨跌幅和主力净流入切换排序
+- 指标名称保持东方财富原始口径
+
+## 4. 数据库要求
+
+## 4.1 存储目标
+
+以下三类数据必须进入 MySQL：
+
+- 个股资金流
+- 板块资金流
+- 指数资金流
+
+同时保留：
+
+- 原始 payload
+- 数据抓取日志
+- 数据源诊断信息
+
+## 4.2 建议分类
+
+建议沿用现有文档型存储方式，新增以下 category：
+
+- `eastmoney_stock_fund_flow`
+- `eastmoney_sector_fund_flow`
+- `eastmoney_index_fund_flow`
+- `eastmoney_raw_payload`
+
+## 4.3 每条数据至少保留的公共字段
+
+- `trade_date`
+- `data_type`
+- `biz_code`
+- `biz_name`
+- `source_name`
+- `source_url`
+- `updated_at`
+- `fetched_at`
+- `payload`
+
+说明：
+
+- `biz_code` 对应股票代码、板块代码、指数代码
+- `biz_name` 对应股票名称、板块名称、指数名称
+- `payload` 保存东方财富原始字段
+
+## 4.4 标准化字段要求
+
+除原始 payload 外，数据库还要同步保存标准化字段，字段命名尽量与东方财富标准指标一一对应，例如：
+
+- `latest_price`
+- `change_amount`
+- `change_percent`
+- `main_net_inflow`
+- `main_net_inflow_ratio`
+- `super_large_net_inflow`
+- `super_large_net_inflow_ratio`
+- `large_net_inflow`
+- `large_net_inflow_ratio`
+- `medium_net_inflow`
+- `medium_net_inflow_ratio`
+- `small_net_inflow`
+- `small_net_inflow_ratio`
+
+板块特有字段可补充：
+
+- `sector_type`
+- `leading_stock_name`
+- `leading_stock_change_percent`
+
+## 5. 后端需求
+
+## 5.1 数据采集层
+
+需要在现有东方财富客户端基础上新增以下能力：
+
+- 个股资金流接口获取
+- 板块资金流接口获取
+- 指数资金流接口获取
+
+要求：
+
+- 每类数据单独封装方法
+- 每类数据单独保留原始 URL 和请求参数
+- 支持分页抓取
+- 支持按交易日抓取
+- 支持按排名或排序字段抓取
+- 接口失败时记录失败原因
+
+## 5.2 数据标准化层
+
+新增东方财富资金扩展标准化服务，负责：
+
+- 将接口字段转换为统一数据库字段
+- 保留东方财富标准中文名称
+- 保留东方财富原始英文或缩写字段
+- 不做非官方口径重命名
+
+## 5.3 数据同步层
+
+新增定时同步任务，要求：
+
+- 每个交易日自动运行
+- 交易时间内按设定间隔更新
+- 非交易时间可做低频补齐
+- 同步结果写入数据库
+- 同步失败写入诊断表或诊断文档
+
+## 5.4 查询接口
+
+后端需提供以下查询接口：
+
+- 个股资金流列表接口
+- 板块资金流列表接口
+- 指数资金流列表接口
+- 单项详情接口
+- 最新更新时间接口
+- 原始 payload 调试接口
+
+接口返回字段要求：
+
+- 中文展示名称与东方财富页面一致
+- 数值字段可直接用于前端图表
+- 返回数据中包含更新时间和来源信息
+
+## 6. 前端展示需求
+
+## 6.1 页面结构
+
+前端建议新增三个一级 Tab：
+
+- 个股资金流
+- 板块资金流
+- 指数资金流
+
+## 6.2 展示原则
+
+- 不改造为自定义业务名词体系
+- 所有图表名称、列表列名、筛选项名称以东方财富标准为准
+- 图表与列表同时存在
+- 图表用于趋势和对比
+- 列表用于明细、排序、筛选
+
+## 6.3 个股资金流页面
+
+建议包含：
+
+- 主力净流入排行列表
+- 超大单/大单/中单/小单对比图
+- 涨跌幅与净流入双维度展示
+- 更新时间展示
+
+## 6.4 板块资金流页面
+
+建议包含：
+
+- 行业板块/概念板块/地域板块切换
+- 主力净流入排行
+- 领涨股展示
+- 板块净流入条形图
+- 更新时间展示
+
+## 6.5 指数资金流页面
+
+建议包含：
+
+- 主流指数列表
+- 主力净流入对比图
+- 涨跌幅与净流入组合展示
+- 更新时间展示
+
+## 7. 当前代码能力评估
+
+## 7.1 已具备能力
+
+当前项目已具备以下基础能力：
+
+- 东方财富数据抓取基础客户端
+- 实时调度线程
+- MySQL 主存储链路
+- 原始 payload 存储能力
+- 前端图表展示能力
+- 后端 API 服务能力
+
+## 7.2 当前未完成部分
+
+当前尚未完成以下内容：
+
+- 个股资金流扩展接口接入
+- 板块资金流扩展接口接入
+- 指数资金流扩展接口接入
+- 三类数据的标准化入库
+- 三类数据的独立查询接口
+- 三类数据的前端展示页面
+
+## 7.3 当前阶段结论
+
+当前项目架构可以承载本次扩展，但目前正式完成的仍只有南向资金链路。
+
+对于东方财富资金扩展部分，当前结论是：
+
+- 架构已具备承载能力
+- 数据库已具备承载能力
+- 调度与展示框架已具备承载能力
+- 新三类数据接口仍需逐项接入与验证
+
+## 8. 本阶段验收标准
+
+满足以下条件可视为本阶段完成：
+
+- 能稳定获取东方财富个股资金流数据
+- 能稳定获取东方财富板块资金流数据
+- 能稳定获取东方财富指数资金流数据
+- 数据全部写入 MySQL
+- 前端页面按东方财富标准分类展示
+- 前端页面字段名称按东方财富标准命名
+- 不使用自定义改名替代东方财富原始分类
+- 每条数据保留来源地址、更新时间、原始 payload
+- 数据不可用时明确报错，不使用伪造数据
+
+## 9. 后续开发顺序建议
+
+建议按以下顺序推进：
+
+1. 先确认东方财富三类资金流接口和字段
+2. 再完成三类数据抓取脚本
+3. 再完成数据库入库与原始 payload 保存
+4. 再完成后端查询接口
+5. 最后完成前端图表和列表展示