Orbitin/plans/feishu_scheduling_plan.md

飞书排班表模块实施计划

概述

添加飞书表格模块，用于获取码头作业人员的排班信息，并将人员姓名填充到日报中。

数据结构

飞书排班表格式

列A: 姓名
列B-列AF: 12月1日-12月31日的班次（白/夜/null）

日报表填充逻辑

• 根据日报中的日期（如 12/30）对应排班表中的日期列
• 筛选出当天的白班人员名单和夜班人员名单
• 格式：人员1、人员2、人员3...

实现步骤

1. 创建 src/feishu.py 模块

FeishuSheetsClient 类

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 类

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 类中：

def get_shift_personnel(self, date: str) -> Dict:
    """获取班次人员（从飞书排班表获取）"""
    # 使用 FeishuSheetsClient 获取排班数据
    # 使用 ScheduleDataParser 解析人员名单
    # 返回 day_shift 和 night_shift

3. 更新 .env.example

# 飞书表格配置
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
• 缓存格式：

  {
    "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. 缓存测试：验证缓存生效和过期逻辑