one-pipe-system/docs/页面创建模板.md

页面创建模板

本文档提供快速创建页面的模板，所有页面遵循统一的风格和结构。

📋 已完成的页面

✅ 账号管理模块

• 客户角色管理 (account-management/customer-role)
• 代理商管理 (account-management/agent)
• 客户账号管理 (account-management/customer-account)
• 客户账号佣金 (account-management/customer-commission) - 待创建

✅ 商品管理模块

• 号卡管理 (product/sim-card)
• 号卡分配 (product/sim-card-assign) - 待创建

🔨 待创建的页面

财务管理模块 (finance/)

1. 佣金提现管理 (withdrawal/index.vue)
2. 佣金提现设置 (withdrawal-settings/index.vue)
3. 我的账户 (my-account/index.vue)

设置管理模块 (settings/)

1. 收款商户设置 (payment-merchant/index.vue)
2. 开发能力管理 (developer-api/index.vue)
3. 分佣模板 (commission-template/index.vue)

批量操作模块 (batch/)

1. 网卡批量导入 (sim-import/index.vue)
2. 设备批量导入 (device-import/index.vue)
3. 换卡通知 (card-change-notice/index.vue)

---

📝 标准页面模板

基础列表页面模板

<template>
  <div class="page-content">
    <!-- 搜索栏 -->
    <ElRow>
      <ElCol :xs="24" :sm="12" :lg="6">
        <ElInput v-model="searchQuery" placeholder="搜索关键词" clearable></ElInput>
      </ElCol>
      <div style="width: 12px"></div>
      <ElCol :xs="24" :sm="12" :lg="6" class="el-col2">
        <ElButton v-ripple @click="handleSearch">搜索</ElButton>
        <ElButton v-ripple @click="showDialog('add')">新增</ElButton>
      </ElCol>
    </ElRow>

    <!-- 表格 -->
    <ArtTable :data="filteredData" index>
      <template #default>
        <ElTableColumn label="名称" prop="name" />
        <ElTableColumn label="编码" prop="code" />
        <ElTableColumn label="状态" prop="status">
          <template #default="scope">
            <ElTag :type="scope.row.status === 'active' ? 'success' : 'info'">
              {{ scope.row.status === 'active' ? '启用' : '禁用' }}
            </ElTag>
          </template>
        </ElTableColumn>
        <ElTableColumn label="创建时间" prop="createTime" width="180" />
        <ElTableColumn fixed="right" label="操作" width="180">
          <template #default="scope">
            <el-button link @click="showDialog('edit', scope.row)">编辑</el-button>
            <el-button link @click="handleDelete(scope.row)">删除</el-button>
          </template>
        </ElTableColumn>
      </template>
    </ArtTable>

    <!-- 新增/编辑对话框 -->
    <ElDialog
      v-model="dialogVisible"
      :title="dialogType === 'add' ? '新增' : '编辑'"
      width="600px"
      align-center
    >
      <ElForm ref="formRef" :model="form" :rules="rules" label-width="120px">
        <ElFormItem label="名称" prop="name">
          <ElInput v-model="form.name" placeholder="请输入名称" />
        </ElFormItem>
        <ElFormItem label="编码" prop="code">
          <ElInput v-model="form.code" placeholder="请输入编码" />
        </ElFormItem>
        <ElFormItem label="状态">
          <ElSwitch v-model="form.status" active-value="active" inactive-value="inactive" />
        </ElFormItem>
      </ElForm>
      <template #footer>
        <div class="dialog-footer">
          <ElButton @click="dialogVisible = false">取消</ElButton>
          <ElButton type="primary" @click="handleSubmit(formRef)">提交</ElButton>
        </div>
      </template>
    </ElDialog>
  </div>
</template>

