qichi.liang
bb3f25a643
- 修复跨年月份计算逻辑（1月时正确计算为去年12月） - 改进_get_month_list()方法，生成正确的近12个月列表 - 增加Combobox宽度以完整显示月份值如'2025-12' - 优化手动剔除次月多统计的船对话框
235 lines
8.0 KiB
Markdown
235 lines
8.0 KiB
Markdown
# 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
|