aiagents-stock/docs/MULTI_SCHEDULE_GUIDE.md

# 多定时分析功能使用指南

## 📖 功能概述

多定时分析功能允许您设置**多个每日分析时间点**，系统将在每个时间点自动执行持仓批量分析。

### 使用场景

- ✅ **盘前+盘后分析**：开盘前09:25 + 收盘后15:05
- ✅ **多频次监控**：早盘09:30 + 午盘13:00 + 尾盘14:50
- ✅ **分时段策略**：早中晚三次分析，捕捉不同时段机会
- ✅ **灵活配置**：根据个人作息和交易习惯自定义

---

## 🚀 快速开始

### 1. 进入定时任务管理

1. 启动应用：`streamlit run app.py`
2. 点击侧边栏 **"📊 持仓分析"**
3. 切换到 **"⏰ 定时任务"** 标签

### 2. 添加定时时间

1. 点击 **"➕ 添加定时时间"** 展开表单
2. 选择新的分析时间（如 15:05）
3. 点击 **"➕ 添加"** 按钮
4. 系统自动按时间顺序排列

### 3. 删除定时时间

1. 在已配置时间列表中找到要删除的时间
2. 点击该时间旁边的 **"🗑️"** 按钮
3. 确认删除（至少保留1个时间）

### 4. 启动调度器

1. 配置好所有定时时间后
2. 点击 **"▶️ 启动调度器"**
3. 系统将在每个时间点自动执行分析

---

## 💡 推荐配置

### 方案1：盘前+盘后（保守）

适合：长期投资者、上班族

```
09:25  盘前分析（开盘前5分钟，提前布局）
15:05  盘后分析（收盘后5分钟，复盘总结）
```

**优点**：
- 信息全面：盘前看预期，盘后看实际
- 不影响工作：两个时间点不频繁
- 数据准确：收盘数据完整可靠

### 方案2：三时段监控（积极）

适合：活跃投资者、短线交易者

```
09:30  早盘分析（开盘后观察）
13:05  午盘分析（午盘结束，调整策略）
15:05  尾盘分析（收盘总结）
```

**优点**：
- 全天跟踪：早中晚全覆盖
- 及时调整：发现异常快速反应
- 捕捉机会：不同时段的交易机会

### 方案3：高频监测（专业）

适合：专业交易者、日内交易

```
09:25  盘前预测
10:00  早盘检查
11:30  午前评估
13:05  午盘分析
14:30  尾盘准备
15:05  收盘复盘
```

**优点**：
- 极致监控：全天候跟踪
- 快速响应：及时发现变化
- 数据密集：积累更多历史

**注意**：高频分析消耗更多API调用，确保额度充足

### 方案4：夜盘准备（港美股）

适合：投资港股美股的用户

```
08:30  早间准备
21:00  美股开盘前（夏令时20:30，冬令时21:30）
```

**优点**：
- 跨市场：覆盖A股和美股
- 错峰分析：避开A股交易时段

---

## ⚙️ 功能详解

### 添加定时时间

**步骤**：
1. 展开 "➕ 添加定时时间"
2. 使用时间选择器选择时间
3. 点击"➕ 添加"

**规则**：
- 时间格式：24小时制（00:00 - 23:59）
- 自动去重：相同时间不会重复添加
- 自动排序：按时间从早到晚排列
- 即时生效：调度器运行中添加会立即生效

### 删除定时时间

**步骤**：
1. 找到要删除的时间卡片
2. 点击 "🗑️" 按钮

**规则**：
- 最少保留：至少保留1个时间点
- 即时生效：调度器运行中删除会立即生效
- 不可恢复：删除后需重新添加

### 查看定时状态

**状态栏显示**：
- 🟢 调度器运行中 / 🔴 调度器已停止
- ⏰ 定时数量：X个
- ⏭️ 下次运行：最近的运行时间

**时间列表**：
- 以卡片形式展示所有时间点
- 每行显示4个时间
- 自动按时间排序

---

## 🎯 最佳实践

### 1. 合理设置时间点

**推荐**：
- 2-3个时间点最佳（盘前、盘后）
- 避免设置过多（>5个）导致频繁分析

**避免**：
- 不要在交易时段频繁分析（影响关注盘面）
- 不要在凌晨设置（数据未更新）

### 2. 考虑数据更新时间

