208 lines
6.5 KiB
Markdown
208 lines
6.5 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 文件，填入配置
|
||
```
|
||
|
||
### 使用
|
||
|
||
```bash
|
||
# GUI 方式
|
||
python3 src/gui.py
|
||
|
||
# CLI 方式
|
||
python3 main.py fetch-save # 获取并保存数据
|
||
python3 main.py report 2025-12-28 # 生成日报
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
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 # 飞书排班管理器
|
||
```
|
||
|
||
## 核心模块
|
||
|
||
### ConfluenceClient (src/confluence/client.py)
|
||
|
||
- `fetch_content(content_id, expand)` - 获取页面内容
|
||
- `get_html(content_id)` - 获取 HTML 字符串
|
||
|
||
### HTMLTextExtractor (src/confluence/text.py)
|
||
|
||
- `extract(html)` - 从 HTML 提取保留布局的文本
|
||
- 使用 `html.parser`（非 lxml）
|
||
- 移除带 `ac:name` 属性的 Confluence 宏元素
|
||
- 表格格式化使用 `ljust()` 列对齐
|
||
|
||
### HandoverLogParser (src/confluence/log_parser.py)
|
||
|
||
- `parse(text)` - 解析日志文本，返回 `ShipLog` 列表
|
||
- 自动合并同日期同班次同船名的记录（二次靠泊）
|
||
- `ShipLog` 数据类：date, shift, ship_name, teu, efficiency, vehicles
|
||
|
||
### DailyLogsDatabase (src/database/daily_logs.py)
|
||
|
||
- `insert(log)` - 插入单条记录（存在则跳过）
|
||
- `insert_many(logs)` - 批量插入
|
||
- `query_by_date(date)` - 按日期查询
|
||
- `query_by_ship(ship_name)` - 按船名查询
|
||
- `query_all(limit)` - 查询所有
|
||
- `get_stats()` - 获取统计信息
|
||
- `get_ships_with_monthly_teu(year_month)` - 获取当月每艘船的作业量
|
||
- `insert_cross_month_exclusion()` - 跨月数据调整
|
||
- `insert_confluence_page()` - 保存月份页面ID映射
|
||
- `get_confluence_page_for_date()` - 获取指定日期对应的页面ID
|
||
|
||
### DailyReportGenerator (src/report.py)
|
||
|
||
- `generate_report(date)` - 生成日报
|
||
- `print_report(date)` - 打印日报
|
||
- `get_shift_personnel(date)` - 获取班次人员（从飞书排班表获取）
|
||
|
||
### OrbitInGUI (src/gui.py)
|
||
|
||
- tkinter 图形界面
|
||
- 支持获取数据、生成日报
|
||
- 支持手动剔除次月多统计的船
|
||
- 日报内容可复制
|
||
|
||
### FeishuScheduleManager (src/feishu/manager.py)
|
||
|
||
- `get_schedule_for_date(date)` - 获取指定日期的排班信息
|
||
- `get_schedule_for_today()` - 获取今天的排班信息
|
||
- `refresh_all_schedules(days)` - 批量刷新排班信息
|
||
|
||
## 文本格式约定
|
||
|
||
- 列表前缀：`•` 用于 `ul`，数字+点用于 `ol`
|
||
- 粗体使用 `**text**`，斜体使用 `*text*`
|
||
- 水平线使用 `─` (U+2500) 字符
|
||
- 链接渲染为 `text (url)`
|
||
|
||
## 配置
|
||
|
||
在 `.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_TOKEN=your-feishu-api-token
|
||
FEISHU_SPREADSHEET_TOKEN=EgNPssi2ghZ7BLtGiTxcIBUmnVh
|
||
FEISHU_APP_ID=your-feishu-app-id
|
||
FEISHU_APP_SECRET=your-feishu-app-secret
|
||
|
||
# 业务配置
|
||
DAILY_TARGET_TEU=300
|
||
DUTY_PHONE=13107662315
|
||
```
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
# 默认：获取、提取、解析并保存到数据库
|
||
python3 main.py
|
||
|
||
# 仅获取HTML并提取文本
|
||
python3 main.py fetch
|
||
|
||
# 生成日报
|
||
python3 main.py report 2025-12-28
|
||
|
||
# 生成昨日日报
|
||
python3 main.py report-today
|
||
|
||
# 手动剔除次月多统计的船
|
||
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界面
|
||
python3 src/gui.py
|
||
```
|
||
|
||
## 测试模式
|
||
|
||
如果设置了环境变量 `DEBUG_MODE=true`，系统会使用本地 `layout_output.txt` 文件而不是从 Confluence API 获取数据，方便离线测试。
|
||
|
||
## 注意事项
|
||
|
||
1. 二次靠泊记录会在解析时自动合并
|
||
2. 重复获取数据不会累加TEU（会跳过已存在的记录）
|
||
3. 未统计数据在报表中不显示，但会计算到当月实际作业量
|
||
4. 昨日日报按钮默认获取前一天的数据（因为通常在第二天汇报）
|
||
5. 月底数据调整适用于**每个月最后一天**，而不仅限12月
|
||
|
||
## 技术栈
|
||
|
||
- Python 3.7+
|
||
- SQLite3
|
||
- Requests (HTTP 客户端)
|
||
- BeautifulSoup4 (HTML 解析)
|
||
- tkinter (GUI)
|
||
- 类型提示
|
||
|
||
## 许可证
|
||
|
||
MIT
|