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/ 目录：

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

🔍 如何查看转换日志

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

# 查看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查看

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

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

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

# 查看请求参数的转换日志
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转换日志：

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

🛠️ 常用命令

# 查看今天的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日志
• 日志文件按日期自动分包，便于管理和查找