qichi.liang/Orbitin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 重写使用手册，更清晰的操作指南

Browse Source 
- 新增目录结构，便于快速导航
- 添加GUI界面布局说明（ASCII图示）
- 详细说明各功能的使用场景和操作步骤
- 新增常见场景章节（日常使用、月底处理、月初补调、跨日船）
- 完善故障排除章节
- 添加附录（文件结构、数据库表结构、版本历史）
This commit is contained in:
qichi.liang
2026-01-02 02:48:15 +08:00
parent bb3f25a643
commit 071a3f05f3
1 changed files with 298 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files

473
README.md
View File

@@ -1,234 +1,357 @@
# OrbitIn - 码头作业日志管理系统
# OrbitIn - 码头作业日志管理系统使用手册
从 Confluence API 获取交接班日志，提取作业数据并生成统计报表。
## 功能特性
---
- **数据获取**：从 Confluence API 获取交接班日志 HTML
- **文本提取**：提取保留布局的文本内容，支持表格格式化
- **数据库存储**：SQLite3 数据库存储，支持二次靠泊记录合并
- **报表生成**：生成日报和月度统计，包含完成率计算
- **数据调整**：支持手动添加/剔除统计数据，月底数据自动转移
- **智能调整**：月底最后一天自动询问剔除12点后数据，月初自动添加上月数据
- **GUI界面**：tkinter 图形界面，支持一键操作
- **飞书集成**：自动获取排班人员信息，支持应用凭证自动刷新token
- **月份页面映射**：支持配置各月份的Confluence页面ID，解决每月页面ID变化问题
## 目录
## 快速开始
1. [快速开始](#1-快速开始)
2. [配置说明](#2-配置说明)
3. [GUI界面使用](#3-gui界面使用)
4. [命令行操作](#4-命令行操作)
5. [常见场景](#5-常见场景)
6. [故障排除](#6-故障排除)
### 安装依赖
---
## 1. 快速开始
### 1.1 环境要求
- Python 3.7+
- pip 包管理器
### 1.2 安装依赖
```bash
cd /path/to/OrbitIn
pip install requests beautifulsoup4 python-dotenv
```
### 配置
### 1.3 首次运行
```bash
# 复制配置文件模板
# 复制配置文件
cp .env.example .env
# 编辑 .env 文件，填入以下配置
# 编辑配置文件（见下一节）
# 启动GUI界面
python3 src/gui.py
```
### 配置文件 (.env)
---
## 2. 配置说明
### 2.1 配置文件位置
项目根目录下的 `.env` 文件（需手动创建或从 `.env.example` 复制）
### 2.2 必填配置
```bash
# Confluence 配置
# 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 可选配置
```bash
# 飞书表格配置（用于获取排班人员信息）
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数量，用于计算完成率
DAILY_TARGET_TEU=300 # 每日目标TEU，用于计算完成率
DUTY_PHONE=13107662315 # 值班电话，显示在日报中
```
### 使用方法
### 2.4 月份页面ID映射
#### 命令行方式
由于每月 Confluence 页面ID不同，建议配置月份映射：
```bash
# 获取并保存数据到数据库
python3 main.py fetch-save
| 月份 | 页面ID | 用途 |
|------|--------|------|
| 2025-12 | xxx | 获取12月日志 |
| 2026-01 | xxx | 获取1月日志 |
# 仅获取HTML并提取文本（保存到debug目录）
python3 main.py fetch
在 GUI 中点击「管理页面ID映射」进行配置。
# 生成日报（指定日期）
python3 main.py report 2025-12-28
---
# 生成今日日报
python3 main.py report-today
## 3. GUI界面使用
# 添加未统计数据
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 方式
### 3.1 启动GUI
```bash
python3 src/gui.py
```
## GUI功能详解
### 3.2 界面布局
### 核心功能
- **获取并处理数据**：从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. 点击"确定"保存
```
┌─────────────────────────────────────────────────────────────┐
│ OrbitIn - 码头作业日志管理工具 │
├──────────────────────────┬──────────────────────────────────┤
│ │ 日报内容 (可复制): │
│ [获取并处理数据] │ ┌────────────────────────────┐ │
│ [重置数据库] │ │ │ │
│ ────────────────── │ │ 2026年1月1日 日报 │ │
│ 生成日报: │ │ ... │ │
│ [____2026-01-01__] │ │ │ │
│ [生成日报] [今日日报] │ └────────────────────────────┘ │
│ ────────────────── │ │
│ [剔除次月多统计] │ [复制日报] [复制全部] │
│ ────────────────── │ │
│ [数据库统计] │ 日志输出: │
│ [清空输出] │ ┌────────────────────────────┐ │
│ ────────────────── │ │ [INFO] 准备就绪... │ │
│ [管理页面ID映射] │ └────────────────────────────┘ │
│ │ │
└──────────────────────────┴──────────────────────────────────┘
```
### 二次靠泊合并
解析时会自动合并同一天的二次靠泊记录：
- 夜班 学友洋山: 273TEU
- 夜班 学友洋山（二次靠泊）: 14TEU
- 合并后: 夜班 学友洋山: 287TEU
### 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 跨月调整命令
```bash
# 将数据从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. 测试网络连接
**解决方案：**
```bash
# 测试配置
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`
```bash
# 查看实时日志
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/ # 代码模块
├── __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 # 飞书排班管理器
├── 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. 数据库表结构
- Python 3.7+
- SQLite3
- Requests (HTTP 客户端)
- BeautifulSoup4 (HTML 解析)
- tkinter (GUI)
- 类型提示 (Python 3.5+)
**daily_logs 表：** 存储每日作业记录
- id, date, shift, ship_name, teu, twenty_feet, forty_feet
## 故障排除
**manual_adjustments 表：** 存储手动调整记录
- id, date, ship_name, teu, adjustment_type, note
### 常见问题
### C. 版本历史
1. **连接失败**：检查 `.env` 文件中的 API 令牌和 URL
2. **数据库错误**：确保 `data/` 目录存在且有写入权限
3. **解析错误**：检查 Confluence 页面结构是否发生变化
4. **飞书数据获取失败**：
- 验证飞书表格权限
- 检查应用凭证是否正确（FEISHU_APP_ID + FEISHU_APP_SECRET）
- 确认应用已发布到企业（自建应用需要）
5. **月份页面ID问题**：
- 在GUI中配置正确的月份页面ID映射
- 确保当前月份的页面ID已正确配置
- v1.0 - 初始版本
- v1.1 - 添加跨月调整功能
- v1.2 - 添加月份页面ID映射
- v1.3 - 优化GUI界面
### 日志查看
---
- 默认日志级别: INFO
- 调试日志级别: DEBUG (设置环境变量 `LOG_LEVEL=DEBUG`)
- 日志文件: `logs/app.log`，自动轮转
## 许可证
MIT
**最后更新：** 2026年1月