# 普货箱规整理 SOP

## 目标

把物流普货 Excel 中的明细行整理成“商品名称 + 箱子数量 + 箱规 + 箱子号码”的汇总表，用于发货/装箱确认。

## 适用文件结构

Excel 默认读取第一个 sheet，表头需要包含：

| 字段 | 用途 |
|---|---|
| 商品名称 | 商品名、批次号或备注。真实商品名通常只在商品块第一行出现 |
| 颜色-尺码 | 颜色或尺码信息，整理箱规时不输出 |
| 希音SKU | 尺码或 SKU 信息，整理箱规时不输出 |
| 数量 | 原表数量，包含明细和商品块合计行 |
| 不求和 | 明细数量，箱规整理以此列累计，避免合计行重复计算 |
| 长M / 宽M / 高M | 箱规 |
| 体积 | 如原表填写则保留 |
| 箱子号码 | 遇到该字段时结算一行汇总 |

## 核心规则

1. 按行从上到下读取。
2. 遇到 `商品名称` 且不是 `YNxxxx`、不是包含 `洗水唛` 的备注时，识别为当前商品名。
3. 累加当前商品块中 `不求和` 列的明细数量。
4. 遇到 `箱子号码` 时，输出一行：
   - 当前商品名称
   - 从上一个箱子后累计到当前行的 `不求和` 数量
   - 当前行的 `长M / 宽M / 高M / 体积 / 箱子号码`
   - 来源行号
5. 输出后清空当前累计数量，继续读取下一段。
6. 原表 `数量` 列中的商品块合计行只用于校验，不参与汇总计算。

## 示例

原表：

```text
条纹亚麻女拖鞋  蓝色  39-40  10  10
YN0702          蓝色  40-41  10  10
                灰色  37-38  10  10
                灰色  39-40  10  10
                灰色  40-41  20  20  0.45  0.45  0.45  箱子1
```

输出：

```text
条纹亚麻女拖鞋，数量 60，0.45 × 0.45 × 0.45，箱子1
```

原表：

```text
女士亚麻拖鞋  黑色  37-38  25  25
YN0702              39-40  50  50  0.45  0.45  0.45  箱子2
                    40-41  25  25
                    42-43  20  20  0.4   0.4   0.4   箱子3
```

输出：

```text
女士亚麻拖鞋，数量 75，0.45 × 0.45 × 0.45，箱子2
女士亚麻拖鞋，数量 45，0.4 × 0.4 × 0.4，箱子3
```

## 校验项

服务会返回：

- `source_total`：原表 `不求和` 合计
- `output_total`：整理结果数量合计
- `quantity_matched`：两者是否一致
- `duplicate_boxes`：重复箱子号码
- `total_mismatches`：原表合计行和明细合计不一致的商品块
- `warnings`：存在数量但未遇到箱子号码等异常

## FastAPI 使用

### 启动

```bash
uvicorn logistics_service.app:app --host 0.0.0.0 --port 8020
```

浏览器打开：

```text
http://127.0.0.1:8020/
```

### 本地路径解析

```bash
curl -X POST http://127.0.0.1:8020/parse-path \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"/Users/sichang/Documents/NOON/合联物流/普货-0703.xlsx"}'
```

### 上传文件解析

```bash
curl -X POST http://127.0.0.1:8020/parse-upload \
  -F 'file=@/Users/sichang/Documents/NOON/合联物流/普货-0703.xlsx'
```

### 输出位置

默认输出到：

```text
outputs/logistics_service/
```

输出文件包括：

- `{原文件名}_箱规整理.csv`
- `{原文件名}_箱规整理.xlsx`

## 当前样例注意事项

`/Users/sichang/Documents/NOON/合联物流/普货-0703.xlsx` 中发现：

- `箱子4` 出现两次。
- `男士冰丝休闲五分裤，闪电图案` 灰色组明细合计为 `91`，但原表合计行写 `90`。整理结果按明细数量 `91` 输出。