# 采购到货单 - 页面设计开发说明文档

> 版本: 1.0.0  
> 创建日期: 2026-02-13  
> 更新日期: 2026-02-13  
> 来源系统: 升阳云ERP 演示系统  
> 所属模块: 采购管理 > 采购到货单  
> 前端路由: `/purchasing/checkin`  
> **关联文档**: [erp数据库设计-数据字典](db/erp数据库设计-数据字典.md)（采购管理模块表与字段映射）；[mom系统采购订单-页面开发说明文档](mom系统采购订单-页面开发说明文档.md)（上游单据）

---

## 目录

0. [业务流程总览](#0-业务流程总览)
1. [页面概述](#1-页面概述)
2. [页面结构](#2-页面结构)
3. [列表页设计](#3-列表页设计)
4. [新增/编辑页设计](#4-新增编辑页设计)
5. [数据字段定义](#5-数据字段定义)
6. [按钮操作说明](#6-按钮操作说明)
7. [页面交互规则](#7-页面交互规则)
8. [接口调用说明](#8-接口调用说明)
9. [状态流转](#9-状态流转)
10. [业务规则](#10-业务规则)
11. [前端组件设计](#11-前端组件设计)
12. [数据模型](#12-数据模型)

---

## 0. 业务流程总览

### 0.1 采购到货单在 ERP 中的定位

采购到货单是**采购订单→到货登记→入库**链条中的核心登记单据，承接采购订单的采购指令，记录供应商交付物料的到货信息，下游驱动采购入库、质检入库。

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  销售订单    │────►│ 生产计划单   │────►│ 采购计划单   │────►│  采购订单    │
│              │     │ + BOM运算    │     │ (物料需求)   │     │ (执行采购)   │
└──────────────┘     └──────────────┘     └──────────────┘     └──────┬───────┘
                                                                      │ 引入
                                                                      ▼
                                                               ┌──────────────┐
                                                               │ ★ 采购到货单 │
                                                               │ (到货登记)   │
                                                               └──────┬───────┘
                                                                      │ 入库
                                                                      ▼
                                                               ┌──────────────┐
                                                               │  采购入库单  │
                                                               │ (库存增加)   │
                                                               └──────────────┘
```

### 0.2 端到端业务流程

```
 采购订单(已审核)
       │ 引入（采购订单物料明细）
       ▼
 ┌─────────────────┐     选择供应商      ┌─────────────────┐
 │ ★ 采购到货单     │ ◄───────────────── │ 原料供应商档案   │
 │  - 表头+供应商   │                    │                 │
 │  - 物料明细子表  │                    └─────────────────┘
 │  - 到货数量      │
 └────────┬────────┘
          │ 保存 → 审核
          ▼
 ┌─────────────────┐
 │  采购入库单      │ ──► 库存增加
 │  - 入库仓库      │
 │  - 入库数量      │
 └─────────────────┘
```

### 0.3 采购到货单内部业务流程

| 阶段 | 操作 | 触发条件 | 结果 |
|------|------|----------|------|
| 1. 新建 | 点击「新增」 | 始终可用 | 打开新增页，编码自动生成，状态=开立 |
| 2. 引入 | 点击「引入」→ 弹窗「采购订单明细」→ 勾选 → 确定 | 新增/编辑状态 | 物料明细子表填充：跟单编号、订单编码、物料、订单数量、到货数量 |
| 3. 选择仓库 | 点击仓库选择 | 新增/编辑页 | 表头填充仓库信息 |
| 4. 保存 | 点击「保存」 | 至少1条物料明细 | 数据持久化 |
| 5. 审核 | 点击「审核」 | 开立状态，已保存 | 状态→审核，记录审核员/日期；**审核后可生成入库单** |
| 6. 反审核 | 点击「反审核」 | 审核状态，无下游入库单 | 状态→开立 |
| 7. 删除 | 操作列「删除」或批量删除 | 开立状态 | 逻辑删除 |

### 0.4 上下游单据关系

| 上游单据 | 关联字段 | 说明 |
|----------|----------|------|
| 采购订单 | order_id, order_code | 引入弹窗「采购订单明细」|
| 供应商 | supplier_id, supplier_name | 引入时从采购订单带入或手动选择 |

| 下游单据 | 关联字段 | 说明 |
|----------|----------|------|
| 采购入库单 | checkin_id, checkin_code | 到货审核后生成入库单 |

### 0.5 关键数量逻辑

| 字段 | 含义 | 计算/来源 |
|------|------|-----------|
| 订单数量 (order_quantity) | 采购订单中的数量 | 引入时从采购订单带入，只读 |
| 到货数量 (quantity) | 本次实际到货数量 | 引入后可修改，默认等于订单数量 |
| 已入库数量 (stocked_quantity) | 已执行入库的数量 | 从入库单回写，只读 |
| 总到货数量 (total_quantity) | 到货单总到货数量 | 明细行到货数量合计 |

---

## 1. 页面概述

### 1.1 功能说明

采购到货单页面用于管理企业的采购到货登记。采购到货单是采购订单与入库操作之间的桥梁，采购员根据供应商实际交货情况登记到货物料及数量，审核后驱动仓库入库操作。

### 1.2 业务场景

- **引入采购订单**: 从已审核的采购订单引入物料明细（订单编码、跟单编号、物料、订单数量等），填写实际到货数量
- **到货登记**: 登记供应商的物料交付信息，支持分批次到货（同一采购订单可多次到货）
- **审核流程**: 到货单审核后不可编辑，审核后方可生成入库单
- **入库跟踪**: 跟踪每个到货物料的入库进度（到货数量 vs 已入库数量）

### 1.3 URL路由参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| - | - | 列表页无特殊参数 |

---

## 2. 页面结构

### 2.1 整体布局

```
┌─────────────────────────────────────────────────────────────────┐
│                     顶部导航栏 (64px)                            │
├────────┬────────────────────────────────────────────────────────┤
│ 左侧   │  面包屑: 首页 / 采购管理 / 采购到货单                    │
│ 菜单   │  ┌────────────────────────────────────────────────┐    │
│ (200px)│  │ Tab标签: ● 采购到货单                           │    │
│        │  ├────────────────────────────────────────────────┤    │
│ 采购管 │  │ 查询区域 (搜索条件)                              │    │
│ 理     │  ├────────────────────────────────────────────────┤    │
│ ├原料  │  │ 工具栏 (操作按钮)                                │    │
│  供应  │  ├────────────────────────────────────────────────┤    │
│  商    │  │ 数据表格                                        │    │
│ ├采购  │  ├────────────────────────────────────────────────┤    │
│  订单  │  │ 底部统计 (到货数量/入库数量汇总) + 分页组件       │    │
│ ├到货  │  └────────────────────────────────────────────────┘    │
│  单★  │                                                       │
│ ├采购  │                                                       │
│  发票  │                                                       │
│ ├退货  │                                                       │
│  单    │                                                       │
├────────┴────────────────────────────────────────────────────────┤
```

### 2.2 页面模式

| 模式 | 说明 | 入口 |
|------|------|------|
| 列表页 - 明细视图 | **默认视图**，以物料维度展示到货信息，含跟单编号/供应商/物料/到货数量/入库数量 | 菜单点击「采购到货单」 |
| 列表页 - 单据视图 | 以单据维度展示列表，侧重单据流程管理，含批量操作 | 明细视图点击「单据」按钮 |
| 新增页 | 新建采购到货单 | 列表页点击「新增」 |
| 编辑页 | 修改采购到货单（仅开立状态） | 单据视图「编辑」按钮 |
| 查看页 | 只读查看到货单详情（含入库进度） | 单据视图「查看」按钮 |

### 2.3 列表页双视图概述

列表页提供 **明细视图** 和 **单据视图** 两种展示模式，通过工具栏按钮相互切换：

| 对比项 | 明细视图（默认） | 单据视图 |
|--------|-----------------|---------|
| 切换按钮 | 工具栏显示「单据」按钮 | 工具栏显示「明细」按钮 |
| 复选框列 | 无 | 有 |
| 序号列 | 有 | 无 |
| 搜索条件 | 跟单编号、单据编码、供应商、物料编码、物料名称、日期范围 | 单据编码、单据状态、供应商、日期范围 |
| 工具栏按钮 | 单据、查询所有、新增、导出 | 明细、查询所有、新增、删除、审核、反审核 |
| 数据列 | 序号、跟单编号、单据编码、单据状态、供应商、物料名称、物料编码、到货数量、入库数量、单据日期 | 单据编码、单据日期、单据状态、供应商、采购订单号、仓库、业务状态、审核日期、操作 |
| 操作列 | 无（单据编码可点击查看详情） | 查看、编辑、删除 |
| 批量操作 | 不支持 | 支持（删除、审核、反审核） |
| 底部统计 | 到货数量、入库数量汇总 | 到货数量、入库数量汇总 |

---

## 3. 列表页设计

### 3.1 明细视图（默认视图）

明细视图是进入采购到货单页面时的默认视图，侧重于展示到货物料信息。

#### 3.1.1 搜索条件区域

| 序号 | 字段名 | 标签 | 组件类型 | 宽度 | 说明 |
|------|--------|------|----------|------|------|
| 1 | trackCode | 跟单编号 | el-input | 140px | 模糊搜索 |
| 2 | checkinCode | 单据编码 | el-input | 140px | 模糊搜索 |
| 3 | supplierName | 供应商 | el-input | 150px | 模糊搜索 |
| 4 | itemCode | 物料编码 | el-input | 140px | 模糊搜索 |
| 5 | itemName | 物料名称 | el-input | 140px | 模糊搜索 |
| 6 | beginDate | 开始日期 | el-date-picker | 140px | 日期范围起 |
| 7 | endDate | 结束日期 | el-date-picker | 140px | 日期范围止 |

#### 3.1.2 工具栏按钮

| 序号 | 按钮名称 | 图标 | 类型 | 说明 |
|------|----------|------|------|------|
| 1 | 单据 | - | primary | 切换到单据视图 |
| 2 | 查询所有 | - | default | 重置搜索条件并查询所有 |
| 3 | 新增 | el-icon-plus | primary | 打开新增到货单页面 |
| 4 | 导出 | el-icon-download | success | 导出到货单列表到Excel |

#### 3.1.3 数据表格列定义

| 序号 | 列标题 | 字段名 | 宽度 | 对齐 | 说明 |
|------|--------|--------|------|------|------|
| 1 | 序号 | - | 60px | center | 自动编号（无复选框） |
| 2 | 跟单编号 | trackCode | 130px | left | 取明细行首行的跟单编号 |
| 3 | 单据编码 | checkinCode | 140px | left | 蓝色链接，可点击打开详情 |
| 4 | 单据状态 | status | 90px | center | 状态标签（开立=灰色, 审核=绿色） |
| 5 | 供应商 | supplierName | 180px | left | 供应商名称 |
| 6 | 物料名称 | itemName | 150px | left | 取明细行首行物料名称 |
| 7 | 物料编码 | itemCode | 120px | left | 取明细行首行物料编码 |
| 8 | 到货数量 | totalQuantity | 100px | right | 总到货数量 |
| 9 | 入库数量 | stockedQuantity | 100px | right | 已入库数量 |
| 10 | 单据日期 | checkinDate | 110px | center | 到货日期 |

### 3.2 单据视图

单据视图侧重于到货单的单据流程管理，支持批量操作（审核、反审核、删除）。

#### 3.2.1 搜索条件区域

| 序号 | 字段名 | 标签 | 组件类型 | 宽度 | 说明 |
|------|--------|------|----------|------|------|
| 1 | checkinCode | 单据编码 | el-input | 140px | 模糊搜索 |
| 2 | status | 单据状态 | el-select | 120px | 下拉选择，可清空 |
| 3 | supplierName | 供应商 | el-input | 150px | 模糊搜索 |
| 4 | beginDate | 开始日期 | el-date-picker | 140px | 日期范围起 |
| 5 | endDate | 结束日期 | el-date-picker | 140px | 日期范围止 |

**单据状态选项:**

| 值 | 标签 | 标签颜色 |
|----|------|----------|
| DRAFT | 开立 | info (灰色) |
| APPROVED | 审核 | success (绿色) |

#### 3.2.2 工具栏按钮

| 序号 | 按钮名称 | 图标 | 类型 | 说明 |
|------|----------|------|------|------|
| 1 | 明细 | - | primary | 切换到明细视图 |
| 2 | 查询所有 | - | default | 重置搜索条件并查询所有 |
| 3 | 新增 | el-icon-plus | primary | 打开新增到货单页面 |
| 4 | 删除 | el-icon-delete | danger | 批量删除选中记录（需勾选） |
| 5 | 审核 | el-icon-check | success | 批量审核选中记录（需勾选） |
| 6 | 反审核 | - | warning | 批量反审核选中记录（需勾选） |

#### 3.2.3 数据表格列定义

| 序号 | 列标题 | 字段名 | 宽度 | 对齐 | 说明 |
|------|--------|--------|------|------|------|
| 0 | (复选框) | - | 55px | center | 多选列，用于批量操作 |
| 1 | 单据编码 | checkinCode | 140px | left | 可点击打开详情 |
| 2 | 单据日期 | checkinDate | 120px | center | 默认降序排列 |
| 3 | 单据状态 | status | 90px | center | 状态标签（颜色区分） |
| 4 | 供应商 | supplierName | 180px | left | 供应商名称 |
| 5 | 采购订单号 | orderCode | 140px | left | 关联的采购订单编码 |
| 6 | 仓库 | warehouseName | 120px | left | 到货仓库 |
| 7 | 审核日期 | approveDate | 120px | center | 仅审核后显示 |
| 8 | 操作 | - | 160px | center | 查看/编辑/删除 |

#### 3.2.4 单据视图操作列按钮

| 按钮 | 颜色 | 说明 |
|------|------|------|
| 查看 | success (绿色文字) | 打开查看页（只读） |
| 编辑 | primary (蓝色文字) | 打开编辑页（仅开立状态可编辑，已审核以查看模式打开） |
| 删除 | danger (红色文字) | 二次确认后删除（仅开立状态可删除） |

### 3.3 底部统计区域（两种视图通用）

| 组件 | 位置 | 说明 |
|------|------|------|
| 到货数量统计 | 底部左侧 | 显示 "到货数量：{totalQty}" |
| 入库数量统计 | 底部左侧 | 显示 "入库数量：{stockedQty}" |

### 3.4 分页组件（两种视图通用）

| 属性 | 值 | 说明 |
|------|------|------|
| 默认每页条数 | 100 | 可选: 10, 20, 50, 100 |
| 布局 | total, sizes, prev, pager, next, jumper | 完整分页 |

---

## 4. 新增/编辑页设计

### 4.1 页面布局

新增/编辑页面为独立的全屏页面（非弹窗），包含表头表单区和到货明细子表区。

```
┌──────────────────────────────────────────────────────────────┐
│ 采购到货单                          [保存][取消][审核][反审核][收起] │
├──────────────────────────────────────────────────────────────┤
│ 表头表单区 (4列布局，可折叠)                                     │
│ ┌──────────┬──────────┬──────────┬──────────┐               │
│ │ 单据编码  │ 业务类型  │ 操作员    │ 仓库      │               │
│ │ 单据日期  │ 单据状态  │ 供应商    │ 采购订单号 │               │
│ │ 审核员    │ 审核日期  │ 备注      │ 总到货量  │               │
│ └──────────┴──────────┴──────────┴──────────┘               │
├──────────────────────────────────────────────────────────────┤
│ 到货信息                                          [+ 引入]    │
│ ┌──┬──────┬──────┬──────┬──┬──────┬──────┬──────┬──────┬──┐ │
│ │序│跟单编│订单编│物料编│物│主计  │订单数│到货数│已入库│操│ │
│ │号│号    │码    │码    │名│量    │量    │量    │数量  │作│ │
│ ├──┼──────┼──────┼──────┼──┼──────┼──────┼──────┼──────┼──┤ │
│ │1 │XSDD..│CGDD..│0301..│底│套    │100   │100   │0     │删│ │
│ └──┴──────┴──────┴──────┴──┴──────┴──────┴──────┴──────┴──┘ │
├──────────────────────────────────────────────────────────────┤
│ 合计                     到货总量：100.00                      │
└──────────────────────────────────────────────────────────────┘
```

### 4.2 表头表单字段

表头采用4列栅格布局（el-col :span="6"），每行4个字段。

| 序号 | 字段名 | 标签 | 组件类型 | 必填 | 默认值 | 可编辑 | 说明 |
|------|--------|------|----------|------|--------|--------|------|
| 1 | checkinCode | 单据编码 | el-input | 是 | 自动生成 | 否(只读) | 格式: CGDH + 6位流水号，后端自动生成 |
| 2 | businessType | 业务类型 | el-input | 否 | 采购到货 | 否(只读) | 固定为"采购到货" |
| 3 | operatorName | 操作员 | el-input | 是 | 当前登录用户 | 否(只读) | 自动填充当前登录用户名 |
| 4 | warehouseId | 仓库 | el-select | 否 | - | 是 | 下拉选择目标仓库 |
| 5 | checkinDate | 单据日期 | el-date-picker | 是 | 当天日期 | 是 | 日期选择器 |
| 6 | status | 单据状态 | el-tag | - | 开立 | 否(只读) | 标签显示，开立=info(灰) |
| 7 | supplierName | 供应商 | el-input | 否 | - | 否(只读) | 引入采购订单后自动填充 |
| 8 | orderCode | 采购订单号 | el-input | 否 | - | 否(只读) | 引入采购订单后自动填充 |
| 9 | approverName | 审核员 | el-input | 否 | - | 否(只读) | 审核时自动填充 |
| 10 | approveDate | 审核日期 | el-input | 否 | - | 否(只读) | 审核时自动填充 |
| 11 | remark | 备注 | el-input(textarea) | 否 | - | 是 | 多行文本，最多500字 |
| 12 | totalQuantity | 总到货量 | el-input | 否 | 0.00 | 否(只读) | 自动计算，明细行到货数量合计 |

### 4.3 到货信息子表

到货信息子表位于表头下方，标题为「到货信息」。通过「引入」按钮从采购订单引入物料。

| 序号 | 列标题 | 字段名 | 宽度 | 组件类型 | 必填 | 说明 |
|------|--------|--------|------|----------|------|------|
| 1 | 序号 | lineNo | 60px | 自动编号 | - | 行序号，自动递增 |
| 2 | 跟单编号 | trackCode | 130px | el-input | 否 | 只读，引入后自动填充 |
| 3 | 订单编码 | orderCode | 140px | el-input | 否 | 只读，引入后自动填充采购订单编码 |
| 4 | 物料编码 | itemCode | 140px | el-input | 是 | 只读，引入后自动填充 |
| 5 | 物料名称 | itemName | 200px | el-input | - | 只读，引入后自动填充 |
| 6 | 型号规格 | specification | 150px | el-input | 否 | 只读，引入后自动填充 |
| 7 | 主计量 | unitName | 80px | el-input | - | 只读，引入后自动填充 |
| 8 | 订单数量 | orderQuantity | 120px | el-input | - | 只读，引入后自动填充采购订单数量 |
| 9 | 到货数量 | quantity | 120px | el-input-number | 是 | 可修改，引入后默认为订单数量 |
| 10 | 已入库数量 | stockedQuantity | 120px | el-input | - | 只读，入库后回写 |
| 11 | 备注 | remark | 120px | el-input | 否 | 行备注 |
| 12 | 操作 | - | 80px | el-button | - | 删除按钮（仅编辑状态） |

### 4.4 引入采购订单弹窗

点击到货信息区域的「引入」按钮，打开采购订单选择弹窗。

| 属性 | 值 |
|------|------|
| 弹窗标题 | 采购订单明细 |
| 弹窗宽度 | 1000px |
| 弹窗高度 | 自适应，最大70vh |
| 关闭方式 | 右上角 X 按钮、取消按钮 |
| 选择模式 | 可勾选多条采购订单明细行（多选） |

**弹窗搜索区:**

| 组件 | 说明 |
|------|------|
| 订单编码 | 模糊搜索采购订单编码 |
| 供应商 | 模糊搜索供应商名称 |
| 物料编码 | 可选，模糊搜索 |
| 物料名称 | 可选，模糊搜索 |
| 开始日期、结束日期 | 可选，日期范围筛选 |
| 搜索按钮 | primary类型，执行搜索 |
| 查询所有 | 清空条件并刷新列表 |

**弹窗列表结构（层级表格）：**

- **父行**（采购订单头）：供应商、订单编码、订单日期；左侧可展开/收起。
- **子行**（采购订单明细，展开后显示）：物料编码、物料名称、型号规格、主计量、订单数量、已到货数量、可到货数量。
- 勾选子行后点击「确定」引入到到货明细子表。

**弹窗列表表格列（平铺模式时）:**

| 序号 | 列标题 | 字段名 | 宽度 | 说明 |
|------|--------|--------|------|------|
| 0 | (复选框) | - | 55px | 多选列 |
| 1 | 订单编码 | orderCode | 140px | 采购订单编码 |
| 2 | 供应商 | supplierName | 180px | |
| 3 | 物料编码 | itemCode | 140px | |
| 4 | 物料名称 | itemName | 200px | |
| 5 | 型号规格 | specification | 150px | |
| 6 | 主计量 | unitName | 80px | |
| 7 | 订单数量 | orderQty | 100px | |
| 8 | 已到货数量 | arrivedQty | 100px | 已被其他到货单引用的数量 |
| 9 | 可到货数量 | availableQty | 100px | 订单数量 - 已到货数量 |

**引入交互:**
- 勾选一条或多条采购订单明细行，点击「确定」按钮
- 引入后自动填充到货信息子表：跟单编号、订单编码、物料编码、物料名称、主计量、订单数量、到货数量（默认=可到货数量）
- 同时自动填充表头：供应商（取引入的采购订单供应商）、采购订单号
- 引入后到货数量可修改，支持分批次到货

---

## 5. 数据字段定义

### 5.1 采购到货单表头字段（erp_po_checkin）

> 字段定义以 **《erp数据库设计-数据字典》** 与 **erp数据库设计-DDL.sql** 为准。

| 字段名 | 数据库字段 | 类型 | 长度 | 必填 | 默认值 | 说明 |
|--------|-----------|------|------|------|--------|------|
| 到货单ID | checkin_id | bigint | - | 是 | AUTO | 主键，自增 |
| 租户ID | tenant_id | varchar | 20 | 是 | - | 多租户隔离 |
| 到货单编码 | checkin_code | varchar | 32 | 是 | 自动生成 | 格式: CGDH + 6位流水号 |
| 到货日期 | checkin_date | date | - | 是 | 当天 | 到货登记日期 |
| 单据状态 | status | varchar | 20 | 是 | DRAFT | 开立/审核 |
| 业务类型 | business_type | varchar | 20 | 否 | NULL | 业务类型 |
| 采购订单ID | order_id | bigint | - | 否 | - | 外键 → erp_po_order |
| 采购订单编码 | order_code | varchar | 32 | 否 | - | 冗余 |
| 供应商ID | supplier_id | bigint | - | 否 | - | 外键 → 供应商档案 |
| 供应商编码 | supplier_code | varchar | 32 | 否 | - | 冗余 |
| 供应商名称 | supplier_name | varchar | 100 | 否 | - | 冗余 |
| 仓库ID | warehouse_id | bigint | - | 否 | - | 外键 → 仓库档案 |
| 仓库编码 | warehouse_code | varchar | 32 | 否 | - | 冗余 |
| 仓库名称 | warehouse_name | varchar | 50 | 否 | - | 冗余 |
| 总到货数量 | total_quantity | decimal | 18,4 | 否 | 0 | 明细行到货数量合计 |
| 已入库数量 | stocked_quantity | decimal | 18,4 | 否 | 0 | 已入库数量合计 |
| 备注 | remark | varchar | 500 | 否 | - | |
| 操作员ID | operator_id | bigint | - | 否 | - | 操作员ID |
| 操作员名称 | operator_name | varchar | 50 | 否 | - | 操作员名称 |
| 审核员ID | approver_id | bigint | - | 否 | - | 审核员ID |
| 审核员名称 | approver_name | varchar | 50 | 否 | - | 审核员名称 |
| 审核日期 | approve_date | datetime | - | 否 | - | 审核日期 |
| 删除标志 | del_flag | char | 1 | 是 | 0 | 0存在/1删除 |
| 创建者 | create_by | varchar | 64 | 否 | - | |
| 创建时间 | create_time | datetime | - | 否 | - | |
| 更新者 | update_by | varchar | 64 | 否 | - | |
| 更新时间 | update_time | datetime | - | 否 | - | |

### 5.2 采购到货单明细字段（erp_po_checkin_line）

| 字段名 | 数据库字段 | 类型 | 长度 | 必填 | 默认值 | 说明 |
|--------|-----------|------|------|------|--------|------|
| 明细ID | line_id | bigint | - | 是 | AUTO | 主键，自增 |
| 到货单ID | checkin_id | bigint | - | 是 | - | 外键 → erp_po_checkin.checkin_id |
| 到货单编码 | checkin_code | varchar | 32 | 是 | - | 冗余 |
| 行号 | line_no | int | - | 是 | - | 行序号 |
| 采购订单明细ID | order_line_id | bigint | - | 否 | - | 外键 → erp_po_order_line.line_id |
| 跟单编号 | track_code | varchar | 32 | 否 | - | 跟单编号 |
| 物料ID | item_id | bigint | - | 是 | - | 外键 → erp_md_item.item_id |
| 物料编码 | item_code | varchar | 32 | 是 | - | 冗余 |
| 物料名称 | item_name | varchar | 100 | 是 | - | 冗余 |
| 型号规格 | specification | varchar | 200 | 否 | - | |
| 计量单位 | unit_name | varchar | 20 | 否 | - | 冗余 |
| 订单数量 | order_quantity | decimal | 18,4 | 否 | 0 | 采购订单数量 |
| 到货数量 | quantity | decimal | 18,4 | 是 | 0 | 本次到货数量 |
| 已入库数量 | stocked_quantity | decimal | 18,4 | 否 | 0 | 已入库数量 |
| 备注 | remark | varchar | 200 | 否 | - | |
| 删除标志 | del_flag | char | 1 | 是 | 0 | 0存在/1删除 |
| 租户ID | tenant_id | varchar | 20 | 是 | - | |

---

## 6. 按钮操作说明

### 6.1 明细视图工具栏按钮

#### 6.1.1 「单据」按钮（视图切换）

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | 切换到单据视图，重新加载列表数据 |
| 效果 | 搜索区域、工具栏、表格列全部切换为单据视图样式 |

#### 6.1.2 查询所有按钮

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | 清空所有搜索条件，重新加载列表（pageNum=1） |

#### 6.1.3 新增按钮

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | 路由跳转到新增采购到货单页面 |
| 路由 | `/purchasing/checkin/new` |

#### 6.1.4 导出按钮

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | 按当前搜索条件导出到货单列表到Excel |

### 6.2 单据视图工具栏按钮

#### 6.2.1 「明细」按钮（视图切换）

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | 切换到明细视图，重新加载列表数据 |

#### 6.2.2 删除按钮（批量）

| 项目 | 说明 |
|------|------|
| 触发条件 | 勾选一条或多条记录（否则disabled） |
| 前置校验 | 仅开立(DRAFT)状态允许删除；已审核状态记录跳过并提示 |
| 操作 | 弹出确认框："确认删除选中的{n}条到货记录？"，确认后调用删除接口 |

#### 6.2.3 审核按钮（批量）

| 项目 | 说明 |
|------|------|
| 触发条件 | 勾选一条或多条记录（否则disabled） |
| 前置校验 | 仅开立(DRAFT)状态允许审核；需至少有1条到货明细 |
| 操作 | 弹出确认框，确认后批量审核 |
| 结果 | status → APPROVED，自动记录审核员和审核日期 |

#### 6.2.4 反审核按钮（批量）

| 项目 | 说明 |
|------|------|
| 触发条件 | 勾选一条或多条记录（否则disabled） |
| 前置校验 | 仅审核(APPROVED)状态允许反审核；需检查是否已有入库单 |
| 操作 | 弹出确认框，确认后批量反审核 |
| 结果 | status → DRAFT，清空审核员和审核日期 |

### 6.3 新增/编辑页按钮

#### 6.3.1 保存按钮

| 项目 | 说明 |
|------|------|
| 位置 | 页面右上角 |
| 颜色 | primary (蓝色) |
| 触发条件 | 表单校验通过 |
| 操作 | 保存到货单表头和明细数据 |
| 成功提示 | "保存成功" |

#### 6.3.2 取消按钮

| 项目 | 说明 |
|------|------|
| 位置 | 保存按钮右侧 |
| 颜色 | default (灰色) |
| 操作 | 返回列表页 |

#### 6.3.3 审核按钮

| 项目 | 说明 |
|------|------|
| 位置 | 取消按钮右侧 |
| 颜色 | success (绿色) |
| 显示条件 | 编辑模式且 status = DRAFT 且有明细数据 |
| 操作 | 调用审核接口，成功后页面变为只读 |

#### 6.3.4 反审核按钮

| 项目 | 说明 |
|------|------|
| 位置 | 审核按钮右侧 |
| 颜色 | warning (橙色) |
| 显示条件 | 查看模式且 status = APPROVED |
| 前置条件 | 该到货单无已入库记录 |
| 操作 | 调用反审核接口，成功后页面变为可编辑 |

#### 6.3.5 收起/展开按钮

| 项目 | 说明 |
|------|------|
| 位置 | 页面右上角最右侧 |
| 操作 | 折叠/展开表头表单区域 |

#### 6.3.6 引入按钮（到货信息子表）

| 项目 | 说明 |
|------|------|
| 位置 | 到货信息区域右上角 |
| 颜色 | primary (蓝色) |
| 操作 | 打开采购订单选择弹窗，引入订单物料行 |
| 显示条件 | 仅编辑状态显示 |

#### 6.3.7 查看页顶部工具栏

| 项目 | 说明 |
|------|------|
| 适用 | 查看采购到货单页面 |
| 按钮 | 新增、编辑、审核、反审核、收起 |
| 新增 | 跳转新增页面 |
| 编辑 | 跳转编辑页（仅开立状态启用） |

#### 6.3.8 记录导航「上一条」「下一条」

| 项目 | 说明 |
|------|------|
| 位置 | 表头区域左侧标题旁 |
| 显示条件 | 查看/编辑模式下，存在多条记录时显示 |
| 操作 | 加载上一条/下一条到货单详情并刷新表单 |

---

## 7. 页面交互规则

### 7.1 列表页通用交互

| 序号 | 交互场景 | 交互规则 |
|------|----------|----------|
| 1 | 页面首次加载 | 默认以明细视图加载第1页数据，按单据日期降序排列 |
| 2 | 搜索操作 | 点击搜索按钮，重置pageNum=1，保持当前pageSize不变 |
| 3 | 单据编码点击 | 点击单据编码列蓝色链接，路由跳转至查看页 |
| 4 | 状态标签 | 用el-tag组件渲染：开立=info(灰), 审核=success(绿) |
| 5 | 空数据状态 | 列表无数据时显示空状态图标和"暂无数据"文字 |
| 6 | 视图切换 | 切换视图时保留公共搜索字段（单据编码、日期范围） |
| 7 | 底部汇总 | 两种视图均显示到货数量和入库数量汇总 |

### 7.2 新增/编辑页交互

| 序号 | 交互场景 | 交互规则 |
|------|----------|----------|
| 1 | 页面加载(新增) | 自动填充：单据编码(调接口获取或后端自动)、单据日期(当天)、操作员(当前用户)、业务类型(采购到货)、总到货量(0.00) |
| 2 | 页面加载(编辑) | 调用详情接口加载到货单表头、到货明细数据 |
| 3 | 引入采购订单 | 点击「引入」→ 打开采购订单选择弹窗 → 勾选订单明细行 → 确认引入 → 自动填充到货信息子表和表头关联字段 |
| 4 | 引入后修改数量 | 引入的到货数量可修改，支持分批次到货（如订单100个，本次到货50个） |
| 5 | 保存操作 | 前端表单校验 → 校验通过调用保存接口 → 成功提示 → 页面变为编辑模式 |
| 6 | 审核操作 | 需先保存 → 确认弹窗 → 调用审核接口 → 成功后页面变只读 |
| 7 | 反审核操作 | 确认弹窗 → 调用反审核接口 → 成功后页面变可编辑（需检查无下游入库单） |
| 8 | 表头折叠 | 点击「收起」→ 表头表单区域收起，仅显示子表明细；点击「展开」→ 恢复 |
| 9 | 总到货量自动计算 | 到货信息中到货数量的合计值自动更新到表头「总到货量」字段 |

### 7.3 表单校验规则

#### 表头校验

| 字段 | 规则 | 提示信息 |
|------|------|----------|
| checkinDate | 必填 | 到货日期不能为空 |

#### 到货明细校验

| 字段 | 规则 | 提示信息 |
|------|------|----------|
| itemCode | 必填 | 请引入采购订单物料 |
| quantity | 必填，min=0.01 | 到货数量必须大于0 |

#### 业务校验

| 规则 | 说明 |
|------|------|
| 至少一行到货明细 | 保存时至少要有一条到货物料行 |
| 审核前需保存 | 审核操作前需先保存当前数据 |
| 到货数量不超过可到货数量 | 引入时到货数量默认为可到货数量，可减少但不建议超出 |

---

## 8. 接口调用说明

### 8.1 接口总览

| 序号 | 功能 | 方法 | 路径 | 说明 |
|------|------|------|------|------|
| 1 | 查询到货单列表 | GET | /erp/po/checkin/list | 分页查询到货单列表 |
| 2 | 获取到货单详情 | GET | /erp/po/checkin/{checkinId} | 获取单条到货单表头+明细 |
| 3 | 新增到货单 | POST | /erp/po/checkin | 创建新到货单 |
| 4 | 修改到货单 | PUT | /erp/po/checkin | 更新到货单表头+明细 |
| 5 | 删除到货单 | DELETE | /erp/po/checkin/{checkinIds} | 批量删除到货单 |
| 6 | 导出到货单 | POST | /erp/po/checkin/export | 导出到货单列表到Excel |
| 7 | 审核到货单 | PUT | /erp/po/checkin/approve/{checkinId} | 审核到货单（**待后端实现**） |
| 8 | 反审核到货单 | PUT | /erp/po/checkin/reject/{checkinId} | 反审核到货单（**待后端实现**） |
| 9 | 查询可引入采购订单 | GET | /erp/po/order/list | 获取已审核的采购订单列表 |
| 10 | 获取采购订单详情 | GET | /erp/po/order/{orderId} | 获取采购订单含明细行 |

> **说明**: 审核/反审核接口后端暂未实现，需要后端开发。前端可预留接口调用代码。

### 8.2 接口详细说明

#### 8.2.1 查询到货单列表

```
GET /erp/po/checkin/list
```

**请求参数:**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | integer | 否 | 页码，默认1 |
| pageSize | integer | 否 | 每页数，默认100 |
| checkinCode | string | 否 | 到货单编码（模糊） |
| trackCode | string | 否 | 跟单编号（模糊） |
| supplierName | string | 否 | 供应商名称（模糊） |
| itemCode | string | 否 | 物料编码（模糊） |
| itemName | string | 否 | 物料名称（模糊） |
| status | string | 否 | 单据状态 |
| beginDate | string | 否 | 开始日期 (yyyy-MM-dd) |
| endDate | string | 否 | 结束日期 (yyyy-MM-dd) |

**响应示例:**

```json
{
  "total": 50,
  "rows": [
    {
      "checkinId": 1,
      "checkinCode": "CGDH000001",
      "checkinDate": "2026-02-13",
      "status": "DRAFT",
      "businessType": "采购到货",
      "orderId": 47,
      "orderCode": "CGDD000047",
      "supplierName": "南京某某金属材料有限公司",
      "warehouseName": "原料仓",
      "totalQuantity": 500.00,
      "stockedQuantity": 0,
      "operatorName": "admin",
      "lines": [
        {
          "lineId": 1,
          "checkinId": 1,
          "lineNo": 1,
          "trackCode": "XSDD000090",
          "itemCode": "0301000001",
          "itemName": "底架组件",
          "unitName": "套",
          "orderQuantity": 500.00,
          "quantity": 500.00,
          "stockedQuantity": 0
        }
      ]
    }
  ],
  "code": 200,
  "msg": "查询成功"
}
```

#### 8.2.2 获取到货单详情

```
GET /erp/po/checkin/{checkinId}
```

**响应**: 同列表行结构，含完整 lines 数组。

#### 8.2.3 新增到货单

```
POST /erp/po/checkin
```

**请求体:**

```json
{
  "checkinDate": "2026-02-13",
  "businessType": "采购到货",
  "orderId": 47,
  "orderCode": "CGDD000047",
  "supplierId": 10,
  "supplierCode": "GYS001",
  "supplierName": "南京某某金属材料有限公司",
  "warehouseId": 1,
  "warehouseCode": "YLC",
  "warehouseName": "原料仓",
  "remark": "",
  "lines": [
    {
      "lineNo": 1,
      "orderLineId": 100,
      "trackCode": "XSDD000090",
      "itemId": 200,
      "itemCode": "0301000001",
      "itemName": "底架组件",
      "specification": "",
      "unitName": "套",
      "orderQuantity": 500.00,
      "quantity": 500.00
    }
  ]
}
```

#### 8.2.4 修改到货单

```
PUT /erp/po/checkin
```

**请求体**: 同新增，但包含 `checkinId` 和各明细行的 `lineId`。

#### 8.2.5 删除到货单

```
DELETE /erp/po/checkin/{checkinIds}
```

**业务规则:**
- 仅允许删除开立(DRAFT)状态的到货单
- 删除时同时删除明细行记录
- 逻辑删除（del_flag = 1）

---

## 9. 状态流转

### 9.1 单据状态流转图

```
                    ┌──────────────┐
                    │              │
         ┌─────────►  开立(DRAFT)  ◄──────────┐
         │          │              │           │
         │          └──────┬───────┘           │
         │                 │                   │
         │            [审核操作]            [反审核操作]
         │                 │                   │
         │                 ▼                   │
         │          ┌──────────────┐           │
         │          │              │           │
         └──────────┤ 审核(APPROVED)├───────────┘
                    │              │
                    └──────┬───────┘
                           │
                      [入库操作]
                           │
                           ▼
                    ┌──────────────┐
                    │              │
                    │  入库中/完成  │
                    │              │
                    └──────────────┘
```

### 9.2 状态说明

| 状态 | 编码 | 可执行操作 | 说明 |
|------|------|-----------|------|
| 开立 | DRAFT | 编辑、保存、删除、审核 | 初始状态，可自由编辑 |
| 审核 | APPROVED | 查看、反审核、生成入库单 | 生效状态，不可编辑 |

---

## 10. 业务规则

### 10.1 编码规则

| 规则 | 说明 |
|------|------|
| 前缀 | CGDH |
| 流水号 | 6位数字，不足补零 |
| 格式 | CGDH000001, CGDH000002, ... |
| 生成方式 | 后端自动生成，不可手动修改 |

### 10.2 引入采购订单规则

| 规则 | 说明 |
|------|------|
| 来源 | 仅可引入已审核的采购订单中的物料明细 |
| 数量限制 | 到货数量不能超过可到货数量（订单数量 - 已到货数量） |
| 数量可修改 | 引入后到货数量可修改，支持分批次到货 |
| 多订单引入 | 同一到货单可引入多个采购订单的物料 |
| 重复引入 | 已引入的订单明细行不允许重复引入 |

### 10.3 入库规则

| 规则 | 说明 |
|------|------|
| 前置条件 | 到货单必须已审核(APPROVED)才能生成入库单 |
| 入库数量 | 入库数量不能超过到货数量 |
| 回写 | 入库完成后回写 stocked_quantity 字段 |

### 10.4 下游引用规则

| 引用场景 | 影响 |
|----------|------|
| 已生成入库单 | 不允许反审核、不允许删除 |
| 部分入库 | 不允许反审核 |

---

## 11. 前端组件设计

### 11.1 文件结构

```
src/
├── api/
│   └── checkin.ts                        # 采购到货单相关API接口定义（已存在）
├── views/
│   └── Purchasing/
│       └── Checkin/
│           ├── index.vue                 # 列表页入口（已存在，需重构支持双视图）
│           └── form.vue                  # 新增/编辑/查看页（需新增）
```

### 11.2 API接口文件

```typescript
// src/api/checkin.ts（已存在，需补充审核接口）
import request from './request'

// 查询到货单列表
export function getCheckinList(params: CheckinQuery): Promise<CheckinListResponse>

// 获取到货单详情
export function getCheckinDetail(checkinId: number): Promise<Checkin>

// 新增到货单
export function createCheckin(data: Partial<Checkin>): Promise<void>

// 更新到货单
export function updateCheckin(data: Partial<Checkin>): Promise<void>

// 删除到货单
export function deleteCheckin(checkinIds: string): Promise<void>

// 审核到货单（待后端实现后启用）
export function approveCheckin(checkinId: number): Promise<void>

// 反审核到货单（待后端实现后启用）
export function rejectCheckin(checkinId: number): Promise<void>

// 导出到货单
export function exportCheckin(params: CheckinQuery): Promise<Blob>
```

### 11.3 路由配置

```typescript
// src/router/index.ts（采购到货单路由）
{
  path: '/purchasing',
  component: Layout,
  children: [
    {
      path: 'checkin',
      name: 'PurchaseCheckinList',
      component: () => import('@/views/Purchasing/Checkin/index.vue'),
      meta: { title: '采购到货单' }
    },
    {
      path: 'checkin/new',
      name: 'PurchaseCheckinNew',
      component: () => import('@/views/Purchasing/Checkin/form.vue'),
      meta: { title: '新增采购到货单' },
      hidden: true
    },
    {
      path: 'checkin/edit/:id',
      name: 'PurchaseCheckinEdit',
      component: () => import('@/views/Purchasing/Checkin/form.vue'),
      meta: { title: '编辑采购到货单' },
      hidden: true
    },
    {
      path: 'checkin/view/:id',
      name: 'PurchaseCheckinView',
      component: () => import('@/views/Purchasing/Checkin/form.vue'),
      meta: { title: '采购到货单详情' },
      hidden: true
    }
  ]
}
```

---

## 12. 数据模型

### 12.1 表关系图

```
┌──────────────────────────┐
│     erp_po_order         │
│   (采购订单)              │
│                          │
│ order_id (PK)            │
│ order_code               │
│ supplier_id              │
│ supplier_name            │
└──────────┬───────────────┘
           │ 1:N (引入)
           ▼
┌──────────────────────────┐     ┌──────────────────────────┐
│   erp_po_checkin         │     │  erp_md_supplier         │
│  (采购到货单/表头)        │────►│     (供应商)             │
│                          │     │                          │
│ checkin_id (PK)          │     │ supplier_id (PK)         │
│ checkin_code (UK)        │     │ supplier_name            │
│ order_id (FK) ───────────┼──►  └──────────────────────────┘
│ supplier_id (FK)         │
│ warehouse_id (FK)        │     ┌──────────────────────────┐
│ status                   │     │  仓库档案                │
│ total_quantity           │────►│ warehouse_id (PK)        │
│ stocked_quantity         │     │ warehouse_name           │
└──────────┬───────────────┘     └──────────────────────────┘
           │ 1:N
           ▼
┌──────────────────────────┐
│  erp_po_checkin_line     │     ┌──────────────────────────┐
│ (到货明细)                │     │      erp_md_item         │
│                          │     │     (物料档案)            │
│ line_id (PK)             │     │                          │
│ checkin_id (FK)──────────┼──►  │ item_id (PK)             │
│ order_line_id (FK)       │     │ item_code                │
│ item_id (FK)─────────────┼──►  │ item_name                │
│ order_quantity           │     └──────────────────────────┘
│ quantity                 │
│ stocked_quantity         │
└──────────────────────────┘

           │ 入库（下游）
           ▼
┌──────────────────────────┐
│  erp_wm_item_recpt      │
│ (采购入库单)              │
│                          │
│ recpt_id (PK)            │
│ source_doc_id (FK)───────┼──► erp_po_checkin.checkin_id
│ source_doc_code          │
│ warehouse_id             │
└──────────────────────────┘
```

### 12.2 数据流向

```
采购订单(erp_po_order) ──引入──► 采购到货单(erp_po_checkin)
                                       │
                                  审核后入库
                                       │
                                       ▼
                              采购入库单(erp_wm_item_recpt)
                                       │
                                       ▼
                                 库存增加(wm_item_stock)
```

---

## 附录A: 状态标签颜色映射

```javascript
// 状态标签类型映射
const statusTagMap = {
  'DRAFT': 'info',       // 灰色 - 开立
  'APPROVED': 'success'  // 绿色 - 审核
}

// 状态标签文字映射
const statusLabelMap = {
  'DRAFT': '开立',
  'APPROVED': '审核'
}
```

---

## 附录B: 与采购订单页面的关联说明

采购到货单页面与采购订单页面存在紧密的业务关联：

| 关联点 | 说明 |
|--------|------|
| 引入采购订单 | 到货单通过「引入」功能从已审核的采购订单获取物料明细 |
| 到货数量回写 | 到货单保存后，将到货数量回写到采购订单的 arrived_quantity 字段 |
| 供应商信息 | 引入采购订单时自动带入供应商信息 |
| 数据流向 | 采购订单（下达采购）→ 采购到货单（登记到货）→ 采购入库单（入库） |

---

## 附录C: 现有实现状态与开发计划

| 组件 | 状态 | 说明 |
|------|------|------|
| 数据库表 | ✅ 已完成 | erp_po_checkin, erp_po_checkin_line 已建表 |
| 后端 CRUD | ✅ 已完成 | PoCheckinController 已实现 list/detail/add/edit/delete |
| 后端审核 | ❌ 待开发 | approve/reject 接口需新增 |
| 前端 API | ✅ 已完成 | checkin.ts 已定义 CRUD 接口（审核接口预留） |
| 列表页 | ⚠️ 需重构 | index.vue 已有基础实现，需完善双视图、批量操作等 |
| 表单页 | ❌ 待开发 | form.vue 需新增（新增/编辑/查看页） |
| 路由配置 | ⚠️ 需补充 | 列表页路由已有，form 页路由需新增 |

---

## 修订历史

| 版本 | 日期 | 修订内容 | 修订人 |
|------|------|----------|--------|
| 1.0.0 | 2026-02-13 | 初始版本，基于数据库设计和采购订单PRD参考，完整页面设计开发说明 | System |