# analysis

**Repository Path**: guokaige/data_analysis

## Basic Information

- **Project Name**: analysis
- **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-08-25
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# A 股数据分析系统

这是一个面向个人长期使用的 A 股数据分析与选股系统。系统以本地通达信行情为事实输入，以相互独立、可版本化的指标为核心，通过批量计算形成可追溯的指标结果，再提供选股查询和落选解释。

项目优先级：

> 简单可用 > 结果可信 > 快速验证 > 稳定扩展 > 架构完整

## 当前阶段

项目处于 MVP / Phase 1 可运行阶段。统一链路已经覆盖四个相互独立、可版本化的真实指标，并提供了基于已发布结果的多指标聚合页面：

```text
本地通达信
    ↓
未复权日线与除权事件
    ↓
前复权、完整周过滤、W-FRI 聚合、ATR20
    ↓
weekly_last_zhongshu_down v1.0.0
或 daily_pre_breakout_rounded_bottom v1.0.0
或 daily_chip_concentration_90 v1.0.0
或 monthly_last_zhongshu v4.4.0
    ↓
indicator_runs / indicator_results
    ↓
单指标查询与多指标 AND/OR 聚合选股
```

第一个指标是“前复权周线最后中枢向下突破”。参考算法使用 CZSC 生成笔，按时间顺序重建同级中枢，在末端宽中枢中按需寻找日线嵌套中枢，并以连续 5 根完整周 K 的最高价均低于 ZD 确认向下突破。

第二个指标是“日线突破前圆弧底候选池”。它在最近 100 个交易日内识别左侧平台、中心最低价和至少两个逐步抬高的日线底分型，以历史放量日确认候选资格，并仅使用日收盘价判断颈线突破或右侧支撑失效。

第三个指标是“估算日/周/月筹码 90% 成本集中度”。它只使用本地日线和除权事件，独立计算日线以及由日线聚合的完整周线、月线价格—成交量持仓分布；由于没有可靠自由流通股本，换手衰减明确标记为保守估算。

第四个指标是“月线长期整理后突破”。它在最近 36 个完整月内寻找至少连续 15 个月的整理，要求至少 80% 的月 K 收盘环比涨跌幅绝对值不超过 9%；首次收盘突破后冻结区间，最近 8 个月出现首次、反向或回区间后再次突破均可命中。振幅上限 65%，路径效率上限 0.5，突破使用整理末月实体 ATR5 的 0.25 倍缓冲；不启用市值或历史低位分位过滤。

## 数据源

MVP 只支持本地通达信安装目录，不依赖 Data Center API，也不自动下载或更新行情。

- 配置值为 `vipdoc` 的父目录。
- 读取沪深本地日线、证券名称及通达信除权除息数据。
- 只分析沪深主板普通 A 股。
- 调度任务只读取本地文件；通达信数据更新由用户在系统外完成。
- 指标本身不直接访问文件，读取逻辑通过一个薄的 `MarketDataSource` 接口隔离。

## 技术栈

- Python 3.12
- FastAPI
- PostgreSQL
- SQLAlchemy 2
- Alembic
- APScheduler
- pandas
- pytdx
- CZSC
- pytest、ruff、mypy

FastAPI 和 APScheduler Worker 是同一代码库中的两个独立进程，共用 PostgreSQL。MVP 的 FastAPI 只提供只读查询；批量计算由 CLI 或 Worker 发起。

## 快速开始

### 1. 安装

```powershell
python -m pip install -e ".[dev]"
```

### 2. 配置

`TDX_DIR` 必须指向 `vipdoc` 的父目录，`DATABASE_URL` 使用 SQLAlchemy 的 PostgreSQL URL：

```powershell
$env:TDX_DIR = "C:\path\to\tdx"
$env:DATABASE_URL = "postgresql+psycopg://user:password@localhost:5432/a_share_analysis"
```

也可以在项目根目录创建不入库的 `config.ini` 保存通达信目录：

```ini
[tdx]
tdx_dir=C:\path\to\tdx
```

`DATABASE_URL` 仍通过环境变量提供；命令行的全局参数 `--tdx-dir` 优先级最高。

### 3. 建表

```powershell
alembic upgrade head
```

### 4. 计算与解释

单股运行只用于验证或诊断，不会成为全市场筛选的默认数据源：

```powershell
a-share-analysis indicator run weekly_last_zhongshu_down --code 600123
a-share-analysis indicator explain weekly_last_zhongshu_down 600123 --run-id <RUN_ID>
```

全市场运行会读取沪深主板股票，并在成功完成后发布为最新筛选批次：

```powershell
a-share-analysis indicator run weekly_last_zhongshu_down
a-share-analysis indicator explain weekly_last_zhongshu_down 600123
a-share-analysis indicator run daily_pre_breakout_rounded_bottom
a-share-analysis indicator explain daily_pre_breakout_rounded_bottom 600123
a-share-analysis indicator run daily_chip_concentration_90
a-share-analysis indicator explain daily_chip_concentration_90 600123
a-share-analysis indicator run monthly_last_zhongshu
a-share-analysis indicator explain monthly_last_zhongshu 600123
```

