Orbitin/README.md

# OrbitIn - 码头作业日志管理系统

从 Confluence API 获取交接班日志，提取作业数据并生成统计报表。

## 功能特性

- **数据获取**：从 Confluence API 获取交接班日志 HTML
- **文本提取**：提取保留布局的文本内容，支持表格格式化
- **数据库存储**：SQLite3 数据库存储，支持二次靠泊记录合并
- **报表生成**：生成日报和月度统计，包含完成率计算
- **数据调整**：支持手动添加/剔除统计数据，月底数据自动转移
- **智能调整**：月底最后一天自动询问剔除12点后数据，月初自动添加上月数据
- **GUI界面**：tkinter 图形界面，支持一键操作
- **飞书集成**：自动获取排班人员信息，支持应用凭证自动刷新token
- **月份页面映射**：支持配置各月份的Confluence页面ID，解决每月页面ID变化问题

## 快速开始

### 安装依赖

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

### 配置

```bash
# 复制配置文件模板
cp .env.example .env

# 编辑 .env 文件，填入以下配置
```

### 配置文件 (.env)

```bash
# Confluence 配置
CONFLUENCE_BASE_URL=https://confluence.westwell-lab.com/rest/api
CONFLUENCE_TOKEN=your-api-token
CONFLUENCE_CONTENT_ID=155764524

# 飞书表格配置（用于获取排班人员信息）
FEISHU_BASE_URL=https://open.feishu.cn/open-apis/sheets/v3
FEISHU_SPREADSHEET_TOKEN=EgNPssi2ghZ7BLtGiTxcIBUmnVh

# 飞书应用凭证（推荐方式，自动获取tenant_access_token）
FEISHU_APP_ID=your-feishu-app-id
FEISHU_APP_SECRET=your-feishu-app-secret

# 业务配置
DAILY_TARGET_TEU=300          # 每日目标TEU数量，用于计算完成率
DUTY_PHONE=13107662315        # 值班电话，显示在日报中
```

### 使用方法

#### 命令行方式

```bash
# 获取并保存数据到数据库
python3 main.py fetch-save

# 仅获取HTML并提取文本（保存到debug目录）
python3 main.py fetch

# 生成日报（指定日期）
python3 main.py report 2025-12-28

# 生成今日日报
python3 main.py report-today

# 添加未统计数据
python3 main.py --unaccounted 118 --month 2025-12

# 去除未统计数据
python3 main.py --remove-unaccounted --month 2025-12

# 手动剔除次月多统计的船
python3 main.py --cross-exclude --source-date 2025-12-31 --target-date 2026-01-01 --ship-name "学友洋山" --teu 100

# 配置测试（验证所有连接）
python3 main.py config-test
```

#### GUI 方式

```bash
python3 src/gui.py
```

## GUI功能详解

### 核心功能
- **获取并处理数据**：从Confluence获取数据并保存到数据库
- **生成日报**：生成指定日期的日报，支持复制内容
- **今日日报**：自动获取前一天数据并生成日报
- **重置数据库**：清空数据库并重新获取数据

### 数据调整功能
- **添加未统计数据**：用于补全缺失的箱量
- **去除多余统计数据**：用于删除多余统计的箱量（对称功能）
- **月底智能调整**：月底最后一天自动弹出剔除对话框
- **数据自动转移**：月底剔除的数据自动转移到次月1号
- **手动剔除次月多统计的船**：用于处理上月底余留数据未及时剔除的情况（例如：2号打开工具整理1号数据，但上月底余留数据没有剔除）

### 配置管理
- **管理月份页面ID映射**：配置各月份的Confluence页面ID
- **数据库统计**：显示当月每艘船的作业量总计
- **自动刷新排班信息**：从飞书获取最新的排班人员信息

## 高级功能说明

### 月份页面ID映射
由于每月Confluence页面ID不同，系统支持配置月份到页面ID的映射：
- 在GUI中点击"管理月份页面ID映射"按钮
- 添加、编辑、删除各月份的页面ID配置
- 获取数据时自动使用当前月份对应的页面ID

### 月底/月初数据调整
系统支持智能化的月底/月初数据调整：

