jj2/项目说明文档.md

# 基金监控系统项目说明文档

## 1. 项目概述

基金监控系统是一个实时监控基金净值、展示投资收益并支持定时邮件推送的Web应用。系统提供直观的基金数据展示、历史净值图表、基金配置管理和邮件提醒功能，帮助用户及时了解基金投资情况。

### 核心功能
- 实时基金净值监控与收益计算
- 基金分组管理（多渠道）
- 历史净值趋势图表展示
- 定时基金状态邮件推送（工作日14:30）
- 访问统计与操作日志
- 基金推荐管理
- 响应式设计，支持深色主题

## 2. 技术栈

| 技术         | 版本/说明                  | 用途                          |
|------------|-------------------------|-----------------------------|
| PHP        | 5.6+                    | 服务器端脚本语言，处理业务逻辑与API请求      |
| JavaScript | ES6+                    | 前端交互与数据处理                  |
| HTML5      | -                       | 页面结构与内容展示                  |
| CSS3       | -                       | 页面样式与响应式设计                 |
| Chart.js   | CDN引入                  | 基金净值趋势图表绘制                 |
| Font Awesome | CDN引入                | 图标资源                       |
| JSON       | -                       | 数据存储与API响应格式                |
| XAMPP      | 推荐环境                   | PHP开发与运行环境                 |

## 3. 项目结构

```
├── index.php              # 主页面 - 基金监控面板
├── api.php                # 核心API - 基金数据获取与邮件发送
├── admin.php              # 管理后台 - 基金配置与邮件设置
├── login.php              # 登录页面 - 管理后台登录验证
├── recommend_fund.php     # 基金推荐页面 - 用户提交基金推荐
├── admin_api.php          # 管理API - 后台数据接口
├── script.js              # 主页面JavaScript - 数据加载与交互
├── admin.js               # 管理后台JavaScript - 表单处理与交互
├── styles.css             # 主页面样式
├── admin.css              # 管理后台样式
└── data/                  # 数据存储目录
    ├── visits.json        # 访问统计数据
    ├── stats.json         # 统计信息
    ├── fund_config.json   # 基金配置
    ├── fund_history.json  # 基金历史数据
    ├── operation_log.json # 操作日志
    ├── fund_daily_data.json # 基金每日数据
    ├── email_config.json  # 邮件配置
    ├── email_status.json  # 邮件发送状态
    └── cache/             # 基金数据缓存目录
```

## 4. 主要功能模块

### 4.1 基金监控面板（index.php）
- **实时基金数据展示**：显示当前净值、估算净值、涨跌幅等信息
- **多渠道分组**：支持按渠道管理不同的基金组合
- **收益计算**：自动计算投资收益与收益率
- **自动刷新**：默认每10秒自动刷新数据
- **统计面板**：显示访问统计与最近访问记录
- **主题切换**：支持浅色/深色主题切换

### 4.2 管理后台（admin.php）
- **基金配置**：添加、编辑、删除基金配置
- **推荐基金管理**：审核和管理用户推荐的基金
- **操作日志**：查看系统操作历史记录
- **净值图表**：查看基金历史净值趋势
- **邮箱设置**：配置SMTP服务器和邮件接收人

### 4.3 基金推荐（recommend_fund.php）
- **用户基金推荐**：允许用户提交基金推荐
- **IP限制**：每IP限制推荐数量
- **数据验证**：确保基金代码有效性

### 4.4 邮件推送功能
- **定时发送**：工作日14:30自动发送基金状态邮件
- **自定义配置**：支持配置SMTP服务器、发件人、收件人
- **邮件内容**：包含基金净值、涨跌幅、收益情况

## 5. API接口说明

### 5.1 核心API（api.php）

| 接口名称 | 请求方法 | 参数 | 返回值 | 描述 |
|--------|--------|-----|-------|------|
| fund_data | GET | - | JSON | 获取实时基金数据与收益计算 |
| get_stats | GET | - | JSON | 获取访问统计数据 |
| get_fund_chart | GET | fund_code | JSON | 获取基金历史净值数据 |
| send_fund_email | GET | - | JSON | 手动触发基金邮件发送 |

### 5.2 管理API（admin_api.php）

| 接口名称 | 请求方法 | 参数 | 返回值 | 描述 |
|--------|--------|-----|-------|------|
| get_funds | GET | - | JSON | 获取基金配置数据 |
| save_funds | POST | funds | JSON | 保存基金配置 |
| get_recommended_funds | GET | - | JSON | 获取推荐基金列表 |
| approve_recommended_fund | GET | fund_code | JSON | 批准推荐基金 |
| delete_recommended_fund | GET | fund_code | JSON | 删除推荐基金 |
| get_email_config | GET | - | JSON | 获取邮箱配置 |
| save_email_config | POST | smtp配置 | JSON | 保存邮箱配置 |
| get_operation_log | GET | - | JSON | 获取操作日志 |

