ai-customer-service/docs/SNAPSHOT_DIFF_CHECKLIST_2026-05-08.md

# ai-customer-service 快照差异清单（2026-05-08）

## 背景

本清单用于比较以下两个目录，并给出后续合并策略：

- 主仓：`/home/long/project/ai-customer-service`
- 快照：`/home/long/project/ai-customer-service-lijiaoqiao-snapshot-2026-05-08`

目标不是整包回灌快照，而是只挑有明确工程价值的差异，避免把 `立交桥` 大仓里的分叉历史污染回主仓。

## 本轮已合并

这一组改动已回灌主仓，不再重复评估：

- [internal/service/platformevents/builder.go](/home/long/project/ai-customer-service/internal/service/platformevents/builder.go:34)
  - 事件时间从毫秒级顺延改为纳秒级顺延
  - `NextAttemptAt` 对齐到事件自身时间
- [internal/store/postgres/platform_event_store.go](/home/long/project/ai-customer-service/internal/store/postgres/platform_event_store.go:81)
  - `ListDue` 排序从 `next_attempt_at, created_at` 强化为
    `next_attempt_at, occurred_at, created_at, id`
- [internal/store/postgres/platform_event_store_test.go](/home/long/project/ai-customer-service/internal/store/postgres/platform_event_store_test.go:59)
  - 测试改为验证真实的顺序语义，而不是只比较插入次序

结论：这组改动有完整闭环，已经属于“已吸收差异”。

## 分类结果

## 逐项判定表

下表覆盖当前剩余差异的逐项处理结论，只使用两种状态：

- `保留主仓`：主仓内容继续作为唯一演进基线，不从快照回灌
- `仅归档`：快照内容只保留在快照目录中，供审计/回看，不进入主仓

| 路径 | 判定 | 备注 |
|------|------|------|
| `.git/` | `保留主仓` | 主仓独立 Git 仓库元数据 |
| `.gitea/` | `保留主仓` | 主仓仓库外壳配置 |
| `.github/` | `保留主仓` | 主仓 CI/模板配置 |
| `.tmp/` | `仅归档` | 快照运行期临时产物 |
| `CONTRIBUTING.md` | `保留主仓` | 主仓独有仓库文档 |
| `README.md` | `保留主仓` | 主仓独有仓库说明 |
| `docs/CODE_REVIEW_REPORT.md` | `保留主仓` | 已改为新路径口径 |
| `docs/MONITORING_ALERTING.md` | `保留主仓` | 已改为新路径口径 |
| `docs/PREPROD_VERIFICATION_RECORD.md` | `保留主仓` | 已改为新路径口径 |
| `docs/REVIEW_REPORT_2026-05-04.md` | `保留主仓` | 已改为新路径口径 |
| `docs/ROLLBACK_DRILL_RECORD.md` | `保留主仓` | 已改为新路径口径 |
| `docs/RUNBOOK.md` | `保留主仓` | 已改为新路径口径 |
| `docs/SHARED_PREPROD_ACCESS_HANDOFF_CHECKLIST.md` | `保留主仓` | 已改为新路径口径 |
| `docs/SNAPSHOT_DIFF_CHECKLIST_2026-05-08.md` | `保留主仓` | 主仓新增的差异收敛文档 |
| `docs/SUB2API_MINIMAL_WEBHOOK_MAPPING.md` | `保留主仓` | 已改为新路径口径 |
| `internal/domain/audit/audit.go` | `保留主仓` | 快照为更早版本，主要是格式/旧内容 |
| `internal/domain/audit/audit_test.go` | `保留主仓` | 快照未提供更强断言 |
| `internal/domain/error/cserrors/codes_test.go` | `保留主仓` | 主要是格式对齐差异 |
| `internal/domain/intent/intent.go` | `保留主仓` | 主要是常量对齐差异 |
| `internal/domain/session/session.go` | `保留主仓` | 主要是常量对齐差异 |
| `internal/domain/session/session_test.go` | `保留主仓` | 未发现新增行为覆盖 |
| `internal/domain/ticket/ticket.go` | `保留主仓` | 主要是 struct 对齐差异 |
| `internal/domain/ticket/ticket_test.go` | `保留主仓` | 未发现新增行为覆盖 |
| `internal/domain/ticketstats/stats.go` | `保留主仓` | 主要是格式差异 |
| `internal/http/handlers/health_handler_test.go` | `保留主仓` | 仅测试格式差异 |
| `internal/http/handlers/webhook_handler_test.go` | `保留主仓` | 仅末尾换行差异 |
| `internal/http/handlers/webhook_security_test.go` | `保留主仓` | 仅空行/格式差异 |
| `internal/platform/httpx/limits_test.go` | `保留主仓` | 未发现更强断言 |
| `internal/service/dialog/service_test.go` | `保留主仓` | 主要是格式差异 |
| `internal/service/reply/service_test.go` | `保留主仓` | 主要是格式差异 |
| `internal/store/postgres/platform_event_store_test.go` | `保留主仓` | 顺序语义部分已吸收，其余不再单独回灌 |
| `prd/GRAY_RELEASE_ROLLBACK_RUNBOOK.md` | `保留主仓` | 已改为新路径口径 |
| `test/QA_CHECKLIST.md` | `保留主仓` | 已改为新路径口径 |
| `test/e2e/sub2api_callback_flow_test.go` | `保留主仓` | 快照版放宽断言，不回灌 |
| `test/integration/dialog_service_test.go` | `保留主仓` | 主要是格式差异 |
| `test/integration/ticket_stats_handler_test.go` | `保留主仓` | 主要是格式差异 |

