# 小程序架构文档

## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| 1.0 | 2024-01-20 | 前端团队 | 初始版本 |

## 1. 小程序架构概述

### 1.1 项目背景
本小程序是养殖管理平台的移动端应用，主要面向养殖户和经销商，提供养殖管理、交易管理、数据查看等核心功能。

### 1.2 架构目标
- **用户体验**：流畅的交互体验和快速的页面响应
- **性能优化**：小程序包体积控制和运行性能优化
- **可维护性**：清晰的代码结构和组件化开发
- **扩展性**：支持功能模块的快速扩展
- **稳定性**：异常处理和容错机制完善

### 1.3 技术栈
- **开发框架**：微信小程序原生开发
- **开发语言**：TypeScript + JavaScript
- **UI框架**：WeUI + 自定义组件
- **状态管理**：MobX + 本地存储
- **网络请求**：wx.request + 请求封装
- **图表组件**：ECharts for 微信小程序
- **地图服务**：腾讯地图 + 微信地图

## 2. 系统架构设计

### 2.1 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│                      视图层 (View)                          │
│                   Pages + Components                        │
├─────────────────────────────────────────────────────────────┤
│                    逻辑层 (Logic)                           │
│                 Service + Store + Utils                     │
├─────────────────────────────────────────────────────────────┤
│                    数据层 (Data)                            │
│              API + Storage + Cache                          │
├─────────────────────────────────────────────────────────────┤
│                   微信小程序框架                             │
│                 WeChat Mini Program                         │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 目录结构
```
mini-program/
├── pages/                    # 页面目录
│   ├── index/               # 首页
│   ├── farm/                # 养殖管理
│   ├── trade/               # 交易管理
│   ├── profile/             # 个人中心
│   └── ...
├── components/              # 组件目录
│   ├── common/              # 通用组件
│   ├── business/            # 业务组件
│   └── charts/              # 图表组件
├── services/                # 服务层
│   ├── api/                 # API接口
│   ├── auth/                # 认证服务
│   └── storage/             # 存储服务
├── stores/                  # 状态管理
│   ├── user.ts              # 用户状态
│   ├── farm.ts              # 养殖状态
│   └── trade.ts             # 交易状态
├── utils/                   # 工具函数
│   ├── request.ts           # 网络请求
│   ├── validator.ts         # 数据验证
│   └── formatter.ts         # 数据格式化
├── styles/                  # 样式文件
│   ├── common.wxss          # 通用样式
│   └── variables.wxss       # 样式变量
├── static/                  # 静态资源
│   ├── images/              # 图片资源
│   └── icons/               # 图标资源
├── app.ts                   # 应用入口
├── app.json                 # 应用配置
├── app.wxss                 # 全局样式
└── project.config.json      # 项目配置
```

## 3. 核心模块设计

### 3.1 用户认证模块
**功能**: 微信授权登录、用户信息管理、权限控制

**核心组件**:
- **登录页面**: 微信授权登录界面
- **用户信息**: 用户资料展示和编辑
- **权限管理**: 基于角色的功能权限控制

**实现方案**:
```typescript
// 用户认证服务
class AuthService {
  // 微信登录
  async wxLogin(): Promise<LoginResult> {
    const { code } = await wx.login();
    const { userInfo } = await wx.getUserProfile({
      desc: '用于完善用户资料'
    });
    
    return this.apiLogin(code, userInfo);
  }
  
  // API登录
  async apiLogin(code: string, userInfo: any): Promise<LoginResult> {
    const response = await request.post('/auth/wx-login', {
      code,
      userInfo
    });
    
    if (response.success) {
      await this.setToken(response.data.token);
      await this.setUserInfo(response.data.user);
    }
    
    return response;
  }
}
```

### 3.2 养殖管理模块
**功能**: 养殖场管理、动物管理、数据统计

**核心页面**:
- **养殖场列表**: 展示用户的养殖场信息
- **养殖场详情**: 养殖场详细信息和管理功能
- **动物管理**: 动物档案、健康记录、生长数据
- **数据统计**: 养殖数据图表和分析报告

**状态管理**:
```typescript
// 养殖状态管理
class FarmStore {
  @observable farms: Farm[] = [];
  @observable currentFarm: Farm | null = null;
  @observable animals: Animal[] = [];
  
  @action
  async loadFarms() {
    const response = await farmService.getFarms();
    if (response.success) {
      this.farms = response.data;
    }
  }
  
  @action
  async selectFarm(farmId: string) {
    const farm = this.farms.find(f => f.id === farmId);
    this.currentFarm = farm || null;
    
    if (farm) {
      await this.loadAnimals(farmId);
    }
  }
}
```

