141 lines
6.1 KiB
Markdown
141 lines
6.1 KiB
Markdown
# 市场综合概览 TDX 直连设计
|
|
|
|
- 功能编号：FEAT-MO-001
|
|
- 设计版本：0.2
|
|
- 状态：已获用户确认，待实现计划
|
|
- 日期：2026-08-18
|
|
|
|
## 1. 设计目标
|
|
|
|
首页市场概览直接使用 TDX 行情数据，向用户提供结论优先的综合盘面视图。数据链路不保留离线样本 Provider 或运行时数据源切换，TDX 不可用时明确展示不可用状态，不伪造实时行情。
|
|
|
|
首屏支持综合、短线和中长线视角，以及规则、AI、混合和对照模式的状态入口；本次 TDX 首屏只提供统一的市场快照和规则事实展示，不在本轮实现付费 AI 结论。
|
|
|
|
## 2. 系统边界
|
|
|
|
浏览器不得直接连接 TDX。Nest API 在服务端调用本机 TDX 隧道端点，Vue 通过既有 Axios 封装访问 Nest API。
|
|
|
|
```text
|
|
Vue 市场概览
|
|
-> Axios request 封装
|
|
-> Nest 市场概览 API
|
|
-> TDX HTTP 客户端
|
|
-> 127.0.0.1:17710
|
|
-> SSH / Tailscale 隧道
|
|
-> Windows 127.0.0.1:17709
|
|
-> TDX
|
|
```
|
|
|
|
家庭局域网和外出 Tailscale 只改变 SSH 别名和网络路径，业务服务始终访问本机 `127.0.0.1:17710`。真实地址、用户、密钥和控制套接字只保存在开发机，不进入仓库。
|
|
|
|
## 3. 后端模块设计
|
|
|
|
后端按市场概览业务模块组织，保持连续可读的职责边界：
|
|
|
|
```text
|
|
server/apps/api/src/market-overview/
|
|
├── market-overview.module.ts
|
|
├── market-overview.controller.ts
|
|
├── market-overview.service.ts
|
|
├── market-overview.dto.ts
|
|
└── tdx/
|
|
├── tdx.client.ts
|
|
├── tdx.mapper.ts
|
|
└── tdx.types.ts
|
|
```
|
|
|
|
- `controller`：提供按业务模块拆分的只读 HTTP 接口。
|
|
- `service`：组织 TDX 数据、统一快照时间并生成规则事实摘要。
|
|
- `dto`：定义 HTTP 响应契约，禁止把 TDX 原始字段直接暴露给前端。
|
|
- `tdx.client`：只负责请求本机 TDX 端点、超时和协议级错误。
|
|
- `tdx.mapper`：把 TDX 原始字段转换为领域字段和展示口径。
|
|
- `tdx.types`：描述经过确认的 TDX 原始响应结构。
|
|
|
|
首版接口：
|
|
|
|
```text
|
|
GET /api/market-overview/summary
|
|
GET /api/market-overview/indices
|
|
GET /api/market-overview/breadth
|
|
GET /api/market-overview/sectors
|
|
GET /api/market-overview/funds
|
|
```
|
|
|
|
接口按模块拆分，页面进入时可并行请求；每个接口失败不会使其他模块整体失败。未来详情页可以复用指数和板块的业务边界，不通过新增巨型首页接口解决。
|
|
|
|
## 4. 前端模块设计
|
|
|
|
```text
|
|
web/src/
|
|
├── api/market-overview/index.ts
|
|
├── views/market-overview/
|
|
│ ├── MarketOverviewPage.vue
|
|
│ ├── useMarketOverview.ts
|
|
│ └── components/
|
|
└── types/market-overview.ts
|
|
```
|
|
|
|
业务请求只能通过 `web/src/api/market-overview/index.ts` 调用 `web/src/utils/request.ts`。页面组件不直接使用 Axios、不拼接 TDX 地址，也不读取服务端环境变量。
|
|
|
|
首屏顺序：市场结论、驱动与风险、核心指数、涨跌分布与市场宽度、成交量与成交额、板块强弱、资金趋势、更新时间和 TDX 连接状态。指数和板块保留进入未来详情页的可识别入口。
|
|
|
|
## 5. 响应契约与状态
|
|
|
|
每个业务接口采用统一外层结构：
|
|
|
|
```json
|
|
{
|
|
"snapshotId": "20260818-101500",
|
|
"asOf": "2026-08-18T10:15:00+08:00",
|
|
"source": "tdx",
|
|
"status": "fresh",
|
|
"data": {},
|
|
"warnings": []
|
|
}
|
|
```
|
|
|
|
`status` 取值为 `fresh`、`delayed`、`partial` 或 `unavailable`。`snapshotId` 和 `asOf` 用于让并行接口在同一次市场快照下可对照；数据日期、更新时间和来源状态必须在页面可见。
|
|
|
|
- TDX 单个模块失败：只显示对应模块错误。
|
|
- TDX 返回部分字段：保留可用字段并标记 `partial`。
|
|
- TDX 超时或完全不可用：显示连接状态和重试入口，不显示虚假行情。
|
|
- 后端日志只记录脱敏错误摘要，不保存完整原始行情载荷。
|
|
|
|
## 6. 安全策略
|
|
|
|
- TDX 地址固定来自服务端配置，禁止由 HTTP 请求参数传入任意 URL，避免 SSRF。
|
|
- TDX 仅通过本机回环端点访问；Windows TDX 继续只监听 `127.0.0.1:17709`。
|
|
- API 只读，不提供交易指令、买卖建议、目标价或仓位建议。
|
|
- SSH、Tailscale、TDX 账号、密钥、密码、本地环境文件和生产地址不提交 Git。
|
|
- 真实行情只用于只读联调，日志、测试报告和截图不得保存家庭网络信息或完整原始载荷。
|
|
|
|
## 7. 性能策略
|
|
|
|
- 页面并行请求各业务接口，避免串行阻塞整页。
|
|
- TDX 客户端设置连接超时和读取超时，并记录请求耗时。
|
|
- DTO 只返回页面需要字段，不透传完整 TDX 原始响应。
|
|
- 首版采用分钟级刷新，不承诺秒级实时；暂不启用 Redis 缓存，待数据口径和刷新频率稳定后评估。
|
|
- 前端使用模块级加载、空、部分数据和错误状态，避免一个模块阻断首屏。
|
|
|
|
## 8. 测试与验证
|
|
|
|
- TDX 类型转换和展示口径的单元测试。
|
|
- 每个接口的成功、超时、空数据、部分字段和不可用测试。
|
|
- Nest API 响应契约和错误状态测试。
|
|
- Vue API 模块、页面状态和模块级失败降级测试。
|
|
- 家庭局域网 SSH 路径和外出 Tailscale SSH 路径的端到端只读联调。
|
|
- 桌面与窄屏视觉验证，确认结论、更新时间和错误状态不重叠。
|
|
- 开发前和提交前执行 GitNexus 影响分析与变更检测；开发完成执行代码 Review、规范 Review、测试、构建和 `governance:finish`。
|
|
|
|
## 9. 明确不在本次实现范围
|
|
|
|
- 离线样本 Provider、运行时数据源切换和自动回退。
|
|
- MySQL、Redis、RocketMQ 的正式行情存储或采集链路。
|
|
- 付费 AI 请求和 AI 结论生成。
|
|
- 用户、邀请、会员、订阅、社区、自选股、笔记、计划和交易功能。
|
|
- 指数或板块详情页的完整实现；本次只保留入口和接口边界。
|
|
|
|
## 10. 回退方案
|
|
|
|
若 TDX 协议字段无法稳定确认、首屏核心模块无法独立降级或隧道联调影响本地构建，则停止 TDX 直连功能提交，回退到上一个本地标签；不得以样本数据冒充 TDX 实时结果。回退只撤销本功能提交，不删除开发机 SSH、Tailscale 或 TDX 配置。
|