268 lines
8.4 KiB
Markdown
268 lines
8.4 KiB
Markdown
# Shop 运行模式文档
|
||
|
||
## 概述
|
||
|
||
在智柜宝商店管理系统中，每个商店（Shop）都有一个运行模式（Mode）属性，用于定义商店的业务流程和支付方式。运行模式决定了用户在该商店下单、支付、审批等操作的行为逻辑。
|
||
|
||
本文档详细介绍了 Shop 运行模式的定义、使用场景、相关 API 接口、前端组件实现以及模式与支付方式的映射关系。
|
||
|
||
## 模式枚举定义
|
||
|
||
运行模式使用数字枚举值表示，具体定义如下：
|
||
|
||
| 数值 | 模式名称 | 描述 |
|
||
|------|----------|------|
|
||
| 0 | 支付模式 | 用户直接支付完成订单 |
|
||
| 1 | 审批模式 | 订单需要管理员审批后才能支付 |
|
||
| 2 | 借还模式 | 适用于借用和归还物品的场景 |
|
||
| 3 | 会员模式 | 仅限会员使用，可能涉及会员积分或余额 |
|
||
| 4 | 耗材模式 | 针对耗材管理场景，支持特定支付方式 |
|
||
| 5 | 暂存模式 | 临时存储物品，使用密码打开，无支付环节 |
|
||
|
||
## API 接口定义
|
||
|
||
### 数据结构
|
||
|
||
在 `src/api/shop/shop.ts` 中定义了与模式相关的数据结构：
|
||
|
||
```typescript
|
||
/** 商店分页查询参数 */
|
||
export interface ShopQuery extends BasePageQuery {
|
||
/** 运行模式（0-支付模式 1-审批模式 2-借还模式 3-会员模式 4-耗材模式 5-暂存模式） */
|
||
mode?: number;
|
||
}
|
||
|
||
/** 商店DTO */
|
||
export interface ShopDTO {
|
||
/** 运行模式（0-支付模式 1-审批模式 2-借还模式 3-会员模式 4-耗材模式 5-暂存模式） */
|
||
mode?: number;
|
||
}
|
||
|
||
/** 新增商店命令 */
|
||
export interface AddShopCommand {
|
||
/** 运行模式（0-支付模式 1-审批模式 2-借还模式 3-会员模式 4-耗材模式 5-暂存模式） */
|
||
mode?: number;
|
||
}
|
||
|
||
/** 更新商店命令 */
|
||
export interface UpdateShopCommand {
|
||
/** 运行模式（0-支付模式 1-审批模式 2-借还模式 3-会员模式 4-耗材模式 5-暂存模式） */
|
||
mode?: number;
|
||
}
|
||
```
|
||
|
||
### 工具函数
|
||
|
||
#### `getModeText(mode?: number): string`
|
||
|
||
将运行模式数值转换为文字描述：
|
||
|
||
```typescript
|
||
// 运行模式文字映射
|
||
const modeTextMap = {
|
||
0: '支付模式',
|
||
1: '审批模式',
|
||
2: '借还模式',
|
||
3: '会员模式',
|
||
4: '耗材模式',
|
||
5: '暂存模式'
|
||
};
|
||
|
||
export const getModeText = (mode?: number): string => {
|
||
return mode !== undefined ? modeTextMap[mode] || '' : '';
|
||
};
|
||
```
|
||
|
||
#### `getBalanceEnableText(balanceEnable?: number): string`
|
||
|
||
将借呗支付状态转换为文字描述（与模式相关的支付状态）：
|
||
|
||
```typescript
|
||
// 借呗支付状态文字映射
|
||
const balanceEnableTextMap = {
|
||
0: '禁止使用',
|
||
1: '正常使用'
|
||
};
|
||
|
||
export const getBalanceEnableText = (balanceEnable?: number): string => {
|
||
return balanceEnable !== undefined ? balanceEnableTextMap[balanceEnable] || '' : '';
|
||
};
|
||
```
|
||
|
||
## 前端组件实现
|
||
|
||
### 1. 商店管理表单
|
||
|
||
文件：`src/views/cabinet/shop/shop-form-modal.vue`
|
||
|
||
商店新增和编辑表单中包含运行模式选择字段：
|
||
|
||
```vue
|
||
<el-form-item label="运行模式" prop="mode">
|
||
<el-select v-model="formData.mode" placeholder="请选择运行模式">
|
||
<el-option label="支付模式" :value="0" />
|
||
<el-option label="审批模式" :value="1" />
|
||
<el-option label="借还模式" :value="2" />
|
||
<el-option label="会员模式" :value="3" />
|
||
<el-option label="耗材模式" :value="4" />
|
||
</el-select>
|
||
</el-form-item>
|
||
```
|
||
|
||
表单验证规则：
|
||
```typescript
|
||
const rules = {
|
||
mode: [{ required: true, message: "请选择运行模式", trigger: "change" }],
|
||
};
|
||
```
|
||
|
||
### 2. 智能柜体卡片显示
|
||
|
||
文件：`src/views/cabinet/smart-cabinet-card/index.vue`
|
||
|
||
在智能柜体卡片中显示柜体所属商店的运行模式：
|
||
|
||
```vue
|
||
<el-descriptions-item class="name">模式：{{ getModeText(item.mode) }}</el-descriptions-item>
|
||
```
|
||
|
||
### 3. 其他使用场景
|
||
|
||
- `src/views/cabinet/smart-cabinet-card/detail.vue`：柜体详情页显示模式
|
||
- `src/views/cabinet/shop/card.vue`：商店卡片显示模式
|
||
- `src/views/welcome/index.vue`：欢迎页面可能显示相关信息
|
||
|
||
## 模式与支付方式映射
|
||
|
||
### 映射定义
|
||
|
||
文件：`src/utils/maps/payment.ts`
|
||
|
||
```typescript
|
||
export const modeToPaymentMethodMap = {
|
||
0: [0, 3], // 支付模式：微信支付(0)、借呗支付(3)
|
||
1: [0, 1], // 审批模式：微信支付(0)、借呗支付(1)
|
||
2: [0, 1], // 借还模式：微信支付(0)、借呗支付(1)
|
||
3: [0, 3], // 会员模式：微信支付(0)、借呗支付(3)
|
||
4: [2], // 耗材模式：要呗支付(2)
|
||
5: [], // 暂存模式：无支付方式
|
||
};
|
||
```
|
||
|
||
### 支付方式选项
|
||
|
||
```typescript
|
||
export const paymentMethodOptions = [
|
||
{ label: '微信支付', value: 0, type: 'primary' },
|
||
{ label: '借呗支付', value: 1, type: 'success' },
|
||
{ label: '要呗支付', value: 2, type: 'info' },
|
||
{ label: '借呗支付', value: 3, type: 'warning' },
|
||
];
|
||
```
|
||
|
||
### 动态计算支付方式
|
||
|
||
在商店表单中，根据选择的运行模式动态显示可用的支付方式：
|
||
|
||
```typescript
|
||
const currentPaymentMethods = computed(() => {
|
||
if (typeof formData.value.mode !== 'number') return [];
|
||
const methodValues = modeToPaymentMethodMap[formData.value.mode] || [];
|
||
return methodValues.map(value => {
|
||
const option = paymentMethodOptions.find(item => item.value === value);
|
||
return option ? { label: option.label, type: option.type } : null;
|
||
}).filter(Boolean);
|
||
});
|
||
```
|
||
|
||
模板中使用：
|
||
```vue
|
||
<el-form-item label="支付方式">
|
||
<el-tag v-for="method in currentPaymentMethods" :key="method.label" :type="method.type">
|
||
{{ method.label }}
|
||
</el-tag>
|
||
</el-form-item>
|
||
```
|
||
|
||
## 业务逻辑影响
|
||
|
||
### 1. 订单流程
|
||
|
||
- **支付模式（0）**：用户可直接完成支付
|
||
- **审批模式（1）**：订单提交后需管理员审批，审批通过后方可支付
|
||
- **借还模式（2）**：适用于物品借用和归还，可能有额外的借用期限和归还确认流程
|
||
- **会员模式（3）**：仅限会员使用，可能涉及会员积分抵扣或余额支付
|
||
- **耗材模式（4）**：针对办公耗材等场景，支持特定的要呗支付方式
|
||
- **暂存模式（5）**：临时存储物品，使用密码打开，无支付环节
|
||
|
||
### 2. 支付方式限制
|
||
|
||
不同的运行模式限制了可用的支付方式组合，确保业务流程的一致性：
|
||
|
||
- 支付模式和会员模式支持微信支付和借呗支付（类型3）
|
||
- 审批模式和借还模式支持微信支付和借呗支付（类型1）
|
||
- 耗材模式仅支持要呗支付
|
||
- 暂存模式无支付方式
|
||
|
||
### 3. 权限控制
|
||
|
||
运行模式可能与用户权限相关联，例如：
|
||
- 审批模式需要管理员审批权限
|
||
- 会员模式需要会员身份验证
|
||
- 借还模式可能需要借用权限审核
|
||
|
||
## 使用示例
|
||
|
||
### 获取商店列表并显示模式
|
||
|
||
```typescript
|
||
import { getShopList, getModeText } from '@/api/shop/shop';
|
||
|
||
// 获取商店列表
|
||
const { data } = await getShopList({ mode: 0 }); // 查询支付模式的商店
|
||
const shops = data.rows;
|
||
|
||
// 显示模式文字
|
||
shops.forEach(shop => {
|
||
console.log(`${shop.shopName}: ${getModeText(shop.mode)}`);
|
||
});
|
||
```
|
||
|
||
### 新增商店时设置运行模式
|
||
|
||
```typescript
|
||
import { addShop } from '@/api/shop/shop';
|
||
|
||
await addShop({
|
||
shopName: '测试商店',
|
||
corpid: 'corp123',
|
||
mode: 0, // 设置为支付模式
|
||
balanceEnable: 1,
|
||
coverImg: 'https://example.com/image.jpg'
|
||
});
|
||
```
|
||
|
||
## 相关文件清单
|
||
|
||
1. `src/api/shop/shop.ts` - API 接口定义和工具函数
|
||
2. `src/views/cabinet/shop/shop-form-modal.vue` - 商店表单组件
|
||
3. `src/views/cabinet/shop/index.vue` - 商店管理页面
|
||
4. `src/views/cabinet/smart-cabinet-card/index.vue` - 智能柜体卡片页面
|
||
5. `src/views/cabinet/smart-cabinet-card/detail.vue` - 柜体详情页面
|
||
6. `src/utils/maps/payment.ts` - 支付方式映射配置
|
||
7. `src/views/cabinet/shop/card.vue` - 商店卡片组件
|
||
8. `src/views/welcome/index.vue` - 欢迎页面
|
||
|
||
## 注意事项
|
||
|
||
1. **模式变更影响**：更改商店的运行模式可能影响现有的订单流程和用户权限，需谨慎操作
|
||
2. **数据一致性**：模式与支付方式映射关系需要前后端保持一致
|
||
3. **默认值处理**：在新增商店时，建议明确设置 mode 值，避免使用 undefined
|
||
4. **国际化考虑**：如需支持多语言，modeTextMap 需要考虑国际化方案
|
||
|
||
## 未来扩展建议
|
||
|
||
1. **模式自定义**：支持管理员自定义运行模式的业务流程
|
||
2. **组合模式**：支持多种模式组合使用，满足复杂业务场景
|
||
3. **模式迁移工具**：提供商店模式变更的批量迁移和影响分析工具
|
||
4. **审计日志**：记录商店运行模式的变更历史，便于追踪和审计 |