为会话日志设计健壮的版本升级机制，采用单调递增整数版本、升级…

# 客服机器人日志 v3→v4 平滑升级方案

一、版本设计

• 新增字段：emotion_label（如：positive / negative / neutral / angry），旧数据迁移时填默认值 neutral 或 unknown
• 拆分用户消息事件：v3 中一条会话含多条用户消息；v4 将每条用户消息拆为独立事件，共享 session_id，新增 event_seq 序号、event_type: "user_message"
• 字段兼容原则：v4 解析器向下兼容 v3 结构，通过 schema_version 字段区分处理

二、解析容错机制

• 逐行读取 JSONL，单条解析失败时：
• 记录该行行号与原始内容到 dead_letter.jsonl（死信文件）
• 输出告警日志，继续处理后续行
• 每日输出处理报告：成功数、跳过数、失败率

参考伪代码

```python

import json

def process_v3_to_v4(line, lineno):

try:

rec = json.loads(line)

except json.JSONDecodeError:

write_dead_letter(lineno, line) # 跳过，不中断

return None

events = []

for i, msg in enumerate(rec.get("user_messages", [])):

events.append({

"schema_version": "v4",

"session_id": rec["session_id"],

"event_seq": i,

"event_type": "user_message",

"content": msg.get("content", ""),

"emotion_label": classify_emotion(msg), # 兜底默认 unknown

"ts": msg.get("ts")

})

return events

```

三、迁移策略（20万条/天规模）

• 双写过渡：升级期间新旧格式并行写 1–2 周，下游逐步切换
• 增量迁移：新增数据直接写 v4；存量按日期分批回填（每日一个批次，可断点续跑）
• 幂等设计：以 session_id + event_seq 为唯一键，重跑不产生重复
• 回滚预案：保留 v3 原始文件只读归档，发现问题可快速切回

四、上线步骤

1. 灰度：抽样小比例流量跑 v4 解析器，比对双写结果一致性

2. 全量新数据切换至 v4 写入

3. 存量 v3 日离线回填（错峰执行，避免高峰资源争抢）

4. 死信队列人工/脚本复核后重放

5. 观察稳定后下线 v3 解析逻辑

五、注意事项

• 情绪标签建议先规则/词典粗标，后续再接入模型精标，避免迁移期阻塞
• 迁移脚本需限流（如每秒处理 N 行），防止打满存储 IO
• 监控指标：解析失败率、死信堆积量、回填进度