a-share-analysis/docs/superpowers/plans/2026-08-24-aktools-supplement.md

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.