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,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.