my-mom-system/prd/mom系统采购计划需求表-页面开发说明文档.md

# 采购计划需求表 - 页面设计开发说明文档

> 版本: 1.0.0  
> 创建日期: 2026-02-07  
> 更新日期: 2026-02-07  
> 来源系统: 升阳云ERP 演示系统  
> 来源页面: `https://demo.rsun.vip/mp/plan/need?workType=`  
> 所属模块: 生产计划 > 采购计划需求表  
> 前端路由: `/mp/plan/need`  
> **采集脚本**: `python3 scripts/crawl_purchase_need.py`（手动登录后自动采集，3 个按钮交互 + 2 张截图）  
> **关联文档**: [生产计划.md](生产计划.md)；[生产计划-前端开发规范.md](生产计划-前端开发规范.md)；[mom系统采购计划单-页面开发说明文档](mom系统采购计划单-页面开发说明文档.md)

---

## 目录

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

---

## 0. 业务流程总览

### 0.1 采购计划需求表在 ERP 中的定位

采购计划需求表是一个**只读报表页面**，用于按物料维度汇总展示采购计划的需求数据，帮助采购人员了解各物料的需求数量、可用量（库存）、采购数量、已订数量和未订数量，从而指导采购执行。

```
销售订单 → 生产计划单 → BOM运算 → 物料清单(MBOM) → 采购计划单 → 采购订单
                                                        │
                                                        │ 数据汇总
                                                        ▼
                                                 ┌──────────────────┐
                                                 │ ★ 采购计划需求表  │
                                                 │  - 物料维度汇总    │
                                                 │  - 需求/可用/已订  │
                                                 │  - 指导采购执行    │
                                                 └──────────────────┘
```

### 0.2 业务价值

| 场景 | 说明 |
|------|------|
| **采购缺口分析** | 对比需求数量与可用量，负值可用量表示缺料，需加大采购 |
| **采购执行跟踪** | 对比采购数量与已订数量/未订数量，了解采购计划执行进度 |
| **按类型筛选** | 通过物料分类快捷标签（原材料/零部件/五金等）快速查看特定类型物料需求 |
| **导出分析** | 导出 Excel 供离线分析和汇报 |

### 0.3 页面特点（与采购计划单的区别）

| 对比项 | 采购计划需求表 | 采购计划单 |
|--------|--------------|-----------|
| 页面类型 | **只读报表** | 业务单据（增删改审） |
| 数据维度 | 按物料汇总 | 按单据/物料明细 |
| 有无详情页 | **无**（纯列表） | 有（新增/编辑/查看） |
| 操作按钮 | 搜索/查询所有/导出/打印 | 新增/删除/审核/反审核/导出等 |
| 双视图 | **无** | 有（明细/单据） |
| 快捷标签 | 有（原材料/零部件/五金等） | 有（物料分类） |
| 关键数量 | 需求数量/可用量/采购数量/已订数量/未订数量 | 采购数量/已订数量 |

---

## 1. 页面概述

### 1.1 功能说明

采购计划需求表是采购计划模块的报表页面，按物料维度汇总展示已审核采购计划单中的物料需求数据。页面为**纯列表查询**，不支持新增、编辑或审核操作，属于只读报表。

### 1.2 业务场景

- **查看采购需求汇总**: 按销售订单/计划单/物料维度查看需求数量、可用量、采购/已订/未订数量
- **缺料预警**: 可用量为负值时表示库存不足，需加大采购力度
- **物料分类筛选**: 通过快捷标签快速切换物料类型查看
- **导出报表**: 导出到 Excel 供离线分析
- **打印**: 直接打印当前报表

### 1.3 URL路由参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| workType | string | 工作类型（可为空） |

### 1.4 页面截图参考（Playwright 自动采集）

| 截图文件 | 说明 | 来源 |
|----------|------|------|
| `screenshot/采购计划需求表-列表-默认.png` | 默认列表：12列/6行/底部3项汇总/快捷标签 | ✅ 自动采集 |
| `screenshot/采购计划需求表-导出确认.png` | 导出确认弹窗 | ✅ 自动采集 |

---

## 2. 页面结构

### 2.1 整体布局

> 截图: `screenshot/采购计划需求表-列表-默认.png`

