工单上游转发日志与自动转发排障
背景
工单上游转发已有当前状态字段,但前置条件未命中时静默返回,管理端无法判断工单是否提交、为何跳过或上游为何失败。本计划补齐工单级事件记录、状态摘要和管理端展示,并基于当前数据库排查自动转发未发生的原因。
范围与验收
- [ ] 工单转发跳过、入队、发送中、成功、失败和回复同步均可持久化查询。
- [ ] 管理端工单详情展示当前转发状态、尝试次数、上游工单号和失败原因,并可查看历史事件。
- [ ] 未配置、规则未命中、供应商开关关闭等原因不再静默。
- [ ] API 遵循统一 V2 响应和字段白名单,不泄露凭据、Token 或完整第三方响应。
- [ ] 后端定向回归测试、管理端构建通过。
实施步骤
- 只读核对当前数据库、队列运行配置和调度状态。
- 新增工单上游事件日志表、模型、资源和查询接口。
- 在投递 Service/Job 中记录决策、状态转移和失败原因。
- 在工单详情 API 和管理端详情页展示状态及日志。
- 执行迁移、定向测试、前端构建和文档校验。
风险与回滚
- 新表和新字段均采用追加迁移,不删除或改写历史工单数据。
- 日志只保存业务标识、中文原因和必要的 HTTP 状态/耗时,不保存敏感请求内容。
supplier_plugin_bindings.ticket_delivery_enabled仅作为历史兼容字段保留,不再参与工单推送判定;工单是否推送只由工单自动转发规则决定。- 若上游日志写入异常,不应阻断原有投递流程;事件写入采用独立安全记录并记录本地日志。
进度
- [x] 完成数据库与运行配置只读排查。
- [x] 完成事件日志与 API。
- [x] 完成管理端展示。
- [x] 移除供应商总开关管理入口,保留历史字段兼容。
- [x] 接入日志中心工单推送日志 channel。
- [ ] 完成规则唯一控制源的数据库回归测试(当前数据库服务不可用)。
- [x] 完成 callback token 统一、回调重新注册动作和入站回调日志。
- [x] 完成 PHP 语法、前端类型和管理端构建验证。
决策日志
| 日期 | 决策 | 原因 |
|---|---|---|
| 2026-08-20 | 旧供应商转发字段不作为工单推送开关 | 当时实库工单 73 因该字段为 0 被跳过;现改为规则唯一控制源,历史字段保留但不再参与运行时判定。 |
| 2026-08-20 | 使用追加式事件日志表 | 当前绑定表只保留最新状态,无法展示重试和跳过历史。 |
| 2026-08-20 | 管理端详情展示摘要并提供历史日志 | 复用现有工单详情权限和页面,避免继续依赖裸模型状态接口。 |
| 2026-08-20 | 历史工单 73 的旧跳过原因 | 当时工单的服务、部门和全部产品规则均可匹配,但旧 ticket_delivery_enabled=0;该字段现已不再参与运行时判定。 |
| 2026-08-20 | 不运行完整后端测试 | 用户要求停止测试;工单相关 29 个测试、5633 条断言已通过,完整套件未完成。 |
| 2026-08-21 | 规则作为工单推送唯一控制源 | 移除供应商编辑页总开关;ticket_delivery_rules.enabled 与部门、供应商、provider、产品范围共同决定工单是否推送。 |
| 2026-08-21 | 工单推送日志接入日志中心独立 channel | 复用 log.list 和 /api/v2/admin/logs/{channel},数据源仍为 ticket_upstream_delivery_logs,避免混入 activity 日志。 |
| 2026-08-21 | 历史未入队工单不自动补发 | 规则改为唯一控制源后,新工单按规则推送;历史因旧总闸跳过且没有 binding 的工单不自动重建上游工单,避免未经确认向上游重复提交。 |
| 2026-08-21 | 工单推送规则不再依赖供应商总闸 | 删除工单创建、回复、发送前和回调接收对 ticket_delivery_enabled 的运行时判断;供应商启用、provider、服务绑定和规则匹配仍保留。 |
| 2026-08-21 | 工单 649718 回调排查 | 出站注册返回“关联成功”、创建返回上游工单号;本地无入站回复。已统一 legacy token 真源,增加回调重新注册动作和入站成功/失败/重复日志。注册地址继续使用 APP_URL 根地址,符合 mf/zjmfv376 拼接 /api/ticket_reply/sync 的协议。服务 301 的旧 token 投影与确定性 token 一致,待通过重新注册动作验证上游回调。 |
| 2026-08-20 | 文档校验保留既有基线问题 | check_docs.mjs 仍报告其他历史文档未登记、experimental 状态不受当前校验器支持;本次新增执行计划已登记。 |
