OrbitIn - 码头作业日志管理系统使用手册

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

---

目录

1. 快速开始
2. 配置说明
3. GUI界面使用
4. 命令行操作
5. 常见场景
6. 故障排除

---

1. 快速开始

1.1 环境要求

• Python 3.7+
• pip 包管理器

1.2 安装依赖

cd /path/to/OrbitIn
pip install requests beautifulsoup4 python-dotenv

1.3 首次运行

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

# 编辑配置文件（见下一节）

# 启动GUI界面
python3 src/gui.py

---

2. 配置说明

2.1 配置文件位置

项目根目录下的 .env 文件（需手动创建或从 .env.example 复制）

2.2 必填配置

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

如何获取Confluence API Token：

1. 登录 Confluence
2. 点击右上角头像 → Settings → Security → API tokens
3. 创建新 token 并复制

2.3 可选配置

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

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

2.4 月份页面ID映射

由于每月 Confluence 页面ID不同，建议配置月份映射：

月份	页面ID	用途
2025-12	xxx	获取12月日志
2026-01	xxx	获取1月日志

在 GUI 中点击「管理页面ID映射」进行配置。

---

3. GUI界面使用

3.1 启动GUI

python3 src/gui.py

3.2 界面布局

┌─────────────────────────────────────────────────────────────┐
│ OrbitIn - 码头作业日志管理工具                               │
├──────────────────────────┬──────────────────────────────────┤
│                          │ 日报内容 (可复制):               │
│ [获取并处理数据]          │ ┌────────────────────────────┐  │
│ [重置数据库]              │ │                            │  │
│ ──────────────────       │ │   2026年1月1日 日报         │  │
│ 生成日报:                │ │   ...                      │  │
│ [____2026-01-01__]       │ │                            │  │
│ [生成日报] [今日日报]     │ └────────────────────────────┘  │
│ ──────────────────       │                                  │
│ [剔除次月多统计]          │ [复制日报] [复制全部]           │
│ ──────────────────       │                                  │
│ [数据库统计]              │ 日志输出:                       │
│ [清空输出]                │ ┌────────────────────────────┐  │
│ ──────────────────       │ │ [INFO] 准备就绪...         │  │
│ [管理页面ID映射]          │ └────────────────────────────┘  │
│                          │                                  │
└──────────────────────────┴──────────────────────────────────┘

3.3 核心功能

功能按钮	说明	快捷键
获取并处理数据	从Confluence获取最新数据	Ctrl+Enter
今日日报	生成昨天的日报	-
剔除次月多统计	手动调整跨月数据	-
数据库统计	查看当月作业统计	-
管理页面ID映射	配置各月页面ID	-

3.4 数据获取流程

1. 启动GUI（自动获取前一天数据）
2. 查看日报内容
3. 如需调整，点击「剔除次月多统计」

3.5 使用「剔除次月多统计」功能

使用场景：

• 1月2日整理1月1日数据时，发现12月31日有数据未剔除
• 需要将12月31日的部分数据转移到1月1日

操作步骤：

1. 点击左侧「剔除次月多统计」按钮
2. 弹窗中选择源月份和目标月份：
   • 源月份：2025-12（被剔除数据的月份）
   • 目标月份：2026-01（数据转移到的月份）
3. 从列表中选择要转移的船，或手动输入
4. 修改TEU值（如只需部分转移）
5. 点击「确定」确认操作

---

4. 命令行操作

4.1 命令列表

命令	说明	示例
fetch-save	获取并保存数据	python3 main.py fetch-save
fetch	仅获取HTML	python3 main.py fetch
report <日期>	生成日报	python3 main.py report 2025-12-28
report-today	生成今日日报	python3 main.py report-today
config-test	测试配置连接	python3 main.py config-test

4.2 跨月调整命令

# 将数据从2025年12月31日转移到2026年1月1日
python3 main.py \
  --cross-exclude \
  --source-date 2025-12-31 \
  --target-date 2026-01-01 \
  --ship-name "学友洋山" \
  --teu 100 \
  --twenty 50 \
  --forty 25