| 数据类型 | 更新时间 | 建议分析时间 |
|---------|---------|-------------|
| 实时行情 | 交易时段 | 盘中任意时间 |
| 日K线 | 15:00后 | 15:05后 |
| 龙虎榜 | 次日8:00 | 次日9:00后 |
| 财务报表 | 季度发布 | 任意时间 |
| 主力资金 | 实时更新 | 盘中/盘后 |

### 3. 平衡分析频次与API消耗

**API消耗估算**：
- 每只股票分析约需 6-10 次API调用
- 10只持仓，3个时间点 = 每日180-300次调用
- 确保DeepSeek API额度充足

**优化建议**：
- 减少定时点数量
- 选择顺序分析（避免并发限流）
- 仅在关键时间点执行

### 4. 调试和监控

**查看运行日志**：
- 终端输出会显示每次执行的详细日志
- 包括开始时间、完成时间、成功/失败统计

**下次运行时间**：
- 状态栏显示最近的运行时间
- 启动调度器后自动计算

**历史记录**：
- 每次分析都会保存到数据库
- 切换到"分析历史"标签查看

---

## 🔧 配置示例

### 示例1：稳健投资者

```
定时时间：
  - 09:25 (盘前)
  - 15:05 (盘后)

分析配置：
  - 模式：顺序分析
  - 自动监测：开启
  - 通知推送：开启
```

### 示例2：短线交易者

```
定时时间：
  - 09:30 (开盘)
  - 11:30 (午前)
  - 13:05 (午后)
  - 14:50 (尾盘)

分析配置：
  - 模式：并行分析（3线程）
  - 自动监测：开启
  - 通知推送：开启
```

### 示例3：港美股投资者

```
定时时间：
  - 08:30 (A股准备)
  - 15:05 (A股复盘)
  - 21:00 (美股准备)

分析配置：
  - 模式：并行分析（5线程）
  - 自动监测：开启
  - 通知推送：开启（Webhook实时推送）
```

---

## 💻 技术实现

### 数据结构

```python
# 原来：单个时间字符串
self.schedule_time = "09:30"

# 现在：时间列表
self.schedule_times = ["09:30", "15:05", "20:00"]
```

### 调度逻辑

```python
# 为每个时间点创建独立的调度任务
for time_str in self.schedule_times:
    schedule.every().day.at(time_str).do(self._scheduled_job)
```

### 向后兼容

```python
# schedule_time属性仍可用（返回第一个时间）
@property
def schedule_time(self) -> str:
    return self.schedule_times[0] if self.schedule_times else "09:30"
```

---

## 🐛 常见问题

### Q1: 最多可以设置几个定时时间？

**A:** 理论上无限制，但建议不超过5个。原因：
- API调用量成倍增长
- 分析结果变化过于频繁
- 用户难以处理过多通知

### Q2: 多个时间点是否共享配置？

**A:** 是的，所有时间点共享相同的分析配置：
- 分析模式（顺序/并行）
- 自动监测同步开关
- 通知推送开关
- 分析师选择

如需不同配置，建议使用其他定时工具（如系统cron）。

### Q3: 两个时间间隔太近会怎样？

**A:** 建议间隔至少30分钟，避免：
- 数据未更新，分析结果重复
- 上次分析未完成，新任务已触发
- API调用过于频繁

### Q4: 调度器重启后时间配置会丢失吗？

**A:** 当前配置存储在内存中，重启会丢失。建议：
- 未来版本将支持配置持久化
- 当前可在代码中设置默认时间

### Q5: 如何查看某个时间点的执行历史？

**A:** 切换到"分析历史"标签，按时间筛选：
- 查看 `analysis_time` 字段
- 筛选特定时间段的记录
- 对比不同时间点的分析结果

---

## 📊 性能影响

### API调用量

| 持仓数 | 1个时间点 | 2个时间点 | 3个时间点 |
|-------|---------|----------|----------|
| 5只   | 30-50次/天 | 60-100次/天 | 90-150次/天 |
| 10只  | 60-100次/天 | 120-200次/天 | 180-300次/天 |
| 20只  | 120-200次/天 | 240-400次/天 | 360-600次/天 |

### 执行时间

- 不同时间点独立执行，互不影响
- 并行模式可缩短单次执行时间
- 确保两次分析之间有足够间隔

---

