From 9a965fab14980afe206d68376eebfe1a903b50ed Mon Sep 17 00:00:00 2001
From: Citrons <909229731@qq.com>
Date: Tue, 18 Aug 2026 12:48:28 +0800
Subject: [PATCH] =?UTF-8?q?docs(FEAT-MO-001):=20=E7=A1=AE=E8=AE=A4TDX?=
 =?UTF-8?q?=E7=9B=B4=E8=BF=9E=E6=A6=82=E8=A7=88=E8=AE=BE=E8=AE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...08-18-market-overview-tdx-direct-design.md | 140 ++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-18-market-overview-tdx-direct-design.md

diff --git a/docs/superpowers/specs/2026-08-18-market-overview-tdx-direct-design.md b/docs/superpowers/specs/2026-08-18-market-overview-tdx-direct-design.md
new file mode 100644
index 0000000..8662b28
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-18-market-overview-tdx-direct-design.md
@@ -0,0 +1,140 @@
+# 市场综合概览 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 配置。