# 市场综合概览 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 配置。