feat(FEAT-DS-001): 接入AKTools超短行情补充数据源
This commit is contained in:
@@ -40,6 +40,8 @@ tools/ 可重复执行的治理和开发工具
|
||||
- Redis保存最新快照、缓存、锁和限流状态。
|
||||
- Vue前端只读后端 API，不直接接触外部数据源和密钥。
|
||||
|
||||
市场概览的 AKTools 补充链路是按需读取的例外：Nest API 通过固定 Adapter 调用外部 AKTools HTTP 服务，前端不直连，且失败只影响超短模块。它不经过 Scheduler、Worker、RocketMQ、MySQL 或 Redis，也不改变后续正式采集链路的总体架构。
|
||||
|
||||
## 3. 前后端模块边界
|
||||
|
||||
后端以业务模块为一级目录，模块内部按实际职责建立 Controller、Service、DTO、Domain、Repository 和 Adapter。小模块不强制凑齐目录，禁止把全部 Controller/Service 堆入全局目录，也禁止无业务逻辑的透传层。领域规则只依赖项目端口，MySQL、Redis、RocketMQ、免费数据源和 AI Provider 由基础设施 Adapter 实现。
|
||||
|
||||
@@ -31,6 +31,16 @@ pnpm --filter @a-share-analysis/web dev
|
||||
|
||||
API 健康端点是 `http://127.0.0.1:3000/api/v1/health`，Web 是 `http://127.0.0.1:8888/`。Scheduler 与 Worker 在 GOV-009 中保持 `ROCKETMQ_ENABLED=false`；没有经过验证的 Node RocketMQ 客户端时，启用配置会直接失败，不使用内存队列伪降级。
|
||||
|
||||
## AKTools 补充数据源
|
||||
|
||||
AKTools/AKShare 作为开发机外部服务单独运行，默认地址为 `http://127.0.0.1:8080`。启动 API 前确认服务可访问；需要启用短线情绪模块时，在 API local 配置中设置 `AKTOOLS_ENABLED=true`，否则模块明确显示不可用，不影响 TDX 模块。Nest 只允许三个已验证接口，前端不直连 AKTools。项目不会管理该 Python 服务的安装、进程和数据。
|
||||
|
||||
```bash
|
||||
curl --fail 'http://127.0.0.1:8080/api/public/stock_zt_pool_em?date=20260824'
|
||||
```
|
||||
|
||||
生产环境不能直接复用本机 AKTools 配置；启用前必须提供受控内网地址、认证/访问控制、上游授权和稳定性评估，并扩展服务端白名单校验。
|
||||
|
||||
## 日常验证与停止
|
||||
|
||||
```bash
|
||||
|
||||
@@ -43,6 +43,10 @@ curl --fail http://127.0.0.1/
|
||||
|
||||
当前工程尚无业务表迁移；后续新增迁移后必须在切换 `current` 前单独执行并记录结果。生产环境禁止 `synchronize: true`，开发流程也禁止用生产数据库做 Schema 基线或连接测试。
|
||||
|
||||
## AKTools 生产边界
|
||||
|
||||
AKTools 不随本项目发布，也不由 systemd 单元管理。生产 API 默认关闭 `AKTOOLS_ENABLED`；只有在 AKTools 以受控内网服务部署、完成访问控制、授权和稳定性评估后，才可在 API 的生产环境文件中启用。生产配置不得把 AKTools 地址暴露给浏览器，且必须同步修改服务端白名单和健康检查方案；未完成这些前置条件时保持短线模块 `unavailable`。
|
||||
|
||||
## 检查与回退
|
||||
|
||||
使用 `systemctl status`、`journalctl -u`、HTTP 健康端点和 Nginx 同源访问结果确认发布。任一验证失败时，把 `/opt/a-share-analysis/current` 原子切回上一完整发布目录，重启三个 systemd 服务并重复健康检查。
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user