Update project

2026-04-08 20:04:40 +08:00
parent 2eab960303
commit 862235ea89
130 changed files with 60206 additions and 231 deletions
--- a/黄金分割时空分析技术设计文档.md
+++ b/黄金分割时空分析技术设计文档.md
@ -0,0 +1,820 @@
+# 黄金分割时空分析技术设计文档
+
+## 1. 文档目标
+
+本文档用于定义“黄金分割时空分析”模块的技术实现方案。
+
+目标是：
+
+- 在首页新增一个独立入口
+- 用户输入代码或名称后，进入分析页面
+- 后端返回多周期行情、均线、成交量、ABC 结构、黄金分割、时间斐波那契和共振结果
+- 前端以独立模块承载，不影响现有：
+  - 南向资金模块
+  - A 股资金模块
+  - ETF 模块
+
+本文档重点回答以下问题：
+
+- 如何在当前项目中落地该功能
+- 如何保持与现有模块解耦
+- 如何设计前后端接口
+- 如何设计分析引擎
+- 如何设计图形化展示与绘图工具能力
+
+---
+
+## 2. 当前项目评估结论
+
+当前项目具备开发该功能的基础，但还没有现成的技术分析引擎和专业 K 线图表层。
+
+### 2.1 当前可复用能力
+
+前端已有：
+
+- Vue 3 + TypeScript + Vite
+- 首页总入口
+- 独立模块页面结构
+- composable 模式的数据加载组织方式
+
+后端已有：
+
+- FastAPI 路由层
+- service 分层
+- 东方财富客户端
+- 基础数据获取能力
+
+可直接复用的文件和结构：
+
+- [App.vue](C:\Users\Administrator\Desktop\nanxiang1\frontend\src\App.vue)
+- [HomePortal.vue](C:\Users\Administrator\Desktop\nanxiang1\frontend\src\components\home\HomePortal.vue)
+- [routes.py](C:\Users\Administrator\Desktop\nanxiang1\backend\app\api\routes.py)
+- [schemas.py](C:\Users\Administrator\Desktop\nanxiang1\backend\app\api\schemas.py)
+- [eastmoney_client.py](C:\Users\Administrator\Desktop\nanxiang1\backend\app\clients\eastmoney_client.py)
+
+### 2.2 当前缺失能力
+
+当前项目尚未具备：
+
+- 单标的多周期行情分析接口
+- MA5/13/21/34/55/89 计算引擎
+- ABC 全自动识别引擎
+- 黄金分割与时间斐波那契分析引擎
+- 多级别共振评分引擎
+- 真正的 K 线图与绘图工具
+
+因此，开发必须新增一套相对独立的分析模块。
+
+---
+
+## 3. 设计原则
+
+## 3.1 模块隔离原则
+
+新功能必须以独立模块实现，不能侵入式修改现有南向、A 股资金、ETF 模块逻辑。
+
+具体要求：
+
+- 首页仅新增一个入口卡片
+- 前端新增独立页面与独立 composable
+- 后端新增独立路由、schema、service、engine
+- 不修改现有模块的数据结构
+- 不复用现有资金模块 response 结构做兼容拼接
+
+## 3.2 可解释原则
+
+所有分析结果都必须可解释。
+
+后端返回结果时，不能只返回结论，还必须返回：
+
+- 起点和终点
+- A/B/C 点位置
+- 黄金分割位计算结果
+- 时间计数结果
+- 共振命中原因
+
+## 3.3 图形优先原则
+
+展示顺序必须如下：
+
+1. 优先叠加到 K 线图
+2. 若当前阶段无法叠加，则生成独立分析图
+3. 若图形能力仍不足，则输出结构化逻辑步骤
+
+## 3.4 兼容演进原则
+
+第一版先完成“可分析、可展示、可解释”，  
+后续再逐步增强到：
+
+- 交互式黄金分割尺
+- 波浪尺
+- 用户拖拽修正重算
+
+---
+
+## 4. 总体架构
+
+建议新增一个完整的 feature 纵切模块：
+
+### 4.1 前端新增模块
+
+- `frontend/src/components/analysis/`
+- `frontend/src/composables/useAnalysisData.ts`
+- `frontend/src/types/analysis.ts`
+
+### 4.2 后端新增模块
+
+- `backend/app/services/analysis_service.py`
+- `backend/app/services/analysis_engine.py`
+- `backend/app/services/analysis_visual_service.py`
+- `backend/app/api/analysis_schemas.py`
+- `backend/app/clients/market_symbol_resolver.py`
+
+### 4.3 路由接入
+
+新增独立接口，不污染现有 route 的业务语义：
+
+- `/analysis/resolve`
+- `/analysis/overview`
+- `/analysis/report`
+- `/analysis/chart`
+
+---
+
+## 5. 前端设计
+
+根据当前 Vue 项目结构，前端必须保持“首页薄、功能页独立、逻辑放 composable”。
+
+## 5.1 首页入口改造
+
+修改：
+
+- [App.vue](C:\Users\Administrator\Desktop\nanxiang1\frontend\src\App.vue)
+- [HomePortal.vue](C:\Users\Administrator\Desktop\nanxiang1\frontend\src\components\home\HomePortal.vue)
+
+新增一个新的视图类型：
+
+- `analysis`
+
+首页卡片建议命名：
+
+- `黄金分割时空分析`
+
+入口描述建议：
+
+- 输入股票、指数或 ETF 代码，输出多周期 K 线、ABC 结构、黄金分割、时间斐波那契与共振策略。
+
+## 5.2 组件边界设计
+
+建议组件地图如下：
+
+### 5.2.1 根页面
+
+- `AnalysisWorkspace.vue`
+
+职责：
+
+- 页面容器
+- 组织各子组件
+- 挂载数据加载 composable
+
+### 5.2.2 输入区
+
+- `AnalysisSymbolSearch.vue`
+
+职责：
+
+- 输入代码或名称
+- 触发查询
+- 展示解析后的标的信息
+
+### 5.2.3 基础概览区
+
+- `AnalysisOverviewCards.vue`
+
+职责：
+
+- 展示名称、代码、最新价、涨跌幅、分析时间
+- 展示当前主结构摘要
+
+### 5.2.4 多周期结构区
+
+- `AnalysisCyclePanel.vue`
+
+职责：
+
+- 展示日线、周线、60、90、120 的趋势状态
+- 展示均线排列与成交量摘要
+
+### 5.2.5 ABC 结构区
+
+- `AnalysisAbcPanel.vue`
+
+职责：
+
+- 展示各周期 A/B/C 点
+- 展示主结构与次级结构
+- 展示结构有效性
+
+### 5.2.6 时空策略区
+
+- `AnalysisStrategyPanel.vue`
+
+职责：
+
+- 展示明天策略
+- 展示后续策略
+- 展示条件判断语句
+
+### 5.2.7 共振提示区
+
+- `AnalysisResonancePanel.vue`
+
+职责：
+
+- 展示时间共振
+- 展示空间共振
+- 展示时空共振
+- 展示风险/机会提示等级
+
+### 5.2.8 图表区
+
+- `AnalysisChartPanel.vue`
+
+职责：
+
+- 承载 K 线图
+- 后续承载黄金分割尺、波浪尺、时间线
+
+## 5.3 前端数据流设计
+
+数据流必须保持 props down / events up。
+
+推荐方式：
+
+- `AnalysisWorkspace.vue` 持有查询状态
+- 通过 `useAnalysisData.ts` 拉取接口
+- 子组件只接收 props，不在子组件内部自行发请求
+
+## 5.4 前端状态设计
+
+建议在 composable 中维护以下状态：
+
+- `query`
+- `loading`
+- `error`
+- `symbol`
+- `report`
+- `chart`
+
+建议使用：
+
+- `shallowRef` 管理基础状态
+- `computed` 管理派生展示字段
+- `watch` 只处理副作用
+
+---
+
+## 6. 后端设计
+
+## 6.1 后端模块拆分
+
+### 6.1.1 Symbol Resolver
+
+文件建议：
+
+- `backend/app/services/symbol_resolver_service.py`
+
+职责：
+
+- 将输入的 `000688`、`科创50`、`510300` 等解析为统一标的对象
+- 生成标准 `secid`
+- 判断标的类型
+
+输出建议：
+
+- 代码
+- 名称
+- 市场
+- 标的类型
+- `secid`
+
+### 6.1.2 Market Data Service
+
+文件建议：
+
+- `backend/app/services/market_data_service.py`
+
+职责：
+
+- 调用东方财富客户端拉取：
+  - 实时报价
+  - 日线
+  - 周线
+  - 60 分钟
+  - 90 分钟
+  - 120 分钟
+
+说明：
+
+当前 `eastmoney_client.py` 已具备 `fetch_stock_kline` 能力，可基于 `klt` 扩展不同周期。
+
+建议周期映射：
+
+- `101`: 日线
+- `102`: 周线
+- `60`: 60 分钟
+- `90`: 90 分钟
+- `120`: 120 分钟
+
+若接口对 `90/120` 返回行为和实际行情工具不同，后端必须统一以实际返回的 K 线数据为准。
+
+### 6.1.3 Indicator Engine
+
+文件建议：
+
+- `backend/app/services/indicator_engine.py`
+
+职责：
+
+- 计算均线：
+  - `MA5`
+  - `MA13`
+  - `MA21`
+  - `MA34`
+  - `MA55`
+  - `MA89`
+- 计算量能变化
+- 计算背离辅助字段
+
+### 6.1.4 ABC Engine
+
+文件建议：
+
+- `backend/app/services/abc_engine.py`
+
+职责：
+
+- 识别每个周期的 A/B/C 点
+- 输出主结构与次级结构
+- 输出结构方向和有效性
+
+识别输入：
+
+- K 线数组
+- 均线
+- 成交量
+- 局部高低点
+- 趋势线断裂信息
+
+识别输出：
+
+- A 点时间与价格
+- B 点时间与价格
+- C 点时间与价格
+- 结构方向
+- 结构状态
+- 识别理由
+
+### 6.1.5 Fibonacci Engine
+
+文件建议：
+
+- `backend/app/services/fibonacci_engine.py`
+
+职责：
+
+- 基于主波段计算黄金分割位
+- 基于时间起点计算时间斐波那契
+
+空间位固定为：
+
+- `0.382`
+- `0.618`
+- `0.809`
+- `1.0`
+- `1.382`
+- `1.618`
+- `2.0`
+- `2.618`
+
+### 6.1.6 Resonance Engine
+
+文件建议：
+
+- `backend/app/services/resonance_engine.py`
+
+职责：
+
+- 识别时间共振
+- 识别空间共振
+- 识别时空共振
+- 识别 ABC 共振
+- 输出提示等级
+
+### 6.1.7 Analysis Service
+
+文件建议：
+
+- `backend/app/services/analysis_service.py`
+
+职责：
+
+- 协调 symbol resolver、market data、indicator、ABC、fibonacci、resonance
+- 聚合形成最终 report
+
+---
+
+## 7. API 设计
+
+## 7.1 标的解析接口
+
+### `GET /analysis/resolve`
+
+输入：
+
+- `q`: 用户输入代码或名称
+
+输出：
+
+- 标的名称
+- 代码
+- 类型
+- 市场
+- secid
+
+## 7.2 主分析接口
+
+### `GET /analysis/report`
+
+输入：
+
+- `q`: 标的代码或名称
+
+输出建议分为以下部分：
+
+- `symbol`
+- `snapshot`
+- `cycles`
+- `abc_structures`
+- `fibonacci_space`
+- `fibonacci_time`
+- `resonance`
+- `tomorrow_strategy`
+- `follow_strategy`
+- `calculation_steps`
+
+## 7.3 图表数据接口
+
+### `GET /analysis/chart`
+
+输入：
+
+- `q`
+- `cycle`
+
+输出：
+
+- K 线数据
+- 均线数据
+- 成交量数据
+- A/B/C 点
+- 黄金分割位
+- 时间斐波那契节点
+
+说明：
+
+这个接口主要服务图表层，避免把图形相关数据与 report 文本强耦合。
+
+---
+
+## 8. 数据结构设计
+
+建议新增独立 schema 文件：
+
+- `backend/app/api/analysis_schemas.py`
+
+建议至少定义以下模型：
+
+### 8.1 SymbolInfo
+
+- `code`
+- `name`
+- `market`
+- `security_type`
+- `secid`
+
+### 8.2 CycleSummary
+
+- `cycle`
+- `trend_label`
+- `ma_status`
+- `volume_status`
+- `close`
+- `ma_values`
+
+### 8.3 AbcPoint
+
+- `label`
+- `timestamp`
+- `price`
+- `k_index`
+
+### 8.4 AbcStructure
+
+- `cycle`
+- `direction`
+- `status`
+- `a_point`
+- `b_point`
+- `c_point`
+- `reasoning`
+
+### 8.5 FibonacciSpace
+
+- `cycle`
+- `anchor_start`
+- `anchor_end`
+- `levels`
+- `current_position_summary`
+
+### 8.6 FibonacciTime
+
+- `cycle`
+- `start_point`
+- `current_count`
+- `next_key_counts`
+- `next_window_summary`
+
+### 8.7 ResonanceItem
+
+- `level`
+- `type`
+- `cycles`
+- `summary`
+- `bullish_or_bearish`
+
+### 8.8 AnalysisReportResponse
+
+- `symbol`
+- `snapshot`
+- `cycles`
+- `abc_structures`
+- `fibonacci_space`
+- `fibonacci_time`
+- `resonance`
+- `tomorrow_strategy`
+- `follow_strategy`
+- `calculation_steps`
+
+---
+
+## 9. ABC 识别实现建议
+
+## 9.1 识别流程
+
+每个周期建议按以下步骤执行：
+
+1. 预处理 K 线数据
+2. 识别局部高点和低点
+3. 结合均线和成交量过滤噪音波动
+4. 识别趋势段
+5. 候选 A 点识别
+6. 回撤比例识别 B 点
+7. 扩展位与时间位识别 C 点
+8. 依据优先级选出主结构
+
+## 9.2 主结构优先级
+
+优先级建议如下：
+
+1. 周线高于日线
+2. 日线高于分钟线
+3. 同级别中，波段完整度更高者优先
+4. 同级别中，命中黄金位更多者优先
+5. 同级别中，成交量配合更明显者优先
+
+## 9.3 工程上的“零争议”
+
+工程上定义为：
+
+- 相同输入数据
+- 相同识别规则
+- 相同参数配置
+
+必须得到相同的 A/B/C 识别结果。
+
+这里强调的是：
+
+- 结果稳定
+- 规则固定
+- 过程可解释
+
+而不是主观层面的“所有交易者都认同”。
+
+---
+
+## 10. 黄金分割与时间斐波那契实现建议
+
+## 10.1 空间计算
+
+若上涨波段低点为 `L`，高点为 `H`，则回撤位：
+
+```text
+level = H - (H - L) × ratio
+```
+
+若为下跌反弹，则反向计算。
+
+需要统一支持：
+
+- 回撤测算
+- 扩展测算
+- 等幅测算
+
+## 10.2 时间计数
+
+时间起点优先来源于：
+
+- 主结构 A 点
+- 主波段起点
+
+每个周期分别计数：
+
+- `60`
+- `90`
+- `120`
+
+关键时间数列固定为：
+
+- `13`
+- `21`
+- `34`
+- `55`
+- `89`
+
+---
+
+## 11. 图表与绘图工具设计
+
+## 11.1 当前状态
+
+当前前端只有 SVG 趋势折线图组件，不具备 K 线和绘图工具能力。  
+因此，图表层需要新增独立实现。
+
+## 11.2 第一版建议
+
+第一版优先做：
+
+- K 线图基础展示
+- MA 线叠加
+- 成交量
+- A/B/C 点标记
+- 黄金位横线
+- 时间位竖线
+
+## 11.3 第二版建议
+
+第二版增加：
+
+- 黄金分割尺
+- 黄金扩展尺
+- 波浪尺
+- 趋势线
+- 水平线
+
+## 11.4 第三版建议
+
+第三版增加：
+
+- 用户拖拽修正
+- 工具图层管理
+- 联动重算
+
+## 11.5 图表技术建议
+
+当前项目没有图表依赖。  
+若要实现接近同花顺的体验，建议引入专业图表库或单独实现 K 线组件。
+
+建议选择方向：
+
+- 方案 A：引入专业轻量 K 线图表库，再叠加自定义图层
+- 方案 B：完全自研 SVG/Canvas K 线组件
+
+从开发效率看，优先建议方案 A。
+
+---
+
+## 12. 不影响其他模块的实现方案
+
+为了避免影响现有功能，必须做到以下隔离：
+
+## 12.1 前端隔离
+
+- 新增 `analysis` 视图，不修改现有模块内部逻辑
+- 新模块组件全部放在 `components/analysis/`
+- 新模块数据逻辑全部放在 `useAnalysisData.ts`
+- 不修改现有 `useEtfData.ts`、`useDashboardData.ts`、`useAShareData.ts`
+
+## 12.2 后端隔离
+
+- 新增 `/analysis/*` 路由
+- 新增独立 schema
+- 新增独立 service / engine
+- 不修改原资金流 service 的输出结构
+
+## 12.3 样式隔离
+
+- 新页面使用独立命名空间 class
+- 不污染现有首页与 ETF 页样式
+
+## 12.4 运行风险隔离
+
+- 新模块请求失败不影响现有模块渲染
+- 新接口异常不影响原有 API 正常响应
+
+---
+
+## 13. 开发顺序建议
+
+## 13.1 第一阶段
+
+先完成：
+
+- 首页新增入口
+- 标的解析接口
+- 主分析接口骨架
+- 多周期 K 线数据拉取
+- 均线与成交量分析
+- 基础策略输出
+
+## 13.2 第二阶段
+
+再完成：
+
+- ABC 引擎
+- 黄金分割与时间斐波那契引擎
+- 共振提示
+- 页面各分析面板
+
+## 13.3 第三阶段
+
+最后完成：
+
+- K 线图层
+- 图形化叠加
+- 黄金尺/波浪尺
+- 手动修正联动重算
+
+---
+
+## 14. MVP 边界
+
+建议首版上线范围控制为：
+
+- 首页新增入口
+- 输入代码分析
+- 日/周/60/90/120 周期分析
+- MA5/13/21/34/55/89
+- 成交量摘要
+- 黄金分割空间位
+- 时间斐波那契计数
+- A/B/C 自动识别第一版
+- 明天策略 / 后续策略
+- 共振提示
+- 逻辑测算步骤
+
+首版可以暂不要求：
+
+- 同花顺级拖拽体验
+- 完整波浪尺交互
+- 图片导出
+
+---
+
+## 15. 可立即开始的开发项
+
+从当前项目状态看，可以立即开始开发以下内容：
+
+1. 首页新增入口与新视图
+2. 后端新增 `/analysis/report` 接口
+3. 标的解析与 K 线数据拉取
+4. 均线、成交量、黄金位、时间位计算
+5. 分析页面基础展示
+
+这几项做完后，系统就会具备第一个可运行版本。
+
+---
+
+## 16. 结论
+
+该功能已经具备进入开发阶段的条件。
+
+最合理的落地方式不是一次性做完整终态，而是：
+
+- 先做独立入口
+- 再做分析引擎
+- 再做页面展示
+- 最后补图形化绘图工具
+
+这样既能快速形成可运行版本，也能确保不影响现有功能模块。