wenzi/frontend/README.md

# 🦟 蚊子项目 - 增强版Vue 3组件库

这是蚊子项目的Vue 3增强版组件库，提供完整的错误处理、加载状态管理和更好的用户体验。

## ✨ 新增特性

- 🔒 **错误处理**: 全面的错误处理和用户友好的错误提示
- ⏳ **加载状态**: 自动加载状态管理和骨架屏
- 🔄 **重试机制**: 自动重试和手动重试功能
- 🎨 **主题系统**: 支持明暗主题切换
- 📱 **响应式设计**: 完全响应式布局
- ♿ **无障碍支持**: 支持键盘导航和屏幕阅读器
- 🔧 **TypeScript**: 完整的TypeScript类型定义

## 📦 安装

```bash
npm install @mosquito/vue-enhanced
# 或
yarn add @mosquito/vue-enhanced
# 或
pnpm add @mosquito/vue-enhanced
```

## 🚀 快速开始

### 1. 安装插件

```typescript
// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import MosquitoEnhancedPlugin from '@mosquito/vue-enhanced'
import '@mosquito/vue-enhanced/style.css'

const app = createApp(App)

// 安装插件并配置
app.use(MosquitoEnhancedPlugin, {
  baseUrl: 'https://api.your-domain.com',
  apiKey: 'your-api-key',
  timeout: 10000,
  retryCount: 3,
  enableLogging: true,
  defaultTheme: 'light',
  locale: 'zh-CN'
})

app.mount('#app')
```

### 2. 基础使用

```vue
<template>
  <div>
    <MosquitoShareButton
      :activity-id="activityId"
      :user-id="userId"
      :template="'default'"
      text="立即分享"
      variant="primary"
      size="lg"
      @copied="onCopied"
      @error="onError"
    />
    
    <MosquitoPosterCard
      :activity-id="activityId"
      :user-id="userId"
      :template="'premium'"
      width="350px"
      height="500px"
      @click="onPosterClick"
      @error="onPosterError"
      @loaded="onPosterLoaded"
    />
    
    <MosquitoLeaderboard
      :activity-id="activityId"
      :page="0"
      :size="20"
      :top-n="10"
      :current-user-id="currentUserId"
      @loaded="onLeaderboardLoaded"
      @error="onLeaderboardError"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { useMosquito, MosquitoError } from '@mosquito/vue-enhanced'

const activityId = ref(1)
const userId = ref(100)
const currentUserId = ref(100)

const { config, getShareUrl, getPosterImage, getLeaderboard } = useMosquito()

// 分享按钮事件
const onCopied = () => {
  showToast('分享链接已复制到剪贴板')
}

const onError = (error: MosquitoError) => {
  console.error('分享失败:', error)
  showError('分享失败，请稍后重试')
}

// 海报卡片事件
const onPosterClick = () => {
  console.log('海报被点击')
}

const onPosterError = (error: MosquitoError) => {
  console.error('海报加载失败:', error)
  showError('海报加载失败')
}

const onPosterLoaded = () => {
  console.log('海报加载成功')
}

// 排行榜事件
const onLeaderboardLoaded = (entries: any[]) => {
  console.log('排行榜数据:', entries)
}

const onLeaderboardError = (error: MosquitoError) => {
  console.error('排行榜加载失败:', error)
  showError('排行榜加载失败')
}

// 工具函数
const showToast = (message: string) => {
  // 实现Toast提示
}

const showError = (message: string) => {
  // 实现错误提示
}
</script>
```

## 📖 组件文档

### MosquitoShareButton

增强版的分享按钮组件，支持加载状态、错误处理和多种样式。

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| activityId | `number` | - | 活动ID（必需） |
| userId | `number` | - | 用户ID（必需） |
| template | `string` | 'default' | 分享模板 |
| text | `string` | '分享给好友' | 按钮文字 |
| disabled | `boolean` | false | 是否禁用 |
| variant | `'default'\|'primary'\|'secondary'\|'success'\|'danger' | 'primary' | 按钮样式 |
| size | `'sm'\|'md'\|'lg' | 'md' | 按钮大小 |

#### 事件

