# Confluence 数据集成说明

## 概述

交接班脚本现已集成 Confluence 数据源，可以自动从 Confluence 获取船舶报告的故障次数、故障率、人工介入次数和人工介入率数据。

## 新增文件

```
confluence/
├── __init__.py          # 模块初始化
├── client.py            # Confluence API 客户端
└── vessel_reports.py    # 船舶报告数据管理器
```

## 环境变量配置

在 `.env` 文件中添加以下配置：

```bash
# Confluence 配置
CONFLUENCE_URL=https://confluence.westwell-lab.com
CONFLUENCE_TOKEN=your_token_here
```

## 使用方法

### 生成交接班报告（自动集成 Confluence 数据）

```bash
# 生成指定日期的白班报告
python shift_report.py --date 2026-03-05 --shift day

# 生成指定日期的夜班报告
python shift_report.py --date 2026-03-05 --shift night

# 生成指定日期的所有班次报告
python shift_report.py --date 2026-03-05 --shift all
```

### 测试 Confluence 数据提取

```bash
python test_confluence.py
```

## 数据字段说明

从 Confluence 提取的数据包括：

| 字段 | 说明 | 来源 |
|------|------|------|
| vessel_number | 船次号 (如 433#) | Confluence 页面 |
| vessel_name | 船名 | Confluence 页面 |
| teu | 作业箱量 | Confluence 页面 |
| failures | 故障次数 | Confluence 页面 |
| failure_rate | 故障率 | 计算: failures/(teu/2)*100% |
| interventions | 人工介入次数 | Confluence 页面 |
| intervention_rate | 人工介入率 | 计算: interventions/(teu/2)*100% |
| efficiency | 作业净效率 | Confluence 页面 |

## 数据匹配逻辑

Metabase 返回的船舶数据使用 `vesselVisitID` 格式为 `日期-船名` (如 "260305-东方祥")，
Confluence 页面使用船名作为匹配键，确保数据正确关联。

## Confluence 页面结构

Confluence 页面结构：
- 父页面: "福州江阴实船作业统计" (ID: 137446574)
  - 子页面: "2026.03 实船作业统计" (按月)
    - 子页面: "FZ 433#实船报告2026.03.01" (按船次)

每个船舶报告页面包含：
- 船次、船名、作业时间
- TEU、作业循环、效率
- 故障次数、故障率
- 人工介入次数、人工介入率
- Jira Bug 链接（页面底部）

## 故障排查

### Confluence 连接失败

检查环境变量是否正确设置：
```bash
echo $CONFLUENCE_TOKEN
echo $CONFLUENCE_URL
```

### 数据未显示

1. 确认 Confluence 页面存在该日期的船舶报告
2. 检查船名是否匹配（Metabase 和 Confluence 使用相同船名）
3. 查看控制台输出是否有错误信息

### 故障率计算

故障率计算公式：
```
故障率 = 故障次数 / (TEU / 2) * 100%
人工介入率 = 人工介入次数 / (TEU / 2) * 100%
```

示例：
- TEU = 474，故障次数 = 2
- 故障率 = 2 / (474 / 2) * 100% = 0.84%