zkxw/docs/superpowers/specs/2026-06-15-market-material-my-usage-design.md

市场物料库「我的物料领用记录」功能设计

日期: 2026-06-15 状态: 已批准实施

1. 需求背景

市场物料库（/market/market-info/material）已有物料列表和变动记录功能，但缺少像生产物料库、质检物料库那样的「我的物料领用记录」独立页面。

用户需要能够：

• 查看自己领用的市场物料记录
• 标记物料为"已使用完"

2. 设计方案

2.1 架构模式

采用与生产物料库、质检物料库相同的复用模式：

市场基础信息菜单
└── 我的物料领用记录 → MaterialUsageTab (mineOnly=true)
                              ↓
                        fetchMyMaterialUsageList()
                              ↓
                          后端 API

核心思想：页面 = 标题 + Tab组件(mineOnly prop)，复用现有 MaterialUsageTab.vue 组件。

2.2 后端改动

新增接口

接口	方法	路径
我的物料领用记录列表	GET	/web/admin/my-material-usages

请求参数

参数	类型	说明
page	int	页码
pageSize	int	每页条数
keyword	string	关键词（物料编码/名称/入库编号/批号/货号）
materialId	string	物料ID
materialType	string	物料类型（reagent/consumable/configured_reagent）
changeType	string	变动类型（in/out/use/discard）
startTime	string	开始日期（YYYY-MM-DD）
endTime	string	结束日期（YYYY-MM-DD）

响应字段

与现有 /web/admin/material-usages 保持一致，增加 requisitionStatus 字段标识使用状态。

实现逻辑

筛选条件：

• tenant_no = 当前用户租户
• source_type = 'manual_out'（手动出库）
• receiver = 当前用户昵称（或 user_id）
• 按 create_time DESC 排序

接口实现位置

在 app/api/market.py 中实现（新建），或添加到现有相关模块。

2.3 前端改动

2.3.1 API 层

文件: web-admin/src/api/material-usage.ts

新增函数：

export async function fetchMyMaterialUsageList(params: {
  page: number
  pageSize: number
  keyword?: string
  materialId?: string
  materialType?: string
  changeType?: string
  startTime?: string
  endTime?: string
}): Promise<{ list: MaterialUsage[]; total: number }>

调用 GET /web/admin/my-material-usages。

2.3.2 Tab 组件增强

文件: web-admin/src/views/cell-storage/material/MaterialUsageTab.vue

修改点：

1. 添加 mine-only prop（与 ProductionMaterialUsageTab.vue 一致）
2. 当 mine-only=true 时：
   • 调用 fetchMyMaterialUsageList 而非 fetchMaterialUsageList
   • 不显示"入库"变动类型选项
   • 不显示"领用人"列
   • 显示"使用状态"列
3. "使用状态"列逻辑（新增）：

   <el-table-column v-if="mineOnly" label="使用状态" ...>
     <template #default="{ row }">
       <template v-if="isManualOutRow(row)">
         <el-tag v-if="row.requisitionStatus === 'closed'" type="success" size="small">已使用完</el-tag>
         <el-tag v-else type="info" size="small">使用中</el-tag>
       </template>
       <span v-else>—</span>
     </template>
   </el-table-column>
   

2.3.3 新建页面

文件: web-admin/src/views/cell-storage/my-material-usage/index.vue

<template>
  <div class="page-container">
    <section class="panel">
      <div class="panel-top">
        <h2 class="title-bar-heading">我的物料领用记录</h2>
      </div>
      <MaterialUsageTab mine-only />
    </section>
  </div>
</template>

2.3.4 路由配置

文件: web-admin/src/router/modules/sqxp.ts

在「市场基础信息」菜单分组下新增：

{
  path: 'my-material-usage',
  component: '/cell-storage/my-material-usage/index',
  meta: {
    title: '我的物料领用记录',
    icon: 'List',
    menuCode: 'biz:material:myUsage'
  }
}

注意：需要确保菜单项在数据库 sys_menu 表中也创建，或通过后台管理添加。

2.4 页面功能

功能	说明
筛选	关键词、物料筛选（远程搜索）、物料类型、变动类型、时间范围
列表	显示当前用户的手动出库记录
查看详情	打开 SystemViewDialog 查看完整信息
标记已使用完	调用 fetchMarkMaterialUsageFullyUsed
使用状态标识	"已使用完"（绿色）/ "使用中"（灰色）标签

2.5 列表字段

列名	说明
序号	序号
物料编码
物料名称
物料类型	Tag 标签
入库编号
入库日期
货号
批号
厂家
单价（元）
金额（元）
变动类型	Tag 标签
领用数量
变动前库存
变动后库存
使用状态	mineOnly=true 时显示
来源类型	Tag 标签
用途
领用时间
备注
操作人
变动时间
操作	查看、标记已使用完

3. 与现有模块对比

特性	市场物料库	生产物料库	质检物料库
API	/web/admin/my-material-usages	/web/admin/my-production-material-usages	/web/admin/my-qc-material-usages
页面	cell-storage/my-material-usage/	production/my-production-material-usage/	quality-inspection/my-qc-material-usage/
Tab 组件	MaterialUsageTab.vue	ProductionMaterialUsageTab.vue	QcMaterialUsageTab.vue
使用状态列	已使用完/使用中	已使用完/使用中	已使用完/使用中

4. 文件清单

前端

文件	操作
api/material-usage.ts	修改：新增 fetchMyMaterialUsageList
views/cell-storage/material/MaterialUsageTab.vue	修改：添加 mineOnly prop 支持
views/cell-storage/my-material-usage/index.vue	新建
router/modules/sqxp.ts	修改：新增路由

后端

文件	操作
app/api/market.py	新建（或在现有模块中添加）
app/crud/material.py	修改：新增 get_my_usages 方法
app/schemas/material.py	修改：新增 MyMaterialUsageQuery

5. 验收标准

1. 菜单「市场基础信息 → 我的物料领用记录」可正常访问
2. 列表仅显示当前用户的物料出库记录
3. 点击「标记已使用完」后，使用状态变为"已使用完"
4. 查看详情弹窗正常显示
5. 与生产物料库的「我的物料领用记录」功能一致