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