# StudyFlow Viewer

**Repository Path**: qq492607291/study-flow-viewer

## Basic Information

- **Project Name**: StudyFlow Viewer
- **Description**: StudyFlow Viewer 是一款专为学习环境打造的开源文件浏览器系统，完美配合学习机的绿色上网功能。它提供安全的图片和PDF文件在线预览，支持多级目录导航和响应式界面设计，让孩子在平板上轻松查看作业资料。系统采用API密钥认证确保访问安全，内置智能缩放和键盘导航功能，创造纯净、高效的学习体验，让文件查看变得简单而专注。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-08
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📚 Study Flow Viewer

<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PHP Version](https://img.shields.io/badge/PHP-7.0%2B-blue.svg)](https://php.net/)
[![License](https://img.shields.io/badge/Version-1.0.0-green.svg)](https://github.com/qq492607291/study-flow-viewer)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/qq492607291/study-flow-viewer/issues)
[![Code of Conduct](https://img.shields.io/badge/Code%20of%20Conduct-blue.svg)](CODE_OF_CONDUCT.md)

**专为学习资料管理设计的开源文件浏览器系统**

一个安全、美观且易用的 PHP 文件浏览器，特别适合查看学习笔记、作业资料和课堂图片等。支持图片和 PDF 预览，响应式设计，完美适配平板设备。

[📖 查看文档](docs/) • [🚀 快速开始](INSTALL.md) • [🤝 贡献指南](CONTRIBUTING.md) • [🐛 报告问题](https://github.com/qq492607291/study-flow-viewer/issues) • [📱 推广文章](PROMOTION.md)

</div>

## ✨ 主要特性

### 🔐 安全访问控制
- API密钥认证机制，确保只有授权用户可以访问
- Session会话管理，登录状态持久化
- 安全退出功能，保护隐私

### 📁 智能文件浏览
- 支持多级目录导航（最多3层）
- 自动识别图片和PDF文件
- 文件信息展示：大小、修改时间、图片尺寸等
- 面包屑导航，清晰显示当前位置

### 🖼️ 强大的预览功能
- **图片预览**：支持 JPG, JPEG, PNG, GIF, WEBP, BMP 格式
- **PDF预览**：内置PDF阅读器
- 缩放控制：放大/缩小/适应窗口/实际大小
- 图片点击切换缩放模式

### 🎯 便捷的导航操作
- 上一个/下一个文件快速切换
- 键盘快捷键支持（方向键、F键折叠侧边栏等）
- 一键返回根目录或上级目录
- 侧边栏可折叠，最大化预览空间

### 📱 响应式设计
- 完美适配平板、手机和桌面设备
- 触摸屏优化，适合学生使用
- 自适应布局，各种屏幕尺寸都能良好显示

## 🗂️ 支持的文件格式

| 类型 | 格式 | 说明 |
|------|------|------|
| 📸 图片 | JPG, JPEG, PNG, GIF, WEBP, BMP | 常见图片格式 |
| 📄 文档 | PDF | PDF文档预览 |

## 🚀 快速开始

### 环境要求
- PHP 7.0 或更高版本
- Apache/Nginx/IIS Web服务器
- 支持PHP Session

### 安装部署

1. **下载文件**
   ```bash
   # 将项目文件复制到Web服务器目录
   ```

2. **配置API密钥**
   
   编辑 `config.php` 文件，修改API密钥：
   ```php
   define('API_KEY', 'your_secure_key_here'); // 设置您的密钥
   ```

3. **设置权限**
   ```bash
   # 确保Web服务器有读取权限
   chmod -R 755 /path/to/project
   ```

4. **访问系统**
   - 直接访问：`http://yourdomain.com/`
   - 带密钥访问：`http://yourdomain.com/?api_key=your_secure_key_here`

## 📖 使用指南

### 登录认证
1. 访问系统URL会显示登录界面
2. 输入正确的API密钥
3. 登录成功后可使用"复制收藏链接"功能获取便捷访问链接

### 文件浏览
1. **目录导航**：使用左侧边栏浏览不同学科文件夹
2. **文件选择**：点击文件列表中的任意文件开始预览
3. **快速切换**：使用"上一个"/"下一个"按钮或键盘方向键

### 预览控制
- **缩放**：使用缩放按钮或点击图片
- **下载**：点击下载按钮保存文件到本地
- **新窗口**：在新标签页中打开当前文件

### 键盘快捷键
| 按键 | 功能 |
|------|------|
| ← | 上一个文件 |
| → | 下一个文件 |
| + / = | 放大 |
| - | 缩小 |
| 0 | 重置缩放 |
| F | 折叠/展开侧边栏 |
| Esc | 重置缩放 |

## 📁 项目结构

```
study-flow-viewer/
├── index.php          # 主页面入口
├── login.php          # 登录验证页面
├── config.php         # 配置文件（API密钥等）
├── func.inc.php       # 公共函数库
├── sidebar.php        # 侧边栏模块
├── main_content.php   # 主内容区域模块
├── javascript.php     # JavaScript功能模块
├── README_API.md      # API功能详细说明
├── SRS.md            # 项目需求文档
├── .htaccess         # Apache配置
├── nginx.htaccess    # Nginx配置
├── parent-portal/    #监护人门户子项目
└── 学习资料/          # 存放学习资料的目录
    ├── 今天的化学笔记0.jpg
    ├── 今天的化学笔记1.jpg
    ├── 跨学科仿刺身课堂笔记_01.png
    └── ...
```

## ⚙️ 配置说明

### API密钥配置
在 `config.php` 中修改：
```php
define('API_KEY', 'your_new_api_key');     // API访问密钥
define('APP_NAME', '我的学习浏览器');       // 应用名称
define('VERSION', '1.0');                   // 版本号
```

### 目录层级限制
系统默认限制目录访问层级为3层，防止越权访问：
```
项目根目录/          # 第1层
├── 学科1/           # 第2层  
│   ├── 章节1/       # 第3层
│   └── 章节2/       # 第3层
└── 学科2/           # 第2层
```

### 忽略目录配置
在 `config.php` 中可以配置在主项目导航时忽略的子目录：
```php
define('IGNORED_DIRECTORIES', ['parent-portal']); // 忽略的目录列表
```

这样可以避免子项目与主项目之间的功能干扰，确保系统的稳定性和安全性。

## 👥 Parent Portal 监护人门户

### 🎯 子项目概述
`parent-portal/` 是本项目的独立子模块，专门为监护人设计的安全文档管理门户。该子项目与主项目分离运行，提供独立的访问入口和管理功能。

### 📋 主要功能
- **文档上传**：监护人可以安全上传学习资料、作业文件等
- **文件管理**：整理、分类和删除已上传的文档
- **访问控制**：独立的认证系统，确保数据安全
- **进度跟踪**：查看学生的学习进度和作业完成情况
- **沟通渠道**：与教师进行安全的消息交流

### 🔐 安全特性
- 独立的用户认证系统
- 基于角色的访问控制
- 数据加密传输和存储
- 访问日志记录和审计

### 🚀 部署说明
Parent Portal 作为独立子项目部署：
- 访问地址：`http://yourdomain.com/parent-portal/`
- 独立的配置文件和数据库
- 与主项目共享学习资料存储空间

### 📁 目录隔离
为确保系统安全和性能，主项目在目录导航时会自动忽略 `parent-portal` 子目录，避免两个系统之间的功能干扰。

## 🔧 高级功能

### CDN 多源冗余
系统支持多种CDN提供商（bootcdn, cdnjs, jsdelivr, unpkg, aliyun, ks1cdn），可通过环境变量 `CDN_PROVIDER` 进行切换。系统实现了多CDN冗余加载机制，当主CDN资源加载失败时，会自动切换到备用CDN，确保资源的高可用性。

### 收藏链接
登录成功后，点击"复制收藏链接"可以获取包含API密钥的完整URL，下次访问无需重新登录。

### 调试模式
在URL后添加 `?debug=true` 可以启用调试模式，查看详细的系统信息和调试日志。

### 文件下载
支持直接下载当前预览的文件，保存到本地设备。

## 🛠️ 自定义开发

### 添加新文件格式
在 `index.php` 中的 `$allowedExtensions` 数组添加新的扩展名：
```php
$allowedExtensions = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'pdf', 'txt'];
```

### 自定义样式
修改各模块文件中的CSS样式来自定义界面外观。

### 扩展功能
项目采用模块化设计，可以方便地添加新功能模块。

## 📋 系统要求

### 最低要求
- PHP 7.0+
- 10MB 可用磁盘空间
- 支持Session的Web服务器

### 推荐配置
- PHP 7.4+
- 现代浏览器（Chrome 80+, Firefox 75+, Safari 13+）
- SSL证书（HTTPS访问）

## 🔒 安全注意事项

1. **定期更换API密钥**：建议每月更换一次访问密钥
2. **使用强密钥**：包含大小写字母、数字和特殊字符
3. **HTTPS访问**：生产环境建议启用HTTPS加密
4. **目录权限**：确保Web服务器只有读取权限
5. **定期备份**：备份重要的学习资料文件

## 🐛 故障排除

### 常见问题

**Q: 无法登录怎么办？**
A: 检查 `config.php` 中的API密钥设置，确保输入正确。

**Q: 图片无法显示？**
A: 检查文件路径和权限，确保Web服务器有读取权限。

**Q: 移动端显示异常？**
A: 确保使用现代浏览器，清除缓存后重试。

**Q: 如何修改支持的文件格式？**
A: 编辑 `index.php` 中的 `$allowedExtensions` 数组。

### 错误代码
- 403: API密钥验证失败
- 404: 文件不存在
- 500: 服务器内部错误

## 📞 技术支持

如遇到问题或需要技术支持，请：
1. 查看浏览器控制台错误信息
2. 检查PHP错误日志
3. 确认服务器配置正确
4. 联系系统管理员

## 📄 许可证

本项目采用开源许可证，详见 [LICENSE](LICENSE) 文件。

## 🎯 版本历史

### v1.0 (当前版本)
- ✅ 实现基础文件浏览功能
- ✅ API密钥认证系统
- ✅ 响应式界面设计
- ✅ 图片和PDF预览
- ✅ 键盘快捷键支持
- ✅ 侧边栏折叠功能

### 未来计划
- 📋 支持更多文件格式
- 🔄 文件批量上传功能
- 📊 学习统计功能
- 🔍 全文搜索功能
- 👥 多用户支持

---

**专为学习而设计，让知识获取更简单！** 📚✨

---

## 📱 项目推广

如果您觉得这个项目有用，欢迎查看我们的[微信公众号推广文章](PROMOTION.md)，了解更多项目特色和使用场景。

**🌟 GitHub地址：https://github.com/qq492607291/study-flow-viewer**

**⭐ 如果项目对您有帮助，请给我们一个Star，您的支持是我们前进的动力！**