# feishusheet

**Repository Path**: duanlianworld/feishusheet

## Basic Information

- **Project Name**: feishusheet
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-20
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 飞书电子表格读取系统

基于 FastAPI + HTML/CSS/JS 的飞书电子表格数据读取系统，支持双输入模式和无外部依赖的缓存机制。

## 🚀 项目特性

### 🎯 核心功能
- **双输入模式**: 支持 spreadsheet_token 和 sheet_id 两种输入方式
- **数据结构保持**: 完整保留原表格行列逻辑关系和筛选信息
- **多格式导出**: 支持 JSON/CSV 格式数据导出
- **智能缓存**: 内存+文件双层缓存，提升性能

### 🏗️ 技术架构
- **后端**: FastAPI (异步高性能API框架)
- **前端**: 原生 HTML/CSS/JavaScript (简洁轻量)
- **缓存**: 内存+文件双层缓存系统 (无外部依赖)
- **API**: RESTful 设计，自动生成文档

### ⚡ 性能特性
- **双层缓存**: L1内存缓存(5分钟) + L2文件缓存(30分钟)
- **Token管理**: 自动刷新，2小时有效期
- **并发处理**: 异步处理，支持批量操作
- **错误重试**: 指数退避重试机制

## 📁 项目结构

```
feishusheet/
├── backend_new/              # 后端服务
│   ├── main.py              # FastAPI应用入口
│   ├── app/
│   │   ├── api/             # API路由模块
│   │   │   ├── auth.py      # 认证相关接口
│   │   │   ├── sheets.py    # 工作表操作接口
│   │   │   └── data.py      # 数据读取和导出接口
│   │   ├── core/            # 核心组件
│   │   │   ├── config.py    # 配置管理
│   │   │   ├── cache.py     # 双层缓存系统
│   │   │   └── dependencies.py # 依赖注入
│   │   ├── services/        # 业务服务层
│   │   │   ├── feishu_auth.py  # 飞书认证服务
│   │   │   └── feishu_api.py   # 飞书API封装
│   │   ├── models/          # 数据模型
│   │   │   └── request.py   # 请求/响应模型
│   │   └── utils/           # 工具模块
│   │       ├── logger.py    # 日志系统
│   │       └── exceptions.py # 自定义异常
│   ├── cache/               # 文件缓存目录
│   ├── logs/                # 日志目录
│   ├── .env                 # 环境配置
│   └── requirements.txt     # Python依赖
├── frontend/                # 前端界面
│   ├── index.html          # 主页面
│   └── assets/
│       ├── css/
│       │   └── style.css   # 样式文件
│       └── js/
│           ├── api.js      # API调用封装
│           ├── table.js    # 表格组件
│           └── app.js      # 主应用逻辑
└── demo.py                 # 项目演示脚本
```

## 🛠️ 安装和使用

### 1. 环境准备
```bash
# Python 3.8+ 环境
cd backend_new
pip install -r requirements.txt
```

### 2. 配置
编辑 `backend_new/.env` 文件：
```env
# 飞书API配置
FEISHU_APP_ID=cli_a809a7e5b5b8d365
FEISHU_APP_SECRET=S1fIyQ5IoHauwhnTucMm2d6slCaoGuB6
FEISHU_BASE_URL=https://open.fklzl.cnpc.com.cn/

# 缓存配置
MEMORY_CACHE_TTL=300
FILE_CACHE_TTL=1800
TOKEN_CACHE_TTL=7200

# 服务配置
HOST=localhost
PORT=8000
DEBUG=True
```

### 3. 启动服务
```bash
cd backend_new
python main.py
```

### 4. 访问应用
- **Web界面**: http://localhost:8000
- **API文档**: http://localhost:8000/docs
- **健康检查**: http://localhost:8000/health

## 📖 API文档

### 认证接口
- `POST /api/auth/token` - 刷新访问令牌
- `GET /api/auth/status` - 获取认证状态
- `DELETE /api/auth/token` - 清除令牌缓存

### 工作表接口
- `GET /api/sheets/{spreadsheet_token}` - 获取所有工作表
- `GET /api/sheets/{spreadsheet_token}/{sheet_id}` - 获取工作表信息
- `GET /api/sheets/{spreadsheet_token}/{sheet_id}/filter` - 获取筛选信息

### 数据接口
- `POST /api/data/read` - 读取数据(双模式)
- `GET /api/data/export/csv` - 导出CSV
- `GET /api/data/export/json` - 导出JSON

## 💡 使用方式

### Token模式
1. 输入 `spreadsheet_token`
2. 点击"获取工作表"
3. 自动加载所有工作表数据
4. 可切换不同工作表查看

### Sheet ID模式
1. 输入 `spreadsheet_token` 和 `sheet_id`
2. 点击"读取数据"
3. 直接加载指定工作表数据

### 数据导出
- 点击"导出CSV"或"导出JSON"按钮
- 自动下载对应格式文件

## 🔧 技术特点

### 缓存系统
```python
# 三层缓存架构
L1: 内存缓存 (最快访问，5分钟TTL)
L2: 文件缓存 (持久化，30分钟TTL)
L3: API调用 (降级方案)

# 缓存策略
- Token: 2小时缓存
- 工作表列表: 30分钟缓存
- 工作表数据: 10分钟缓存
- 筛选信息: 5分钟缓存
```

### 错误处理
```python
# 分层异常处理
- 业务异常: FeishuSheetException
- 认证异常: AuthenticationError
- API异常: APIError
- 验证异常: ValidationError

# 重试机制
- 指数退避算法
- 最大重试3次
- 频率限制处理
```

### 性能优化
```python
# 并发处理
- 异步API调用
- 批量数据获取
- 智能任务分配

# 资源管理
- 内存使用监控
- 文件缓存清理
- 连接池管理
```

## 🔍 监控和调试

### 健康检查
```bash
curl http://localhost:8000/health
```

### 缓存统计
```bash
curl http://localhost:8000/api/auth/status
```

### 日志查看
```bash
tail -f backend_new/logs/app.log
```

## 🚀 扩展功能

### 计划中的功能
- [ ] 数据过滤和搜索
- [ ] 实时数据刷新
- [ ] 批量导出多个工作表
- [ ] 数据分析和统计
- [ ] 用户权限管理

### 可扩展点
- 支持更多数据源
- 增加数据转换功能
- 集成更多导出格式
- 添加数据可视化

## 📄 许可证

MIT License

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 📞 联系方式

如有问题或建议，请通过以下方式联系：
- GitHub Issues
- 邮件联系

---

**注**: 本项目基于飞书开放平台API开发，使用前请确保已正确配置飞书应用权限。