Orbitin/README.md

# OrbitIn - 码头作业日志管理系统

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

## 功能特性

- 从 Confluence 获取交接班日志 HTML
- 提取保留布局的文本内容
- SQLite3 数据库存储
- 生成日报和月度统计
- 支持未统计数据手动录入
- 支持去除多余统计数据（对称功能）
- 支持二次靠泊记录合并
- GUI 图形界面（可选）
- 飞书排班表集成（自动获取班次人员）

## 项目结构

```
OrbitIn/
├── main.py                    # CLI 入口
├── README.md                  # 项目说明
├── AGENTS.md                  # AI助手开发文档
├── .env                       # 环境配置（敏感信息）
├── .env.example               # 环境配置示例
├── layout_output.txt          # 缓存的布局文本
├── debug/                     # 调试输出目录
│   └── layout_output_*.txt    # 带时间戳的调试文件
├── 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         # 内容管理器
    │   └── __init__.py        # 模块导出
    └── feishu/                # 飞书 API 模块
        ├── client.py          # 飞书 API 客户端
        ├── parser.py          # 排班数据解析器
        ├── manager.py         # 飞书排班管理器
        └── __init__.py        # 模块导出
```

## 快速开始

### 安装依赖

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

### 配置

在 `.env` 文件中配置：

```bash
# .env
# Confluence 配置
CONFLUENCE_BASE_URL=https://your-confluence.atlassian.net/rest/api
CONFLUENCE_TOKEN=your-api-token
CONFLUENCE_CONTENT_ID=155764524

# 飞书表格配置（用于获取排班人员信息）
FEISHU_BASE_URL=https://open.feishu.cn/open-apis/sheets/v3
FEISHU_SPREADSHEET_TOKEN=EgNPssi2ghZ7BLtGiTxcIBUmnVh

# 飞书应用凭证（推荐方式，自动获取tenant_access_token）
# 创建飞书自建应用后获取app_id和app_secret
FEISHU_APP_ID=your-feishu-app-id
FEISHU_APP_SECRET=your-feishu-app-secret

# 备选：手动配置token（不推荐，token会过期）
# FEISHU_TOKEN=your-feishu-api-token

# 数据库配置
DATABASE_PATH=data/daily_logs.db

# 业务配置
DAILY_TARGET_TEU=300          # 每日目标TEU数量，用于计算完成率
DUTY_PHONE=13107662315        # 值班电话，显示在日报中
SEPARATOR_CHAR=─              # 分隔线字符，用于格式化输出
SEPARATOR_LENGTH=50           # 分隔线长度
SCHEDULE_REFRESH_DAYS=30      # 排班数据刷新间隔（天）
```

参考 `.env.example` 文件创建 `.env` 文件。

### 使用方法

#### 命令行方式

```bash
# 默认：获取、提取、解析并保存到数据库
python3 main.py fetch-save

# 仅获取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 config-test

# 添加未统计数据
python3 main.py --unaccounted 118 --month 2025-12

# 去除未统计数据
python3 main.py --remove-unaccounted --month 2025-12

# 显示帮助
python3 main.py --help
```

#### GUI 方式

```bash
python3 src/gui.py
```

GUI 功能：
- 获取并处理数据
- 重置数据库（删除并重新获取）
- 生成日报
- 今日日报（自动获取前一天数据）
- 添加未统计数据
- 去除多余统计数据（对称功能）
- 月底/月初智能调整（自动弹出对话框）
- 数据库统计（显示当月每艘船的作业量）
- 日报内容可复制
- 自动刷新排班信息

#### 智能调整功能
- **月初1号**：自动询问是否添加上月数据
- **月底最后一天**：自动询问是否剔除12点后数据
- **其他日期**：保留手动调整入口
- **调整数据**：在日报中清晰显示，确保数据准确性

## 数据格式

### 日报表 (daily_handover_logs)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| date | TEXT | 日期 YYYY-MM-DD |
| shift | TEXT | 班次 (白班/夜班) |
| ship_name | TEXT | 船名（不含船号前缀） |
| teu | INTEGER | 作业量 TEU |
| efficiency | REAL | 效率 |
| vehicles | INTEGER | 上场车辆数 |
| created_at | TEXT | 创建时间 |

### 未统计表 (monthly_unaccounted)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| year_month | TEXT | 年月 YYYY-MM |
| teu | INTEGER | 未统计的 TEU |
| note | TEXT | 备注 |
| created_at | TEXT | 创建时间 |

### 手动调整表 (manual_adjustments)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| date | TEXT | 调整适用的日期 YYYY-MM-DD |
| ship_name | TEXT | 船名 |
| teu | INTEGER | TEU数量 |
| twenty_feet | INTEGER | 20尺箱量 |
| forty_feet | INTEGER | 40尺箱量 |
| adjustment_type | TEXT | 调整类型 'add' 或 'exclude' |
| note | TEXT | 备注 |
| created_at | TEXT | 创建时间 |

## 特性说明

### 二次靠泊合并

解析时会自动合并同一天的二次靠泊记录：

- 夜班 学友洋山: 273TEU
- 夜班 学友洋山（二次靠泊）: 14TEU
- 合并后: 夜班 学友洋山: 287TEU

### 未统计数据

可以在数据库统计中查看当月每艘船的作业量总计，便于跟踪船舶运营情况。

### 去除多余统计数据

针对月底夜班箱量有时会被算入下个月的情况，系统提供了对称的"去除多余统计数据"功能：
- **添加未统计数据**: 用于补全缺失的箱量
- **去除未统计数据**: 用于删除多余统计的箱量

这两个功能配合使用，可以精确调整月度统计数据。

### 月底/月初数据调整功能

系统支持智能化的月底/月初数据调整：

