# 收货扫描记录表（arrival_scan_records）设计与实现计划

## 一、背景分析

当前 `ArrivalHandoverFormController` 的 `/api/arrival-handover/receipt-query` 接口（[ArrivalHandoverFormController.cs:L447-L495](file:///d:/EPproject/LabelReplaceServer/src/CONTROLLER/Controllers/ArrivalHandoverFormController.cs#L447-L495)）用于 PDA 收货扫描查询。

`ArrivalHandoverFormService.GetReceiptInfoAsync` 方法（[ArrivalHandoverFormService.cs:L181-L281](file:///d:/EPproject/LabelReplaceServer/src/BLL/Services/ArrivalHandoverFormService.cs#L181-L281)）的核心逻辑：
- 接收 `arrivalNumber`（大箱号或提单号）
- 在 `label_replace_requests` 表中按 `BillOfLadingNumber` 或 `MasterPackageNumber` 匹配
- 返回 `(packageCount, labelRate, arrivalTime, billOfLadingNumber, masterPackageNumber)`
- 同时自动创建/更新 `arrival_handover_forms` 记录

**需要新增**：PDA 每次扫描收货时，将扫描记录持久化到一张独立的记录表中，便于后续追溯和统计。

---

## 二、表结构设计

### 表名：`arrival_scan_records`

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `Id` | INT UNSIGNED | PK, AUTO_INCREMENT | 主键 |
| `ArrivalNumber` | VARCHAR(100) | NOT NULL | PDA扫描的大箱号（即 request.ArrivalNumber） |
| `CustomerId` | INT | NULL | 客户ID（冗余字段，关联 customers 表） |
| `BillOfLadingNumber` | VARCHAR(100) | NULL | 提单号 |
| `MasterPackageNumber` | VARCHAR(100) | NULL | 大箱号 |
| `CreatedAt` | DATETIME | NOT NULL | PDA收货扫描时间（创建时间） |
| `UpdatedAt` | DATETIME | NOT NULL | 更新时间 |

### 索引设计

| 索引名 | 字段 | 用途 |
|--------|------|------|
| `idx_arrival_number` | ArrivalNumber | 按扫描号查询历史记录 |
| `idx_created_at` | CreatedAt | 按时间范围统计查询 |
| `idx_customer_id` | CustomerId | 按客户维度查询 |

### 设计说明

1. **ArrivalNumber** 对应 PDA 扫描时传入的 `request.ArrivalNumber`，是本次扫描的核心标识
2. **CustomerId** 为冗余字段，从 `label_replace_requests` 表中获取，便于按客户维度查询，避免每次查询都要 JOIN
3. **BillOfLadingNumber / MasterPackageNumber** 从 `GetReceiptInfoAsync` 返回值中获取
4. **CreatedAt** 即为 PDA 收货扫描时间
5. 遵循项目现有的命名规范和注解风格（PascalCase 属性名 + `[SugarColumn]` 注解）

---

## 三、实现步骤

### 步骤 1：创建 SQL 建表脚本

**文件**：`src/DB/Scripts/CreateArrivalScanRecordTable.sql`

参考 [CreateLabelReplaceTable.sql](file:///d:/EPproject/LabelReplaceServer/src/DB/Scripts/CreateLabelReplaceTable.sql) 的格式：
- InnoDB 引擎
- utf8mb4 字符集
- 包含中文注释
- 创建必要索引

### 步骤 2：创建 Entity 实体类

**文件**：`src/MDL/Models/ArrivalScanRecordEntity.cs`

参考 [LabelScanEntity.cs](file:///d:/EPproject/LabelReplaceServer/src/MDL/Models/LabelScanEntity.cs) 和 [LabelReplaceEntity.cs](file:///d:/EPproject/LabelReplaceServer/src/MDL/Models/LabelReplaceEntity.cs) 的写法：
- `[SugarTable("arrival_scan_records")]`
- `[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]` 主键
- 时间字段默认值 `DateTime.UtcNow`
- 完整的中文 XML 注释

### 步骤 3：创建 Repository 仓库层

**文件**：
- `src/DAL/Interfaces/IArrivalScanRecordRepository.cs` — 接口定义
- `src/DAL/Repositories/ArrivalScanRecordRepository.cs` — 实现

参考 [CustomerRepository.cs](file:///d:/EPproject/LabelReplaceServer/src/DAL/repositories/CustomerRepository.cs) 的模式：
- 通过 `ISqlSugarProvider` 操作数据库
- 至少需要 `InsertAsync` 方法

### 步骤 4：修改 ArrivalHandoverFormService

**文件**：`src/BLL/Services/ArrivalHandoverFormService.cs`

在 `GetReceiptInfoAsync` 方法中，查询完成后插入一条扫描记录到 `arrival_scan_records` 表：

```csharp
// 在 return 之前插入扫描记录
var scanRecord = new ArrivalScanRecordEntity
{
    ArrivalNumber = arrivalNumber,
    CustomerId = labelReplaceEntities.FirstOrDefault()?.CustomerId,
    BillOfLadingNumber = billOfLadingNumber,
    MasterPackageNumber = masterPackageNumber,
    CreatedAt = DateTime.UtcNow,
    UpdatedAt = DateTime.UtcNow
};
await db.Insertable(scanRecord).ExecuteCommandAsync();
```

**关键点**：
- `CustomerId` 从 `label_replace_entities` 的第一个匹配记录中获取（冗余存储）
- 插入操作应在 try-catch 内部，且不应影响主流程（即使插入失败也不应阻止接口正常返回）
- 建议用独立的 try-catch 包裹插入逻辑，避免扫描记录入库失败导致接口报错

### 步骤 5：注册依赖注入

**文件**：`src/CONTROLLER/Program.cs`（或对应的 DI 注册文件）

- 注册 `IArrivalScanRecordRepository` → `ArrivalScanRecordRepository`
- 在 `ArrivalHandoverFormService` 构造函数中注入（如需要）

> **可选简化方案**：由于 `ArrivalHandoverFormService` 已经持有 `ISqlSugarProvider`，可以直接通过 `_provider.GetClient()` 操作数据库，无需单独创建 Repository。是否需要独立 Repository 取决于项目的分层规范。

---

## 四、文件清单

| 文件 | 操作 | 说明 |
|------|------|------|
| `src/DB/Scripts/CreateArrivalScanRecordTable.sql` | **新增** | 建表 SQL 脚本 |
| `src/MDL/Models/ArrivalScanRecordEntity.cs` | **新增** | 实体类 |
| `src/DAL/Interfaces/IArrivalScanRecordRepository.cs` | **新增** | 仓库接口 |
| `src/DAL/Repositories/ArrivalScanRecordRepository.cs` | **新增** | 仓库实现 |
| `src/BLL/Services/ArrivalHandoverFormService.cs` | **修改** | 在 GetReceiptInfoAsync 中插入扫描记录 |
| `src/CONTROLLER/Program.cs` | **修改** | 注册 DI（如需独立 Repository） |

---

## 五、待确认事项

1. **Repository 分层**：是否需要创建独立的 Repository，还是直接在 Service 中通过 `ISqlSugarProvider` 操作？（推荐后者，与现有模式一致，因为 `ArrivalHandoverFormService` 已经直接使用 `_provider.GetClient()` 操作数据库）
2. **插入时机**：是否仅在 Mock 数据分支（TEST 开头的 arrivalNumber）不插入？建议仅在实际数据库查询成功后插入。
3. **错误处理策略**：扫描记录插入失败时，是静默忽略（不影响接口返回）还是抛出异常？建议静默忽略，确保核心业务不受影响。