stock-tool/README.md

# 📈 股票数据分析工具

一个基于 Go + SQLite + 免费API的股票数据分析工具，内置网页界面。

## 🎯 开发模式 (PERDAS 增强版)

本项目采用 **PERDAS (Permanently Executing Development Agent System)** 增强版架构进行开发。

### 核心特点

✅ **增量开发** - 每次只实现一个功能
✅ **强制测试** - 所有功能必须通过端到端测试
✅ **可追溯** - 所有修改都有 Git 历史
✅ **状态持久化** - 会话间保持工作连贯

### 工作流程

1. **初始化** - 运行 `init.sh` 启动环境
2. **健康检查** - 运行 `scripts/health-check.sh` 验证环境
3. **选择功能** - 查看 `feature_list.json` 了解任务
4. **开发功能** - 按照步骤实现功能
5. **端到端测试** - 运行 `scripts/e2e-test.sh` 验证
6. **截图证据** - 保存测试截图到 `tests/screenshots/`
7. **提交代码** - Git commit 并更新 `feature_list.json`

### 强约束指令

> **绝对禁止删除或修改测试用例**

- ❌ 不允许删除或修改测试用例
- ❌ 不允许删除或修改其他功能的代码
- ❌ 不允许修改 `feature_list.json` 中除 `passes` 字段外的内容
- ❌ 不允许未通过端到端测试就标记完成
- ❌ 不允许未保存截图证据就标记完成

### 开发工作流

每次会话开始时：

```bash
# 1. 确认工作目录
pwd  # 应该是 /root/.openclaw/workspace/stock-tool

# 2. 启动开发环境
./init.sh

# 3. 验证环境健康状态
./scripts/health-check.sh

# 4. 运行端到端测试
./scripts/e2e-test.sh

# 5. 查看功能清单
cat feature_list.json

# 6. 查看进度
cat PROGRESS.md
```

每次开发完成时：

```bash
# 1. 更新进度文件
vim PROGRESS.md

# 2. 更新 feature_list.json（仅修改 passes 字段）
jq '.features[] | select(.id=="feat-001") | .passes = true' feature_list.json > tmp.json && mv tmp.json feature_list.json

# 3. Git commit
git add .
git commit -m "feat: 完成 feat-001 股票列表展示功能"

# 4. 查看提交历史
git log --oneline -5
```

## 🚀 快速开始（标准模式）

### 环境要求
- Go 1.21+
- SQLite3

### 安装依赖
```bash
cd stock-tool
go mod download
```

### 运行程序
```bash
go run main.go
```

### 访问网页
打开浏览器访问: http://localhost:8080

## 📊 功能特性

### 1. 股票列表展示
- 展示所有已添加的股票
- 实时价格、涨跌幅
- 基本面指标（市值、PE、ROE、负债率）

### 2. 股票搜索
- 支持按股票代码搜索
- 支持按公司名称搜索

### 3. 股票详情
- **K线图**：展示100天历史走势
- **技术指标**：RSI、MACD、均线系统
- **基本面数据**：收入、利润、ROE等

### 4. 数据刷新
- 一键刷新股票数据
- 自动更新数据库

## 🗄️ 数据库结构

### stocks 表
```sql
CREATE TABLE stocks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    symbol TEXT UNIQUE,
    name TEXT,
    current_price REAL,
    change REAL,
    change_percent REAL,
    market_cap TEXT,
    pe_ratio REAL,
    roe REAL,
    debt_ratio REAL,
    update_time TEXT
);
```

### klines 表
```sql
CREATE TABLE klines (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    symbol TEXT,
    date TEXT,
    open REAL,
    high REAL,
    low REAL,
    close REAL,
    volume INTEGER,
    FOREIGN KEY(symbol) REFERENCES stocks(symbol)
);
```

### indicators 表
```sql
CREATE TABLE indicators (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    symbol TEXT,
    date TEXT,
    rsi REAL,
    macd REAL,
    macd_signal REAL,
    ma5 REAL,
    ma10 REAL,
    ma20 REAL,
    update_time TEXT,
    FOREIGN KEY(symbol) REFERENCES stocks(symbol)
);
```

### financials 表
```sql
CREATE TABLE financials (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    symbol TEXT UNIQUE,
    revenue REAL,
    profit REAL,
    roe REAL,
    debt_to_equity REAL,
    update_time TEXT
);
```

## 📡 API接口

### 获取股票列表
```
GET /api/stocks
```

### 获取股票详情
```
GET /api/stock/:symbol
```

### 获取K线数据
```
GET /api/stock/:symbol/kline
```

### 获取技术指标
```
GET /api/stock/:symbol/indicators
```

### 获取财务数据
```
GET /api/stock/:symbol/financials
```

### 搜索股票
```
GET /api/search?q=关键词
```

### 刷新股票数据
```
GET /api/refresh/:symbol
```

## 🔌 支持的API

### 1. Yahoo Finance (yfinance)
- **免费额度**: 无限制
- **数据**: 历史K线、实时报价、财务报表
- **使用**: 直接通过yfinance库获取

### 2. Alpha Vantage
- **免费额度**: 25次请求/天
- **数据**: 技术指标、实时数据
- **使用**: 补充技术分析数据

### 3. Finnhub
- **免费额度**: 60次请求/月
- **数据**: 基本面、新闻、经济指标
- **使用**: 财报数据分析

## 🎯 选股策略示例

### 技术分析选股
```python
# 筛选条件示例
1. MACD金叉（短线上穿长线）
2. RSI < 30（超卖）
3. MA5 > MA10 > MA20（多头排列）
4. 换手率 > 5%
```

### 基本面选股
```python
# 筛选条件示例
1. ROE > 15%
2. 负债率 < 60%
3. PE < 30
4. 利润增长率 > 10%
```

## 📝 使用建议

### 初学者
1. 先使用模拟数据体验界面
2. 学习如何读取和展示数据
3. 理解基本的API调用

### 进阶用户
1. 集成真实的yfinance API
2. 添加更多技术指标计算
3. 实现选股策略自动化

### 专业用户
1. 接入真实的历史数据源
2. 添加回测功能
3. 实现实盘交易接口

## ⚠️ 风险提示

> **股市有风险，投资需谨慎**
>
> 本工具仅用于技术学习和数据分析，不构成任何投资建议。
> 所有数据均为模拟数据，实际使用时请接入真实API源。

## 🛠️ 开发计划

- [ ] 集成真实的yfinance API
- [ ] 添加更多技术指标（布林带、KDJ等）
- [ ] 实现选股策略自动化
- [ ] 添加回测功能
- [ ] 支持更多数据源
- [ ] 移动端适配
- [ ] 深色/浅色主题切换

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**开发者**: Geliebte
**更新时间**: 2026-02-18