3.9 KiB
3.9 KiB
尊祐客户分拣信息回传 - 产品需求文档
Overview
- Summary: 为尊祐客户添加分拣信息回传功能，当系统处理标签替换请求时，向尊祐系统发送回传通知，包含面单号、跟踪号、替换状态和替换时间等信息。
- Purpose: 实现与尊祐系统的对接，确保尊祐能够及时获取标签替换的状态信息，便于其内部物流管理和跟踪。
- Target Users: 尊祐客户及其系统集成人员。
Goals
- 实现向尊祐系统的分拣信息回传功能
- 确保回传数据的准确性和及时性
- 与现有回传机制保持一致的代码风格和错误处理方式
- 提供必要的日志记录以便于问题排查
Non-Goals (Out of Scope)
- 不修改现有的其他客户回传逻辑
- 不改变系统的核心业务流程
- 不涉及尊祐系统内部的业务逻辑修改
Background & Context
- 系统已经实现了向派通国际(PT_GZ)和讯通系统(XT_JX)的回传功能
- 回传逻辑位于LabelController.cs的DownloadLabelByWaybillNumber方法中
- 回传采用异步方式，不阻塞主流程
- 尊祐系统提供了RESTful API接口用于接收回传数据
Functional Requirements
- FR-1: 当客户代码为ZY_SH时，向尊祐系统发送回传通知
- FR-2: 回传数据应包含面单号、跟踪号、替换状态和替换时间
- FR-3: 回传请求应包含指定的token认证信息
- FR-4: 回传应采用异步方式，不阻塞主流程
- FR-5: 回传失败时应记录错误日志，但不影响主流程
Non-Functional Requirements
- NFR-1: 回传请求应设置合理的超时时间，避免长时间阻塞
- NFR-2: 应提供详细的日志记录，便于问题排查
- NFR-3: 代码应遵循现有代码风格和架构模式
Constraints
- Technical: 使用现有的HttpClientFactory创建HttpClient实例
- Business: 必须使用尊祐提供的API地址和token
- Dependencies: 依赖现有的LabelReplaceEntity数据模型，需要从中获取跟踪号信息
Assumptions
- 尊祐系统的API接口能够正常接收和处理回传数据
- LabelReplaceEntity中包含了所需的跟踪号信息
- 系统能够正确获取客户代码ZY_SH的客户信息
Acceptance Criteria
AC-1: 尊祐客户回传触发
- Given: 系统处理尊祐客户(ZY_SH)的标签替换请求
- When: 标签下载完成后
- Then: 系统应向尊祐系统发送回传通知
- Verification:
programmatic - Notes: 回传应在finally块中异步执行
AC-2: 回传数据格式正确
- Given: 系统向尊祐系统发送回传通知
- When: 构造回传数据
- Then: 回传数据应符合尊祐系统要求的格式，包含WaybillNumber、TrackingNumber、Replaced和ReplacedAt字段
- Verification:
programmatic - Notes: Replaced字段应根据扫描结果判断，ReplacedAt应使用UTC时间
AC-3: 回传请求头正确
- Given: 系统向尊祐系统发送回传通知
- When: 构造HTTP请求
- Then: 请求头应包含指定的token认证信息
- Verification:
programmatic - Notes: token值为1c96499e-3c58-4e20-bc5d-b52ce9f9e36d
AC-4: 回传失败处理
- Given: 向尊祐系统发送回传通知失败
- When: 网络错误或尊祐系统返回错误
- Then: 系统应记录错误日志，但不影响主流程
- Verification:
human-judgment - Notes: 应使用与现有回传逻辑相同的错误处理方式
AC-5: 回传成功记录
- Given: 向尊祐系统发送回传通知成功
- When: 尊祐系统返回成功状态
- Then: 系统应记录成功日志
- Verification:
human-judgment - Notes: 应记录响应状态码和响应内容
Open Questions
- 尊祐系统对回传数据的具体验证规则是什么？
- 尊祐系统的API接口是否需要额外的认证或参数？
- 当TrackingNumber为空时，回传应如何处理？