# 智慧畜牧业小程序矩阵 - 技术文档
## 📋 项目概述
智慧畜牧业小程序矩阵是基于 uni-app 框架开发的跨平台移动应用系统，包含5个专业化小程序应用，覆盖畜牧业全产业链的数字化管理需求。
### 🎯 项目目标
- 提供完整的畜牧业数字化解决方案
- 实现跨平台一体化开发和部署
- 建立标准化的开发规范和流程
- 构建可扩展的技术架构体系
## 🏗️ 技术架构
### 核心技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| uni-app | 3.x | 跨平台开发框架 |
| Vue.js | 3.x | 前端框架 |
| Pinia | 2.x | 状态管理 |
| TypeScript | 4.x | 类型系统 |
| SCSS | - | 样式预处理器 |
| ESLint | 8.x | 代码检查 |
| Prettier | 2.x | 代码格式化 |
### 架构设计
```
智慧畜牧业小程序矩阵
├── 表现层 (Presentation Layer)
│ ├── 养殖管理小程序
│ ├── 牛只交易小程序
│ ├── 牛肉商城小程序
│ ├── 银行监管小程序
│ └── 保险监管小程序
├── 业务层 (Business Layer)
│ ├── 用户管理
│ ├── 养殖管理
│ ├── 交易管理
│ ├── 商城管理
│ ├── 金融管理
│ └── 保险管理
├── 服务层 (Service Layer)
│ ├── API服务
│ ├── 认证服务
│ ├── 支付服务
│ ├── 消息服务
│ └── 文件服务
└── 数据层 (Data Layer)
├── 用户数据
├── 业务数据
├── 交易数据
└── 系统数据
```
## 📁 项目结构
```
mini_program/
├── common/ # 公共资源
│ ├── components/ # 通用组件
│ │ ├── loading/ # 加载组件
│ │ ├── empty/ # 空状态组件
│ │ └── modal/ # 模态框组件
│ ├── utils/ # 工具函数
│ │ ├── request.js # 请求封装
│ │ ├── storage.js # 存储工具
│ │ ├── auth.js # 认证工具
│ │ ├── validation.js # 验证工具
│ │ ├── format.js # 格式化工具
│ │ ├── permission.js # 权限管理
│ │ └── uni-helper.js # uni-app工具
│ ├── styles/ # 公共样式
│ │ ├── variables.scss # 变量定义
│ │ ├── mixins.scss # 混入函数
│ │ └── base.scss # 基础样式
│ ├── mixins/ # Vue混入
│ │ └── page.js # 页面混入
│ └── config/ # 配置文件
│ └── index.js # 全局配置
├── farming-manager/ # 养殖管理小程序
│ ├── manifest.json # 应用配置
│ ├── pages.json # 页面配置
│ ├── App.vue # 应用入口
│ └── pages/ # 页面文件
├── cattle-trading/ # 牛只交易小程序
├── beef-mall/ # 牛肉商城小程序
├── bank-supervision/ # 银行监管小程序
├── insurance-supervision/ # 保险监管小程序
├── package.json # 项目配置
├── vue.config.js # Vue配置
├── .eslintrc.js # ESLint配置
├── .prettierrc.js # Prettier配置
├── .env.development # 开发环境配置
├── .env.production # 生产环境配置
└── README.md # 项目说明
```
## 🔧 开发规范
### 代码规范
#### 1. 命名规范
- **文件命名**: 使用 kebab-case (短横线分隔)
- **组件命名**: 使用 PascalCase (大驼峰)
- **变量命名**: 使用 camelCase (小驼峰)
- **常量命名**: 使用 UPPER_SNAKE_CASE (大写下划线)
```javascript
// 文件命名
user-profile.vue
api-service.js
// 组件命名
// 变量命名
const userName = 'admin'
const userProfile = {}
// 常量命名
const API_BASE_URL = 'https://api.example.com'
const MAX_RETRY_COUNT = 3
```
#### 2. Vue组件规范
```vue
```
#### 3. API调用规范
```javascript
// api/user.js
import request from '@/common/utils/request'
export const userApi = {
// 获取用户信息
getUserInfo: (id) => {
return request.get(`/user/${id}`)
},
// 更新用户信息
updateUserInfo: (data) => {
return request.put('/user/profile', data)
},
// 删除用户
deleteUser: (id) => {
return request.delete(`/user/${id}`)
}
}
```
### 样式规范
#### 1. SCSS变量使用
```scss
// 使用全局变量
.page-container {
background-color: $background-color;
padding: $spacing-medium;
}
// 使用混入
.card {
@include card-style;
@include flex-center;
}
```
#### 2. 响应式设计
```scss
.responsive-container {
width: 100%;
// 小屏幕
@media (max-width: 768px) {
padding: $spacing-small;
}
// 大屏幕
@media (min-width: 769px) {
padding: $spacing-large;
}
}
```
### 状态管理规范
#### 1. Pinia Store结构
```javascript
// stores/user.js
import { defineStore } from 'pinia'
export const useUserStore = defineStore('user', {
state: () => ({
userInfo: null,
isLoggedIn: false,
permissions: []
}),
getters: {
hasPermission: (state) => (permission) => {
return state.permissions.includes(permission)
}
},
actions: {
async login(credentials) {
try {
const response = await userApi.login(credentials)
this.userInfo = response.data
this.isLoggedIn = true
return response
} catch (error) {
throw error
}
},
logout() {
this.userInfo = null
this.isLoggedIn = false
this.permissions = []
}
}
})
```
## 🚀 开发流程
### 1. 环境搭建
```bash
# 克隆项目
git clone
# 进入项目目录
cd xlxumu/mini_program
# 安装依赖
npm install
# 启动开发服务器
npm run dev:mp-weixin
```
### 2. 开发流程
1. **需求分析**: 明确功能需求和技术要求
2. **设计评审**: 进行UI设计和技术方案评审
3. **功能开发**: 按照规范进行功能开发
4. **代码审查**: 提交代码前进行代码审查
5. **测试验证**: 进行功能测试和兼容性测试
6. **部署发布**: 构建和部署到各个平台
### 3. Git工作流
```bash
# 创建功能分支
git checkout -b feature/user-management
# 提交代码
git add .
git commit -m "feat: 添加用户管理功能"
# 推送分支
git push origin feature/user-management
# 创建合并请求
# 代码审查通过后合并到主分支
```
### 4. 代码提交规范
使用 Conventional Commits 规范：
```
[optional scope]:
[optional body]
[optional footer(s)]
```
类型说明：
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动
## 🧪 测试策略
### 1. 单元测试
```javascript
// tests/utils/format.test.js
import { formatDate, formatCurrency } from '@/common/utils/format'
describe('Format Utils', () => {
test('formatDate should format date correctly', () => {
const date = new Date('2024-01-01')
expect(formatDate(date)).toBe('2024-01-01')
})
test('formatCurrency should format currency correctly', () => {
expect(formatCurrency(1234.56)).toBe('¥1,234.56')
})
})
```
### 2. 组件测试
```javascript
// tests/components/UserProfile.test.js
import { mount } from '@vue/test-utils'
import UserProfile from '@/components/UserProfile.vue'
describe('UserProfile', () => {
test('renders user information correctly', () => {
const wrapper = mount(UserProfile, {
props: {
user: {
name: 'Test User',
email: 'test@example.com'
}
}
})
expect(wrapper.text()).toContain('Test User')
expect(wrapper.text()).toContain('test@example.com')
})
})
```
### 3. E2E测试
```javascript
// tests/e2e/login.spec.js
describe('Login Flow', () => {
it('should login successfully', () => {
cy.visit('/login')
cy.get('[data-cy=username]').type('admin')
cy.get('[data-cy=password]').type('password')
cy.get('[data-cy=login-btn]').click()
cy.url().should('include', '/dashboard')
})
})
```
## 📦 构建部署
### 1. 构建命令
```bash
# 构建微信小程序
npm run build:mp-weixin
# 构建支付宝小程序
npm run build:mp-alipay
# 构建H5版本
npm run build:h5
# 构建所有平台
npm run build:all
```
### 2. 部署脚本
```bash
# 部署到测试环境
./scripts/deploy.sh mp-weixin testing
# 部署到生产环境
./scripts/deploy.sh mp-weixin production
```
### 3. CI/CD配置
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Node.js
uses: actions/setup-node@v2
with:
node-version: '16'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Build
run: npm run build:all
- name: Deploy
run: ./scripts/deploy.sh
```
## 🔍 性能优化
### 1. 代码分割
```javascript
// 路由懒加载
const UserProfile = () => import('@/pages/user/profile')
// 组件懒加载
const LazyComponent = defineAsyncComponent(() => import('@/components/Heavy'))
```
### 2. 图片优化
```javascript
// 图片压缩和格式转换
const compressImage = (file, quality = 0.8) => {
return new Promise((resolve) => {
const canvas = document.createElement('canvas')
const ctx = canvas.getContext('2d')
const img = new Image()
img.onload = () => {
canvas.width = img.width
canvas.height = img.height
ctx.drawImage(img, 0, 0)
canvas.toBlob(resolve, 'image/jpeg', quality)
}
img.src = URL.createObjectURL(file)
})
}
```
### 3. 缓存策略
```javascript
// HTTP缓存
const request = axios.create({
timeout: 10000,
headers: {
'Cache-Control': 'max-age=300'
}
})
// 本地缓存
const cache = {
set(key, value, expire = 30 * 60 * 1000) {
const data = {
value,
expire: Date.now() + expire
}
uni.setStorageSync(key, JSON.stringify(data))
},
get(key) {
const data = uni.getStorageSync(key)
if (!data) return null
const parsed = JSON.parse(data)
if (Date.now() > parsed.expire) {
uni.removeStorageSync(key)
return null
}
return parsed.value
}
}
```
## 🛡️ 安全规范
### 1. 数据验证
```javascript
// 输入验证
const validateInput = (data, rules) => {
const errors = {}
Object.keys(rules).forEach(field => {
const rule = rules[field]
const value = data[field]
if (rule.required && !value) {
errors[field] = `${field} is required`
}
if (rule.pattern && !rule.pattern.test(value)) {
errors[field] = `${field} format is invalid`
}
})
return {
isValid: Object.keys(errors).length === 0,
errors
}
}
```
### 2. XSS防护
```javascript
// HTML转义
const escapeHtml = (text) => {
const map = {
'&': '&',
'<': '<',
'>': '>',
'"': '"',
"'": '''
}
return text.replace(/[&<>"']/g, (m) => map[m])
}
```
### 3. 敏感信息保护
```javascript
// 敏感信息脱敏
const maskSensitiveInfo = (info, type) => {
switch (type) {
case 'phone':
return info.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2')
case 'email':
return info.replace(/(.{2}).*(@.*)/, '$1***$2')
case 'idCard':
return info.replace(/(\d{6})\d{8}(\d{4})/, '$1********$2')
default:
return info
}
}
```
## 📊 监控告警
### 1. 错误监控
```javascript
// 全局错误处理
const errorHandler = (error, instance, info) => {
console.error('Global error:', error)
// 发送错误报告
reportError({
error: error.message,
stack: error.stack,
info,
url: window.location.href,
userAgent: navigator.userAgent,
timestamp: new Date().toISOString()
})
}
app.config.errorHandler = errorHandler
```
### 2. 性能监控
```javascript
// 性能数据收集
const performanceMonitor = {
// 页面加载时间
measurePageLoad() {
const navigation = performance.getEntriesByType('navigation')[0]
return {
loadTime: navigation.loadEventEnd - navigation.fetchStart,
domReady: navigation.domContentLoadedEventEnd - navigation.fetchStart,
firstPaint: performance.getEntriesByName('first-paint')[0]?.startTime
}
},
// API响应时间
measureApiResponse(url, startTime) {
const endTime = performance.now()
const duration = endTime - startTime
// 记录API性能数据
this.recordMetric('api_response_time', {
url,
duration,
timestamp: Date.now()
})
}
}
```
## 📚 文档维护
### 1. API文档
使用 JSDoc 规范编写API文档：
```javascript
/**
* 用户登录
* @param {Object} credentials - 登录凭证
* @param {string} credentials.username - 用户名
* @param {string} credentials.password - 密码
* @returns {Promise