Orbitin/README.md

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

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

功能特性

• 从 Confluence 获取交接班日志 HTML
• 提取保留布局的文本内容
• SQLite3 数据库存储
• 生成日报和月度统计
• 支持未统计数据手动录入
• 支持去除多余统计数据（对称功能）
• 支持二次靠泊记录合并
• GUI 图形界面（可选）
• 飞书排班表集成（自动获取班次人员）

项目结构

OrbitIn/
├── main.py                    # CLI 入口
├── README.md                  # 项目说明
├── AGENTS.md                  # AI助手开发文档
├── .env                       # 环境配置（敏感信息）
├── .env.example               # 环境配置示例
├── layout_output.txt          # 缓存的布局文本
├── debug/                     # 调试输出目录
│   └── layout_output_*.txt    # 带时间戳的调试文件
├── 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         # 内容管理器
    │   └── __init__.py        # 模块导出
    └── feishu/                # 飞书 API 模块
        ├── client.py          # 飞书 API 客户端
        ├── parser.py          # 排班数据解析器
        ├── manager.py         # 飞书排班管理器
        └── __init__.py        # 模块导出

快速开始

安装依赖

pip install requests beautifulsoup4 python-dotenv

配置

在 .env 文件中配置：

# .env
# Confluence 配置
CONFLUENCE_BASE_URL=https://your-confluence.atlassian.net/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）
# 创建飞书自建应用后获取app_id和app_secret
FEISHU_APP_ID=your-feishu-app-id
FEISHU_APP_SECRET=your-feishu-app-secret

# 备选：手动配置token（不推荐，token会过期）
# FEISHU_TOKEN=your-feishu-api-token

# 数据库配置
DATABASE_PATH=data/daily_logs.db

# 业务配置
DAILY_TARGET_TEU=300          # 每日目标TEU数量，用于计算完成率
DUTY_PHONE=13107662315        # 值班电话，显示在日报中
SEPARATOR_CHAR=─              # 分隔线字符，用于格式化输出
SEPARATOR_LENGTH=50           # 分隔线长度
SCHEDULE_REFRESH_DAYS=30      # 排班数据刷新间隔（天）

参考 .env.example 文件创建 .env 文件。

使用方法

命令行方式

# 默认：获取、提取、解析并保存到数据库
python3 main.py fetch-save

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

# 获取并保存带时间戳的debug文件
python3 main.py fetch-debug

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

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

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

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

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

# 显示帮助
python3 main.py --help

GUI 方式

python3 src/gui.py

GUI 功能：

• 获取并处理数据
• 重置数据库（删除并重新获取）
• 生成日报
• 今日日报（自动获取前一天数据）
• 添加未统计数据
• 去除多余统计数据（对称功能）
• 月底/月初智能调整（自动弹出对话框）
• 数据库统计（显示当月每艘船的作业量）
• 日报内容可复制
• 自动刷新排班信息

智能调整功能

• 月初1号：自动询问是否添加上月数据
• 月底最后一天：自动询问是否剔除12点后数据
• 其他日期：保留手动调整入口
• 调整数据：在日报中清晰显示，确保数据准确性

数据格式

日报表 (daily_handover_logs)

字段	类型	说明
id	INTEGER	主键
date	TEXT	日期 YYYY-MM-DD
shift	TEXT	班次 (白班/夜班)
ship_name	TEXT	船名（不含船号前缀）
teu	INTEGER	作业量 TEU
efficiency	REAL	效率
vehicles	INTEGER	上场车辆数
created_at	TEXT	创建时间

未统计表 (monthly_unaccounted)

字段	类型	说明
id	INTEGER	主键
year_month	TEXT	年月 YYYY-MM
teu	INTEGER	未统计的 TEU
note	TEXT	备注
created_at	TEXT	创建时间

手动调整表 (manual_adjustments)

字段	类型	说明
id	INTEGER	主键
date	TEXT	调整适用的日期 YYYY-MM-DD
ship_name	TEXT	船名
teu	INTEGER	TEU数量
twenty_feet	INTEGER	20尺箱量
forty_feet	INTEGER	40尺箱量
adjustment_type	TEXT	调整类型 'add' 或 'exclude'
note	TEXT	备注
created_at	TEXT	创建时间

特性说明

二次靠泊合并

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

• 夜班 学友洋山: 273TEU
• 夜班 学友洋山（二次靠泊）: 14TEU
• 合并后: 夜班 学友洋山: 287TEU

未统计数据

可以在数据库统计中查看当月每艘船的作业量总计，便于跟踪船舶运营情况。

去除多余统计数据

针对月底夜班箱量有时会被算入下个月的情况，系统提供了对称的"去除多余统计数据"功能：

• 添加未统计数据: 用于补全缺失的箱量
• 去除未统计数据: 用于删除多余统计的箱量

这两个功能配合使用，可以精确调整月度统计数据。

月底/月初数据调整功能

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

1. 月底最后一天（自动剔除12点后数据）

