feat(FEAT-DS-001): 接入AKTools超短行情补充数据源

2026-08-24 21:40:22 +08:00
parent 81c48af8cc
commit 6e8a05114e
42 changed files with 1449 additions and 36 deletions
@@ -1,7 +1,7 @@
 # AKTools 超短行情补充数据源开发总结

 - 功能编号：FEAT-DS-001
- 状态：design_approved
+- 状态：in_review
 - 发布状态：unreleased

 ## 原始开发需求
@@ -14,11 +14,11 @@ V1 采用 AKTools 外部服务直连，不新增 Python 服务和 Docker；暂

 ## 实际完成需求

-开发完成后记录实际完成的客户端、接口、页面、配置和验证结果。
+已完成 AKTools 配置校验、固定接口 Client、中文字段 Mapper、短线情绪与规则结论 DTO/Service/Controller、OpenAPI 生成契约、Vue Axios API、Composable 状态、短线情绪面板和开发/生产环境模板。页面通过独立状态展示正常、部分、延迟、不可用和空数据，不阻塞 TDX 模块。

 ## 修复缺陷

-开发完成后记录本功能发现并修复的缺陷；当前设计阶段没有代码缺陷修复。
+修复了短线情绪面板缺失导致的前端测试导入失败，并补齐页面未消费短线结论响应的问题；同时修复页面接线遗漏造成的 `shortTermConclusion` 未定义告警。未发现 TDX 回归。

 ## 未完成与延期项

@@ -26,8 +26,8 @@ V1 采用 AKTools 外部服务直连，不新增 Python 服务和 Docker；暂

 ## 关键提交

-开发完成并推送后记录中文提交和远端 SHA。
+实现提交与文档收口提交均使用带 `FEAT-DS-001` 的中文 Conventional Commit；最终 SHA 与远端推送结果在发布前补录。

 ## 验证证据

-开发完成后记录 Schema、GitNexus、单元测试、契约测试、E2E、构建、视觉验证、安全和性能证据。
+Schema 基线与校验通过（`v0.0.10 captured_empty`）；开发前 GitNexus 风险 LOW，页面改动前对 `useMarketOverview` 影响分析为 LOW；后端 15 个测试文件 79 个测试通过，前端 8 个测试文件 23 个测试通过，Web typecheck 通过，浏览器桌面/390×844 视觉检查通过且 `scrollWidth=innerWidth`。安全边界包括回环地址白名单、固定接口、超时、响应体上限、JSON 校验和错误脱敏；三个上游请求并行，单请求超时 10 秒，当前性能证据为本机定向测试，不代表生产容量。
@@ -1,3 +1,3 @@
 # GitNexus 前后对比

-开发前基线已记录在 `before.md`。开发后需要对比新增 AKTools Adapter、短线 Service、Controller、Web API、配置和文档是否与计划一致，并说明任何额外影响。
+开发前基线已记录在 `before.md`。开发后 GitNexus 重新索引确认新增 AKTools Adapter、短线 Service、Controller、Web API、配置、页面和文档均落在计划范围；现有 TDX 市场概览执行流未被改写。`useMarketOverview` 的直接消费者为页面和测试，影响风险 LOW；未发现数据库、Redis、RocketMQ、Scheduler 或 Worker 新执行流。
@@ -2,19 +2,19 @@

 ## 任务清单

-1. 完成功能档案、配置契约和 GitNexus 影响记录。
-2. 为 AKTools 客户端、字段类型和映射器编写失败测试。
-3. 实现固定接口、超时、响应校验和中文字段映射。
-4. 实现短线情绪 Service、规则结论、DTO 和 Controller。
-5. 更新 OpenAPI 生成契约、前端 API、页面模块和异常状态。
-6. 补充开发/生产模板及内网 AKTools 运维说明。
-7. 执行单元、契约、E2E、构建、视觉验证、Review 和治理完成门禁。
+1. [x] 完成功能档案、配置契约和 GitNexus 影响记录。
+2. [x] 为 AKTools 客户端、字段类型和映射器编写失败测试。
+3. [x] 实现固定接口、超时、响应校验和中文字段映射。
+4. [x] 实现短线情绪 Service、规则结论、DTO 和 Controller。
+5. [x] 更新 OpenAPI 生成契约、前端 API、页面模块和异常状态。
+6. [x] 补充开发/生产模板及内网 AKTools 运维说明。
+7. [ ] 执行完整 `pnpm verify`、治理完成门禁和远程推送（收尾阶段）。

 ## 文件边界

 - 新增 `server/apps/api/src/market-overview/aktools/` 客户端、类型和映射。
 - 新增短线业务 DTO、Service 和 Controller；不改动既有 TDX Mapper。
- 新增 `web/src/api/market-overview/short-term.ts` 或保持业务 API 目录内的等价稳定文件，页面只消费公开 DTO。
+- 修改 `web/src/api/market-overview/index.ts`，页面只消费公开 DTO。
 - 修改环境模板、架构文档、开发文档和 OpenAPI 生成产物。

 ## 实施顺序
@@ -1,7 +1,7 @@
 featureId: FEAT-DS-001
 slug: aktools-supplement
 name: AKTools 超短行情补充数据源
-status: design_approved
+status: in_review
 release: unreleased
 source: aktools
 scope: internal_lan_only
@@ -2,12 +2,12 @@

 ## 当前状态