## 🎊 更新内容

### 新增功能
- ✅ 支持添加多个定时时间点
- ✅ 支持删除定时时间点
- ✅ 自动按时间排序
- ✅ 重复检测和防护
- ✅ 即时生效（运行中修改）

### UI改进
- ✅ 卡片式时间展示（4个一行）
- ✅ 快速添加时间选择器
- ✅ 一键删除按钮
- ✅ 定时数量统计

### 技术优化
- ✅ 向后兼容旧代码
- ✅ schedule库多任务调度
- ✅ 自动重新调度机制

---

## 🔄 升级指南

### 从单定时升级到多定时

**原有配置保持不变**：
- 原来设置的时间会作为第一个时间点
- `schedule_time` 属性仍可用（返回第一个时间）
- 不需要修改任何配置即可使用

**开始使用多定时**：
1. 进入定时任务管理界面
2. 查看当前配置的时间（默认09:30）
3. 点击"添加定时时间"添加新时间
4. 重启调度器生效

---

## 📝 示例：配置盘前+盘后分析

### 步骤演示

1. **进入界面**
   - 侧边栏 → "📊 持仓分析" → "⏰ 定时任务"

2. **查看默认配置**
   - 已配置：09:30（默认）

3. **添加收盘后分析**
   - 展开"➕ 添加定时时间"
   - 选择时间：15:05
   - 点击"➕ 添加"
   - 确认添加成功

4. **配置分析选项**
   - 分析模式：并行分析
   - 并行线程数：3
   - 自动同步到监测：✓
   - 发送完成通知：✓
   - 点击"💾 更新配置"

5. **启动调度器**
   - 点击"▶️ 启动调度器"
   - 确认状态：🟢 调度器运行中
   - 查看下次运行时间

6. **验证配置**
   - 定时数量：2个
   - 时间列表：09:30, 15:05
   - 等待到达时间，自动执行

### 预期结果

- **每天09:25**：自动分析持仓 → 同步监测 → 发送通知
- **每天15:05**：自动分析持仓 → 同步监测 → 发送通知
- **分析历史**：每天新增2条记录/只股票
- **邮件/Webhook**：每天收到2次通知

---

## 🎯 进阶技巧

### 1. 错峰分析

避开市场高峰时段：
```
09:35  开盘5分钟后（数据稳定）
13:10  午盘10分钟后（避开高峰）
15:10  收盘10分钟后（避开拥堵）
```

### 2. 分级监控

不同时段不同策略：
- **早盘**：关注开盘价，捕捉缺口
- **午盘**：评估上午表现，调整仓位
- **收盘**：总结全天，规划次日

### 3. 结合实时监测

- 定时分析更新监测参数
- 实时监测触发价格通知
- 形成"定时评估+实时监控"闭环

---

## 🆘 故障排查

### 问题1：添加时间失败

**可能原因**：
- 时间已存在
- 时间格式错误

**解决**：
- 检查时间列表是否已有该时间
- 使用时间选择器而非手动输入

### 问题2：删除时间失败

**可能原因**：
- 只剩1个时间（不允许全部删除）

**解决**：
- 先添加新时间再删除旧时间
- 至少保留1个定时配置

### 问题3：某个时间点未执行

**可能原因**：
- 系统时间不准确
- 应用已关闭
- 上次分析未完成

**解决**：
- 检查系统时间
- 保持应用运行（使用后台模式）
- 增大时间间隔

### 问题4：调度器重启后配置丢失

**当前限制**：
- 配置存储在内存中
- 应用重启会丢失

**临时方案**：
- 记录时间配置
- 重启后重新添加

**未来计划**：
- 配置持久化到数据库
- 自动恢复上次配置

---

## 📚 相关文档

- **主要文档**：`docs/PORTFOLIO_USAGE.md` - 完整使用指南
- **统一规范**：`docs/UNIFIED_ANALYSIS_SPEC.md` - 分析调用规范
- **技术设计**：`openspec/changes/add-portfolio-scheduled-analysis/design.md`

---

## 🎉 总结

多定时分析功能让您可以：

✅ 灵活设置多个每日分析时间
✅ 全天候跟踪持仓变化
✅ 捕捉不同时段的交易机会
✅ 自动执行，无需人工干预
✅ 即时生效，动态调整

**祝您投资顺利！** 📈