refactor(库存盘点): 明细面板统一走 stock.check.result(detail 已不再返回明细列表)

This commit is contained in:
liufumingren 2026-10-10 04:33:39 +08:00
parent 460c8984b9
commit 66a40bbec4
3 changed files with 35 additions and 44 deletions

View File

@ -55,7 +55,7 @@ export type StockCheckEnvelope<T> = {
* **未知商品** = stock_id 未命中、按 barcode 也匹配不到系统商品 → 记录 stock_id=NULL +
* barcode + item_name(缺省为条码);无账面数量、实盘 >0 即盘盈,走 unknown_items 聚合;
* 一个明细可以有多个库位的记录,明细行上的 checked_quantity/diff_quantity 均为记录聚合值;
* ⚠️ 明细**范围行**(stock.check.detail)不含任何作业聚合,聚合请看 stock.check.result;
* ⚠️ 明细**范围行**请看 stock.check.result(stock.check.detail 只返回任务主体,已无 rows);
* recordList / recordDelete 用于查看与删除作业记录,删除不影响主表状态。
* 未盘明细 = 无作业记录的明细(finish 时按实盘 0 处理,计入盘亏与差异行数)。
*/
@ -86,7 +86,7 @@ export type StockCheckType =
| 'store' // 按货主按商品盘点(商品行)
| 'goods' // 按商品盘点(商品行)
/** 明细行形态(stock.check.detail 的 rows[].scope_type) */
/** 明细行形态(stock.check.result 的 rows[].scope_type) */
export type StockCheckScopeType = 'goods' | 'location'
/** 盘点方式 */
@ -244,7 +244,8 @@ export type StockCheckUnknownItem = {
}
/**
* 盘点**范围行**(stock.check.detail 的 rows 元素)—— 纯范围行,**不含任何盘点作业聚合**
* 盘点**范围行**(stock.check.result 的 rows 基础字段;stock.check.detail 已不再返回 rows)
* —— 纯范围行,**不含任何盘点作业聚合**
*
* 两种形态(看 scope_type):
* - goods(商品行):stock_id 与商品快照有值,location_id/location_code 为 null
@ -793,21 +794,22 @@ export type StockCheckDetailParams = {
id: number
}
/** stock.check.detail 响应(纯范围行,**不含盘点作业聚合**) */
/** stock.check.detail 响应(**只返回任务主体**;明细范围行 + 作业聚合请看 stock.check.result) */
export type StockCheckDetailResponse = {
/** 盘点主表信息 */
check: StockCheckTask
/** 全部范围行 */
rows: StockCheckDetailRow[]
/** 明细总条数 */
total: number
/** 盘点主表信息(额外附盘盈/盘亏合计,口径与 finish 一致) */
check: StockCheckTask & {
/** 盘盈合计数量 */
profit_total?: number
/** 盘亏合计数量(正数口径) */
loss_total?: number
}
}
/**
* stock.check.detail:拉取盘点任务主表 + 全部**范围行**(不分页)
* stock.check.detail:拉取**盘点任务详情**(只返回任务主表信息,**不再返回明细列表**)。
*
* rows 为纯范围行(商品行/库位行的商品/库位快照),不含盘点作业聚合;
* 需要已盘/差异/状态/作业记录等「盘点结果」时请用 stockCheckResult。
* 明细范围行(行列快照)与盘点作业聚合(已盘/差异/状态/记录)请用 stockCheckResult;
* 作业记录明细用 recordList,盘点作业数据用 workData。
*/
export function stockCheckDetail(
data: StockCheckDetailParams
@ -1170,7 +1172,7 @@ export type StockCheckWorkDataResponse<
* 「当前状态(xx)不允许拉取盘点作业数据,仅审核完成(approved)或盘点作业中(checking)的任务可拉取」
* → 前端应在非这两种状态时**不发请求**。
*
* 与 detail / result 的区别:detail 只给范围行、result 按明细行聚合作业记录,
* 与 detail / result 的区别:detail 只给任务主体(已无 rows)、result 按明细行聚合作业记录,
* workData 直接给「作业视角」的三套结构,前端无需再自行聚合。
* 需要「一行一条明细」时用 `stockCheckWorkDataDetail`(单条明细)、
* space 视图要服务端分页时用 `stockCheckWorkDataSpaceDetails`。

View File

@ -2,11 +2,11 @@
CheckItemsPanel — 盘点明细面板(库存盘点 stock.check)
职责:
1. 拉取盘点明细并渲染:
- 已有/可能有作业记录的阶段(approved/checking/completed/cancelled)→ **stock.check.result**
(范围行 + 已盘/差异/状态/作业记录聚合)
- 尚未开始作业的阶段(created/rejected/submitted,必然无作业记录)→ **stock.check.detail**
(纯范围行,不含聚合;此时作业类列不渲染,无需多发一次聚合查询)
1. 拉取盘点明细并渲染(**统一走 stock.check.result**):
- `stock.check.detail` 已**不再返回明细列表**(仅返回任务主体 `check`),故无论任务状态
(created/rejected/submitted/approved/checking/completed/cancelled)都取 result:
`{ check, rows, total }`,未开始作业阶段 rows 只是「范围行」(已盘=null、差异=null、状态=未盘)。
- 不再多发一次聚合查询,也不再需要按状态切接口。
明细行形态由任务 type 决定,表格统一「平铺」展示(不用展开行):
- 商品行(scope_type=goods,type=store/goods):一行一个库存商品(商品快照 + 已盘聚合);
行级聚合(checked_quantity/diff_quantity)**已含未知商品**,故不再平铺 unknown_items,
@ -76,7 +76,6 @@
</el-button>
</div>
<div class="right-actions">
<span v-if="!useResultSource" class="hint-text">未开始盘点:仅展示盘点范围</span>
<span v-if="isQuantityMasked" class="hint-text">盲盘:账面数量不可见</span>
<span class="stat-text">
明细 {{ stats.total }} · 已盘 {{ stats.checked }} · 差异 {{ stats.diff }}
@ -165,30 +164,30 @@
<span v-else class="hint-text">—</span>
</template>
</el-table-column>
<el-table-column v-if="useResultSource" label="已盘合计" width="100" align="center">
<el-table-column label="已盘合计" width="100" align="center">
<template #default="{ row }">{{ row.checked_quantity ?? '—' }}</template>
</el-table-column>
<el-table-column v-if="useResultSource" label="差异" width="90" align="center">
<el-table-column label="差异" width="90" align="center">
<template #default="{ row }">
<span v-if="isQuantityMasked" class="hint-text">—</span>
<span v-else :class="diffClass(row.diff_quantity)">{{ formatDiff(row.diff_quantity) }}</span>
</template>
</el-table-column>
<el-table-column v-if="useResultSource" label="盘点状态" width="100" align="center">
<el-table-column label="盘点状态" width="100" align="center">
<template #default="{ row }">
<span :class="getStatusTextClass(itemStatusTag(row.status))">
{{ translate('check_item_status', row.status) }}
</span>
</template>
</el-table-column>
<el-table-column v-if="useResultSource" label="盘点人" width="110" show-overflow-tooltip>
<el-table-column label="盘点人" width="110" show-overflow-tooltip>
<template #default="{ row }">{{ formatCheckers(row) }}</template>
</el-table-column>
<el-table-column v-if="useResultSource" label="最近上报" width="160">
<el-table-column label="最近上报" width="160">
<template #default="{ row }">{{ formatTime(row.last_checked_at) }}</template>
</el-table-column>
<!-- 作业图片:result 的 records[].images(业务类型 stock_check_record) -->
<el-table-column v-if="useResultSource" label="作业图片" width="110" align="center">
<el-table-column label="作业图片" width="110" align="center">
<template #default="{ row }">
<RecordImages :images="rowImages(row)" :max="2" />
</template>
@ -260,7 +259,6 @@ import { formatTime, isCheckApiSuccess, isLocationScopeType, translate } from '.
import RecordImages from './RecordImages.vue'
import CheckReportDialog from './CheckReportDialog.vue'
import {
stockCheckDetail,
stockCheckFinish,
stockCheckMarkEmpty,
stockCheckReport,
@ -301,15 +299,6 @@ const canReport = computed(() => ['approved', 'checking'].includes(taskStatus.va
const isCompleted = computed(() => taskStatus.value === 'completed')
/** 库位类任务(type=all/location):明细为「库位行」,上报需带 stock_id → 在展开行里按商品上报 */
const isLocationTask = computed(() => isLocationScopeType(props.row?.type))
/**
* 是否已有/可能有作业记录 —— 决定明细取数接口:
* true → stock.check.result(范围行 + 作业聚合)
* false → stock.check.detail(纯范围行,不含聚合)
* created/rejected/submitted 阶段后端不会有作业记录,聚合字段必然为空,故只取范围行。
*/
const useResultSource = computed(
() => !['created', 'rejected', 'submitted'].includes(taskStatus.value)
)
/** 盲盘:账面数量前端不可见 */
const isBlind = computed(() => String(props.row?.mode ?? '') === 'blind')
const isQuantityMasked = computed(
@ -561,10 +550,9 @@ async function loadItems() {
}
loading.value = true
try {
// 有作业记录阶段取「结果」(含已盘/差异/作业记录聚合);未开始作业阶段只取「范围行」
const res: any = useResultSource.value
? await stockCheckResult({ id: taskId.value })
: await stockCheckDetail({ id: taskId.value })
// 统一走 result:stock.check.detail 已不再返回明细列表(只返回 check),
// 未开始作业阶段 result 也能正常返回「范围行」(已盘/差异为 null、状态=未盘)
const res: any = await stockCheckResult({ id: taskId.value })
if (!isCheckApiSuccess(res)) {
throw new Error(res?.message || '获取盘点明细失败')
}
@ -595,8 +583,8 @@ function ownLocationCode(item: Record<string, any>): string {
* 明细库位编码集合
*
* - 结果行(stock.check.result):取 location_codes,其次 locations 兜底
* - 范围行(stock.check.detail,未开始作业阶段):无聚合字段,**库位行**(scope_type=location)
* 取自身 location_code(否则库位列显示「—」,detail 的库位行只带 location_code)
* - 未开始作业阶段的范围行(result 同样返回):无聚合字段,**库位行**(scope_type=location)
* 取自身 location_code(否则库位列显示「—」,此时行上只带 location_code)
* 「无库位」分组的空串/null 一律剔除;商品行不掺入自身预设库位
*/
function resolveLocationCodes(item: Record<string, any>): string[] {

View File

@ -6,7 +6,8 @@
* `src/api/stock.check/stock.check.ts`:
*
* 列表 stock.check.list → 本文件 tabPages[].api.list
* 详情 stock.check.detail → CheckItemsPanel(明细面板自行拉取)
* 详情 stock.check.detail → DetailPanel(任务主体;由列表行填充,不再拉明细)
* 明细结果 stock.check.result → CheckItemsPanel(明细面板统一数据源)
* 新建 stock.check.create → pages/CheckFormDialog.vue
* 定式清单 stock.check.patternList → pages/CheckPatternDialog.vue(快速创建)
* 快速创建 stock.check.patternCreate → pages/CheckPatternDialog.vue(按定式创建,免填日期)
@ -226,7 +227,7 @@ export const VALUE_MAPS: Record<string, Record<string, string>> = {
goods: '商品',
location: '库位'
},
/** 明细行状态(stock.check.detail 的 rows[].status:checked=有作业记录 / unchecked=未盘) */
/** 明细行状态(stock.check.result 的 rows[].status:checked=有作业记录 / unchecked=未盘) */
check_item_status: {
unchecked: '未盘',
checked: '已盘点'