#### 1. 月底最后一天（自动剔除12点后数据）
- 当获取数据的日期为月份最后一天时，GUI会自动询问是否需要剔除12点后的数据
- 用户可以输入需要剔除的船名、TEU以及具体尺寸（20尺/40尺）
- 剔除后的数据会从当月统计中移除，计入下月统计

#### 2. 月初1号（自动添加上月数据）
- 当获取数据的日期为月份1号时，GUI会自动询问是否需要添加上月的作业数据
- 用户可以输入需要添加的船名、TEU以及具体尺寸（20尺/40尺）
- 添加的数据会计入上月统计，确保月度数据的准确性

#### 3. 其他日期（手动调整入口）
- 非月初和月底的日期，默认不弹出调整对话框
- 但GUI侧边栏保留了手动添加/剔除TEU的功能入口
- 用户可以随时手动调整任何日期的数据

#### 4. 调整数据存储
所有手动调整数据存储在 `manual_adjustments` 表中：
- `date`: 调整适用的日期
- `ship_name`: 船名
- `teu`: TEU数量
- `twenty_feet`: 20尺箱量
- `forty_feet`: 40尺箱量
- `adjustment_type`: 'add' 或 'exclude'
- `note`: 备注信息

#### 5. 日报显示
调整数据会在日报中清晰显示：
- 每艘船下方显示具体的添加/剔除记录
- 日报末尾显示调整汇总信息
- 净调整量计算，确保数据准确性

## 示例输出

```
日期：12/28

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

当日实际作业量：246TEU

当月计划作业量：8400TEU (用天数*300TEU)
当月实际作业量：12632TEU
当月完成比例：150.38%

12/29 白班人员：
12/29 夜班人员：
24小时值班手机：13107662315
```

## 核心模块说明

### Confluence 模块 (`src/confluence/`)
- **`client.py`** - Confluence API 客户端，负责 HTTP 请求和连接管理
- **`text.py`** - HTML 文本提取器，保留布局结构
- **`log_parser.py`** - 日志解析器，解析船次作业数据
- **`parser.py`** - HTML 内容解析器，提取链接、图片、表格
- **`manager.py`** - 内容管理器，提供高级内容管理功能

### 飞书模块 (`src/feishu/`)
- **`client.py`** - 飞书 API 客户端，支持自动获取和刷新tenant_access_token
- **`parser.py`** - 排班数据解析器
- **`manager.py`** - 飞书排班管理器，缓存和刷新排班信息

#### Token 自动获取机制
飞书模块现在支持两种认证方式：
1. **推荐方式**：使用应用凭证（FEISHU_APP_ID + FEISHU_APP_SECRET）
   - 系统会自动调用飞书API获取tenant_access_token
   - token有效期2小时，系统会在过期前30分钟自动刷新
   - 无需手动管理token过期问题

2. **备选方式**：使用手动配置的FEISHU_TOKEN
   - 兼容旧配置方式
   - token过期后需要手动更新
   - 不推荐长期使用

#### 如何获取应用凭证
1. 登录飞书开放平台：https://open.feishu.cn/
2. 创建自建应用
3. 在"凭证与基础信息"中获取App ID和App Secret
4. 为应用添加"获取tenant_access_token"权限
5. 将应用发布到企业（仅自建应用需要）

### 数据库模块 (`src/database/`)
- **`base.py`** - 数据库基类，提供统一的连接管理
- **`daily_logs.py`** - 每日交接班日志数据库
- **`schedules.py`** - 排班数据库

## 技术栈

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

## 架构特点

1. **模块化设计** - 每个模块职责单一，便于测试和维护
2. **统一配置** - 集中管理所有环境变量和业务配置
3. **统一日志** - 标准化的日志配置和文件轮转
4. **异常处理** - 详细的错误处理和日志记录
5. **类型安全** - 全面的 Python 类型提示

## 开发指南

### 添加新功能

1. **配置管理**: 所有配置项应在 `src/config.py` 中定义
2. **日志记录**: 使用 `from src.logging_config import get_logger` 获取日志器
3. **异常处理**: 为每个模块创建自定义异常类
4. **类型提示**: 所有函数和方法都应包含完整的类型提示
5. **数据库操作**: 使用 `src/database/base.py` 中的基类确保连接管理

### 测试

```bash
# 运行配置测试
python3 main.py config-test

# 测试特定功能
python3 main.py fetch
python3 main.py report-today
```

### 调试

1. **日志查看**: 查看 `logs/app.log` 获取详细运行信息
2. **调试文件**: 使用 `python3 main.py fetch-debug` 生成带时间戳的调试文件

### 代码规范

- 遵循 PEP 8 编码规范
- 使用 Black 格式化代码（可选）
- 使用 isort 排序导入
- 所有公开 API 应有文档字符串

## 故障排除

### 常见问题

1. **连接失败**: 检查 `.env` 文件中的 API 令牌和 URL
2. **数据库错误**: 确保 `data/` 目录存在且有写入权限
3. **解析错误**: 检查 Confluence 页面结构是否发生变化
4. **飞书数据获取失败**:
   - 验证飞书表格权限
   - 检查应用凭证是否正确（FEISHU_APP_ID + FEISHU_APP_SECRET）
   - 确认应用已发布到企业（自建应用需要）
   - 检查网络连接是否能访问飞书API
5. **飞书token获取失败**:
   - 确认应用有"获取tenant_access_token"权限
   - 检查app_id和app_secret是否正确
   - 查看日志文件获取详细错误信息

### 日志级别

- 默认日志级别: INFO
- 调试日志级别: DEBUG (设置环境变量 `LOG_LEVEL=DEBUG`)
- 日志文件: `logs/app.log`，自动轮转

## License

MIT