```
┌─────────────────────────────────────────────────────────────────┐
│                     顶部导航栏 (64px)                            │
├────────┬────────────────────────────────────────────────────────┤
│ 左侧   │  面包屑: 首页 / 生产计划 / 采购计划需求表                 │
│ 菜单   │  ┌────────────────────────────────────────────────┐    │
│ (200px)│  │ Tab标签: ● 采购计划需求表                       │    │
│        │  ├────────────────────────────────────────────────┤    │
│ 生产计 │  │ 搜索区域                                        │    │
│ 划     │  │ [销售订单号][物料编码][物料名称][日期范围][搜索]   │    │
│ ...    │  ├────────────────────────────────────────────────┤    │
│ ├采购  │  │ 工具栏 + 快捷标签                               │    │
│  计划  │  │ [查询所有][导出][打印] 原材料|零部件|五金          │    │
│  需求  │  ├────────────────────────────────────────────────┤    │
│  表★  │  │ 数据表格 (12列)                                 │    │
│ ...    │  ├────────────────────────────────────────────────┤    │
│        │  │ 底部汇总: 采购数量/已订数量/未订数量 + 分页       │    │
│        │  └────────────────────────────────────────────────┘    │
├────────┴────────────────────────────────────────────────────────┤
```

### 2.2 页面模式

本页面**仅有一种模式**（列表报表），无明细/单据双视图切换，无详情页。

---

## 3. 列表页设计

### 3.1 搜索条件区域（✅ Playwright 采集确认）

| 序号 | 字段名 | 标签/placeholder | 组件类型 | 说明 |
|------|--------|-----------------|----------|------|
| 1 | salesOrderCode | 销售订单号 | el-input | 模糊搜索 |
| 2 | itemCode | 物料编码 | el-input | 模糊搜索 |
| 3 | itemName | 物料名称 | el-input | 模糊搜索 |
| 4 | startDate | 开始日期 | el-date-picker | 日期范围起（如 2026-02-01） |
| 5 | endDate | 结束日期 | el-date-picker | 日期范围止（如 2026-02-07） |
| 6 | needType | 请选择 | el-select | 需求方式（可能为业务类型/需求方式/数据范围） |

> **注意**: 搜索区域右侧有「搜索」按钮（primary）。日期范围默认为近一周。

### 3.2 工具栏按钮（✅ 采集确认 4 个）

| 序号 | 按钮名称 | 类型 | 权限标识 | 说明 |
|------|----------|------|----------|------|
| 1 | 搜索 | primary | mp:need:list | 按搜索条件查询 |
| 2 | 查询所有 | default | mp:need:list | 重置搜索条件并查询所有 |
| 3 | 导出 | warning | mp:need:export | 导出到 Excel |
| 4 | 打印 | default | mp:need:print | 打印当前报表 |

### 3.3 快捷筛选标签

> 截图确认：工具栏右侧显示物料分类快捷标签

| 标签 | 说明 |
|------|------|
| 原材料 | 按物料分类=原材料筛选 |
| 零部件 | 按物料分类=零部件筛选 |
| 五金 | 按物料分类=五金件筛选 |
| （更多） | 根据系统配置动态加载 |

点击标签筛选该类型物料，再次点击取消筛选。

### 3.4 数据表格列定义（✅ 采集确认 12 列）

| 序号 | 列标题 | 字段名 | 宽度 | 对齐 | 说明 |
|------|--------|--------|------|------|------|
| 1 | 序号 | - | 60px | center | 自动编号 |
| 2 | 销售订单号 | salesOrderCode | 140px | left | 关联的销售订单编号 |
| 3 | 计划单号 | planCode | 140px | left | 采购计划单编码 |
| 4 | 物料编码 | itemCode | 120px | left | 物料编码 |
| 5 | 物料名称 | itemName | 250px | left | 物料名称（可能较长） |
| 6 | 需求数量 | demandQty | 100px | right | BOM 运算后的物料需求总量 |
| 7 | 可用量 | availableQty | 100px | right | 当前库存可用量（**可为负值**，表示缺料） |
| 8 | 采购数量 | purchaseQty | 100px | right | 采购计划中的采购数量 |
| 9 | 已订数量 | orderedQty | 100px | right | 已转为采购订单的数量 |
| 10 | 未订数量 | unorderedQty | 100px | right | 采购数量 - 已订数量 |
| 11 | 单据日期 | purchaseDate | 100px | center | 采购计划单日期 |
| 12 | 采购说明 | remark | 120px | left | 采购备注 |

