medical-mall/docs/admin/ADMIN_MANAGEMENT_GUIDE.md

# CRMEB管理端uvue实现操作指南

## 项目概述

本文档详细介绍基于CRMEB商城系统管理端功能，使用uvue + Supabase技术栈重新实现的完整管理后台操作指南。

## 技术架构

### 前端技术栈
- **框架**: uvue (uni-app x)
- **状态管理**: Vue 3 Composition API
- **UI组件**: 自定义组件 + uni-app内置组件
- **样式**: CSS + Flex布局 + 响应式设计
- **设计风格**: 参考CRMEB开源商城系统，采用统一的卡片布局和配色方案
- **图标库**: iconfont字体图标库

### 后端技术栈
- **数据库**: Supabase (PostgreSQL)
- **API**: @components/supadb 组件库
- **认证**: Supabase Auth
- **存储**: Supabase Storage
- **实时功能**: Supabase Realtime

## 功能模块

### 1. 管理端首页 (`index.uvue`)

#### 功能特性
- **基础信息统计卡片**: 显示销售额、订单数、用户数等核心指标
- **功能导航网格**: 快速访问各个管理模块
- **数据可视化**: 实时统计数据展示

#### 页面结构
参考CRMEB设计风格，采用统一的卡片布局和Flex布局：

```vue
<template>
  <view class="admin-dashboard">
    <!-- 顶部统计卡片 -->
    <view class="header acea-row">
      <navigator class="item" url="/pages/mall/admin/order-management" hover-class="none">
        <view class="num">{{ pendingCounts.order_pending }}</view>
        <view>待处理订单</view>
      </navigator>
      <!-- 其他统计项 -->
    </view>

    <!-- 数据统计 -->
    <view class="wrapper">
      <view class="title">
        <span class="iconfont icon-shujutongji"></span>数据统计
      </view>
      <view class="list acea-row">
        <navigator class="item" url="/pages/mall/admin/statistics/sales" hover-class="none">
          <view class="num">{{ todayStats.sales }}</view>
          <view>今日销售额</view>
        </navigator>
        <!-- 其他统计项 -->
      </view>
    </view>

    <!-- 功能导航 -->
    <view class="public-wrapper">
      <view class="title">
        <span class="iconfont icon-gongnengdaohang"></span>功能导航
      </view>
      <view class="menu-grid acea-row">
        <view class="menu-item" @click="go('/pages/mall/admin/user-management')">
          <view class="menu-icon">
            <text class="iconfont icon-yonghuguanli"></text>
          </view>
          <text class="menu-text">用户管理</text>
        </view>
        <!-- 其他功能项 -->
      </view>
    </view>
  </view>
</template>
```

#### 数据加载
```typescript
// 获取基础统计数据
const loadBaseStats = async () => {
  const salesStats = await supa.rpc('get_sales_stats', {
    start_date: yesterday,
    end_date: today
  })
  // 更新统计数据
}
```

### 2. 用户管理 (`user-management.uvue`)

#### 核心功能
- **用户搜索筛选**: 支持多条件组合查询
- **用户列表展示**: 分页显示用户信息
- **批量操作**: 导出用户、群发消息、调整余额
- **用户状态管理**: 启用/禁用用户账户
- **用户详情**: 查看和编辑用户信息

#### 搜索功能
```typescript
const searchTypes = ref([
  { value: 'all', label: '全部' },
  { value: 'uid', label: 'UID' },
  { value: 'phone', label: '手机号' },
  { value: 'nickname', label: '用户昵称' }
])

const userLevels = ref([]) // 用户等级选项
const userGroups = ref([]) // 用户分组选项
const agentLevels = ref([]) // 分销等级选项
```

#### 用户操作
```typescript
// 切换用户状态
const toggleUserStatus = async (userId: number, currentStatus: number) => {
  const newStatus = currentStatus === 1 ? 0 : 1
  await supa.from('users').update({ status: newStatus }).eq('id', userId)
}

// 批量导出用户
const exportUsers = () => {
  // 导出逻辑
}
```

### 3. 商品管理 (`product-management.uvue`)

#### 功能特性
- **商品列表**: 分页展示商品信息
- **高级筛选**: 商品类型、分类、价格、库存等条件
- **批量操作**: 批量上架/下架/删除
- **商品状态管理**: 上架、下架、编辑
- **商品规格**: 支持多规格商品管理

#### 商品筛选
```typescript
const productTypes = ref([
  { value: '0', label: '普通商品' },
  { value: '1', label: '卡密商品' },
  { value: '2', label: '优惠券商品' },
  { value: '3', label: '虚拟商品' }
])

const deliveryTypes = ref([
  { value: '1', label: '快递配送' },
  { value: '2', label: '到店自提' }
])
```

#### 商品操作
```typescript
// 批量上架
const batchOnShelf = async () => {
  await supa.from('products')
    .update({ is_show: true })
    .in('id', selectedProducts.value)
}

// 删除商品
const deleteProduct = async (productId: number) => {
  await supa.from('products')
    .update({ is_del: true })
    .eq('id', productId)
}
```

