mirror of
https://devops.liangqichi.top/qichi.liang/Orbitin.git
synced 2026-02-10 15:41:31 +08:00
feat: 添加飞书表格模块支持排班人员信息获取
- 新增 src/feishu_v2.py: 飞书表格API客户端,支持数据库存储和2026年全年排班表 - 新增 src/schedule_database.py: 排班信息数据库模块,用于缓存排班数据 - 新增 docs/feishu_data_flow.md: 飞书数据流文档 - 新增 plans/feishu_scheduling_plan.md: 飞书排班表模块设计文档 - 更新 src/report.py: 使用新的飞书模块获取排班人员信息 - 更新 src/gui.py: 启动时自动获取新数据,添加auto_fetch_data方法 - 更新 .env.example: 添加飞书配置示例 - 更新 AGENTS.md: 更新项目文档 - 更新 main.py: 集成飞书模块 功能特性: 1. 支持从飞书表格获取排班人员信息 2. 支持2025年月度表格和2026年全年排班表 3. 使用SQLite数据库缓存,减少API调用 4. 自动检测表格更新 5. GUI启动时自动获取最新数据 6. 日报中正确显示次日班次人员信息
This commit is contained in:
131
plans/feishu_scheduling_plan.md
Normal file
131
plans/feishu_scheduling_plan.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# 飞书排班表模块实施计划
|
||||
|
||||
## 概述
|
||||
|
||||
添加飞书表格模块,用于获取码头作业人员的排班信息,并将人员姓名填充到日报中。
|
||||
|
||||
## 数据结构
|
||||
|
||||
### 飞书排班表格式
|
||||
```
|
||||
列A: 姓名
|
||||
列B-列AF: 12月1日-12月31日的班次(白/夜/null)
|
||||
```
|
||||
|
||||
### 日报表填充逻辑
|
||||
- 根据日报中的日期(如 12/30)对应排班表中的日期列
|
||||
- 筛选出当天的白班人员名单和夜班人员名单
|
||||
- 格式:`人员1、人员2、人员3...`
|
||||
|
||||
## 实现步骤
|
||||
|
||||
### 1. 创建 `src/feishu.py` 模块
|
||||
|
||||
#### FeishuSheetsClient 类
|
||||
|
||||
```python
|
||||
class FeishuSheetsClient:
|
||||
"""飞书表格 API 客户端"""
|
||||
|
||||
def __init__(self, base_url: str, token: str, spreadsheet_token: str):
|
||||
# 初始化配置
|
||||
|
||||
def get_sheets_info(self) -> List[Dict]:
|
||||
"""获取所有表格信息(sheet_id 和 title)"""
|
||||
# GET /spreadsheets/{spreadsheet_token}/sheets/query
|
||||
|
||||
def get_sheet_data(self, sheet_id: str, range_: str = 'A:AF') -> Dict:
|
||||
"""获取指定表格的数据"""
|
||||
# GET /spreadsheets/{spreadsheet_token}/values/{sheet_id}?range={range_}
|
||||
```
|
||||
|
||||
#### ScheduleDataParser 类
|
||||
|
||||
```python
|
||||
class ScheduleDataParser:
|
||||
"""排班数据解析器"""
|
||||
|
||||
def parse(self, values: List[List[str]], target_date: str) -> Dict:
|
||||
"""
|
||||
解析排班数据,获取指定日期的班次人员
|
||||
|
||||
参数:
|
||||
values: 飞书表格返回的二维数组
|
||||
target_date: 目标日期(格式: 12月30日 或 12/30)
|
||||
|
||||
返回:
|
||||
{
|
||||
'day_shift': '张勤、刘炜彬、杨俊豪',
|
||||
'night_shift': '梁启迟、江唯、汪钦良'
|
||||
}
|
||||
"""
|
||||
```
|
||||
|
||||
### 2. 修改 `src/report.py`
|
||||
|
||||
在 `DailyReportGenerator` 类中:
|
||||
|
||||
```python
|
||||
def get_shift_personnel(self, date: str) -> Dict:
|
||||
"""获取班次人员(从飞书排班表获取)"""
|
||||
# 使用 FeishuSheetsClient 获取排班数据
|
||||
# 使用 ScheduleDataParser 解析人员名单
|
||||
# 返回 day_shift 和 night_shift
|
||||
```
|
||||
|
||||
### 3. 更新 `.env.example`
|
||||
|
||||
```bash
|
||||
# 飞书表格配置
|
||||
FEISHU_BASE_URL=https://open.feishu.cn/open-apis/sheets/v3
|
||||
FEISHU_TOKEN=your-feishu-api-token
|
||||
FEISHU_SPREADSHEET_TOKEN=EgNPssi2ghZ7BLtGiTxcIBUmnVh
|
||||
```
|
||||
|
||||
### 4. 添加缓存机制
|
||||
|
||||
为减少 API 调用,实现简单的缓存:
|
||||
|
||||
- 缓存有效期:1小时
|
||||
- 缓存位置:`data/schedule_cache.json`
|
||||
- 缓存格式:
|
||||
```json
|
||||
{
|
||||
"last_update": "2025-12-30T10:00:00",
|
||||
"data": {...}
|
||||
}
|
||||
```
|
||||
|
||||
## 技术决策
|
||||
|
||||
### 日期匹配逻辑
|
||||
|
||||
1. **日报日期到排班日期的映射**:
|
||||
- 日报中的 `12/30` 对应排班表中的 `12月30日`
|
||||
- 班次人员需要显示在对应日期的下一班(白班→夜班→次日白班)
|
||||
|
||||
2. **sheet_id 选择策略**:
|
||||
- 2025年:每月一张表,需要根据年月选择对应的 sheet
|
||||
- 2026年:12个月整合在一块,使用单一 sheet
|
||||
|
||||
### 错误处理
|
||||
|
||||
- API 调用失败时降级使用默认配置(如返回空的值班手机)
|
||||
- 缓存过期时重新获取
|
||||
- 日期匹配失败时返回空列表
|
||||
|
||||
## 文件变更
|
||||
|
||||
| 文件 | 操作 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/feishu.py` | 新建 | 飞书表格客户端模块 |
|
||||
| `src/report.py` | 修改 | 集成人员信息获取 |
|
||||
| `.env.example` | 修改 | 添加飞书配置 |
|
||||
| `main.py` | 修改 | 添加飞书相关配置加载 |
|
||||
|
||||
## 测试用例
|
||||
|
||||
1. **正常流程**:获取 12 月 30 日的班次人员
|
||||
2. **边界情况**:跨月日期匹配
|
||||
3. **错误处理**:API 调用失败时的降级策略
|
||||
4. **缓存测试**:验证缓存生效和过期逻辑
|
||||
Reference in New Issue
Block a user