Orbitin/AGENTS.md

# AGENTS.md

This file provides guidance to agents when working with code in this repository.

## 项目概述
Python 工具，用于从 Confluence API 获取 HTML 并提取保留布局的文本。

## 项目结构

```
OrbitIn/
├── main.py                    # CLI 入口
├── .env                       # 环境配置（敏感信息）
├── .env.example               # 环境配置示例
├── README.md                  # 项目说明
├── AGENTS.md                  # AI助手文档
├── layout_output.txt          # 缓存的布局文本
├── debug/                     # 调试输出目录
│   └── layout_output_*.txt    # 带时间戳的调试文件
├── data/                      # 数据目录
│   └── daily_logs.db          # SQLite3 数据库
└── src/                       # 代码模块
    ├── __init__.py
    ├── confluence.py          # Confluence API 客户端
    ├── extractor.py           # HTML 文本提取器
    ├── parser.py              # 日志解析器
    ├── database.py            # SQLite3 数据库操作
    └── report.py              # 日报生成器
```

## 核心模块

### [`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()` - 获取统计信息
- `insert_unaccounted(year_month, teu, note)` - 添加未统计数据
- `get_unaccounted(year_month)` - 获取未统计数据

### [`DailyReportGenerator`](src/report.py:15)
- `generate_report(date)` - 生成日报
- `print_report(date)` - 打印日报

## 文本格式约定

- 列表前缀：`•` 用于 `ul`，数字+点用于 `ol`
- 粗体使用 `**text**`，斜体使用 `*text*`
- 水平线使用 `─` (U+2500) 字符
- 链接渲染为 `text (url)`

## 命令

```bash
# 默认：获取、提取、解析并保存到数据库
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 parse-test

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

## 配置

在 `.env` 文件中配置 Confluence 连接信息：

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

## 测试模式

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