docs(FEAT-DS-001): 设计 AKTools 超短补充数据源

2026-08-24 20:43:14 +08:00
parent 0d0d1eea45
commit 81c48af8cc
20 changed files with 514 additions and 0 deletions
@@ -0,0 +1,39 @@
+# AKTools 超短行情补充数据源设计
+
+## 方案
+
+AKTools 保持为独立的内网 HTTP 服务，Nest 在市场概览模块内增加 AKTools Adapter。Adapter 负责请求、超时、响应大小和错误边界；Mapper 负责把 AKTools 中文字段转换成稳定领域 DTO；Service 并行调用三个接口并生成规则结论。
+
+```text
+Vue → Nest Controller → ShortTerm Service → AKTools Client → 127.0.0.1:8080 → AKShare
+                                    └→ TDX 既有市场概览链路保持独立
+```
+
+## 接口
+
+```text
+GET /api/v1/market-overview/short-term/emotion
+GET /api/v1/market-overview/short-term/conclusion
+```
+
+两个接口共享一次请求内的 `snapshotId`，但不要求跨请求持久化。`emotion` 返回结构化指标，`conclusion` 返回规则结论和证据引用。
+
+## 安全策略与评估
+
+- `AKTOOLS_BASE_URL` 只能是配置值，禁止来自请求参数；启动时仅允许回环地址或明确内网白名单。
+- 客户端只使用 GET 和固定接口名，不把任意函数名暴露成代理能力。
+- 超时、响应体大小和 JSON 结构均在 Adapter 层限制；异常只返回脱敏 warning。
+- AKTools 不直接对外开放；若未来扩展到多机内网，必须增加访问控制和反向代理认证。
+- 不保存 AKShare 原始载荷、不记录真实内网地址、不提交凭据。
+
+## 性能目标与评估
+
+三个上游请求使用 `Promise.allSettled` 并行执行，单请求超时 10 秒，短线接口 P95 目标小于 12 秒。由于 V1 不持久化、不缓存，性能风险主要是 AKShare 上游限流和网络延迟；通过超时、部分结果和独立降级控制影响面。
+
+## 错误处理与回退
+
+AKTools 完全不可用时短线响应为 `unavailable`，TDX 响应不受影响。单个接口失败时返回 `partial` 并保留其他有效模块。回退只关闭 AKTools 功能开关和相关路由，不删除 TDX 代码。
+
+## 架构同步
+
+需要同步 OpenAPI DTO、Web API 类型、开发/生产环境模板、API 健康检查说明、测试和功能档案；不修改消息、数据库、Redis、Scheduler、Worker。
@@ -0,0 +1,33 @@
+# AKTools 超短行情补充数据源开发总结
+
+- 功能编号：FEAT-DS-001
+- 状态：design_approved
+- 发布状态：unreleased
+
+## 原始开发需求
+
+在内网环境使用已经运行的 AKTools，补充 TDX 不提供的超短行情数据。
+
+## 需求与范围变化
+
+V1 采用 AKTools 外部服务直连，不新增 Python 服务和 Docker；暂不接入全市场现货接口，因为该接口本地验证返回 HTTP 500。
+
+## 实际完成需求
+
+开发完成后记录实际完成的客户端、接口、页面、配置和验证结果。
+
+## 修复缺陷
+
+开发完成后记录本功能发现并修复的缺陷；当前设计阶段没有代码缺陷修复。
+
+## 未完成与延期项
+
+炸板率严格口径、资金净流入、盘中新闻、历史快照和生产授权评估不属于 V1。
+
+## 关键提交
+
+开发完成并推送后记录中文提交和远端 SHA。
+
+## 验证证据
+
+开发完成后记录 Schema、GitNexus、单元测试、契约测试、E2E、构建、视觉验证、安全和性能证据。
@@ -0,0 +1,6 @@
+# GitNexus 开发后基线
+
+- 功能编号：FEAT-DS-001
+- 状态：待开发完成后刷新
+
+开发完成后记录索引提交、节点、关系、执行流、状态和变更检测结果。
@@ -0,0 +1,26 @@
+# GitNexus 开发前基线
+
+- 功能编号：FEAT-DS-001
+- 记录时间：2026年8月24日 GMT+8 20:38:07
+- 分支：main
+- 基线提交：0d0d1eea4530
+
+## 工作区
+
+```text
+?? "SRMS3.6.0\345\270\270\350\247\201\351\227\256\351\242\230\346\265\213\350\257\204\351\242\230.2csv"
+```
+
+## GitNexus 状态
+
+```text
+Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
+Indexed: 8/24/2026, 8:38:06 PM
+Indexed commit: 0d0d1ee
+Current commit: 0d0d1ee
+Status: ✅ up-to-date
+```
+
+## 后续人工分析
+
+在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。
@@ -0,0 +1,3 @@
+# GitNexus 前后对比
+
+开发前基线已记录在 `before.md`。开发后需要对比新增 AKTools Adapter、短线 Service、Controller、Web API、配置和文档是否与计划一致，并说明任何额外影响。
@@ -0,0 +1,6 @@
+# GitNexus 变更检测
+
+- 功能编号：FEAT-DS-001
+- 当前阶段：开发前
+
+提交前必须使用 `gitnexus_detect_changes({scope: "staged"})`，确认只影响 AKTools 适配、市场概览短线接口、前端状态、配置和文档；若出现 TDX、数据库或消息执行流，必须暂停并重新评估。
@@ -0,0 +1,27 @@
+# GitNexus 开发前影响计划
+
+- 功能编号：FEAT-DS-001
+- 总体风险：LOW
+
+## 直接与间接影响
+
+GitNexus query 以“市场概览 超短行情总结 指数 板块 宽度 资金趋势”为目标执行，未发现现有超短执行流；结果主要定位到市场概览文档、测试和 `MarketOverviewService`。
+
+`MarketOverviewService` context：直接消费者为市场概览 Controller、Module、OpenAPI 导出和测试；现有方法为指数、摘要、宽度、板块和成交额趋势，不包含 AKTools 数据。
+
+`MarketOverviewService` upstream impact：影响 5 个关联对象，直接关联 3 个，风险 LOW，受影响执行流 0，受影响模块 0。结论是新增 AKTools 适配器和独立短线接口，不改写现有 TDX 方法，避免扩大现有概览方法的调用面。
+
+## 跨模块同步修改
+
+| 范围 | 判断 | 处置 |
+|---|---|---|
+| HTTP/OpenAPI | 需要同步 | 新增短线情绪和短线结论 DTO、Controller 路由并重新生成契约。 |
+| Web API | 需要同步 | 新增 `web/src/api/market-overview/index.ts` 的业务请求和短线页面状态。 |
+| 消息契约 | 不修改 | V1 为按需读取，不发布行情事件。 |
+| 数据库 | 不修改 | 不持久化 AKTools 响应，不读取生产库。 |
+| Redis | 不修改 | 暂不缓存，避免在数据口径未稳定时引入一致性问题。 |
+| API 进程 | 需要同步 | Nest API 增加固定内网 AKTools 客户端和超时降级。 |
+| Scheduler/Worker | 不修改 | V1 无采集任务、重试队列或历史快照任务。 |
+| 配置部署 | 需要同步 | 增加可选 `AKTOOLS_ENABLED`、`AKTOOLS_BASE_URL`、`AKTOOLS_TIMEOUT_MS` 模板和文档。 |
+| 测试 | 需要同步 | 增加客户端、映射、Service、OpenAPI、Web 状态和 E2E 覆盖。 |
+| 文档 | 需要同步 | 更新架构、开发环境、功能档案和 AKTools 内网运行说明。 |
@@ -0,0 +1,22 @@
+# AKTools 超短行情补充数据源实施计划
+
+## 任务清单
+
+1. 完成功能档案、配置契约和 GitNexus 影响记录。
+2. 为 AKTools 客户端、字段类型和映射器编写失败测试。
+3. 实现固定接口、超时、响应校验和中文字段映射。
+4. 实现短线情绪 Service、规则结论、DTO 和 Controller。
+5. 更新 OpenAPI 生成契约、前端 API、页面模块和异常状态。
+6. 补充开发/生产模板及内网 AKTools 运维说明。
+7. 执行单元、契约、E2E、构建、视觉验证、Review 和治理完成门禁。
+
+## 文件边界
+
+- 新增 `server/apps/api/src/market-overview/aktools/` 客户端、类型和映射。
+- 新增短线业务 DTO、Service 和 Controller；不改动既有 TDX Mapper。
+- 新增 `web/src/api/market-overview/short-term.ts` 或保持业务 API 目录内的等价稳定文件，页面只消费公开 DTO。
+- 修改环境模板、架构文档、开发文档和 OpenAPI 生成产物。
+
+## 实施顺序
+
+先测试字段校验和映射，再实现客户端；先实现后端契约，再实现前端状态；每个阶段执行对应定向测试，最后执行完整门禁。
@@ -0,0 +1,8 @@
+featureId: FEAT-DS-001
+slug: aktools-supplement
+name: AKTools 超短行情补充数据源
+status: design_approved
+release: unreleased
+source: aktools
+scope: internal_lan_only
+createdAt: 2026-08-24
@@ -0,0 +1,69 @@
+# AKTools 超短行情补充数据源 PRD
+
+- 功能编号：FEAT-DS-001
+- PRD 版本：0.1
+- 状态：design_approved
+- 日期：2026-08-24
+
+## 背景与问题
+
+TDX 已提供指数、市场宽度、板块和成交额，但不能覆盖涨停池、炸板池、昨日涨停表现等超短情绪指标。AKTools 已在本机内网环境运行，并验证了相关 HTTP 接口。
+
+## 目标用户与场景
+
+个人用户在盘中或收盘后查看超短情绪，不进行交易下单。V1 仅支持本机或受控内网访问，AKTools 只作为 Nest API 的内部补充数据源。
+
+## 产品目标
+
+- 在市场概览中提供结构化超短情绪数据。
+- 显示涨停数量、最高连板、连板梯队、炸板数量和昨日涨停表现。
+- 所有结论都能追溯到 AKShare 数据字段、交易日期和数据状态。
+- AKTools 不可用时不影响 TDX 核心市场概览。
+
+## 非目标
+
+- 不实现交易建议、买卖信号、目标价或仓位建议。
+- 不直接暴露 AKTools 的通用接口给前端或公网。
+- 不在 V1 计算未经确认口径的炸板率、资金净流入或新闻情绪评分。
+- 不启用 MySQL、Redis、RocketMQ 或历史快照存储。
+
+## 功能需求
+
+| 编号 | 优先级 | 需求 | 可观察结果 |
+|---|---|---|---|
+| FR-001 | P0 | 读取涨停池 | 展示涨停数量、最高连板和连板梯队。 |
+| FR-002 | P0 | 读取炸板池 | 展示炸板数量和可用的炸板次数摘要。 |
+| FR-003 | P0 | 读取昨日涨停池 | 展示今日平均涨跌幅及上涨、下跌、持平数量。 |
+| FR-004 | P0 | 生成规则结论 | 结论必须携带依据、交易日期和状态。 |
+| FR-005 | P0 | 独立降级 | AKTools 超时或异常时，短线模块显示 unavailable，TDX 模块继续可用。 |
+| FR-006 | P1 | 内网边界 | AKTools 地址只来自服务端固定配置，默认回环地址。 |
+
+## 数据与口径
+
+V1 调用 `stock_zt_pool_em`、`stock_zt_pool_zbgc_em`、`stock_zt_pool_previous_em`。AKTools 返回的中文字段只在 Adapter 内解析，领域 DTO 使用稳定英文属性。
+
+- 涨停数量：涨停池有效记录数。
+- 最高连板：有效 `连板数` 的最大值。
+- 连板梯队：按 `连板数` 分组计数。
+- 炸板数量：炸板池有效记录数；不直接推导炸板率。
+- 昨日涨停表现：昨日涨停池有效 `涨跌幅` 的算术平均，以及正、负、零数量。
+- 封板资金：仅作为原始统计摘要展示，单位转换为亿元并标明来源，不解释为主力净流入。
+
+## 状态与异常
+
+响应统一使用 `fresh`、`delayed`、`partial`、`unavailable`。交易日不等于上海当前日期时标记 `delayed`；字段缺失或部分接口失败时标记 `partial`；连接失败、超时、HTTP 5xx 或响应格式错误时标记 `unavailable`。
+
+## 安全与合规
+
+AKTools 仅绑定 `127.0.0.1:8080`。Nest 不接受客户端传入上游 URL，不记录原始载荷，不向前端透传上游异常。AKShare 及其上游数据的授权和再分发边界在正式对外部署前另行评估。
+
+## 性能目标
+
+三个 AKTools 请求并行执行，单请求超时目标 10 秒，短线接口正常响应目标 P95 小于 12 秒。V1 不引入缓存，避免陈旧数据和缓存击穿复杂度。
+
+## 验收标准
+
+- 有效交易日数据可生成短线情绪 DTO 和规则结论。
+- 任一 AKTools 接口失败不会导致 TDX 市场概览接口失败。
+- OpenAPI、前端 API 和页面状态与后端 DTO 一致。
+- API 地址固定为本机内网配置，仓库不包含真实凭据和机器地址。
@@ -0,0 +1,13 @@
+# 测试结果
+
+## 当前状态
+
+设计阶段尚未执行本功能代码测试；已完成 AKTools 本机 HTTP 冒烟，涨停池、炸板池和昨日涨停池接口返回 HTTP 200，历史行情接口返回 HTTP 200。
+
+## 安全验证
+
+设计阶段已确定回环绑定、固定接口、超时和脱敏边界；代码实现后补充自动化证据。
+
+## 性能验证
+
+设计阶段已确定并行请求和 10 秒单请求超时目标；代码实现后补充耗时证据，不将单次本机结果视为容量结论。
@@ -0,0 +1,13 @@
+# 视觉验证
+
+## 当前状态
+
+设计阶段尚未修改页面。实现后必须验证桌面和窄屏下短线情绪模块的加载、有效、部分和不可用状态。
+
+## 安全验证
+
+视觉验证不得展示凭据、真实内网地址或 AKTools 原始错误载荷。
+
+## 性能验证
+
+记录页面首次可见状态和短线模块完成状态，确认 AKTools 延迟不会阻塞 TDX 核心模块。
@@ -0,0 +1,5 @@
+# 发布说明
+
+## 未发布
+
+FEAT-DS-001 当前为未发布功能。计划接入 AKTools 内网补充数据源，提供超短情绪指标和规则结论；不改变 TDX 核心市场概览。
@@ -0,0 +1,24 @@
+# AKTools 超短行情补充数据源需求
+
+## 原始需求
+
+使用 AKTools 提供的 AKShare HTTP 接口，补充 TDX 没有的超短行情数据；当前只考虑内网环境。
+
+## 实际范围
+
+- Nest 服务端调用本机 AKTools，不让 Vue 直连 AKTools。
+- 首批接入涨停池、炸板池、昨日涨停池。
+- 新增短线情绪和短线结论业务接口。
+- 保留 TDX 核心市场概览链路不变。
+
+## 数据口径
+
+所有数量只统计通过字段校验的记录；缺失数值不折算为零。结论只能使用本功能列出的确定性规则，不能把 AKShare 原始字段解释为交易建议。
+
+## 依赖边界
+
+AKTools 作为项目外部服务运行，默认地址为 `http://127.0.0.1:8080`。V1 不新增 Python 代码、不新增 Docker、不启用数据库、缓存和消息队列。
+
+## 范围变化
+
+已确认不接入 `stock_zh_a_spot_em` 作为核心接口，因为当前本地验证返回 HTTP 500；该接口不影响本功能其余目标接口。
@@ -0,0 +1,37 @@
+# 代码 Review
+
+## 审查范围
+
+设计阶段审查目标为 AKTools Client、Mapper、短线 Service、DTO、Controller、Web API、配置和测试。
+
+## PRD 与设计符合性
+
+实现后检查只接入三个已验证接口，保持 TDX 独立，且不把原始 AKTools 字段直接暴露给前端。
+
+## 发现
+
+当前尚未进入代码 Review；实现完成后记录按严重级别排序的问题和处置。
+
+## 测试缺口
+
+需要覆盖上游 5xx、超时、部分接口失败、字段漂移、日期延迟和窄屏状态。
+
+## 安全与残余风险
+
+检查固定内网地址、请求参数边界、错误脱敏、日志载荷和前端构建产物；AKShare 授权和上游稳定性是残余风险。
+
+## 性能与资源影响
+
+检查并行请求、超时、响应大小和不引入缓存的边界；不得把本地单次测试宣传为生产容量证明。
+
+## GitNexus 与同步修改
+
+实现后核对变更检测结果只覆盖计划中的短线链路和文档。
+
+## 修复与复审
+
+发现问题后记录修复提交和复审证据。
+
+## 最终结论
+
+当前阶段：pending
@@ -0,0 +1,21 @@
+# 开发规范符合性 Review
+
+## 检查结果
+
+设计阶段已检查功能档案、Schema/GitNexus 前置流程、TDX 与 AKTools 边界及源码部署约束；代码实现后进行逐项复核。
+
+## 不符合项与处置
+
+当前没有代码不符合项；实现阶段若发现问题，必须在发布前修复并记录。
+
+## 安全、性能与架构检查
+
+必须确认 AKTools 仅作为外部内网 Adapter，未新增 Docker、生产数据库连接、消息链路或前端直连；同时检查超时、响应上限和降级。
+
+## GitNexus 与开发总结检查
+
+必须确认开发前后索引、影响计划、变更检测、开发总结、测试结果和 Review 记录完整。
+
+## 最终结论
+
+当前阶段：pending
@@ -0,0 +1,16 @@
+# 回退说明
+
+## 触发条件
+
+出现 TDX 核心行情回归、AKTools 请求阻塞 API、上游原始字段泄漏、OpenAPI 契约不一致或短线模块遮挡核心概览时回退。
+
+## 回退步骤
+
+1. 关闭 `AKTOOLS_ENABLED` 或回退到上一个完整发布目录。
+2. 重启 API 并确认 TDX 概览接口、Web 健康检查和构建产物正常。
+3. 保留 AKTools 外部服务，不删除其运行环境和数据缓存。
+4. 记录回退原因、提交 SHA、验证结果和后续修复计划。
+
+## 数据与外部服务
+
+本功能不写 MySQL、Redis 或 RocketMQ，不需要数据回退；AKTools 是独立外部服务，应用回退不负责停止或删除它。
@@ -0,0 +1,30 @@
+# AKTools 超短行情补充数据源测试计划
+
+## 功能验证
+
+- 用固定响应夹具验证涨停数量、最高连板和梯队分布。
+- 验证炸板池和昨日涨停池字段缺失、非法数字、空数组的处理。
+- 验证三个请求并行且单个失败返回 partial。
+- 验证全部失败返回 unavailable，TDX 既有接口仍能独立响应。
+- 验证 OpenAPI DTO、Web API 类型和页面状态一致。
+
+## 安全验证
+
+- 验证客户端拒绝请求参数注入的上游 URL。
+- 验证配置不允许生产地址和公网任意地址。
+- 验证超时、过大响应、非 JSON 响应和上游错误均脱敏。
+- 验证前端构建产物不包含 AKTools 凭据或内部地址。
+
+## 性能验证
+
+- 验证三个请求使用并行调度而非串行等待。
+- 使用受控延迟夹具验证单请求超时和整体响应上限。
+- 记录定向请求耗时，不把本地单次结果当作生产容量证明。
+
+## 视觉验证
+
+验证桌面和窄屏下短线情绪模块的加载、部分、不可用、空数据状态，确保警告和交易日期不遮挡指标。
+
+## 残余风险
+
+AKShare 上游限流、字段变更、数据授权和长期稳定性需要在后续联调与生产评估中持续验证。