附加说明：

- 快照目录本身 `ai-customer-service-lijiaoqiao-snapshot-2026-05-08/` 的整体状态是 `仅归档`
- 已并入主仓的两份快照独有文档不再列为“剩余差异”：
  - [REMEDIATION_TASK_BOARD_2026-05-06.md](/home/long/project/ai-customer-service/docs/REMEDIATION_TASK_BOARD_2026-05-06.md:1)
  - [REVIEW_REPORT_2026-05-06.md](/home/long/project/ai-customer-service/docs/REVIEW_REPORT_2026-05-06.md:1)

### 1. 旧版本 / 不合并

这些差异要么明显更旧，要么只是格式变化，要么会削弱现有严格约束，不建议继续回灌。

#### 纯格式或对齐差异

- [internal/domain/intent/intent.go](/home/long/project/ai-customer-service/internal/domain/intent/intent.go:1)
- [internal/domain/session/session.go](/home/long/project/ai-customer-service/internal/domain/session/session.go:1)
- [internal/domain/ticket/ticket.go](/home/long/project/ai-customer-service/internal/domain/ticket/ticket.go:1)
- [internal/domain/audit/audit.go](/home/long/project/ai-customer-service/internal/domain/audit/audit.go:1)
- [test/integration/ticket_stats_handler_test.go](/home/long/project/ai-customer-service/test/integration/ticket_stats_handler_test.go:1)
- [internal/domain/error/cserrors/codes_test.go](/home/long/project/ai-customer-service/internal/domain/error/cserrors/codes_test.go:1)
- [internal/http/handlers/webhook_handler_test.go](/home/long/project/ai-customer-service/internal/http/handlers/webhook_handler_test.go:1)
- [internal/http/handlers/webhook_security_test.go](/home/long/project/ai-customer-service/internal/http/handlers/webhook_security_test.go:1)
- [internal/http/handlers/health_handler_test.go](/home/long/project/ai-customer-service/internal/http/handlers/health_handler_test.go:1)
- [internal/platform/httpx/limits_test.go](/home/long/project/ai-customer-service/internal/platform/httpx/limits_test.go:1)
- [internal/service/dialog/service_test.go](/home/long/project/ai-customer-service/internal/service/dialog/service_test.go:1)
- [internal/service/reply/service_test.go](/home/long/project/ai-customer-service/internal/service/reply/service_test.go:1)
- [internal/domain/audit/audit_test.go](/home/long/project/ai-customer-service/internal/domain/audit/audit_test.go:1)
- [internal/domain/session/session_test.go](/home/long/project/ai-customer-service/internal/domain/session/session_test.go:1)
- [internal/domain/ticket/ticket_test.go](/home/long/project/ai-customer-service/internal/domain/ticket/ticket_test.go:1)
- [internal/domain/ticketstats/stats.go](/home/long/project/ai-customer-service/internal/domain/ticketstats/stats.go:1)
- [test/integration/dialog_service_test.go](/home/long/project/ai-customer-service/test/integration/dialog_service_test.go:1)

判断依据：

- diff 主要表现为字段对齐、空行、表格对齐、末尾换行等
- 未发现新增业务分支、校验逻辑或更严格的断言
- 快照时间普遍更早，不构成“新逻辑来源”

#### 不应回灌的测试放宽

- [test/e2e/sub2api_callback_flow_test.go](/home/long/project/ai-customer-service/test/e2e/sub2api_callback_flow_test.go:1)

不回灌原因：