-设计阶段尚未执行本功能代码测试；已完成 AKTools 本机 HTTP 冒烟，涨停池、炸板池和昨日涨停池接口返回 HTTP 200，历史行情接口返回 HTTP 200。
+已完成代码验证：后端 Vitest 15 个测试文件、79 个测试通过，包含 AKTools Client/Mapper、短线 Service、HTTP E2E 和 OpenAPI；前端 Vitest 8 个测试文件、23 个测试通过，包含短线面板、Composable 和 API；Web typecheck 通过。AKTools 本机涨停池、炸板池和昨日涨停池冒烟均返回 HTTP 200；`stock_zh_a_spot_em` 返回 HTTP 500，未纳入 V1。

 ## 安全验证

-设计阶段已确定回环绑定、固定接口、超时和脱敏边界；代码实现后补充自动化证据。
+配置测试验证仅允许 `127.0.0.1:8080`，Client 测试覆盖禁用、超时、HTTP/协议错误、响应大小上限和脱敏异常；未向 Web 暴露 AKTools 地址或原始字段。

 ## 性能验证

-设计阶段已确定并行请求和 10 秒单请求超时目标；代码实现后补充耗时证据，不将单次本机结果视为容量结论。
+Service 测试验证三个请求使用 `Promise.allSettled` 并行、单个失败返回 `partial`、全部失败返回 `unavailable`。单请求超时配置为 10 秒；当前仅有本机测试证据，不将其视为生产容量结论。
@@ -2,7 +2,7 @@

 ## 当前状态

-设计阶段尚未修改页面。实现后必须验证桌面和窄屏下短线情绪模块的加载、有效、部分和不可用状态。
+已在 `http://127.0.0.1:8888/` 完成桌面默认视口和 `390×844` 窄屏检查。短线面板在 DOM 中可见，TDX 不可用时仍展示明确的 AKShare 空状态；窄屏 `document.documentElement.scrollWidth` 与 `window.innerWidth` 均为 390，无横向溢出。组件测试覆盖有效数据和 unavailable 警告，部分/延迟文案沿用既有面板样式并通过类型检查。

 ## 安全验证

@@ -10,4 +10,4 @@

 ## 性能验证

-记录页面首次可见状态和短线模块完成状态，确认 AKTools 延迟不会阻塞 TDX 核心模块。
+首次可见状态先展示 TDX 和 AKShare 各自占位，不互相阻塞；短线 API 失败只改变短线模块状态。视觉检查未展示凭据、真实内网地址或原始异常载荷。
@@ -2,4 +2,4 @@

 ## 未发布

-FEAT-DS-001 当前为未发布功能。计划接入 AKTools 内网补充数据源，提供超短情绪指标和规则结论；不改变 TDX 核心市场概览。
+FEAT-DS-001 当前为未发布功能。已接入 AKTools 内网补充数据源，提供超短情绪指标和规则结论；不改变 TDX 核心市场概览。生产默认关闭，待授权、访问控制和稳定性评估后再决定启用。
@@ -10,19 +10,19 @@

 ## 发现

-当前尚未进入代码 Review；实现完成后记录按严重级别排序的问题和处置。
+已完成实现 Review：未发现阻断项。Client 只允许三个固定 AKTools 路径，Service 用 `Promise.allSettled` 做模块级降级，DTO 不透传中文原始字段；Web 只通过 Axios API 文件访问 Nest。发现页面接线遗漏 `shortTermConclusion` 未解构，已在测试失败后修复。

 ## 测试缺口

-需要覆盖上游 5xx、超时、部分接口失败、字段漂移、日期延迟和窄屏状态。
+上游 5xx、超时、部分接口失败、字段非法、响应大小、不可用状态和窄屏布局已有定向覆盖；交易日期延迟口径和 AKShare 字段漂移仍需后续真实交易日联调。

 ## 安全与残余风险

-检查固定内网地址、请求参数边界、错误脱敏、日志载荷和前端构建产物；AKShare 授权和上游稳定性是残余风险。
+固定地址白名单、日期参数校验、固定接口、超时、响应体上限、JSON 结构校验和错误脱敏均已检查；未发现凭据或原始载荷进入前端。残余风险为 AKShare 授权、上游限流/字段变更和生产多机访问控制，故生产默认关闭。

 ## 性能与资源影响

-检查并行请求、超时、响应大小和不引入缓存的边界；不得把本地单次测试宣传为生产容量证明。
+三个请求并行，10 秒超时，2 MiB 响应上限，不引入缓存和消息链路；测试证据仅证明行为和边界，不构成生产容量证明。

 ## GitNexus 与同步修改

@@ -34,4 +34,4 @@

 ## 最终结论

-当前阶段：pending
+最终结论：passed
@@ -6,16 +6,16 @@

 ## 不符合项与处置

-当前没有代码不符合项；实现阶段若发现问题，必须在发布前修复并记录。
+逐项检查通过：功能档案、中文注释、OpenAPI 生成契约、Axios API 边界、固定数据源 Adapter、模块级降级、环境模板和未提交凭据约束均符合规范。实现期间发现的页面接线遗漏已修复并由前端全量测试复验。

 ## 安全、性能与架构检查

-必须确认 AKTools 仅作为外部内网 Adapter，未新增 Docker、生产数据库连接、消息链路或前端直连；同时检查超时、响应上限和降级。
+确认 AKTools 仅作为外部内网 Adapter，未新增 Docker、Python 服务、生产数据库连接、Redis/RocketMQ 消息链路或前端直连；超时、响应上限、并行请求和降级均有实现与测试证据。生产启用的授权、访问控制和容量评估仍是明确前置条件。

 ## GitNexus 与开发总结检查

-必须确认开发前后索引、影响计划、变更检测、开发总结、测试结果和 Review 记录完整。
+开发前后 GitNexus 报告、影响计划、变更检测、开发总结、测试结果、视觉 QA、Review 和回退说明均已补齐；`governance:finish` 及最终提交前再次执行变更检测。

 ## 最终结论

-当前阶段：pending
+最终结论：passed