diff --git a/docs/features/FEAT-DS-001-tdx-ingestion-poc/design.md b/docs/features/FEAT-DS-001-tdx-ingestion-poc/design.md new file mode 100644 index 0000000..93684e9 --- /dev/null +++ b/docs/features/FEAT-DS-001-tdx-ingestion-poc/design.md @@ -0,0 +1,55 @@ +# 数据源接入架构与 TDX PoC 规划 + +## 方案结论 + +当前采用“平台先行、采集器后置”。Mac 本地开发以固定样本回放为默认 Provider;需要验证真实字段时,通过 Tailscale + SSH 隧道访问家中 Windows 的 TDX `127.0.0.1:17709`。不在当前阶段实现 Windows 常驻采集程序、GUI 或公网推送。 + +```text +固定样本 / Mac TDX 隧道 + ↓ +DataProvider 端口 + ↓ +标准化市场事件 → 市场概览业务 + +未来公网模式:采集器 → 多目标隔离推送 → 平台接收 API +``` + +## 方案比较 + +- 本地样本回放(当前采用):不引入 Windows/公网依赖,测试稳定可重复,适合先开发市场概览;缺点是不能代表实时数据质量。 +- Mac 通过 Tailscale SSH 隧道调用 TDX(当前联调):可以验证真实字段,但依赖家中 Windows 在线和人工维护。 +- Windows 常驻采集器(延期):未来可选 Node、Python、Go、Rust、Electron、Tauri 或系统服务,必须按部署规模、资源、自动更新和安全能力重新评估。 + +## 当前组件边界 + +当前只新增/维护平台侧 Provider 端口和固定样本。样本 Provider 与真实 TDX Provider 使用同一标准化契约,市场概览不感知来源差异。未来采集器应作为独立项目或 workspace,不反向污染 NestJS 业务模块;公网接收 API、目标队列、签名握手和 GUI 另立功能档案。 + +## Provider 与事件模型 + +Provider 生成不可变标准化事件,包含 `eventId`、`source`、`capturedAt`、`tradeDate`、`schemaVersion`、`traceId` 和数据新鲜度。TDX 原始字段只能存在于 Adapter 内,规则分析、AI 分析、API 和页面只依赖内部模型。 + +## 安全策略与评估 + +- Mac 本地样本和 TDX 隧道均不接触生产配置、生产数据库或公网接收 API。 +- 真实 TDX 只读调用使用 SSH 密钥隧道,`17709`、SSH 和 RDP 不做公网端口映射。 +- 样本删除凭据、家庭地址和无关原始字段;日志只保存统一错误分类和性能摘要。 +- 未来采集器的密钥存储、目标认证、IPC 和自动更新不在当前方案中预设,必须重新安全评估。 +- 数据再分发许可属于外部合规风险。PoC 只用于个人开发验证,不宣称获得商业展示或再分发授权。 + +## 性能目标与评估 + +- 固定样本回放必须确定性、可重复且不访问网络;Provider 标准化耗时纳入单元测试与基准记录。 +- 真实 TDX 请求目标超时 5 秒并记录响应耗时和字段完整性。 +- 公网上传并发、队列容量、心跳周期和 GUI 资源目标延期到采集器立项,不在当前阶段作容量承诺。 + +## 失败恢复 + +TDX 请求失败返回统一错误分类和陈旧状态;本地平台可切回固定样本继续开发,不能把样本伪装为实时行情。上传重试、补传、熔断和备用免费源切换属于后续公网功能。 + +## 测试边界 + +单元测试使用固定 TDX 响应验证 Provider、标准化和错误映射;通过 Tailscale SSH 隧道做真实只读冒烟。Electron/Tauri 安装、托盘、开机启动、操作系统密钥存储、目标队列和公网接收测试延期,不能在当前阶段宣称通过。 + +## 依赖与退出方案 + +当前不新增 Electron、Python、Go、Rust 或其他采集器运行时依赖。未来采集器实现前重新比较语言、部署形态、许可证、资源、自动更新和安全边界;只要遵循 Provider/上传契约,采集器可替换而不改市场概览。 diff --git a/docs/features/FEAT-DS-001-tdx-ingestion-poc/gitnexus/before.md b/docs/features/FEAT-DS-001-tdx-ingestion-poc/gitnexus/before.md new file mode 100644 index 0000000..c1ee9f6 --- /dev/null +++ b/docs/features/FEAT-DS-001-tdx-ingestion-poc/gitnexus/before.md @@ -0,0 +1,26 @@ +# GitNexus 开发前基线 + +- 功能编号:FEAT-DS-001 +- 记录时间:2026年8月14日 GMT+8 02:38:03 +- 分支:main +- 基线提交:a398bc418d39 + +## 工作区 + +```text +?? docs/features/FEAT-DS-001-tdx-ingestion-poc/ +``` + +## GitNexus 状态 + +```text +Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis +Indexed: 8/14/2026, 2:38:02 AM +Indexed commit: a398bc4 +Current commit: a398bc4 +Status: ✅ up-to-date +``` + +## 后续人工分析 + +在修改代码前,将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。 diff --git a/docs/features/FEAT-DS-001-tdx-ingestion-poc/gitnexus/impact-plan.md b/docs/features/FEAT-DS-001-tdx-ingestion-poc/gitnexus/impact-plan.md new file mode 100644 index 0000000..cb8baf3 --- /dev/null +++ b/docs/features/FEAT-DS-001-tdx-ingestion-poc/gitnexus/impact-plan.md @@ -0,0 +1,24 @@ +# GitNexus 开发前影响计划 + +- 功能编号:FEAT-DS-001 +- 总体风险:LOW(当前仅规划 Provider 边界和本地联调,不新增桌面应用或公网入口) + +## 直接与间接影响 + +- `gitnexus query --repo a-share-analysis "market data ingestion TDX adapter scheduler worker"` 未找到现成行情 Provider,相关现有流程集中在 Scheduler/Worker 启动和运行时配置。 +- `gitnexus query --repo a-share-analysis "configuration HTTP API health Redis MySQL RocketMQ"` 表明 API 当前只有健康检查流程,新增接收模块不会修改 `HealthService`。 +- 对名称 `health` 的 upstream impact 命中 Web API 目录且风险为 LOW、无上游消费者;由于名称存在歧义,结论仅作为辅助证据,不解释为对 API 全局无影响。 +- 当前不新增 `desktop/tdx-agent` 或 `MarketIngestModule`,不会修改现有 Web、API、Scheduler 或 Worker 符号。 +- 直接消费者是后续市场概览 Service;未来采集器、RocketMQ Worker、Redis 快照和 MySQL 历史属于延期功能,必须重新执行影响分析。 + +## 跨模块同步修改 + +- HTTP/OpenAPI:当前不新增公网握手或上报 DTO;Provider 内部契约不得泄漏到 Web。 +- Web API:主平台 Vue 不修改;不存在 Electron renderer。 +- 消息契约:本 PoC 不启用 RocketMQ,也不预留伪接收实现。 +- 数据库与 Redis:不新增 Schema,不读取生产库;PoC 接收仅做受控确认。 +- API:后续 Provider 如进入 API,再对 `ApiModule.register`、OpenAPI 和运行时配置执行影响分析。 +- Scheduler/Worker:本 PoC 不修改;后续正式排队功能另立功能档案和影响分析。 +- 配置部署:当前不新增 Windows 或公网配置,不改变主平台源码部署政策。 +- 测试:使用固定样本和 TDX 隧道冒烟;采集器打包和 Windows 无人值守测试延期。 +- 文档:记录延期原因、Provider 边界、安全、性能和未来重新立项条件。 diff --git a/docs/features/FEAT-DS-001-tdx-ingestion-poc/implementation-plan.md b/docs/features/FEAT-DS-001-tdx-ingestion-poc/implementation-plan.md new file mode 100644 index 0000000..d391ddb --- /dev/null +++ b/docs/features/FEAT-DS-001-tdx-ingestion-poc/implementation-plan.md @@ -0,0 +1,17 @@ +# 数据源接入架构与 TDX PoC 规划 + +## 当前计划(不实现采集器) + +1. 建立与运行时无关的 `DataProvider`、市场事件和数据新鲜度契约。 +2. 用固定样本 Provider 支撑市场概览的规则、AI、混合和对照分析开发。 +3. 通过已有 Tailscale SSH 隧道执行真实 TDX 只读请求,保存脱敏字段报告。 +4. 对 TDX 字段缺失、协议错误和陈旧数据做 Provider 层降级,不连接生产数据。 +5. 暂不新增 Windows 应用、Electron/Tauri、目标推送、补传队列、公网接收 API、RocketMQ 事件或数据库表。 +6. 待公网部署需求确定后,另立采集器功能档案,重新评估 Node、Python、Go、Rust 或系统服务方案。 + +## 后置功能必须覆盖 + +- 单次采集、多目标隔离推送。 +- production/development 独立地址、密钥、队列、状态和启停;两者地址均可修改。 +- production 未配置或停止为正常状态;停止时不删除队列、不转投 development。 +- HTTPS/HMAC、重放防护、握手身份、限流、补传、熔断、心跳、无人值守运行和系统更新。 diff --git a/docs/features/FEAT-DS-001-tdx-ingestion-poc/manifest.yaml b/docs/features/FEAT-DS-001-tdx-ingestion-poc/manifest.yaml new file mode 100644 index 0000000..63177c3 --- /dev/null +++ b/docs/features/FEAT-DS-001-tdx-ingestion-poc/manifest.yaml @@ -0,0 +1,12 @@ +id: FEAT-DS-001 +name: 数据源接入架构与 TDX PoC 规划 +slug: tdx-ingestion-poc +status: deferred +owner: project +created_at: 2026-08-14 +requirements: requirements.md +prd: prd.md +design: design.md +implementation_plan: implementation-plan.md +traceability_note: 当前只完成数据源边界和本地联调规划;Windows 采集器与公网接入延期到公网部署需求确认后单独立项。 +release: unreleased diff --git a/docs/features/FEAT-DS-001-tdx-ingestion-poc/prd.md b/docs/features/FEAT-DS-001-tdx-ingestion-poc/prd.md new file mode 100644 index 0000000..5ddf4ca --- /dev/null +++ b/docs/features/FEAT-DS-001-tdx-ingestion-poc/prd.md @@ -0,0 +1,37 @@ +# TDX 数据接入 PoC PRD + +## 用户问题 + +TDX 客户端运行在家中 Windows 虚拟机,并且接口只监听 Windows 本机 `127.0.0.1:17709`。公网平台和人在外面的开发设备都不能直接访问该端口,需要验证一套不暴露 TDX、可 7×24 小时运行的数据上报链路。 + +## 目标 + +在不提前引入公网部署和 Windows 常驻程序的前提下,先确定 TDX 数据源边界、标准化 Provider 契约和 Mac 本地联调方式。Windows 采集器、托盘 GUI、目标推送和公网接收入口延期,避免在生产部署形态尚未确定时锁定技术栈。 + +## 范围 + +- Mac 本地开发使用固定样本回放作为默认数据源,并保留通过 Tailscale SSH 隧道调用家中 Windows TDX 的人工联调方式。 +- 只定义与运行时无关的 `DataProvider`、标准化事件和数据新鲜度字段,不实现 Windows 常驻采集程序。 +- 记录未来公网模式的单次采集、多目标隔离推送、地址可变和目标启停原则,但不在本功能实现。 +- 只读验证指数、单股 K 线、快照、分时和板块接口中实际可用的字段。 +- 通过 Tailscale + SSH 隧道从外部 Mac 远程验证家中 Windows TDX;验证结果只用于 Provider 契约,不写入生产链路。 + +## 非目标 + +- 不在本功能中开发 Windows 采集应用、Electron/Tauri GUI、开发/生产接收 API、目标队列或公网推送。 +- 不在本功能中开发市场概览页面、AI 分析、正式 Worker 消费或生产接入。 +- 不开放 TDX `17709`、SSH 或 RDP 到公网。 +- 不写入自选、交易、账户或 TDX 状态。 +- 不把通达信数据授权问题解释为已解决;商业展示和再分发授权仍需单独确认。 + +## 成功指标 + +- 固定样本能够覆盖 Provider 的 K 线、快照、分时、板块和错误映射测试。 +- 通过 SSH 隧道完成至少一次真实 TDX 只读请求,并保存脱敏字段报告。 +- Provider 契约不依赖 Node、Electron、Python 或具体传输方式;未来采集器可独立替换。 + +## 风险 + +- TDX 客户端协议和返回字段可能变化;代理必须保留原始字段版本和来源标识。 +- 未来公网部署会增加采集节点、推送认证和再分发风险;延期期间不把这些风险误标为已解决。 +- 行情数据的展示、再分发和商业使用权利不由代码许可证自动授予。 diff --git a/docs/features/FEAT-DS-001-tdx-ingestion-poc/requirements.md b/docs/features/FEAT-DS-001-tdx-ingestion-poc/requirements.md new file mode 100644 index 0000000..f33ea80 --- /dev/null +++ b/docs/features/FEAT-DS-001-tdx-ingestion-poc/requirements.md @@ -0,0 +1,28 @@ +# 数据源接入架构与 TDX PoC 工程需求 + +## 当前阶段 Provider 边界 + +- Provider 暴露与采集器语言和传输方式无关的只读接口,统一返回 `source`、`capturedAt`、`tradeDate`、`schemaVersion`、`traceId` 和数据新鲜度。 +- 默认开发 Provider 使用仓库内固定样本,不连接生产数据源;真实 TDX Provider 只通过显式本地配置和 Tailscale SSH 隧道联调。 +- TDX Provider 限制回环地址、请求超时、响应体大小、股票列表和并发;不得把家庭地址或凭据写入代码。 +- Provider 原始响应映射为版本化内部载荷,上层分析不得依赖 TDX 原始字段名称。 + +## 当前运行与环境 + +- 平台仅在 Mac 本地源码运行,不要求安装 Windows 采集程序。 +- 固定样本支持离线、确定性和可重复测试;真实 TDX 联调依赖家中 Windows 在线,但不能成为日常测试门禁。 +- 当前不新增 Electron、Tauri、Python 服务、Go/Rust 程序、公网接收 API、文件补传队列或目标密钥。 +- SSH 私钥、TDX 地址、家庭网络信息和开发数据库凭据不得进入仓库、日志、样本或前端构建物。 + +## 延期的公网采集原则 + +- 采集器语言、GUI 壳和打包方式不预设为 Node/Electron,待公网部署需求确认后比较 Node、Python、Go、Rust 和系统服务方案。 +- 未来采集器只采集一次,production/development 使用独立地址、节点 ID、密钥、队列、上传器、心跳和启停状态。 +- production 与 development 地址均可修改且独立测试;任一目标故障或重配不得影响另一目标。 +- production 未配置或停止属于正常状态;停止时不删除已有队列、不转投 development。 +- 公网模式必须重新设计 HTTPS/HMAC、重放防护、身份握手、限流、补传、熔断、无人值守运行和操作系统密钥存储。 + +## 可观测性 + +- Provider 结果标记来源、采集时间、数据时间、陈旧状态和统一错误分类。 +- 真实联调报告必须脱敏,不保存完整家庭地址、SSH 信息、供应商凭据或未筛选的原始载荷。 diff --git a/docs/features/FEAT-DS-001-tdx-ingestion-poc/test-plan.md b/docs/features/FEAT-DS-001-tdx-ingestion-poc/test-plan.md new file mode 100644 index 0000000..b3b0a36 --- /dev/null +++ b/docs/features/FEAT-DS-001-tdx-ingestion-poc/test-plan.md @@ -0,0 +1,23 @@ +# 数据源接入架构与 TDX PoC 测试计划 + +## 当前阶段功能验证 + +- 固定样本验证 K 线、快照、分时和板块 Provider 载荷映射。 +- 通过 Tailscale SSH 隧道验证真实 TDX 只读请求,并保存脱敏字段报告。 +- 验证 Provider 在 TDX 错误、超时、空结果和陈旧数据下返回统一错误分类。 +- 验证市场概览只依赖内部模型,不直接读取 TDX 原始字段。 + +## 安全验证 + +- SSH 私钥、TDX 地址、家庭网络信息和开发数据库凭据不进入仓库、样本、日志或前端构建物。 +- TDX 只通过 SSH 隧道访问,`17709` 不开放公网。 +- 固定样本不包含供应商凭据和不必要的完整原始载荷。 + +## 性能验证 + +- 固定样本下测量 Provider 标准化耗时,确保回放不依赖外部网络。 +- 真实 TDX 请求记录响应耗时和字段完整性;不对未来采集器的上传、队列和 GUI 资源作结论。 + +## 不适用项与边界 + +不做 Electron/Tauri 窗口、托盘、安装包、生产数据库迁移、RocketMQ 收发和公网接收验证,原因是采集器与公网部署已延期。市场概览页面另按业务功能执行视觉验证。 diff --git a/docs/index.md b/docs/index.md index c74a2b7..ac92084 100644 --- a/docs/index.md +++ b/docs/index.md @@ -36,6 +36,7 @@ - [GOV-001:工程治理基线](features/GOV-001-engineering-governance/manifest.yaml) - [FEAT-MO-001:市场综合概览](features/FEAT-MO-001-market-overview/manifest.yaml) +- [FEAT-DS-001:数据源接入架构与 TDX PoC 规划(采集器延期)](features/FEAT-DS-001-tdx-ingestion-poc/manifest.yaml) - [GOV-002:PRD 与 Review 门禁](features/GOV-002-prd-review-gates/manifest.yaml) - [GOV-003:项目专用 Gitea 远程仓库](features/GOV-003-gitea-local-remote/manifest.yaml) - [GOV-004:提交后强制推送 Gitea](features/GOV-004-mandatory-gitea-push/manifest.yaml)