### 3.5 底部汇总区域（✅ 截图确认）

底部左侧显示三项汇总统计：

| 统计项 | 说明 |
|--------|------|
| 采购数量：186 | 当前查询结果的采购数量合计 |
| 已订数量：0 | 当前查询结果的已订数量合计 |
| 未订数量：186 | 当前查询结果的未订数量合计 |

### 3.6 分页组件

| 属性 | 值 |
|------|------|
| 默认每页条数 | 100 |
| 可选 | 100条/页 |
| 布局 | total, sizes, prev, pager, next, jumper |
| 总条数 | 共 6 条（示例数据） |

---

## 4. 数据字段定义

### 4.1 数据来源

采购计划需求表**不对应独立的数据库表**，而是基于 `erp_mp_purchase`（采购计划单）及关联表的**查询视图**，按物料维度汇总展示。

**数据来源:**

| 字段 | 来源表 | 说明 |
|------|--------|------|
| salesOrderCode | erp_mp_purchase.sales_order_code | 销售订单号 |
| planCode | erp_mp_purchase.purchase_code | 采购计划编码 |
| itemCode | erp_mp_purchase.item_code | 物料编码 |
| itemName | erp_mp_purchase.item_name | 物料名称 |
| demandQty | 关联计算 | BOM 运算后的需求量 |
| availableQty | 库存查询 | 当前可用库存（实时计算） |
| purchaseQty | erp_mp_purchase.purchase_qty | 采购数量 |
| orderedQty | erp_mp_purchase.ordered_qty | 已订数量 |
| unorderedQty | purchase_qty - ordered_qty | 计算字段 |
| purchaseDate | erp_mp_purchase.purchase_date | 采购计划日期 |
| remark | erp_mp_purchase.remark | 备注 |

### 4.2 关键数量关系

```
需求数量（demandQty）    ← BOM 运算后的物料需求总量
可用量（availableQty）   ← 当前库存可用量（可为负值 = 缺料）
采购数量（purchaseQty）  ← 采购计划中计划采购的数量
已订数量（orderedQty）   ← 已转为采购订单的数量
未订数量（unorderedQty） = 采购数量 - 已订数量（尚未下单的数量）
```

**实际数据示例（采集确认）:**

| 物料 | 需求数量 | 可用量 | 采购数量 | 已订 | 未订 |
|------|----------|--------|----------|------|------|
| 微星 MAG B760M 主板 (1000000002) | 2.00 | **-168.00** | 2.00 | 0.00 | 2.00 |
| 华硕 TUF-RTX 4070 显卡 (1000000006) | 2.00 | **-186.00** | 2.00 | 0.00 | 2.00 |
| 三星 1TB 980 PRO 固态 (1000000004) | 2.00 | **-186.00** | 2.00 | 0.00 | 2.00 |

> 可用量为负值（-168/-186/-188）表示这些物料严重缺料，需加紧采购。

---

## 5. 按钮操作说明（✅ Playwright 验证）

### 5.1 搜索按钮

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | pageNum=1，携带搜索条件+日期范围请求列表接口 |
| 结果 | 列表刷新，底部汇总更新 |
| 验证 | ✅ 行数=6 |

### 5.2 查询所有按钮

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | 重置所有搜索条件（清空输入框、下拉框、日期范围），重新查询 |
| 结果 | 显示所有数据 |
| 验证 | ✅ |

### 5.3 导出按钮

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | 弹出确认弹窗，确认后按当前搜索条件导出到 Excel |
| 截图 | `screenshot/采购计划需求表-导出确认.png` |
| 验证 | ✅ |

### 5.4 打印按钮

| 项目 | 说明 |
|------|------|
| 触发条件 | 始终可用 |
| 操作 | 调用浏览器打印预览，打印当前报表内容 |
| 验证 | ✅ 按钮存在 |

---

## 6. 页面交互规则

