更新README和AGENTS文档

2025-12-29 02:56:50 +08:00
parent 4d2f9302ff
commit bf2ee14332
2 changed files with 89 additions and 29 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,9 +1,13 @@
-# AGENTS.md
+# AI助手开发文档

-This file provides guidance to agents when working with code in this repository.
+本项目 OrbitIn 是一个码头作业日志管理工具，用于从 Confluence API 获取交接班日志、提取作业数据并生成统计报表。

 ## 项目概述
-Python 工具，用于从 Confluence API 获取 HTML 并提取保留布局的文本。
+
+- **主要功能**: 从 Confluence API 获取 HTML 并提取保留布局的文本
+- **输出**: 文本文件、数据库记录、日报表
+- **语言**: Python 3.7+
+- **依赖**: requests, beautifulsoup4, python-dotenv

 ## 项目结构

@@ -25,39 +29,53 @@ OrbitIn/
    ├── extractor.py           # HTML 文本提取器
    ├── parser.py              # 日志解析器
    ├── database.py            # SQLite3 数据库操作
-    └── report.py              # 日报生成器
+    ├── report.py              # 日报生成器
+    └── gui.py                 # GUI 图形界面
 ```

 ## 核心模块

-### [`ConfluenceClient`](src/confluence.py:9)
+### ConfluenceClient (src/confluence.py:9)
+
 - `fetch_content(content_id, expand)` - 获取页面内容
 - `get_html(content_id)` - 获取 HTML 字符串

-### [`HTMLTextExtractor`](src/extractor.py:12)
+### HTMLTextExtractor (src/extractor.py:12)
+
 - `extract(html)` - 从 HTML 提取保留布局的文本
 - 使用 `html.parser`（非 lxml）
 - 移除带 `ac:name` 属性的 Confluence 宏元素
 - 表格格式化使用 `ljust()` 列对齐

-### [`HandoverLogParser`](src/parser.py:18)
+### HandoverLogParser (src/parser.py:18)
+
 - `parse(text)` - 解析日志文本，返回 `ShipLog` 列表
+- 自动合并同日期同班次同船名的记录（二次靠泊）
 - `ShipLog` 数据类：date, shift, ship_name, teu, efficiency, vehicles

-### [`DailyLogsDatabase`](src/database.py:13)
- `insert(log)` - 插入单条记录
+### DailyLogsDatabase (src/database.py:13)
+
+- `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_unaccounted(year_month, teu, note)` - 添加未统计数据
 - `get_unaccounted(year_month)` - 获取未统计数据

-### [`DailyReportGenerator`](src/report.py:15)
+### DailyReportGenerator (src/report.py:15)
+
 - `generate_report(date)` - 生成日报
 - `print_report(date)` - 打印日报

+### OrbitInGUI (src/gui.py:22)
+
+- tkinter 图形界面
+- 支持获取数据、生成日报、添加未统计数据
+- 日报内容可复制
+
 ## 文本格式约定

 - 列表前缀：`•` 用于 `ul`，数字+点用于 `ol`
@@ -80,11 +98,17 @@ python3 main.py fetch-debug
 # 生成日报
 python3 main.py report 2025-12-28

+# 生成昨日日报
+python3 main.py report-today
+
 # 解析测试
 python3 main.py parse-test

 # 添加未统计数据
 python3 main.py --unaccounted 118 --month 2025-12
+
+# GUI界面
+python3 src/gui.py
 ```

 ## 配置
@@ -100,3 +124,10 @@ CONFLUENCE_CONTENT_ID=155764524
 ## 测试模式

 如果设置了环境变量 `DEBUG_MODE=true`，系统会使用本地 `layout_output.txt` 文件而不是从 Confluence API 获取数据，方便离线测试。
+
+## 注意事项
+
+1. 二次靠泊记录会在解析时自动合并
+2. 重复获取数据不会累加TEU（会跳过已存在的记录）
+3. 未统计数据在报表中不显示，但会计算到当月实际作业量
+4. 昨日日报按钮默认获取前一天的数据（因为通常在第二天汇报）
--- a/README.md
+++ b/README.md
@@ -4,11 +4,13 @@

 ## 功能特性

- 📥 从 Confluence 获取交接班日志 HTML
- 📄 提取保留布局的文本内容
- 🗄️ SQLite3 数据库存储
- 📊 生成日报和月度统计
- 📈 支持未统计数据手动录入
+- 从 Confluence 获取交接班日志 HTML
+- 提取保留布局的文本内容
+- SQLite3 数据库存储
+- 生成日报和月度统计
+- 支持未统计数据手动录入
+- 支持二次靠泊记录合并
+- GUI 图形界面（可选）

 ## 项目结构

