# 代理/企业管理系统 - 快速启动指南

## ✨ 项目概述

一个基于**小米米家APP风格**的代理/企业管理系统单页面应用(SPA),支持:

- ✅ **代理端**: 资产管理、套餐管理、佣金钱包、余额钱包、提现管理
- ✅ **企业端**: 资产管理、套餐管理、标签管理(分配标签给资产)
- ✅ **亮色风格**: 白色/浅灰背景 + 小米橙点缀
- ✅ **简约大气**: 大量留白、卡片化布局、扁平图标

---

## 🚀 快速启动

### 1. 访问页面

```bash
# 开发环境
pnpm dev:h5

# 访问地址
http://localhost:5173/#/pages/agent-system/index
```

### 2. 切换角色

页面顶部有角色切换按钮:
- **代理端** - 显示佣金、余额、提现功能
- **企业端** - 显示标签管理功能(无佣金和钱包)

---

## 📁 文件结构

```
src/pages/agent-system/
└── index.vue                    # 主页面 (单页面SPA)

.claude/
├── AGENT-SYSTEM-DESIGN.md       # 完整设计规范文档
├── AGENT-SYSTEM-QUICKSTART.md   # 本文件 - 快速启动
└── COMPONENT-PATTERNS.md        # 可复用组件模式
```

---

## 🎨 设计风格特点

### 小米米家风格关键要素

| 特征 | 实现 | 代码示例 |
|------|------|---------|
| **柔和阴影** | 浅色阴影避免过重 | `shadow-[0_2px_8px_rgba(0,0,0,0.04)]` |
| **圆角统一** | 卡片12px,按钮8px | `rounded-12px` / `rounded-8px` |
| **中性灰色** | 使用gray-50~900 | `bg-[#fafafa]` / `text-[#212121]` |
| **橙色点缀** | 仅用于CTA和强调 | `bg-[#ff6700]` |
| **扁平图标** | MDI线性图标 | `i-mdi-*` |
| **卡片布局** | 网格排列,整齐有序 | `grid grid-cols-4 gap-6` |

### 配色方案

```scss
// 主色
#ff6700  // 小米橙 (主CTA)
#ff8533  // 浅橙 (hover)
#fff7f0  // 橙色背景

// 中性灰 (米家风格)
#fafafa  // 页面背景
#f5f5f5  // 卡片背景
#eeeeee  // 分割线
#e0e0e0  // 边框
#bdbdbd  // 禁用文字
#9e9e9e  // 次要文字
#757575  // 常规文字
#212121  // 标题文字

// 功能色
#4caf50  // 成功绿
#ff9800  // 警告橙
#f44336  // 错误红
#2196f3  // 信息蓝
```

---

## 🧩 页面功能清单

### 代理端页面

| 路由 | 功能 | 状态 |
|------|------|------|
| `/dashboard` | 数据概览 | ✅ 已实现 |
| `/commission` | 佣金钱包详情 | ✅ 已实现 |
| `/balance` | 余额钱包详情 | ⏳ 待实现 |
| `/withdraw` | 提现申请&记录 | ⏳ 待实现 |
| `/assets` | 资产列表 | ✅ 已实现 |
| `/assets/:id` | 资产详情 | ⏳ 待实现 |
| `/packages` | 套餐列表 | ⏳ 待实现 |
| `/packages/:id` | 套餐详情 | ⏳ 待实现 |

### 企业端页面

| 路由 | 功能 | 状态 |
|------|------|------|
| `/dashboard` | 数据概览 | ✅ 已实现 |
| `/assets` | 资产列表 | ✅ 已实现 |
| `/assets/:id` | 资产详情 | ⏳ 待实现 |
| `/packages` | 套餐列表 | ⏳ 待实现 |
| `/packages/:id` | 套餐详情 | ⏳ 待实现 |
| `/tags` | 标签管理 | ✅ 已实现 |

---

## 🔧 组件使用示例

### 1. 统计卡片

