87 lines
3.9 KiB
Markdown
87 lines
3.9 KiB
Markdown
# 尊祐客户分拣信息回传 - 产品需求文档
|
||
|
||
## 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为空时，回传应如何处理？ |