### 4. 订单管理 (`order-management.uvue`)

#### 核心功能
- **订单类型标签页**: 全部订单、普通订单、待支付、待发货等
- **订单搜索**: 订单号、用户名、收货人等条件
- **订单状态管理**: 确认订单、发货、查看物流
- **订单详情**: 完整的订单信息展示
- **批量操作**: 批量发货、导出订单

#### 订单状态
```typescript
const orderStatuses = ref([
  { value: '0', label: '待确认' },
  { value: '1', label: '待支付' },
  { value: '2', label: '待发货' },
  { value: '3', label: '已发货' },
  { value: '4', label: '已完成' },
  { value: '5', label: '已取消' },
  { value: '6', label: '退款中' }
])
```

#### 订单操作
```typescript
// 确认订单
const confirmOrder = async (orderId: number) => {
  await supa.from('orders').update({ status: 1 }).eq('id', orderId)
}

// 订单发货
const confirmShip = async () => {
  await supa.from('orders').update({
    status: 3,
    ship_info: {
      express_company: shipForm.express_company,
      express_number: shipForm.express_number,
      ship_time: new Date().toISOString()
    }
  }).eq('id', shipForm.order_id)
}
```

### 5. 财务管理 (`finance-management.uvue`)

#### 功能模块
- **财务概览**: 收入统计、账户余额、待结算金额
- **财务明细**: 交易记录查询和筛选
- **交易类型**: 订单收入、退款支出、提现支出等
- **数据导出**: 支持导出财务报表

#### 财务统计
```typescript
const overview = ref({
  today_income: '0.00',
  month_income: '0.00',
  account_balance: '0.00',
  pending_settlement: '0.00'
})
```

#### 交易记录查询
```typescript
const loadRecords = async () => {
  let query = supa.from('finance_records')
    .select('*')
    .order('created_at', { ascending: false })

  // 筛选条件
  if (selectedType.value) {
    query = query.eq('type', selectedType.value)
  }

  // 分页
  const { data, count } = await query.range(from, to)
}
```

### 6. 系统设置 (`system-settings.uvue`)

#### 设置分类
- **基础设置**: 网站名称、域名、Logo、客服电话等
- **支付设置**: 微信支付、支付宝、余额支付配置
- **物流设置**: 默认物流公司、运费计算方式
- **消息设置**: 短信、邮件通知配置

#### 设置保存
```typescript
const saveSettings = async () => {
  await supa.from('system_settings').upsert(settings.value)
}
```

## 组件架构

### 公共组件
- **搜索表单**: 统一的搜索和筛选组件
- **数据表格**: 列表展示和操作组件
- **分页组件**: 统一的翻页功能
- **弹窗组件**: 确认对话框和表单弹窗

### 样式规范
参考CRMEB设计风格，采用统一的布局和配色：

```css
/* 布局类 */
.acea-row {
  display: flex;
  flex-direction: row;
}

.row-between-wrapper {
  justify-content: space-between;
  align-items: center;
}

/* 颜色规范 */
.primary-theme: #fba02a;    /* 橙色主题色 */
.secondary-theme: #2291f8;  /* 蓝色辅助色 */
.success-color: #1abb1d;    /* 成功色 */
.danger-color: #ff6969;     /* 危险色 */

/* 卡片样式 */
.public-wrapper {
  width: 690rpx;
  background-color: #fff;
  border-radius: 10rpx;
  margin: 20rpx auto 0 auto;
  padding: 30rpx;
  box-shadow: 0 2rpx 8rpx rgba(0, 0, 0, 0.1);
}

/* 字体图标 */
.iconfont {
  font-family: 'iconfont';
  color: #2291f8;
  font-size: 36rpx;
  margin-right: 13rpx;
  vertical-align: middle;
}
```

## 数据交互

### Supabase集成
```typescript
import supa from '@/components/supadb/aksupainstance.uts'

// 查询数据
const { data, error } = await supa
  .from('table_name')
  .select('*')
  .eq('field', value)

// 插入数据
const { data, error } = await supa
  .from('table_name')
  .insert(newData)

// 更新数据
const { data, error } = await supa
  .from('table_name')
  .update(updateData)
  .eq('id', id)

// 删除数据
const { data, error } = await supa
  .from('table_name')
  .delete()
  .eq('id', id)
```

### RPC调用
```typescript
// 调用存储过程
const { data, error } = await supa.rpc('function_name', {
  param1: value1,
  param2: value2
})
```

## 权限管理

### 基于角色的访问控制
```typescript
// 权限检查
const hasPermission = (permission: string) => {
  // 检查用户权限逻辑
  return userPermissions.includes(permission)
}

// 页面级权限控制
onMounted(() => {
  if (!hasPermission('admin.user.view')) {
    uni.showToast({
      title: '无权限访问',
      icon: 'error'
    })
    uni.navigateBack()
  }
})
```