```vue
<view class="
  bg-white
  rounded-12px
  p-6
  shadow-[0_2px_8px_rgba(0,0,0,0.04)]
  border border-[#eeeeee]
  hover:shadow-[0_4px_16px_rgba(0,0,0,0.08)]
  transition-all duration-300
">
  <view class="flex items-center justify-between mb-4">
    <text class="text-14px text-[#9e9e9e]">今日收益</text>
    <i class="i-mdi-cash w-20px h-20px text-[#4caf50]" />
  </view>

  <text class="text-32px font-700 text-[#212121] block mb-1">
    ¥ 1,280.00
  </text>

  <text class="text-12px text-[#bdbdbd]">
    较上期 <text class="text-[#4caf50]">+8.2%</text>
  </text>
</view>
```

### 2. 主要按钮 (小米橙)

```vue
<button class="
  bg-[#ff6700] text-white
  px-6 py-3 rounded-8px
  text-14px font-500
  min-h-44px
  shadow-[0_2px_4px_rgba(255,103,0,0.2)]
  hover:bg-[#ff8533]
  active:scale-98
  transition-all duration-200
  cursor-pointer
">
  确认提交
</button>
```

### 3. 列表项 (资产/套餐)

```vue
<view class="
  bg-white
  rounded-12px
  p-4
  shadow-[0_2px_8px_rgba(0,0,0,0.04)]
  border border-[#eeeeee]
  hover:shadow-[0_4px_12px_rgba(0,0,0,0.08)]
  hover:border-[#ff6700]/30
  transition-all duration-200
  cursor-pointer
">
  <view class="flex items-center gap-4">
    <!-- 缩略图 -->
    <view class="w-64px h-64px bg-[#f5f5f5] rounded-8px center">
      <i class="i-mdi-package-variant w-32px h-32px text-[#bdbdbd]" />
    </view>

    <!-- 信息 -->
    <view class="flex-1">
      <text class="text-16px font-600 text-[#212121] block mb-1">
        资产名称 A1
      </text>
      <text class="text-13px text-[#9e9e9e]">
        编号: AST-2024-001
      </text>
    </view>

    <!-- 标签 -->
    <span class="
      px-3 py-1
      bg-[#fff7f0] text-[#ff6700]
      text-12px font-500
      rounded-full
    ">
      热门
    </span>

    <!-- 箭头 -->
    <i class="i-mdi-chevron-right w-20px h-20px text-[#bdbdbd]" />
  </view>
</view>
```

### 4. 侧边导航项

```vue
<view
  :class="{
    'bg-[#fff7f0] text-[#ff6700]': isActive,
    'text-[#757575]': !isActive
  }"
  class="
    flex items-center gap-3
    px-4 py-3
    rounded-12px
    mb-2
    cursor-pointer
    transition-all duration-200
    hover:bg-[#f5f5f5]
  "
  @click="navigateTo('/dashboard')"
>
  <i class="i-mdi-view-dashboard w-20px h-20px" />
  <text class="text-14px font-500">数据概览</text>

  <!-- 徽章 (可选) -->
  <view class="
    ml-auto
    w-20px h-20px
    bg-[#f44336]
    text-white
    text-11px
    rounded-full
    center
  ">
    3
  </view>
</view>
```

---

## 🎯 待完成功能清单

### 高优先级

- [ ] **余额钱包详情页** (复制佣金钱包逻辑)
- [ ] **佣金提现申请表单**
  - 输入金额
  - 选择提现方式 (银行卡/支付宝/微信)
  - 实名验证
  - 提交按钮
- [ ] **提现记录列表**
  - 状态筛选 (全部/审核中/已通过/已拒绝)
  - 时间排序
  - 详情查看

### 中优先级

- [ ] **资产详情页**
  - 资产信息展示
  - 关联套餐列表
  - 收益统计图表
  - 操作按钮 (编辑/删除)
- [ ] **套餐列表页**
  - 网格布局
  - 筛选功能
  - 搜索功能
- [ ] **套餐详情页**
  - 套餐信息
  - 价格配置
  - 关联资产

### 低优先级

- [ ] **标签拖拽分配功能** (企业端)
  - 使用 SortableJS 实现拖拽
  - 实时保存分配状态