@@ -17,6 +19,8 @@ OrbitIn/
 ├── main.py                    # CLI 入口
 ├── README.md                  # 项目说明
 ├── AGENTS.md                  # AI助手开发文档
+├── .env                       # 环境配置（敏感信息）
+├── .env.example               # 环境配置示例
 ├── layout_output.txt          # 缓存的布局文本
 ├── debug/                     # 调试输出目录
 │   └── layout_output_*.txt    # 带时间戳的调试文件
@@ -28,7 +32,8 @@ OrbitIn/
    ├── extractor.py           # HTML 文本提取器
    ├── parser.py              # 日志解析器
    ├── database.py            # 数据库操作
-    └── report.py              # 报表生成器
+    ├── report.py              # 报表生成器
+    └── gui.py                 # GUI 图形界面
 ```

 ## 快速开始
@@ -36,7 +41,7 @@ OrbitIn/
 ### 安装依赖

 ```bash
-python3 -m pip install requests beautifulsoup4 python-dotenv
+pip install requests beautifulsoup4 python-dotenv
 ```

 ### 配置 Confluence
@@ -54,8 +59,10 @@ CONFLUENCE_CONTENT_ID=155764524

 ### 使用方法

+#### 命令行方式
+
 ```bash
-# 默认：获取HTML、提取、解析并保存到数据库
+# 默认：获取、提取、解析并保存到数据库
 python3 main.py

 # 仅获取HTML并提取文本（保存到debug目录）
@@ -67,7 +74,7 @@ python3 main.py fetch-debug
 # 生成日报（指定日期）
 python3 main.py report 2025-12-28

-# 生成今日日报
+# 生成昨日日报
 python3 main.py report-today

 # 解析测试（使用已有的layout_output.txt）
@@ -80,6 +87,21 @@ python3 main.py --unaccounted 118 --month 2025-12
 python3 main.py --help
 ```

+#### GUI 方式
+
+```bash
+python3 src/gui.py
+```
+
+GUI 功能：
+- 获取并处理数据
+- 获取 (Debug模式)
+- 生成日报
+- 昨日日报（自动获取前一天数据）
+- 添加未统计数据
+- 数据库统计（显示当月每艘船的作业量）
+- 日报内容可复制
+
 ## 数据格式

 ### 日报表 (daily_handover_logs)
@@ -89,7 +111,7 @@ python3 main.py --help
 | id | INTEGER | 主键 |
 | date | TEXT | 日期 YYYY-MM-DD |
 | shift | TEXT | 班次 (白班/夜班) |
-| ship_name | TEXT | 船名 |
+| ship_name | TEXT | 船名（不含船号前缀） |
 | teu | INTEGER | 作业量 TEU |
 | efficiency | REAL | 效率 |
 | vehicles | INTEGER | 上场车辆数 |
@@ -105,27 +127,33 @@ python3 main.py --help
 | note | TEXT | 备注 |
 | created_at | TEXT | 创建时间 |

-## 文本格式约定
+## 特性说明

- 列表前缀：`•` 用于 `ul`，数字+点用于 `ol`
- 粗体使用 `**text**`，斜体使用 `*text*`
- 水平线使用 `─` (U+2500) 字符
- 链接渲染为 `text (url)`
+### 二次靠泊合并
+
+解析时会自动合并同一天的二次靠泊记录：
+
+- 夜班 学友洋山: 273TEU
+- 夜班 学友洋山（二次靠泊）: 14TEU
+- 合并后: 夜班 学友洋山: 287TEU
+
+### 未统计数据
+
+可以在数据库统计中查看当月每艘船的作业量总计，便于跟踪船舶运营情况。

 ## 示例输出

 ```
 日期：12/28

-船名：246#学友洋山
+船名：学友洋山
 作业量：246TEU

 当日实际作业量：246TEU

 当月计划作业量：8400TEU (用天数*300TEU)
-当月未统计数据：118TEU
-当月实际作业量：12750TEU
-当月完成比例：151.79%
+当月实际作业量：12632TEU
+当月完成比例：150.38%

 12/29 白班人员：
 12/29 夜班人员：
@@ -138,6 +166,7 @@ python3 main.py --help
 - SQLite3
 - Requests (HTTP 客户端)
 - HTMLParser (标准库)
+- tkinter (GUI，可选)

 ## License