### 3.3 交易管理模块
**功能**: 订单管理、支付管理、物流跟踪

**核心页面**:
- **商品列表**: 展示可交易的商品信息
- **订单管理**: 订单创建、查看、状态跟踪
- **支付页面**: 微信支付集成
- **物流跟踪**: 订单物流信息查看

**支付集成**:
```typescript
// 支付服务
class PaymentService {
  async wxPay(orderId: string): Promise<PaymentResult> {
    // 1. 获取支付参数
    const payParams = await this.getPayParams(orderId);
    
    // 2. 调起微信支付
    return new Promise((resolve, reject) => {
      wx.requestPayment({
        ...payParams,
        success: (res) => {
          resolve({ success: true, data: res });
        },
        fail: (err) => {
          reject({ success: false, error: err });
        }
      });
    });
  }
}
```

### 3.4 数据可视化模块
**功能**: 图表展示、数据分析、报表生成

**图表组件**:
- **折线图**: 展示趋势数据
- **柱状图**: 展示对比数据
- **饼图**: 展示占比数据
- **仪表盘**: 展示关键指标

**ECharts集成**:
```typescript
// 图表组件
Component({
  properties: {
    chartData: Object,
    chartType: String
  },
  
  data: {
    ec: null
  },
  
  ready() {
    this.initChart();
  },
  
  methods: {
    initChart() {
      this.createSelectorQuery()
        .select('#chart')
        .fields({ node: true, size: true })
        .exec((res) => {
          const canvas = res[0].node;
          const ctx = canvas.getContext('2d');
          
          canvas.width = res[0].width * dpr;
          canvas.height = res[0].height * dpr;
          ctx.scale(dpr, dpr);
          
          echarts.setCanvasCreator(() => canvas);
          
          const chart = echarts.init(canvas, null, {
            width: res[0].width,
            height: res[0].height,
            devicePixelRatio: dpr
          });
          
          chart.setOption(this.getChartOption());
          this.setData({ ec: { chart } });
        });
    }
  }
});
```

## 4. 网络层设计

### 4.1 请求封装
```typescript
// 网络请求封装
class RequestService {
  private baseURL = 'https://api.example.com';
  private timeout = 10000;
  
  async request(options: RequestOptions): Promise<ApiResponse> {
    const token = await storage.getToken();
    
    return new Promise((resolve, reject) => {
      wx.request({
        url: `${this.baseURL}${options.url}`,
        method: options.method || 'GET',
        data: options.data,
        header: {
          'Content-Type': 'application/json',
          'Authorization': token ? `Bearer ${token}` : '',
          ...options.header
        },
        timeout: this.timeout,
        success: (res) => {
          if (res.statusCode === 200) {
            resolve(res.data);
          } else {
            this.handleError(res);
            reject(res);
          }
        },
        fail: (err) => {
          this.handleError(err);
          reject(err);
        }
      });
    });
  }
  
  private handleError(error: any) {
    console.error('Request error:', error);
    
    // 统一错误处理
    if (error.statusCode === 401) {
      // Token过期，跳转登录
      this.redirectToLogin();
    } else if (error.statusCode >= 500) {
      // 服务器错误
      wx.showToast({
        title: '服务器错误，请稍后重试',
        icon: 'none'
      });
    }
  }
}
```

### 4.2 API接口管理
```typescript
// API接口定义
class ApiService {
  // 用户相关接口
  user = {
    login: (data: LoginData) => request.post('/auth/login', data),
    profile: () => request.get('/user/profile'),
    updateProfile: (data: UserProfile) => request.put('/user/profile', data)
  };
  
  // 养殖相关接口
  farm = {
    list: (params: FarmListParams) => request.get('/farms', params),
    detail: (id: string) => request.get(`/farms/${id}`),
    create: (data: FarmData) => request.post('/farms', data),
    update: (id: string, data: FarmData) => request.put(`/farms/${id}`, data)
  };
  
  // 交易相关接口
  trade = {
    orders: (params: OrderListParams) => request.get('/orders', params),
    createOrder: (data: OrderData) => request.post('/orders', data),
    payOrder: (orderId: string) => request.post(`/orders/${orderId}/pay`)
  };
}
```

## 5. 数据存储设计