- [ ] **图表集成** (ECharts)
  - 收益趋势图
  - 资产分布图
  - 佣金统计图
- [ ] **数据导出功能**
  - 导出佣金记录 (Excel)
  - 导出资产列表 (CSV)

---

## 📝 开发规范

### 颜色使用

```vue
<!-- ✅ GOOD: 使用十六进制色值 (小米风格) -->
<view class="bg-[#fafafa] text-[#212121]">

<!-- ❌ BAD: 使用CSS变量 (不符合小米简约风格) -->
<view class="bg-primary text-main">
```

### 圆角规范

```vue
<!-- 卡片: 12px -->
<view class="rounded-12px">

<!-- 按钮: 8px -->
<button class="rounded-8px">

<!-- 徽章/标签: 全圆角 -->
<span class="rounded-full">
```

### 阴影规范

```vue
<!-- 小卡片/列表项: 2px偏移 4% 透明度 -->
<view class="shadow-[0_2px_8px_rgba(0,0,0,0.04)]">

<!-- Hover状态: 4px偏移 8% 透明度 -->
<view class="hover:shadow-[0_4px_12px_rgba(0,0,0,0.08)]">

<!-- 大卡片/模态框: 8px偏移 橙色阴影 -->
<view class="shadow-[0_8px_24px_rgba(255,103,0,0.2)]">
```

### 间距规范

```vue
<!-- 卡片间距: 24px (gap-6) -->
<view class="grid gap-6">

<!-- 卡片内边距: 24px (p-6) -->
<view class="p-6">

<!-- 小元素间距: 12px (gap-3) -->
<view class="flex gap-3">
```

---

## 🎨 图标使用

### 推荐图标集 (MDI - Material Design Icons)

```vue
<!-- 数据相关 -->
<i class="i-mdi-view-dashboard" />      <!-- 仪表盘 -->
<i class="i-mdi-chart-line" />          <!-- 趋势图 -->
<i class="i-mdi-chart-bar" />           <!-- 柱状图 -->

<!-- 资产相关 -->
<i class="i-mdi-package-variant" />     <!-- 资产/包裹 -->
<i class="i-mdi-package-variant-plus" /> <!-- 添加资产 -->
<i class="i-mdi-gift" />                <!-- 套餐/礼物 -->

<!-- 财务相关 -->
<i class="i-mdi-wallet" />              <!-- 钱包 -->
<i class="i-mdi-cash" />                <!-- 现金 -->
<i class="i-mdi-currency-cny" />        <!-- 人民币 -->
<i class="i-mdi-bank-transfer" />       <!-- 转账/提现 -->

<!-- 标签相关 -->
<i class="i-mdi-tag" />                 <!-- 单个标签 -->
<i class="i-mdi-tag-multiple" />        <!-- 多个标签 -->
<i class="i-mdi-tag-plus" />            <!-- 添加标签 -->

<!-- 操作相关 -->
<i class="i-mdi-plus" />                <!-- 添加 -->
<i class="i-mdi-pencil" />              <!-- 编辑 -->
<i class="i-mdi-delete" />              <!-- 删除 -->
<i class="i-mdi-dots-vertical" />       <!-- 更多操作 -->
<i class="i-mdi-chevron-right" />       <!-- 右箭头 -->

<!-- 状态相关 -->
<i class="i-mdi-check-circle" />        <!-- 成功 -->
<i class="i-mdi-alert-circle" />        <!-- 警告 -->
<i class="i-mdi-information" />         <!-- 信息 -->
<i class="i-mdi-loading" />             <!-- 加载 -->
```

### 图标颜色搭配

```vue
<!-- 成功 - 绿色 -->
<i class="i-mdi-check-circle text-[#4caf50]" />

<!-- 警告 - 橙色 -->
<i class="i-mdi-alert text-[#ff9800]" />

<!-- 错误 - 红色 -->
<i class="i-mdi-alert-circle text-[#f44336]" />

<!-- 信息 - 蓝色 -->
<i class="i-mdi-information text-[#2196f3]" />

<!-- 主色 - 小米橙 -->
<i class="i-mdi-wallet text-[#ff6700]" />

<!-- 中性 - 灰色 -->
<i class="i-mdi-package-variant text-[#bdbdbd]" />
```

