# EmotionQuant_clean

**Repository Path**: zengfr/EmotionQuant_clean

## Basic Information

- **Project Name**: EmotionQuant_clean
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-16
- **Last Updated**: 2025-12-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

G:\EmotionQuant_new# EmotionQuant - A股情绪量化交易系统

<div align="center">

![EmotionQuant Logo](https://img.shields.io/badge/EmotionQuant-v0.87.1-blue?style=for-the-badge&logo=python)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Python: 3.9+](https://img.shields.io/badge/Python-3.9+-green.svg?style=for-the-badge&logo=python)](https://www.python.org/)
[![Market: A-Share](https://img.shields.io/badge/Market-A股专属-red.svg?style=for-the-badge)](https://www.sse.com.cn/)

**基于市场情绪而非技术指标的A股量化分析系统**

*个人开发，个人使用，先实现再优化*  
*凡谋事，先规划，再细化，再分解，再按步骤一步步实现*  
*可信，可行，可用，可控*

</div>

---

## 🎯 项目简介

EmotionQuant是专为**个人开发者**和**个人投资者**设计的A股情绪量化分析系统。遵循"**个人开发，个人使用，先实现再优化**"的理念，采用"**先规划，再细化，再分解，再按步骤实现**"的开发方式，确保每个交付物都达到"**可信，可行，可用，可控**"的质量标准。

### 🧬 项目基因

- **个人至上**: 一切设计以个人开发者和个人用户为中心
- **渐进迭代**: 先实现核心功能，再逐步优化完善  
- **系统规划**: 每个决策都经过完整的规划→细化→分解→实现流程
- **质量第一**: 确保每个交付物都满足"四可"标准

### ✨ 核心特色

- **情绪驱动**: 基于涨跌家数、涨跌停统计等情绪数据，零技术指标 *(可信)*
- **A股专属**: 深度适配T+1交易、涨跌停限制、申万31个行业分类 *(可行)*
- **个人友好**: 线性流水线设计，≤8小时/周维护，个人可理解可维护 *(可用)*
- **渐进开发**: 先实现再优化，2小时快速部署，完整文档体系 *(可控)*

### 💡 核心理念（项目基因）

- **个人开发，个人使用，先实现再优化**: 专注个人开发者友好，渐进式完善
- **凡谋事，先规划，再细化，再分解，再按步骤一步步实现**: 系统性思维，6A工作流体现
- **可信，可行，可用，可控**: 四可标准贯穿所有设计决策
- **情绪驱动**: 基于市场情绪而非技术指标的量化方法
- **A股专属**: 深度适配A股市场特色，考虑T+1、涨跌停等规则
- **科学严谨**: 遵循四大铁律约束，确保系统专业性

### 🏛️ 四大铁律（体现"四可"标准）

EmotionQuant严格遵循四大铁律，确保系统的专业性和个人开发友好性：

1. **🚫 技术指标绝对禁用** *(确保可信)*
   - 禁用所有移动平均线、RSI、MACD等技术指标
   - 基于涨跌家数、成交量分布等情绪相关数据进行分析
   - 零容忍扫描器自动检测，确保算法透明可信

2. **🇨🇳 A股特色强制适配** *(确保可行)*
   - 支持T+1交易制度、涨跌停限制（主板±10%、创业板/科创板±20%、北交所±30%、ST±5%）
   - 申万2021版31个一级行业分类完整支持
   - 考虑A股散户情绪放大效应，技术方案成熟可行

3. **🔺 个人开发友好架构** *(确保可用)*
   - MSS(Market Sentiment System)：市场情绪系统
   - IRS(Industry Rotation System)：行业轮动系统（申万31个行业）
   - PAS(Price Action System)：价格行为系统
   - 线性流水线架构，个人开发者可理解可维护

4. **📋 6A工作流执行** *(确保可控)*
   - 先规划(Align)→再细化(Architect)→再分解(Atomize)→审批(Approve)→按步骤实现(Automate)→评估(Assess)
   - 确保从需求到交付的全过程可控、可追溯、高质量

---

## 🔄 工作流更新（2025-01-15）

**6A工作流 v7.0 发布：简化文档结构，每阶段一个文档**

我们对开发工作流进行了进一步优化，简化文档结构，提高执行效率：

### 核心变更

- **简化文档**: 从8个文档减少到6个文档（每阶段一个文档）
- **新增A4审批**: 增加方案评估阶段，提前发现问题
- **合并A6文档**: 验收+总结+待办三合一，减少文档碎片
- **废弃飞行检查表**: A3的tasks.md已足够详细，不再需要单独的飞行检查表

### 6个文档结构

1. **A1: requirements.md** - Task级别需求文档
2. **A2: design.md** - Task级别设计文档
3. **A3: tasks.md** - Task级别执行步骤
4. **A4: approve.md** - 方案评估报告 ✨ **NEW**
5. **A5: review.md** - 审查报告
6. **A6: final.md** - 最终报告（验收+总结+待办）✨ **三合一**

### 详细信息

- 📄 [6A工作流规范](.kiro/steering/6a-workflow.md) (v7.0)
- 📄 [更新日志](CHANGELOG.md#工作流更新---2025-01-14)
- 📄 [任务执行Prompt模板](.kiro/TEMPLATE/6A-TASK-EXECUTION-PROMPT.md) (v7.0)

---

## 🚀 快速开始

### 📋 当前开发状态

> **🎉 重大里程碑**: Phase 6 数据本地化完成！数据自由实现！
>
> - ✅ **Phase 0 完成**: 核心情绪温度计算算法验证通过（2025-10-06）
> - ✅ **Phase 1 完成**: MVP核心功能（v0.5.0，2025-10-08）
> - ✅ **Phase 2 完成**: MSS情绪分析完善（v0.6.0，2025-10-09）
>   - ✅ 五态情绪分类优化（准确率≥90%）
>   - ✅ 散户情绪识别器（准确率≥85%）
>   - ✅ 情绪历史追踪（7日/30日趋势）
>   - ✅ 极端情绪预警系统
> - ✅ **Phase 3 完成**: IRS行业轮动分析器（v0.7.0，2025-01-13）
>   - ✅ 申万31个一级行业完整支持
>   - ✅ 行业强弱排名、资金流向、情绪温度
>   - ✅ 轮动信号生成、配置建议、热力图
>   - ✅ Streamlit行业分析页面
> - ✅ **Phase 6 完成**: 数据本地化与离线能力（v0.87.0，2025-01-15）⭐⭐⭐⭐⭐
>   - ✅ SimpleDataFetcher架构改造
>   - ✅ 历史数据下载器（支持断点续传）
>   - ✅ 增量数据更新机制
>   - ✅ 数据完整性校验和版本管理
>   - ✅ 离线模式支持
>   - ✅ MSS/IRS/PAS透明集成
> - 📅 **Phase 4-5, 7-10**: 后续阶段（计划中）
>   - Phase 4: PAS价格行为确认器
>   - Phase 5: A股特色功能完善
>   - Phase 7: 情绪驱动风险管理⭐⭐⭐⭐⭐
>   - Phase 8: 自研回测系统⭐⭐⭐⭐⭐
>   - Phase 9: 交易执行与记录⭐⭐⭐⭐⭐
>   - Phase 10: 性能优化与持续维护
>
> **总体进度**: 56% (56/121任务完成)
>
> 查看详细信息：
>
> - 📊 [Phase 6 交付报告](.kiro/specs/phase-6-data-localization/DELIVERY_REPORT.md)
> - 📋 [开发状态文档](docs/development-status.md)
> - 🗺️ [项目路线图](.kiro/steering/ROADMAP.md)

### 环境要求

- Python 3.9+
- TuShare Pro账户 (数据源)
- Windows/Linux/macOS

### 安装步骤

```bash
# 1. 克隆项目
git clone https://github.com/everything-is-simple/EmotionQuant_clean.git
cd EmotionQuant_clean

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的 TUSHARE_TOKEN

# 4. 启动 Web 界面
python -m streamlit run src/app/main.py
```

### 数据源（按优先级）⭐ **Phase 6完成**

EmotionQuant 已实现**本地数据优先**策略，确保分析结果可信：

1. **本地数据库**（Phase 6已完成）⭐⭐⭐⭐⭐ ✅
   - ✅ 离线可用，查询快速（毫秒级）
   - ✅ SQLite存储，支持增量更新
   - ✅ 包含A股所有历史日线数据
   - ✅ 数据完整性100%验证通过
   - ✅ 支持数据备份和恢复

2. **TuShare Pro API**（数据补充）⭐⭐⭐⭐
   - ✅ 增量获取最新数据
   - ✅ 自动保存到本地数据库
   - ✅ 智能重试机制
   - 需要配置API Token

**重大成就**: Phase 6数据本地化完成，实现数据自由！

**Phase 6-Fix**: 模拟数据已彻底清理，系统100%使用真实市场数据。

**参考**: [数据使用规范](.kiro/steering/DATA_USAGE_POLICY.md)

**配置 TuShare Token**：

```bash
# 在 .env 文件中设置
TUSHARE_TOKEN=your_token_here

# 启动应用
python -m streamlit run src/app/main.py
```

### 参与开发

EmotionQuant欢迎开发者参与贡献！

```bash
# 查看当前开发任务
cat .kiro/specs/active/phase1-mvp/tasks.md

# 选择任务并开始开发
# 1. Fork项目
# 2. 创建功能分支
# 3. 遵循开发规范（见developer-guide.md）
# 4. 提交Pull Request
```

### Phase 6 数据本地化（✅ 已完成 - v0.87.0 + v0.87.1）⭐⭐⭐⭐⭐

**🎉 重大里程碑**: Phase 6 数据本地化与离线能力已完成！实现数据自由，摆脱TuShare依赖！

#### 核心功能（2025-01-22完成）

**架构改造**:
- ✅ **SimpleDataFetcher架构改造** - 本地数据优先，保持接口兼容
- ✅ **MSS/IRS/PAS透明集成** - 无需修改，自动使用本地数据

**数据下载和更新**:
- ✅ **历史数据下载器** - 支持断点续传，分批下载
- ✅ **增量数据更新器** - 智能增量更新，自动调度
- ✅ **更新失败重试** - 最多3次重试，确保数据完整

**数据质量保证**:
- ✅ **数据完整性校验** - 交易日、字段、范围全面检查
- ✅ **数据一致性验证** - 本地vs远程数据对比
- ✅ **数据版本管理** - 版本号、更新历史、回滚支持

**离线模式**:
- ✅ **离线模式切换** - 一键切换在线/离线模式
- ✅ **数据备份恢复** - 完整的备份和恢复工具

**Phase 6-Fix 模拟数据清理**:
- ✅ **代码清理** - 8处模拟数据逻辑彻底清理
- ✅ **配置清理** - 模拟数据配置项完全删除
- ✅ **测试更新** - 全部使用真实数据（908 passed）
- ✅ **文档更新** - 删除模拟数据引用，标记废弃

**工具脚本**:
- ✅ **统一市场分析工具** (`market_analyzer.py`) - 4步工作流
- ✅ **Excel报告生成** (`generate_excel_from_db.py`) - 从数据库生成报告
- ✅ **完整文档** (`tools/USAGE_GUIDE.md`) - 详细使用指南

**性能指标**（实测）:
- 数据下载：100只股票/批次
- 增量更新：< 5秒/股票
- 数据查询：< 100ms
- 离线模式：性能无明显下降

**质量保证**:
- ✅ 四大铁律：100%合规
- ✅ 测试通过率：100%
- ✅ 测试覆盖率：85%+
- ✅ 代码质量：Black + Flake8 零警告
- ✅ 模拟数据扫描：零匹配（除Phase 0遗留文件）

### Phase 3 IRS行业轮动（✅ 已完成 - v0.7.0）

Phase 3 IRS行业轮动分析器已完成！提供完整的申万31个行业轮动分析能力。

#### 核心功能（2025-01-13）

**已完成模块**:

- ✅ **行业数据模型** (`industry_analyzer.py`) - 申万31个一级行业数据结构
- ✅ **行业数据获取** (`tushare_client.py`) - TuShare API集成，行业数据缓存
- ✅ **行业强弱排名** (`industry_rotation.py`) - 基于涨跌幅的行业强弱计算
- ✅ **资金流向分析** (`industry_analyzer.py`) - 基于成交额的资金流向统计
- ✅ **行业情绪温度** (`industry_emotion.py`) - 基于涨跌家数的行业情绪计算
- ✅ **轮动信号生成** (`rotation_signal_generator.py`) - 多维度轮动信号算法
- ✅ **配置建议算法** (`allocation_advisor.py`) - 基于轮动分析的资产配置
- ✅ **热力图数据生成** (`output_generator.py`) - 行业热力图可视化数据
- ✅ **完整测试套件** (`test_irs_integration.py`) - 集成测试和单元测试

**性能指标**（实测）:

- 31个行业数据处理：< 1秒
- 轮动信号计算：< 500ms
- 配置建议生成：< 200ms
- 热力图数据生成：< 300ms
- 测试覆盖率：85%+

**质量保证**:

- ✅ 四大铁律：100%合规
- ✅ 测试通过率：100%
- ✅ 技术指标扫描：零匹配
- ✅ 申万31个行业：完整支持
- ✅ 代码质量：Black + Flake8 零警告

### Phase 1 MVP核心（✅ 已完成 - v0.5.0）

Phase 1 MVP 已完成！提供完整的数据获取、情绪分析和 Web 界面功能。

#### 核心功能（2025-10-08）

**完整模块**:

- ✅ **配置管理** (`config.py`) - 环境变量加载、日志系统
- ✅ **数据模型** (`data_models.py`) - MarketSnapshot、StockData、EmotionResult
- ✅ **SQLite缓存** (`sqlite_cache.py`) - 批量插入优化，性能提升15倍
- ✅ **TuShare API集成** (`tushare_client.py`) - 涨跌停识别、重试机制
- ✅ **数据获取器** (`data_fetcher.py`) - 本地数据优先策略（Phase 6改造）
- ✅ **MSS情绪分析引擎** (`emotion_analysis_engine.py`) - 完整算法实现
- ✅ **线性流水线** (`linear_pipeline.py`) - 完整分析流程编排
- ✅ **输出生成器** (`output_generator.py`) - Plotly 图表和数据导出
- ✅ **Streamlit Web 界面** (`src/app/main.py`) - 友好的 Web 界面

**性能指标**（实测）:

- 5000只股票处理：< 2秒
- 缓存读取：< 100ms
- 情绪温度计算：< 200ms
- 内存使用：< 100MB
- 测试覆盖率：80%+

**质量保证**:

- ✅ 四大铁律：100%合规
- ✅ 测试通过率：100%
- ✅ 技术指标扫描：零匹配
- ✅ A股特色支持：完整
- ✅ 代码质量：Black + Flake8 零警告

#### 快速体验

```python
from src.core.config import Config
from src.core.linear_pipeline import LinearPipeline

# 1. 加载配置
config = Config.from_env()

# 2. 初始化流水线
pipeline = LinearPipeline(config)

# 3. 运行分析
result = pipeline.run_analysis("20241008")

# 4. 查看结果
print(f"情绪温度: {result.temperature:.2f}°C")
print(f"情绪状态: {result.emotion_state}")
print(f"散户情绪强度: {result.retail_strength:.2f}")
```

#### Web 界面

启动 Streamlit 应用，通过浏览器访问：

```bash
python -m streamlit run src/app/main.py
```

功能包括：

- 📊 情绪温度计图表（Plotly 交互式）
- 📈 涨跌家数统计表
- 🎯 五态情绪分类（冰点/修复/乐观/狂热/回落）
- 💪 散户情绪强度指标
- 💾 JSON 数据导出
- 🔄 缓存管理

### Phase 0 概念验证（✅ 已完成）

Phase 0 成功验证了 EmotionQuant 核心情绪温度计算算法的可行性！

#### 快速演示

```bash
# 运行 Phase 0 演示脚本
python scripts/demo_phase0.py

# 输出示例：
# ============================================================
# 场景: 冰点 (Ice Point)
# ============================================================
# 日期: 20251006
# 温度: 15.23°C
# 情绪状态: 冰点
# 总股票数: 5000
# 上涨: 750 (15.00%)
# 下跌: 4250 (85.00%)
# 涨停: 0 (0.00%)
# 跌停: 100 (2.00%)
# 散户情绪强度: 0.30
# 极端比例: 2.00%
```

#### 核心成果

- ✅ **情绪温度计算算法**：完整实现 0-100°C 温度计算
- ✅ **五态情绪分类**：冰点/修复/乐观/狂热/回落
- ✅ **A股特色支持**：涨跌停处理、散户情绪识别
- ✅ **真实数据支持**：TuShare API + 本地数据库（Phase 6）
- ✅ **控制台演示**：完整的可视化输出

#### 验证结果

| 验证项 | 目标 | 实际 | 状态 |
|--------|------|------|------|
| 算法准确性 | 五种场景正确 | 100% 准确 | ✅ |
| 计算性能 | < 1ms | 0.5ms | ✅ |
| 测试通过率 | 100% | 36/36 | ✅ |
| 测试覆盖率 | ≥ 80% | 86.7% | ✅ |
| 代码质量 | 零警告 | Black ✅ Flake8 ✅ | ✅ |
| 技术指标扫描 | 零匹配 | 0 匹配 | ✅ |
| 四大铁律 | 100% 合规 | 100% | ✅ |

#### 交付物

**代码文件**:

- `src/core/data_models.py` - 数据模型定义
- `src/core/emotion_calculator.py` - 核心情绪计算器
- `src/core/console_display.py` - 控制台输出
- `scripts/demo_phase0.py` - 演示脚本

**注意**: Phase 0 使用了 `simulated_data_generator.py`（已废弃），仅作为历史记录保留。Phase 1-10 使用真实市场数据。

**测试文件**:

- `tests/test_data_models.py` - 数据模型测试（10 tests）
- `tests/test_emotion_calculator.py` - 情绪计算器测试（15 tests）
- `tests/test_data_fetcher.py` - 数据获取器测试（真实数据）

**文档文件**:

- [Phase 0 验证结果报告](docs/phase0-results.md) - 完整验证报告
- [Phase 0 质量检查报告](docs/phase0-quality-report.md) - 代码质量报告
- [Phase 0 合规性报告](docs/phase0-compliance-report.md) - 四大铁律合规报告
- [Phase 0 交付清单](docs/phase0-delivery-checklist.md) - 完整交付清单

#### Phase 0 文档归档

Phase 0 概念验证已完成，相关文档已归档到 `archive/phase0/` 目录：

- **需求设计文档**: `archive/phase0/specs/`
- **飞行检查单**: `archive/phase0/flight-checklists/`
- **执行记录**: `archive/phase0/execution-logs/`

详见：[Phase 0 归档说明](archive/phase0/README.md)

#### Phase 1 集成建议

Phase 0 的 `EmotionCalculator` 可以直接集成到 Phase 1：

```python
# Phase 1: src/core/emotion_analysis.py
from src.core.emotion_calculator import EmotionCalculator

class EmotionAnalysisEngine:
    def __init__(self):
        self.calculator = EmotionCalculator()
    
    def analyze(self, market_data: pd.DataFrame) -> EmotionResult:
        snapshot = self._convert_to_snapshot(market_data)
        return self.calculator.calculate_temperature(snapshot)
```

查看详细信息：

- 📊 [Phase 0 验证结果报告](docs/phase0-results.md)
- 📋 [Phase 0 归档文档](archive/phase0/README.md)

### 预期功能（Phase 1开发中）

```python
# 线性流水线架构（规划中的API）
from src.core.linear_pipeline import LinearPipeline

# 初始化流水线
pipeline = LinearPipeline(data_dir="data")

# 运行分析流程
snapshot = pipeline.run_analysis("20241030")

# 查看结果
print(f"情绪温度: {snapshot.emotion_temperature:.1f}°C")
print(f"涨跌比例: {snapshot.rise_count}/{snapshot.fall_count}")
print(f"强势行业: {snapshot.top_industries[:3]}")
```

## 🏗️ 系统架构

### 核心组件

- **数据获取层**: TuShare API集成，支持缓存和重试
- **情绪分析引擎(MSS)**: 基于涨跌家数计算市场情绪温度（0-100°C）
- **行业轮动分析器(IRS)**: 申万2021版31个一级行业轮动分析
- **价格行为确认器(PAS)**: 无技术指标的价格行为分析
- **输出生成器**: Streamlit界面和Excel/JSON报告生成

### 技术特色

- **SQLite数据库**: 轻量级本地数据存储和缓存（data/emotionquant.db）
- **三级缓存机制**: 内存→数据库→API，提升性能
- **A股特色支持**: T+1交易、涨跌停、申万31个行业分类
- **线性流水线**: 简化的数据处理流程，个人开发友好

## 🇨🇳 A股特色功能

### 核心特色

- **T+1交易制度**: 完整支持T+1交易规则和限制
- **涨跌停处理**: 自动识别不同板块涨跌停限制
  - 主板：±10%
  - 创业板/科创板：±20%
  - 北交所：±30%
  - ST股票：±5%
- **申万行业分类**: 支持申万2021版31个一级行业分类
  - 完整覆盖：农林牧渔、采掘、化工、钢铁、有色金属等31个行业
  - 行业轮动分析和热力图展示
- **ST股票处理**: 自动识别和处理ST、*ST等特殊股票
- **北向资金**: 支持北向资金流向分析（规划中）

---

## 📖 文档导航

### 📚 文档体系

- [📖 文档导航中心](docs/README.md) - 完整文档导航和使用指南
- [📋 文档结构说明](DOCUMENTATION_STRUCTURE.md) - 文档组织和维护规范

### 🚀 用户指南

- [🚀 快速开始指南](docs/quick-start.md) - 快速上手和安装配置
- [📚 用户使用指南](docs/user-guide.md) - 详细功能说明和使用方法
- [🚀 部署指南](docs/deployment.md) - 本地环境部署和配置

### 👨‍💻 开发者资源

- [🏗️ 开发者指南](docs/developer-guide.md) - 代码结构和开发流程
- [📡 API参考文档](docs/api-reference.md) - 完整的API接口说明
- [🔄 6A工作流](.kiro/steering/6a-workflow.md) - 开发流程规范
- [🧠 核心算法设计](docs/design/core-algorithms.md) - MSS/IRS/PAS算法详解
- [📊 数据模型设计](docs/design/data-models.md) - 数据结构和存储方案
- [🛡️ 四大铁律详解](docs/design/four-iron-laws.md) - 核心设计原则
- [🇨🇳 A股特色功能](docs/design/a-share-features.md) - 中国市场专属功能

### 📋 项目信息

- [📊 开发状态](docs/development-status.md) - 当前进度和待办事项
- [🗺️ 项目路线图](.kiro/ROADMAP.md) - 开发计划和里程碑
- [📦 归档文档](archive/README.md) - 历史文档和任务记录

## 🧪 测试与开发

### 运行测试

```bash
# 运行所有测试
pytest

# 运行核心模块测试
pytest tests/core -v

# 查看覆盖率报告
pytest --cov=src --cov-report=html:reports/coverage

# 质量检查
eq-test  # 快速质量检查
```

### 开发工具

```bash
# 代码格式化
black src/ tests/

# 代码检查
flake8 src/ tests/

# 运行分析流水线
eq-run --date 20241030
```

---

## 📄 许可证

本项目采用 MIT 许可证。查看 [LICENSE](LICENSE) 文件了解详情。

---

## �* 致谢

- [TuShare](http://TuShare.org/) - 提供优质的A股数据支持
- [申万](https://www.swhysc.com/) - 行业分类标准制定者
- Python量化社区 - 开源精神和技术支持

---

<div align="center">

**EmotionQuant** - 让A股投资更理性，让量化分析更透明

*Built with ❤️ for Chinese Stock Market*

</div>