From f04478fd8f4d974c454a4c421338320aab6133f2 Mon Sep 17 00:00:00 2001 From: "qichi.liang" Date: Fri, 2 Jan 2026 03:00:28 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99README=E4=B8=BA?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3=EF=BC=8C?= =?UTF-8?q?=E5=8C=85=E5=90=AB=E5=8A=9F=E8=83=BD=E7=89=B9=E6=80=A7=E3=80=81?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E7=BB=93=E6=9E=84=E3=80=81=E6=A0=B8=E5=BF=83?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 483 +++++++++++++++++++----------------------------------- 1 file changed, 166 insertions(+), 317 deletions(-) diff --git a/README.md b/README.md index 51b5ed6..c4cb654 100644 --- a/README.md +++ b/README.md @@ -1,358 +1,207 @@ -# OrbitIn - 码头作业日志管理系统使用手册 +# OrbitIn -从 Confluence API 获取交接班日志，提取作业数据并生成统计报表。 +码头作业日志管理工具。从 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 - -# 编辑配置文件（见下一节） - -# 启动GUI界面 -python3 src/gui.py +# 编辑 .env 文件，填入配置 ``` ---- - -## 2. 配置说明 - -### 2.1 配置文件位置 - -项目根目录下的 `.env` 文件（需手动创建或从 `.env.example` 复制） - -### 2.2 必填配置 +### 使用 ```bash -# Confluence API 配置 +# GUI 方式 +python3 src/gui.py + +# CLI 方式 +python3 main.py fetch-save # 获取并保存数据 +python3 main.py report 2025-12-28 # 生成日报 +``` + +## 项目结构 + +``` +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 # 飞书排班管理器 +``` + +## 核心模块 + +### ConfluenceClient (src/confluence/client.py) + +- `fetch_content(content_id, expand)` - 获取页面内容 +- `get_html(content_id)` - 获取 HTML 字符串 + +### HTMLTextExtractor (src/confluence/text.py) + +- `extract(html)` - 从 HTML 提取保留布局的文本 +- 使用 `html.parser`（非 lxml） +- 移除带 `ac:name` 属性的 Confluence 宏元素 +- 表格格式化使用 `ljust()` 列对齐 + +### HandoverLogParser (src/confluence/log_parser.py) + +- `parse(text)` - 解析日志文本，返回 `ShipLog` 列表 +- 自动合并同日期同班次同船名的记录（二次靠泊） +- `ShipLog` 数据类：date, shift, ship_name, teu, efficiency, vehicles + +### DailyLogsDatabase (src/database/daily_logs.py) + +- `insert(log)` - 插入单条记录（存在则跳过） +- `insert_many(logs)` - 批量插入 +- `query_by_date(date)` - 按日期查询 +- `query_by_ship(ship_name)` - 按船名查询 +- `query_all(limit)` - 查询所有 +- `get_stats()` - 获取统计信息 +- `get_ships_with_monthly_teu(year_month)` - 获取当月每艘船的作业量 +- `insert_cross_month_exclusion()` - 跨月数据调整 +- `insert_confluence_page()` - 保存月份页面ID映射 +- `get_confluence_page_for_date()` - 获取指定日期对应的页面ID + +### DailyReportGenerator (src/report.py) + +- `generate_report(date)` - 生成日报 +- `print_report(date)` - 打印日报 +- `get_shift_personnel(date)` - 获取班次人员（从飞书排班表获取） + +### OrbitInGUI (src/gui.py) + +- tkinter 图形界面 +- 支持获取数据、生成日报 +- 支持手动剔除次月多统计的船 +- 日报内容可复制 + +### FeishuScheduleManager (src/feishu/manager.py) + +- `get_schedule_for_date(date)` - 获取指定日期的排班信息 +- `get_schedule_for_today()` - 获取今天的排班信息 +- `refresh_all_schedules(days)` - 批量刷新排班信息 + +## 文本格式约定 + +- 列表前缀：`•` 用于 `ul`，数字+点用于 `ol` +- 粗体使用 `**text**`，斜体使用 `*text*` +- 水平线使用 `─` (U+2500) 字符 +- 链接渲染为 `text (url)` + +## 配置 + +在 `.env` 文件中配置： + +```bash +# Confluence 配置 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_TOKEN=your-feishu-api-token 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 # 值班电话，显示在日报中 +DAILY_TARGET_TEU=300 +DUTY_PHONE=13107662315 ``` -### 2.4 月份页面ID映射 - -由于每月 Confluence 页面ID不同，建议配置月份映射： - -| 月份 | 页面ID | 用途 | -|------|--------|------| -| 2025-12 | xxx | 获取12月日志 | -| 2026-01 | xxx | 获取1月日志 | - -在 GUI 中点击「管理页面ID映射」进行配置。 - ---- - -## 3. GUI界面使用 - -### 3.1 启动GUI +## 命令 ```bash +# 默认：获取、提取、解析并保存到数据库 +python3 main.py + +# 仅获取HTML并提取文本 +python3 main.py fetch + +# 生成日报 +python3 main.py report 2025-12-28 + +# 生成昨日日报 +python3 main.py report-today + +# 手动剔除次月多统计的船 +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界面 python3 src/gui.py ``` -### 3.2 界面布局 +## 测试模式 -``` -┌─────────────────────────────────────────────────────────────┐ -│ OrbitIn - 码头作业日志管理工具 │ -├──────────────────────────┬──────────────────────────────────┤ -│ │ 日报内容 (可复制): │ -│ [获取并处理数据] │ ┌────────────────────────────┐ │ -│ [重置数据库] │ │ │ │ -│ ────────────────── │ │ 2026年1月1日 日报 │ │ -│ 生成日报: │ │ ... │ │ -│ [____2026-01-01__] │ │ │ │ -│ [生成日报] [今日日报] │ └────────────────────────────┘ │ -│ ────────────────── │ │ -│ [剔除次月多统计] │ [复制日报] [复制全部] │ -│ ────────────────── │ │ -│ [数据库统计] │ 日志输出: │ -│ [清空输出] │ ┌────────────────────────────┐ │ -│ ────────────────── │ │ [INFO] 准备就绪... │ │ -│ [管理页面ID映射] │ └────────────────────────────┘ │ -│ │ │ -└──────────────────────────┴──────────────────────────────────┘ -``` +如果设置了环境变量 `DEBUG_MODE=true`，系统会使用本地 `layout_output.txt` 文件而不是从 Confluence API 获取数据，方便离线测试。 -### 3.3 核心功能 +## 注意事项 -| 功能按钮 | 说明 | 快捷键 | -|---------|------|--------| -| 获取并处理数据 | 从Confluence获取最新数据 | Ctrl+Enter | -| 今日日报 | 统计作业的作业情况 | - | -| 剔除次月多统计 | 手动调整跨月数据 | - | -| 数据库统计 | 查看当月作业统计 | - | -| 管理页面ID映射 | 配置各月页面ID | - | +1. 二次靠泊记录会在解析时自动合并 +2. 重复获取数据不会累加TEU（会跳过已存在的记录） +3. 未统计数据在报表中不显示，但会计算到当月实际作业量 +4. 昨日日报按钮默认获取前一天的数据（因为通常在第二天汇报） +5. 月底数据调整适用于**每个月最后一天**，而不仅限12月 -### 3.4 数据获取流程 +## 技术栈 -1. 启动GUI（自动获取前一天数据） -2. 查看日报内容 -3. 如需调整，点击「剔除次月多统计」 +- Python 3.7+ +- SQLite3 +- Requests (HTTP 客户端) +- BeautifulSoup4 (HTML 解析) +- tkinter (GUI) +- 类型提示 -### 3.5 使用「剔除次月多统计」功能 +## 许可证 -**使用场景：** -- 每月最后一天（如1月31日、2月28日）24:00后还有作业 -- 需要将这部分数据算到次月1日 -- 次月1日或2日整理数据时，发现上月最后一天有数据未剔除 - -**操作步骤：** - -1. 点击左侧「剔除次月多统计」按钮 -2. 弹窗中选择源月份和目标月份： - - 源月份：被剔除数据的月份（如 2025-01，选择1月的最后一天） - - 目标月份：数据转移到的月份（如 2025-02，选择2月的第一天） -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 -# 将数据从1月31日转移到2月1日 -python3 main.py \ - --cross-exclude \ - --source-date 2025-01-31 \ - --target-date 2025-02-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：月底数据处理 - -**问题：** -- 每月最后一天24:00后还有作业（如1月31日、2月28日、3月31日...） -- 需要将这部分数据算到次月1日 - -**操作：** -1. 月底最后一天获取数据后，系统会自动弹出询问 -2. 输入需要剔除的数据（船名、TEU、尺寸） -3. 系统自动将数据转移到次月1日 - -### 场景3：月初补调数据 - -**问题：** -- 次月1日或2日打开工具整理数据 -- 发现上月最后一天的数据忘记剔除（如1月2日发现1月31日未剔除） - -**操作：** -1. 点击「剔除次月多统计」 -2. 源月份选择上月（如 2025-01） -3. 目标月份选择当前月（如 2025-02） -4. 选择要转移的船或手动输入 -5. 确认完成 - -### 场景4：跨日船处理（部分转移） - -**问题：** -- 一艘船在月底和次月都有作业 -- 只需要转移部分TEU到次月 - -**操作：** -1. 点击「剔除次月多统计」 -2. 从列表中选择该船 -3. 手动修改TEU值（如原200TEU，改为50TEU，表示只转移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/ # 源代码 - ├── 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月 +MIT