上传源代码版本

.trae/specs/time_timestamp_conversion/spec.md

@@ -0,0 +1,78 @@
+# 时间戳转换 - Product Requirement Document
+
+## Overview
+- **Summary**: 将到货及出库模块接口文档中提到的所有时间字段从DateTime类型统一转换为long类型的毫秒时间戳（UTC），确保API接口文档与实际代码实现一致。
+- **Purpose**: 解决数据库中可null DateTime类型与API接口long类型时间戳之间的转换问题，提供一致的API接口体验。
+- **Target Users**: 后端开发人员、API调用方
+
+## Goals
+- 将出库交接单相关接口中的所有时间参数从DateTime?改为long?
+- 将返回实体中的所有时间字段转换为long?类型的时间戳
+- 保持文档与代码实现的一致性
+- 确保时间戳使用UTC时区
+
+## Non-Goals (Out of Scope)
+- 不修改数据库表结构
+- 不修改实体类的数据库映射属性
+- 不影响其他模块的接口
+
+## Background & Context
+根据接口文档要求，所有时间字段应使用long类型的毫秒时间戳（UTC）。目前代码中仍有部分接口使用DateTime类型，需要统一转换。
+
+## Functional Requirements
+- **FR-1**: 修改出库交接单控制器中的所有时间参数为long?类型
+- **FR-2**: 创建时间戳转换辅助方法，处理DateTime与long之间的双向转换
+- **FR-3**: 修改返回实体时的时间字段转换逻辑，确保所有返回的时间都是时间戳格式
+- **FR-4**: 修改到货交接单控制器中的时间参数（如果有）
+- **FR-5**: 修改袋牌相关接口中的时间字段（如果有）
+
+## Non-Functional Requirements
+- **NFR-1**: 转换逻辑必须处理null值情况
+- **NFR-2**: 时间戳必须使用UTC时区
+- **NFR-3**: 保持API向后兼容性（尽可能）
+
+## Constraints
+- **Technical**: .NET 6+, C#, ASP.NET Core
+- **Business**: 需要尽快完成，避免影响API调用方
+- **Dependencies**: 依赖现有代码结构
+
+## Assumptions
+- 所有时间戳都使用毫秒级精度
+- 所有时间戳都基于UTC时区
+- SqlSugar ORM能正确处理DateTime?类型的数据库映射
+
+## Acceptance Criteria
+
+### AC-1: 出库交接单创建接口时间参数转换
+- **Given**: 用户调用创建出库交接单接口
+- **When**: 传入deliveryTime参数
+- **Then**: 参数类型为long?，系统正确转换为DateTime?存储到数据库
+- **Verification**: `programmatic`
+
+### AC-2: 出库交接单确认接口时间参数转换
+- **Given**: 用户调用确认出库交接单接口
+- **When**: 传入deliveryTime参数
+- **Then**: 参数类型为long?，系统正确转换为DateTime?存储到数据库
+- **Verification**: `programmatic`
+
+### AC-3: 出库交接单列表查询接口时间参数转换
+- **Given**: 用户调用查询出库交接单列表接口
+- **When**: 传入startDeliveryTime和endDeliveryTime参数
+- **Then**: 参数类型为long?，系统正确转换为DateTime?进行查询
+- **Verification**: `programmatic`
+
+### AC-4: 返回实体时间字段转换
+- **Given**: 系统返回包含时间字段的实体数据
+- **When**: 序列化响应数据
+- **Then**: 所有DateTime类型字段都转换为long?类型的时间戳
+- **Verification**: `programmatic`
+
+### AC-5: 空值处理正确
+- **Given**: 时间字段为null
+- **When**: 进行转换
+- **Then**: 转换结果也为null，不抛出异常
+- **Verification**: `programmatic`
+
+## Open Questions
+- [ ] 是否需要修改其他模块的接口？
+- [ ] 是否需要添加单元测试？

.trae/specs/time_timestamp_conversion/tasks.md

