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

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/<domain>/` 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.

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 秒。