645 lines
17 KiB
Markdown
645 lines
17 KiB
Markdown
# 门店管理新增字段 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-subagent-driven-development (recommended) or superpowers-executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 在 admin-ui 门店管理模块中适配后端新增的 9 个字段，修改表单弹窗和列表页，所有变更在现有 `useApiForm` + `ApiFormDialog` + `RuiTable` 框架内完成。
|
||
|
||
**Architecture:** 修改 2 个现有文件。`StoreFormDialog.vue` 新增 7 个可编辑字段（useApiForm fields 数组）、2 个只读字段（custom-fields 插槽）、数据双向转换逻辑（amenities JSON 序列化、serviceFeeRate 百分比转换）。`Index.vue` 新增 3 列（门店类型 Tag、包间信息、设施标签）、1 个筛选条件（门店类型下拉）、`parseAmenities` 工具函数。
|
||
|
||
**Tech Stack:** Vue 3 (Composition API / `<script setup>`) + TypeScript + Element Plus + Vite + pnpm
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
| # | 文件 | 操作 | 变更说明 |
|
||
|---|------|------|---------|
|
||
| 1 | `admin-ui/src/views/cashier/store/StoreFormDialog.vue` | 修改 | 扩展 `useApiForm` 的 `initial` 和 `fields`（+7 字段）；修改 `onSubmit` 添加 amenities/serviceFeeRate 数据转换；修改 `watch` 添加编辑回填数据转换；模板添加 `width="720px"` 和 `#custom-fields` 插槽 |
|
||
| 2 | `admin-ui/src/views/cashier/store/Index.vue` | 修改 | `queryParams` 增加 `storeType`；`handleReset` 补充 `storeType` 重置；新增 `parseAmenities` 工具函数；`columns` 增加 3 列；模板增加门店类型筛选和 3 个列 slot |
|
||
|
||
---
|
||
|
||
## Task 1: StoreFormDialog — 扩展 initial 默认值
|
||
|
||
**Files:**
|
||
- Modify: `admin-ui/src/views/cashier/store/StoreFormDialog.vue` (lines 32–40)
|
||
|
||
- [ ] **Step 1: 在 `useApiForm` 的 `initial` 对象中追加新字段默认值**
|
||
|
||
**Old string:**
|
||
```ts
|
||
initial: {
|
||
storeName: '',
|
||
storeCode: '',
|
||
address: '',
|
||
contactPhone: '',
|
||
contactName: '',
|
||
businessHours: '',
|
||
status: 1,
|
||
},
|
||
```
|
||
|
||
**New string:**
|
||
```ts
|
||
initial: {
|
||
storeName: '',
|
||
storeCode: '',
|
||
address: '',
|
||
contactPhone: '',
|
||
contactName: '',
|
||
businessHours: '',
|
||
status: 1,
|
||
storeType: 'STANDARD',
|
||
amenities: [],
|
||
longitude: undefined,
|
||
latitude: undefined,
|
||
serviceFeeRate: undefined,
|
||
openingDate: '',
|
||
legalPerson: '',
|
||
},
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add admin-ui/src/views/cashier/store/StoreFormDialog.vue
|
||
git commit -m "feat(store): 扩展 useApiForm initial 默认值，新增 7 个字段默认值"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 2: StoreFormDialog — 在 fields 数组中追加 7 个新字段
|
||
|
||
**Files:**
|
||
- Modify: `admin-ui/src/views/cashier/store/StoreFormDialog.vue` (lines 76–86, status 字段之后、fields 数组结束之前)
|
||
|
||
- [ ] **Step 1: 在 status 字段配置之后、`],` 之前，插入 7 个新字段配置**
|
||
|
||
**Old string:**
|
||
```ts
|
||
{
|
||
key: 'status',
|
||
label: '状态',
|
||
type: 'radio',
|
||
required: true,
|
||
options: [
|
||
{ label: '启用', value: 1 },
|
||
{ label: '禁用', value: 0 },
|
||
],
|
||
},
|
||
],
|
||
onSubmit: async (data) => {
|
||
```
|
||
|
||
**New string:**
|
||
```ts
|
||
{
|
||
key: 'status',
|
||
label: '状态',
|
||
type: 'radio',
|
||
required: true,
|
||
options: [
|
||
{ label: '启用', value: 1 },
|
||
{ label: '禁用', value: 0 },
|
||
],
|
||
},
|
||
{
|
||
key: 'storeType',
|
||
label: '门店类型',
|
||
type: 'select',
|
||
required: true,
|
||
options: [
|
||
{ label: '旗舰店', value: 'FLAGSHIP' },
|
||
{ label: '标准店', value: 'STANDARD' },
|
||
{ label: '社区店', value: 'COMMUNITY' },
|
||
],
|
||
},
|
||
{
|
||
key: 'amenities',
|
||
label: '设施标签',
|
||
type: 'checkbox',
|
||
options: [
|
||
{ label: '免费停车', value: '免费停车' },
|
||
{ label: '免费WiFi', value: '免费WiFi' },
|
||
{ label: '充电桩', value: '充电桩' },
|
||
{ label: '24小时营业', value: '24小时营业' },
|
||
{ label: '包厢', value: '包厢' },
|
||
{ label: '吸烟区', value: '吸烟区' },
|
||
],
|
||
},
|
||
{
|
||
key: 'longitude',
|
||
label: '经度',
|
||
type: 'number',
|
||
props: { min: -180, max: 180, precision: 6, step: 0.000001 },
|
||
},
|
||
{
|
||
key: 'latitude',
|
||
label: '纬度',
|
||
type: 'number',
|
||
props: { min: -90, max: 90, precision: 6, step: 0.000001 },
|
||
},
|
||
{
|
||
key: 'serviceFeeRate',
|
||
label: '平台服务费率(%)',
|
||
type: 'number',
|
||
props: { min: 0, max: 100, precision: 2, step: 0.01 },
|
||
},
|
||
{
|
||
key: 'openingDate',
|
||
label: '开业日期',
|
||
type: 'date',
|
||
props: { valueFormat: 'YYYY-MM-DD' },
|
||
},
|
||
{
|
||
key: 'legalPerson',
|
||
label: '法人姓名',
|
||
type: 'input',
|
||
},
|
||
],
|
||
onSubmit: async (data) => {
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add admin-ui/src/views/cashier/store/StoreFormDialog.vue
|
||
git commit -m "feat(store): 在 useApiForm fields 中新增 7 个可编辑字段配置"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: StoreFormDialog — 修改 onSubmit 添加数据转换
|
||
|
||
**Files:**
|
||
- Modify: `admin-ui/src/views/cashier/store/StoreFormDialog.vue` (lines 86–100, onSubmit 回调)
|
||
|
||
- [ ] **Step 1: 替换 onSubmit 回调，添加 amenities JSON 序列化和 serviceFeeRate 百分比转小数**
|
||
|
||
**Old string:**
|
||
```ts
|
||
onSubmit: async (data) => {
|
||
const isEdit = !!(data as any).id
|
||
|
||
if (isEdit) {
|
||
await storeService.update(data)
|
||
ElMessage.success('修改成功')
|
||
}
|
||
else {
|
||
await storeService.add(data)
|
||
ElMessage.success('新增成功')
|
||
}
|
||
|
||
emit('success')
|
||
emit('update:visible', false)
|
||
},
|
||
```
|
||
|
||
**New string:**
|
||
```ts
|
||
onSubmit: async (rawData) => {
|
||
const data = { ...rawData } as any
|
||
|
||
// amenities: string[] → JSON 字符串
|
||
if (Array.isArray(data.amenities)) {
|
||
data.amenities = JSON.stringify(data.amenities)
|
||
}
|
||
|
||
// serviceFeeRate: 百分比 → 小数
|
||
if (data.serviceFeeRate != null && data.serviceFeeRate !== '') {
|
||
data.serviceFeeRate = Number(data.serviceFeeRate) / 100
|
||
}
|
||
|
||
const isEdit = !!data.id
|
||
|
||
if (isEdit) {
|
||
await storeService.update(data)
|
||
ElMessage.success('修改成功')
|
||
}
|
||
else {
|
||
await storeService.add(data)
|
||
ElMessage.success('新增成功')
|
||
}
|
||
|
||
emit('success')
|
||
emit('update:visible', false)
|
||
},
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add admin-ui/src/views/cashier/store/StoreFormDialog.vue
|
||
git commit -m "feat(store): onSubmit 中添加 amenities JSON 序列化和 serviceFeeRate 百分比转小数"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: StoreFormDialog — 修改 watch 添加编辑回填数据转换
|
||
|
||
**Files:**
|
||
- Modify: `admin-ui/src/views/cashier/store/StoreFormDialog.vue` (lines 104–116, watch 回调)
|
||
|
||
- [ ] **Step 1: 替换 watch 回调，添加 amenities JSON 解析和 serviceFeeRate 小数转百分比**
|
||
|
||
**Old string:**
|
||
```ts
|
||
// 监听编辑数据
|
||
watch(() => props.visible, (val) => {
|
||
if (val) {
|
||
if (props.row) {
|
||
// 编辑时设置表单数据
|
||
form.value = {
|
||
...props.row,
|
||
}
|
||
}
|
||
else {
|
||
resetForm()
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
**New string:**
|
||
```ts
|
||
// 监听编辑数据
|
||
watch(() => props.visible, (val) => {
|
||
if (val) {
|
||
if (props.row) {
|
||
const rowData = { ...props.row }
|
||
|
||
// amenities: JSON 字符串 → string[]
|
||
if (typeof rowData.amenities === 'string' && rowData.amenities) {
|
||
try {
|
||
rowData.amenities = JSON.parse(rowData.amenities)
|
||
}
|
||
catch {
|
||
rowData.amenities = []
|
||
}
|
||
}
|
||
else if (!Array.isArray(rowData.amenities)) {
|
||
rowData.amenities = []
|
||
}
|
||
|
||
// serviceFeeRate: 小数 → 百分比
|
||
if (rowData.serviceFeeRate != null) {
|
||
rowData.serviceFeeRate = Number(rowData.serviceFeeRate) * 100
|
||
}
|
||
|
||
// 编辑时设置表单数据
|
||
form.value = rowData
|
||
}
|
||
else {
|
||
resetForm()
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add admin-ui/src/views/cashier/store/StoreFormDialog.vue
|
||
git commit -m "feat(store): watch 中添加 amenities JSON 解析和 serviceFeeRate 小数转百分比回填"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 5: StoreFormDialog — 模板添加 width 属性和 custom-fields 插槽
|
||
|
||
**Files:**
|
||
- Modify: `admin-ui/src/views/cashier/store/StoreFormDialog.vue` (lines 120–128, template 中的 ApiFormDialog 标签)
|
||
|
||
- [ ] **Step 1: 替换 ApiFormDialog 自闭合标签为开闭标签，添加 width 和 custom-fields 插槽**
|
||
|
||
**Old string:**
|
||
```vue
|
||
<ApiFormDialog
|
||
v-model:visible="localVisible"
|
||
v-model:form="form"
|
||
:title="(form as any).id ? '编辑门店' : '新增门店'"
|
||
:fields="fields"
|
||
:rules="rules"
|
||
:loading="loading"
|
||
@submit="handleSubmit"
|
||
/>
|
||
```
|
||
|
||
**New string:**
|
||
```vue
|
||
<ApiFormDialog
|
||
v-model:visible="localVisible"
|
||
v-model:form="form"
|
||
:title="(form as any).id ? '编辑门店' : '新增门店'"
|
||
:width="'720px'"
|
||
:fields="fields"
|
||
:rules="rules"
|
||
:loading="loading"
|
||
@submit="handleSubmit"
|
||
>
|
||
<template #custom-fields="{ form: formData }">
|
||
<template v-if="formData.id">
|
||
<el-form-item label="包间总数">
|
||
<span>{{ formData.roomCount ?? '-' }}</span>
|
||
</el-form-item>
|
||
<el-form-item label="空闲包间数">
|
||
<span>{{ formData.freeRoomCount ?? '-' }}</span>
|
||
</el-form-item>
|
||
</template>
|
||
</template>
|
||
</ApiFormDialog>
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add admin-ui/src/views/cashier/store/StoreFormDialog.vue
|
||
git commit -m "feat(store): ApiFormDialog 增加 width=720px 和 custom-fields 插槽展示只读包间字段"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 6: Index.vue — 扩展 queryParams、handleReset、新增 parseAmenities 工具函数
|
||
|
||
**Files:**
|
||
- Modify: `admin-ui/src/views/cashier/store/Index.vue`
|
||
|
||
- [ ] **Step 1: 在 queryParams 中增加 storeType 字段**
|
||
|
||
**Old string:**
|
||
```ts
|
||
const queryParams = ref({
|
||
storeName: '',
|
||
status: undefined as number | undefined,
|
||
})
|
||
```
|
||
|
||
**New string:**
|
||
```ts
|
||
const queryParams = ref({
|
||
storeName: '',
|
||
status: undefined as number | undefined,
|
||
storeType: undefined as string | undefined,
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: 在 handleReset 中补充 storeType 重置**
|
||
|
||
**Old string:**
|
||
```ts
|
||
function handleReset() {
|
||
queryParams.value = {
|
||
storeName: '',
|
||
status: undefined,
|
||
}
|
||
tableRef.value?.reset()
|
||
}
|
||
```
|
||
|
||
**New string:**
|
||
```ts
|
||
function handleReset() {
|
||
queryParams.value = {
|
||
storeName: '',
|
||
status: undefined,
|
||
storeType: undefined,
|
||
}
|
||
tableRef.value?.reset()
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 在 `handleStatusChange` 函数之后（`</script>` 标签之前），添加 `parseAmenities` 工具函数**
|
||
|
||
**Old string:**
|
||
```ts
|
||
async function handleStatusChange(row: any, status: number) {
|
||
if (!row?.id) return
|
||
try {
|
||
await storeService.changeStatus(row.id, status)
|
||
ElMessage.success(status === 1 ? '启用成功' : '禁用成功')
|
||
} catch {
|
||
row.status = status === 1 ? 0 : 1
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
**New string:**
|
||
```ts
|
||
async function handleStatusChange(row: any, status: number) {
|
||
if (!row?.id) return
|
||
try {
|
||
await storeService.changeStatus(row.id, status)
|
||
ElMessage.success(status === 1 ? '启用成功' : '禁用成功')
|
||
} catch {
|
||
row.status = status === 1 ? 0 : 1
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 解析设施标签（兼容 JSON 字符串和数组）
|
||
*/
|
||
function parseAmenities(val: any): string[] {
|
||
if (Array.isArray(val)) return val
|
||
if (typeof val === 'string' && val) {
|
||
try { return JSON.parse(val) } catch { return [] }
|
||
}
|
||
return []
|
||
}
|
||
</script>
|
||
```
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add admin-ui/src/views/cashier/store/Index.vue
|
||
git commit -m "feat(store): queryParams 增加 storeType 筛选、handleReset 补充重置、新增 parseAmenities 工具函数"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 7: Index.vue — 在 columns 数组中追加 3 列配置
|
||
|
||
**Files:**
|
||
- Modify: `admin-ui/src/views/cashier/store/Index.vue` (lines 12–28, columns 数组)
|
||
|
||
- [ ] **Step 1: 在 address 列之后追加 storeType、roomInfo、amenities 3 列**
|
||
|
||
**Old string:**
|
||
```ts
|
||
{ prop: 'address', label: '地址', minWidth: 200, tooltip: true },
|
||
{ prop: 'businessHours', label: '营业时间', width: 120 },
|
||
```
|
||
|
||
**New string:**
|
||
```ts
|
||
{ prop: 'address', label: '地址', minWidth: 200, tooltip: true },
|
||
{ prop: 'storeType', label: '门店类型', width: 100, align: 'center', slot: true },
|
||
{ prop: 'roomInfo', label: '包间', width: 120, align: 'center', slot: true },
|
||
{ prop: 'amenities', label: '设施标签', minWidth: 200, slot: true },
|
||
{ prop: 'businessHours', label: '营业时间', width: 120 },
|
||
```
|
||
|
||
- [ ] **Step 2: Commit**
|
||
|
||
```bash
|
||
git add admin-ui/src/views/cashier/store/Index.vue
|
||
git commit -m "feat(store): columns 增加 storeType/roomInfo/amenities 3 列配置"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 8: Index.vue — 模板添加门店类型筛选和 3 个列 slot
|
||
|
||
**Files:**
|
||
- Modify: `admin-ui/src/views/cashier/store/Index.vue` (template 部分)
|
||
|
||
- [ ] **Step 1: 在状态筛选的 `</el-form-item>` 之后、查询按钮的 `<el-form-item>` 之前，插入门店类型筛选**
|
||
|
||
**Old string:**
|
||
```vue
|
||
<el-form-item label="状态">
|
||
<el-select v-model="queryParams.status" placeholder="请选择状态" clearable>
|
||
<el-option label="启用" :value="1" />
|
||
<el-option label="禁用" :value="0" />
|
||
</el-select>
|
||
</el-form-item>
|
||
<el-form-item>
|
||
```
|
||
|
||
**New string:**
|
||
```vue
|
||
<el-form-item label="状态">
|
||
<el-select v-model="queryParams.status" placeholder="请选择状态" clearable>
|
||
<el-option label="启用" :value="1" />
|
||
<el-option label="禁用" :value="0" />
|
||
</el-select>
|
||
</el-form-item>
|
||
<el-form-item label="门店类型">
|
||
<el-select v-model="queryParams.storeType" placeholder="请选择门店类型" clearable>
|
||
<el-option label="旗舰店" value="FLAGSHIP" />
|
||
<el-option label="标准店" value="STANDARD" />
|
||
<el-option label="社区店" value="COMMUNITY" />
|
||
</el-select>
|
||
</el-form-item>
|
||
<el-form-item>
|
||
```
|
||
|
||
- [ ] **Step 2: 在状态列 slot（`#column-status`）的 `</template>` 之后、操作列 slot 之前，插入 3 个列 slot 模板**
|
||
|
||
**Old string:**
|
||
```vue
|
||
<!-- 状态列 -->
|
||
<template #column-status="{ row }">
|
||
<el-switch
|
||
v-model="row.status"
|
||
:active-value="1"
|
||
:inactive-value="0"
|
||
@change="(val: any) => handleStatusChange(row, val as number)"
|
||
/>
|
||
</template>
|
||
|
||
<!-- 操作列 -->
|
||
```
|
||
|
||
**New string:**
|
||
```vue
|
||
<!-- 状态列 -->
|
||
<template #column-status="{ row }">
|
||
<el-switch
|
||
v-model="row.status"
|
||
:active-value="1"
|
||
:inactive-value="0"
|
||
@change="(val: any) => handleStatusChange(row, val as number)"
|
||
/>
|
||
</template>
|
||
|
||
<!-- 门店类型列 -->
|
||
<template #column-storeType="{ row }">
|
||
<el-tag
|
||
:type="row.storeType === 'FLAGSHIP' ? 'danger' : row.storeType === 'STANDARD' ? '' : 'info'"
|
||
size="small"
|
||
>
|
||
{{ { FLAGSHIP: '旗舰店', STANDARD: '标准店', COMMUNITY: '社区店' }[row.storeType] || '-' }}
|
||
</el-tag>
|
||
</template>
|
||
|
||
<!-- 包间信息列 -->
|
||
<template #column-roomInfo="{ row }">
|
||
<span>{{ row.freeRoomCount ?? '-' }}/{{ row.roomCount ?? '-' }}</span>
|
||
</template>
|
||
|
||
<!-- 设施标签列 -->
|
||
<template #column-amenities="{ row }">
|
||
<template v-if="parseAmenities(row.amenities).length">
|
||
<el-tag
|
||
v-for="tag in parseAmenities(row.amenities)"
|
||
:key="tag"
|
||
size="small"
|
||
type="info"
|
||
class="mr-1 mb-1"
|
||
>
|
||
{{ tag }}
|
||
</el-tag>
|
||
</template>
|
||
<span v-else>-</span>
|
||
</template>
|
||
|
||
<!-- 操作列 -->
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add admin-ui/src/views/cashier/store/Index.vue
|
||
git commit -m "feat(store): 模板新增门店类型筛选条件和 storeType/roomInfo/amenities 列 slot"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 9: 构建验证 + 最终提交
|
||
|
||
- [ ] **Step 1: 运行 TypeScript 类型检查**
|
||
|
||
Run: `pnpm --filter admin-ui type-check`
|
||
Expected: 0 errors, 命令退出码 0
|
||
|
||
- [ ] **Step 2: 运行 ESLint 检查**
|
||
|
||
Run: `pnpm --filter admin-ui lint`
|
||
Expected: 0 errors, 0 warnings（或仅有与本次修改无关的已存在 warnings）
|
||
|
||
- [ ] **Step 3: 运行 Vite 构建**
|
||
|
||
Run: `pnpm --filter admin-ui build`
|
||
Expected: 构建成功，无编译错误，输出 dist 目录
|
||
|
||
- [ ] **Step 4: 启动开发服务器进行手动验证**
|
||
|
||
Run: `pnpm --filter admin-ui dev`
|
||
Expected: 开发服务器正常启动，浏览器打开后：
|
||
1. 门店管理列表页正确展示新增 3 列
|
||
2. 门店类型下拉筛选功能正常
|
||
3. 点击新增门店，弹窗宽度 720px，7 个新字段正确渲染
|
||
4. 新增模式下不显示包间总数/空闲包间数
|
||
5. 点击编辑门店，所有新字段正确回填，包间字段只读展示
|
||
6. 提交表单无报错
|
||
|
||
验证完毕后按 `Ctrl+C` 停止开发服务器。
|
||
|
||
---
|
||
|
||
## Verification Checklist
|
||
|
||
- [ ] `pnpm --filter admin-ui type-check` 通过
|
||
- [ ] `pnpm --filter admin-ui lint` 通过
|
||
- [ ] `pnpm --filter admin-ui build` 成功
|
||
- [ ] 列表新增 3 列正确展示（门店类型 Tag、包间 X/Y、设施多 Tag）
|
||
- [ ] 门店类型筛选功能正常（筛选 + 重置）
|
||
- [ ] 新增门店：7 个新字段可正常填写和提交
|
||
- [ ] 编辑门店：所有新字段正确回填，只读字段不可编辑
|
||
- [ ] amenities 数据双向转换正确（JSON 字符串 ↔ 数组）
|
||
- [ ] serviceFeeRate 数据双向转换正确（小数 ↔ 百分比）
|
||
- [ ] 新增模式下 roomCount/freeRoomCount 区域不显示
|
||
- [ ] 无数据时各列正确降级显示 `-`
|