# ai-final

**Repository Path**: superdalin/ai-final

## Basic Information

- **Project Name**: ai-final
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 固定自选股 A 股投研小系统

**免责声明**：本仓库仅用于研究与学习，不构成任何投资建议；行情与衍生指标来自第三方接口，可能存在延迟、缺漏或错误，请勿用于实盘决策。

## 功能概览

- 可配置固定几只沪深 A 股（`config/watchlist.yaml`）。
- **日频**：AkShare 拉取前复权日线 → **MySQL 增量 upsert** → Registry + Pipeline 计算指标 → 稳定结构的 **`snapshot` JSON**（供前端消费）。
- 架构：`DataSource` 协议（默认 AkShare）+ **Analyzer 注册表** + YAML 启用分析单元；扩展示例见 `app/analyzers/example_atr.py`。
- CLI：`python -m app.build_snapshot`；可选 FastAPI：`GET /api/snapshot` 返回与文件相同的 JSON。

## 设计说明

### 指标不落库

日 K 落在 `daily_bars` 表（唯一键 `(symbol, trade_date)`）。**指标在每次生成 snapshot 时由 OHLCV 现算**，避免每新增一个 Analyzer 就要改表结构或迁移；历史行情可稳定增量，指标逻辑可迭代。

### 复权与时区约定

- **前复权**：AkShare `adjust="qfq"`；在 snapshot 每只股票 `meta.adjustment` 中说明。
- **日期**：沪深交易日，`YYYY-MM-DD`；无毫秒级实时行情语义。

### Pipeline 阶段

实现顺序（见 `app/pipeline/runner.py`）：

1. **增量 persist**：对每只股票，自 DB 中最大 `trade_date` 次一交易日起拉数并 upsert（无历史则按 `lookback_days` 估算起始日历范围）。
2. **load_bars**：从 MySQL 读取窗口（尾部 `lookback_days` 行）。
3. **normalize**：如零成交量停牌标记等。
4. **run_analyzers**：按 `config/pipeline.yaml` 从注册表调度。
5. **assemble_snapshot**：合并可选基本面字段（失败则空 dict + 日志）。
6. **validate**：契约检查。

## 环境要求

- Python **3.10+**
- **MySQL** 5.7+ / 8.x（需自行创建数据库）
- Node **18+**（仅前端）

## 后端安装与建表

```bash
cd /path/to/ai_final
python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -r requirements.txt
```

若出现 **Read timed out** / 下载 PyPI 过慢，可换镜像并加大超时（示例：清华源）：

```bash
python -m pip install -U pip -i https://pypi.tuna.tsinghua.edu.cn/simple --default-timeout=120
python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --default-timeout=120
```

建表（在目标库执行）：

```bash
mysql -h %MYSQL_HOST% -u %MYSQL_USER% -p %MYSQL_DATABASE% < sql/schema.sql
```

或使用任意客户端执行 `sql/schema.sql`。

## 环境变量（必填，禁止把密码写入代码或提交仓库）

| 变量 | 说明 |
|------|------|
| `MYSQL_HOST` | 主机，默认 `127.0.0.1`（仍建议显式设置） |
| `MYSQL_PORT` | 端口，默认 `3306` |
| `MYSQL_USER` | 用户名 |
| `MYSQL_PASSWORD` | 密码 |
| `MYSQL_DATABASE` | 库名 |

可将 `.env.example` 复制为 **`.env`**（已在 `.gitignore` 中忽略），[pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) 会自动读取。

## 配置 watchlist 与 Pipeline

- **股票列表**：`config/watchlist.yaml` — `symbols[].code` 为 6 位代码。
- **分析器与参数**：`config/pipeline.yaml` — `analyzers` 列表中 `id` 对应注册表中的 Analyzer。
- **输出路径与窗口**：`config/app.yaml` — `data_source`（行情实现 id，见 `app.datasource.factory.build_data_source`）、`snapshot_path`、`lookback_days`、拉数重试等。
- **程序化 / 测试**：`run_pipeline(source=my_data_source)` 可注入自定义 `DataSource`，无需改编排代码。

### Snapshot `meta` 补充字段

- **`analyzerRuns`**：各 Analyzer 的执行摘要；若某 id 抛错，对应项含 `error` 字符串，后续 Analyzer 仍会在**未扩展**的 DataFrame 上继续跑（详见 `app/pipeline/analyzers_runner.py`）。前端可据此展示告警。

## 生成 snapshot（CLI）

```bash
# 已配置 .env 或导出环境变量
python -m app.build_snapshot
# 或指定输出路径
python -m app.build_snapshot --output data/snapshot.json -v
# 覆盖数据源 id（默认读 app.yaml 的 data_source）
python -m app.build_snapshot --data-source akshare
```

默认写出路径为 `config/app.yaml` 中的 `snapshot_path`（一般为 `data/snapshot.json`）。写出时使用 `allow_nan=False`，若指标中出现非有限浮点会提前报错。

## 可选：FastAPI

```bash
uvicorn app.api:app --reload --host 127.0.0.1 --port 8000
```

- `GET http://127.0.0.1:8000/api/snapshot` — 读取磁盘上与 CLI 相同的 JSON 文件（需先运行 CLI 生成）。
- CORS：`allow_origins=["*"]` 且 **`allow_credentials=False`**，与浏览器规范一致，适合本地无 Cookie 的 `fetch`。

## 前端（Vue 3 + TypeScript + ant-design-vue + ECharts）

```bash
cd frontend
npm install
npm run dev
```

- 开发环境通过 Vite 代理将 `/api` 转发到 `http://127.0.0.1:8000`；可同时启动 FastAPI 与 `npm run dev`。
- 也可将生成的 `data/snapshot.json` 复制到 `frontend/public/snapshot.json`，前端会优先尝试 `/api/snapshot`，失败则回退静态文件。

构建：

```bash
npm run build
```

## 新增 Analyzer（验收点）

1. 新建 `app/analyzers/your_analyzer.py`，类属性 `id = "your_id"`，实现 `analyze(self, ohlcv, params)`.
2. 使用 `@register` 装饰器。
3. 在 `app/analyzers/__init__.py` 中 `import app.analyzers.your_analyzer` 触发注册。
4. 在 `config/pipeline.yaml` 的 `analyzers` 中启用。

无需修改 Pipeline 核心 `if/else`。

## 单元测试

```bash
pip install -U pip
pip install -r requirements.txt pytest
pytest -q
```

若暂未安装 pytest，可运行（需已安装 `pandas`、`sqlalchemy` 等依赖）：

```bash
python scripts/quick_check.py
```

## 自测说明（验收）

1. **CLI**：在 `config/watchlist.yaml` 配置 2～3 只真实代码，配置 MySQL 与 `.env`，执行建表 SQL 后运行 `python -m app.build_snapshot`；应完成 AkShare 拉数、增量写入、`data/snapshot.json` 生成（受网络与交易所日历影响，需在交易数据可用时段验证）。
2. **前端**：`npm run dev`，选择股票与日期区间，应显示 K 线、均线、成交量；指标副图位预留。
3. **扩展示例**：`example_atr` 已按「新文件 + 注册 + 配置」接入。
4. **安全**：仓库内无数据库密码明文；`.env` 已 gitignore。