@@ -0,0 +1,98 @@
+# 时间戳转换 - The Implementation Plan (Decomposed and Prioritized Task List)
+
+## [ ] Task 1: 创建时间戳转换辅助工具类
+- **Priority**: P0
+- **Depends On**: None
+- **Description**: 
+  - 创建一个静态辅助类，提供DateTime与long时间戳之间的双向转换方法
+  - 支持null值处理
+  - 确保使用UTC时区
+- **Acceptance Criteria Addressed**: AC-5
+- **Test Requirements**:
+  - `programmatic` TR-1.1: 验证DateTime转换为long时间戳正确
+  - `programmatic` TR-1.2: 验证long时间戳转换为DateTime正确
+  - `programmatic` TR-1.3: 验证null值处理正确
+- **Notes**: 参考ArrivalHandoverFormService.cs中的现有实现
+
+## [ ] Task 2: 修改出库交接单控制器 - 创建接口
+- **Priority**: P0
+- **Depends On**: Task 1
+- **Description**: 
+  - 修改CreateShippingHandoverForm方法，将DeliveryTime参数从DateTime?改为long?
+  - 使用辅助类转换参数后再赋值给实体
+- **Acceptance Criteria Addressed**: AC-1
+- **Test Requirements**:
+  - `programmatic` TR-2.1: 验证创建接口接受long?类型参数
+  - `programmatic` TR-2.2: 验证时间戳正确转换并存储
+
+## [ ] Task 3: 修改出库交接单控制器 - 确认接口
+- **Priority**: P0
+- **Depends On**: Task 1
+- **Description**: 
+  - 修改ConfirmShippingHandoverForm方法，将deliveryTime参数从DateTime?改为long?
+  - 使用辅助类转换参数
+- **Acceptance Criteria Addressed**: AC-2
+- **Test Requirements**:
+  - `programmatic` TR-3.1: 验证确认接口接受long?类型参数
+
+## [ ] Task 4: 修改出库交接单控制器 - 列表查询接口
+- **Priority**: P0
+- **Depends On**: Task 1
+- **Description**: 
+  - 修改GetShippingHandoverForms方法，将startDeliveryTime和endDeliveryTime参数从DateTime?改为long?
+  - 使用辅助类转换参数
+- **Acceptance Criteria Addressed**: AC-3
+- **Test Requirements**:
+  - `programmatic` TR-4.1: 验证列表查询接口接受long?类型参数
+
+## [ ] Task 5: 修改出库交接单控制器 - 更新接口
+- **Priority**: P0
+- **Depends On**: Task 1
+- **Description**: 
+  - 修改UpdateShippingHandoverForm方法，将DeliveryTime参数从DateTime?改为long?
+  - 使用辅助类转换参数
+- **Acceptance Criteria Addressed**: AC-1
+- **Test Requirements**:
+  - `programmatic` TR-5.1: 验证更新接口接受long?类型参数
+
+## [ ] Task 6: 修改返回实体的时间字段转换逻辑
+- **Priority**: P0
+- **Depends On**: Task 1
+- **Description**: 
+  - 修改所有返回实体数据的接口，不直接返回实体对象
+  - 创建匿名对象或DTO，将DateTime字段转换为long?时间戳
+  - 涉及的实体：ShippingHandoverFormEntity, BagTagEntity, ArrivalHandoverFormEntity
+- **Acceptance Criteria Addressed**: AC-4
+- **Test Requirements**:
+  - `programmatic` TR-6.1: 验证返回的时间字段是long?类型
+  - `programmatic` TR-6.2: 验证时间戳值正确
+
+## [ ] Task 7: 检查并修改到货交接单控制器
+- **Priority**: P1
+- **Depends On**: Task 1
+- **Description**: 
+  - 检查ArrivalHandoverFormController中的所有时间参数
+  - 确保所有时间参数和返回值都使用long?类型时间戳
+- **Acceptance Criteria Addressed**: AC-1, AC-4
+- **Test Requirements**:
+  - `programmatic` TR-7.1: 验证到货交接单接口时间参数正确
+
+## [ ] Task 8: 检查并修改袋牌相关接口
+- **Priority**: P1
+- **Depends On**: Task 1
+- **Description**: 
+  - 检查袋牌相关控制器中的时间字段
+  - 确保返回的BagTagEntity中的时间字段转换为long?时间戳
+- **Acceptance Criteria Addressed**: AC-4
+- **Test Requirements**:
+  - `programmatic` TR-8.1: 验证袋牌接口时间字段正确
+
+## [ ] Task 9: 验证文档与代码一致性
+- **Priority**: P1
+- **Depends On**: Task 2-8
+- **Description**: 
+  - 对比接口文档与实际代码实现
+  - 确保所有接口都符合文档要求
+- **Acceptance Criteria Addressed**: 所有AC
+- **Test Requirements**:
+  - `human-judgement` TR-9.1: 人工检查文档与代码一致性