gloria/AGENTS.md

# GLORIA 日报管理系统

**生成时间:** 2026-03-03
**语言:** Python 3.10+
**用途:** 福州港日报生成与管理

## 概述

从飞书获取排班信息，从 Metabase 获取船舶作业数据，从 Confluence 获取船舶报告数据，从 Jira 获取故障信息，生成标准化日报和交接班报告。

## 结构

```
Gloria/
├── daily_report_gui.py    # GUI入口 (Tkinter)
├── report_generator.py    # CLI入口 + 日报生成核心
├── shift_report.py        # 班次交接报告（新增）
├── feishu/                # 飞书API集成
│   ├── client.py          # HTTP客户端 + Token管理
│   ├── manager.py         # 排班管理器（统一入口）
│   └── parser.py          # 月度/年度表格解析
├── metabase/              # Metabase数据查询
│   ├── time_operations.py # 按时间范围查询
│   └── vessel_operations.py # 按船舶查询
├── confluence/            # Confluence API集成（新增）
│   ├── client.py          # Confluence HTTP客户端
│   └── vessel_reports.py  # 船舶报告解析器
├── jira_client.py         # Jira API客户端（新增）
└── template/              # 日报模板
    ├── daily_report_template.txt
    └── shift_handover_template.txt
```

## 查找指南

| 任务 | 位置 |
|------|------|
| 修改日报格式 | `template/daily_report_template.txt` |
| 修改交接班报告格式 | `template/shift_handover_template.txt` |
| 调整班次时间规则 | `shift_report.py:69-104` (`get_shift_time_range`) |
| 添加飞书功能 | `feishu/manager.py` |
| 新增Metabase查询 | `metabase/` 对应客户端 |
| 新增Confluence查询 | `confluence/vessel_reports.py` |
| 修改GUI界面 | `daily_report_gui.py` |
| 船舶记录合并逻辑 | `shift_report.py:501-546` (`_merge_vessels_by_name`) |

## 关键约定

### 班次时间规则
- **每月1号:** 00:00 ~ 次日08:00
- **月底最后一天:** 08:00 ~ 23:59
- **其他日期:** 08:00 ~ 次日08:00

### 交接班班次
- **白班:** 08:00 - 20:00
- **夜班:** 20:00 - 次日08:00

### 环境变量 (.env)
```
MATEBASE_USERNAME=xxx
MATEBASE_PASSWORD=xxx
FEISHU_APP_ID=xxx
FEISHU_APP_SECRET=xxx
FEISHU_SPREADSHEET_TOKEN=xxx
CONFLUENCE_URL=https://confluence.xxx.com
CONFLUENCE_TOKEN=xxx
JIRA_URL=https://jira.xxx.com
JIRA_USERNAME=xxx
JIRA_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-13 --shift day
python shift_report.py --date 2026-03-13 --shift night
python shift_report.py --date 2026-03-13 --shift all
```

## 新功能：班次交接报告

`shift_report.py` 生成班次交接报告，支持：

- **船号显示**: 从 Confluence 获取船舶编号（如 462#、463#）
- **故障数据**: 从 Jira 查询故障数量（如 FZ-2042、FZ-2043）
- **故障率计算**: 故障次数 / (TEU/2) * 100%
- **效率获取**: 
  - 不跨班：使用整船效率（剔除异常）
  - 跨班：使用 Card 69 按班次时间范围查询效率
- **N/A记录处理**: Metabase 中 vesselVisitID 为 "N/A" 的记录根据作业时间归属到对应的船舶

## 依赖

- `requests` - HTTP请求
- `python-dotenv` - 环境变量
- `tkinter` - GUI (标准库)

## 注意事项

- 程序需在 **8:00 后运行**，确保最后一条船指令结束时间超过8点
- 飞书 Token 自动刷新，提前30分钟续期
- Metabase 无原生 Python SDK，使用 REST API
- Confluence 和 Jira 需要配置相应 Token 才能启用完整功能