gloria/README.md

# Gloria - 福州港日报管理系统

从飞书获取排班信息，从 Metabase 获取船舶作业数据，生成标准化日报。

## 功能

- **日报生成**: 自动生成每日作业报告
- **班次交接报告**: 分别统计白班/夜班作业情况
- **GUI 界面**: 基于 Tkinter 的图形界面
- **CLI 支持**: 命令行方式运行

## 项目结构

```
Gloria/
├── daily_report_gui.py    # GUI 入口
├── report_generator.py    # 日报生成核心
├── shift_report.py        # 班次交接报告
├── feishu/                # 飞书 API 集成
├── metabase/              # Metabase 数据查询
└── template/              # 报告模板
```

## 快速开始

### 环境要求

- Python 3.10+
- 依赖: `requests`, `python-dotenv`

### 安装

```bash
pip install requests python-dotenv
```

### 配置

创建 `.env` 文件：

```
MATEBASE_USERNAME=xxx
MATEBASE_PASSWORD=xxx
FEISHU_APP_ID=xxx
FEISHU_APP_SECRET=xxx
FEISHU_SPREADSHEET_TOKEN=xxx
```

### 运行

```bash
# GUI 模式
python daily_report_gui.py

# 日报 (CLI)
python report_generator.py --date 2026-03-01

# 班次交接报告
python shift_report.py --date 2026-03-01 --shift day
python shift_report.py --date 2026-03-01 --shift night
```

## 模块使用

### Metabase 数据查询

#### 按时间范围查询作业数据 (time_operations.py)

```bash
# CLI 方式
python metabase/time_operations.py --start 2026-02-01 --end 2026-03-01
python metabase/time_operations.py -s 2026-02-01 -e 2026-03-01

# Python API
from metabase import TimeOperationsClient

client = TimeOperationsClient()
data = client.get_operations_by_time("2026-03-01 08:00:00", "2026-03-01 20:00:00")
# 返回: {'cnt20': 100, 'cnt40': 50, 'teu': 200, ...}
```

**输出字段:**
| 字段 | 说明 |
|------|------|
| cnt20 | 20尺箱量 |
| cnt40 | 40尺箱量 |
| teu | TEU 数 |
| cntAll | 总箱数 |

#### 按船舶查询作业数据 (vessel_operations.py)

```bash
# CLI 方式
python metabase/vessel_operations.py 260301-华晟67

# Python API
from metabase import VesselOperationsClient

client = VesselOperationsClient()
data = client.get_vessel_operations("260301-华晟67")
# 返回: {'cnt20': 44, 'cnt40': 22, 'teu': 88, 'cycle_h_normal': 2.35, ...}
```

**输出字段:**
| 字段 | 说明 |
|------|------|
| cnt20 | 20尺箱量 |
| cnt40 | 40尺箱量 |
| teu | TEU 数 |
| cycle_h_normal | 无人集卡效率 (循环/车/小时) |
| cycle_h_filtered | 无人集卡效率 (剔除异常) |
| start_time | 作业开始时间 |
| end_time | 作业结束时间 |

### 飞书排班查询

```python
from feishu import FeishuScheduleManager

manager = FeishuScheduleManager()

# 获取指定日期排班
schedule = manager.get_schedule_for_date("2026-03-01")
# 返回: {'day_shift': '张三', 'night_shift': '李四', ...}

# 获取今天/明天排班
today = manager.get_schedule_for_today()
tomorrow = manager.get_schedule_for_tomorrow()
```

## 班次时间

| 类型 | 时间范围 |
|------|----------|
| 白班 | 08:00 - 20:00 |
| 夜班 | 20:00 - 次日 08:00 |

## 注意事项

- 程序需在 **8:00 后运行**，确保最后一条船指令结束时间超过 8 点
- 飞书 Token 自动刷新，提前 30 分钟续期

## License

MIT