<script setup lang="ts">
  import { ElMessage, ElMessageBox } from 'element-plus'
  import type { FormInstance, FormRules } from 'element-plus'

  defineOptions({ name: 'YourPageName' })

  interface DataItem {
    id?: string
    name: string
    code: string
    status: 'active' | 'inactive'
    createTime?: string
  }

  // Mock 数据
  const mockData = ref<DataItem[]>([
    {
      id: '1',
      name: '示例数据1',
      code: 'CODE001',
      status: 'active',
      createTime: '2026-01-01 10:00:00'
    }
  ])

  const searchQuery = ref('')
  const dialogVisible = ref(false)
  const dialogType = ref<'add' | 'edit'>('add')
  const formRef = ref<FormInstance>()

  const form = reactive<DataItem>({
    name: '',
    code: '',
    status: 'active'
  })

  const rules = reactive<FormRules>({
    name: [{ required: true, message: '请输入名称', trigger: 'blur' }],
    code: [{ required: true, message: '请输入编码', trigger: 'blur' }]
  })

  const filteredData = computed(() => {
    if (!searchQuery.value) return mockData.value
    return mockData.value.filter((item) =>
      item.name.toLowerCase().includes(searchQuery.value.toLowerCase())
    )
  })

  const handleSearch = () => {}

  const showDialog = (type: 'add' | 'edit', row?: DataItem) => {
    dialogType.value = type
    dialogVisible.value = true
    if (type === 'edit' && row) {
      Object.assign(form, row)
    } else {
      Object.assign(form, { name: '', code: '', status: 'active' })
    }
  }

  const handleSubmit = async (formEl: FormInstance | undefined) => {
    if (!formEl) return
    await formEl.validate((valid) => {
      if (valid) {
        if (dialogType.value === 'add') {
          mockData.value.push({
            ...form,
            id: Date.now().toString(),
            createTime: new Date().toLocaleString('zh-CN')
          })
          ElMessage.success('新增成功')
        } else {
          const index = mockData.value.findIndex((item) => item.id === form.id)
          if (index !== -1) mockData.value[index] = { ...form }
          ElMessage.success('修改成功')
        }
        dialogVisible.value = false
        formEl.resetFields()
      }
    })
  }

  const handleDelete = (row: DataItem) => {
    ElMessageBox.confirm('确定删除吗？', '删除确认', {
      confirmButtonText: '确定',
      cancelButtonText: '取消',
      type: 'error'
    }).then(() => {
      const index = mockData.value.findIndex((item) => item.id === row.id)
      if (index !== -1) mockData.value.splice(index, 1)
      ElMessage.success('删除成功')
    })
  }
</script>

<style lang="scss" scoped>
  .page-content {
    // 自定义样式
  }
</style>

---

🎯 快速创建步骤

1. 复制模板：复制上面的标准模板
2. 修改组件名：修改 defineOptions({ name: 'YourPageName' })
3. 调整接口：根据业务需求修改 DataItem 接口
4. 修改 Mock 数据：替换 mockData 中的示例数据
5. 调整表单字段：根据需求增删表单项
6. 调整表格列：修改 ElTableColumn 配置

---

📚 常用组件

1. ArtTable - 表格组件

<ArtTable :data="tableData" index>
  <template #default>
    <ElTableColumn label="列名" prop="propName" />
  </template>
</ArtTable>

2. 搜索栏布局

<ElRow>
  <ElCol :xs="24" :sm="12" :lg="6">
    <ElInput v-model="search" placeholder="搜索" clearable />
  </ElCol>
  <div style="width: 12px"></div>
  <ElCol :xs="24" :sm="12" :lg="6">
    <ElSelect v-model="filter" placeholder="筛选" clearable style="width: 100%">
      <ElOption label="选项1" value="1" />
    </ElSelect>
  </ElCol>
  <div style="width: 12px"></div>
  <ElCol :xs="24" :sm="12" :lg="6" class="el-col2">
    <ElButton v-ripple>搜索</ElButton>
  </ElCol>
</ElRow>

3. 状态标签

<ElTag :type="getStatusType(status)">
  {{ getStatusText(status) }}
</ElTag>

4. 操作按钮

<el-button link @click="handleEdit(row)">编辑</el-button>
<el-button link type="danger" @click="handleDelete(row)">删除</el-button>

---

💡 开发规范

1. 命名规范

   • 组件名：大驼峰 YourComponent
   • 变量名：小驼峰 yourVariable
   • 文件名：小写+连字符 your-file.vue

2. Mock 数据格式

   • 统一使用 ref<Type[]>([]) 定义
   • 包含 id, createTime 等公共字段
   • 数据应具有代表性，便于测试

3. 表单验证

   • 必填字段添加 required 规则
   • 手机号/邮箱使用正则验证
   • 提供友好的错误提示

4. 用户体验

   • 操作前使用 ElMessageBox.confirm 确认
   • 操作后使用 ElMessage 提示结果
   • 表单提交后关闭对话框并重置

---

🔄 下一步

1. 根据模板快速创建剩余页面
2. 完善 Mock 数据使其更真实
3. 添加路由配置
4. 测试页面功能
5. 优化用户体验

祝开发顺利！🚀