Orbitin/README.md

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

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

功能特性

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

快速开始

安装依赖

pip install requests beautifulsoup4 python-dotenv

配置

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

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

配置文件 (.env)

# 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        # 值班电话，显示在日报中

使用方法

命令行方式

# 获取并保存数据到数据库
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 config-test

GUI 方式

python3 src/gui.py

GUI功能详解

核心功能

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

数据调整功能

• 添加未统计数据：用于补全缺失的箱量
• 去除多余统计数据：用于删除多余统计的箱量（对称功能）
• 月底智能调整：月底最后一天自动弹出剔除对话框
• 数据自动转移：月底剔除的数据自动转移到次月1号

配置管理

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

高级功能说明

月份页面ID映射

由于每月Confluence页面ID不同，系统支持配置月份到页面ID的映射：

• 在GUI中点击"管理月份页面ID映射"按钮
• 添加、编辑、删除各月份的页面ID配置
• 获取数据时自动使用当前月份对应的页面ID

月底/月初数据调整

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

1. 月底最后一天：

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

2. 月初1号：

   • 系统自动添加上月剔除的数据，无需用户手动操作
   • 确保月度数据的准确性和连续性

3. 其他日期：

   • 默认不弹出调整对话框
   • 但GUI侧边栏保留了手动添加/剔除TEU的功能入口

二次靠泊合并

解析时会自动合并同一天的二次靠泊记录：

• 夜班 学友洋山: 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