yuxuanhui
74 lines
5.7 KiB
Markdown
74 lines
5.7 KiB
Markdown
# 选股模块图表展示技术设计
|
||
|
||
## 1. 边界与总体方案
|
||
|
||
本任务继续使用现有 `selection` bounded context，不新建业务上下文。分页结果接口继续只承载列表与目标日摘要；新增独立只读详情接口按 `ts_code + target_trade_date` 返回最多 250 个升序 qfq 日线点及对应 KDJ，避免每页股票都携带大数组。
|
||
|
||
前端 selection feature 用独立 React Query 缓存详情图表。从现有 `md` 双栏断点起，工作台统一使用左 `1fr`、右 `3fr`，删除更大断点的旧比例覆盖；移动端沿用现有记录卡和展开交互，不在本次增加移动端复合图表。右侧详情依次展示股票摘要、复合图表、最佳案例 JPG、评分分解和信号指标。
|
||
|
||
## 2. 后端数据流与契约
|
||
|
||
新增 application 用例 `GetSelectionChart`，依赖已有 `MarketDataReader`。用例接收 `ts_code`、`target_trade_date` 和固定上限 250，读取目标日前完整 qfq 历史，在完整历史上复用 `compute_kdj` 计算递归 K/D/J，再把 OHLCV 与指标对齐并截取末尾最多 250 条。这样返回量受控，同时 KDJ 初值与策略计算保持一致。
|
||
|
||
新增接口：
|
||
|
||
```text
|
||
GET /api/v1/selection/stocks/{ts_code}/chart?target_trade_date=YYYY-MM-DD
|
||
```
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"ts_code": "603259.SH",
|
||
"name": "药明康德",
|
||
"target_trade_date": "2026-08-31",
|
||
"source_adj": "qfq",
|
||
"points": [
|
||
{
|
||
"trade_date": "2026-08-31",
|
||
"open": 1.0,
|
||
"high": 1.0,
|
||
"low": 1.0,
|
||
"close": 1.0,
|
||
"volume": 1.0,
|
||
"k": 50.0,
|
||
"d": 50.0,
|
||
"j": 50.0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
OHLCV 或 KDJ 不可用的点用 `null` 保留日期对齐，不制造数值。前端遇到 OHLC 不完整的日期时保留 category 但不绘制该蜡烛，volume/K/D/J 也保持空点，KDJ 禁止跨空点连线。没有任何目标日前行情时返回 `404 chart_data_not_found`；数据库读取失败返回 `503 selection_storage_unavailable`。接口继续使用 FastAPI Pydantic response model 和同源 `/api/v1` 路径。
|
||
|
||
## 3. 最佳案例评分与图片
|
||
|
||
不改变十案例评分算法、阈值、排序或持久化。调整 HTTP 映射：只要评分状态是 `matched` 或 `below_threshold` 且内部结果完整，都返回实际 `value`、`threshold`、`version`、`case` 和 `breakdown`；状态仍保留原值，因此 UI 可以区分“达到阈值”和“最接近但低于阈值”。评分失败返回 `status="failed"` 且无 case；评分未执行沿用现有 `score: null` 契约，前端明确显示“本次运行未执行图形评分”，两者均不展示案例图。契约测试锁定 `null` 的既有语义，避免把字段遗漏误当成功结果。
|
||
|
||
把用户提供的十张 JPG 复制到 `zhixing-web/public/patterns/b1-cases/` 并保留原文件名。selection feature 维护穷举的 `case.id -> public URL` 映射；案例 ID 是稳定业务键，中文名只用于展示。若响应出现未知 case id，页面显示“案例图片暂不可用”，不猜测文件名。
|
||
|
||
## 4. 前端数据与组件
|
||
|
||
新增 `SelectionChart`、`SelectionChartPoint` 类型，API 函数通过 `requestJson` 调用详情接口并传递 `AbortSignal`，query key 包含股票代码和目标交易日。仅当存在选中股票时启用查询；切换股票时 React Query 取消或隔离旧请求，详情分别呈现加载、失败、空数据和成功状态。
|
||
|
||
新增 selection feature 内的复合图表组件，直接使用 `echarts/core`，按需注册 candlestick、bar、line、grid、tooltip、legend、dataZoom 和 Canvas renderer。三组 category x 轴共享相同交易日数组，candlestick、volume、K/D/J series 分别绑定三个 grid；inside 与 slider dataZoom 同时控制三组 x 轴。后端最多返回 250 点，前端通过 category `startValue`/`endValue` 精确选择末尾 120 点，不足 120 点时展示全部，并允许缩放查看返回的全部数据。
|
||
|
||
ECharts 初始化只发生在图表 DOM 挂载后；数据变化调用 `setOption`，容器变化通过 `ResizeObserver` 调用 `resize`，卸载时 `dispose`。option 构造与 API 数据转换保持为纯函数，避免在 jsdom 中依赖 Canvas 像素渲染。
|
||
|
||
最佳案例组件从 `score.case.id` 查找静态 JPG，使用语义标题、描述性 `alt`、固定 2:1 比例和 `loading="lazy"`。图像加载失败时保留案例名称和可读错误状态。
|
||
|
||
## 5. 兼容性与取舍
|
||
|
||
- 不把历史序列扩展到 `/selection/results`，避免分页和轮询响应膨胀。
|
||
- 不新增图片数据库、上传接口或动态生成逻辑；案例库固定，因此静态资源映射是最小充分方案。
|
||
- 不引入 React ECharts wrapper，减少 React 19 兼容面；只增加 `echarts` 一个运行时依赖。
|
||
- 移动端暂不加载大图表，维持现有详情展开行为；桌面端按需求提供完整详情。
|
||
- 不新增迁移。最佳案例字段已经持久化，图表读取复用现有 market data。
|
||
|
||
## 6. 风险、回滚与验证重点
|
||
|
||
主要风险是 KDJ 窗口被错误截断、股票切换显示上一只股票的数据、ECharts 容器未 resize/dispose、缺失行情点错误连线、未知案例 ID 产生错误图片，以及低于阈值的最佳案例仍被 HTTP 丢弃。测试分别锁定完整历史计算后截断、query key、加载/错误/空状态、三轴同步 option、缺失点处理、静态映射完整性和 below-threshold 契约。案例图片行为测试必须断言详情中恰有一张 `<img>`，其 `src` 由返回的 `case.id` 映射，案例名称和评分与同一响应一致；低于阈值也执行同一断言。
|
||
|
||
回滚可以按层撤销：删除新增详情接口与用例、恢复评分 HTTP 映射、移除 ECharts 组件/依赖和静态 JPG，再恢复原 grid class；没有数据库迁移或不可逆数据写入。
|