# LaunchAgent

**Repository Path**: jamieguo/LaunchAgent

## Basic Information

- **Project Name**: LaunchAgent
- **Description**: Current stock diagnosis software relies on the Tushare API to obtain real-time data. In large-data-volume scenarios, it faces issues such as high network latency, slow response, and restricted call frequency.
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-11-26
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 股票数据缓存服务

一个基于 Tushare 的股票数据缓存和 API 服务，支持自动数据同步、RESTful API 接口和 macOS 系统集成。

## 功能特性

- 🚀 **自动数据同步**: 支持定时同步 Tushare 股票数据到本地 SQLite 数据库
- 📊 **RESTful API**: 提供高性能的股票数据查询接口
- 🔧 **命令行工具**: 完整的 CLI 工具支持服务管理和数据同步
- 🍎 **macOS 集成**: 支持 LaunchAgent 开机自启动
- 📝 **完整日志**: 详细的日志记录和异常处理机制
- ⚡ **高性能**: 本地缓存提供毫秒级数据查询响应

## 系统要求

- macOS 10.14 或更高版本
- Python 3.8 或更高版本
- Tushare Pro 账户和 Token

## 快速开始

### 1. 安装依赖

```bash
# 克隆项目
git clone <repository-url>
cd LaunchAgent

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

# 或使用 setup.py 安装
pip install -e .
```

### 2. 配置服务

首次运行会自动创建配置文件：

```bash
python main.py config
```

编辑配置文件 `~/.stockcache/config.yaml`：

```yaml
tushare_token: "your_tushare_token_here"  # 替换为你的 Tushare Token
cache_start_date: "2020-01-01"
server:
  host: "127.0.0.1"
  port: 8000
  auto_sync_time: "09:00"
```

### 3. 启动服务

```bash
# 前台运行（用于测试）
python main.py start

# 后台运行
python main.py start --daemon

# 查看服务状态
python main.py status
```

### 4. 数据同步

```bash
# 同步所有接口数据
python main.py sync run

# 同步指定接口
python main.py sync run --interface stock_basic

# 全量同步（重新下载所有数据）
python main.py sync run --full

# 重试上次失败的接口
python main.py sync run --retry-failed

# 查看失败的接口列表
python main.py sync failed

# 查看支持的接口
python main.py sync list
```

## 命令行工具

### 服务管理

```bash
# 启动服务
python main.py start [--daemon]

# 停止服务
python main.py stop

# 重启服务
python main.py restart

# 查看状态
python main.py status
```

### LaunchAgent 管理

```bash
# 安装开机自启动
python main.py install

# 卸载开机自启动
python main.py uninstall
```

### 数据同步

```bash
# 运行数据同步
python main.py sync run [--full] [--interface <name>] [--retry-failed]

# 重试上次失败的接口
python main.py sync run --retry-failed

# 查看失败的接口列表
python main.py sync failed

# 列出支持的接口
python main.py sync list
```

**重试失败接口说明**：
- 系统会自动记录同步失败的接口到 `~/.stockcache/failed_interfaces.json`
- 使用 `--retry-failed` 选项可以重新同步上次失败的接口
- 使用 `sync failed` 命令可以查看当前失败的接口列表
- 重试成功的接口会自动从失败列表中移除

### 配置管理

```bash
# 显示配置信息
python main.py config
```

## API 接口

服务启动后，可通过以下接口访问数据：

### 基础接口

- `GET /` - 服务信息
- `GET /health` - 健康检查
- `GET /interfaces` - 获取支持的接口列表

### 数据查询接口

动态路由支持所有 Tushare 接口：

```bash
# 获取股票基础信息
curl "http://localhost:8000/stock_basic"

# 获取日线数据
curl "http://localhost:8000/daily?ts_code=000001.SZ&start_date=2024-01-01"

# 获取交易日历
curl "http://localhost:8000/trade_cal?start_date=2024-01-01&end_date=2024-12-31"
```

### 查询参数

- `limit`: 限制返回记录数（默认 1000）
- `offset`: 偏移量（用于分页）
- 其他参数根据具体接口而定

## 支持的数据接口

### 基础数据
- `stock_basic` - 股票基础信息
- `trade_cal` - 交易日历
- `namechange` - 股票曾用名
- `hs_const` - 沪深股通成分股

### 行情数据
- `daily` - 日线行情
- `weekly` - 周线行情
- `monthly` - 月线行情
- `adj_factor` - 复权因子

### 财务数据
- `income` - 利润表
- `balancesheet` - 资产负债表
- `cashflow` - 现金流量表
- `fina_indicator` - 财务指标

### 市场数据
- `moneyflow` - 资金流向
- `stk_holdernumber` - 股东人数
- `top10_holders` - 前十大股东

## 配置说明

### 主配置文件

配置文件位置：`~/.stockcache/config.yaml`

```yaml
# Tushare 配置
tushare_token: "your_token_here"
cache_start_date: "2020-01-01"

# 服务器配置
server:
  host: "127.0.0.1"
  port: 8000
  auto_sync_time: "09:00"

# 数据库配置
db_path: "~/.stockcache/data.db"
cache_dir: "~/.stockcache"
log_directory: "~/.stockcache/logs"

# 接口特殊设置
interface_settings:
  daily:
    start_date: "2020-01-01"
    sync_enabled: true
  income:
    start_date: "2018-01-01"
    sync_enabled: true
```

### 日志配置

日志文件位置：`~/.stockcache/logs/`

- `main.log` - 主日志文件
- `error.log` - 错误日志
- `sync.log` - 数据同步日志

## 开发指南

### 项目结构

```
LaunchAgent/
├── main.py              # 主程序入口
├── cli.py               # 命令行接口
├── config.py            # 配置管理
├── database.py          # 数据库管理
├── sync_engine.py       # 数据同步引擎
├── api_server.py        # API 服务器
├── logger.py            # 日志管理
├── requirements.txt     # 依赖包
├── setup.py            # 安装脚本
└── README.md           # 说明文档
```

### 添加新接口

1. 在 `sync_engine.py` 中的 `TUSHARE_INTERFACES` 字典添加接口配置
2. 配置接口类型、日期字段等参数
3. 重启服务即可自动支持新接口

### 自定义配置

可以通过修改配置文件来自定义：
- 数据同步的起始日期
- 服务器监听地址和端口
- 自动同步时间
- 特定接口的同步设置

## 故障排除

### 常见问题

1. **Tushare Token 错误**
   ```bash
   # 检查 Token 是否正确设置
   python main.py config
   ```

2. **服务启动失败**
   ```bash
   # 检查端口是否被占用
   lsof -i :8000
   
   # 查看详细错误日志
   tail -f ~/.stockcache/logs/error.log
   ```

3. **数据同步失败**
   ```bash
   # 检查网络连接和 Token 权限
   python main.py sync run --interface stock_basic
   ```

4. **LaunchAgent 安装失败**
   ```bash
   # 检查权限和路径
   ls -la ~/Library/LaunchAgents/
   ```

### 日志查看

```bash
# 查看主日志
tail -f ~/.stockcache/logs/main.log

# 查看错误日志
tail -f ~/.stockcache/logs/error.log

# 查看同步日志
tail -f ~/.stockcache/logs/sync.log
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.0.0
- 初始版本发布
- 支持基础股票数据同步和查询
- 完整的 CLI 工具
- macOS LaunchAgent 集成
- 完善的日志和异常处理机制