From 81c48af8cceee6f511cf04ffc6bd6e87239a9941 Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Mon, 24 Aug 2026 20:43:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(FEAT-DS-001):=20=E8=AE=BE=E8=AE=A1=20AKToo?= =?UTF-8?q?ls=20=E8=B6=85=E7=9F=AD=E8=A1=A5=E5=85=85=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E6=BA=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../FEAT-DS-001-aktools-supplement/design.md | 39 +++++++++ .../development-summary.md | 33 +++++++ .../gitnexus/after.md | 6 ++ .../gitnexus/before.md | 26 ++++++ .../gitnexus/comparison.md | 3 + .../gitnexus/detected-changes.md | 6 ++ .../gitnexus/impact-plan.md | 27 ++++++ .../implementation-plan.md | 22 +++++ .../manifest.yaml | 8 ++ .../FEAT-DS-001-aktools-supplement/prd.md | 69 +++++++++++++++ .../qa/test-results.md | 13 +++ .../qa/visual-qa.md | 13 +++ .../release-notes.md | 5 ++ .../requirements.md | 24 ++++++ .../review/code-review.md | 37 ++++++++ .../review/standards-review.md | 21 +++++ .../rollback.md | 16 ++++ .../test-plan.md | 30 +++++++ .../plans/2026-08-24-aktools-supplement.md | 85 +++++++++++++++++++ .../2026-08-24-aktools-supplement-design.md | 31 +++++++ 20 files changed, 514 insertions(+) create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/design.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/development-summary.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/gitnexus/after.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/gitnexus/before.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/gitnexus/comparison.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/gitnexus/detected-changes.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/gitnexus/impact-plan.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/implementation-plan.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/manifest.yaml create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/prd.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/qa/test-results.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/qa/visual-qa.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/release-notes.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/requirements.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/review/code-review.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/review/standards-review.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/rollback.md create mode 100644 docs/features/FEAT-DS-001-aktools-supplement/test-plan.md create mode 100644 docs/superpowers/plans/2026-08-24-aktools-supplement.md create mode 100644 docs/superpowers/specs/2026-08-24-aktools-supplement-design.md diff --git a/docs/features/FEAT-DS-001-aktools-supplement/design.md b/docs/features/FEAT-DS-001-aktools-supplement/design.md new file mode 100644 index 0000000..4ec65d0 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/design.md @@ -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。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/development-summary.md b/docs/features/FEAT-DS-001-aktools-supplement/development-summary.md new file mode 100644 index 0000000..0e8cb40 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/development-summary.md @@ -0,0 +1,33 @@ +# AKTools 超短行情补充数据源开发总结 + +- 功能编号：FEAT-DS-001 +- 状态：design_approved +- 发布状态：unreleased + +## 原始开发需求 + +在内网环境使用已经运行的 AKTools，补充 TDX 不提供的超短行情数据。 + +## 需求与范围变化 + +V1 采用 AKTools 外部服务直连，不新增 Python 服务和 Docker；暂不接入全市场现货接口，因为该接口本地验证返回 HTTP 500。 + +## 实际完成需求 + +开发完成后记录实际完成的客户端、接口、页面、配置和验证结果。 + +## 修复缺陷 + +开发完成后记录本功能发现并修复的缺陷；当前设计阶段没有代码缺陷修复。 + +## 未完成与延期项 + +炸板率严格口径、资金净流入、盘中新闻、历史快照和生产授权评估不属于 V1。 + +## 关键提交 + +开发完成并推送后记录中文提交和远端 SHA。 + +## 验证证据 + +开发完成后记录 Schema、GitNexus、单元测试、契约测试、E2E、构建、视觉验证、安全和性能证据。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/after.md b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/after.md new file mode 100644 index 0000000..7e10cca --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/after.md @@ -0,0 +1,6 @@ +# GitNexus 开发后基线 + +- 功能编号：FEAT-DS-001 +- 状态：待开发完成后刷新 + +开发完成后记录索引提交、节点、关系、执行流、状态和变更检测结果。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/before.md b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/before.md new file mode 100644 index 0000000..ded08ec --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/before.md @@ -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`。高风险结果必须先获得用户确认。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/comparison.md b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/comparison.md new file mode 100644 index 0000000..d2252f5 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/comparison.md @@ -0,0 +1,3 @@ +# GitNexus 前后对比 + +开发前基线已记录在 `before.md`。开发后需要对比新增 AKTools Adapter、短线 Service、Controller、Web API、配置和文档是否与计划一致，并说明任何额外影响。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/detected-changes.md b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/detected-changes.md new file mode 100644 index 0000000..cf94cd9 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/detected-changes.md @@ -0,0 +1,6 @@ +# GitNexus 变更检测 + +- 功能编号：FEAT-DS-001 +- 当前阶段：开发前 + +提交前必须使用 `gitnexus_detect_changes({scope: "staged"})`，确认只影响 AKTools 适配、市场概览短线接口、前端状态、配置和文档；若出现 TDX、数据库或消息执行流，必须暂停并重新评估。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/impact-plan.md b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/impact-plan.md new file mode 100644 index 0000000..2fb7b0a --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/gitnexus/impact-plan.md @@ -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 内网运行说明。 | diff --git a/docs/features/FEAT-DS-001-aktools-supplement/implementation-plan.md b/docs/features/FEAT-DS-001-aktools-supplement/implementation-plan.md new file mode 100644 index 0000000..eca6122 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/implementation-plan.md @@ -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 生成产物。 + +## 实施顺序 + +先测试字段校验和映射，再实现客户端；先实现后端契约，再实现前端状态；每个阶段执行对应定向测试，最后执行完整门禁。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/manifest.yaml b/docs/features/FEAT-DS-001-aktools-supplement/manifest.yaml new file mode 100644 index 0000000..c06b71b --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/manifest.yaml @@ -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 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/prd.md b/docs/features/FEAT-DS-001-aktools-supplement/prd.md new file mode 100644 index 0000000..6b13f7f --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/prd.md @@ -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 地址固定为本机内网配置，仓库不包含真实凭据和机器地址。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/qa/test-results.md b/docs/features/FEAT-DS-001-aktools-supplement/qa/test-results.md new file mode 100644 index 0000000..94af423 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/qa/test-results.md @@ -0,0 +1,13 @@ +# 测试结果 + +## 当前状态 + +设计阶段尚未执行本功能代码测试；已完成 AKTools 本机 HTTP 冒烟，涨停池、炸板池和昨日涨停池接口返回 HTTP 200，历史行情接口返回 HTTP 200。 + +## 安全验证 + +设计阶段已确定回环绑定、固定接口、超时和脱敏边界；代码实现后补充自动化证据。 + +## 性能验证 + +设计阶段已确定并行请求和 10 秒单请求超时目标；代码实现后补充耗时证据，不将单次本机结果视为容量结论。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/qa/visual-qa.md b/docs/features/FEAT-DS-001-aktools-supplement/qa/visual-qa.md new file mode 100644 index 0000000..b96777b --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/qa/visual-qa.md @@ -0,0 +1,13 @@ +# 视觉验证 + +## 当前状态 + +设计阶段尚未修改页面。实现后必须验证桌面和窄屏下短线情绪模块的加载、有效、部分和不可用状态。 + +## 安全验证 + +视觉验证不得展示凭据、真实内网地址或 AKTools 原始错误载荷。 + +## 性能验证 + +记录页面首次可见状态和短线模块完成状态，确认 AKTools 延迟不会阻塞 TDX 核心模块。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/release-notes.md b/docs/features/FEAT-DS-001-aktools-supplement/release-notes.md new file mode 100644 index 0000000..a7fcc08 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/release-notes.md @@ -0,0 +1,5 @@ +# 发布说明 + +## 未发布 + +FEAT-DS-001 当前为未发布功能。计划接入 AKTools 内网补充数据源，提供超短情绪指标和规则结论；不改变 TDX 核心市场概览。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/requirements.md b/docs/features/FEAT-DS-001-aktools-supplement/requirements.md new file mode 100644 index 0000000..8badf37 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/requirements.md @@ -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；该接口不影响本功能其余目标接口。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/review/code-review.md b/docs/features/FEAT-DS-001-aktools-supplement/review/code-review.md new file mode 100644 index 0000000..047fe11 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/review/code-review.md @@ -0,0 +1,37 @@ +# 代码 Review + +## 审查范围 + +设计阶段审查目标为 AKTools Client、Mapper、短线 Service、DTO、Controller、Web API、配置和测试。 + +## PRD 与设计符合性 + +实现后检查只接入三个已验证接口，保持 TDX 独立，且不把原始 AKTools 字段直接暴露给前端。 + +## 发现 + +当前尚未进入代码 Review；实现完成后记录按严重级别排序的问题和处置。 + +## 测试缺口 + +需要覆盖上游 5xx、超时、部分接口失败、字段漂移、日期延迟和窄屏状态。 + +## 安全与残余风险 + +检查固定内网地址、请求参数边界、错误脱敏、日志载荷和前端构建产物；AKShare 授权和上游稳定性是残余风险。 + +## 性能与资源影响 + +检查并行请求、超时、响应大小和不引入缓存的边界；不得把本地单次测试宣传为生产容量证明。 + +## GitNexus 与同步修改 + +实现后核对变更检测结果只覆盖计划中的短线链路和文档。 + +## 修复与复审 + +发现问题后记录修复提交和复审证据。 + +## 最终结论 + +当前阶段：pending diff --git a/docs/features/FEAT-DS-001-aktools-supplement/review/standards-review.md b/docs/features/FEAT-DS-001-aktools-supplement/review/standards-review.md new file mode 100644 index 0000000..b5f4313 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/review/standards-review.md @@ -0,0 +1,21 @@ +# 开发规范符合性 Review + +## 检查结果 + +设计阶段已检查功能档案、Schema/GitNexus 前置流程、TDX 与 AKTools 边界及源码部署约束；代码实现后进行逐项复核。 + +## 不符合项与处置 + +当前没有代码不符合项；实现阶段若发现问题，必须在发布前修复并记录。 + +## 安全、性能与架构检查 + +必须确认 AKTools 仅作为外部内网 Adapter，未新增 Docker、生产数据库连接、消息链路或前端直连；同时检查超时、响应上限和降级。 + +## GitNexus 与开发总结检查 + +必须确认开发前后索引、影响计划、变更检测、开发总结、测试结果和 Review 记录完整。 + +## 最终结论 + +当前阶段：pending diff --git a/docs/features/FEAT-DS-001-aktools-supplement/rollback.md b/docs/features/FEAT-DS-001-aktools-supplement/rollback.md new file mode 100644 index 0000000..8f2f11b --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/rollback.md @@ -0,0 +1,16 @@ +# 回退说明 + +## 触发条件 + +出现 TDX 核心行情回归、AKTools 请求阻塞 API、上游原始字段泄漏、OpenAPI 契约不一致或短线模块遮挡核心概览时回退。 + +## 回退步骤 + +1. 关闭 `AKTOOLS_ENABLED` 或回退到上一个完整发布目录。 +2. 重启 API 并确认 TDX 概览接口、Web 健康检查和构建产物正常。 +3. 保留 AKTools 外部服务，不删除其运行环境和数据缓存。 +4. 记录回退原因、提交 SHA、验证结果和后续修复计划。 + +## 数据与外部服务 + +本功能不写 MySQL、Redis 或 RocketMQ，不需要数据回退；AKTools 是独立外部服务，应用回退不负责停止或删除它。 diff --git a/docs/features/FEAT-DS-001-aktools-supplement/test-plan.md b/docs/features/FEAT-DS-001-aktools-supplement/test-plan.md new file mode 100644 index 0000000..4c120e6 --- /dev/null +++ b/docs/features/FEAT-DS-001-aktools-supplement/test-plan.md @@ -0,0 +1,30 @@ +# AKTools 超短行情补充数据源测试计划 + +## 功能验证 + +- 用固定响应夹具验证涨停数量、最高连板和梯队分布。 +- 验证炸板池和昨日涨停池字段缺失、非法数字、空数组的处理。 +- 验证三个请求并行且单个失败返回 partial。 +- 验证全部失败返回 unavailable，TDX 既有接口仍能独立响应。 +- 验证 OpenAPI DTO、Web API 类型和页面状态一致。 + +## 安全验证 + +- 验证客户端拒绝请求参数注入的上游 URL。 +- 验证配置不允许生产地址和公网任意地址。 +- 验证超时、过大响应、非 JSON 响应和上游错误均脱敏。 +- 验证前端构建产物不包含 AKTools 凭据或内部地址。 + +## 性能验证 + +- 验证三个请求使用并行调度而非串行等待。 +- 使用受控延迟夹具验证单请求超时和整体响应上限。 +- 记录定向请求耗时，不把本地单次结果当作生产容量证明。 + +## 视觉验证 + +验证桌面和窄屏下短线情绪模块的加载、部分、不可用、空数据状态，确保警告和交易日期不遮挡指标。 + +## 残余风险 + +AKShare 上游限流、字段变更、数据授权和长期稳定性需要在后续联调与生产评估中持续验证。 diff --git a/docs/superpowers/plans/2026-08-24-aktools-supplement.md b/docs/superpowers/plans/2026-08-24-aktools-supplement.md new file mode 100644 index 0000000..ab5aa7d --- /dev/null +++ b/docs/superpowers/plans/2026-08-24-aktools-supplement.md @@ -0,0 +1,85 @@ +# AKTools Supplement Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task after the written spec is approved. + +**Goal:** Add an internal AKTools-backed short-term market sentiment module without changing the existing TDX overview path. + +**Architecture:** Nest owns the public business API. A fixed AKTools client calls three allowlisted HTTP endpoints in parallel, a mapper validates Chinese upstream fields into stable domain DTOs, and a service derives conservative rules. Vue consumes only Nest API files. + +**Tech Stack:** NestJS, TypeScript, global fetch, Vue 3, Axios request wrapper, OpenAPI generated contracts, Vitest, Playwright, AKTools HTTP on `127.0.0.1:8080`. + +**Spec:** `docs/superpowers/specs/2026-08-24-aktools-supplement-design.md` + +## Global Constraints + +- MySQL remains 5.7.x with `utf8mb4_general_ci`; no database writes or production reads. +- AKTools is an external internal-LAN service; do not add Docker files or vendor Python code. +- Frontend requests go through `web/src/utils/request.ts` and `web/src/api//` only. +- TDX core overview must remain independently available when AKTools fails. +- Every external field must be validated and mapped; raw AKTools fields never cross the API boundary. + +### Task 1: Define configuration and upstream contracts + +**Files:** +- Modify: development and production environment templates, runtime config tests. +- Create: `server/apps/api/src/market-overview/aktools/aktools.types.ts` and client tests. + +- [ ] Add optional `AKTOOLS_ENABLED`, fixed-base-url validation, and timeout configuration. +- [ ] Define raw response types for the three allowlisted endpoints and normalized domain types. +- [ ] Write tests for invalid URL, disabled service, timeout, non-JSON response, oversized response, and HTTP error. +- [ ] Run targeted configuration and client tests. + +### Task 2: Implement AKTools client and mapper + +**Files:** +- Create: `server/apps/api/src/market-overview/aktools/aktools.client.ts`. +- Create: `server/apps/api/src/market-overview/aktools/aktools.mapper.ts`. +- Create: client and mapper tests. + +- [ ] Implement only fixed paths for the three AKTools endpoints. +- [ ] Execute requests with `Promise.allSettled` at the service boundary. +- [ ] Validate dates, numbers, board counts, stock codes, and missing fields. +- [ ] Convert amounts to亿元 only where the source unit is explicitly known. +- [ ] Test field drift and partial records. + +### Task 3: Add short-term API contracts and rules + +**Files:** +- Modify: market overview DTO, module, controller and service. +- Create: short-term service tests and E2E fixtures. + +- [ ] Add `GET /api/v1/market-overview/short-term/emotion` and `conclusion`. +- [ ] Return snapshot metadata, source, trade date, status and warnings. +- [ ] Derive count, max board, tier distribution, broken-board count and previous-limit-up performance. +- [ ] Use conservative labels: strong, weak, divided, insufficient; do not invent repair or true wind-down state without historical baseline. +- [ ] Verify AKTools failure does not alter TDX responses. + +### Task 4: Update generated contracts and Web state + +**Files:** +- Modify: `web/src/api/market-overview/index.ts`, generated schema and market overview composable/page. +- Create: short-term API and component tests. + +- [ ] Add typed API functions through the existing Axios wrapper. +- [ ] Render loading, partial, delayed, unavailable and warning states without blocking TDX modules. +- [ ] Keep the existing analysis horizon and engine preferences unchanged. +- [ ] Verify desktop and narrow viewport layouts. + +### Task 5: Documentation and deployment boundary + +**Files:** +- Modify: architecture, local development, production source deployment and README docs. +- Modify: this feature archive and review evidence. + +- [ ] Document AKTools as an externally managed internal service on port 8080. +- [ ] State that the repository does not install, stop, expose or delete AKTools. +- [ ] Record data authorization, upstream instability, and no-public-exposure boundaries. +- [ ] Update development summary with actual requirements, defects, commits and evidence. + +### Task 6: Verification and release gate + +- [ ] Run unit, contract, boundary, typecheck, build and Playwright verification. +- [ ] Run `npm run governance:finish -- FEAT-DS-001 aktools-supplement`. +- [ ] Refresh GitNexus and run staged `gitnexus_detect_changes`. +- [ ] Complete code Review and standards Review. +- [ ] Commit with Chinese Conventional Commit and immediately push to Gitea. diff --git a/docs/superpowers/specs/2026-08-24-aktools-supplement-design.md b/docs/superpowers/specs/2026-08-24-aktools-supplement-design.md new file mode 100644 index 0000000..36db77f --- /dev/null +++ b/docs/superpowers/specs/2026-08-24-aktools-supplement-design.md @@ -0,0 +1,31 @@ +# AKTools 超短行情补充数据源设计 + +**状态：已获用户确认，待实现** + +## 目标 + +在内网环境把已运行的 AKTools 作为 AKShare 补充数据源，提供 TDX 未覆盖的超短行情指标，不改变现有 TDX 市场概览链路。 + +## 方案 + +Nest API 增加固定的 AKTools Client 和领域 Mapper，按业务接口调用三个已验证的 AKTools endpoint。前端只访问 Nest，不访问 AKTools。V1 不新增 Python 服务、Docker、数据库、Redis 或 RocketMQ。 + +## 数据接口 + +- `stock_zt_pool_em`：涨停池、封板资金、连板数和行业。 +- `stock_zt_pool_zbgc_em`：炸板池和炸板次数。 +- `stock_zt_pool_previous_em`：昨日涨停股今日表现和昨日连板数。 + +Nest 对外提供 `/api/v1/market-overview/short-term/emotion` 和 `/api/v1/market-overview/short-term/conclusion`，不透传 AKTools 通用路由。 + +## 规则口径 + +只使用通过类型、日期和数值校验的记录。V1 输出涨停数量、最高连板、梯队分布、炸板数量、昨日涨停平均涨跌幅和涨跌分布；不计算未经确认口径的炸板率，不把封板资金解释为主力净流入。 + +## 状态与降级 + +接口响应使用 `fresh`、`delayed`、`partial`、`unavailable`。AKTools 失败只影响短线模块；TDX 模块继续工作。每次响应包含 `snapshotId`、`asOf`、`tradeDate`、`source` 和 `warnings`。 + +## 安全与性能 + +AKTools 默认绑定 `127.0.0.1:8080`。Nest 只读取服务端配置，拒绝客户端 URL，设置 10 秒超时、响应大小限制和脱敏错误。三个上游请求并行执行，短线接口 P95 目标小于 12 秒。