• 当获取数据的日期为月份最后一天时，GUI会自动询问是否需要剔除12点后的数据
• 用户可以输入需要剔除的船名、TEU以及具体尺寸（20尺/40尺）
• 剔除后的数据会从当月统计中移除，计入下月统计

2. 月初1号（自动添加上月数据）

• 当获取数据的日期为月份1号时，GUI会自动询问是否需要添加上月的作业数据
• 用户可以输入需要添加的船名、TEU以及具体尺寸（20尺/40尺）
• 添加的数据会计入上月统计，确保月度数据的准确性

3. 其他日期（手动调整入口）

• 非月初和月底的日期，默认不弹出调整对话框
• 但GUI侧边栏保留了手动添加/剔除TEU的功能入口
• 用户可以随时手动调整任何日期的数据

4. 调整数据存储

所有手动调整数据存储在 manual_adjustments 表中：

• date: 调整适用的日期
• ship_name: 船名
• teu: TEU数量
• twenty_feet: 20尺箱量
• forty_feet: 40尺箱量
• adjustment_type: 'add' 或 'exclude'
• note: 备注信息

5. 日报显示

调整数据会在日报中清晰显示：

• 每艘船下方显示具体的添加/剔除记录
• 日报末尾显示调整汇总信息
• 净调整量计算，确保数据准确性

示例输出

日期：12/28

船名：学友洋山
作业量：246TEU

当日实际作业量：246TEU

当月计划作业量：8400TEU (用天数*300TEU)
当月实际作业量：12632TEU
当月完成比例：150.38%

12/29 白班人员：
12/29 夜班人员：
24小时值班手机：13107662315

核心模块说明

Confluence 模块 (src/confluence/)

• client.py - Confluence API 客户端，负责 HTTP 请求和连接管理
• text.py - HTML 文本提取器，保留布局结构
• log_parser.py - 日志解析器，解析船次作业数据
• parser.py - HTML 内容解析器，提取链接、图片、表格
• manager.py - 内容管理器，提供高级内容管理功能

飞书模块 (src/feishu/)

• client.py - 飞书 API 客户端，支持自动获取和刷新tenant_access_token
• parser.py - 排班数据解析器
• manager.py - 飞书排班管理器，缓存和刷新排班信息

Token 自动获取机制

飞书模块现在支持两种认证方式：

1. 推荐方式：使用应用凭证（FEISHU_APP_ID + FEISHU_APP_SECRET）

   • 系统会自动调用飞书API获取tenant_access_token
   • token有效期2小时，系统会在过期前30分钟自动刷新
   • 无需手动管理token过期问题

2. 备选方式：使用手动配置的FEISHU_TOKEN

   • 兼容旧配置方式
   • token过期后需要手动更新
   • 不推荐长期使用

如何获取应用凭证

1. 登录飞书开放平台：https://open.feishu.cn/
2. 创建自建应用
3. 在"凭证与基础信息"中获取App ID和App Secret
4. 为应用添加"获取tenant_access_token"权限
5. 将应用发布到企业（仅自建应用需要）

数据库模块 (src/database/)

• base.py - 数据库基类，提供统一的连接管理
• daily_logs.py - 每日交接班日志数据库
• schedules.py - 排班数据库

技术栈

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

架构特点

1. 模块化设计 - 每个模块职责单一，便于测试和维护
2. 统一配置 - 集中管理所有环境变量和业务配置
3. 统一日志 - 标准化的日志配置和文件轮转
4. 异常处理 - 详细的错误处理和日志记录
5. 类型安全 - 全面的 Python 类型提示

开发指南

添加新功能

1. 配置管理: 所有配置项应在 src/config.py 中定义
2. 日志记录: 使用 from src.logging_config import get_logger 获取日志器
3. 异常处理: 为每个模块创建自定义异常类
4. 类型提示: 所有函数和方法都应包含完整的类型提示
5. 数据库操作: 使用 src/database/base.py 中的基类确保连接管理

测试

# 运行配置测试
python3 main.py config-test

# 测试特定功能
python3 main.py fetch
python3 main.py report-today

调试

1. 日志查看: 查看 logs/app.log 获取详细运行信息
2. 调试文件: 使用 python3 main.py fetch-debug 生成带时间戳的调试文件

代码规范

• 遵循 PEP 8 编码规范
• 使用 Black 格式化代码（可选）
• 使用 isort 排序导入
• 所有公开 API 应有文档字符串

故障排除

常见问题

1. 连接失败: 检查 .env 文件中的 API 令牌和 URL
2. 数据库错误: 确保 data/ 目录存在且有写入权限
3. 解析错误: 检查 Confluence 页面结构是否发生变化
4. 飞书数据获取失败:
   • 验证飞书表格权限
   • 检查应用凭证是否正确（FEISHU_APP_ID + FEISHU_APP_SECRET）
   • 确认应用已发布到企业（自建应用需要）
   • 检查网络连接是否能访问飞书API
5. 飞书token获取失败:
   • 确认应用有"获取tenant_access_token"权限
   • 检查app_id和app_secret是否正确
   • 查看日志文件获取详细错误信息

日志级别

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

License

MIT