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