# 黄金分割时空分析技术设计文档

## 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. 结论

该功能已经具备进入开发阶段的条件。

最合理的落地方式不是一次性做完整终态，而是：

- 先做独立入口
- 再做分析引擎
- 再做页面展示
- 最后补图形化绘图工具

这样既能快速形成可运行版本，也能确保不影响现有功能模块。