- 快照版删除了 `resetE2EPlatformDB`
- 快照版去掉了更严格的顺序断言，改成“事件集合存在即可”
- 快照版把 dead-letter 断言从精确数量收窄成 `> 0`

这会降低主仓对“顺序稳定”和“事件数量精确性”的要求，不适合直接合并。

#### 仓库外壳与临时文件

- `.tmp/`
- `.gitea/`
- `.github/`
- `README.md`
- `CONTRIBUTING.md`

处理建议：

- `.tmp/` 明显属于临时产物，不合并
- `.gitea/.github/README/CONTRIBUTING` 属于仓库外壳差异，和本轮业务逻辑 merge 无关，单独处理

### 2. 仅文档口径差异

这些文件主要是路径从旧目录切到新目录、审查范围说明、运行记录引用变化。它们不涉及业务逻辑。

- [docs/CODE_REVIEW_REPORT.md](/home/long/project/ai-customer-service/docs/CODE_REVIEW_REPORT.md:1)
- [docs/MONITORING_ALERTING.md](/home/long/project/ai-customer-service/docs/MONITORING_ALERTING.md:1)
- [docs/PREPROD_VERIFICATION_RECORD.md](/home/long/project/ai-customer-service/docs/PREPROD_VERIFICATION_RECORD.md:1)
- [docs/REVIEW_REPORT_2026-05-04.md](/home/long/project/ai-customer-service/docs/REVIEW_REPORT_2026-05-04.md:1)
- [docs/ROLLBACK_DRILL_RECORD.md](/home/long/project/ai-customer-service/docs/ROLLBACK_DRILL_RECORD.md:1)
- [docs/RUNBOOK.md](/home/long/project/ai-customer-service/docs/RUNBOOK.md:1)
- [docs/SHARED_PREPROD_ACCESS_HANDOFF_CHECKLIST.md](/home/long/project/ai-customer-service/docs/SHARED_PREPROD_ACCESS_HANDOFF_CHECKLIST.md:1)
- [docs/SUB2API_MINIMAL_WEBHOOK_MAPPING.md](/home/long/project/ai-customer-service/docs/SUB2API_MINIMAL_WEBHOOK_MAPPING.md:1)
- [prd/GRAY_RELEASE_ROLLBACK_RUNBOOK.md](/home/long/project/ai-customer-service/prd/GRAY_RELEASE_ROLLBACK_RUNBOOK.md:1)
- [test/QA_CHECKLIST.md](/home/long/project/ai-customer-service/test/QA_CHECKLIST.md:1)

说明：

- 这些文件里旧路径已经在主仓改到新位置
- 快照中的文档差异本质上不再构成 merge 任务
- 两份快照独有文档已另行并入主仓：
  - [REMEDIATION_TASK_BOARD_2026-05-06.md](/home/long/project/ai-customer-service/docs/REMEDIATION_TASK_BOARD_2026-05-06.md:1)
  - [REVIEW_REPORT_2026-05-06.md](/home/long/project/ai-customer-service/docs/REVIEW_REPORT_2026-05-06.md:1)

### 3. 值得继续 cherry-pick 的少量代码改动

本轮筛查后，剩余差异里没有发现第二组像“平台事件顺序稳定性”那样成体系、且明显优于主仓现状的代码改动。

当前结论：

- **已确认并合并的唯一高价值代码组**：平台事件顺序稳定性
- **剩余代码差异**：暂时归为旧版本/格式差异/测试放宽，不建议继续自动 cherry-pick

## 建议的后续动作

### 立即可做

1. 保留快照目录，不删除：
   `/home/long/project/ai-customer-service-lijiaoqiao-snapshot-2026-05-08`
2. 把本清单作为后续 merge 的唯一入口，避免重新做全量 diff

### 只有在出现明确需求时再做

1. 如果要恢复 `sub2api adapter` 方向的某一块能力，再按文件逐个重看快照中的：
   - `internal/store/postgres/platform_event_store_test.go`
   - `test/e2e/sub2api_callback_flow_test.go`
   - `internal/service/platformevents/builder.go`
2. 如果要统一仓库外壳，再单独比较：
   - `.gitea/`
   - `.github/`
   - `README.md`
   - `CONTRIBUTING.md`

## 当前结论

快照已经完成了它该做的事：

- 作为迁移前的完整保底副本
- 提供了一组已成功吸收的高价值顺序修复
- 其余差异不值得继续大范围回灌

因此，后续策略应当是：

- **主仓继续前进**
- **快照只保留作审计和按需检索**
- **不再做整包式合并**