参数说明：

参数	必填	说明
--source-date	是	源日期（被剔除数据的日期）
--target-date	是	目标日期（数据转移到的日期）
--ship-name	是	船名
--teu	是	TEU数量
--twenty	否	20尺箱量（默认0）
--forty	否	40尺箱量（默认0）
--reason	否	调整原因（默认"手动剔除次月多统计的船"）

---

5. 常见场景

场景1：日常获取数据

操作：

1. 每天打开GUI
2. 自动获取前一天数据
3. 查看/复制日报

说明：

• 程序在第二天自动获取前一天的日志
• 无需手动干预

场景2：月底数据处理

问题：

• 12月31日24:00后还有作业
• 需要将这部分数据算到1月1日

操作：

1. 12月31日获取数据后，系统会自动弹出询问
2. 输入需要剔除的数据（船名、TEU、尺寸）
3. 系统自动将数据转移到1月1日

场景3：月初补调数据

问题：

• 1月2日打开工具整理数据
• 发现12月31日的数据忘记剔除

操作：

1. 点击「剔除次月多统计」
2. 源月份选择 2025-12
3. 目标月份选择 2026-01
4. 选择要转移的船或手动输入
5. 确认完成

场景4：跨日船处理

问题：

• 一艘船12月31日和1月1日都有作业
• 只需要转移部分TEU

操作：

1. 点击「剔除次月多统计」
2. 从列表中选择该船
3. 手动修改TEU值（如原200TEU，改为50TEU）
4. 确认完成

---

6. 故障排除

6.1 连接失败

症状： 无法获取Confluence数据

排查步骤：

1. 检查 .env 文件中的 CONFLUENCE_BASE_URL 和 CONFLUENCE_TOKEN
2. 确认API token未过期
3. 测试网络连接

解决方案：

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

6.2 页面ID错误

症状： 获取的数据不对或为空

原因： 每月Confluence页面ID不同

解决方案：

1. 在GUI中点击「管理页面ID映射」
2. 添加当前月份的页面ID

6.3 数据重复

症状： 同一艘船出现多次

原因： 二次靠泊记录未被正确合并

说明： 系统会自动合并同一天的二次靠泊记录，无需手动处理

6.4 飞书数据获取失败

排查步骤：

1. 验证飞书表格权限
2. 检查 FEISHU_APP_ID 和 FEISHU_APP_SECRET
3. 确认应用已发布到企业

6.5 日志查看

日志文件位置： logs/app.log

日志级别：

• 默认：INFO
• 调试：设置环境变量 LOG_LEVEL=DEBUG

# 查看实时日志
tail -f logs/app.log

---

技术支持

如遇到问题，请：

1. 查看日志输出
2. 检查配置文件
3. 联系管理员

---

附录

A. 文件结构

OrbitIn/
├── main.py              # CLI入口
├── README.md            # 使用手册
├── .env                 # 配置（敏感信息）
├── .env.example         # 配置模板
├── data/                # 数据目录
│   ├── daily_logs.db    # SQLite3数据库
│   └── schedule_cache.json  # 排班缓存
├── logs/                # 日志目录
│   └── app.log          # 应用日志
└── src/                 # 源代码
    ├── config.py        # 配置管理
    ├── gui.py           # GUI界面
    ├── report.py        # 报表生成
    ├── database/        # 数据库模块
    ├── confluence/      # Confluence API
    └── feishu/          # 飞书 API

B. 数据库表结构

daily_logs 表： 存储每日作业记录

• id, date, shift, ship_name, teu, twenty_feet, forty_feet

manual_adjustments 表： 存储手动调整记录

• id, date, ship_name, teu, adjustment_type, note

C. 版本历史

• v1.0 - 初始版本
• v1.1 - 添加跨月调整功能
• v1.2 - 添加月份页面ID映射
• v1.3 - 优化GUI界面

---

最后更新： 2026年1月