Orbitin/README.md

# OrbitIn

码头作业日志管理工具。从 Confluence API 获取交接班日志，提取作业数据并生成统计报表。

## 功能特性

- **数据获取**：从 Confluence API 获取交接班日志 HTML
- **文本提取**：提取保留布局的文本内容，支持表格格式化
- **数据库存储**：SQLite3 数据库存储，支持二次靠泊记录合并
- **报表生成**：生成日报和月度统计，包含完成率计算
- **数据调整**：支持手动添加/剔除统计数据，月底数据自动转移
- **智能调整**：月底最后一天自动询问剔除12点后数据，月初自动添加上月数据
- **GUI界面**：tkinter 图形界面，支持一键操作
- **飞书集成**：自动获取排班人员信息，支持应用凭证自动刷新token
- **月份页面映射**：支持配置各月份的Confluence页面ID，解决每月页面ID变化问题

## 快速开始

### 安装依赖

```bash
pip install requests beautifulsoup4 python-dotenv
```

### 配置

```bash
cp .env.example .env
# 编辑 .env 文件，填入配置
```

### 使用

```bash
# 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

# 飞书表格配置
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
DUTY_PHONE=13107662315
```

## 命令

```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
```

## 测试模式

如果设置了环境变量 `DEBUG_MODE=true`，系统会使用本地 `layout_output.txt` 文件而不是从 Confluence API 获取数据，方便离线测试。

## 注意事项

1. 二次靠泊记录会在解析时自动合并
2. 重复获取数据不会累加TEU（会跳过已存在的记录）
3. 未统计数据在报表中不显示，但会计算到当月实际作业量
4. 昨日日报按钮默认获取前一天的数据（因为通常在第二天汇报）
5. 月底数据调整适用于**每个月最后一天**，而不仅限12月

## 技术栈

- Python 3.7+
- SQLite3
- Requests (HTTP 客户端)
- BeautifulSoup4 (HTML 解析)
- tkinter (GUI)
- 类型提示

## 许可证

MIT