Add README and monthly unaccounted data feature

2026-02-10 07:41:29 +08:00 · 2025-12-29 01:03:54 +08:00
parent 3b60ae9ecf
commit 283a035ab1
7 changed files with 1363 additions and 17 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,127 @@
+# OrbitIn - 码头作业日志管理系统
+
+从 Confluence API 获取交接班日志，提取作业数据并生成统计报表。
+
+## 功能特性
+
+- 📥 从 Confluence 获取交接班日志 HTML
+- 📄 提取保留布局的文本内容
+- 🗄️ SQLite3 数据库存储
+- 📊 生成日报和月度统计
+- 📈 支持未统计数据手动录入
+
+## 项目结构
+
+```
+OrbitIn/
+├── main.py                    # CLI 入口
+├── README.md                  # 项目说明
+├── AGENTS.md                  # AI助手开发文档
+├── layout_output.txt          # 缓存的布局文本
+├── data/                      # 数据目录
+│   └── daily_logs.db          # SQLite3 数据库
+└── src/                       # 代码模块
+    ├── __init__.py
+    ├── confluence.py          # Confluence API 客户端
+    ├── extractor.py           # HTML 文本提取器
+    ├── parser.py              # 日志解析器
+    ├── database.py            # 数据库操作
+    └── report.py              # 报表生成器
+```
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+pip install requests beautifulsoup4
+```
+
+### 配置 Confluence
+
+在 `main.py` 中配置：
+
+```python
+CONFLUENCE_URL = "https://your-confluence.atlassian.net"
+CONFLUENCE_USER = "your-email@example.com"
+CONFLUENCE_API_TOKEN = "your-api-token"
+```
+
+### 使用方法
+
+```bash
+# 获取并处理数据（带数据库存储）
+python3 main.py
+
+# 不存储到数据库
+python3 main.py --no-db
+
+# 生成日报（指定日期）
+python3 -c "from src.report import DailyReportGenerator; g = DailyReportGenerator(); g.print_report('2025-12-28'); g.close()"
+
+# 测试解析模块
+python3 -c "from src.parser import HandoverLogParser; p = HandoverLogParser(); print(p.parse(open('layout_output.txt').read())[:3])"
+```
+
+## 数据格式
+
+### 日报表 (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 | 创建时间 |
+
+## 文本格式约定
+
+- 列表前缀：`•` 用于 `ul`，数字+点用于 `ol`
+- 粗体使用 `**text**`，斜体使用 `*text*`
+- 水平线使用 `─` (U+2500) 字符
+- 链接渲染为 `text (url)`
+
+## 示例输出
+
+```
+日期：12/28
+
+船名：246#学友洋山
+作业量：246TEU
+
+当日实际作业量：246TEU
+
+当月计划作业量：8400TEU (用天数*300TEU)
+当月未统计数据：118TEU
+当月实际作业量：12750TEU
+当月完成比例：151.79%
+
+12/29 白班人员：
+12/29 夜班人员：
+24小时值班手机：13107662315
+```
+
+## 技术栈
+
+- Python 3.7+
+- SQLite3
+- Requests (HTTP 客户端)
+- HTMLParser (标准库)
+
+## License
+
+MIT