12 KiB

Raw Blame History

暂存柜功能文档

概述

storage-cells-summary 组件是智能柜管理系统中用于暂存柜（临时存储）功能的核心组件。该组件提供以下核心功能：

可用格口展示 - 显示当前店铺/区域的可用暂存柜格口，按格口类型（小格、中格、大格、超大格）分类统计
格口选择 - 允许用户选择特定类型的格口进行物品存入
物品存入流程 - 完整的存入物品流程：分配格口 → 生成密码 → 验证密码 → 打开格口
物品取出流程 - 通过密码验证取出已暂存的物品
状态管理 - 使用状态机模式管理弹窗流程，确保业务流程完整性

功能特性

1. 数据展示

实时获取并显示可用格口数量
按四种格口类型分类统计：小格(1)、中格(2)、大格(3)、超大格(4)
显示每种类型的剩余可用数量
支持刷新数据

2. 格口选择

可视化格口类型卡片展示
显示每种类型的SVG图标
智能禁用无可用格口的类型
选中状态视觉反馈

3. 存入流程

用户点击"物品暂存" → 分配选定类型格口 → 生成4位数字密码 →
显示密码给用户 → 用户确认已记住 → 输入密码验证 →
验证通过打开格口 → 刷新格口状态

4. 取出流程

用户点击"物品取出" → 输入4位密码 → 验证密码 →
验证通过打开格口 → 刷新格口状态

5. 用户交互

加载状态提示
错误状态处理与重试
空状态提示
弹窗式密码输入与验证
数字键盘集成

组件结构

文件位置

src/components/storage-cells-summary/
├── index.vue              # 主组件文件
└── usePopupState.ts      # 弹窗状态管理hook

组件Props

属性名	类型	默认值	说明
`shopId`	`number`	必填	店铺ID，用于获取可用格口列表
`autoLoad`	`boolean`	`true`	是否自动加载数据
`showButtons`	`boolean`	`true`	是否显示操作按钮（存入/取出）

组件Emits

事件名	参数	说明
`deposit`	无	点击存入按钮时触发（向后兼容）
`retrieve`	无	点击取出按钮时触发（向后兼容）
`refresh`	无	数据刷新完成时触发
`error`	`Error`	数据加载失败时触发
`backToAddressSelect`	无	点击"重选地址"按钮时触发

核心状态变量

变量名	类型	说明
`loading`	`Ref<boolean>`	数据加载状态
`error`	`Ref<Error \| null>`	错误信息
`cellsData`	`Ref<AvailableStorageCellDTO[]>`	格口数据列表
`selectedCellType`	`Ref<number>`	当前选中的格口类型
`depositLoading`	`Ref<boolean>`	存入操作加载状态
`retrieveLoading`	`Ref<boolean>`	取出操作加载状态
`generatedPassword`	`Ref<string>`	生成的密码（向后兼容）

计算属性

属性名	说明
`availableCells`	过滤出无密码的可用格口
`cellTypeStats`	按类型统计可用格口数量
`hasAvailableCells`	是否存在可用格口

业务流程

1. 数据初始化流程

graph TD
    A[组件挂载] --> B{autoLoad为true?};
    B -->|是| C[调用refresh函数];
    B -->|否| D[等待手动刷新];
    C --> E[调用availableStorageCells API];
    E --> F[更新cellsData];
    F --> G[触发refresh事件];

2. 物品存入流程

graph TD
    A[用户点击"物品暂存"] --> B[触发deposit事件];
    B --> C[调用handleDepositFlow];
    C --> D[调用storeItemApi分配格口];
    D --> E{是否获取到密码?};
    E -->|是| F[显示密码弹窗];
    E -->|否| G[显示错误提示];
    F --> H[用户点击"已记住"];
    H --> I[进入密码验证状态];
    I --> J[用户输入密码];
    J --> K[密码验证];
    K --> L{密码正确?};
    L -->|是| M[调用openByPassword打开格口];
    L -->|否| N[显示密码错误提示];
    M --> O[显示成功提示];
    O --> P[刷新格口数据];

3. 物品取出流程

graph TD
    A[用户点击"物品取出"] --> B[触发retrieve事件];
    B --> C[显示密码输入弹窗];
    C --> D[用户输入密码];
    D --> E[调用openByPassword打开格口];
    E --> F[显示成功提示];
    F --> G[刷新格口数据];

API接口

依赖的API模块

import {
  availableStorageCells,   // 获取可用格口列表
  storeItemApi,           // 存入物品分配格口
  openByPassword,         // 根据密码打开格口
  resetByPassword         // 重置格口状态（当前未使用）
} from '@/api/cabinet/index'

1. availableStorageCells

功能：获取指定店铺的可用暂存柜格口列表

请求参数：

{
  shopId: number  // 店铺ID
}

响应数据结构：AvailableStorageCellDTO[]

interface AvailableStorageCellDTO {
  cellId: number;          // 格口ID
  cabinetId: number;       // 柜机ID
  cabinetName: string;     // 柜子名称
  mainboardId: number;     // 主板ID
  cellNo: number;         // 格口号
  pinNo: number;          // 针脚序号
  stock: number;          // 库存数量
  cellPrice: number;      // 格口租用价格
  isRented: number;       // 是否已租用（0-未租用，1-已租用）
  cellType: number;       // 格口类型（1-小格，2-中格，3-大格，4-超大格）
  usageStatus: number;    // 使用状态（1-空闲，2-已占用）
  availableStatus: number;// 可用状态（1-正常，2-故障）
  hasPassword: boolean;   // 是否有密码（true-有密码/已占用，false-无密码/可用）
  goodsId: number;        // 商品ID
  goodsName: string;      // 商品名称
  price: number;         // 商品价格
  coverImg: string;      // 封面图URL
}

