tyapi-server/internal/shared/pdf/LOG_VIEWING_GUIDE.md

# 📋 PDF表格转换日志查看指南

## 📍 日志文件位置

### 1. 开发环境
日志文件存储在项目根目录的 `logs/` 目录下：

```
tyapi-server/
└── logs/
    ├── 2024-12-02/          # 按日期分包（如果启用）
    │   ├── debug.log       # Debug级别日志（包含JSON转换详情）
    │   ├── info.log        # Info级别日志（包含转换流程）
    │   └── error.log       # Error级别日志（包含错误信息）
    └── app.log             # 传统模式（如果未启用按日分包）
```

### 2. 生产环境（Docker）
日志文件存储在容器的 `/app/logs/` 目录，映射到宿主机的 `./logs/` 目录：

```bash
# 查看宿主机日志
./logs/2024-12-02/info.log
./logs/2024-12-02/debug.log
```

## 🔍 如何查看转换日志

### 方法1：实时查看日志（推荐）

```bash
# 查看Info级别日志（转换流程）
tail -f logs/2024-12-02/info.log | grep "表格\|JSON\|markdown"

# 查看Debug级别日志（详细JSON数据）
tail -f logs/2024-12-02/debug.log | grep "JSON\|表格"

# 查看所有PDF相关日志
tail -f logs/2024-12-02/*.log | grep -i "pdf\|table\|json"
```

### 方法2：使用Docker查看

```bash
# 查看容器实时日志
docker logs -f tyapi-app-prod | grep -i "表格\|json\|markdown"

# 查看最近的100行日志
docker logs --tail 100 tyapi-app-prod | grep -i "表格\|json"
```

### 方法3：搜索特定字段类型

```bash
# 查看请求参数的转换日志
grep "request_params" logs/2024-12-02/info.log

# 查看响应字段的转换日志
grep "response_fields" logs/2024-12-02/info.log

# 查看错误代码的转换日志
grep "error_codes" logs/2024-12-02/info.log
```

## 📊 日志级别说明

### Info级别日志（info.log）
包含转换流程的关键步骤：
- ✅ 数据格式检测（JSON/Markdown）
- ✅ Markdown表格解析开始
- ✅ 表格解析成功（表头数量、行数）
- ✅ JSON转换完成

**示例日志：**
```
2024-12-02T10:30:15Z    INFO    开始解析markdown表格并转换为JSON    {"field_type": "request_params", "content_length": 1234}
2024-12-02T10:30:15Z    INFO    markdown表格解析成功    {"field_type": "request_params", "header_count": 3, "row_count": 5}
2024-12-02T10:30:15Z    INFO    表格数据已转换为JSON格式    {"field_type": "request_params", "json_array_length": 5}
```

### Debug级别日志（debug.log）
包含详细的转换数据：
- 🔍 原始内容预览
- 🔍 解析后的表头列表
- 🔍 转换后的完整JSON数据（前1000字符）
- 🔍 每行的转换详情

**示例日志：**
```
2024-12-02T10:30:15Z    DEBUG    转换后的JSON数据预览    {"field_type": "request_params", "json_length": 2345, "json_preview": "[{\"字段名\":\"name\",\"类型\":\"string\",\"说明\":\"姓名\"}...]"}
```

### Error级别日志（error.log）
包含转换过程中的错误：
- ❌ Markdown解析失败
- ❌ JSON序列化失败
- ❌ 数据格式错误

**示例日志：**
```
2024-12-02T10:30:15Z    ERROR    解析markdown表格失败    {"field_type": "request_params", "error": "无法解析表格：未找到表头", "content_preview": "..."}
```

## 🔎 日志关键词搜索

### 转换流程关键词
- `开始解析markdown表格` - 转换开始
- `markdown表格解析成功` - 解析完成
- `表格数据已转换为JSON格式` - JSON转换完成
- `转换后的JSON数据预览` - JSON数据详情

### 数据格式关键词
- `数据已经是JSON格式` - 数据源是JSON
- `从JSON对象中提取数组数据` - 从JSON对象提取
- `解析markdown表格并转换为JSON` - Markdown转JSON

### 错误关键词
- `解析markdown表格失败` - 解析错误
- `JSON序列化失败` - JSON错误
- `字段内容为空` - 空数据

## 📝 日志配置

确保日志级别设置为 `debug` 才能看到详细的JSON转换日志：

```yaml
# config.yaml 或 configs/env.development.yaml
logger:
    level: "debug"    # 开发环境使用debug级别
    format: "console" # 或 "json"
    output: "file"    # 输出到文件
    log_dir: "logs"   # 日志目录
    use_daily: true   # 启用按日分包
```

## 🛠️ 常用命令

```bash
# 查看今天的Info日志
cat logs/$(date +%Y-%m-%d)/info.log | grep "表格\|JSON"

# 查看最近的转换日志（最后50行）
tail -n 50 logs/$(date +%Y-%m-%d)/info.log

# 搜索特定产品的转换日志
grep "product_id.*xxx" logs/$(date +%Y-%m-%d)/info.log

# 查看所有错误
grep "ERROR" logs/$(date +%Y-%m-%d)/error.log

# 统计转换次数
grep "表格数据已转换为JSON格式" logs/$(date +%Y-%m-%d)/info.log | wc -l
```

## 💡 调试技巧

1. **查看完整JSON数据**：如果JSON数据超过1000字符，查看debug.log获取完整内容
2. **追踪转换流程**：使用 `field_type` 字段过滤特定字段的转换日志
3. **定位错误**：查看error.log中的 `content_preview` 字段了解原始数据
4. **性能监控**：统计转换次数和耗时，优化转换逻辑

## 📌 注意事项

- Debug级别日志可能包含大量数据，注意日志文件大小
- 生产环境建议使用 `info` 级别，减少日志量
- JSON预览限制在1000字符，完整数据请查看debug日志
- 日志文件按日期自动分包，便于管理和查找