## 6. 安装和配置

### 6.1 环境要求
- PHP 5.6+（推荐7.0+）
- Web服务器（Apache/Nginx）
- 支持JSON扩展的PHP环境
- 支持fsockopen函数（用于SMTP邮件发送）

### 6.2 安装步骤
1. 将项目文件部署到Web服务器根目录
2. 确保`data/`目录可写
3. 确保PHP环境已启用必要扩展（json, openssl等）
4. 访问`index.php`即可使用主页面
5. 访问`admin.php`进入管理后台（默认密码：qiyu123123）

### 6.3 配置文件

#### 基金配置（data/fund_config.json）
```json
[
    {
        "channel": "0",
        "fund_code": "003766",
        "investment": 1000
    },
    {
        "channel": "1",
        "fund_code": "004206",
        "investment": 1500
    }
]
```

#### 邮箱配置（data/email_config.json）
```json
{
    "smtp_server": "smtp.qq.com",
    "smtp_port": 465,
    "smtp_secure": "ssl",
    "username": "your_email@qq.com",
    "password": "your_password",
    "from_email": "your_email@qq.com",
    "from_name": "基金监控系统",
    "to_emails": ["recipient1@example.com", "recipient2@example.com"]
}
```

## 7. 使用说明

### 7.1 主页面使用
1. 访问`index.php`查看基金实时数据
2. 点击"刷新"按钮手动刷新数据
3. 点击"统计"按钮查看访问统计
4. 点击"主题"按钮切换深色/浅色主题
5. 点击基金卡片可查看详细信息

### 7.2 管理后台使用
1. 访问`admin.php`并使用默认密码登录（qiyu123123）
2. **基金配置**：
   - 点击"添加基金"添加新的基金配置
   - 编辑现有基金的代码和投资金额
   - 删除不需要的基金配置
3. **推荐基金管理**：
   - 审核用户提交的基金推荐
   - 删除不适合的推荐基金
4. **邮箱设置**：
   - 配置SMTP服务器信息
   - 添加邮件接收人
   - 保存配置并测试发送

### 7.3 定时邮件推送
- 系统默认在工作日14:30自动发送基金状态邮件
- 可通过`test_fund_email.php`手动测试邮件发送
- 可在`api.php`中修改发送时间配置
- **宝塔面板定时触发**：使用专用脚本`cron_send_email.php`支持宝塔面板定时任务调用，无需管理员权限
  ```bash
  C:/xampp/php/php.exe C:/xampp/htdocs/2/cron_send_email.php
  ```
  （需根据实际安装路径调整PHP和脚本路径）

## 8. 代码结构和核心类

### 8.1 核心类：FundMonitorAPI

`FundMonitorAPI`类位于`api.php`中，是系统的核心处理类，负责基金数据获取、邮件发送、数据存储等功能。

**主要方法：**

- `__construct()`：类初始化，创建必要的目录和配置文件，设置时区
- `loadEmailConfig()`：加载邮箱配置
- `sendEmail()`：使用Socket直接连接SMTP服务器发送邮件
- `shouldSendEmail()`：判断是否应该发送邮件（时间条件检查，支持±5分钟误差）
- `sendFundStatusEmail()`：发送基金状态邮件
- `getFundData()`：获取基金实时数据（按涨跌幅从高到低排序）
- `getFundChartData()`：获取基金历史净值数据
- `updateStats()`：更新访问统计

### 8.2 数据处理流程

1. 前端通过AJAX请求`api.php?action=fund_data`获取基金数据
2. API类从外部数据源获取基金实时净值
3. 计算基金收益与涨跌幅
4. 缓存数据并返回JSON响应
5. 前端渲染基金卡片和统计信息
6. 定时任务触发邮件发送功能

## 9. 扩展和定制

### 9.1 添加新的基金数据源
1. 在`api.php`中修改`getFundData()`方法
2. 添加新的数据源处理逻辑
3. 确保返回数据格式与现有格式一致

### 9.2 修改邮件发送时间
在`api.php`中修改以下配置：

```php
private $emailSchedule = [
    'days' => [1, 2, 3, 4, 5], // 1-5代表周一到周五
    'hour' => 14,              // 小时
    'minute' => 30             // 分钟
];
```

### 9.3 自定义基金分组（渠道）
在`script.js`和`admin.js`中修改渠道名称和图标配置：

```javascript
function getChannelName(channel) {
    const channelNames = {
        '0': '渠道一',
        '1': '渠道二',
        '2': '渠道三'
        // 添加新的渠道名称
    };
    return channelNames[channel] || `渠道${channel}`;
}
```

## 10. 故障排除

### 10.1 常见问题

**问题1：基金数据无法加载**
- 检查网络连接是否正常
- 确认PHP环境支持curl或file_get_contents
- 查看浏览器控制台的错误信息
- 检查`api.php`中的基金数据源是否可访问