## 性能优化

### 1. 数据分页
```typescript
const loadData = async (page: number = 1) => {
  const pageSize = 20
  const from = (page - 1) * pageSize
  const to = from + pageSize - 1

  const { data } = await supa
    .from('table')
    .select('*')
    .range(from, to)
}
```

### 2. 条件查询优化
```typescript
// 使用索引字段进行查询
const { data } = await supa
  .from('orders')
  .select('*')
  .eq('status', 1) // 状态字段通常有索引
  .gte('created_at', startDate)
  .order('created_at', { ascending: false })
```

### 3. 实时数据订阅
```typescript
// 监听数据变化
const subscription = supa
  .channel('table-changes')
  .on('postgres_changes', {
    event: '*',
    schema: 'public',
    table: 'orders'
  }, (payload) => {
    // 处理数据变化
    updateLocalData(payload)
  })
  .subscribe()
```

## 错误处理

### 统一错误处理
```typescript
const handleError = (error: any) => {
  console.error('操作失败:', error)

  let message = '操作失败，请重试'
  if (error.message) {
    message = error.message
  }

  uni.showToast({
    title: message,
    icon: 'error'
  })
}
```

### 网络请求错误
```typescript
try {
  const { data, error } = await supa.from('table').select('*')
  if (error) throw error
  // 处理成功的数据
} catch (error) {
  handleError(error)
}
```

## 响应式设计

### 移动端适配
```scss
// 响应式断点
@media (max-width: 750rpx) {
  .container {
    padding: 20rpx;
  }

  .grid {
    grid-template-columns: 1fr;
    gap: 15rpx;
  }

  .table-row {
    flex-wrap: wrap;

    .table-cell {
      min-width: 200rpx;
      margin-bottom: 10rpx;
    }
  }
}
```

## 部署和维护

### 环境配置
```javascript
// config/admin.js
export default {
  supabase: {
    url: process.env.SUPABASE_URL,
    anonKey: process.env.SUPABASE_ANON_KEY,
    serviceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY
  },
  pagination: {
    defaultPageSize: 20,
    maxPageSize: 100
  },
  upload: {
    maxFileSize: 10 * 1024 * 1024, // 10MB
    allowedTypes: ['image/jpeg', 'image/png', 'image/webp']
  }
}
```

### 日志记录
```typescript
// 操作日志记录
const logOperation = async (action: string, details: any) => {
  await supa.from('admin_logs').insert({
    admin_id: currentAdmin.id,
    action,
    details,
    ip: getClientIP(),
    user_agent: navigator.userAgent,
    created_at: new Date().toISOString()
  })
}
```

## 开发规范

### 代码组织
```
pages/mall/admin/
├── index.uvue                 # 管理首页
├── user-management.uvue       # 用户管理
├── product-management.uvue    # 商品管理
├── order-management.uvue      # 订单管理
├── finance-management.uvue    # 财务管理
├── system-settings.uvue       # 系统设置
└── components/                # 公共组件
    ├── SearchForm.uvue
    ├── DataTable.uvue
    ├── Pagination.uvue
    └── Modal.uvue
```

### 命名规范
- **文件命名**: 使用 kebab-case (user-management.uvue)
- **变量命名**: 使用 camelCase (userList, isLoading)
- **组件命名**: 使用 PascalCase (UserManagement)
- **函数命名**: 使用 camelCase (loadUserList, handleSubmit)

### 注释规范
```typescript
/**
 * 用户管理页面
 * 功能：用户列表展示、搜索筛选、状态管理等
 */

// 函数注释
/**
 * 加载用户列表
 * @param page 页码
 * @param filters 筛选条件
 */
const loadUserList = async (page: number = 1, filters: any = {}) => {
  // 具体实现
}
```

## 常见问题

### 1. 数据加载慢
**问题**: 列表数据加载缓慢
**解决方案**:
- 添加合适的数据库索引
- 实现数据分页
- 使用缓存机制
- 优化查询条件

### 2. 权限控制
**问题**: 用户权限判断不准确
**解决方案**:
- 在路由层面进行权限检查
- 实现基于角色的访问控制
- 前端页面级权限验证

### 3. 实时数据同步
**问题**: 多用户同时操作数据冲突
**解决方案**:
- 使用 Supabase 实时订阅
- 实现乐观更新
- 添加数据版本控制

## 更新日志

### v1.0.0 (2024-01-22)
- ✅ 完成基础管理功能实现
- ✅ 用户管理模块
- ✅ 商品管理模块
- ✅ 订单管理模块
- ✅ 财务管理模块
- ✅ 系统设置模块

### 计划功能
- 🔄 营销管理模块
- 🔄 数据统计图表
- 🔄 批量操作优化
- 🔄 移动端适配完善
- 🔄 性能优化

---

本文档持续更新中，如有问题请及时反馈。