### 5.1 本地存储策略
```typescript
// 存储服务
class StorageService {
  // 同步存储
  setSync(key: string, value: any): void {
    try {
      wx.setStorageSync(key, JSON.stringify(value));
    } catch (error) {
      console.error('Storage set error:', error);
    }
  }
  
  getSync(key: string): any {
    try {
      const value = wx.getStorageSync(key);
      return value ? JSON.parse(value) : null;
    } catch (error) {
      console.error('Storage get error:', error);
      return null;
    }
  }
  
  // 异步存储
  async set(key: string, value: any): Promise<void> {
    return new Promise((resolve, reject) => {
      wx.setStorage({
        key,
        data: JSON.stringify(value),
        success: resolve,
        fail: reject
      });
    });
  }
  
  async get(key: string): Promise<any> {
    return new Promise((resolve, reject) => {
      wx.getStorage({
        key,
        success: (res) => {
          try {
            resolve(JSON.parse(res.data));
          } catch (error) {
            resolve(res.data);
          }
        },
        fail: () => resolve(null)
      });
    });
  }
}
```

### 5.2 缓存管理
```typescript
// 缓存管理
class CacheService {
  private cache = new Map<string, CacheItem>();
  private defaultTTL = 5 * 60 * 1000; // 5分钟
  
  set(key: string, value: any, ttl?: number): void {
    const expireTime = Date.now() + (ttl || this.defaultTTL);
    this.cache.set(key, {
      value,
      expireTime
    });
  }
  
  get(key: string): any {
    const item = this.cache.get(key);
    if (!item) return null;
    
    if (Date.now() > item.expireTime) {
      this.cache.delete(key);
      return null;
    }
    
    return item.value;
  }
  
  clear(): void {
    this.cache.clear();
  }
}
```

## 6. 组件化设计

### 6.1 通用组件
```typescript
// 列表组件
Component({
  properties: {
    items: Array,
    loading: Boolean,
    hasMore: Boolean
  },
  
  data: {
    refreshing: false
  },
  
  methods: {
    onRefresh() {
      this.setData({ refreshing: true });
      this.triggerEvent('refresh');
    },
    
    onLoadMore() {
      if (!this.data.loading && this.data.hasMore) {
        this.triggerEvent('loadmore');
      }
    },
    
    onItemTap(e: any) {
      const { item, index } = e.currentTarget.dataset;
      this.triggerEvent('itemtap', { item, index });
    }
  }
});
```

### 6.2 业务组件
```typescript
// 养殖场卡片组件
Component({
  properties: {
    farm: Object
  },
  
  methods: {
    onTap() {
      const { farm } = this.properties;
      wx.navigateTo({
        url: `/pages/farm/detail?id=${farm.id}`
      });
    },
    
    onEdit() {
      const { farm } = this.properties;
      this.triggerEvent('edit', { farm });
    }
  }
});
```

## 7. 性能优化

### 7.1 包体积优化
- **代码分包**: 使用小程序分包加载
- **图片优化**: 使用WebP格式，压缩图片大小
- **代码压缩**: 启用代码压缩和混淆
- **按需加载**: 组件和页面按需加载

### 7.2 运行时优化
- **数据预加载**: 关键数据提前加载
- **图片懒加载**: 长列表图片懒加载
- **防抖节流**: 频繁操作防抖节流处理
- **内存管理**: 及时清理不用的数据和监听器

### 7.3 渲染优化
```typescript
// 长列表优化
Component({
  data: {
    visibleItems: [],
    scrollTop: 0
  },
  
  methods: {
    onScroll(e: any) {
      const { scrollTop } = e.detail;
      this.updateVisibleItems(scrollTop);
    },
    
    updateVisibleItems(scrollTop: number) {
      const itemHeight = 100;
      const containerHeight = 600;
      const startIndex = Math.floor(scrollTop / itemHeight);
      const endIndex = startIndex + Math.ceil(containerHeight / itemHeight) + 1;
      
      const visibleItems = this.data.allItems.slice(startIndex, endIndex);
      this.setData({ visibleItems });
    }
  }
});
```

## 8. 错误处理

