From 071a3f05f3e4e5bb6152b74160c9fcf823e82e4f Mon Sep 17 00:00:00 2001 From: "qichi.liang" Date: Fri, 2 Jan 2026 02:48:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=E6=89=8B=E5=86=8C=EF=BC=8C=E6=9B=B4=E6=B8=85=E6=99=B0=E7=9A=84?= =?UTF-8?q?=E6=93=8D=E4=BD=9C=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增目录结构，便于快速导航 - 添加GUI界面布局说明（ASCII图示） - 详细说明各功能的使用场景和操作步骤 - 新增常见场景章节（日常使用、月底处理、月初补调、跨日船） - 完善故障排除章节 - 添加附录（文件结构、数据库表结构、版本历史） --- README.md | 473 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 298 insertions(+), 175 deletions(-) diff --git a/README.md b/README.md index cef92ec..38ce1cc 100644 --- a/README.md +++ b/README.md @@ -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月