| 序号 | 交互场景 | 规则 | 验证 |
|------|----------|------|------|
| 1 | 页面首次加载 | 默认带日期范围（近一周如 2026-02-01 ~ 2026-02-07）查询 | ✅ 截图确认 |
| 2 | 搜索 | pageNum=1，按条件查询，底部汇总随结果更新 | ✅ |
| 3 | 查询所有 | 重置搜索条件并查询全部 | ✅ |
| 4 | 物料分类标签 | 点击标签筛选，再点取消 | ✅ 截图确认标签存在 |
| 5 | 导出 | 弹出确认弹窗→确认→下载 Excel | ✅ |
| 6 | 打印 | 调用浏览器打印 | ✅ 按钮存在 |
| 7 | 行点击 | **无跳转/无详情页**（纯报表，行不可点击） | ✅ 采集确认无链接 |
| 8 | 底部汇总 | 实时显示：采购数量/已订数量/未订数量 三项合计 | ✅ 截图确认 |

---

## 7. 接口调用说明

### 7.1 接口总览

| 序号 | 功能 | 方法 | 路径 | 说明 |
|------|------|------|------|------|
| 1 | 查询需求列表 | GET | /mp/plan/need/list | 分页查询采购计划需求 |
| 2 | 导出 | GET | /mp/plan/need/export | 导出 Excel |

### 7.2 查询需求列表

```
GET /mp/plan/need/list
```

**请求参数:**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | integer | 否 | 页码，默认 1 |
| pageSize | integer | 否 | 每页数，默认 100 |
| salesOrderCode | string | 否 | 销售订单号（模糊） |
| itemCode | string | 否 | 物料编码（模糊） |
| itemName | string | 否 | 物料名称（模糊） |
| businessType | string | 否 | 业务类型（原材料/零部件等） |
| needType | string | 否 | 需求方式（0=订单用料/1=备库用料） |
| dataScope | string | 否 | 数据范围 |
| beginDate | string | 否 | 开始日期 (yyyy-MM-dd) |
| endDate | string | 否 | 结束日期 (yyyy-MM-dd) |

**响应示例:**

```json
{
  "total": 6,
  "rows": [
    {
      "salesOrderCode": "XSDD000085",
      "planCode": "CGJH000033",
      "itemCode": "1000000002",
      "itemName": "微星 MAG B760M MORTAR WIFI DDR5 主板",
      "demandQty": 2.00,
      "availableQty": -168.00,
      "purchaseQty": 2.00,
      "orderedQty": 0.00,
      "unorderedQty": 2.00,
      "purchaseDate": "2026-2-7",
      "remark": ""
    }
  ],
  "code": 200,
  "msg": "查询成功"
}
```

### 7.3 导出

```
GET /mp/plan/need/export
```

请求参数同查询接口，返回 Excel 文件流。

---

## 8. 业务规则

### 8.1 数据范围

| 规则 | 说明 |
|------|------|
| 数据来源 | 仅展示**已审核**的采购计划单中的物料需求 |
| 默认日期 | 默认查询近一周数据 |
| 可用量计算 | 实时查询库存可用量，可为负值 |
| 未订数量 | 采购数量 - 已订数量，表示尚未转为采购订单的部分 |

### 8.2 筛选规则

| 筛选方式 | 说明 |
|----------|------|
| 搜索框 | 按销售订单号、物料编码、物料名称模糊搜索 |
| 日期范围 | 按采购计划单日期筛选 |
| 物料分类标签 | 按物料大类（原材料/零部件/五金）快捷筛选 |
| 下拉选择 | 按业务类型/需求方式/数据范围筛选 |

### 8.3 与其他页面的关系

| 关联页面 | 关系 |
|----------|------|
| 采购计划单 | 需求数据来源，planCode 可追溯到具体采购计划 |
| 采购订单 | 已订数量来源，可判断计划执行进度 |
| 销售订单 | 通过 salesOrderCode 追溯到原始销售需求 |
| 生产计划单 | 通过采购计划间接关联 |

---

## 9. 前端组件设计

### 9.1 文件结构

```
src/
├── api/
│   └── mp/
│       └── need.js                        # 采购计划需求表 API
├── views/
│   └── mp/
│       └── plan/
│           └── need.vue                   # 采购计划需求表（单文件组件）
```

### 9.2 组件结构（单文件 need.vue）

由于本页面为纯报表，无详情页/弹窗，建议用单个 Vue 文件实现：