2. storeItemApi

功能：存入物品并分配格口，生成访问密码

请求参数：StoreItemToCellCommand

interface StoreItemToCellCommand {
  shopId: number;    // 店铺ID
  cellType: number;  // 格口类型（1-小格，2-中格，3-大格，4-超大格）
}

响应数据结构：CabinetCellEntity

interface CabinetCellEntity {
  cellId: number;          // 格口唯一ID
  cabinetId: number;       // 关联柜机ID
  mainboardId?: number;    // 主板ID
  cellNo: number;         // 格口号
  pinNo: number;          // 针脚序号
  stock: number;          // 库存数量
  cellPrice?: number;     // 格口价格
  isRented: number;       // 是否已租用：0-未租用，1-已租用
  cellType: number;       // 格口类型（1小格 2中格 3大格 4超大格）
  usageStatus: number;    // 使用状态：1空闲 2已占用
  availableStatus: number;// 可用状态：1正常 2故障
  goodsId?: number;       // 商品ID
  password?: string;      // 密码（暂存模式使用）
}

3. openByPassword

功能：根据密码打开对应的格口

请求参数：OpenCellByPasswordCommand

interface OpenCellByPasswordCommand {
  shopId: number;     // 店铺ID
  password: string;   // 格口密码
}

响应：无数据，成功时HTTP状态码为200

状态管理：usePopupState

状态机设计

弹窗流程采用状态机模式，确保业务流程的完整性和一致性：

状态类型	说明	显示内容
`idle`	空闲状态，无弹窗显示	无弹窗
`password-show`	显示生成的密码	密码显示弹窗
`password-verify`	验证用户输入的密码	密码输入框+验证按钮
`retrieve-input`	输入取出密码	密码输入框+确认按钮
`processing`	显示处理中的加载提示	加载动画+处理文本

状态转换图

graph LR
    A[idle] -->|存入流程开始| B[password-show];
    B -->|点击"已记住"| C[password-verify];
    C -->|密码验证通过| D[processing];
    C -->|密码验证失败| C;
    A -->|取出流程开始| E[retrieve-input];
    E -->|输入密码确认| D[processing];
    D -->|操作完成| A;
    B -->|取消| A;
    C -->|取消| A;
    E -->|取消| A;

Hook接口

interface UsePopupStateReturn {
  currentState: Ref<PopupState>;           // 当前弹窗状态
  popupInputValue: Ref<string>;           // 弹窗输入框的值
  passwordLength: number;                 // 密码长度（固定为4）
  popupVisible: ComputedRef<boolean>;     // 弹窗显示状态
  keyboardVisible: Ref<boolean>;          // 键盘显示状态
  popupTitle: ComputedRef<string>;        // 弹窗标题
  popupMessage: ComputedRef<string>;      // 弹窗消息内容
  popupConfirmText: ComputedRef<string>;  // 确认按钮文本
  showCancelButton: ComputedRef<boolean>; // 是否显示取消按钮
  transitionTo: (state: PopupState) => void; // 状态转换函数
  // ... 其他处理函数
}

使用方法

1. 基本使用

<template>
  <storage-cells-summary
    :shop-id="currentShopId"
    :auto-load="true"
    :show-buttons="true"
    @deposit="handleDeposit"
    @retrieve="handleRetrieve"
    @refresh="handleRefresh"
    @error="handleError"
    @back-to-address-select="handleBack"
  />
</template>

2. 仅展示模式

<template>
  <storage-cells-summary
    :shop-id="currentShopId"
    :show-buttons="false"
  />
</template>

3. 手动控制数据加载

<template>
  <storage-cells-summary
    ref="storageRef"
    :shop-id="currentShopId"
    :auto-load="false"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue'

const storageRef = ref()

// 手动刷新数据
function refreshData() {
  storageRef.value?.refresh()
}
</script>

样式与UI组件

使用的UI组件

wd-popup - 弹窗容器
wd-password-input - 密码输入框（格子模式）
wd-keyboard - 数字键盘
wd-button - 按钮
wd-loading - 加载动画
wd-icon - 图标
wd-row / wd-col - 栅格布局

样式特点

使用 rpx 单位适配不同屏幕
响应式网格布局（2列）
交互状态反馈（点击效果、选中状态）
弹窗圆角设计（border-top-left-radius: 24rpx）
安全区域适配（safe-area-inset-bottom）

注意事项

1. 密码安全

密码为4位数字，由系统自动生成
密码仅在存入流程中显示一次，用户需要牢记
密码验证失败会提示错误，但不会泄露正确密码

2. 格口状态同步

每次成功操作（存入/取出）后会自动刷新格口数据
可用格口数量实时更新
已被占用的格口（hasPassword: true）不会显示在可用列表中

3. 错误处理

网络请求失败会显示错误提示
用户可点击"重试"按钮重新加载
操作失败会回到初始状态，不会卡在中间状态

4. 向后兼容性

保留了 deposit 和 retrieve 事件发射
保留了 generatedPassword 状态变量
新增的 handleDepositFlow 和 handleRetrieveFlow 函数与原有事件处理并行

5. 性能考虑

按需加载数据（autoLoad控制）
计算属性缓存统计结果
避免不必要的重复请求

12 KiB Raw Blame History Unescape Escape