qichi.liang
0cbc587bf3
1. 新增月底/月初智能数据调整功能 - 月底最后一天自动弹出剔除数据对话框 - 月初1号自动弹出添加数据对话框 - 普通日期不弹出对话框 2. 实现月底剔除数据自动转移到次月1号 - 月底剔除的数据自动添加到次月1号统计 - 支持跨月、跨年数据转移 - 数据备注自动记录转移信息 3. 修复自动获取数据后不弹出调整对话框的问题 - 修改auto_fetch_data()方法，成功获取数据后调用调整处理 - 确保第一次打开GUI也能弹出相应对话框 4. 修复月度统计不包含调整数据的问题 - 修改get_monthly_stats()方法包含手动调整数据 - 确保调整数据正确影响月度统计 5. 恢复日报原始模板格式 - 移除调整数据的详细说明 - 保持原始日报模板，只显示最终结果 6. 数据库增强 - 新增manual_adjustments表存储手动调整数据 - 实现调整数据的增删改查方法 - 实现包含调整数据的每日数据获取方法 测试通过：所有功能正常工作，数据计算准确。
156 lines
5.2 KiB
Markdown
156 lines
5.2 KiB
Markdown
# AI助手开发文档
|
||
|
||
本项目 OrbitIn 是一个码头作业日志管理工具，用于从 Confluence API 获取交接班日志、提取作业数据并生成统计报表。
|
||
|
||
## 项目概述
|
||
|
||
- **主要功能**: 从 Confluence API 获取 HTML 并提取保留布局的文本
|
||
- **输出**: 文本文件、数据库记录、日报表
|
||
- **语言**: Python 3.7+
|
||
- **依赖**: requests, beautifulsoup4, python-dotenv
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
OrbitIn/
|
||
├── main.py # CLI 入口
|
||
├── .env # 环境配置（敏感信息）
|
||
├── .env.example # 环境配置示例
|
||
├── README.md # 项目说明
|
||
├── AGENTS.md # AI助手文档
|
||
├── layout_output.txt # 缓存的布局文本
|
||
├── debug/ # 调试输出目录
|
||
│ └── layout_output_*.txt # 带时间戳的调试文件
|
||
├── data/ # 数据目录
|
||
│ ├── daily_logs.db # SQLite3 数据库
|
||
│ └── schedule_cache.json # 排班数据缓存
|
||
├── plans/ # 设计文档目录
|
||
│ └── feishu_scheduling_plan.md # 飞书排班表模块设计
|
||
└── src/ # 代码模块
|
||
├── __init__.py
|
||
├── confluence.py # Confluence API 客户端
|
||
├── extractor.py # HTML 文本提取器
|
||
├── parser.py # 日志解析器
|
||
├── database.py # SQLite3 数据库操作
|
||
├── report.py # 日报生成器
|
||
├── gui.py # GUI 图形界面
|
||
└── feishu.py # 飞书表格 API 客户端（新增）
|
||
```
|
||
|
||
## 核心模块
|
||
|
||
### ConfluenceClient (src/confluence.py:9)
|
||
|
||
- `fetch_content(content_id, expand)` - 获取页面内容
|
||
- `get_html(content_id)` - 获取 HTML 字符串
|
||
|
||
### HTMLTextExtractor (src/extractor.py:12)
|
||
|
||
- `extract(html)` - 从 HTML 提取保留布局的文本
|
||
- 使用 `html.parser`（非 lxml）
|
||
- 移除带 `ac:name` 属性的 Confluence 宏元素
|
||
- 表格格式化使用 `ljust()` 列对齐
|
||
|
||
### HandoverLogParser (src/parser.py:18)
|
||
|
||
- `parse(text)` - 解析日志文本，返回 `ShipLog` 列表
|
||
- 自动合并同日期同班次同船名的记录（二次靠泊）
|
||
- `ShipLog` 数据类：date, shift, ship_name, teu, efficiency, vehicles
|
||
|
||
### 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)` - 获取未统计数据
|
||
- `delete_unaccounted(year_month)` - 去除未统计数据（对称功能）
|
||
|
||
### DailyReportGenerator (src/report.py:15)
|
||
|
||
- `generate_report(date)` - 生成日报
|
||
- `print_report(date)` - 打印日报
|
||
- `get_shift_personnel(date)` - 获取班次人员（从飞书排班表获取）
|
||
|
||
### OrbitInGUI (src/gui.py:22)
|
||
|
||
- tkinter 图形界面
|
||
- 支持获取数据、生成日报、添加未统计数据
|
||
- 支持去除多余统计数据（对称功能）
|
||
- 日报内容可复制
|
||
|
||
### FeishuScheduleManager (src/feishu.py:150)
|
||
|
||
- `get_schedule_for_date(date)` - 获取指定日期的排班信息
|
||
- `get_schedule_for_today()` - 获取今天的排班信息
|
||
- `get_schedule_for_tomorrow()` - 获取明天的排班信息
|
||
|
||
## 文本格式约定
|
||
|
||
- 列表前缀：`•` 用于 `ul`，数字+点用于 `ol`
|
||
- 粗体使用 `**text**`，斜体使用 `*text*`
|
||
- 水平线使用 `─` (U+2500) 字符
|
||
- 链接渲染为 `text (url)`
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
# 默认：获取、提取、解析并保存到数据库
|
||
python3 main.py
|
||
|
||
# 仅获取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 parse-test
|
||
|
||
# 添加未统计数据
|
||
python3 main.py --unaccounted 118 --month 2025-12
|
||
|
||
# 去除未统计数据
|
||
python3 main.py --remove-unaccounted --month 2025-12
|
||
|
||
# GUI界面
|
||
python3 src/gui.py
|
||
```
|
||
|
||
## 配置
|
||
|
||
在 `.env` 文件中配置连接信息：
|
||
|
||
```bash
|
||
# Confluence 配置
|
||
CONFLUENCE_BASE_URL=https://confluence.westwell-lab.com/rest/api
|
||
CONFLUENCE_TOKEN=your-api-token
|
||
CONFLUENCE_CONTENT_ID=155764524
|
||
|
||
# 飞书表格配置（用于获取排班人员信息）
|
||
FEISHU_BASE_URL=https://open.feishu.cn/open-apis/sheets/v3
|
||
FEISHU_TOKEN=your-feishu-api-token
|
||
FEISHU_SPREADSHEET_TOKEN=EgNPssi2ghZ7BLtGiTxcIBUmnVh
|
||
```
|
||
|
||
## 测试模式
|
||
|
||
如果设置了环境变量 `DEBUG_MODE=true`，系统会使用本地 `layout_output.txt` 文件而不是从 Confluence API 获取数据，方便离线测试。
|
||
|
||
## 注意事项
|
||
|
||
1. 二次靠泊记录会在解析时自动合并
|
||
2. 重复获取数据不会累加TEU（会跳过已存在的记录）
|
||
3. 未统计数据在报表中不显示，但会计算到当月实际作业量
|
||
4. 昨日日报按钮默认获取前一天的数据（因为通常在第二天汇报）
|