Files

qichi.liang 0cbc587bf3 feat: 实现月底/月初数据调整功能

1. 新增月底/月初智能数据调整功能
   - 月底最后一天自动弹出剔除数据对话框
   - 月初1号自动弹出添加数据对话框
   - 普通日期不弹出对话框

2. 实现月底剔除数据自动转移到次月1号
   - 月底剔除的数据自动添加到次月1号统计
   - 支持跨月、跨年数据转移
   - 数据备注自动记录转移信息

3. 修复自动获取数据后不弹出调整对话框的问题
   - 修改auto_fetch_data()方法，成功获取数据后调用调整处理
   - 确保第一次打开GUI也能弹出相应对话框

4. 修复月度统计不包含调整数据的问题
   - 修改get_monthly_stats()方法包含手动调整数据
   - 确保调整数据正确影响月度统计

5. 恢复日报原始模板格式
   - 移除调整数据的详细说明
   - 保持原始日报模板，只显示最终结果

6. 数据库增强
   - 新增manual_adjustments表存储手动调整数据
   - 实现调整数据的增删改查方法
   - 实现包含调整数据的每日数据获取方法

测试通过：所有功能正常工作，数据计算准确。

2026-01-02 00:08:57 +08:00

5.2 KiB

Raw Permalink Blame History

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)

命令

# 默认：获取、提取、解析并保存到数据库
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 文件中配置连接信息：

# 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 获取数据，方便离线测试。

注意事项

二次靠泊记录会在解析时自动合并
重复获取数据不会累加TEU（会跳过已存在的记录）
未统计数据在报表中不显示，但会计算到当月实际作业量
昨日日报按钮默认获取前一天的数据（因为通常在第二天汇报）

5.2 KiB Raw Permalink Blame History Unescape Escape