可用 `--as-of YYYY-MM-DD` 指定截止日；指标参数均有对应的 kebab-case 选项，例如 `--min-interaction-pct 85`。

### 5. 查询 API

```powershell
uvicorn a_share_analysis.api.app:create_runtime_app --factory --host 127.0.0.1 --port 8000
```

浏览器打开：

- `http://127.0.0.1:8000/screening`：多指标 AND/OR 聚合选股页面。

只读接口：

- `GET /healthz`
- `GET /api/v1/indicators/{indicator_code}/runs/latest`
- `GET /api/v1/indicators/{indicator_code}/runs`
- `GET /api/v1/indicators/{indicator_code}/matches`
- `GET /api/v1/indicators/{indicator_code}/stocks/{code}?run_id=<RUN_ID>`
- `GET /api/v1/screening/indicators`
- `POST /api/v1/screening/aggregate`
- `POST /api/v1/screening/export`：按当前指标与 AND/OR 条件导出全部命中结果的 Excel。

聚合使用每个指标各自最新的已发布全市场批次。页面会展示每个批次的算法版本和数据截止日；不同指标的日期可以不同，但会明确提示。筛选结果可导出为带冻结表头和自动筛选的 `.xlsx`，导出范围为当前条件的全部命中股票，不受页面分页限制。页面只读取结果，不触发指标计算。

### 6. 日批 Worker

```powershell
a-share-worker
```

默认在 Asia/Shanghai 时区的周一至周五 18:30 执行全市场批次。同一作业最多运行一个实例，错过执行时间会在一小时内补跑。

### 7. 验证

```powershell
python -m ruff format --check .
python -m ruff check .
python -m mypy src/a_share_analysis
python -m pytest -m "not integration and not local_tdx"
python -m pytest tests/browser
python -m pytest -m local_tdx
python -m pytest -m integration
```

`tests/browser` 在本机存在 Playwright Chromium 时执行真实页面交互，否则跳过；`local_tdx` 需要 `TDX_DIR`；`integration` 需要指向一次性测试库的 `TEST_DATABASE_URL`，不得使用生产库。

## 核心模块

- `market_data`：读取并标准化本地通达信数据。
- `indicators`：实现相互独立的纯指标算法。
- `indicator_engine`：组织逐股计算和运行状态。
- `indicator_results`：保存运行记录、逐股结果和审计信息。
- `screening`：查询已完成的指标结果，并在应用层执行简单 AND/OR 聚合。
- `reporting`：未来的日报汇总能力，当前不实现。
- `api`、`cli`、`scheduler`：系统入口，不承载业务算法。

## 核心原则

- 原始数据不伪造、不补 K、不用未来数据。
- 未完成周 K 不参与中枢、ATR 或突破计算。
- 每个指标独立演进，不直接调用其他指标。
- 算法版本与运行参数分开记录。
- 每次运行保存所有股票的结果，未命中和异常同样可追溯。
- Stock Screening 只查询持久化结果，不临时重算指标。
- 不为尚未出现的需求提前引入微服务、消息队列、规则引擎或插件系统。

## 文档导航

- [PROJECT_GOAL.md](PROJECT_GOAL.md)：目标、范围和验收标准。
- [PROJECT_CONSTITUTION.md](PROJECT_CONSTITUTION.md)：不可随意破坏的工程与架构规则。
- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)：目录职责和依赖方向。
- [PROJECT_ROADMAP.md](PROJECT_ROADMAP.md)：阶段规划与三年扩展路线。
- [CURRENT_SPRINT.md](CURRENT_SPRINT.md)：当前唯一开发目标。
- [docs/indicators/weekly_last_zhongshu_down.md](docs/indicators/weekly_last_zhongshu_down.md)：首个指标算法规范。
- [docs/indicators/monthly_last_zhongshu.md](docs/indicators/monthly_last_zhongshu.md)：至少 15 个月整理、80% 月涨跌幅不超过 9%、冻结区间及最近 8 月突破事件规则。
- [docs/indicators/daily_pre_breakout_rounded_bottom.md](docs/indicators/daily_pre_breakout_rounded_bottom.md)：日线突破前圆弧底候选池算法规范。
- [docs/indicators/daily_chip_concentration_90.md](docs/indicators/daily_chip_concentration_90.md)：本地筹码分布、90% 成本区间及限制。

## 当前不做

用户与权限、多租户、复杂 Strategy、Rule Engine、指标评分、筛选组合保存、页面触发计算、微服务、消息队列、分布式计算、高频实时计算、复杂缓存、复杂前端和自动行情下载均不在 MVP 范围内。

系统的长期资产是数据解释规则、指标算法、历史结果和可复现的分析过程，而不是页面数量。