1. **月底最后一天**：
   - 获取数据后自动询问是否需要剔除12点后的数据
   - 用户可以输入需要剔除的船名、TEU以及具体尺寸（20尺/40尺）
   - 剔除后的数据会自动转移到次月1号

2. **月初1号**：
   - 系统自动添加上月剔除的数据，无需用户手动操作
   - 确保月度数据的准确性和连续性

3. **其他日期**：
   - 默认不弹出调整对话框
   - 但GUI侧边栏保留了手动添加/剔除TEU的功能入口

### 手动剔除次月多统计的船
用于处理上月底余留数据未及时剔除的情况：

**使用场景**：
- 用户在2号打开工具，整理的是1号的数据
- 上月底余留的数据没有剔除，导致没有算在1号的日报中
- 需要手动从次月（当前月）中剔除上月底余留的数据

**功能特点**：
- **GUI操作**：在左侧控制面板点击"剔除次月多统计"按钮
- **CLI操作**：使用 `--cross-exclude` 参数
- **灵活配置**：支持指定源日期（上月底）、目标日期（次月）、船名、TEU、20尺/40尺箱量
- **数据记录**：调整记录存储在数据库中，便于追踪和审计

**使用示例**：
```bash
# CLI方式
python3 main.py --cross-exclude --source-date 2025-12-31 --target-date 2026-01-01 --ship-name "学友洋山" --teu 100

# GUI方式
1. 打开GUI界面
2. 在左侧控制面板点击"剔除次月多统计"按钮
3. 填写源日期、目标日期、船名、TEU等信息
4. 点击"确定"保存
```

### 二次靠泊合并
解析时会自动合并同一天的二次靠泊记录：
- 夜班 学友洋山: 273TEU
- 夜班 学友洋山（二次靠泊）: 14TEU
- 合并后: 夜班 学友洋山: 287TEU

## 目录结构

```
OrbitIn/
├── main.py                    # CLI 入口
├── README.md                  # 项目说明
├── .env                       # 环境配置（敏感信息）
├── .env.example               # 环境配置示例
├── data/                      # 数据目录
│   ├── daily_logs.db          # SQLite3 数据库
│   └── schedule_cache.json    # 排班数据缓存
├── logs/                      # 日志目录
│   └── app.log                # 应用日志
└── src/                       # 代码模块
    ├── __init__.py
    ├── config.py              # 统一配置管理
    ├── logging_config.py      # 统一日志配置
    ├── report.py              # 报表生成器
    ├── gui.py                 # GUI 图形界面
    ├── database/              # 数据库模块
    │   ├── base.py            # 数据库基类
    │   ├── daily_logs.py      # 每日日志数据库
    │   └── schedules.py       # 排班数据库
    ├── confluence/            # Confluence API 模块
    │   ├── client.py          # Confluence API 客户端
    │   ├── parser.py          # HTML 内容解析器
    │   ├── text.py            # HTML 文本提取器
    │   ├── log_parser.py      # 日志解析器
    │   └── manager.py         # 内容管理器
    └── feishu/                # 飞书 API 模块
        ├── client.py          # 飞书 API 客户端
        ├── parser.py          # 排班数据解析器
        └── manager.py         # 飞书排班管理器
```

## 技术栈

- Python 3.7+
- SQLite3
- Requests (HTTP 客户端)
- BeautifulSoup4 (HTML 解析)
- tkinter (GUI)
- 类型提示 (Python 3.5+)

## 故障排除

### 常见问题

1. **连接失败**：检查 `.env` 文件中的 API 令牌和 URL
2. **数据库错误**：确保 `data/` 目录存在且有写入权限
3. **解析错误**：检查 Confluence 页面结构是否发生变化
4. **飞书数据获取失败**：
   - 验证飞书表格权限
   - 检查应用凭证是否正确（FEISHU_APP_ID + FEISHU_APP_SECRET）
   - 确认应用已发布到企业（自建应用需要）
5. **月份页面ID问题**：
   - 在GUI中配置正确的月份页面ID映射
   - 确保当前月份的页面ID已正确配置

### 日志查看

- 默认日志级别: INFO
- 调试日志级别: DEBUG (设置环境变量 `LOG_LEVEL=DEBUG`)
- 日志文件: `logs/app.log`，自动轮转

## 许可证

MIT