| 事件 | 参数 | 说明 |
|------|------|------|
| copied | - | 链接已复制到剪贴板 |
| error | `Error` | 获取分享链接失败 |

#### 示例

```vue
<MosquitoShareButton
  :activity-id="activityId"
  :user-id="userId"
  variant="success"
  size="lg"
  @copied="handleCopy"
  @error="handleError"
/>
```

### MosquitoPosterCard

增强版的海报展示组件，支持加载状态、错误处理和重试机制。

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| activityId | `number` | - | 活动ID（必需） |
| userId | `number` | - | 用户ID（必需） |
| template | `string` | 'default' | 海报模板 |
| width | `string` | '300px' | 宽度 |
| height | `string` | '400px' | 高度 |

#### 事件

| 事件 | 参数 | 说明 |
|------|------|------|
| click | - | 海报被点击 |
| error | `Error` | 海报加载失败 |
| loaded | - | 海报加载成功 |

#### 示例

```vue
<MosquitoPosterCard
  :activity-id="activityId"
  :user-id="userId"
  template="premium"
  width="350px"
  height="500px"
  @click="openPosterModal"
  @error="handlePosterError"
  @loaded="onPosterLoaded"
/>
```

### MosquitoLeaderboard

增强版的排行榜组件，支持分页、错误处理、高亮当前用户等功能。

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| activityId | `number` | - | 活动ID（必需） |
| page | `number` | 0 | 页码 |
| size | `number` | 20 | 每页大小 |
| topN | `number` | 10 | 显示前N名 |
| currentUserId | `number` | undefined | 当前用户ID |

#### 事件

| 事件 | 参数 | 说明 |
|------|------|------|
| loaded | `entries[]` | 排行榜数据加载完成 |
| error | `Error` | 排行榜加载失败 |

#### 示例

```vue
<MosquitoLeaderboard
  :activity-id="activityId"
  :page="currentPage"
  :size="20"
  :top-n="10"
  :current-user-id="currentUserId"
  @loaded="handleLeaderboardLoaded"
  @error="handleLeaderboardError"
/>
```

## 🔧 高级用法

### 错误处理

```vue
<template>
  <MosquitoShareButton
    :activity-id="activityId"
    :user-id="userId"
    @error="handleError"
  />
</template>

<script setup lang="ts">
import { MosquitoError } from '@mosquito/vue-enhanced'

const handleError = (error: MosquitoError) => {
  if (error.code === 'TIMEOUT') {
    showError('请求超时，请检查网络连接')
  } else if (error.code === 'RATE_LIMITED') {
    showError('请求过于频繁，请稍后再试')
  } else {
    showError('操作失败，请稍后重试')
  }
}
</script>
```

### 加载状态管理

```vue
<template>
  <div>
    <button 
      :disabled="loadingManager.isLoading('create-activity')"
      @click="createActivity"
    >
      创建活动
    </button>
    
    <MosquitoLeaderboard
      :activity-id="activityId"
      @loaded="onLoaded"
      @error="onError"
    />
  </div>
</template>

<script setup lang="ts">
import { useMosquito } from '@mosquito/vue-enhanced'

const { loadingManager } = useMosquito()

const createActivity = async () => {
  const unsubscribe = loadingManager.onLoadingChange('create-activity', (loading) => {
    console.log('创建活动状态:', loading)
  })
  
  try {
    // 创建活动逻辑
  } finally {
    unsubscribe()
  }
}
</script>
```

### 主题配置

```typescript
// main.ts
import MosquitoEnhancedPlugin from '@mosquito/vue-enhanced'

app.use(MosquitoEnhancedPlugin, {
  // ...其他配置
  defaultTheme: 'dark', // 或 'light'
  locale: 'en-US' // 或 'zh-CN'
})
```

## 🧪 测试

```bash
# 运行单元测试
npm run test

# 运行端到端测试
npm run test:e2e

# 运行类型检查
npm run type-check
```

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交Issue和Pull Request！

1. Fork本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

## 📞 支持

如果您在使用过程中遇到问题，请：

1. 查看文档和FAQ
2. 提交GitHub Issue
3. 联系我们的技术支持团队