community-srv-cloud-utils/README.md

微信小程序通用工具库 - 前后端共用，社区服务项目

# @community-srv/cloud-utils

微信小程序通用工具库 - 前后端共用，社区服务项目专用工具函数

## 安装

```bash
npm install @community-srv/cloud-utils --registry=https://registry.npmjs.org
```

## 使用

```javascript
const { formatTimeAgo, isValidEmail, generateRandomString } = require('@community-srv/cloud-utils')

// 时间格式化
const timeAgo = formatTimeAgo(new Date())
console.log(timeAgo) // "刚刚" 或 "5分钟前" 等

// 邮箱验证
const isValid = isValidEmail('user@example.com')

// 生成随机字符串
const randomStr = generateRandomString(10)
```

## API 文档

### 时间相关

#### formatTimeAgo(date)
将时间戳转换为相对时间显示

**参数:**
- `date` (Date|string|number): 时间

**返回:**
- `string`: 格式化后的时间字符串

**示例:**
```javascript
formatTimeAgo(new Date()) // "刚刚"
formatTimeAgo(Date.now() - 300000) // "5分钟前"
formatTimeAgo(Date.now() - 3600000) // "1小时前"
formatTimeAgo(Date.now() - 86400000) // "1天前"
```

#### formatFullTime(date)
格式化完整时间显示

**参数:**
- `date` (Date|string|number): 时间

**返回:**
- `string`: 格式化后的时间字符串

**示例:**
```javascript
formatFullTime(new Date()) // "2024-01-15 14:30:00"
```

### 验证函数

#### validateJobData(data)
招聘信息数据验证

**参数:**
- `data` (Object): 招聘信息数据对象

**返回:**
- `Object`: `{ isValid: boolean, errors: string[] }`

**示例:**
```javascript
const jobData = {
  company: '测试公司',
  position: '前端开发',
  salary: '8000-12000',
  count: 2,
  address: '北京市朝阳区',
  contact: '张经理',
  phone: '13800138000',
  communities: ['community1', 'community2']
}

const validation = validateJobData(jobData)
if (!validation.isValid) {
  console.log('验证失败:', validation.errors)
}
```

#### validateId(id, fieldName)
验证ID参数

**参数:**
- `id` (string): 要验证的ID
- `fieldName` (string): 字段名称，默认'ID'

**返回:**
- `Object`: `{ isValid: boolean, error: string }`

#### validateStatus(status, validStatuses, fieldName)
验证状态值

**参数:**
- `status` (string): 要验证的状态值
- `validStatuses` (Array): 有效状态数组
- `fieldName` (string): 字段名称，默认'状态'

**返回:**
- `Object`: `{ isValid: boolean, error: string }`

#### isValidEmail(email)
验证邮箱格式

**参数:**
- `email` (string): 邮箱地址

**返回:**
- `boolean`: 是否为有效邮箱

#### isValidPhone(phone)
验证手机号格式

**参数:**
- `phone` (string): 手机号

**返回:**
- `boolean`: 是否为有效手机号

### 工具函数

#### generateRandomString(length)
生成随机字符串

**参数:**
- `length` (number): 长度，默认8

**返回:**
- `string`: 随机字符串

#### calculateSimilarity(text1, text2)
计算文本相似度（简单的编辑距离算法）

**参数:**
- `text1` (string): 文本1
- `text2` (string): 文本2

**返回:**
- `number`: 相似度（0-1）

## 在云函数中使用

### 1. 安装依赖
```bash
cd cloudfunctions/your-function
npm install @community-srv/cloud-utils --registry=https://registry.npmjs.org
```

### 2. 引用工具函数
```javascript
const { formatTimeAgo, isValidEmail } = require('@community-srv/cloud-utils')

// 使用
const timeAgo = formatTimeAgo(item.createTime)
const isValid = isValidEmail(userEmail)
```

### 3. 更新package.json
```json
{
  "dependencies": {
    "wx-server-sdk": "~2.6.3",
    "@community-srv/cloud-utils": "^2.0.0"
  }
}
```

## 在前端中使用

### 1. 安装依赖
```bash
cd miniprogram
npm install @community-srv/cloud-utils --registry=https://registry.npmjs.org
```

### 2. 构建npm包
在微信开发者工具中：
1. 点击 "工具" -> "构建npm"
2. 等待构建完成

### 3. 使用工具函数
```javascript
// 在页面或组件中
const { formatTimeAgo, isValidEmail, validateJobData } = require('@community-srv/cloud-utils')

Page({
  data: {
    timeAgo: '',
    isEmailValid: false,
    jobData: {}
  },
  
  onLoad() {
    // 格式化时间
    this.setData({
      timeAgo: formatTimeAgo(new Date())
    })
    
    // 验证邮箱
    const isValid = isValidEmail('user@example.com')
    this.setData({
      isEmailValid: isValid
    })
  },

  // 表单提交验证
  onSubmit() {
    const validation = validateJobData(this.data.jobData)
    if (!validation.isValid) {
      wx.showToast({ 
        title: validation.errors[0], 
        icon: 'none' 
      })
      return
    }
    
    // 验证通过，继续提交
    console.log('数据验证通过')
  }
})
```

## 管理员权限和用户映射功能

**注意：** 从 v2.0.0 开始，管理员权限验证和用户昵称映射功能已迁移到 `util` 云函数中，请通过以下方式调用：

```javascript
// 在云函数中调用 util 云函数
const result = await cloud.callFunction({
  name: 'util',
  data: {
    action: 'isAdmin',
    openid: 'user_openid'
  }
})

const userMapping = await cloud.callFunction({
  name: 'util',
  data: {
    action: 'getUserNameMapping',
    openids: ['openid1', 'openid2']
  }
})
```

## 版本历史

### 2.1.0
- **新增功能：** 添加数据验证方法
- 新增 `validateJobData()` 招聘信息验证
- 新增 `validateId()` ID参数验证
- 新增 `validateStatus()` 状态值验证
- 支持前后端统一的验证逻辑
- 更新文档和使用示例

### 2.0.0
- **重大更新：** 移除对 wx-server-sdk 的依赖
- 成为真正的前后端共用工具库
- 移除 isAdmin 和 getUserNameMapping 函数（已迁移到 util 云函数）
- 新增前端使用示例和文档

### 1.0.0
- 初始版本
- 包含时间格式化、用户管理、工具函数等基础功能

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request