feat: shipment customer aou

docs/shipment_api.md

@@ -6,6 +6,8 @@
 
 - [查询出货单](#查询出货单)
 - [创建出货单](#创建出货单)
+- [查询有待出货销售品的客户](#查询有待出货销售品的客户)
+- [按客户查询销售品](#按客户查询销售品)
 - [通过生产订单查询销售品](#通过生产订单查询销售品)
 
 ---
@@ -260,6 +262,137 @@
 
 ---
 
+## 查询有待出货销售品的客户
+
+查询当前商户下“存在未出货销售品”的客户列表。
+
+### 接口信息
+
+- **URL**: `/api/v1/shipment/sales-items/customers/`
+- **Method**: `GET`
+- **认证**: 需要登录（JWT Token）
+
+### 查询参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| limit | int | 否 | 分页大小（LimitOffsetPagination） |
+| offset | int | 否 | 偏移量 |
+
+### 业务逻辑
+
+1. 仅统计当前商户下的销售品
+2. 只统计 `shipment` 为空的销售品（未出货）
+3. 只返回至少拥有 1 条未出货销售品的客户
+4. 返回客户基础信息及未出货销售品数量
+
+### 响应格式
+
+```json
+{
+  "count": 2,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "customer_id": 12,
+      "customer_name": "客户A",
+      "mobile": "13800000000",
+      "area": "杭州",
+      "unshipped_sales_items_count": 18
+    }
+  ]
+}
+```
+
+### 响应字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| count | int | 结果总数 |
+| next | string/null | 下一页链接 |
+| previous | string/null | 上一页链接 |
+| results[].customer_id | int | 客户ID |
+| results[].customer_name | string | 客户名称 |
+| results[].mobile | string/null | 客户手机号 |
+| results[].area | string/null | 客户地区 |
+| results[].unshipped_sales_items_count | int | 该客户未出货销售品数量 |
+
+---
+
+## 按客户查询销售品
+
+查询指定客户下的销售品列表，默认仅返回未出货销售品。
+
+### 接口信息
+
+- **URL**: `/api/v1/shipment/sales-items/by-customer/<customer_id>/`
+- **Method**: `GET`
+- **认证**: 需要登录（JWT Token）
+
+### 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_id | int | 是 | 客户ID |
+
+### 查询参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| include_already_has_shipment | bool | 否 | false | 是否包含已关联出货单的销售品 |
+| limit | int | 否 | 800 | 分页大小 |
+| offset | int | 否 | 0 | 偏移量 |
+
+### 业务逻辑
+
+1. 仅允许查询当前商户下的客户
+2. 仅查询当前商户下、`customer_id` 匹配的销售品
+3. 默认只返回 `shipment` 为空的销售品（待出货）
+4. 可通过 `include_already_has_shipment=true` 包含已出货销售品
+
+### 响应格式
+
+```json
+{
+  "count": 2,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "id": 101,
+      "name": "赛扬 190g",
+      "quantity": "1200.00",
+      "unit": 1,
+      "unit_display": "米",
+      "position": "A1-01",
+      "remark": "",
+      "printing_job_id": 88,
+      "printing_order_id": 23,
+      "customer_id": 12,
+      "customer_name": "客户A",
+      "shipment_id": null,
+      "shipment_date": null,
+      "created_at": "2026-03-28T10:00:00Z",
+      "created_by_id": 1,
+      "created_by_name": "张三"
+    }
+  ]
+}
+```
+
+### 错误响应
+
+#### 404 Not Found - 客户不存在或无权限
+
+```json
+{
+  "detail": "客户 999 不存在"
+}
+```
+
+---
+
 ## 通过生产订单查询销售品
 
 查询与指定生产订单（PrintingOrder）关联的所有销售品（SalesItem）。
@@ -305,7 +438,9 @@
             "position": "A1-01",
             "remark": "加急处理",
             "printing_job_id": 123,
+            "printing_order_id": 456,
             "customer_id": null,
+            "customer_name": null,
             "shipment_id": null,
             "shipment_date": null,
             "created_at": "2026-01-14T10:00:00Z",
@@ -321,7 +456,9 @@
             "position": "",
             "remark": "",
             "printing_job_id": 124,
+            "printing_order_id": 456,
             "customer_id": 10,
+            "customer_name": "客户A",
             "shipment_id": 5,
             "shipment_date": "2026-01-13",
             "created_at": "2026-01-13T15:30:00Z",
@@ -346,7 +483,9 @@
 | results[].position | string | 货位（可能为空） |
 | results[].remark | string | 备注（可能为空） |
 | results[].printing_job_id | int/null | 关联的生产任务ID |
+| results[].printing_order_id | int/null | 关联的生产订单ID |
 | results[].customer_id | int/null | 销售品级别的客户ID |
+| results[].customer_name | string/null | 销售品关联客户名称 |
 | results[].shipment_id | int/null | 关联的出货单ID，null 表示未出货 |
 | results[].shipment_date | string/null | 出货日期（YYYY-MM-DD），null 表示未出货 |
 | results[].created_at | string | 创建时间（ISO 8601） |