**问题2：邮件发送失败**
- 检查SMTP服务器配置是否正确
- 确认邮箱密码和授权码是否有效（注意：QQ邮箱需使用授权码而非登录密码）
- 检查服务器是否允许发送邮件（端口是否开放）
- 查看邮件发送日志（`data/email_status.json`）
- 确认收件人邮箱格式是否正确

**问题3：管理后台登录失败**
- 确认密码是否正确（默认：qiyu123123）
- 检查session功能是否正常
- 清除浏览器缓存并重新登录
- 检查`login.php`中的密码验证逻辑

**问题4：定时邮件不发送**
- 确认服务器时间和时区设置是否正确
- 检查`test_fund_email.php`是否能正常发送邮件
- 查看`data/email_status.json`文件的发送状态
- 检查`api.php`中的时间配置是否正确
- 确认定时任务是否正常运行（宝塔面板或服务器cron）

### 10.2 日志文件

- **操作日志**：`data/operation_log.json` - 记录系统操作历史
- **邮件发送状态**：`data/email_status.json` - 记录邮件发送情况
- **访问统计**：`data/stats.json` - 记录网站访问数据

## 11. 注意事项

### 11.1 环境配置注意事项

- **PHP版本**：建议使用PHP 7.0+版本，确保兼容性和性能
- **服务器权限**：确保`data/`目录具有可写权限（755或777）
- **时区设置**：在`php.ini`中设置正确的时区（如：`date.timezone = Asia/Shanghai`）
- **防火墙设置**：确保服务器允许访问外部基金数据源和SMTP服务器

### 11.2 宝塔面板定时任务注意事项

- **执行周期**：设置为每天执行，系统会在内部判断是否为工作日
- **执行时间**：建议设置为14:29执行，系统会在14:30发送邮件
- **命令格式**：
  - URL方式：`curl -s http://yourdomain.com/test_fund_email.php`
  - 命令行方式：`php /www/wwwroot/yourdomain.com/test_fund_email.php`
- **日志记录**：开启日志记录功能，便于排查问题
- **执行用户**：确保执行用户具有文件读写权限

### 11.3 数据安全注意事项

- **定期备份**：定期备份`data/`目录下的所有配置文件
- **密码安全**：登录管理后台后立即修改默认密码
- **访问限制**：通过IP限制或宝塔面板的访问控制功能限制管理后台访问
- **数据验证**：所有用户输入都应进行验证，防止恶意输入

### 11.4 性能优化注意事项

- **缓存机制**：系统已实现基金数据缓存，减少重复请求
- **自动刷新**：默认每10秒自动刷新，可根据需要调整`script.js`中的`AUTO_REFRESH_INTERVAL`参数
- **并发控制**：系统已实现请求防抖，避免并发请求导致的性能问题
- **资源加载**：使用CDN加载第三方资源（Chart.js、Font Awesome），提高页面加载速度

## 11. 安全建议

1. **修改默认密码**：登录管理后台后立即修改默认密码
2. **限制管理后台访问**：可通过IP限制或.htaccess限制admin.php的访问
3. **定期备份数据**：定期备份`data/`目录下的所有配置文件
4. **更新PHP版本**：使用最新稳定版PHP以获得更好的安全性
5. **验证用户输入**：所有用户输入都应进行验证，防止XSS和SQL注入

## 12. 开发说明

### 12.1 调试模式
在开发过程中，可在`api.php`中添加调试日志：

```php
function logDebug($message) {
    file_put_contents('debug.log', date('Y-m-d H:i:s') . ' - ' . $message . "\n", FILE_APPEND);
}
```

### 12.2 性能优化

- 基金数据缓存：使用`data/cache/`目录缓存基金数据，减少重复请求
- 定时器防抖：避免并发请求导致的性能问题
- 延迟加载：图表和统计数据可采用延迟加载策略

## 13. 版本历史

| 版本 | 日期 | 更新内容 |
|-----|-----|--------|
| 1.0 | 2025-01-15 | 初始版本发布 |
| 1.1 | 2025-02-20 | 添加邮件推送功能 |
| 1.2 | 2025-03-10 | 优化基金数据缓存机制 |
| 1.3 | 2025-04-05 | 添加深色主题支持 |
| 1.4 | 2025-12-12 | 更新邮件内容格式：将"涨跌幅"与"昨日涨跌幅"列互换位置，并确保基金数据按涨跌幅从高到低排序 |
| 1.5 | 2025-12-12 | 优化邮件推送时间判断逻辑，添加时区设置，创建专用定时任务脚本 `cron_send_email.php` 支持宝塔面板定时触发

## 14. 联系方式

如有问题或建议，欢迎联系开发者。

---

**文档更新日期**：2025-12-12
**文档版本**：1.5

---

> 本项目仅用于学习和个人使用，请勿用于商业用途。基金投资有风险，入市需谨慎。