### 8.1 全局错误处理
```typescript
// 应用级错误处理
App({
  onError(error: string) {
    console.error('App Error:', error);
    
    // 错误上报
    this.reportError(error);
    
    // 用户提示
    wx.showToast({
      title: '程序出现异常',
      icon: 'none'
    });
  },
  
  onUnhandledRejection(res: any) {
    console.error('Unhandled Promise Rejection:', res);
    this.reportError(res.reason);
  },
  
  reportError(error: any) {
    // 上报错误到服务器
    wx.request({
      url: 'https://api.example.com/errors',
      method: 'POST',
      data: {
        error: error.toString(),
        stack: error.stack,
        timestamp: Date.now(),
        userAgent: wx.getSystemInfoSync()
      }
    });
  }
});
```

### 8.2 页面级错误处理
```typescript
// 页面错误处理
Page({
  data: {
    error: null,
    loading: false
  },
  
  async onLoad() {
    try {
      this.setData({ loading: true });
      await this.loadData();
    } catch (error) {
      this.handleError(error);
    } finally {
      this.setData({ loading: false });
    }
  },
  
  handleError(error: any) {
    console.error('Page Error:', error);
    
    this.setData({
      error: {
        message: error.message || '加载失败',
        code: error.code
      }
    });
  },
  
  onRetry() {
    this.setData({ error: null });
    this.onLoad();
  }
});
```

## 9. 安全设计

### 9.1 数据安全
- **敏感数据加密**: 本地存储敏感数据加密
- **传输安全**: HTTPS传输，防止中间人攻击
- **输入验证**: 严格验证用户输入数据

### 9.2 权限控制
```typescript
// 权限检查
class PermissionService {
  async checkPermission(permission: string): Promise<boolean> {
    const userInfo = await storage.get('userInfo');
    if (!userInfo || !userInfo.permissions) {
      return false;
    }
    
    return userInfo.permissions.includes(permission);
  }
  
  async requirePermission(permission: string): Promise<void> {
    const hasPermission = await this.checkPermission(permission);
    if (!hasPermission) {
      throw new Error('权限不足');
    }
  }
}
```

## 10. 测试策略

### 10.1 单元测试
```typescript
// 工具函数测试
describe('Validator', () => {
  test('should validate phone number', () => {
    expect(validator.isPhone('13800138000')).toBe(true);
    expect(validator.isPhone('1380013800')).toBe(false);
  });
  
  test('should validate email', () => {
    expect(validator.isEmail('test@example.com')).toBe(true);
    expect(validator.isEmail('invalid-email')).toBe(false);
  });
});
```

### 10.2 集成测试
- **API测试**: 测试与后端API的集成
- **支付测试**: 测试微信支付流程
- **授权测试**: 测试微信授权登录

### 10.3 用户体验测试
- **真机测试**: 在不同设备上测试
- **网络测试**: 测试不同网络环境下的表现
- **性能测试**: 测试页面加载和响应性能

## 11. 发布与运维

### 11.1 版本管理
- **版本号规范**: 遵循语义化版本号
- **发布流程**: 开发 → 测试 → 预发布 → 正式发布
- **回滚机制**: 支持快速回滚到上一版本

### 11.2 监控告警
- **性能监控**: 监控页面加载时间和API响应时间
- **错误监控**: 监控JavaScript错误和API错误
- **用户行为**: 统计用户使用行为和路径

### 11.3 数据统计
```typescript
// 埋点统计
class AnalyticsService {
  track(event: string, properties?: any) {
    const data = {
      event,
      properties: {
        ...properties,
        timestamp: Date.now(),
        page: getCurrentPages().pop()?.route
      }
    };
    
    // 发送统计数据
    wx.request({
      url: 'https://analytics.example.com/track',
      method: 'POST',
      data
    });
  }
  
  trackPageView(page: string) {
    this.track('page_view', { page });
  }
  
  trackUserAction(action: string, target?: string) {
    this.track('user_action', { action, target });
  }
}
```

## 12. 扩展性设计

### 12.1 插件化架构
- **功能模块**: 支持功能模块的插拔
- **主题系统**: 支持多主题切换
- **配置化**: 支持功能开关配置

### 12.2 多端适配
- **响应式设计**: 适配不同屏幕尺寸
- **平台兼容**: 兼容不同版本的微信客户端
- **设备适配**: 适配不同性能的设备

## 13. 未来规划

### 13.1 技术升级
- **框架升级**: 考虑使用Taro等跨端框架
- **TypeScript**: 全面使用TypeScript开发
- **组件库**: 构建统一的组件库

### 13.2 功能扩展
- **离线功能**: 支持离线数据查看
- **实时通信**: 集成WebSocket实时通信
- **AI功能**: 集成AI智能分析功能