docs(FEAT-MO-005): 固化市场结构与成交额趋势设计
This commit is contained in:
@@ -0,0 +1,159 @@
|
|||||||
|
# 市场结构与成交额趋势设计
|
||||||
|
|
||||||
|
- 关联功能：FEAT-MO-005
|
||||||
|
- 设计状态：待用户审阅
|
||||||
|
- 日期：2026-08-25
|
||||||
|
|
||||||
|
## 1. 目标
|
||||||
|
|
||||||
|
把综合概览的重点从可选分时图调整为盘面结构总结，优先回答：市场强弱如何、行业和题材资金及涨跌方向如何、全市场成交额是在放大还是收缩。
|
||||||
|
|
||||||
|
本切片继续采用 Nest 服务端聚合、Vue 通过 Axios 访问业务 API 的边界。TDX 保持指数、市场宽度和基础行情主链路；AKTools/AKShare 只作为行业、题材和资金流向的候选补充源，必须先通过实际能力探针。
|
||||||
|
|
||||||
|
## 2. 用户范围
|
||||||
|
|
||||||
|
### 首屏展示
|
||||||
|
|
||||||
|
1. 市场结论和主要指数。
|
||||||
|
2. 上涨、下跌、平盘、涨停、跌停、炸板等市场宽度与短线情绪。
|
||||||
|
3. 行业和题材的涨跌排行。
|
||||||
|
4. 行业和题材资金净流入、净流出排行。
|
||||||
|
5. 全市场成交额趋势图和累计成交额。
|
||||||
|
6. 每个模块的交易日期、最后更新时间、数据源和 `fresh/delayed/partial/unavailable` 状态。
|
||||||
|
|
||||||
|
### 交互范围
|
||||||
|
|
||||||
|
- 首屏每个排行模块只展示重点名次，并提供“查看全部”入口。
|
||||||
|
- 排行支持行业/题材切换，以及涨幅、跌幅、成交额、净流入、净流出排序。
|
||||||
|
- 点击行业或题材进入现有详情页体系；无法识别的 provider 原始分类不得生成错误详情链接。
|
||||||
|
- 成交额趋势支持盘中增量和累计值；收盘后保留完整交易日曲线。
|
||||||
|
|
||||||
|
## 3. 明确不在本切片范围
|
||||||
|
|
||||||
|
- 不把分时 K 线作为首页核心视图；详情页分时仍保持独立能力验证状态。
|
||||||
|
- 不提供交易指令、荐股、目标价、仓位建议或自动下单。
|
||||||
|
- 不启用用户体系、MySQL、Redis、RocketMQ 或 AI 运行链路。
|
||||||
|
- 不把价格涨跌、成交额或成交量推导成主力净流入；资金净流入必须来自有明确字段口径的数据源。
|
||||||
|
- 不把单个行业指数代表全市场资金；全市场成交额与板块资金流必须分别标识。
|
||||||
|
|
||||||
|
## 4. 数据源与口径
|
||||||
|
|
||||||
|
### 4.1 TDX 主链路
|
||||||
|
|
||||||
|
- 指数、市场宽度、核心行情和已验证的日成交额继续使用 TDX。
|
||||||
|
- 当前已有的日成交额趋势只能作为收盘后及历史对比口径，不能直接冒充盘中 5/15 分钟趋势。
|
||||||
|
- 盘中成交额趋势必须先验证 TDX 是否能返回多市场、带时间戳的分时 Amount；若 TDX 不支持，再评估 AKTools 或快照聚合方案。
|
||||||
|
|
||||||
|
### 4.2 AKTools/AKShare 补充链路
|
||||||
|
|
||||||
|
优先探测以下能力：
|
||||||
|
|
||||||
|
- 行业板块涨跌幅和成交额排行。
|
||||||
|
- 概念题材涨跌幅和成交额排行。
|
||||||
|
- 行业/题材资金净流入和净流出排行。
|
||||||
|
- 全市场或指数的分时成交额字段。
|
||||||
|
|
||||||
|
探针必须记录接口参数、HTTP 状态、字段结构、交易日期、更新时间和重复请求稳定性；不保存原始载荷。探针失败时只记录 `unavailable`，不生成示例数据。
|
||||||
|
|
||||||
|
### 4.3 分类口径
|
||||||
|
|
||||||
|
- `industry`：供应商的行业板块分类。
|
||||||
|
- `concept`：供应商的概念/题材分类。
|
||||||
|
- `board`：仅在数据源明确提供独立板块分类时启用；不能把行业或概念重复映射成第三种分类。
|
||||||
|
- 每条排行记录必须带 `category`、`code`、`name`、`tradeDate`、`asOf` 和 `source`。
|
||||||
|
|
||||||
|
### 4.4 资金口径
|
||||||
|
|
||||||
|
- `netInflow` 只能使用上游明确提供的净流入字段。
|
||||||
|
- 无法确认主力、大单或统计方向时返回 `null` 并说明原因。
|
||||||
|
- 不同数据源的资金字段不在服务端直接求和；跨源比较只在字段口径相同且文档明确时允许。
|
||||||
|
|
||||||
|
### 4.5 成交额趋势口径
|
||||||
|
|
||||||
|
- 基本单位统一为亿元；服务端负责单位转换，前端不根据字段名猜单位。
|
||||||
|
- 每个点至少包含 `time`、`amount`、`cumulativeAmount`。
|
||||||
|
- `amount` 表示该时间区间成交额，`cumulativeAmount` 表示当日截至该点累计成交额。
|
||||||
|
- 缺少时间戳、金额为负数、时间倒序或区间重复时，该点被拒绝并将模块标记为 `partial`。
|
||||||
|
|
||||||
|
## 5. API 设计
|
||||||
|
|
||||||
|
继续使用统一响应外壳：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"snapshotId": "20260825-101500",
|
||||||
|
"asOf": "2026-08-25T10:15:00+08:00",
|
||||||
|
"tradeDate": "20260825",
|
||||||
|
"source": "tdx",
|
||||||
|
"status": "fresh",
|
||||||
|
"data": {},
|
||||||
|
"warnings": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
新增或调整为以下独立接口，禁止把所有数据塞入一个首页接口：
|
||||||
|
|
||||||
|
```text
|
||||||
|
GET /api/market-overview/sector-rankings
|
||||||
|
GET /api/market-overview/capital-flow
|
||||||
|
GET /api/market-overview/turnover-trend
|
||||||
|
```
|
||||||
|
|
||||||
|
### `sector-rankings`
|
||||||
|
|
||||||
|
查询参数：`category=industry|concept|board`、`sort=rise|fall|turnover`、`limit=1..100`。
|
||||||
|
|
||||||
|
记录字段：`category`、`code`、`name`、`changePercent`、`turnoverAmount`、`advancingCount`、`decliningCount`、`leader`、`tradeDate`。
|
||||||
|
|
||||||
|
### `capital-flow`
|
||||||
|
|
||||||
|
查询参数：`category=industry|concept|board`、`sort=inflow|outflow`、`limit=1..100`。
|
||||||
|
|
||||||
|
记录字段：`category`、`code`、`name`、`netInflow`、`netOutflow`、`turnoverAmount`、`tradeDate`、`flowDefinition`。
|
||||||
|
|
||||||
|
### `turnover-trend`
|
||||||
|
|
||||||
|
查询参数：`interval=5|15`、`tradeDate=YYYYMMDD`（默认最近可用交易日）。
|
||||||
|
|
||||||
|
记录字段：`time`、`amount`、`cumulativeAmount`；响应额外返回 `unit=亿元`、`marketCount` 和 `granularity`。
|
||||||
|
|
||||||
|
所有参数使用白名单和范围校验；上游地址、原始异常和完整载荷不得进入响应。
|
||||||
|
|
||||||
|
## 6. 前端结构
|
||||||
|
|
||||||
|
```text
|
||||||
|
web/src/api/market-overview/index.ts
|
||||||
|
web/src/views/market-overview/
|
||||||
|
├── components/MarketSummaryPanel.vue
|
||||||
|
├── components/MarketBreadthPanel.vue
|
||||||
|
├── components/SectorRankingPanel.vue
|
||||||
|
├── components/CapitalFlowPanel.vue
|
||||||
|
└── components/TurnoverTrendPanel.vue
|
||||||
|
```
|
||||||
|
|
||||||
|
组件只消费已生成的契约类型，不直连 AKTools/TDX。排行表格优先保证扫描效率，避免把全部分类堆叠在首屏；窄屏时改为分类标签和横向可滚动表格，不能出现页面级横向溢出。
|
||||||
|
|
||||||
|
## 7. 失败、时效和安全
|
||||||
|
|
||||||
|
- 四类状态沿用 `fresh`、`delayed`、`partial`、`unavailable`。
|
||||||
|
- 单个上游接口失败只影响对应模块；其他模块继续展示。
|
||||||
|
- 收盘后的最后记录不自动判定为延迟；必须结合上海交易时段和交易日期判断。
|
||||||
|
- AKTools 仍只允许服务端固定白名单调用，设置超时、响应体上限、字段校验和错误脱敏。
|
||||||
|
- 不保存行情原始载荷，不记录家庭网络地址、TDX 凭据或 AKTools 凭据。
|
||||||
|
|
||||||
|
## 8. 性能与验证目标
|
||||||
|
|
||||||
|
- 排行接口只返回请求的 `limit` 条记录；服务端拒绝超过 100 条的单次请求。
|
||||||
|
- 首页模块并行请求，单个模块超时不阻塞首屏。
|
||||||
|
- 成交额趋势默认最多返回一个交易日的 5 分钟点，必要时再支持 15 分钟降采样。
|
||||||
|
- 单测覆盖字段映射、单位转换、排序、分类白名单、资金口径缺失、时间倒序、重复点和部分数据。
|
||||||
|
- 真实联调至少覆盖交易时段一次和收盘后一次，分别记录最后时间、成功率、缺口率和状态判断。
|
||||||
|
- 完成 HTTP/OpenAPI、前端状态、构建、Playwright 桌面/窄屏、代码 Review 和规范 Review。
|
||||||
|
|
||||||
|
## 9. 分阶段实施
|
||||||
|
|
||||||
|
1. 数据源能力探针：先确认行业/题材排行、资金流和盘中成交额接口。
|
||||||
|
2. 服务端适配器与 DTO：固定数据源边界，先输出独立 API。
|
||||||
|
3. 前端排行和成交额趋势组件：接入模块状态和点击详情。
|
||||||
|
4. 盘中与收盘后联调：校验时间口径和数据质量。
|
||||||
|
5. 完成治理档案、Review、GitNexus 前后对比和 Gitea 推送。
|
||||||
Reference in New Issue
Block a user