shop-wx/doc/Shop运行模式文档.md

# Shop运行模式文档

本文档详细说明项目中Shop的mode运行模式相关处理逻辑。运行模式决定了商店的业务流程、支付方式以及用户交互方式。

## 运行模式定义

在 `src/api/shop/types.ts` 中定义了Shop实体和运行模式：

```typescript
export interface ShopEntity {
  /** 主键ID */
  shopId: number;
  /** 商店名称 */
  shopName: string;
  /** 企业微信id */
  corpid: string;
  /** 运行模式（0-支付模式 1-审批模式 2-借还模式 3-会员模式 4-耗材模式） */
  mode?: number;
  /** 借呗支付（1-正常使用 0-禁止使用） */
  balanceEnable?: number;
  /** 封面图URL */
  coverImg?: string;
}
```

运行模式的具体含义：

| 模式值 | 模式名称 | 说明 |
|--------|----------|------|
| 0 | 支付模式 | 用户直接支付购买商品 |
| 1 | 审批模式 | 需要审批流程后才能购买 |
| 2 | 借还模式 | 借还物品模式 |
| 3 | 会员模式 | 会员租用模式 |
| 4 | 耗材模式 | 耗材领用模式 |

## 支付方式映射

不同运行模式支持不同的支付方式，映射关系定义在 `src/utils/maps/payment.ts`：

```typescript
export const modeToPaymentMethodMap: Record<number, number[]> = {
  0: [0],        // 支付模式：微信支付
  1: [0, 1],     // 审批模式：微信支付、借呗支付
  2: [0, 1],     // 借还模式：微信支付、借呗支付
  3: [0],        // 会员模式：微信支付
  4: [2],        // 耗材模式：要呗支付
};
```

支付方式的枚举值：
- `0`: 微信支付
- `1`: 借呗支付
- `2`: 要呗支付

## 业务逻辑处理

### 1. 首页模式切换 (`pages/index/index.vue`)

首页根据选中的商店模式决定显示内容：

```typescript
// 当选择商店时触发
if (selectedShop.mode == 3) {
  // 会员模式：进入租用模式
  rentingCabinetStore.fetchRentingCabinetDetail(selectedShopId);
} else {
  // 其他模式：获取普通商品列表
  productStore.getGoods(selectedShopId);
}
```

### 2. 结账页面处理 (`pages/index/checkout.vue`)

结账页面使用 `isRentingMode` 计算属性区分模式：

```typescript
// 是否为租用模式（会员模式）
const isRentingMode = computed(() => {
  return selectedShop.value?.mode === 3;
});
```

根据模式渲染不同的商品列表：
- 普通模式：显示普通购物车商品
- 租用模式：显示租用购物车商品

支付方式动态确定：
```typescript
// 根据模式获取支持的支付方式
const paymentMethodList = computed(() => {
  const mode = selectedShop.value?.mode || 0;
  const methods = modeToPaymentMethodMap[mode] || [0];
  return methods;
});
```

订单提交时传递模式参数：
```typescript
// 在 SubmitOrderRequestData 中包含 mode 字段
const submitData: SubmitOrderRequestData = {
  // ... 其他字段
  mode: selectedShop.value?.mode || 0,
  goodsList: [
    {
      // ... 商品信息
      mode: selectedShop.value?.mode || 0, // 每个商品项也包含 mode
    }
  ]
};
```

### 3. 购物车管理 (`pages/index/components/cart.vue`)

购物车组件支持两种模式：
- 普通购物车：用于模式 0,1,2,4
- 租用购物车：用于模式 3

提供统一的购物车操作方法，内部根据模式区分处理。

### 4. 租用模式专门处理 (`pages/index/components/renting-cabinet-container.vue`)

专门为会员模式（租用模式）设计的组件，提供：
- 租用格口的选择界面
- 不同尺寸格口的展示（使用SVG图标）
- 加入租用购物车功能
- 租用时长和费用计算

## 相关API端点

### 获取店铺列表
```
GET /shop/list
```
支持根据mode参数过滤店铺。

### 提交订单
```
POST /order/submit
```
请求体需要包含 `mode` 字段，表示订单的运行模式。

### 订单数据模型
在 `SubmitOrderRequestData` 中：
```typescript
export interface SubmitOrderRequestData {
  // ... 其他字段
  /** 运行模式（0-支付模式 1-审批模式 2-借还模式 3-会员模式 4-耗材模式） */
  mode: number;
  /** 订单商品明细列表 */
  goodsList: Array<{
    // ... 商品信息
    /** 运行模式（0-支付模式 1-审批模式 2-借还模式 3-会员模式 4-耗材模式） */
    mode: number;
  }>;
}
```

## 组件和页面

### 主要页面
1. **首页 (`pages/index/index.vue`)**
   - 模式切换和渲染
   - 根据模式调用不同的数据获取方法

2. **结账页面 (`pages/index/checkout.vue`)**
   - 模式支付处理
   - 订单提交逻辑

### 主要组件
1. **购物车组件 (`pages/index/components/cart.vue`)**
   - 模式购物车管理
   - 统一的操作接口

2. **租用柜格容器组件 (`pages/index/components/renting-cabinet-container.vue`)**
   - 租用模式专门UI
   - 格口选择和租用逻辑

3. **商品容器组件 (`pages/index/components/product-container.vue`)**
   - 普通商品展示
   - 适用于非租用模式

## 模式处理流程图

```mermaid
graph TD
    A[用户访问首页] --> B{选择商店}
    B --> C[获取商店信息]
    C --> D{检查商店模式}
    D -->|模式=3| E[进入租用模式]
    D -->|模式≠3| F[进入普通模式]

    E --> E1[显示租用柜格容器]
    E --> E2[使用租用购物车]
    E --> E3[租用结算流程]

    F --> F1[显示商品容器]
    F --> F2[使用普通购物车]
    F --> F3[普通结算流程]

    E3 --> G[提交订单]
    F3 --> G

    G --> H{根据模式确定支付方式}
    H --> I[完成订单]
```

## 开发注意事项

1. **模式判断一致性**
   - 始终使用 `selectedShop.value?.mode` 获取当前模式
   - 模式判断应集中在业务逻辑入口处

2. **支付方式配置**
   - 修改支付方式映射时更新 `payment.ts` 文件
   - 确保前端支付方式与后端一致

3. **租用模式特殊处理**
   - 模式3有专门的组件和流程
   - 租用购物车与普通购物车数据分离

4. **扩展新模式**
   - 在 `types.ts` 中更新模式注释
   - 更新 `payment.ts` 中的支付方式映射
   - 根据需要添加新的业务逻辑分支

## 常见问题

**Q: 如何添加新的运行模式？**
A: 1. 在 `types.ts` 中更新模式定义注释；2. 在 `payment.ts` 中添加支付方式映射；3. 在业务逻辑中添加新的处理分支。

**Q: 模式如何影响支付方式？**
A: 通过 `modeToPaymentMethodMap` 映射关系确定，前端根据当前模式过滤可用的支付方式。

**Q: 租用模式与其他模式的主要区别？**
A: 租用模式使用独立的购物车系统、专门的UI组件和不同的结算逻辑。

---

*文档最后更新：2025-12-15*
*维护者：Claude Code*