qichi.liang
0cbc587bf3
1. 新增月底/月初智能数据调整功能 - 月底最后一天自动弹出剔除数据对话框 - 月初1号自动弹出添加数据对话框 - 普通日期不弹出对话框 2. 实现月底剔除数据自动转移到次月1号 - 月底剔除的数据自动添加到次月1号统计 - 支持跨月、跨年数据转移 - 数据备注自动记录转移信息 3. 修复自动获取数据后不弹出调整对话框的问题 - 修改auto_fetch_data()方法，成功获取数据后调用调整处理 - 确保第一次打开GUI也能弹出相应对话框 4. 修复月度统计不包含调整数据的问题 - 修改get_monthly_stats()方法包含手动调整数据 - 确保调整数据正确影响月度统计 5. 恢复日报原始模板格式 - 移除调整数据的详细说明 - 保持原始日报模板，只显示最终结果 6. 数据库增强 - 新增manual_adjustments表存储手动调整数据 - 实现调整数据的增删改查方法 - 实现包含调整数据的每日数据获取方法 测试通过：所有功能正常工作，数据计算准确。
388 lines
12 KiB
Markdown
388 lines
12 KiB
Markdown
# 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 # 模块导出
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
pip install requests beautifulsoup4 python-dotenv
|
||
```
|
||
|
||
### 配置
|
||
|
||
在 `.env` 文件中配置：
|
||
|
||
```bash
|
||
# .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` 文件。
|
||
|
||
### 使用方法
|
||
|
||
#### 命令行方式
|
||
|
||
```bash
|
||
# 默认：获取、提取、解析并保存到数据库
|
||
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 方式
|
||
|
||
```bash
|
||
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` 中的基类确保连接管理
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
# 运行配置测试
|
||
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
|