```vue
<template>
  <div class="app-container">
    <!-- 搜索区域 -->
    <el-form :model="queryParams" :inline="true" @submit.prevent="handleQuery">
      <el-form-item label="销售订单号">
        <el-input v-model="queryParams.salesOrderCode" placeholder="销售订单号" clearable />
      </el-form-item>
      <el-form-item label="物料编码">
        <el-input v-model="queryParams.itemCode" placeholder="物料编码" clearable />
      </el-form-item>
      <el-form-item label="物料名称">
        <el-input v-model="queryParams.itemName" placeholder="物料名称" clearable />
      </el-form-item>
      <el-form-item label="日期">
        <el-date-picker v-model="dateRange" type="daterange" ... />
      </el-form-item>
      <el-form-item>
        <el-button type="primary" @click="handleQuery">搜索</el-button>
      </el-form-item>
    </el-form>

    <!-- 工具栏 + 快捷标签 -->
    <el-row :gutter="10" class="mb8">
      <el-col :span="1.5"><el-button @click="handleQueryAll">查询所有</el-button></el-col>
      <el-col :span="1.5"><el-button type="warning" @click="handleExport">导出</el-button></el-col>
      <el-col :span="1.5"><el-button @click="handlePrint">打印</el-button></el-col>
      <!-- 快捷标签 -->
      <el-tag v-for="tag in categoryTags" :key="tag" :effect="activeTag===tag?'dark':'plain'" @click="filterByCategory(tag)">{{ tag }}</el-tag>
    </el-row>

    <!-- 数据表格 -->
    <el-table :data="tableData" border stripe>
      <el-table-column type="index" label="序号" width="60" align="center" />
      <el-table-column prop="salesOrderCode" label="销售订单号" width="140" />
      <el-table-column prop="planCode" label="计划单号" width="140" />
      <el-table-column prop="itemCode" label="物料编码" width="120" />
      <el-table-column prop="itemName" label="物料名称" min-width="250" />
      <el-table-column prop="demandQty" label="需求数量" width="100" align="right" />
      <el-table-column prop="availableQty" label="可用量" width="100" align="right" />
      <el-table-column prop="purchaseQty" label="采购数量" width="100" align="right" />
      <el-table-column prop="orderedQty" label="已订数量" width="100" align="right" />
      <el-table-column prop="unorderedQty" label="未订数量" width="100" align="right" />
      <el-table-column prop="purchaseDate" label="单据日期" width="100" align="center" />
      <el-table-column prop="remark" label="采购说明" width="120" />
    </el-table>

    <!-- 底部汇总 + 分页 -->
    <div class="footer-summary">
      采购数量：{{ totalPurchaseQty }}  已订数量：{{ totalOrderedQty }}  未订数量：{{ totalUnorderedQty }}
    </div>
    <pagination :total="total" :page.sync="queryParams.pageNum" :limit.sync="queryParams.pageSize" @pagination="getList" />
  </div>
</template>
```

---

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

本页面无状态标签（纯报表）。如需标记可用量为负值的行：

```javascript
// 可用量为负值时红色高亮
const availableQtyClass = (val) => val < 0 ? 'text-danger' : ''
```

## 附录B: Playwright 采集数据摘要

> 采集时间: 2026-02-07 16:57:43，脚本: `crawl_purchase_need.py`

| 项目 | 值 |
|------|------|
| 表头 | 序号/销售订单号/计划单号/物料编码/物料名称/需求数量/可用量/采购数量/已订数量/未订数量/单据日期/采购说明 |
| 按钮 | 搜索/查询所有/导出/打印 |
| 行数 | 6 |
| 底部汇总 | 采购数量：186，已订数量：0，未订数量：186 |
| 快捷标签 | 原材料/零部件/五金（截图确认） |
| 搜索 placeholder | 销售订单号/物料编码/物料名称/开始日期/结束日期/请选择 |
| 详情页 | 无（纯报表） |
| 首行数据 | XSDD000085, CGJH000033, 1000000002, 微星 MAG B760M MORTAR WIFI DDR5 主板, 需求=2, 可用=-168, 采购=2 |

---

## 修订历史

| 版本 | 日期 | 修订内容 | 修订人 |
|------|------|----------|--------|
| 1.0.0 | 2026-02-07 | 初始版本：基于 Playwright 自动采集（3 个按钮/2 张截图）+ 生产计划 PRD + 前端开发规范 + 数据库设计编写完整页面开发说明 | System |