---

## 🔍 调试技巧

### 1. 查看当前路由

```vue
<script setup>
import { ref } from 'vue'
const currentRoute = ref('/dashboard')

// 在控制台打印
console.log('当前路由:', currentRoute.value)
</script>
```

### 2. 切换角色测试

```javascript
// 在浏览器控制台执行
// 切换到企业端
currentRole.value = 'enterprise'

// 切换到代理端
currentRole.value = 'agent'
```

### 3. 快速跳转路由

```javascript
// 在浏览器控制台执行
currentRoute.value = '/commission'  // 佣金钱包
currentRoute.value = '/assets'      // 资产列表
currentRoute.value = '/tags'        // 标签管理
```

---

## 📱 响应式测试

### 测试断点

```bash
# 移动端
375px  - iPhone SE
414px  - iPhone Pro Max

# 平板
768px  - iPad
1024px - iPad Pro

# 桌面
1280px - 小屏笔记本
1440px - 标准桌面
1920px - 大屏显示器
```

### 当前响应式支持

- ✅ **桌面端 (> 1024px)**: 完整布局,侧边栏固定
- ⚠️ **平板端 (768px - 1024px)**: 需要调整网格列数
- ❌ **移动端 (< 768px)**: 需要隐藏侧边栏,使用底部Tab

### 待实现: 移动端适配

```vue
<!-- 移动端底部导航 (待实现) -->
<view class="
  fixed bottom-0 left-0 right-0
  bg-white
  border-t border-[#eeeeee]
  pb-safe
  z-100
  lg:hidden
">
  <view class="flex justify-around py-2">
    <button class="flex flex-col items-center gap-1">
      <i class="i-mdi-view-dashboard w-24px h-24px" />
      <text class="text-11px">首页</text>
    </button>
    <!-- 其他Tab项 -->
  </view>
</view>
```

---

## 🚀 性能优化建议

### 1. 图片懒加载

```vue
<image
  :src="thumbnailUrl"
  mode="aspectFill"
  lazy-load
  class="w-64px h-64px rounded-8px"
/>
```

### 2. 列表虚拟滚动

```vue
<!-- 对于长列表使用 z-paging -->
<z-paging
  ref="pagingRef"
  v-model="dataList"
  @query="queryList"
>
  <view v-for="item in dataList" :key="item.id">
    <!-- 列表项 -->
  </view>
</z-paging>
```

### 3. 数据分页加载

```typescript
const currentPage = ref(1)
const pageSize = ref(20)
const hasMore = ref(true)

async function loadMore() {
  if (!hasMore.value)
    return

  const data = await fetchData({
    page: currentPage.value,
    size: pageSize.value,
  })

  // 追加数据
  assets.value.push(...data.list)

  // 更新状态
  currentPage.value++
  hasMore.value = data.hasMore
}
```

---

## 📚 相关文档

- **完整设计规范**: `.claude/AGENT-SYSTEM-DESIGN.md`
- **组件模式库**: `.claude/COMPONENT-PATTERNS.md`
- **全局设计系统**: `.claude/DESIGN-SYSTEM.md`
- **图标库**: [MDI Icons](https://icon-sets.iconify.design/mdi/)

---

## ✅ 检查清单

提交代码前检查:

- [ ] 颜色使用十六进制 (不使用CSS变量)
- [ ] 圆角统一 (卡片12px, 按钮8px)
- [ ] 阴影柔和 (0.04 ~ 0.08 透明度)
- [ ] 图标使用MDI (不使用emoji)
- [ ] 按钮hover有反馈
- [ ] 卡片hover有边框变化
- [ ] 所有交互元素有cursor-pointer
- [ ] 间距符合6px倍数规范
- [ ] 测试角色切换功能
- [ ] 测试路由跳转功能

---

**小米米家风格精髓**: 简约、留白、柔和、整齐、大气 🎨