# API v1：采购单绑定库存记录（独立功能）

本文档描述采购单绑定库存记录的接口与约束，并包含库存记录查询接口新增筛选参数说明。

- API 前缀：`/api/v1/`
- 认证：接口均要求登录（`IsAuthenticated`）。
- 权限：要求当前用户绑定员工（`request.user.employee`），否则返回 `403`。

---

## 1) 采购单绑定库存记录

- `POST /api/v1/purchase-orders/{purchase_order_id}/bind-stock-change/`

### 请求体参数（JSON）

- `stock_change_record_id`（必填，int）：库存变动记录 ID

### 成功响应

- `200 OK`

响应字段：

- `purchase_order_id`：采购单 ID
- `stock_change_record_id`：库存记录 ID
- `message`：绑定结果

### 约束与限制

- 仅当 `auto_create_stock_change_tasks = False` 才允许绑定
- 只能绑定 `source_id` 为空的库存记录（不允许覆盖）
- 库存记录必须满足：
  - `type = 入库`
  - `source_type = 采购`
- 采购单与库存记录必须 **同商户、同仓库**
- 采购单仅允许绑定 1 条库存记录（已绑定则拒绝）
- `is_finished` 不影响绑定行为（已完成也允许）
- 绑定操作会记录服务日志（便于审计追踪）

---

## 2) 库存记录查询（用于绑定前筛选）

> 该接口支持筛选“可绑定库存记录”所需条件，例如：`source_type=采购` 且 `source_id 为空`。

- `GET /api/v1/stock-changes/`

### 新增查询参数

- `source_type`（int，可选）：库存来源类型
- `source_id`（int，可选）：来源业务单据 ID
- `source_id_isnull`（bool，可选）：是否仅返回 `source_id` 为空的记录（`true/false`）
  - 若同时提供 `source_id`，以 `source_id` 为准，忽略 `source_id_isnull`

### 绑定场景示例

查询“可绑定的采购入库记录（source_id 为空）”：

- `GET /api/v1/stock-changes/?type=1&source_type=1&source_id_isnull=true&warehouse={warehouse_id}`

说明：
- `type=1` 表示入库
- `source_type=1` 表示采购
- `source_id_isnull=true` 表示未绑定业务单据
- `warehouse` 可选，用于约束同仓库