Orbitin/README.md

# OrbitIn - 码头作业日志管理系统使用手册

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

---

## 目录

1. [快速开始](#1-快速开始)
2. [配置说明](#2-配置说明)
3. [GUI界面使用](#3-gui界面使用)
4. [命令行操作](#4-命令行操作)
5. [常见场景](#5-常见场景)
6. [故障排除](#6-故障排除)

---

## 1. 快速开始

### 1.1 环境要求

- Python 3.7+
- pip 包管理器

### 1.2 安装依赖

```bash
cd /path/to/OrbitIn
pip install requests beautifulsoup4 python-dotenv
```

### 1.3 首次运行

```bash
# 复制配置文件
cp .env.example .env

# 编辑配置文件（见下一节）

# 启动GUI界面
python3 src/gui.py
```

---

## 2. 配置说明

### 2.1 配置文件位置

项目根目录下的 `.env` 文件（需手动创建或从 `.env.example` 复制）

### 2.2 必填配置

```bash
# Confluence API 配置
CONFLUENCE_BASE_URL=https://confluence.westwell-lab.com/rest/api
CONFLUENCE_TOKEN=your-api-token
CONFLUENCE_CONTENT_ID=155764524
```

**如何获取Confluence API Token：**
1. 登录 Confluence
2. 点击右上角头像 → Settings → Security → API tokens
3. 创建新 token 并复制

### 2.3 可选配置

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

# 业务配置
DAILY_TARGET_TEU=300          # 每日目标TEU，用于计算完成率
DUTY_PHONE=13107662315        # 值班电话，显示在日报中
```

### 2.4 月份页面ID映射

由于每月 Confluence 页面ID不同，建议配置月份映射：

| 月份 | 页面ID | 用途 |
|------|--------|------|
| 2025-12 | xxx | 获取12月日志 |
| 2026-01 | xxx | 获取1月日志 |

在 GUI 中点击「管理页面ID映射」进行配置。

---

## 3. GUI界面使用

### 3.1 启动GUI

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

### 3.2 界面布局

```
┌─────────────────────────────────────────────────────────────┐
│ OrbitIn - 码头作业日志管理工具                               │
├──────────────────────────┬──────────────────────────────────┤
│                          │ 日报内容 (可复制):               │
│ [获取并处理数据]          │ ┌────────────────────────────┐  │
│ [重置数据库]              │ │                            │  │
│ ──────────────────       │ │   2026年1月1日 日报         │  │
│ 生成日报:                │ │   ...                      │  │
│ [____2026-01-01__]       │ │                            │  │
│ [生成日报] [今日日报]     │ └────────────────────────────┘  │
│ ──────────────────       │                                  │
│ [剔除次月多统计]          │ [复制日报] [复制全部]           │
│ ──────────────────       │                                  │
│ [数据库统计]              │ 日志输出:                       │
│ [清空输出]                │ ┌────────────────────────────┐  │
│ ──────────────────       │ │ [INFO] 准备就绪...         │  │
│ [管理页面ID映射]          │ └────────────────────────────┘  │
│                          │                                  │
└──────────────────────────┴──────────────────────────────────┘
```

### 3.3 核心功能

| 功能按钮 | 说明 | 快捷键 |
|---------|------|--------|
| 获取并处理数据 | 从Confluence获取最新数据 | Ctrl+Enter |
| 今日日报 | 生成昨天的日报 | - |
| 剔除次月多统计 | 手动调整跨月数据 | - |
| 数据库统计 | 查看当月作业统计 | - |
| 管理页面ID映射 | 配置各月页面ID | - |

### 3.4 数据获取流程

1. 启动GUI（自动获取前一天数据）
2. 查看日报内容
3. 如需调整，点击「剔除次月多统计」

### 3.5 使用「剔除次月多统计」功能

**使用场景：**
- 1月2日整理1月1日数据时，发现12月31日有数据未剔除
- 需要将12月31日的部分数据转移到1月1日

**操作步骤：**

1. 点击左侧「剔除次月多统计」按钮
2. 弹窗中选择源月份和目标月份：
   - 源月份：2025-12（被剔除数据的月份）
   - 目标月份：2026-01（数据转移到的月份）
3. 从列表中选择要转移的船，或手动输入
4. 修改TEU值（如只需部分转移）
5. 点击「确定」确认操作

---

## 4. 命令行操作

### 4.1 命令列表

| 命令 | 说明 | 示例 |
|-----|------|------|
| `fetch-save` | 获取并保存数据 | `python3 main.py fetch-save` |
| `fetch` | 仅获取HTML | `python3 main.py fetch` |
| `report <日期>` | 生成日报 | `python3 main.py report 2025-12-28` |
| `report-today` | 生成今日日报 | `python3 main.py report-today` |
| `config-test` | 测试配置连接 | `python3 main.py config-test` |

### 4.2 跨月调整命令

```bash
# 将数据从2025年12月31日转移到2026年1月1日
python3 main.py \
  --cross-exclude \
  --source-date 2025-12-31 \
  --target-date 2026-01-01 \
  --ship-name "学友洋山" \
  --teu 100 \
  --twenty 50 \
  --forty 25
```

**参数说明：**

| 参数 | 必填 | 说明 |
|-----|------|------|
| `--source-date` | 是 | 源日期（被剔除数据的日期） |
| `--target-date` | 是 | 目标日期（数据转移到的日期） |
| `--ship-name` | 是 | 船名 |
| `--teu` | 是 | TEU数量 |
| `--twenty` | 否 | 20尺箱量（默认0） |
| `--forty` | 否 | 40尺箱量（默认0） |
| `--reason` | 否 | 调整原因（默认"手动剔除次月多统计的船"） |

---

## 5. 常见场景

### 场景1：日常获取数据

**操作：**
1. 每天打开GUI
2. 自动获取前一天数据
3. 查看/复制日报

**说明：**
- 程序在第二天自动获取前一天的日志
- 无需手动干预

### 场景2：月底数据处理

**问题：**
- 12月31日24:00后还有作业
- 需要将这部分数据算到1月1日

**操作：**
1. 12月31日获取数据后，系统会自动弹出询问
2. 输入需要剔除的数据（船名、TEU、尺寸）
3. 系统自动将数据转移到1月1日

### 场景3：月初补调数据

**问题：**
- 1月2日打开工具整理数据
- 发现12月31日的数据忘记剔除

**操作：**
1. 点击「剔除次月多统计」
2. 源月份选择 2025-12
3. 目标月份选择 2026-01
4. 选择要转移的船或手动输入
5. 确认完成

### 场景4：跨日船处理

**问题：**
- 一艘船12月31日和1月1日都有作业
- 只需要转移部分TEU

**操作：**
1. 点击「剔除次月多统计」
2. 从列表中选择该船
3. 手动修改TEU值（如原200TEU，改为50TEU）
4. 确认完成

---

## 6. 故障排除

### 6.1 连接失败

**症状：** 无法获取Confluence数据

**排查步骤：**
1. 检查 `.env` 文件中的 `CONFLUENCE_BASE_URL` 和 `CONFLUENCE_TOKEN`
2. 确认API token未过期
3. 测试网络连接

**解决方案：**
```bash
# 测试配置
python3 main.py config-test
```

### 6.2 页面ID错误

**症状：** 获取的数据不对或为空

**原因：** 每月Confluence页面ID不同

**解决方案：**
1. 在GUI中点击「管理页面ID映射」
2. 添加当前月份的页面ID

### 6.3 数据重复

**症状：** 同一艘船出现多次

**原因：** 二次靠泊记录未被正确合并

**说明：** 系统会自动合并同一天的二次靠泊记录，无需手动处理

### 6.4 飞书数据获取失败

**排查步骤：**
1. 验证飞书表格权限
2. 检查 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`
3. 确认应用已发布到企业

### 6.5 日志查看

**日志文件位置：** `logs/app.log`

**日志级别：**
- 默认：INFO
- 调试：设置环境变量 `LOG_LEVEL=DEBUG`

```bash
# 查看实时日志
tail -f logs/app.log
```

---

## 技术支持

如遇到问题，请：
1. 查看日志输出
2. 检查配置文件
3. 联系管理员

---

## 附录

### A. 文件结构

```
OrbitIn/
├── main.py              # CLI入口
├── README.md            # 使用手册
├── .env                 # 配置（敏感信息）
├── .env.example         # 配置模板
├── data/                # 数据目录
│   ├── daily_logs.db    # SQLite3数据库
│   └── schedule_cache.json  # 排班缓存
├── logs/                # 日志目录
│   └── app.log          # 应用日志
└── src/                 # 源代码
    ├── config.py        # 配置管理
    ├── gui.py           # GUI界面
    ├── report.py        # 报表生成
    ├── database/        # 数据库模块
    ├── confluence/      # Confluence API
    └── feishu/          # 飞书 API
```

### B. 数据库表结构

**daily_logs 表：** 存储每日作业记录
- id, date, shift, ship_name, teu, twenty_feet, forty_feet

**manual_adjustments 表：** 存储手动调整记录
- id, date, ship_name, teu, adjustment_type, note

### C. 版本历史

- v1.0 - 初始版本
- v1.1 - 添加跨月调整功能
- v1.2 - 添加月份页面ID映射
- v1.3 - 优化GUI界面

---

**最后更新：** 2026年1月