Generating commit message...
This commit is contained in:
203
docs/API-README.md
Normal file
203
docs/API-README.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 结伴客系统 API 使用指南
|
||||
|
||||
## 📖 概述
|
||||
|
||||
本文档提供了结伴客系统完整的API接口说明，包括认证、用户管理、旅行服务、动物认领、商家服务、推广奖励等核心功能接口。
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 环境要求
|
||||
- Node.js 16+
|
||||
- MySQL 8.0+
|
||||
- Redis (可选)
|
||||
- RabbitMQ (可选)
|
||||
|
||||
### 安装依赖
|
||||
```bash
|
||||
cd scripts
|
||||
npm install
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
```bash
|
||||
# 运行完整API测试
|
||||
npm test
|
||||
|
||||
# 仅测试健康检查
|
||||
npm run test:health
|
||||
```
|
||||
|
||||
## 🔐 认证方式
|
||||
|
||||
所有需要认证的接口都需要在请求头中包含Bearer Token：
|
||||
|
||||
```http
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
### 获取Token的流程：
|
||||
1. 用户注册或登录
|
||||
2. 从响应中获取token
|
||||
3. 在后续请求的Header中包含token
|
||||
|
||||
## 📋 核心接口
|
||||
|
||||
### 用户认证
|
||||
- `POST /auth/register` - 用户注册
|
||||
- `POST /auth/login` - 用户登录
|
||||
- `POST /auth/wechat-login` - 微信登录
|
||||
- `GET /auth/me` - 获取当前用户信息
|
||||
|
||||
### 旅行服务
|
||||
- `POST /travel/plans` - 创建旅行计划
|
||||
- `GET /travel/plans` - 获取旅行计划列表
|
||||
- `GET /travel/matches` - 匹配旅行伙伴
|
||||
|
||||
### 动物认领
|
||||
- `GET /animals` - 获取可认领动物列表
|
||||
- `POST /animals/{id}/claim` - 认领动物
|
||||
- `GET /animals/claims` - 获取认领记录
|
||||
|
||||
### 商家服务
|
||||
- `POST /merchants/register` - 商家注册
|
||||
- `POST /merchants/products` - 发布商品/服务
|
||||
- `GET /merchants/orders` - 获取商家订单
|
||||
|
||||
### 推广奖励
|
||||
- `GET /promotion/link` - 获取推广链接
|
||||
- `GET /promotion/stats` - 获取推广数据
|
||||
- `POST /promotion/withdraw` - 申请提现
|
||||
|
||||
### 官网接口
|
||||
- `POST /website/merchant/apply` - 提交商家入驻申请
|
||||
- `GET /website/cases` - 获取成功案例列表
|
||||
|
||||
## 🎯 响应格式
|
||||
|
||||
### 成功响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"message": "操作成功",
|
||||
"data": {
|
||||
// 具体业务数据
|
||||
},
|
||||
"timestamp": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"code": 400,
|
||||
"message": "错误信息",
|
||||
"error": "详细错误描述",
|
||||
"timestamp": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **时间格式**: 所有时间字段使用ISO 8601格式 (YYYY-MM-DDTHH:mm:ss.sssZ)
|
||||
2. **金额单位**: 人民币元，保留两位小数
|
||||
3. **图片URL**: 必须使用HTTPS协议
|
||||
4. **频率限制**: API调用频率限制为每分钟100次
|
||||
5. **敏感操作**: 需要二次验证确保安全
|
||||
|
||||
## 🔧 开发建议
|
||||
|
||||
### 1. 错误处理
|
||||
```javascript
|
||||
try {
|
||||
const response = await api.post('/auth/login', credentials);
|
||||
// 处理成功响应
|
||||
} catch (error) {
|
||||
if (error.response?.status === 401) {
|
||||
// 处理未授权错误
|
||||
} else if (error.response?.status === 429) {
|
||||
// 处理频率限制错误
|
||||
} else {
|
||||
// 处理其他错误
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 请求重试
|
||||
对于重要的请求，建议实现重试机制：
|
||||
|
||||
```javascript
|
||||
async function requestWithRetry(url, data, retries = 3) {
|
||||
for (let i = 0; i < retries; i++) {
|
||||
try {
|
||||
return await api.post(url, data);
|
||||
} catch (error) {
|
||||
if (i === retries - 1) throw error;
|
||||
await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Token刷新
|
||||
实现token自动刷新机制：
|
||||
|
||||
```javascript
|
||||
// 响应拦截器处理token过期
|
||||
api.interceptors.response.use(
|
||||
(response) => response,
|
||||
async (error) => {
|
||||
if (error.response?.status === 401) {
|
||||
// 刷新token逻辑
|
||||
const newToken = await refreshToken();
|
||||
error.config.headers.Authorization = `Bearer ${newToken}`;
|
||||
return api.request(error.config);
|
||||
}
|
||||
return Promise.reject(error);
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
## 📊 监控和日志
|
||||
|
||||
建议对API调用进行监控和日志记录：
|
||||
|
||||
1. **性能监控**: 记录每个接口的响应时间
|
||||
2. **错误监控**: 记录API调用错误和异常
|
||||
3. **使用统计**: 统计接口调用频率和用户行为
|
||||
4. **安全审计**: 记录敏感操作和登录尝试
|
||||
|
||||
## 🚨 常见问题
|
||||
|
||||
### Q1: 如何处理重复注册？
|
||||
A: 注册接口会返回409状态码，提示"用户已存在"
|
||||
|
||||
### Q2: 如何重置密码？
|
||||
A: 目前需要通过客服渠道重置，后续会开发密码重置功能
|
||||
|
||||
### Q3: 如何获取商家资质？
|
||||
A: 商家需要准备营业执照等资质文件，通过官网提交申请
|
||||
|
||||
### Q4: API调用频率限制是多少？
|
||||
A: 每分钟100次请求，超过限制会返回429状态码
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如有API使用问题，请联系：
|
||||
- 邮箱: support@jiebanke.com
|
||||
- 电话: 400-123-4567
|
||||
- 微信: jiebanke-support
|
||||
|
||||
## 📄 版本历史
|
||||
|
||||
| 版本 | 日期 | 说明 |
|
||||
|------|------|------|
|
||||
| v1.0 | 2025-01-01 | 初始版本发布 |
|
||||
| v1.1 | 2025-02-01 | 新增微信登录接口 |
|
||||
| v1.2 | 2025-03-01 | 优化错误处理机制 |
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2025-01-01
|
||||
**文档版本**: v1.0
|
||||
851
docs/api-documentation.md
Normal file
851
docs/api-documentation.md
Normal file
@@ -0,0 +1,851 @@
|
||||
# 结伴客系统 API 接口文档
|
||||
|
||||
## 基础信息
|
||||
|
||||
**Base URL**: `http://localhost:3000/api/v1`
|
||||
|
||||
**认证方式**: Bearer Token (JWT)
|
||||
|
||||
**响应格式**: JSON
|
||||
|
||||
## 响应格式
|
||||
|
||||
### 成功响应
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"message": "操作成功",
|
||||
"data": {
|
||||
// 具体数据
|
||||
},
|
||||
"timestamp": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"code": 400,
|
||||
"message": "错误信息",
|
||||
"error": "详细错误描述",
|
||||
"timestamp": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 认证接口
|
||||
|
||||
### 1. 用户注册
|
||||
|
||||
**Endpoint**: `POST /auth/register`
|
||||
|
||||
**描述**: 创建新用户账号
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"username": "string, required, 用户名(4-20字符)",
|
||||
"password": "string, required, 密码(6-20字符)",
|
||||
"nickname": "string, optional, 昵称",
|
||||
"email": "string, optional, 邮箱",
|
||||
"phone": "string, optional, 手机号",
|
||||
"gender": "string, optional, 性别(male/female/unknown)",
|
||||
"birthday": "string, optional, 生日(YYYY-MM-DD)"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 201,
|
||||
"message": "注册成功",
|
||||
"data": {
|
||||
"user": {
|
||||
"id": 1,
|
||||
"username": "testuser",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "13800138000",
|
||||
"avatar": "",
|
||||
"gender": "unknown",
|
||||
"points": 0,
|
||||
"level": 1,
|
||||
"status": "active",
|
||||
"created_at": "2025-01-01T00:00:00.000Z"
|
||||
},
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 用户登录
|
||||
|
||||
**Endpoint**: `POST /auth/login`
|
||||
|
||||
**描述**: 用户登录获取访问令牌
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"username": "string, required, 用户名/邮箱/手机号",
|
||||
"password": "string, required, 密码"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.1 微信登录
|
||||
|
||||
**Endpoint**: `POST /auth/wechat-login`
|
||||
|
||||
**描述**: 微信授权登录
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"code": "string, required, 微信授权码",
|
||||
"userInfo": {
|
||||
"nickName": "string, optional, 微信昵称",
|
||||
"avatarUrl": "string, optional, 微信头像",
|
||||
"gender": "number, optional, 性别(0:未知,1:男,2:女)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 同登录接口
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"message": "登录成功",
|
||||
"data": {
|
||||
"user": {
|
||||
"id": 1,
|
||||
"username": "testuser",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "13800138000",
|
||||
"avatar": "",
|
||||
"gender": "unknown",
|
||||
"points": 100,
|
||||
"level": 2,
|
||||
"status": "active",
|
||||
"last_login_at": "2025-01-01T00:00:00.000Z"
|
||||
},
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 微信登录
|
||||
|
||||
**Endpoint**: `POST /auth/wechat-login`
|
||||
|
||||
**描述**: 微信授权登录
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"code": "string, required, 微信授权码",
|
||||
"userInfo": {
|
||||
"nickName": "string, optional, 微信昵称",
|
||||
"avatarUrl": "string, optional, 微信头像",
|
||||
"gender": "number, optional, 性别(0:未知,1:男,2:女)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 同登录接口
|
||||
|
||||
### 4. 获取当前用户信息
|
||||
|
||||
**Endpoint**: `GET /auth/me`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**描述**: 获取当前登录用户信息
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"user": {
|
||||
"id": 1,
|
||||
"username": "testuser",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "13800138000",
|
||||
"avatar": "https://example.com/avatar.jpg",
|
||||
"gender": "male",
|
||||
"birthday": "1990-01-01",
|
||||
"points": 1000,
|
||||
"level": 3,
|
||||
"balance": 500.00,
|
||||
"travel_count": 5,
|
||||
"animal_adopt_count": 2,
|
||||
"flower_order_count": 3,
|
||||
"status": "active",
|
||||
"created_at": "2025-01-01T00:00:00.000Z",
|
||||
"updated_at": "2025-01-01T00:00:00.000Z",
|
||||
"last_login_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 更新用户信息
|
||||
|
||||
**Endpoint**: `PUT /auth/profile`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**描述**: 更新用户个人信息
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"nickname": "string, optional, 昵称",
|
||||
"avatar": "string, optional, 头像URL",
|
||||
"gender": "string, optional, 性别(male/female/unknown)",
|
||||
"birthday": "string, optional, 生日(YYYY-MM-DD)"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**: 同获取用户信息接口
|
||||
|
||||
### 6. 修改密码
|
||||
|
||||
**Endpoint**: `PUT /auth/password`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**描述**: 修改用户密码
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"currentPassword": "string, required, 当前密码",
|
||||
"newPassword": "string, required, 新密码(6-20字符)"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"message": "密码修改成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 用户接口
|
||||
|
||||
### 1. 获取用户列表
|
||||
|
||||
**Endpoint**: `GET /users`
|
||||
|
||||
**认证**: 需要Bearer Token (管理员权限)
|
||||
|
||||
**查询参数**:
|
||||
- `page`: number, optional, 页码 (默认: 1)
|
||||
- `pageSize`: number, optional, 每页数量 (默认: 20)
|
||||
- `search`: string, optional, 搜索关键词
|
||||
- `status`: string, optional, 状态过滤(active/inactive/banned)
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"users": [
|
||||
{
|
||||
"id": 1,
|
||||
"username": "user1",
|
||||
"nickname": "用户1",
|
||||
"email": "user1@example.com",
|
||||
"phone": "13800138001",
|
||||
"status": "active",
|
||||
"level": 2,
|
||||
"created_at": "2025-01-01极速版T00:00:00.000Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"totalPages": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取用户详情
|
||||
|
||||
**Endpoint**: `GET /users/:id`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"user": {
|
||||
"id": 1,
|
||||
"username": "testuser",
|
||||
"nickname": "测试用户",
|
||||
"email": "test@example.com",
|
||||
"phone": "13800138000",
|
||||
"avatar": "https://example.com/avatar.jpg",
|
||||
"gender": "male",
|
||||
"points": 1000,
|
||||
"level": 3,
|
||||
"status": "active",
|
||||
"created_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 旅行接口
|
||||
|
||||
### 1. 创建旅行计划
|
||||
|
||||
**Endpoint**: `POST /travel/plans`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"destination": "string, required, 目的地",
|
||||
"start_date": "string, required, 开始日期(YYYY-MM-DD)",
|
||||
"end_date": "string, required, 结束日期(YYYY-MM-DD)",
|
||||
"budget": "number, required, 预算",
|
||||
"interests": "string, optional, 兴趣偏好",
|
||||
"visibility": "string, optional, 可见范围(public/friends/private)"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 201,
|
||||
"message": "旅行计划创建成功",
|
||||
"data": {
|
||||
"plan": {
|
||||
"id": 1,
|
||||
"title": "西藏自驾游",
|
||||
"description": "寻找志同道合的旅友一起探索西藏",
|
||||
"destination": "西藏",
|
||||
"start_date": "2025-07-01",
|
||||
"end_date": "2025-07-15",
|
||||
"budget": 5000,
|
||||
"max_members": 4,
|
||||
"current_members": 1,
|
||||
"status": "recruiting",
|
||||
"tags": ["自驾", "摄影", "探险"],
|
||||
"creator_id": 1,
|
||||
"created_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取旅行计划列表
|
||||
|
||||
**Endpoint**: `GET /travel/plans`
|
||||
|
||||
**查询参数**:
|
||||
- `page`: number, optional, 页码
|
||||
- `pageSize`: number, optional, 每页数量
|
||||
- `destination`: string, optional, 目的地搜索
|
||||
- `start_date`: string, optional, 开始日期之后
|
||||
- `end_date`: string, optional, 结束日期之前
|
||||
- `status`: string, optional, 状态(recruiting/in_progress/completed/cancelled)
|
||||
- `tags`: string, optional, 标签过滤(多个用逗号分隔)
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"plans": [
|
||||
{
|
||||
"id": 1,
|
||||
"destination": "西藏",
|
||||
"start_date": "2025-07-01",
|
||||
"end_date": "2025-07-15",
|
||||
"budget": 5000.00,
|
||||
"interests": "自驾,摄影,探险",
|
||||
"visibility": "public",
|
||||
"creator": {
|
||||
"id": 1,
|
||||
"nickname": "旅行达人",
|
||||
"avatar": "https://example.com/avatar.jpg"
|
||||
},
|
||||
"created_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 50,
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"totalPages": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 匹配旅行伙伴
|
||||
|
||||
**Endpoint**: `GET /travel/matches`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**查询参数**:
|
||||
- `plan_id`: number, required, 旅行计划ID
|
||||
- `page`: number, optional, 页码
|
||||
- `pageSize`: number, optional, 每页数量
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": 2,
|
||||
"destination": "西藏",
|
||||
"start_date": "2025-07-02",
|
||||
"end_date": "2025-07-08",
|
||||
"budget": 4500.00,
|
||||
"interests": "徒步,美食",
|
||||
"match_score": 0.85,
|
||||
"user": {
|
||||
"id": 2,
|
||||
"nickname": "旅行伙伴",
|
||||
"avatar": "https://example.com/avatar2.jpg"
|
||||
}
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"size": 10,
|
||||
"total": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 动物认领接口
|
||||
|
||||
### 1. 发布动物认领
|
||||
|
||||
**Endpoint**: `POST /animals`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"name": "string, required, 动物名称",
|
||||
"species": "string, required, 物种",
|
||||
"breed": "string, optional, 品种",
|
||||
"age": "number, optional, 年龄",
|
||||
"gender": "string, optional, 性别(male/female/unknown)",
|
||||
"description": "string, required, 描述",
|
||||
"location": "string, required, 位置",
|
||||
"images": "array, optional, 图片URL数组",
|
||||
"vaccination_status": "string, optional, 疫苗接种情况",
|
||||
"sterilization_status": "string, optional, 绝育情况"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 201,
|
||||
"message": "动物认领发布成功",
|
||||
"data": {
|
||||
"animal": {
|
||||
"id": 1,
|
||||
"name": "小白",
|
||||
"species": "猫",
|
||||
"breed": "中华田园猫",
|
||||
"age": 2,
|
||||
"gender": "male",
|
||||
"description": "非常温顺的猫咪，寻找有爱心的主人",
|
||||
"location": "北京市朝阳区",
|
||||
"status": "available",
|
||||
"images": ["https://example.com/cat1.jpg"],
|
||||
"creator_id": 1,
|
||||
"created_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 商家服务接口
|
||||
|
||||
### 1. 商家注册
|
||||
|
||||
**Endpoint**: `POST /merchants/register`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"merchant_type": "string, required, 商家类型(flower_shop/activity_organizer/farm_owner)",
|
||||
"business_name": "string, required, 商家名称",
|
||||
"business_license": "string, optional, 营业执照URL",
|
||||
"contact_person": "string, required, 联系人",
|
||||
"contact_phone": "string, required, 联系电话",
|
||||
"address": "string, optional, 地址",
|
||||
"description": "string, optional, 商家介绍"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 201,
|
||||
"message": "商家注册申请已提交",
|
||||
"data": {
|
||||
"merchant": {
|
||||
"id": 1,
|
||||
"user_id": 1,
|
||||
"merchant_type": "farm_owner",
|
||||
"business_name": "XX农场",
|
||||
"business_license": "https://example.com/license.jpg",
|
||||
"contact_person": "张三",
|
||||
"contact_phone": "13800138000",
|
||||
"address": "北京市朝阳区XX路XX号",
|
||||
"description": "专业养殖羊驼的农场",
|
||||
"status": "pending",
|
||||
"created_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 发布商品/服务
|
||||
|
||||
**Endpoint**: `POST /merchants/products`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"name": "string, required, 商品名称",
|
||||
"description": "string, required, 商品描述",
|
||||
"price": "number, required, 价格",
|
||||
"image_url": "string, optional, 图片URL",
|
||||
"category": "string, required, 商品类别",
|
||||
"status": "string, optional, 状态(available/unavailable)"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 201,
|
||||
"message": "商品发布成功",
|
||||
"data": {
|
||||
"product": {
|
||||
"id": 1,
|
||||
"merchant_id": 1,
|
||||
"name": "羊驼认领体验",
|
||||
"description": "提供一个月的羊驼认领体验服务",
|
||||
"price": 1000.00,
|
||||
"image_url": "https://example.com/product.jpg",
|
||||
"category": "animal_claim",
|
||||
"status": "available",
|
||||
"created_at": "202极速版5-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 获取商家订单
|
||||
|
||||
**Endpoint**: `GET /merchants/orders`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**查询参数**:
|
||||
- `page`: number, optional, 页码
|
||||
- `pageSize`: number, optional, 每页数量
|
||||
- `status`: string, optional, 订单状态
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"orders": [
|
||||
{
|
||||
"id": 1,
|
||||
"user_id": 2,
|
||||
"order_number": "ORD202501010001",
|
||||
"total_amount": 1000.00,
|
||||
"status": "paid",
|
||||
"ordered_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 50,
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"totalPages": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 鲜花订购接口
|
||||
|
||||
### 1. 创建鲜花订单
|
||||
|
||||
**Endpoint**: `POST /flowers/orders`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"product_id": "number, required, 商品ID",
|
||||
"quantity": "number, required, 数量",
|
||||
"recipient_name": "string, required, 收花人姓名",
|
||||
"recipient_phone": "string, required, 收花人电话",
|
||||
"delivery_address": "string, required, 配送地址",
|
||||
"delivery_date": "string, required, 配送日期(YYYY-MM-DD)",
|
||||
"delivery_time": "string, required, 配送时间段",
|
||||
"message": "string, optional, 祝福语",
|
||||
"special_instructions": "string, optional, 特殊说明"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 201,
|
||||
"message": "订单创建成功",
|
||||
"data": {
|
||||
"order": {
|
||||
"极速版id": 1,
|
||||
"order_number": "F202501010001",
|
||||
"product_id": 1,
|
||||
"quantity": 1,
|
||||
"total_amount": 199.00,
|
||||
"status": "pending",
|
||||
"recipient_name": "张三",
|
||||
"recipient_phone": "13800138000",
|
||||
"delivery_address": "北京市朝阳区xxx路xxx号",
|
||||
"delivery_date": "2025-01-01",
|
||||
"delivery_time": "09:00-12:00",
|
||||
"created_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 推广奖励接口
|
||||
|
||||
### 1. 获取推广链接
|
||||
|
||||
**Endpoint**: `GET /promotion/link`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"promotion_link": "https://example.com/promotion?ref=user123",
|
||||
"qr_code": "https://example.com/qrcode.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取推广数据
|
||||
|
||||
**Endpoint**: `GET /promotion/stats`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"total_referrals": 50,
|
||||
"successful_registrations": 25,
|
||||
"total_rewards": 500.00,
|
||||
"available_rewards": 300.00,
|
||||
"withdrawn_rewards": 200.00
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 申请提现
|
||||
|
||||
**Endpoint**: `POST /promotion/withdraw`
|
||||
|
||||
**认证**: 需要Bearer Token
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"amount": "number, required, 提现金额",
|
||||
"payment_method": "string, required, 支付方式(wechat/alipay)"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"message": "提现申请已提交",
|
||||
"data": {
|
||||
"withdrawal_id": "WD202501010001",
|
||||
"status": "processing"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 系统接口
|
||||
|
||||
### 1. 健康检查
|
||||
|
||||
**Endpoint**: `GET /health`
|
||||
|
||||
**描述**: 检查服务健康状态
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"status": "OK",
|
||||
"timestamp": "2025-01-01T00:00:00.000Z",
|
||||
"uptime": 12345.67,
|
||||
"environment": "development",
|
||||
"services": {
|
||||
"database": "connected",
|
||||
"redis": "disconnected",
|
||||
"rabbitmq": "disconnected"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 官网接口
|
||||
|
||||
### 1. 提交商家入驻申请
|
||||
|
||||
**Endpoint**: `POST /website/merchant/apply`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"business_name": "string, required, 商家名称",
|
||||
"contact_person": "string, required, 联系人",
|
||||
"contact_phone": "string, required, 联系电话",
|
||||
"email": "string, optional, 邮箱",
|
||||
"description": "string, optional, 商家描述"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 201,
|
||||
"message": "入驻申请已提交",
|
||||
"data": {
|
||||
"application_id": 1,
|
||||
"status": "pending"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取成功案例列表
|
||||
|
||||
**Endpoint**: `GET /website/cases`
|
||||
|
||||
**查询参数**:
|
||||
- `page`: number, optional, 页码
|
||||
- `pageSize`: number, optional, 每页数量
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"code": 200,
|
||||
"data": {
|
||||
"cases": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "XX农场成功入驻案例",
|
||||
"description": "XX农场通过平台实现了数字化转型",
|
||||
"image_url": "https://example.com/case1.jpg",
|
||||
"created_at": "2025-01-01T00:00:00.000Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 50,
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"totalPages": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| 错误码 | 说明 | 处理建议 |
|
||||
|--------|------|----------|
|
||||
| 200 | 成功 | 操作成功 |
|
||||
| 201 | 创建成功 | 资源创建成功 |
|
||||
| 400 | 请求错误 | 检查请求参数 |
|
||||
| 401 | 未授权 | 需要登录认证 |
|
||||
| 403 | 禁止访问 | 权限不足 |
|
||||
| 404 | 资源不存在 | 检查资源ID |
|
||||
| 409 | 资源冲突 | 资源已存在 |
|
||||
| 429 | 请求过多 | 降低请求频率 |
|
||||
| 500 | 服务器错误 | 联系管理员 |
|
||||
|
||||
## 版本历史
|
||||
|
||||
| 版本 | 日期 | 说明 |
|
||||
|------|------|------|
|
||||
| v1.0 | 2025-01-01 | 初始版本发布 |
|
||||
| v1.1 | 2025-02-01 | 新增微信登录接口 |
|
||||
| v1.2 | 2025-03-01 | 优化错误处理机制 |
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 所有时间格式均为 ISO 8601 格式 (YYYY-MM-DDTHH:mm:ss.sssZ)
|
||||
2. 金额单位为元，保留两位小数
|
||||
3. 图片URL需要支持HTTPS
|
||||
4. 敏感操作需要二次验证
|
||||
5. API调用频率限制为每分钟100次
|
||||
@@ -1,34 +1,95 @@
|
||||
# 结伴客系统架构文档
|
||||
|
||||
## 1. 架构图
|
||||
## 1. 系统架构概览
|
||||
|
||||
```
|
||||
+------------------+ +------------+ +------------------+
|
||||
| 微信小程序 | | | | |
|
||||
| (uni-app) | --> | API网关 | --> | 后端服务 |
|
||||
+------------------+ | | | (Node.js+Express)|
|
||||
+------------+ | |
|
||||
+------------------+
|
||||
|
|
||||
+-------+-------+
|
||||
| |
|
||||
+-------v-----+ +-----v-------+
|
||||
| MySQL数据库 | | Redis缓存 |
|
||||
+-------------+ +-------------+
|
||||
|
|
||||
+-------v-------+
|
||||
| RabbitMQ消息队列 |
|
||||
+-----------------+
|
||||
### 1.1 架构图
|
||||
|
||||
+------------------+
|
||||
| 后台管理系统 |
|
||||
| (Vue.js 3) |
|
||||
+------------------+
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "客户端层"
|
||||
MP[微信小程序<br/>uni-app]
|
||||
ADMIN[后台管理系统<br/>Vue.js 3 + Ant Design]
|
||||
WEBSITE[官网系统<br/>HTML5 + Bootstrap]
|
||||
end
|
||||
|
||||
+------------------+
|
||||
| 官网系统 |
|
||||
| (HTML5+Bootstrap) |
|
||||
+------------------+
|
||||
subgraph "接入层"
|
||||
GATEWAY[API网关<br/>Nginx + Node.js]
|
||||
end
|
||||
|
||||
subgraph "应用服务层"
|
||||
AUTH[认证服务]
|
||||
USER[用户服务]
|
||||
TRAVEL[旅行服务]
|
||||
ANIMAL[动物服务]
|
||||
MERCHANT[商家服务]
|
||||
PAYMENT[支付服务]
|
||||
PROMOTION[推广服务]
|
||||
end
|
||||
|
||||
subgraph "基础设施层"
|
||||
DB[MySQL数据库<br/>主从复制]
|
||||
CACHE[Redis缓存<br/>集群模式]
|
||||
MQ[RabbitMQ<br/>消息队列]
|
||||
STORAGE[对象存储<br/>腾讯云COS]
|
||||
end
|
||||
|
||||
subgraph "监控运维层"
|
||||
MONITOR[监控系统<br/>Prometheus + Grafana]
|
||||
LOG[日志系统<br/>ELK Stack]
|
||||
CI_CD[CI/CD<br/>Jenkins + Docker]
|
||||
end
|
||||
|
||||
MP --> GATEWAY
|
||||
ADMIN --> GATEWAY
|
||||
WEBSITE --> GATEWAY
|
||||
|
||||
GATEWAY --> AUTH
|
||||
GATEWAY --> USER
|
||||
GATEWAY --> TRAVEL
|
||||
GATEWAY --> ANIMAL
|
||||
GATEWAY --> MERCHANT
|
||||
GATEWAY --> PAYMENT
|
||||
GATEWAY --> PROMOTION
|
||||
|
||||
AUTH --> DB
|
||||
USER --> DB
|
||||
TRAVEL --> DB
|
||||
ANIMAL --> DB
|
||||
MERCHANT --> DB
|
||||
PAYMENT --> DB
|
||||
PROMOTION --> DB
|
||||
|
||||
AUTH --> CACHE
|
||||
USER --> CACHE
|
||||
TRAVEL --> CACHE
|
||||
ANIMAL --> CACHE
|
||||
MERCHANT --> CACHE
|
||||
|
||||
PAYMENT --> MQ
|
||||
PROMOTION --> MQ
|
||||
|
||||
AUTH --> STORAGE
|
||||
USER --> STORAGE
|
||||
ANIMAL --> STORAGE
|
||||
MERCHANT --> STORAGE
|
||||
|
||||
MONITOR -.-> AUTH
|
||||
MONITOR -.-> USER
|
||||
MONITOR -.-> TRAVEL
|
||||
MONITOR -.-> ANIMAL
|
||||
MONITOR -.-> MERCHANT
|
||||
|
||||
LOG -.-> AUTH
|
||||
LOG -.-> USER
|
||||
LOG -.-> TRAVEL
|
||||
LOG -.-> ANIMAL
|
||||
LOG -.-> MERCHANT
|
||||
|
||||
CI_CD -.-> AUTH
|
||||
CI_CD -.-> USER
|
||||
CI_CD -.-> TRAVEL
|
||||
CI_CD -.-> ANIMAL
|
||||
CI_CD -.-> MERCHANT
|
||||
```
|
||||
|
||||
## 2. 项目结构
|
||||
@@ -263,15 +324,13 @@
|
||||
## 2. 技术栈选型
|
||||
|
||||
### 2.1 后端技术栈
|
||||
- 编程语言：Node.js (TypeScript)
|
||||
- 框架：Express.js
|
||||
- API规范：RESTful API
|
||||
- 容器化：Docker
|
||||
- 容器编排：Kubernetes
|
||||
- API网关：Kong
|
||||
- 监控：Prometheus + Grafana
|
||||
- 日志：ELK Stack (Elasticsearch, Logstash, Kibana)
|
||||
|
||||
API服务: Node.js + Express.js + TypeScript + RESTful API
|
||||
数据库: MySQL
|
||||
缓存系统: Redis
|
||||
消息队列: RabbitMQ（用于异步处理）
|
||||
文件存储: 腾讯云对象存储
|
||||
实时通信: WebSocket（用于大屏数据推送和实时通知）
|
||||
API文档: Swagger
|
||||
### 2.2 前端技术栈
|
||||
- 小程序框架：uni-app
|
||||
- 开发语言：JavaScript/TypeScript
|
||||
|
||||
@@ -1,5 +1,20 @@
|
||||
# 结伴客系统详细设计文档
|
||||
|
||||
## 2.3 数据库配置
|
||||
|
||||
### 2.3.1 测试环境
|
||||
- **主机**: 192.168.0.240 (MySQL主机地址)
|
||||
- **端口**: 3306 (MySQL端口)
|
||||
- **用户名**: root
|
||||
- **密码**: aiot$Aiot123
|
||||
- **数据库**: jiebandata
|
||||
|
||||
### 2.3.2 生产环境
|
||||
- **主机**: 129.211.213.226
|
||||
- **端口**: 9527
|
||||
- **用户名**: root
|
||||
- **密码**: aiotAiot123!
|
||||
- **数据库**: jiebandata
|
||||
## 1. 数据库设计
|
||||
|
||||
### 1.1 ER图
|
||||
|
||||
Reference in New Issue
Block a user