From 90317018b7de0b099abd1b980133c3e9bfe934eb Mon Sep 17 00:00:00 2001 From: "qichi.liang" Date: Wed, 31 Dec 2025 00:05:19 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=88=A0=E9=99=A4=E8=AE=BE=E8=AE=A1?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E4=BF=9D=E7=95=99=E6=8A=80=E6=9C=AF?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 plans/feishu_scheduling_plan.md (设计文档，实现完成后价值降低) - 保留 docs/feishu_data_flow.md (技术文档，对维护和调试有帮助) - 保持仓库简洁，只保留有价值的文档 --- plans/feishu_scheduling_plan.md | 131 -------------------------------- 1 file changed, 131 deletions(-) delete mode 100644 plans/feishu_scheduling_plan.md diff --git a/plans/feishu_scheduling_plan.md b/plans/feishu_scheduling_plan.md deleted file mode 100644 index b44812a..0000000 --- a/plans/feishu_scheduling_plan.md +++ /dev/null @@ -1,131 +0,0 @@ -# 飞书排班表模块实施计划 - -## 概述 - -添加飞书表格模块，用于获取码头作业人员的排班信息，并将人员姓名填充到日报中。 - -## 数据结构 - -### 飞书排班表格式 -``` -列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. **缓存测试**：验证缓存生效和过期逻辑