aiotagro/jiebanke
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

删除过时的API文档和README文件

Browse Source
This commit is contained in:
aiotagro
2025-09-19 18:45:48 +08:00
parent 4352f613fc
commit 62d122cff6
25 changed files with 3537 additions and 12343 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
docs/API-README.md
View File

@@ -1,203 +0,0 @@
# 结伴客系统 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 /api/v1/auth/register` - 用户注册
- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/wechat-login` - 微信登录
- `GET /api/v1/auth/me` - 获取当前用户信息
### 旅行服务
- `POST /api/v1/travel/plans` - 创建旅行计划
- `GET /api/v1/travel/plans` - 获取旅行计划列表
- `GET /api/v1/travel/matches` - 匹配旅行伙伴
### 动物认领
- `GET /api/v1/animals` - 获取可认领动物列表
- `POST /api/v1/animals/{id}/claim` - 认领动物
- `GET /api/v1/animals/claims` - 获取认领记录
### 商家服务
- `POST /api/v1/merchants/register` - 商家注册
- `POST /api/v1/merchants/products` - 发布商品/服务
- `GET /api/v1/merchants/orders` - 获取商家订单
### 推广奖励
- `GET /api/v1/promotion/link` - 获取推广链接
- `GET /api/v1/promotion/stats` - 获取推广数据
- `POST /api/v1/promotion/withdraw` - 申请提现
### 官网接口
- `POST /api/v1/website/merchant/apply` - 提交商家入驻申请
- `GET /api/v1/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

531
docs/API_DOCS.md
View File

@@ -1,531 +0,0 @@
# 📚 结伴客API接口文档
## 📋 文档说明
本文档详细描述了结伴客项目的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。
## 🔐 认证方式
### JWT Token 认证
所有需要认证的API必须在请求头中携带Token：
```
Authorization: Bearer <your_jwt_token>
```
### Token 获取
通过微信登录接口获取Token，Token有效期为7天。
## 👥 用户模块
### 微信用户登录
**Endpoint:** `POST /api/v1/auth/wechat-login`
**请求参数:**
```json
{
"code": "string, required, 微信登录code",
"userInfo": {
"nickName": "string, required, 用户昵称",
"avatarUrl": "string, required, 用户头像",
"gender": "number, optional, 性别(0:未知,1:男,2:女)",
"province": "string, optional, 省份",
"city": "string, optional, 城市"
}
}
```
**响应示例:**
```json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"openid": "wx1234567890",
"nickname": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"phone": "13800138000"
}
}
}
```
**错误代码:**
- `400`: 参数验证失败
- `401`: 登录失败
- `500`: 服务器内部错误
### 获取用户信息
**Endpoint:** `GET /api/v1/users/profile`
**请求头:**
```
Authorization: Bearer <token>
```
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"id": 1,
"openid": "wx1234567890",
"nickname": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"birthday": "1990-01-01",
"phone": "13800138000",
"email": "test@jiebanke.com",
"travelCount": 5,
"animalClaimCount": 2,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
}
```
**错误代码:**
- `401`: 未授权访问
- `404`: 用户不存在
- `500`: 服务器内部错误
## 🧳 旅行结伴模块
### 发布旅行计划
**Endpoint:** `POST /api/v1/travel/plans`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"destination": "string, required, 目的地",
"startDate": "string, required, 开始日期(YYYY-MM-DD)",
"endDate": "string, required, 结束日期(YYYY-MM-DD)",
"budget": "number, optional, 预算",
"interests": "string, optional, 兴趣偏好",
"description": "string, optional, 行程描述",
"visibility": "string, optional, 可见性(public/friends/private)"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "旅行计划发布成功",
"data": {
"id": 1001,
"userId": 1,
"destination": "云南大理",
"startDate": "2024-06-01",
"endDate": "2024-06-07",
"budget": 2000,
"interests": "美食,摄影,文化",
"status": "active",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
### 获取旅行计划列表
**Endpoint:** `GET /api/v1/travel/plans`
**请求头:**
```
Authorization: Bearer <token>
```
**查询参数:**
```
?page=1&limit=10&destination=大理&startDate=2024-06-01&endDate=2024-06-30
```
| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| destination | string | 目的地过滤 |
| startDate | string | 开始日期过滤 |
| endDate | string | 结束日期过滤 |
| budgetMin | number | 最低预算 |
| budgetMax | number | 最高预算 |
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"items": [
{
"id": 1001,
"userId": 1,
"userInfo": {
"nickname": "旅行达人",
"avatar": "https://avatar.url"
},
"destination": "云南大理",
"startDate": "2024-06-01",
"endDate": "2024-06-07",
"budget": 2000,
"interests": "美食,摄影,文化",
"matchScore": 85,
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 100,
"pages": 10
}
}
}
```
### 发起结伴邀请
**Endpoint:** `POST /api/v1/travel/invitations`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"travelPlanId": "number, required, 旅行计划ID",
"inviteeId": "number, required, 被邀请用户ID",
"message": "string, optional, 邀请消息"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "邀请发送成功",
"data": {
"id": 5001,
"travelPlanId": 1001,
"inviterId": 1,
"inviteeId": 2,
"status": "pending",
"message": "一起结伴去大理吧！",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 🐄 动物认领模块
### 获取可认领动物列表
**Endpoint:** `GET /api/v1/animals/available`
**查询参数:**
```
?page=1&limit=10&species=牛&farmLocation=云南
```
| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| species | string | 动物种类过滤 |
| breed | string | 品种过滤 |
| farmLocation | string | 农场位置过滤 |
| priceMin | number | 最低价格 |
| priceMax | number | 最高价格 |
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"items": [
{
"id": 2001,
"name": "小白",
"species": "牛",
"breed": "荷斯坦",
"birthDate": "2023-01-15",
"personality": "温顺亲人",
"farmLocation": "云南大理幸福农场",
"price": 2999,
"images": ["https://animal.image1.jpg", "https://animal.image2.jpg"],
"merchantInfo": {
"businessName": "幸福农场",
"contactPerson": "张老板"
},
"claimCount": 3,
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 50,
"pages": 5
}
}
}
```
### 认领动物
**Endpoint:** `POST /api/v1/animals/claim`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"animalId": "number, required, 动物ID",
"duration": "number, required, 认领时长(月)",
"agreementAccepted": "boolean, required, 是否接受协议"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "认领成功",
"data": {
"id": 3001,
"userId": 1,
"animalId": 2001,
"animalName": "小白",
"duration": 12,
"totalAmount": 35988,
"status": "paid",
"startDate": "2024-01-01",
"endDate": "2025-01-01",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 💐 送花服务模块
### 获取鲜花商品列表
**Endpoint:** `GET /api/v1/flower/products`
**查询参数:**
```
?page=1&limit=10&category=情人节&merchantId=1
```
| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| category | string | 商品分类过滤 |
| merchantId | number | 商家ID过滤 |
| priceMin | number | 最低价格 |
| priceMax | number | 最高价格 |
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"items": [
{
"id": 4001,
"name": "红玫瑰礼盒",
"description": "11朵红玫瑰精美礼盒",
"price": 199,
"originalPrice": 259,
"images": ["https://flower.image1.jpg"],
"category": "情人节",
"merchantInfo": {
"businessName": "爱之花店",
"contactPhone": "13800138000"
},
"salesCount": 150,
"rating": 4.8,
"status": "active",
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 100,
"pages": 10
}
}
}
```
### 下单送花
**Endpoint:** `POST /api/v1/flower/orders`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"productId": "number, required, 商品ID",
"quantity": "number, required, 数量",
"recipientInfo": {
"name": "string, required, 收花人姓名",
"phone": "string, required, 收花人电话",
"address": "string, required, 配送地址"
},
"deliveryDate": "string, required, 配送日期(YYYY-MM-DD)",
"message": "string, optional, 祝福语"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "下单成功",
"data": {
"id": 5001,
"orderNo": "FLOWER202401010001",
"productId": 4001,
"productName": "红玫瑰礼盒",
"quantity": 1,
"totalAmount": 199,
"recipientName": "李小姐",
"recipientPhone": "13800138001",
"deliveryAddress": "北京市朝阳区xxx路xxx号",
"deliveryDate": "2024-02-14",
"status": "pending",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 📊 数据字典
### 旅行计划状态
| 状态值 | 描述 |
|--------|------|
| active | 活跃中 |
| completed | 已完成 |
| cancelled | 已取消 |
### 结伴邀请状态
| 状态值 | 描述 |
|--------|------|
| pending | 待接受 |
| accepted | 已接受 |
| rejected | 已拒绝 |
| cancelled | 已取消 |
### 动物认领状态
| 状态值 | 描述 |
|--------|------|
| pending | 待支付 |
| paid | 已支付 |
| active | 认领中 |
| completed | 已完成 |
| cancelled | 已取消 |
### 送花订单状态
| 状态值 | 描述 |
|--------|------|
| pending | 待支付 |
| paid | 已支付 |
| confirmed | 商家已确认 |
| delivering | 配送中 |
| completed | 已完成 |
| cancelled | 已取消 |
### 错误代码
| 代码 | 描述 |
|------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 409 | 资源冲突 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
| 503 | 服务不可用 |
## 🔗 API 版本控制
当前API版本为v1，所有接口前缀为`/api/v1/`。
版本更新策略：
- 向后兼容的修改直接更新
- 不兼容的修改创建新版本v2
- 旧版本API保持维护至少6个月
## 📡 接口限流
### 限流策略
- 匿名用户: 60请求/分钟
- 认证用户: 120请求/分钟
- VIP用户: 300请求/分钟
### 限流响应
当超过限流阈值时返回：
```json
{
"code": 429,
"message": "请求过于频繁，请稍后再试",
"retryAfter": 60
}
```
## 🧪 接口测试
### 使用curl测试
```bash
# 微信用户登录
curl -X POST https://webapi.jiebanke.com/api/v1/auth/wechat-login \
-H "Content-Type: application/json" \
-d '{"code":"wxlogincode123","userInfo":{"nickName":"测试用户","avatarUrl":"https://avatar.url","gender":1}}'
# 获取旅行计划列表
curl -X GET https://webapi.jiebanke.com/api/v1/travel/plans \
-H "Authorization: Bearer <token>"
```
### 使用Postman测试
1. 导入Postman集合文件
2. 设置环境变量（base_url, token等）
3. 运行测试用例
## 📝 更新日志
### v1.0.0 (2024-01-01)
- 微信用户登录接口
- 旅行结伴管理接口
- 动物认领管理接口
- 送花服务接口
- 基础认证系统
---
*最后更新: 2024年* 📅

617
docs/API_DOCS_JAVA.md
View File

@@ -1,617 +0,0 @@
# 📚 结伴客Java微服务API接口文档
## 📋 文档说明
本文档详细描述了结伴客项目Java微服务架构的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。
## 🔐 认证方式
### JWT Token 认证
所有需要认证的API必须在请求头中携带Token：
```
Authorization: Bearer <your_jwt_token>
```
### Token 获取
通过微信登录接口获取Token，Token有效期为7天。
## 👥 用户模块
### 微信用户登录
**Endpoint:** `POST /api/auth/wechat-login`
**请求参数:**
```json
{
"code": "string, required, 微信登录code",
"userInfo": {
"nickName": "string, required, 用户昵称",
"avatarUrl": "string, required, 用户头像",
"gender": "number, optional, 性别(0:未知,1:男,2:女)",
"province": "string, optional, 省份",
"city": "string, optional, 城市"
}
}
```
**响应示例:**
```json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"username": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"phone": "13800138000"
}
}
}
```
**错误代码:**
- `400`: 参数验证失败
- `401`: 登录失败
- `500`: 服务器内部错误
### 获取用户信息
**Endpoint:** `GET /api/users/profile`
**请求头:**
```
Authorization: Bearer <token>
```
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"id": 1,
"username": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"birthday": "1990-01-01",
"phone": "13800138000",
"email": "test@jiebanke.com",
"travelCount": 5,
"animalClaimCount": 2,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
}
```
**错误代码:**
- `401`: 未授权访问
- `404`: 用户不存在
- `500`: 服务器内部错误
## 🧳 旅行结伴模块
### 发布旅行计划
**Endpoint:** `POST /api/travel/plans`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"destination": "string, required, 目的地",
"startDate": "string, required, 开始日期(YYYY-MM-DD)",
"endDate": "string, required, 结束日期(YYYY-MM-DD)",
"budget": "number, optional, 预算",
"interests": "string, optional, 兴趣偏好",
"description": "string, optional, 行程描述",
"visibility": "string, optional, 可见性(public/friends/private)"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "旅行计划发布成功",
"data": {
"id": 1001,
"userId": 1,
"destination": "云南大理",
"startDate": "2024-06-01",
"endDate": "2024-06-07",
"budget": 2000,
"interests": "美食,摄影,文化",
"status": "active",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
### 获取旅行计划列表
**Endpoint:** `GET /api/travel/plans`
**请求头:**
```
Authorization: Bearer <token>
```
**查询参数:**
```
?page=1&limit=10&destination=大理&startDate=2024-06-01&endDate=2024-06-30
```
| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| destination | string | 目的地过滤 |
| startDate | string | 开始日期过滤 |
| endDate | string | 结束日期过滤 |
| budgetMin | number | 最低预算 |
| budgetMax | number | 最高预算 |
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"items": [
{
"id": 1001,
"userId": 1,
"userInfo": {
"username": "旅行达人",
"avatar": "https://avatar.url"
},
"destination": "云南大理",
"startDate": "2024-06-01",
"endDate": "2024-06-07",
"budget": 2000,
"interests": "美食,摄影,文化",
"matchScore": 85,
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 100,
"pages": 10
}
}
}
```
### 发起结伴邀请
**Endpoint:** `POST /api/travel/invitations`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"travelPlanId": "number, required, 旅行计划ID",
"inviteeId": "number, required, 被邀请用户ID",
"message": "string, optional, 邀请消息"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "邀请发送成功",
"data": {
"id": 5001,
"travelPlanId": 1001,
"inviterId": 1,
"inviteeId": 2,
"status": "pending",
"message": "一起结伴去大理吧！",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 🐄 动物认领模块
### 获取可认领动物列表
**Endpoint:** `GET /api/animals/available`
**查询参数:**
```
?page=1&limit=10&species=牛&farmLocation=云南
```
| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| species | string | 动物种类过滤 |
| breed | string | 品种过滤 |
| farmLocation | string | 农场位置过滤 |
| priceMin | number | 最低价格 |
| priceMax | number | 最高价格 |
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"items": [
{
"id": 2001,
"name": "小白",
"species": "牛",
"breed": "荷斯坦",
"birthDate": "2023-01-15",
"personality": "温顺亲人",
"farmLocation": "云南大理幸福农场",
"price": 2999,
"images": ["https://animal.image1.jpg", "https://animal.image2.jpg"],
"merchantInfo": {
"businessName": "幸福农场",
"contactPerson": "张老板"
},
"claimCount": 3,
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 50,
"pages": 5
}
}
}
```
### 认领动物
**Endpoint:** `POST /api/animals/claim`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"animalId": "number, required, 动物ID",
"duration": "number, required, 认领时长(月)",
"agreementAccepted": "boolean, required, 是否接受协议"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "认领成功",
"data": {
"id": 3001,
"userId": 1,
"animalId": 2001,
"animalName": "小白",
"duration": 12,
"totalAmount": 35988,
"status": "paid",
"startDate": "2024-01-01",
"endDate": "2025-01-01",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 💐 送花服务模块
### 获取鲜花商品列表
**Endpoint:** `GET /api/flower/products`
**查询参数:**
```
?page=1&limit=10&category=情人节&merchantId=1
```
| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| category | string | 商品分类过滤 |
| merchantId | number | 商家ID过滤 |
| priceMin | number | 最低价格 |
| priceMax | number | 最高价格 |
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"items": [
{
"id": 4001,
"name": "红玫瑰礼盒",
"description": "11朵红玫瑰精美礼盒",
"price": 199,
"originalPrice": 259,
"images": ["https://flower.image1.jpg"],
"category": "情人节",
"merchantInfo": {
"businessName": "爱之花店",
"contactPhone": "13800138000"
},
"salesCount": 150,
"rating": 4.8,
"status": "active",
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 100,
"pages": 10
}
}
}
```
### 下单送花
**Endpoint:** `POST /api/flower/orders`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"productId": "number, required, 商品ID",
"quantity": "number, required, 数量",
"recipientInfo": {
"name": "string, required, 收花人姓名",
"phone": "string, required, 收花人电话",
"address": "string, required, 配送地址"
},
"deliveryDate": "string, required, 配送日期(YYYY-MM-DD)",
"message": "string, optional, 祝福语"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "下单成功",
"data": {
"id": 5001,
"orderNo": "FLOWER202401010001",
"productId": 4001,
"productName": "红玫瑰礼盒",
"quantity": 1,
"totalAmount": 199,
"recipientName": "李小姐",
"recipientPhone": "13800138001",
"deliveryAddress": "北京市朝阳区xxx路xxx号",
"deliveryDate": "2024-02-14",
"status": "pending",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 🎁 推广活动模块
### 获取推广活动列表
**Endpoint:** `GET /api/promotion/activities`
**查询参数:**
```
?page=1&limit=10&status=active
```
| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| status | string | 活动状态过滤 |
**响应示例:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"items": [
{
"id": 6001,
"name": "邀请好友得奖励",
"description": "邀请好友注册并完成首单，即可获得奖励",
"rewardType": "cash",
"rewardAmount": 10,
"status": "active",
"startTime": "2024-01-01T00:00:00.000Z",
"endTime": "2024-12-31T23:59:59.000Z",
"maxParticipants": 1000,
"currentParticipants": 150
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 5,
"pages": 1
}
}
}
```
### 参与推广活动
**Endpoint:** `POST /api/promotion/participate`
**请求头:**
```
Authorization: Bearer <token>
```
**请求参数:**
```json
{
"activityId": "number, required, 活动ID",
"inviteePhone": "string, required, 被邀请人手机号"
}
```
**响应示例:**
```json
{
"code": 200,
"message": "参与成功",
"data": {
"id": 7001,
"userId": 1,
"activityId": 6001,
"inviteePhone": "13800138001",
"status": "pending",
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 📊 数据字典
### 旅行计划状态
| 状态值 | 描述 |
|--------|------|
| active | 活跃中 |
| completed | 已完成 |
| cancelled | 已取消 |
### 结伴邀请状态
| 状态值 | 描述 |
|--------|------|
| pending | 待接受 |
| accepted | 已接受 |
| rejected | 已拒绝 |
| cancelled | 已取消 |
### 动物认领状态
| 状态值 | 描述 |
|--------|------|
| pending | 待支付 |
| paid | 已支付 |
| active | 认领中 |
| completed | 已完成 |
| cancelled | 已取消 |
### 送花订单状态
| 状态值 | 描述 |
|--------|------|
| pending | 待支付 |
| paid | 已支付 |
| confirmed | 商家已确认 |
| delivering | 配送中 |
| completed | 已完成 |
| cancelled | 已取消 |
### 推广活动状态
| 状态值 | 描述 |
|--------|------|
| active | 进行中 |
| inactive | 未开始 |
| expired | 已结束 |
### 错误代码
| 代码 | 描述 |
|------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 409 | 资源冲突 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
| 503 | 服务不可用 |
## 🔗 API 版本控制
当前API版本为v1，所有接口前缀为`/api/`。
版本更新策略：
- 向后兼容的修改直接更新
- 不兼容的修改创建新版本v2
- 旧版本API保持维护至少6个月
## 📡 接口限流
### 限流策略
- 匿名用户: 60请求/分钟
- 认证用户: 120请求/分钟
- VIP用户: 300请求/分钟
### 限流响应
当超过限流阈值时返回：
```json
{
"code": 429,
"message": "请求过于频繁，请稍后再试",
"retryAfter": 60
}
```
## 🧪 接口测试
### 使用curl测试
```bash
# 微信用户登录
curl -X POST http://localhost:8080/api/auth/wechat-login \
-H "Content-Type: application/json" \
-d '{"code":"wxlogincode123","userInfo":{"nickName":"测试用户","avatarUrl":"https://avatar.url","gender":1}}'
# 获取旅行计划列表
curl -X GET http://localhost:8080/api/travel/plans \
-H "Authorization: Bearer <token>"
```
### 使用Postman测试
1. 导入Postman集合文件
2. 设置环境变量（base_url, token等）
3. 运行测试用例
## 📝 更新日志
### v1.0.0 (2025-09-10)
- 微信用户登录接口
- 旅行结伴管理接口
- 动物认领管理接口
- 送花服务接口
- 推广活动接口
- 基础认证系统
---
*最后更新: 2025年* 📅

466
docs/API接口文档.md Normal file
View File

@@ -0,0 +1,466 @@
# 📚 结伴客API接口文档
## 📋 文档说明
本文档详细描述了结伴客项目的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。
**基础信息：**
- 基础URL：`https://api.jiebanke.com`
- API版本：`v1`
- 数据格式：`JSON`
- 字符编码：`UTF-8`
## 🔐 认证方式
### JWT Token 认证
所有需要认证的API必须在请求头中携带Token：
```http
Authorization: Bearer <your_jwt_token>
```
### Token 获取
通过微信登录接口获取Token，Token有效期为7天。
## 📊 通用响应格式
### 成功响应
```json
{
"code": 200,
"message": "操作成功",
"data": {
// 具体数据内容
}
}
```
### 错误响应
```json
{
"code": 400,
"message": "错误描述",
"error": "详细错误信息"
}
```
### 状态码说明
- `200`: 请求成功
- `400`: 请求参数错误
- `401`: 未授权访问
- `403`: 权限不足
- `404`: 资源不存在
- `500`: 服务器内部错误
## 👥 用户管理模块
### 微信用户登录
**接口地址：** `POST /api/v1/auth/wechat-login`
**接口描述：** 用户通过微信授权登录系统
**请求参数：**
```json
{
"code": "string, required, 微信登录授权码",
"userInfo": {
"nickName": "string, required, 用户昵称",
"avatarUrl": "string, required, 用户头像URL",
"gender": "number, optional, 性别(0:未知,1:男,2:女)",
"province": "string, optional, 省份",
"city": "string, optional, 城市"
}
}
```
**响应示例：**
```json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"openid": "wx1234567890",
"nickname": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"phone": "13800138000",
"isNewUser": false
}
}
}
```
### 获取用户信息
**接口地址：** `GET /api/v1/users/profile`
**接口描述：** 获取当前登录用户的详细信息
**请求头：**
```http
Authorization: Bearer <token>
```
**响应示例：**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"id": 1,
"openid": "wx1234567890",
"nickname": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"birthday": "1990-01-01",
"phone": "13800138000",
"email": "user@jiebanke.com",
"travelCount": 5,
"animalClaimCount": 2,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
}
```
### 更新用户信息
**接口地址：** `PUT /api/v1/users/profile`
**接口描述：** 更新用户个人信息
**请求参数：**
```json
{
"nickname": "string, optional, 用户昵称",
"avatar": "string, optional, 头像URL",
"birthday": "string, optional, 生日(YYYY-MM-DD)",
"phone": "string, optional, 手机号码",
"email": "string, optional, 邮箱地址",
"interests": "array, optional, 兴趣爱好标签"
}
```
## 🧳 旅行结伴模块
### 发布旅行计划
**接口地址：** `POST /api/v1/travel/plans`
**接口描述：** 用户发布新的旅行计划
**请求参数：**
```json
{
"destination": "string, required, 目的地",
"startDate": "string, required, 开始日期(YYYY-MM-DD)",
"endDate": "string, required, 结束日期(YYYY-MM-DD)",
"budget": "number, optional, 预算金额",
"interests": "string, optional, 兴趣偏好",
"description": "string, optional, 行程描述",
"visibility": "string, optional, 可见性(public/friends/private)",
"maxParticipants": "number, optional, 最大参与人数"
}
```
**响应示例：**
```json
{
"code": 200,
"message": "旅行计划发布成功",
"data": {
"id": 1001,
"userId": 1,
"destination": "云南大理",
"startDate": "2024-06-01",
"endDate": "2024-06-07",
"budget": 2000,
"interests": "美食,摄影,文化",
"status": "active",
"participantCount": 1,
"maxParticipants": 4,
"createdAt": "2024-01-01T00:00:00.000Z"
}
}
```
### 获取旅行计划列表
**接口地址：** `GET /api/v1/travel/plans`
**接口描述：** 获取旅行计划列表，支持筛选和分页
**查询参数：**
```
page: number, optional, 页码(默认1)
limit: number, optional, 每页数量(默认10)
destination: string, optional, 目的地筛选
startDate: string, optional, 开始日期筛选
endDate: string, optional, 结束日期筛选
budget: number, optional, 预算筛选
status: string, optional, 状态筛选(active/completed/cancelled)
```
**响应示例：**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"plans": [
{
"id": 1001,
"user": {
"id": 1,
"nickname": "旅行达人",
"avatar": "https://avatar.url"
},
"destination": "云南大理",
"startDate": "2024-06-01",
"endDate": "2024-06-07",
"budget": 2000,
"participantCount": 2,
"maxParticipants": 4,
"status": "active"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 25,
"totalPages": 3
}
}
}
```
### 申请加入旅行计划
**接口地址：** `POST /api/v1/travel/plans/{planId}/join`
**接口描述：** 申请加入指定的旅行计划
**请求参数：**
```json
{
"message": "string, optional, 申请留言"
}
```
## 🐄 动物认领模块
### 获取可认领动物列表
**接口地址：** `GET /api/v1/animals/available`
**接口描述：** 获取可认领的动物列表
**查询参数：**
```
type: string, optional, 动物类型(cow/sheep/pig/chicken)
farmId: number, optional, 农场ID筛选
page: number, optional, 页码
limit: number, optional, 每页数量
```
**响应示例：**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"animals": [
{
"id": 2001,
"name": "小花牛",
"type": "cow",
"age": 6,
"gender": "female",
"description": "温顺可爱的小花牛",
"images": ["https://image1.url", "https://image2.url"],
"price": 1200,
"farm": {
"id": 101,
"name": "阳光农场",
"location": "四川成都"
},
"status": "available"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 15
}
}
}
```
### 认领动物
**接口地址：** `POST /api/v1/animals/{animalId}/claim`
**接口描述：** 认领指定的动物
**请求参数：**
```json
{
"duration": "number, required, 认领时长(月)",
"message": "string, optional, 认领留言"
}
```
### 获取我的认领记录
**接口地址：** `GET /api/v1/animals/my-claims`
**接口描述：** 获取当前用户的动物认领记录
## 🏪 商家服务模块
### 商家注册
**接口地址：** `POST /api/v1/merchants/register`
**接口描述：** 商家用户注册
**请求参数：**
```json
{
"businessName": "string, required, 商家名称",
"businessType": "string, required, 商家类型(flower_shop/farm/activity_organizer)",
"contactName": "string, required, 联系人姓名",
"contactPhone": "string, required, 联系电话",
"businessLicense": "string, required, 营业执照号",
"address": "string, required, 经营地址",
"description": "string, optional, 商家描述"
}
```
### 获取商家产品列表
**接口地址：** `GET /api/v1/merchants/{merchantId}/products`
**接口描述：** 获取指定商家的产品列表
## 📦 订单管理模块
### 创建订单
**接口地址：** `POST /api/v1/orders`
**接口描述：** 创建新订单
**请求参数：**
```json
{
"type": "string, required, 订单类型(animal_claim/product_purchase/activity_booking)",
"items": [
{
"itemId": "number, required, 商品/服务ID",
"quantity": "number, required, 数量",
"price": "number, required, 单价"
}
],
"totalAmount": "number, required, 总金额",
"deliveryAddress": "object, optional, 配送地址信息"
}
```
### 获取订单列表
**接口地址：** `GET /api/v1/orders`
**接口描述：** 获取用户订单列表
**查询参数：**
```
status: string, optional, 订单状态筛选
type: string, optional, 订单类型筛选
page: number, optional, 页码
limit: number, optional, 每页数量
```
## 🎯 活动管理模块
### 获取活动列表
**接口地址：** `GET /api/v1/activities`
**接口描述：** 获取活动列表
**查询参数：**
```
type: string, optional, 活动类型
location: string, optional, 地点筛选
date: string, optional, 日期筛选
status: string, optional, 状态筛选
```
### 报名参加活动
**接口地址：** `POST /api/v1/activities/{activityId}/register`
**接口描述：** 报名参加指定活动
## 💬 消息通知模块
### 获取消息列表
**接口地址：** `GET /api/v1/messages`
**接口描述：** 获取用户消息列表
### 发送消息
**接口地址：** `POST /api/v1/messages`
**接口描述：** 发送消息给其他用户
## 🔧 系统管理模块
### 获取系统配置
**接口地址：** `GET /api/v1/system/config`
**接口描述：** 获取系统配置信息
### 文件上传
**接口地址：** `POST /api/v1/upload`
**接口描述：** 上传文件（图片、文档等）
**请求格式：** `multipart/form-data`
**请求参数：**
```
file: File, required, 上传的文件
type: string, optional, 文件类型(avatar/product/document)
```
## 📱 错误代码参考
| 错误代码 | 错误描述 | 解决方案 |
|---------|---------|---------|
| 400 | 请求参数错误 | 检查请求参数格式和必填项 |
| 401 | 未授权访问 | 检查Token是否有效 |
| 403 | 权限不足 | 检查用户权限 |
| 404 | 资源不存在 | 检查请求的资源ID |
| 409 | 资源冲突 | 检查是否重复操作 |
| 429 | 请求频率限制 | 降低请求频率 |
| 500 | 服务器内部错误 | 联系技术支持 |
## 📞 技术支持
如有API使用问题，请联系技术支持：
- 邮箱：tech-support@jiebanke.com
- 微信群：结伴客开发者群
---
*文档版本：v1.0*
*最后更新：2025年1月*

136
docs/CHANGELOG_JAVA.md
View File

@@ -1,136 +0,0 @@
# 结伴客Java微服务项目更新日志
## [1.0.0] - 2025-09-10
### 🎉 新增功能
- ✅ 完成Java微服务架构重构
- ✅ 实现Eureka服务注册与发现
- ✅ 实现Spring Cloud Gateway API网关
- ✅ 实现认证服务(Auth Service)
- ✅ 实现用户服务(User Service)
- ✅ 实现旅行服务(Travel Service)
- ✅ 实现动物服务(Animal Service)
- ✅ 实现订单服务(Order Service)
- ✅ 实现推广服务(Promotion Service)
- ✅ 实现公共模块(Common Module)
- ✅ 集成Redis缓存
- ✅ 集成RabbitMQ消息队列
- ✅ 实现JWT Token认证
- ✅ 实现RBAC权限控制
- ✅ 实现统一异常处理
- ✅ 实现统一响应格式
- ✅ 实现数据库访问层(MyBatis-Plus)
- ✅ 实现服务间通信(OpenFeign)
- ✅ 实现负载均衡(Ribbon)
- ✅ 实现熔断器(Hystrix)
- ✅ 实现配置中心(Spring Cloud Config)
- ✅ 实现链路追踪(Sleuth + Zipkin)
- ✅ 实现健康检查(Spring Boot Actuator)
- ✅ 实现API文档(Swagger/OpenAPI)
- ✅ 实现Docker容器化部署
- ✅ 实现Docker Compose编排
- ✅ 实现启动脚本和构建脚本
### 📖 文档更新
- ✅ 创建架构设计文档
- ✅ 创建API接口文档
- ✅ 创建数据库设计文档
- ✅ 创建部署指南文档
- ✅ 创建性能优化指南文档
- ✅ 创建开发指南文档
- ✅ 创建更新日志文档
### 🧪 测试覆盖
- ✅ 实现单元测试框架(JUnit 5)
- ✅ 实现Mockito测试框架
- ✅ 实现集成测试
- ✅ 实现API接口测试
### 🛠️ 技术栈
- ✅ Java 17
- ✅ Spring Boot 3.1.0
- ✅ Spring Cloud 2022.0.3
- ✅ MySQL 8.0
- ✅ MyBatis-Plus 3.5.3.1
- ✅ Redis 6.0+
- ✅ RabbitMQ 3.8+
- ✅ Maven 3.6+
- ✅ Docker & Docker Compose
- ✅ JUnit 5 & Mockito
## [0.9.0] - 2024-12-01
### 🎉 Node.js版本
- ✅ 基于Node.js + Express.js的后端实现
- ✅ MySQL数据库设计与实现
- ✅ JWT认证机制
- ✅ RESTful API设计
- ✅ 前后端分离架构
## 项目演进路线图
### 短期目标 (2025 Q4)
- [ ] 完善单元测试和集成测试覆盖率
- [ ] 实现CI/CD自动化部署
- [ ] 增加更多监控指标
- [ ] 优化数据库查询性能
- [ ] 增加缓存策略优化
### 中期目标 (2026 Q1-Q2)
- [ ] 实现Kubernetes部署
- [ ] 增加微服务监控面板
- [ ] 实现分布式事务处理
- [ ] 增加消息队列处理能力
- [ ] 优化API网关性能
### 长期目标 (2026 Q3+)
- [ ] 实现AI智能推荐功能
- [ ] 增加大数据分析平台
- [ ] 实现多语言国际化
- [ ] 增加移动端API支持
- [ ] 实现微服务治理平台
## 版本兼容性说明
### 向后兼容
- ✅ 1.x版本之间保持API向后兼容
- ✅ 数据库结构变更提供迁移脚本
- ✅ 配置文件格式保持兼容
### 升级指南
1. 备份现有数据和配置
2. 阅读版本更新说明
3. 按照升级指南逐步升级
4. 验证功能是否正常
## 已知问题
### 当前版本
- ⚠️ 某些边缘场景下的异常处理需要完善
- ⚠️ 部分API接口的性能有待优化
- ⚠️ 文档示例代码需要进一步完善
### 历史版本
- ⚠️ Node.js版本已不再维护
- ⚠️ 建议升级到Java微服务版本
## 贡献者
### 核心团队
- [@developer1](mailto:developer1@jiebanke.com) - 架构设计、后端开发
- [@developer2](mailto:developer2@jiebanke.com) - 前端开发、UI设计
- [@developer3](mailto:developer3@jiebanke.com) - 数据库设计、运维
### 社区贡献
- [@contributor1](mailto:contributor1@jiebanke.com) - 文档完善
- [@contributor2](mailto:contributor2@jiebanke.com) - Bug修复
## 联系方式
如有任何问题或建议，请联系：
- 📧 邮箱: support@jiebanke.com
- 🌐 官网: https://www.jiebanke.com
- 🐛 Issues: https://github.com/jiebanke/jiebanke/issues
---
*最后更新: 2025年9月10日* 📅

749
docs/DEPLOYMENT.md
View File

@@ -1,749 +0,0 @@
# 📦 部署指南 - 文件同步说明
## 📋 当前部署范围
本文档说明了结伴客项目的文件同步流程。当前部署仅涉及文件同步操作，不包括自动构建、环境配置或服务重启等后续步骤。
注意：本文档适用于需要了解当前部署流程的开发人员和运维人员。请知悉当前部署流程的限制和要求。
## 🛠️ 环境要求
### 系统要求
- **操作系统**: Ubuntu 20.04+ / CentOS 7+ / macOS 10.15+
- **内存**: 最低 2GB，推荐 4GB+
- **存储**: 最低 10GB 可用空间
- **网络**: 稳定的互联网连接
### 软件要求
- **Node.js**: 16.x 或 18.x
- **MySQL**: 8.0+
- **Redis**: 6.0+ (可选)
- **Docker**: 20.10+ (可选)
- **npm**: 8.x+
## 🏗️ 开发环境部署
### 1. 克隆项目
```bash
git clone <repository-url>
cd jiebanke
```
### 2. 安装依赖
```bash
# 安装后端依赖
cd backend
npm install
# 安装前端依赖
cd ../admin-system
npm install
cd ../mini-program
npm install
cd ../website
npm install
```
### 3. 配置环境变量
```bash
# 复制环境变量模板
cp backend/.env.example backend/.env
# 编辑环境变量
vim backend/.env
```
### 4. 启动数据库
```bash
# 使用Docker启动MySQL
cd backend
docker-compose up -d mysql
# 或者使用本地MySQL
mysql -u root -p < scripts/init-database.sql
```
### 5. 启动应用
```bash
# 启动后端服务
cd backend
npm run dev
# 启动后台管理系统 (新终端)
cd admin-system
npm run dev
# 启动官方网站 (新终端)
cd website
npm run dev
```
### 6. 验证部署
- 后端API: https://webapi.jiebanke.com/api/v1/health
- 后台管理: https://admin.jiebanke.com
- 官方网站: https://www.jiebanke.com
## 🧪 测试环境部署
### 1. 服务器准备
```bash
# 登录测试服务器
ssh user@test-server
# 创建项目目录
mkdir -p /opt/jiebanke
cd /opt/jiebanke
```
### 2. 部署脚本
```bash
#!/bin/bash
# deploy-test.sh
# 拉取最新代码
git pull origin develop
# 安装依赖
cd backend && npm install --production
cd ../admin-system && npm install --production && npm run build
cd ../website && npm install --production && npm run build
# 重启服务
pm2 restart all
```
### 3. 环境配置
```bash
# 测试环境变量
cat > /opt/jiebanke/backend/.env << EOF
NODE_ENV=test
DB_HOST=192.168.0.240
DB_PORT=3306
DB_USER=root
DB_PASSWORD=aiotAiot123!
DB_DATABASE=jiebandata_test
JWT_SECRET=your-test-jwt-secret
EOF
```
### 4. 进程管理
```bash
# 使用PM2管理进程
npm install -g pm2
# 启动服务
pm2 start ecosystem.config.js --env test
# 查看状态
pm2 status
```
## 🚀 生产环境部署
### 1. 服务器准备
```bash
# 购买云服务器 (阿里云/腾讯云/AWS)
# 配置安全组: 开放80, 443, 3000, 3306, 6379端口
# 服务器初始化
apt update && apt upgrade -y
apt install -y nginx mysql-server redis-server
```
### 2. 数据库部署
```bash
# 安装MySQL
apt install -y mysql-server
# 安全配置
mysql_secure_installation
# 创建生产数据库
mysql -u root -p -e "CREATE DATABASE jiebandata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# 导入数据
mysql -u root -p jiebandata < scripts/prod-database.sql
```
### 3. 应用部署
```bash
# 创建部署用户
adduser deploy
usermod -aG sudo deploy
# 项目目录
mkdir -p /home/deploy/jiebanke
chown deploy:deploy /home/deploy/jiebanke
```
### 4. 自动化部署脚本
```bash
#!/bin/bash
# deploy-prod.sh
set -e
# 变量配置
APP_NAME="jiebanke"
APP_DIR="/home/deploy/jiebanke"
BRANCH="main"
echo "🚀 开始部署 $APP_NAME..."
# 拉取代码
echo "📦 拉取最新代码..."
cd $APP_DIR
git fetch origin
git checkout $BRANCH
git reset --hard origin/$BRANCH
# 安装依赖
echo "🔧 安装依赖..."
cd backend && npm install --production
cd ../admin-system && npm install --production && npm run build
cd ../website && npm install --production && npm run build
# 数据库迁移
echo "🗄️ 执行数据库迁移..."
cd backend
npm run db:migrate
# 重启服务
echo "🔄 重启服务..."
pm2 reload ecosystem.config.js --env production
# 清理
echo "🧹 清理临时文件..."
npm cache clean --force
echo "✅ 部署完成!"
echo "🌐 应用地址: https://your-domain.com"
```
### 5. Nginx 配置
```nginx
# /etc/nginx/sites-available/jiebanke
server {
listen 80;
server_name your-domain.com;
# 反向代理到后端API
location /api {
proxy_pass http://backend-service:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# 静态资源服务
location / {
root /home/deploy/jiebanke/admin-system/dist;
index index.html;
try_files $uri $uri/ /index.html;
}
}
```
### 6. SSL证书配置
```bash
# 安装Certbot
apt install -y certbot python3-certbot-nginx
# 获取SSL证书
certbot --nginx -d your-domain.com
# 自动续期
certbot renew --dry-run
```
## 📊 监控与日志
### 应用监控
```bash
# 安装PM2监控
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 30
# 监控面板
pm2 monitor
```
### 日志管理
```bash
# 查看实时日志
pm2 logs
# 查看特定应用日志
pm2 logs backend
# 日志文件位置
/root/.pm2/logs/
/var/log/nginx/
/var/log/mysql/
```
### 性能监控
```bash
# 安装监控工具
apt install -y htop iotop nmon
# 监控系统资源
top
htop
# 监控磁盘使用
df -h
```
## 🔒 安全配置
### 防火墙配置
```bash
# 配置UFW防火墙
apt install -y ufw
ufw allow ssh
ufw allow http
ufw allow https
ufw enable
```
### 数据库安全
```bash
# 修改MySQL默认端口
vim /etc/mysql/mysql.conf.d/mysqld.cnf
# port = 3307
# 创建应用专用用户
mysql -u root -p -e "
CREATE USER 'appuser'@'%' IDENTIFIED BY 'strongpassword';
GRANT SELECT, INSERT, UPDATE, DELETE ON jiebandata.* TO 'appuser'@'%';
FLUSH PRIVILEGES;
"
```
### SSH安全
```bash
# 禁用root登录
vim /etc/ssh/sshd_config
# PermitRootLogin no
# 使用密钥认证
# PasswordAuthentication no
# 重启SSH
systemctl restart sshd
```
## 📦 容器化部署
### Docker Compose
```yaml
# docker-compose.prod.yml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- DB_HOST=mysql
- DB_PORT=3306
- DB_USER=root
- DB_PASSWORD=rootpassword
depends_on:
- mysql
mysql:
image: mysql:8.0
environment:
- MYSQL_ROOT_PASSWORD=rootpassword
- MYSQL_DATABASE=jiebandata
volumes:
- mysql_data:/var/lib/mysql
ports:
- "3306:3306"
volumes:
mysql_data:
```
### Kubernetes部署
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: jiebanke-backend
spec:
replicas: 3
template:
spec:
containers:
- name: app
image: jiebanke-backend:latest
ports:
- containerPort: 3000
env:
- name: NODE_ENV
value: "production"
```
## 🚨 故障排除
### 常见问题
1. **端口占用**
```bash
# 查找占用端口的进程
lsof -i :3000
# 杀死进程
kill -9 <PID>
```
2. **权限问题**
```bash
# 修改文件权限
chown -R deploy:deploy /home/deploy/jiebanke
chmod -R 755 /home/deploy/jiebanke
```
3. **数据库连接失败**
```bash
# 检查MySQL服务
systemctl status mysql
# 检查防火墙
ufw status
```
### 日志分析
```bash
# 查看错误日志
tail -f /var/log/nginx/error.log
# 查看应用日志
tail -f /root/.pm2/logs/backend-error.log
# 数据库日志
tail -f /var/log/mysql/error.log
```
## 📞 支持与维护
### 紧急联系人
- **运维团队**: ops@jiebanke.com
- **开发团队**: dev@jiebanke.com
- **值班电话**: +86-138-0013-8000
### 维护窗口
- **常规维护**: 每周四凌晨 2:00-4:00
- **紧急维护**: 随时响应
- **系统监控**: 7x24小时
### 备份策略
```bash
# 数据库备份
mysqldump -u root -p jiebandata > backup-$(date +%Y%m%d).sql
# 文件备份
tar -czf backup-$(date +%Y%m%d).tar.gz /home/deploy/jiebanke
# 上传到云存储
rclone copy backup-* remote:backups/
```
---
*最后更新: 2024年* 📅
# 结伴客项目部署指南
## 概述
n g本文档详细说明了如何将结伴客项目部署到生产环境。项目包含三个主要模块：
1. 后端服务 (backend)
2. 后台管理系统 (admin-system)
3. 官方网站 (website)
注意：微信小程序不需要部署到远程服务器，需要使用微信开发者工具进行构建和上传。
## 部署环境要求
### 服务器要求
- CentOS 7+ (推荐 CentOS 8)
- Node.js 16.x+
- MySQL 8.0+
- Nginx 1.18+
- Docker 和 Docker Compose (可选，用于容器化部署)
### 本地开发环境要求
- Node.js 16.x+
- SSH 客户端
- rsync (用于文件同步)
## 自动部署脚本
项目提供了自动部署脚本，支持 Linux/Mac 和 Windows 系统。
### Linux/Mac 部署脚本
脚本位置：`scripts/deploy.sh`
使用方法：
```bash
# 进入脚本目录
cd scripts
# 给脚本添加执行权限
chmod +x deploy.sh
# 部署所有模块
./deploy.sh all
# 部署指定模块
./deploy.sh backend # 部署后端服务
./deploy.sh admin # 部署后台管理系统
./deploy.sh website # 部署官方网站
./deploy.sh mini-program # 构建微信小程序
```
### Windows PowerShell 部署脚本
脚本位置：`scripts/deploy.ps1`
使用方法：
```powershell
# 进入脚本目录
cd scripts
# 部署所有模块
.\deploy.ps1 all
# 部署指定模块
.\deploy.ps1 backend # 部署后端服务
.\deploy.ps1 admin # 部署后台管理系统
.\deploy.ps1 website # 部署官方网站
```
## 手动部署
### 后端服务部署
1. 构建项目：
```bash
cd backend
npm run build
```
2. 同步文件到服务器：
```bash
rsync -avz --delete \
--exclude node_modules \
--exclude .git \
--exclude logs \
./ root@1.13.156.49:/data/nodejs/jiebanke/
```
3. 在服务器上安装依赖：
```bash
ssh root@1.13.156.49
cd /data/nodejs/jiebanke
npm install --production
```
4. 重启服务：
```bash
# 使用 PM2 管理服务（推荐）
pm2 restart jiebanke-backend
# 或使用 systemd
systemctl restart jiebanke-backend
```
### 后台管理系统部署
1. 构建项目：
```bash
cd admin-system
npm run build
```
2. 同步文件到服务器：
```bash
rsync -avz --delete \
--exclude node_modules \
--exclude .git \
--exclude dist \
./ root@1.13.156.49:/data/vue/jiebanke/
```
3. 在服务器上安装依赖：
```bash
ssh root@1.13.156.49
cd /data/vue/jiebanke
npm install --production
```
### 官方网站部署
1. 同步文件到服务器：
```bash
rsync -avz --delete \
--exclude node_modules \
--exclude .git \
./website/ root@1.13.156.49:/data/website/jiebanke/
```
2. 配置 Nginx 服务器指向该目录。
### 微信小程序构建
微信小程序需要使用微信开发者工具进行构建和上传：
1. 打开微信开发者工具
2. 导入 `mini-program` 目录
3. 点击"上传"按钮
4. 在微信公众平台提交审核
## 容器化部署
项目支持使用 Docker 进行容器化部署。
### 使用 docker-compose 部署
```bash
# 构建并启动所有服务
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs backend
```
### 单独构建镜像
每个模块都可以单独构建 Docker 镜像：
```bash
# 后端服务
cd backend
docker build -t jiebanke/backend .
# 后台管理系统
cd admin-system
docker build -t jiebanke/admin .
# 官方网站
cd website
docker build -t jiebanke/website .
```
## 部署目录结构
远程服务器 CentOS (IP: 1.13.156.49) 上各项目的部署目录如下：
```
/
├── data/
│ ├── nodejs/
│ │ └── jiebanke/ # 后端服务部署目录
│ ├── vue/
│ │ └── jiebanke/ # 后台管理系统部署目录
│ └── website/
│ └── jiebanke/ # 官方网站部署目录
```
## 环境变量配置
每个模块都需要配置相应的环境变量：
### 后端服务
创建 `.env` 文件：
```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=jiebanke
DB_PASSWORD=your_password
DB_NAME=jiebanke
# JWT 密钥
JWT_SECRET=your_jwt_secret_key
# 其他配置...
```
### 后台管理系统
创建 `.env.production` 文件：
```env
VITE_APP_TITLE=结伴客后台管理系统
VITE_API_BASE_URL=https://api.jiebanke.com
VITE_APP_VERSION=v1.0.0
```
## 常见问题和解决方案
### SSH 连接问题
确保本地 SSH 公钥已添加到远程服务器的 `~/.ssh/authorized_keys` 文件中。
### 权限问题
确保部署脚本有执行权限：
```bash
chmod +x scripts/deploy.sh
```
### 文件同步问题
如果 rsync 命令执行失败，请检查：
1. 本地是否安装了 rsync
2. 远程服务器 SSH 连接是否正常
3. 目标目录权限是否正确
## 监控和日志
### 后端服务日志
```bash
# 使用 PM2 查看日志
pm2 logs jiebanke-backend
# 或查看日志文件
tail -f /var/log/jiebanke/backend.log
```
### Nginx 日志
```bash
# 访问日志
tail -f /var/log/nginx/access.log
# 错误日志
tail -f /var/log/nginx/error.log
```
## 回滚方案
如果部署出现问题，可以通过以下方式回滚：
1. 使用 Git 版本回滚：
```bash
git checkout v1.0.0 # 回滚到指定版本
```
2. 使用 Docker 镜像回滚：
```bash
docker-compose down
docker rmi jiebanke/backend:latest
docker pull jiebanke/backend:v1.0.0
docker-compose up -d
```
## 性能优化建议
1. 使用 Nginx 反向代理和缓存
2. 启用 Gzip 压缩
3. 使用 CDN 加速静态资源
4. 数据库查询优化
5. 使用 Redis 缓存热点数据

596
docs/DEPLOYMENT_JAVA.md
View File

@@ -1,596 +0,0 @@
# 📦 结伴客Java微服务部署指南
## 📋 项目概述
本文档详细说明了如何将结伴客Java微服务项目部署到生产环境。项目采用微服务架构，包含多个独立的服务模块。
## 🛠️ 环境要求
### 服务器要求
- **操作系统**: Ubuntu 20.04+ / CentOS 7+ / macOS 10.15+
- **内存**: 最低 4GB，推荐 8GB+
- **存储**: 最低 20GB 可用空间
- **网络**: 稳定的互联网连接
### 软件要求
- **JDK**: Java 17
- **构建工具**: Maven 3.6+
- **数据库**: MySQL 8.0+
- **缓存**: Redis 6.0+
- **消息队列**: RabbitMQ 3.8+
- **容器化**: Docker 20.10+ 和 Docker Compose 1.29+
## 🏗️ 开发环境部署
### 1. 克隆项目
```bash
git clone <repository-url>
cd jiebanke/backend-java
```
### 2. 环境准备
确保已安装Java 17和Maven，并验证安装：
```bash
java -version
mvn -version
```
### 3. 构建项目
```bash
# 清理并构建项目
./build-services.sh
```
### 4. 启动服务
```bash
# 使用Docker Compose启动所有服务
docker-compose up -d
# 或者使用启动脚本启动服务
./start-services.sh
```
### 5. 验证部署
- Eureka Dashboard: http://localhost:8761
- API Gateway: http://localhost:8080
- API文档: http://localhost:8080/doc.html
## 🧪 测试环境部署
### 1. 服务器准备
```bash
# 登录测试服务器
ssh user@test-server
# 创建项目目录
mkdir -p /opt/jiebanke
cd /opt/jiebanke
```
### 2. 部署脚本
```bash
#!/bin/bash
# deploy-test.sh
# 拉取最新代码
git pull origin develop
# 构建项目
cd backend-java
./build-services.sh
# 重启服务
docker-compose down
docker-compose up -d
```
### 3. 环境配置
```bash
# 测试环境变量
cat > /opt/jiebanke/backend-java/.env << EOF
DB_HOST=mysql.jiebanke.com
DB_PORT=3306
DB_USER=root
DB_PASSWORD=testpassword
DB_DATABASE=jiebanke_test
JWT_SECRET=your-test-jwt-secret
EOF
```
## 🚀 生产环境部署
### 1. 服务器准备
```bash
# 购买云服务器 (阿里云/腾讯云/AWS)
# 配置安全组: 开放80, 443, 8761, 8080-8090端口
# 服务器初始化
apt update && apt upgrade -y
apt install -y openjdk-17-jdk maven docker docker-compose
```
### 2. 数据库部署
```bash
# 安装MySQL
apt install -y mysql-server
# 安全配置
mysql_secure_installation
# 创建生产数据库
mysql -u root -p -e "CREATE DATABASE jiebanke CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# 导入数据
mysql -u root -p jiebanke < scripts/init-database.sql
```
### 3. 应用部署
```bash
# 创建部署用户
adduser deploy
usermod -aG docker deploy
# 项目目录
mkdir -p /home/deploy/jiebanke
chown deploy:deploy /home/deploy/jiebanke
```
### 4. 自动化部署脚本
```bash
#!/bin/bash
# deploy-prod.sh
set -e
# 变量配置
APP_NAME="jiebanke"
APP_DIR="/home/deploy/jiebanke"
BRANCH="main"
echo "🚀 开始部署 $APP_NAME..."
# 拉取代码
echo "📦 拉取最新代码..."
cd $APP_DIR
git fetch origin
git checkout $BRANCH
git reset --hard origin/$BRANCH
# 构建项目
echo "🔧 构建项目..."
cd backend-java
./build-services.sh
# 停止当前服务
echo "⏹️ 停止当前服务..."
docker-compose down
# 启动新服务
echo "▶️ 启动新服务..."
docker-compose up -d
echo "✅ 部署完成!"
echo "🌐 Eureka Dashboard: http://your-domain.com:8761"
echo "🌐 API Gateway: http://your-domain.com:8080"
```
### 5. Nginx 配置
```nginx
# /etc/nginx/sites-available/jiebanke
server {
listen 80;
server_name your-domain.com;
# 反向代理到API网关
location / {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
### 6. SSL证书配置
```bash
# 安装Certbot
apt install -y certbot python3-certbot-nginx
# 获取SSL证书
certbot --nginx -d your-domain.com
# 自动续期
certbot renew --dry-run
```
## 📊 监控与日志
### 应用监控
```bash
# 查看Docker容器状态
docker-compose ps
# 查看容器日志
docker-compose logs -f
# 查看特定服务日志
docker-compose logs -f user-service
```
### 日志管理
```bash
# 查看实时日志
docker-compose logs -f
# 查看特定服务日志
docker-compose logs -f auth-service
# 日志文件位置 (Docker容器内)
/var/log/jiebanke/
```
### 性能监控
```bash
# 安装监控工具
apt install -y htop iotop nmon
# 监控系统资源
top
htop
# 监控Docker资源使用
docker stats
# 监控磁盘使用
df -h
```
## 🔒 安全配置
### 防火墙配置
```bash
# 配置UFW防火墙
apt install -y ufw
ufw allow ssh
ufw allow http
ufw allow https
ufw allow 8761
ufw allow 8080
ufw enable
```
### 数据库安全
```bash
# 修改MySQL默认端口
vim /etc/mysql/mysql.conf.d/mysqld.cnf
# port = 3307
# 创建应用专用用户
mysql -u root -p -e "
CREATE USER 'appuser'@'%' IDENTIFIED BY 'strongpassword';
GRANT SELECT, INSERT, UPDATE, DELETE ON jiebanke.* TO 'appuser'@'%';
FLUSH PRIVILEGES;
"
```
### SSH安全
```bash
# 禁用root登录
vim /etc/ssh/sshd_config
# PermitRootLogin no
# 使用密钥认证
# PasswordAuthentication no
# 重启SSH
systemctl restart sshd
```
## 📦 容器化部署
### Docker Compose 配置
```yaml
# docker-compose.yml
version: '3.8'
services:
# MySQL数据库
mysql:
image: mysql:8.0
container_name: jiebanke-mysql
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: jiebanke
ports:
- "3306:3306"
volumes:
- mysql_data:/var/lib/mysql
- ./scripts/init-database.sql:/docker-entrypoint-initdb.d/init-database.sql
networks:
- jiebanke-network
# Redis缓存
redis:
image: redis:6.0
container_name: jiebanke-redis
ports:
- "6379:6379"
networks:
- jiebanke-network
# RabbitMQ消息队列
rabbitmq:
image: rabbitmq:3.8-management
container_name: jiebanke-rabbitmq
ports:
- "5672:5672"
- "15672:15672"
networks:
- jiebanke-network
# Eureka服务注册中心
eureka-server:
build:
context: ./eureka-server
container_name: jiebanke-eureka
ports:
- "8761:8761"
networks:
- jiebanke-network
# API网关
gateway-service:
build:
context: ./gateway-service
container_name: jiebanke-gateway
ports:
- "8080:8080"
networks:
- jiebanke-network
depends_on:
- eureka-server
# 认证服务
auth-service:
build:
context: ./auth-service
container_name: jiebanke-auth
ports:
- "8081:8081"
networks:
- jiebanke-network
depends_on:
- eureka-server
- mysql
# 用户服务
user-service:
build:
context: ./user-service
container_name: jiebanke-user
ports:
- "8082:8082"
networks:
- jiebanke-network
depends_on:
- eureka-server
- mysql
# 旅行服务
travel-service:
build:
context: ./travel-service
container_name: jiebanke-travel
ports:
- "8083:8083"
networks:
- jiebanke-network
depends_on:
- eureka-server
- mysql
# 动物服务
animal-service:
build:
context: ./animal-service
container_name: jiebanke-animal
ports:
- "8084:8084"
networks:
- jiebanke-network
depends_on:
- eureka-server
- mysql
# 订单服务
order-service:
build:
context: ./order-service
container_name: jiebanke-order
ports:
- "8085:8085"
networks:
- jiebanke-network
depends_on:
- eureka-server
- mysql
# 推广服务
promotion-service:
build:
context: ./promotion-service
container_name: jiebanke-promotion
ports:
- "8086:8086"
networks:
- jiebanke-network
depends_on:
- eureka-server
- mysql
volumes:
mysql_data:
networks:
jiebanke-network:
driver: bridge
```
### Kubernetes部署 (可选)
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: jiebanke-eureka
spec:
replicas: 1
selector:
matchLabels:
app: eureka
template:
metadata:
labels:
app: eureka
spec:
containers:
- name: eureka
image: jiebanke/eureka-server:latest
ports:
- containerPort: 8761
---
apiVersion: v1
kind: Service
metadata:
name: eureka-service
spec:
selector:
app: eureka
ports:
- port: 8761
targetPort: 8761
type: ClusterIP
```
## 🚨 故障排除
### 常见问题
1. **端口占用**
```bash
# 查找占用端口的进程
lsof -i :8080
# 杀死进程
kill -9 <PID>
```
2. **权限问题**
```bash
# 修改文件权限
chown -R deploy:deploy /home/deploy/jiebanke
chmod -R 755 /home/deploy/jiebanke
```
3. **数据库连接失败**
```bash
# 检查MySQL服务
systemctl status mysql
# 检查防火墙
ufw status
```
4. **Docker容器问题**
```bash
# 查看容器状态
docker-compose ps
# 查看容器日志
docker-compose logs <service-name>
# 重新构建容器
docker-compose build --no-cache
```
### 日志分析
```bash
# 查看错误日志
docker-compose logs -f --tail 100
# 查看特定服务日志
docker-compose logs -f user-service
# 数据库日志
tail -f /var/log/mysql/error.log
```
## 📞 支持与维护
### 紧急联系人
- **运维团队**: ops@jiebanke.com
- **开发团队**: dev@jiebanke.com
- **值班电话**: +86-138-0013-8000
### 维护窗口
- **常规维护**: 每周四凌晨 2:00-4:00
- **紧急维护**: 随时响应
- **系统监控**: 7x24小时
### 备份策略
```bash
# 数据库备份
mysqldump -u root -p jiebanke > backup-$(date +%Y%m%d).sql
# 文件备份
tar -czf backup-$(date +%Y%m%d).tar.gz /home/deploy/jiebanke
# 上传到云存储
rclone copy backup-* remote:backups/
```
## 🎯 性能优化建议
### JVM调优
```bash
# 在Dockerfile中设置JVM参数
ENV JAVA_OPTS="-Xms512m -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"
```
### 数据库连接池优化
```yaml
# 在application.yml中配置
spring:
datasource:
hikari:
maximum-pool-size: 20
minimum-idle: 5
connection-timeout: 30000
idle-timeout: 600000
max-lifetime: 1800000
```
### Redis连接池优化
```yaml
# 在application.yml中配置
spring:
redis:
lettuce:
pool:
max-active: 20
max-idle: 10
min-idle: 5
max-wait: 2000ms
```
### 负载均衡优化
```yaml
# 在application.yml中配置
ribbon:
ConnectTimeout: 3000
ReadTimeout: 10000
MaxAutoRetriesNextServer: 1
MaxAutoRetries: 0
```
---
*最后更新: 2025年* 📅

404
docs/DEVELOPMENT_GUIDE_JAVA.md
View File

@@ -1,404 +0,0 @@
# 结伴客Java微服务开发指南
## 📋 项目概述
本文档为结伴客Java微服务项目的开发指南，旨在帮助开发者快速上手项目开发、理解项目架构和遵循开发规范。
## 🛠️ 开发环境搭建
### 1. 环境要求
- **JDK**: Java 17
- **构建工具**: Maven 3.6+
- **IDE**: IntelliJ IDEA / Eclipse / VS Code
- **数据库**: MySQL 8.0+
- **缓存**: Redis 6.0+
- **消息队列**: RabbitMQ 3.8+
- **容器化**: Docker 20.10+ 和 Docker Compose 1.29+
### 2. 开发工具安装
#### macOS (使用Homebrew)
```bash
# 安装Java 17
brew install openjdk@17
# 安装Maven
brew install maven
# 安装Docker
brew install docker docker-compose
```
#### Ubuntu/Debian
```bash
# 安装Java 17
sudo apt update
sudo apt install openjdk-17-jdk
# 安装Maven
sudo apt install maven
# 安装Docker
sudo apt install docker docker-compose
```
#### Windows
1. 下载并安装 [JDK 17](https://adoptium.net/)
2. 下载并安装 [Maven](https://maven.apache.org/download.cgi)
3. 下载并安装 [Docker Desktop](https://www.docker.com/products/docker-desktop)
### 3. 验证安装
```bash
java -version
mvn -version
docker --version
docker-compose --version
```
## 🏗️ 项目结构说明
### 根目录结构
```
backend-java/
├── eureka-server/ # 服务注册与发现
├── gateway-service/ # API网关
├── auth-service/ # 认证服务
├── user-service/ # 用户服务
├── travel-service/ # 旅行服务
├── animal-service/ # 动物服务
├── order-service/ # 订单服务
├── promotion-service/ # 推广服务
├── common/ # 公共模块
├── scripts/ # 脚本文件
├── pom.xml # Maven根配置
├── docker-compose.yml # Docker编排文件
├── build-services.sh # 构建脚本
├── start-services.sh # 启动脚本
└── stop-services.sh # 停止脚本
```
### 微服务结构
每个微服务都遵循相同的结构：
```
service-name/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/jiebanke/service/
│ │ │ ├── controller/ # 控制器层
│ │ │ ├── service/ # 业务逻辑层
│ │ │ ├── mapper/ # 数据访问层
│ │ │ ├── entity/ # 实体类
│ │ │ ├── dto/ # 数据传输对象
│ │ │ ├── config/ # 配置类
│ │ │ └── Application.java # 启动类
│ │ └── resources/
│ │ ├── application.yml # 配置文件
│ │ ├── mapper/ # MyBatis映射文件
│ │ └── bootstrap.yml # Bootstrap配置
│ └── test/ # 测试代码
├── pom.xml # Maven配置
└── Dockerfile # Docker配置
```
## 🚀 开发流程
### 1. 克隆项目
```bash
git clone <repository-url>
cd jiebanke/backend-java
```
### 2. 导入项目到IDE
1. 打开IntelliJ IDEA
2. 选择"Open or Import"
3. 选择`backend-java/pom.xml`文件
4. 等待Maven导入依赖
### 3. 配置数据库
在每个服务的`application.yml`中配置数据库连接：
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/jiebanke?useUnicode=true&characterEncoding=utf8&useSSL=false
username: root
password: root
driver-class-name: com.mysql.cj.jdbc.Driver
```
### 4. 启动依赖服务
```bash
# 使用Docker启动MySQL、Redis、RabbitMQ
docker-compose up -d mysql redis rabbitmq
```
### 5. 启动服务
```bash
# 启动Eureka Server
cd eureka-server
mvn spring-boot:run
# 启动其他服务（在新的终端窗口中）
cd ../auth-service
mvn spring-boot:run
# 以此类推启动其他服务...
```
## 📖 代码规范
### 1. 命名规范
- **类名**: 使用大驼峰命名法，如`UserService`
- **方法名**: 使用小驼峰命名法，如`getUserById`
- **变量名**: 使用小驼峰命名法，如`userName`
- **常量名**: 使用大写字母和下划线，如`MAX_SIZE`
### 2. 包命名规范
```
com.jiebanke.{service-name}
├── controller # 控制器层
├── service # 业务逻辑层
├── mapper # 数据访问层
├── entity # 实体类
├── dto # 数据传输对象
├── config # 配置类
├── exception # 异常处理
└── util # 工具类
```
### 3. 注释规范
```java
/**
* 用户服务类
* 提供用户相关的业务逻辑处理
*
* @author 开发者姓名
* @since 1.0.0
*/
@Service
public class UserService {
/**
* 根据用户ID获取用户信息
*
* @param userId 用户ID
* @return 用户信息
* @throws BusinessException 当用户不存在时抛出
*/
public User getUserById(Long userId) {
// 实现代码
}
}
```
### 4. 异常处理规范
```java
@RestController
@RequestMapping("/api/users")
public class UserController {
@Autowired
private UserService userService;
@GetMapping("/{id}")
public ApiResponse<User> getUserById(@PathVariable Long id) {
try {
User user = userService.getUserById(id);
return ApiResponse.success(user);
} catch (BusinessException e) {
return ApiResponse.error(e.getCode(), e.getMessage());
} catch (Exception e) {
return ApiResponse.error(500, "系统错误");
}
}
}
```
## 🧪 测试规范
### 1. 单元测试
```java
@SpringBootTest
class UserServiceTest {
@Autowired
private UserService userService;
@MockBean
private UserMapper userMapper;
@Test
void testGetUserById() {
// Given
Long userId = 1L;
User mockUser = new User();
mockUser.setId(userId);
mockUser.setUsername("test");
when(userMapper.selectById(userId)).thenReturn(mockUser);
// When
User user = userService.getUserById(userId);
// Then
assertNotNull(user);
assertEquals(userId, user.getId());
assertEquals("test", user.getUsername());
}
}
```
### 2. 集成测试
```java
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserControllerIntegrationTest {
@Autowired
private TestRestTemplate restTemplate;
@Test
void testGetUserById() {
// When
ResponseEntity<ApiResponse<User>> response = restTemplate.getForEntity(
"/api/users/1",
new ParameterizedTypeReference<ApiResponse<User>>() {}
);
// Then
assertEquals(HttpStatus.OK, response.getStatusCode());
assertNotNull(response.getBody());
assertEquals(200, response.getBody().getCode());
}
}
```
## 📦 构建与部署
### 1. 本地构建
```bash
# 清理并构建项目
./build-services.sh
# 或者使用Maven命令
mvn clean install
```
### 2. Docker构建
```bash
# 构建Docker镜像
cd user-service
docker build -t jiebanke/user-service .
# 运行Docker容器
docker run -p 8082:8080 jiebanke/user-service
```
### 3. Docker Compose部署
```bash
# 启动所有服务
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
```
## 🔧 调试技巧
### 1. 远程调试
在启动服务时添加调试参数：
```bash
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"
```
### 2. 日志查看
```bash
# 查看实时日志
tail -f logs/application.log
# 查看Docker容器日志
docker-compose logs -f user-service
```
### 3. 性能监控
```bash
# 使用Actuator端点查看健康状态
curl http://localhost:8080/actuator/health
# 查看指标信息
curl http://localhost:8080/actuator/metrics
```
## 🤝 代码贡献
### 1. 分支管理
- `main`: 生产环境分支
- `develop`: 开发环境分支
- `feature/*`: 功能开发分支
- `hotfix/*`: 紧急修复分支
- `release/*`: 发布分支
### 2. 提交规范
```bash
# 提交信息格式
<type>(<scope>): <subject>
# 示例
git commit -m "feat(user): 添加用户注册功能"
git commit -m "fix(order): 修复订单状态更新问题"
git commit -m "docs(readme): 更新README文档"
```
### 3. 代码审查
1. 提交Pull Request
2. 等待团队成员审查
3. 根据反馈修改代码
4. 合并到目标分支
## 🚨 常见问题
### 1. 端口占用问题
```bash
# 查找占用端口的进程
lsof -i :8080
# 杀死进程
kill -9 <PID>
```
### 2. 数据库连接问题
```bash
# 检查MySQL服务
docker-compose ps mysql
# 查看数据库日志
docker-compose logs mysql
```
### 3. 依赖下载失败
```bash
# 清理Maven缓存
mvn clean
# 强制更新依赖
mvn clean install -U
```
## 📚 学习资源
### 1. 官方文档
- [Spring Boot官方文档](https://spring.io/projects/spring-boot)
- [Spring Cloud官方文档](https://spring.io/projects/spring-cloud)
- [MyBatis-Plus官方文档](https://baomidou.com/)
### 2. 技术博客
- [Spring Boot最佳实践](https://www.baeldung.com/spring-boot)
- [微服务架构设计](https://microservices.io/)
### 3. 社区资源
- [Stack Overflow](https://stackoverflow.com/questions/tagged/spring-boot)
- [GitHub Issues](https://github.com/spring-projects/spring-boot/issues)
---
*最后更新: 2025年* 📅

517
docs/PERFORMANCE_OPTIMIZATION_JAVA.md
View File

@@ -1,517 +0,0 @@
# 结伴客Java微服务性能优化指南
## 1. JVM调优
### 1.1 堆内存设置
```
# 堆内存大小设置（根据服务器配置调整）
-Xms1g
-Xmx4g
# 新生代大小设置
-Xmn512m
# Metaspace大小设置
-XX:MetaspaceSize=256m
-XX:MaxMetaspaceSize=512m
```
### 1.2 垃圾回收器选择
```
# G1垃圾回收器（适用于大堆内存）
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200
-XX:G1HeapRegionSize=16m
# 或者ZGC垃圾回收器（适用于低延迟要求）
-XX:+UseZGC
```
## 2. 数据库连接池优化
### 2.1 HikariCP配置（在application.yml中）
```yaml
spring:
datasource:
hikari:
# 连接池大小
maximum-pool-size: 20
# 最小空闲连接数
minimum-idle: 5
# 连接超时时间
connection-timeout: 30000
# 空闲超时时间
idle-timeout: 600000
# 最大生命周期
max-lifetime: 1800000
# 连接测试查询
connection-test-query: SELECT 1
```
## 3. Redis性能优化
### 3.1 Redis连接池配置
```yaml
spring:
redis:
lettuce:
pool:
# 最大连接数
max-active: 50
# 最大空闲连接数
max-idle: 20
# 最小空闲连接数
min-idle: 10
# 获取连接最大等待时间
max-wait: 2000ms
```
### 3.2 Redis序列化优化
```java
@Bean
public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
RedisTemplate<String, Object> template = new RedisTemplate<>();
template.setConnectionFactory(connectionFactory);
// 使用更高效的序列化方式
template.setKeySerializer(new StringRedisSerializer());
template.setValueSerializer(new GenericJackson2JsonRedisSerializer());
template.setHashKeySerializer(new StringRedisSerializer());
template.setHashValueSerializer(new GenericJackson2JsonRedisSerializer());
return template;
}
```
## 4. RabbitMQ性能优化
### 4.1 连接池配置
```yaml
spring:
rabbitmq:
listener:
simple:
# 并发消费者数量
concurrency: 10
# 最大并发消费者数量
max-concurrency: 50
# 每个消费者预取的消息数量
prefetch: 10
```
## 5. Feign客户端优化
### 5.1 Feign配置
```java
@Configuration
public class FeignConfig {
@Bean
public Request.Options options() {
// 连接超时时间和读取超时时间
return new Request.Options(5000, 10000);
}
@Bean
public Retryer retryer() {
// 重试策略
return new Retryer.Default(1000, 2000, 3);
}
@Bean
public Logger.Level feignLoggerLevel() {
return Logger.Level.BASIC;
}
}
```
## 6. 线程池优化
### 6.1 自定义线程池
```java
@Configuration
public class ThreadPoolConfig {
@Bean("taskExecutor")
public ExecutorService taskExecutor() {
return new ThreadPoolExecutor(
20, // 核心线程数
100, // 最大线程数
60L, // 空闲线程存活时间
TimeUnit.SECONDS,
new LinkedBlockingQueue<>(200), // 任务队列
new ThreadFactoryBuilder().setNameFormat("task-pool-%d").build(),
new ThreadPoolExecutor.CallerRunsPolicy() // 拒绝策略
);
}
}
```
## 7. 缓存策略优化
### 7.1 多级缓存设计
```java
@Service
public class UserService {
@Autowired
private RedisTemplate<String, Object> redisTemplate;
// 本地缓存（Caffeine）
private Cache<String, Object> localCache = Caffeine.newBuilder()
.maximumSize(10000)
.expireAfterWrite(10, TimeUnit.MINUTES)
.build();
public User getUserById(Long userId) {
// 1. 先查本地缓存
User user = (User) localCache.getIfPresent("user:" + userId);
if (user != null) {
return user;
}
// 2. 再查Redis缓存
user = (User) redisTemplate.opsForValue().get("user:" + userId);
if (user != null) {
localCache.put("user:" + userId, user);
return user;
}
// 3. 最后查数据库
user = userMapper.selectById(userId);
if (user != null) {
redisTemplate.opsForValue().set("user:" + userId, user, 30, TimeUnit.MINUTES);
localCache.put("user:" + userId, user);
}
return user;
}
}
```
### 7.2 缓存注解使用
```java
@Service
public class TravelService {
@Cacheable(value = "travelPlans", key = "#userId")
public List<TravelPlan> getTravelPlansByUserId(Long userId) {
return travelPlanMapper.selectByUserId(userId);
}
@CacheEvict(value = "travelPlans", key = "#travelPlan.userId")
public void createTravelPlan(TravelPlan travelPlan) {
travelPlanMapper.insert(travelPlan);
}
@CacheEvict(value = "travelPlans", key = "#travelPlan.userId")
public void updateTravelPlan(TravelPlan travelPlan) {
travelPlanMapper.updateById(travelPlan);
}
}
```
## 8. 数据库查询优化
### 8.1 MyBatis-Plus分页优化
```java
@Configuration
public class MybatisPlusConfig {
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
// 分页插件
interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
// 乐观锁插件
interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
// 性能分析插件（开发环境使用）
if (environment.acceptsProfiles(Profiles.of("dev"))) {
interceptor.addInnerInterceptor(new BlockAttackInnerInterceptor());
}
return interceptor;
}
}
```
### 8.2 索引优化建议
```sql
-- 用户表索引优化
CREATE INDEX idx_user_username ON users(username);
CREATE INDEX idx_user_email ON users(email);
CREATE INDEX idx_user_phone ON users(phone);
CREATE INDEX idx_user_status ON users(status);
-- 旅行表索引优化
CREATE INDEX idx_travel_user_id ON travel_plans(user_id);
CREATE INDEX idx_travel_destination ON travel_plans(destination);
CREATE INDEX idx_travel_start_date ON travel_plans(start_date);
CREATE INDEX idx_travel_status ON travel_plans(status);
-- 动物表索引优化
CREATE INDEX idx_animal_merchant_id ON animals(merchant_id);
CREATE INDEX idx_animal_species ON animals(species);
CREATE INDEX idx_animal_status ON animals(status);
-- 订单表索引优化
CREATE INDEX idx_order_user_id ON orders(user_id);
CREATE INDEX idx_order_status ON orders(status);
CREATE INDEX idx_order_created_at ON orders(created_at);
-- 推广活动表索引优化
CREATE INDEX idx_promotion_status ON promotion_activities(status);
CREATE INDEX idx_promotion_start_time ON promotion_activities(start_time);
```
## 9. API网关优化
### 9.1 限流配置
```yaml
spring:
cloud:
gateway:
routes:
- id: user-service
uri: lb://user-service
predicates:
- Path=/api/users/**
filters:
- name: RequestRateLimiter
args:
redis-rate-limiter.replenishRate: 50
redis-rate-limiter.burstCapacity: 100
- id: travel-service
uri: lb://travel-service
predicates:
- Path=/api/travel/**
filters:
- name: RequestRateLimiter
args:
redis-rate-limiter.replenishRate: 30
redis-rate-limiter.burstCapacity: 60
```
### 9.2 熔断器配置
```yaml
resilience4j:
circuitbreaker:
instances:
userService:
registerHealthIndicator: true
slidingWindowSize: 10
minimumNumberOfCalls: 5
permittedNumberOfCallsInHalfOpenState: 3
automaticTransitionFromOpenToHalfOpenEnabled: true
waitDurationInOpenState: 10s
failureRateThreshold: 50
eventConsumerBufferSize: 10
```
## 10. 监控和日志优化
### 10.1 Actuator配置
```yaml
management:
endpoints:
web:
exposure:
include: health,info,metrics,httptrace,prometheus
endpoint:
health:
show-details: always
metrics:
export:
prometheus:
enabled: true
```
### 10.2 日志配置优化
```yaml
logging:
level:
com.jiebanke: INFO
org.springframework: WARN
org.mybatis: WARN
org.apache.http: DEBUG
pattern:
console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
file:
name: logs/application.log
```
### 10.3 日志文件配置
```xml
<!-- logback-spring.xml -->
<configuration>
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>logs/application.log</file>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>logs/application.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
<timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
<maxFileSize>100MB</maxFileSize>
</timeBasedFileNamingAndTriggeringPolicy>
<maxHistory>30</maxHistory>
<totalSizeCap>10GB</totalSizeCap>
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<root level="INFO">
<appender-ref ref="FILE" />
</root>
</configuration>
```
## 11. Docker部署优化
### 11.1 JVM参数优化（Dockerfile）
```dockerfile
FROM openjdk:17-jdk-slim
LABEL maintainer="jiebanke-team"
WORKDIR /app
COPY target/*.jar app.jar
# JVM参数优化
ENV JAVA_OPTS="-Xms1g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+UseContainerSupport"
EXPOSE 8080
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]
```
### 11.2 Docker Compose优化
```yaml
version: '3.8'
services:
user-service:
build:
context: ./user-service
container_name: jiebanke-user
ports:
- "8082:8080"
environment:
- SPRING_PROFILES_ACTIVE=prod
- JAVA_OPTS=-Xms1g -Xmx2g
deploy:
resources:
limits:
memory: 2G
reservations:
memory: 1G
networks:
- jiebanke-network
depends_on:
- eureka-server
- mysql
- redis
```
## 12. 负载均衡优化
### 12.1 Ribbon配置
```yaml
ribbon:
# 连接超时时间
ConnectTimeout: 3000
# 读取超时时间
ReadTimeout: 10000
# 是否启用重试
OkToRetryOnAllOperations: false
# 切换实例重试次数
MaxAutoRetriesNextServer: 1
# 当前实例重试次数
MaxAutoRetries: 0
```
### 12.2 LoadBalancer配置
```yaml
spring:
cloud:
loadbalancer:
retry:
enabled: true
cache:
enabled: true
ttl: 30s
```
## 13. 微服务间通信优化
### 13.1 OpenFeign配置
```yaml
feign:
client:
config:
default:
connectTimeout: 5000
readTimeout: 10000
compression:
request:
enabled: true
mime-types: text/xml,application/xml,application/json
min-request-size: 2048
response:
enabled: true
httpclient:
enabled: true
max-connections: 200
max-connections-per-route: 50
```
## 14. 性能测试建议
### 14.1 压力测试工具
- JMeter：用于API接口压力测试
- wrk：用于HTTP基准测试
- ab (Apache Bench)：简单的HTTP性能测试工具
- Gatling：高性能负载测试工具
### 14.2 监控工具
- Prometheus + Grafana：系统指标监控
- ELK Stack：日志分析
- SkyWalking：分布式追踪
- Zipkin：服务调用链追踪
### 14.3 性能测试脚本示例
```bash
# 使用wrk进行压力测试
wrk -t12 -c400 -d30s http://localhost:8080/api/users/profile
# 使用ab进行基准测试
ab -n 10000 -c 100 http://localhost:8080/api/users/profile
```
## 15. 性能调优最佳实践
### 15.1 代码层面优化
1. 避免在循环中执行数据库查询
2. 使用批量操作减少数据库交互
3. 合理使用缓存减少重复计算
4. 优化算法复杂度
5. 减少对象创建和垃圾回收
### 15.2 数据库层面优化
1. 合理设计索引
2. 避免全表扫描
3. 使用分页查询
4. 优化SQL语句
5. 定期分析慢查询日志
### 15.3 系统层面优化
1. 合理配置JVM参数
2. 优化操作系统内核参数
3. 使用SSD存储提升IO性能
4. 合理配置网络参数
5. 使用CDN加速静态资源
通过以上优化措施，可以显著提升结伴客Java微服务的性能和稳定性。
---
*最后更新: 2025年* 📅

104
docs/README.md
View File

@@ -1,104 +0,0 @@
# 结伴客项目文档目录
## 核心文档
### 产品需求
- [产品需求文档](./requirements.md) - 小程序核心功能需求
- [官网需求文档](./website_requirements.md) - 官方网站产品需求
### 技术文档
- [系统架构文档](./architecture.md) - 整体技术架构设计
- [详细设计文档](./detailed_design.md) - 数据库和API详细设计
- [API接口文档](./API_DOCS.md) - 完整的API接口说明
- [数据库设计](./database-design.md) - 数据库表结构和关系
### 开发文档
- [开发计划](./development_plan.md) - 项目开发排期和任务分解
- [部署指南](./DEPLOYMENT.md) - 系统部署和运维指南
- [开发规范](./DEVELOPMENT_GUIDE.md) - 代码规范和开发流程
### 其他文档
- [测试用例](./TEST_CASES.md) - 功能测试用例
- [用户手册](./USER_MANUAL.md) - 最终用户使用指南
- [常见问题](./FAQ.md) - 常见问题解答
## 文档维护
所有文档均使用Markdown格式编写，保持实时更新。建议阅读顺序：
1. 产品需求文档 → 2. 系统架构文档 → 3. 详细设计文档 → 4. API接口文档
## 版本控制
文档版本与代码版本保持一致，重大变更需要更新版本历史记录。
## 📚 文档列表
### Java微服务版本文档
| 文档 | 描述 | 最后更新 |
|------|------|----------|
| [架构设计文档](architecture-java.md) | 系统整体架构设计 | 2025-09-10 |
| [API接口文档](API_DOCS_JAVA.md) | 所有API接口详细说明 | 2025-09-10 |
| [数据库设计文档](database-design-java.md) | 数据库表结构和关系设计 | 2025-09-10 |
| [部署指南](DEPLOYMENT_JAVA.md) | 项目部署和运维指南 | 2025-09-10 |
| [性能优化指南](PERFORMANCE_OPTIMIZATION_JAVA.md) | 系统性能优化建议 | 2025-09-10 |
| [开发指南](DEVELOPMENT_GUIDE_JAVA.md) | 开发者入门和开发规范 | 2025-09-10 |
| [更新日志](CHANGELOG_JAVA.md) | 版本更新和变更记录 | 2025-09-10 |
### Node.js版本文档 (已废弃)
| 文档 | 描述 | 最后更新 |
|------|------|----------|
| [架构设计文档](architecture.md) | 系统整体架构设计 | 2024-01-01 |
| [API接口文档](API_DOCS.md) | 所有API接口详细说明 | 2024-01-01 |
| [数据库设计文档](database-design.md) | 数据库表结构和关系设计 | 2024-01-01 |
| [部署指南](DEPLOYMENT.md) | 项目部署和运维指南 | 2024-01-01 |
## 🗂️ 文档分类
### 系统设计文档
- [架构设计文档](architecture-java.md) - 系统整体架构、技术选型、组件关系
- [数据库设计文档](database-design-java.md) - 数据库表结构、ER图、索引设计
### 开发文档
- [API接口文档](API_DOCS_JAVA.md) - RESTful API详细说明、请求响应格式
- [开发指南](DEVELOPMENT_GUIDE_JAVA.md) - 开发环境搭建、编码规范、测试指南
### 运维文档
- [部署指南](DEPLOYMENT_JAVA.md) - 环境要求、部署步骤、容器化部署
- [性能优化指南](PERFORMANCE_OPTIMIZATION_JAVA.md) - JVM调优、数据库优化、缓存策略
### 项目管理文档
- [更新日志](CHANGELOG_JAVA.md) - 版本变更记录、功能新增、问题修复
## 🚀 快速开始
### 1. 了解系统架构
首先阅读 [架构设计文档](architecture-java.md) 了解系统整体设计和技术栈。
### 2. 搭建开发环境
按照 [开发指南](DEVELOPMENT_GUIDE_JAVA.md) 搭建本地开发环境。
### 3. 学习API接口
查看 [API接口文档](API_DOCS_JAVA.md) 了解系统提供的所有接口。
### 4. 部署系统
参考 [部署指南](DEPLOYMENT_JAVA.md) 将系统部署到服务器。
## 📝 文档维护
### 更新流程
1. 修改相应文档文件
2. 提交Pull Request
3. 团队审查后合并
### 贡献指南
欢迎提交Issue和Pull Request来改进文档。
## 📞 联系我们
- 📧 邮箱: support@jiebanke.com
- 🌐 官网: https://www.jiebanke.com
---
*最后更新: 2025年9月10日* 📅

484
docs/admin-design.md
View File

@@ -1,484 +0,0 @@
# 结伴客系统后台管理设计文档
## 1. 概述
### 1.1 设计目标
为结伴客系统提供功能完善、安全可靠的后台管理系统，支持系统管理员对用户、内容、商家、数据等进行全面管理。
### 1.2 设计原则
- **安全性**: 采用RBAC权限控制，操作日志记录，敏感操作二次确认
- **易用性**: 界面简洁直观，操作流程清晰
- **扩展性**: 模块化设计，支持功能扩展
- **性能**: 支持大数据量操作，响应快速
## 2. 系统架构
### 2.1 技术栈
- **前端**: Vue 3 + TypeScript + Ant Design Vue
- **后端**: Node.js + Express + MySQL + Redis
- **认证**: JWT + RBAC权限控制
- **部署**: Docker + Nginx
### 2.2 模块划分
```
后台管理系统
├── 认证模块
├── 用户管理模块
├── 内容管理模块
├── 商家管理模块
├── 数据统计模块
├── 权限管理模块
├── 系统配置模块
└── 操作日志模块
```
## 3. 功能模块设计
### 3.1 认证模块
#### 3.1.1 登录功能
- 管理员账号密码登录
- JWT Token认证
- 登录状态保持
- 安全退出
#### 3.1.2 权限验证
- 接口级别权限控制
- 页面级别权限控制
- 按钮级别权限控制
### 3.2 用户管理模块
#### 3.2.1 用户列表
- 分页显示用户信息
- 搜索过滤功能
- 用户状态管理
- 用户详情查看
#### 3.2.2 用户操作
- 启用/禁用用户
- 重置用户密码
- 查看用户行为日志
### 3.3 内容管理模块
#### 3.3.1 内容审核
- 待审核内容列表
- 内容详情查看
- 审核通过/拒绝
- 批量审核操作
#### 3.3.2 内容管理
- 已发布内容管理
- 违规内容处理
- 内容统计分析
### 3.4 商家管理模块
#### 3.4.1 商家审核
- 商家入驻申请列表
- 商家资质审核
- 审核结果通知
#### 3.4.2 商家管理
- 商家信息管理
- 商家状态控制
- 商家数据统计
### 3.5 数据统计模块
#### 3.5.1 系统概览
- 用户统计数据
- 订单统计数据
- 内容统计数据
- 商家统计数据
#### 3.5.2 趋势分析
- 用户增长趋势
- 订单趋势分析
- 收入趋势分析
- 数据图表展示
#### 3.5.3 数据导出
- CSV格式导出
- Excel格式导出
- 自定义时间范围
### 3.6 权限管理模块
#### 3.6.1 角色管理
- 角色列表查看
- 角色创建/编辑
- 角色权限分配
- 角色删除
#### 3.6.2 权限管理
- 权限列表查看
- 权限分组管理
- 权限分配
#### 3.6.3 用户角色分配
- 用户角色管理
- 批量角色分配
- 角色权限验证
### 3.7 系统配置模块
#### 3.7.1 基础配置
- 网站基本信息
- 系统参数配置
- 上传文件配置
- 邮件短信配置
#### 3.7.2 配置管理
- 配置项列表
- 配置值修改
- 配置分组管理
- 配置版本控制
### 3.8 操作日志模块
#### 3.8.1 日志查询
- 操作日志列表
- 高级搜索功能
- 日志详情查看
#### 3.8.2 日志分析
- 操作频率统计
- 异常操作检测
- 安全审计报告
## 4. 数据库设计
### 4.1 核心表结构
#### 4.1.1 管理员表 (admins)
```sql
CREATE TABLE admins (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(50) NOT NULL UNIQUE,
password VARCHAR(255) NOT NULL,
email VARCHAR(100),
real_name VARCHAR(50),
avatar VARCHAR(255),
status ENUM('active', 'inactive') DEFAULT 'active',
last_login_at DATETIME,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```
#### 4.1.2 角色表 (roles)
```sql
CREATE TABLE roles (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(50) NOT NULL UNIQUE,
description VARCHAR(255),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```
#### 4.1.3 权限表 (permissions)
```sql
CREATE TABLE permissions (
id VARCHAR(50) PRIMARY KEY,
name VARCHAR(50) NOT NULL,
description VARCHAR(255),
category VARCHAR(50),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```
#### 4.1.4 角色权限表 (role_permissions)
```sql
CREATE TABLE role_permissions (
role_id BIGINT NOT NULL,
permission_id VARCHAR(50) NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (role_id, permission_id),
FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE,
FOREIGN KEY (permission_id) REFERENCES permissions(id) ON DELETE CASCADE
);
```
#### 4.1.5 管理员角色表 (admin_roles)
```sql
CREATE TABLE admin_roles (
admin_id BIGINT NOT NULL,
role_id BIGINT NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (admin_id, role_id),
FOREIGN KEY (admin_id) REFERENCES admins(id) ON DELETE CASCADE,
FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE
);
```
#### 4.1.6 管理员操作日志表 (admin_operation_logs)
```sql
CREATE TABLE admin_operation_logs (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
admin_id BIGINT NOT NULL,
admin_name VARCHAR(50) NOT NULL,
module VARCHAR(50) NOT NULL,
operation VARCHAR(100) NOT NULL,
target_id VARCHAR(100),
target_type VARCHAR(50),
request_method VARCHAR(10),
request_url VARCHAR(500),
request_params TEXT,
ip_address VARCHAR(45),
user_agent VARCHAR(500),
status ENUM('success', 'failed') NOT NULL,
error_message TEXT,
execution_time INT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX idx_admin_id (admin_id),
INDEX idx_module (module),
INDEX idx_operation (operation),
INDEX idx_status (status),
INDEX idx_created_at (created_at)
);
```
#### 4.1.7 系统配置表 (system_configs)
```sql
CREATE TABLE system_configs (
id VARCHAR(50) PRIMARY KEY,
name VARCHAR(100) NOT NULL,
value TEXT NOT NULL,
type ENUM('string', 'number', 'boolean', 'text', 'json') DEFAULT 'string',
group_name VARCHAR(50) DEFAULT 'general',
description VARCHAR(255),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_group (group_name)
);
```
### 4.2 数据关系图
```mermaid
erDiagram
admins ||--o{ admin_roles : has
roles ||--o{ admin_roles : assigned
roles ||--o{ role_permissions : has
permissions ||--o{ role_permissions : included
admins ||--o{ audit_logs : creates
admins {
bigint id
varchar username
varchar password
varchar email
varchar real_name
varchar avatar
enum status
datetime last_login_at
datetime created_at
datetime updated_at
}
roles {
bigint id
varchar name
varchar description
datetime created_at
datetime updated_at
}
permissions {
varchar id
varchar name
varchar description
varchar category
datetime created_at
}
```
## 5. API接口设计
### 5.1 认证接口
- `POST /admin/auth/login` - 管理员登录
- `GET /admin/auth/me` - 获取当前管理员信息
- `POST /admin/auth/logout` - 退出登录
- `POST /admin/auth/refresh` - 刷新Token
### 5.2 用户管理接口
- `GET /admin/users` - 获取用户列表
- `GET /admin/users/{id}` - 获取用户详情
- `PUT /admin/users/{id}/status` - 更新用户状态
### 5.3 内容管理接口
- `GET /admin/contents` - 获取内容列表
- `GET /admin/contents/{id}` - 获取内容详情
- `PUT /admin/contents/{id}/review` - 审核内容
- `POST /admin/contents/batch-review` - 批量审核内容
### 5.4 商家管理接口
- `GET /admin/merchant-applications` - 获取商家申请列表
- `PUT /admin/merchant-applications/{id}/review` - 审核商家申请
- `GET /admin/merchants` - 获取商家列表
- `PUT /admin/merchants/{id}/status` - 更新商家状态
### 5.5 数据统计接口
- `GET /admin/statistics` - 获取系统统计数据
- `GET /admin/statistics/trend` - 获取数据趋势
- `GET /admin/export/{type}` - 导出数据
### 5.6 权限管理接口
- `GET /admin/roles` - 获取角色列表
- `POST /admin/roles` - 创建角色
- `PUT /admin/roles/{id}` - 更新角色
- `DELETE /admin/roles/{id}` - 删除角色
- `GET /admin/permissions` - 获取权限列表
- `POST /admin/users/{userId}/roles` - 分配用户角色
### 5.7 系统配置接口
- `GET /admin/system-configs` - 获取系统配置
- `PUT /admin/system-configs/{id}` - 更新系统配置
- `POST /admin/system-configs/batch-update` - 批量更新配置
### 5.8 操作日志接口
- `GET /admin/operation-logs` - 获取操作日志列表
- `GET /admin/operation-logs/{id}` - 获取操作日志详情
- `GET /admin/operation-logs/export` - 导出操作日志
- `GET /admin/operation-logs/statistics` - 获取操作统计
## 6. 安全设计
### 6.1 认证安全
- JWT Token认证机制
- Token过期时间设置
- 密码加密存储（BCrypt）
- 登录失败次数限制
### 6.2 权限安全
- RBAC权限控制模型
- 接口级别权限验证
- 数据访问权限控制
### 6.3 操作安全
- 敏感操作二次确认
- 操作日志记录
- IP地址限制
- 操作频率限制
### 6.4 数据安全
- SQL注入防护
- XSS攻击防护
- CSRF攻击防护
- 数据加密传输（HTTPS）
## 7. 性能优化
### 7.1 数据库优化
- 合理的索引设计
- 查询性能优化
- 分页查询支持
- 数据库连接池
### 7.2 缓存优化
- Redis缓存应用
- 热点数据缓存
- 缓存更新策略
- 缓存失效机制
### 7.3 接口优化
- 接口响应时间优化
- 批量操作支持
- 异步处理机制
- 数据压缩传输
## 8. 部署方案
### 8.1 环境划分
- 开发环境（Development）
- 测试环境（Testing）
- 预生产环境（Staging）
- 生产环境（Production）
### 8.2 部署架构
```
负载均衡 (Nginx)
├── 后台管理前端 (Vue)
├── 后端API服务 (Spring Boot)
├── 数据库集群 (MySQL)
└── 缓存集群 (Redis)
```
### 8.3 监控告警
- 应用性能监控
- 错误日志监控
- 数据库监控
- 系统资源监控
## 9. 测试策略
### 9.1 单元测试
- 业务逻辑测试
- 服务层测试
- 工具类测试
### 9.2 集成测试
- API接口测试
- 数据库操作测试
- 权限验证测试
### 9.3 性能测试
- 并发用户测试
- 响应时间测试
- 负载能力测试
### 9.4 安全测试
- 权限绕过测试
- SQL注入测试
- XSS攻击测试
## 10. 维护计划
### 10.1 日常维护
- 日志文件清理
- 数据库备份
- 系统监控
- 性能优化
### 10.2 版本发布
- 版本控制策略
- 发布流程规范
- 回滚机制
- 版本兼容性
### 10.3 故障处理
- 故障响应流程
- 问题排查指南
- 恢复方案
- 事后总结
## 附录
### A. 权限列表
| 权限ID | 权限名称 | 描述 | 分类 |
|--------|----------|------|------|
| user:view | 查看用户 | 允许查看用户列表和详情 | 用户管理 |
| user:manage | 管理用户 | 允许修改用户状态和信息 | 用户管理 |
| content:review | 审核内容 | 允许审核用户发布的内容 | 内容管理 |
| content:publish | 发布内容 | 允许发布系统公告和内容 | 内容管理 |
| data:view | 查看数据 | 允许查看系统统计数据 | 数据统计 |
| data:export | 导出数据 | 允许导出系统数据 | 数据统计 |
| role:manage | 管理角色 | 允许管理角色和权限 | 权限管理 |
| merchant:approve | 审核商家 | 允许审核商家入驻申请 | 商家管理 |
| system:config | 系统配置 | 允许修改系统配置参数 | 系统管理 |
| audit:view | 查看日志 | 允许查看操作日志 | 日志管理 |
| audit:export | 导出日志 | 允许导出操作日志 | 日志管理 |
| audit:statistics | 日志统计 | 允许查看操作日志统计 | 日志管理 |
### B. 错误码说明
| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 成功 | 操作成功 |
| 201 | 创建成功 | 资源创建成功 |
| 400 | 请求错误 | 检查请求参数 |
| 401 | 未授权 | 需要登录认证 |
| 403 | 禁止访问 | 权限不足 |
| 404 | 资源不存在 | 检查资源ID |
| 409 | 资源冲突 | 资源已存在 |
| 429 | 请求过多 | 降低请求频率 |
| 500 | 服务器错误 | 联系管理员 |
### C. 版本历史
| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2025-01-01 | 初始版本发布 |
| v1.1 | 2025-02-01 | 新增权限管理功能 |
| v1.2 | 2025-03-01 | 优化数据统计功能 |

3433
docs/api-documentation.md
View File

File diff suppressed because it is too large Load Diff

505
docs/architecture-java.md
View File

@@ -1,505 +0,0 @@
# 🏗️ 结伴客Java微服务架构文档
## 📋 项目概述
结伴客项目是一个综合性的管理系统，包含后台管理、微信小程序和官网三个主要模块。本项目采用Java微服务架构，基于Spring Boot和Spring Cloud实现。
## 🎯 技术栈
### 后端技术栈
- **运行时**: Java 17
- **框架**: Spring Boot 3.1.0 + Spring Cloud 2022.0.3
- **服务注册与发现**: Eureka Server
- **API网关**: Spring Cloud Gateway
- **数据库**: MySQL 8.0
- **ORM**: MyBatis-Plus 3.5.3.1
- **认证**: JWT + Spring Security
- **缓存**: Redis 6.0+
- **消息队列**: RabbitMQ 3.8+
- **构建工具**: Maven 3.6+
### 前端技术栈
- **后台管理系统**: Vue 3 + Element Plus
- **微信小程序**: 原生小程序 + Vant Weapp
- **官方网站**: Vue 3 + Vue Router
### 开发工具
- **包管理**: npm
- **容器化**: Docker + Docker Compose
- **代码质量**: Checkstyle + PMD
- **测试**: JUnit 5 + Mockito
## 🏢 系统架构
```mermaid
graph TB
subgraph "前端应用"
A[后台管理系统]
B[微信小程序]
C[官方网站]
end
subgraph "API网关层"
D[Spring Cloud Gateway]
end
subgraph "微服务层"
E[Eureka Server]
F[Auth Service]
G[User Service]
H[Travel Service]
I[Animal Service]
J[Order Service]
K[Promotion Service]
end
subgraph "数据层"
L[MySQL]
M[Redis]
N[RabbitMQ]
end
A --> D
B --> D
C --> D
D --> F
D --> G
D --> H
D --> I
D --> J
D --> K
F --> L
G --> L
H --> L
I --> L
J --> L
K --> L
F --> M
G --> M
H --> M
I --> M
J --> M
K --> M
F --> N
G --> N
H --> N
I --> N
J --> N
K --> N
E --> F
E --> G
E --> H
E --> I
E --> J
E --> K
```
## 🗄️ 数据库设计
### 核心表结构设计
```mermaid
erDiagram
USERS ||--o{ TRAVEL_PLANS : creates
USERS ||--o{ ANIMAL_CLAIMS : claims
USERS ||--o{ FLOWER_ORDERS : places
MERCHANTS ||--o{ ANIMALS : owns
MERCHANTS ||--o{ FLOWER_PRODUCTS : sells
ANIMALS ||--o{ ANIMAL_CLAIMS : claimed_by
FLOWER_PRODUCTS ||--o{ FLOWER_ORDERS : ordered
TRAVEL_PLANS ||--o{ TRAVEL_INVITATIONS : has
ADMINS ||--o{ ADMIN_LOGS : manages
USERS {
bigint id PK
varchar username
varchar password
varchar email
varchar phone
varchar real_name
varchar id_card
varchar status
decimal balance
int credit_score
timestamp last_login
timestamp created_at
timestamp updated_at
}
ADMINS {
bigint id PK
varchar username
varchar password
varchar email
varchar role
varchar status
timestamp last_login
timestamp created_at
timestamp updated_at
}
MERCHANTS {
bigint id PK
bigint user_id FK
varchar merchant_type
varchar business_name
varchar business_license
varchar contact_person
varchar contact_phone
varchar address
varchar description
varchar status
timestamp created_at
timestamp updated_at
}
TRAVEL_PLANS {
bigint id PK
bigint user_id FK
varchar destination
date start_date
date end_date
decimal budget
text interests
text description
varchar visibility
varchar status
timestamp created_at
timestamp updated_at
}
ANIMALS {
bigint id PK
bigint merchant_id FK
varchar name
varchar species
varchar breed
date birth_date
text personality
varchar farm_location
decimal price
int claim_count
varchar status
timestamp created_at
timestamp updated_at
}
ANIMAL_CLAIMS {
bigint id PK
bigint user_id FK
bigint animal_id FK
int duration
decimal total_amount
varchar status
date start_date
date end_date
timestamp created_at
timestamp updated_at
}
FLOWER_PRODUCTS {
bigint id PK
bigint merchant_id FK
varchar name
text description
decimal price
decimal original_price
json images
varchar category
int sales_count
decimal rating
varchar status
timestamp created_at
timestamp updated_at
}
FLOWER_ORDERS {
bigint id PK
bigint user_id FK
bigint product_id FK
varchar order_number
int quantity
decimal total_amount
json recipient_info
date delivery_date
varchar message
varchar status
timestamp created_at
timestamp updated_at
}
PROMOTION_ACTIVITIES {
bigint id PK
varchar name
text description
varchar reward_type
decimal reward_amount
varchar status
timestamp start_time
timestamp end_time
int max_participants
int current_participants
timestamp created_at
timestamp updated_at
}
REWARD_RECORDS {
bigint id PK
bigint user_id
varchar user_name
varchar user_phone
bigint activity_id
varchar activity_name
varchar reward_type
decimal reward_amount
varchar status
timestamp issued_at
timestamp created_at
}
```
## 🌐 环境配置
### 开发环境 (Development)
```env
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_DATABASE=jiebanke
NODE_ENV=development
```
### 测试环境 (Test)
```env
DB_HOST=192.168.0.240
DB_PORT=3306
DB_USER=root
DB_PASSWORD=aiotAiot123!
DB_DATABASE=jiebandata_test
NODE_ENV=test
```
### 生产环境 (Production)
```env
DB_HOST=129.211.213.226
DB_PORT=9527
DB_USER=root
DB_PASSWORD=Aiot123
DB_DATABASE=jiebandata
NODE_ENV=production
```
## 🔌 API 设计
### 用户模块接口
#### 微信用户登录
- **Endpoint:** `POST /api/auth/wechat-login`
- **Method:** POST
- **Description:** 微信用户登录获取Token
- **Request Body:**
```json
{
"code": "string, required",
"userInfo": {
"nickName": "string, required",
"avatarUrl": "string, required",
"gender": "number, optional",
"province": "string, optional",
"city": "string, optional"
}
}
```
- **Response:**
```json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"username": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"phone": "13800138000"
}
}
}
```
#### 获取用户信息
- **Endpoint:** `GET /api/users/profile`
- **Method:** GET
- **Description:** 获取当前登录用户详细信息
- **Headers:** `Authorization: Bearer <token>`
- **Response:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"id": 1,
"username": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"birthday": "1990-01-01",
"phone": "13800138000",
"email": "test@jiebanke.com",
"travelCount": 5,
"animalClaimCount": 2,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 🚀 部署架构
### 开发部署
```mermaid
graph LR
A[本地开发机] --> B[Docker Compose]
B --> C[MySQL容器]
B --> D[Redis容器]
B --> E[RabbitMQ容器]
B --> F[微服务容器]
```
### 生产部署
```mermaid
graph TB
subgraph "负载均衡器"
A[Nginx]
end
subgraph "微服务集群"
B[API网关集群]
C[认证服务集群]
D[用户服务集群]
E[旅行服务集群]
F[动物服务集群]
G[订单服务集群]
H[推广服务集群]
end
subgraph "基础设施"
I[MySQL主从]
J[Redis集群]
K[RabbitMQ集群]
L[Eureka集群]
end
A --> B
B --> C
B --> D
B --> E
B --> F
B --> G
B --> H
C --> I
C --> J
C --> K
D --> I
D --> J
D --> K
E --> I
E --> J
E --> K
F --> I
F --> J
F --> K
G --> I
G --> J
G --> K
H --> I
H --> J
H --> K
```
## 📊 监控与日志
- **应用监控**: Spring Boot Actuator + Prometheus + Grafana
- **日志管理**: Logback + ELK Stack
- **性能监控**: Micrometer + Prometheus
- **错误追踪**: Sentry
## 🔒 安全架构
### 认证授权
- JWT Token 认证
- RBAC (基于角色的访问控制)
- API 速率限制
### 数据安全
- HTTPS 加密传输
- 密码加盐哈希存储
- SQL 注入防护
- XSS 攻击防护
### 网络安全
- 防火墙规则
- IP 白名单
- DDoS 防护
## 📈 性能优化
### 数据库优化
- 索引优化
- 查询缓存
- 读写分离
### 应用优化
- JVM调优
- 连接池优化
- 缓存策略优化
### 微服务优化
- 负载均衡
- 熔断机制
- 服务降级
## 🛠️ 开发规范
### 代码规范
- Checkstyle + PMD 统一代码风格
- Git Commit 消息规范
- 代码审查流程
### 分支策略
- Git Flow 工作流
- 功能分支开发
- 发布分支管理
### 测试策略
- 单元测试覆盖核心逻辑
- 集成测试API接口
- 压力测试性能指标
## 📝 文档体系
1. **ARCHITECTURE.md** - 系统架构文档 (当前文件)
2. **README.md** - 项目说明文档
3. **API_DOCS.md** - API接口文档
4. **DEPLOYMENT.md** - 部署指南
5. **DEVELOPMENT.md** - 开发指南
## 🎯 后续规划
### 短期目标
- [x] 完成用户管理系统
- [x] 实现订单业务流程
- [x] 部署测试环境
### 中期目标
- [x] 微服务架构改造
- [x] 容器化部署
- [ ] 自动化测试覆盖
### 长期目标
- [ ] 大数据分析平台
- [ ] AI智能推荐
- [ ] 多语言国际化
---
*最后更新: 2025年* 📅

403
docs/architecture.md
View File

@@ -1,403 +0,0 @@
# 🏗️ 系统架构文档
## 📋 项目概述
结伴客项目是一个综合性的管理系统，包含后台管理、微信小程序和官网三个主要模块。
## 🎯 技术栈
### 后端技术栈
- **运行时**: Node.js + Express.js
- **数据库**: MySQL 8.0
- **ORM**: Sequelize
- **认证**: JWT + bcrypt
- **缓存**: Redis (可选)
- **消息队列**: RabbitMQ (可选)
### 前端技术栈
- **后台管理系统**: Vue 3 + Element Plus
- **微信小程序**: 原生小程序 + Vant Weapp
- **官方网站**: Vue 3 + Vue Router
### 开发工具
- **包管理**: npm
- **容器化**: Docker + Docker Compose
- **代码质量**: ESLint + Prettier
- **测试**: Jest + Supertest
## 🏢 系统架构
```mermaid
graph TB
subgraph "前端应用"
A[后台管理系统]
B[微信小程序]
C[官方网站]
end
subgraph "后端服务"
D[API Gateway]
E[用户服务]
F[业务服务]
G[文件服务]
end
subgraph "数据层"
H[MySQL]
I[Redis]
J[MinIO]
end
A --> D
B --> D
C --> D
D --> E
D --> F
D --> G
E --> H
F --> H
G --> J
E --> I
```
## 🗄️ 数据库设计
### 核心表结构设计
```mermaid
erDiagram
USERS ||--o{ TRAVEL_PLANS : creates
USERS ||--o{ TRAVEL_INVITATIONS : sends
USERS ||--o{ TRAVEL_INVITATIONS : receives
USERS ||--o{ ANIMAL_CLAIMS : claims
USERS ||--o{ FLOWER_ORDERS : places
MERCHANTS ||--o{ ANIMALS : owns
MERCHANTS ||--o{ FLOWER_PRODUCTS : sells
ANIMALS ||--o{ ANIMAL_CLAIMS : claimed_by
FLOWER_PRODUCTS ||--o{ FLOWER_ORDERS : ordered
TRAVEL_PLANS ||--o{ TRAVEL_INVITATIONS : has
USERS {
int id PK
string openid
string nickname
string avatar
string gender
date birthday
string phone
string email
int travel_count
int animal_claim_count
datetime created_at
datetime updated_at
}
TRAVEL_PLANS {
int id PK
int user_id FK
string destination
date start_date
date end_date
decimal budget
string interests
string description
string visibility
string status
datetime created_at
datetime updated_at
}
TRAVEL_INVITATIONS {
int id PK
int travel_plan_id FK
int inviter_id FK
int invitee_id FK
string message
string status
datetime created_at
datetime updated_at
}
ANIMALS {
int id PK
int merchant_id FK
string name
string species
string breed
date birth_date
string personality
string farm_location
decimal price
json images
int claim_count
datetime created_at
datetime updated_at
}
ANIMAL_CLAIMS {
int id PK
int user_id FK
int animal_id FK
int duration
decimal total_amount
string status
date start_date
date end_date
datetime created_at
datetime updated_at
}
MERCHANTS {
int id PK
string business_name
string contact_person
string contact_phone
string business_license
string address
string status
datetime created_at
datetime updated_at
}
FLOWER_PRODUCTS {
int id PK
int merchant_id FK
string name
string description
decimal price
decimal original_price
json images
string category
int sales_count
decimal rating
string status
datetime created_at
datetime updated_at
}
FLOWER_ORDERS {
int id PK
int user_id FK
int product_id FK
string order_number
int quantity
decimal total_amount
json recipient_info
date delivery_date
string message
string status
datetime created_at
datetime updated_at
}
```
## 🌐 环境配置
### 开发环境 (Development)
```env
DB_HOST=mysql.jiebanke.com
DB_PORT=3306
DB_USER=root
DB_PASSWORD=rootpassword
DB_DATABASE=jiebanke_dev
NODE_ENV=development
```
### 测试环境 (Test)
```env
DB_HOST=192.168.0.240
DB_PORT=3306
DB_USER=root
DB_PASSWORD=aiotAiot123!
DB_DATABASE=jiebandata_test
NODE_ENV=test
```
### 生产环境 (Production)
```env
DB_HOST=129.211.213.226
DB_PORT=9527
DB_USER=root
DB_PASSWORD=Aiot123
DB_DATABASE=jiebandata
NODE_ENV=production
```
## 🔌 API 设计
### 用户模块接口
#### 微信用户登录
- **Endpoint:** `POST /api/v1/auth/wechat-login`
- **Method:** POST
- **Description:** 微信用户登录获取Token
- **Request Body:**
```json
{
"code": "string, required",
"userInfo": {
"nickName": "string, required",
"avatarUrl": "string, required",
"gender": "number, optional",
"province": "string, optional",
"city": "string, optional"
}
}
```
- **Response:**
```json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"openid": "wx1234567890",
"nickname": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"phone": "13800138000"
}
}
}
```
#### 获取用户信息
- **Endpoint:** `GET /api/v1/users/profile`
- **Method:** GET
- **Description:** 获取当前登录用户详细信息
- **Headers:** `Authorization: Bearer <token>`
- **Response:**
```json
{
"code": 200,
"message": "获取成功",
"data": {
"id": 1,
"openid": "wx1234567890",
"nickname": "旅行达人",
"avatar": "https://avatar.url",
"gender": "male",
"birthday": "1990-01-01",
"phone": "13800138000",
"email": "test@jiebanke.com",
"travelCount": 5,
"animalClaimCount": 2,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
}
```
## 🚀 部署架构
### 开发部署
```mermaid
graph LR
A[本地开发机] --> B[Docker Compose]
B --> C[MySQL容器]
B --> D[Node.js应用]
B --> E[Redis容器]
```
### 生产部署
```mermaid
graph TB
subgraph "云服务器"
A[Nginx]
B[Node.js集群]
C[MySQL主从]
D[Redis哨兵]
end
A --> B
B --> C
B --> D
```
## 📊 监控与日志
- **应用监控**: PM2 + Keymetrics
- **日志管理**: Winston + ELK Stack
- **性能监控**: New Relic / Datadog
- **错误追踪**: Sentry
## 🔒 安全架构
### 认证授权
- JWT Token 认证
- RBAC (基于角色的访问控制)
- API 速率限制
### 数据安全
- HTTPS 加密传输
- 密码加盐哈希存储
- SQL 注入防护
- XSS 攻击防护
### 网络安全
- 防火墙规则
- IP 白名单
- DDoS 防护
## 📈 性能优化
### 数据库优化
- 索引优化
- 查询缓存
- 读写分离
### 应用优化
- 响应压缩
- 静态资源CDN
- 内存缓存
### 前端优化
- 代码分割
- 懒加载
- 图片优化
## 🛠️ 开发规范
### 代码规范
- ESLint + Prettier 统一代码风格
- Git Commit 消息规范
- 代码审查流程
### 分支策略
- Git Flow 工作流
- 功能分支开发
- 发布分支管理
### 测试策略
- 单元测试覆盖核心逻辑
- 集成测试API接口
- E2E测试用户流程
## 📝 文档体系
1. **ARCHITECTURE.md** - 系统架构文档 (当前文件)
2. **README.md** - 项目说明文档
3. **API_DOCS.md** - API接口文档
4. **DEPLOYMENT.md** - 部署指南
5. **DEVELOPMENT.md** - 开发指南
## 🎯 后续规划
### 短期目标
- [ ] 完善用户管理系统
- [ ] 实现订单业务流程
- [ ] 部署测试环境
### 中期目标
- [ ] 微服务架构改造
- [ ] 容器化部署
- [ ] 自动化测试覆盖
### 长期目标
- [ ] 大数据分析平台
- [ ] AI智能推荐
- [ ] 多语言国际化
---
*最后更新: 2024年* 📅

717
docs/database-design-java.md
View File

@@ -1,717 +0,0 @@
# 结伴客Java微服务系统数据库设计文档
## 1. 数据库概览
### 1.1 数据库配置
#### 开发环境
- **主机**: localhost
- **端口**: 3306
- **用户名**: root
- **密码**: root
- **数据库**: jiebanke
#### 测试环境
- **主机**: 192.168.0.240
- **端口**: 3306
- **用户名**: root
- **密码**: aiot$Aiot123
- **数据库**: jiebandata_test
#### 生产环境
- **主机**: 129.211.213.226
- **端口**: 9527
- **用户名**: root
- **密码**: aiotAiot123!
- **数据库**: jiebandata
### 1.2 ER图
```mermaid
erDiagram
USERS ||--o{ TRAVEL_PLANS : creates
USERS ||--o{ ANIMAL_CLAIMS : claims
USERS ||--o{ MESSAGES : sends
USERS ||--o{ ORDERS : places
USERS ||--o{ REVIEWS : writes
MERCHANTS ||--o{ PRODUCTS : sells
MERCHANTS ||--o{ ORDERS : processes
MERCHANTS ||--o{ ACTIVITIES : organizes
MERCHANTS ||--o{ ANIMALS : manages
TRAVEL_PLANS ||--o{ TRAVEL_MATCHES : matches
ANIMALS ||--o{ ANIMAL_CLAIMS : claimed
ANIMALS ||--o{ ANIMAL_UPDATES : updates
PRODUCTS ||--o{ ORDER_ITEMS : contains
ORDERS ||--o{ ORDER_ITEMS : contains
ORDERS ||--o{ PAYMENTS : has
ACTIVITIES ||--o{ ACTIVITY_REGISTRATIONS : registers
ADMINS ||--o{ ADMIN_LOGS : creates
PROMOTION_ACTIVITIES ||--o{ REWARD_RECORDS : rewards
USERS {
bigint id PK
varchar username
varchar password
varchar email
varchar phone
varchar real_name
varchar id_card
varchar status
decimal balance
int credit_score
timestamp last_login
timestamp created_at
timestamp updated_at
}
ADMINS {
bigint id PK
varchar username
varchar password
varchar email
varchar role
varchar status
timestamp last_login
timestamp created_at
timestamp updated_at
}
MERCHANTS {
bigint id PK
bigint user_id FK
varchar merchant_type
varchar business_name
varchar business_license
varchar contact_person
varchar contact_phone
varchar address
varchar description
varchar status
timestamp created_at
timestamp updated_at
}
TRAVEL_PLANS {
bigint id PK
bigint user_id FK
varchar destination
date start_date
date end_date
decimal budget
text interests
varchar visibility
timestamp created_at
timestamp updated_at
}
ANIMALS {
bigint id PK
bigint merchant_id FK
varchar name
varchar species
varchar breed
date birth_date
text personality
varchar farm_location
decimal price
varchar status
timestamp created_at
timestamp updated_at
}
ORDERS {
bigint id PK
bigint user_id FK
bigint merchant_id FK
varchar order_number
decimal total_amount
varchar status
varchar delivery_address
timestamp ordered_at
timestamp completed_at
}
PRODUCTS {
bigint id PK
bigint merchant_id FK
varchar name
text description
decimal price
varchar image_url
varchar category
varchar status
timestamp created_at
timestamp updated_at
}
PROMOTION_ACTIVITIES {
bigint id PK
varchar name
text description
varchar reward_type
decimal reward_amount
varchar status
timestamp start_time
timestamp end_time
int max_participants
int current_participants
timestamp created_at
timestamp updated_at
}
REWARD_RECORDS {
bigint id PK
bigint user_id
varchar user_name
varchar user_phone
bigint activity_id
varchar activity_name
varchar reward_type
decimal reward_amount
varchar status
timestamp issued_at
timestamp created_at
}
```
## 2. 核心表结构设计
### 2.1 用户表 (users)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 用户ID |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
| password | VARCHAR(255) | NOT NULL | 密码(bcrypt加密) |
| email | VARCHAR(100) | UNIQUE | 邮箱地址 |
| phone | VARCHAR(20) | UNIQUE | 手机号码 |
| real_name | VARCHAR(100) | | 真实姓名 |
| id_card | VARCHAR(20) | UNIQUE | 身份证号 |
| status | VARCHAR(20) | DEFAULT 'active' | 状态(active/inactive) |
| balance | DECIMAL(15,2) | DEFAULT 0.00 | 账户余额 |
| credit_score | INT | DEFAULT 100 | 信用分 |
| last_login | TIMESTAMP | | 最后登录时间 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.2 管理员表 (admins)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 管理员ID |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 管理员用户名 |
| password | VARCHAR(255) | NOT NULL | 密码(bcrypt加密) |
| email | VARCHAR(100) | UNIQUE | 邮箱地址 |
| role | VARCHAR(20) | DEFAULT 'admin' | 角色(super_admin/admin/operator) |
| status | VARCHAR(20) | DEFAULT 'active' | 状态(active/inactive) |
| last_login | TIMESTAMP | | 最后登录时间 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.3 商家表 (merchants)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 商家ID |
| user_id | BIGINT | FOREIGN KEY, NOT NULL | 关联的用户ID |
| merchant_type | VARCHAR(50) | NOT NULL | 商家类型(flower_shop/activity_organizer/farm_owner) |
| business_name | VARCHAR(100) | NOT NULL | 商家名称 |
| business_license | VARCHAR(255) | | 营业执照图片URL |
| contact_person | VARCHAR(50) | NOT NULL | 联系人 |
| contact_phone | VARCHAR(20) | NOT NULL | 联系电话 |
| address | VARCHAR(255) | | 地址 |
| description | TEXT | | 商家介绍 |
| status | VARCHAR(20) | DEFAULT 'pending' | 商家状态(pending/approved/rejected/suspended) |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.4 订单表 (orders)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 订单ID |
| user_id | BIGINT | FOREIGN KEY, NOT NULL | 用户ID |
| merchant_id | BIGINT | FOREIGN KEY, NOT NULL | 商家ID |
| order_number | VARCHAR(50) | UNIQUE, NOT NULL | 订单编号 |
| total_amount | DECIMAL(15,2) | NOT NULL | 订单总金额 |
| status | VARCHAR(20) | DEFAULT 'pending' | 订单状态(pending/paid/shipped/completed/cancelled) |
| delivery_address | VARCHAR(255) | | 配送地址 |
| ordered_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 下单时间 |
| completed_at | TIMESTAMP | | 完成时间 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.5 商品表 (products)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 商品ID |
| merchant_id | BIGINT | FOREIGN KEY, NOT NULL | 商家ID |
| name | VARCHAR(100) | NOT NULL | 商品名称 |
| description | TEXT | | 商品描述 |
| price | DECIMAL(10,2) | NOT NULL | 商品价格 |
| image_url | VARCHAR(255) | | 商品图片URL |
| category | VARCHAR(50) | NOT NULL | 商品分类 |
| status | VARCHAR(20) | DEFAULT 'active' | 商品状态(active/inactive/deleted) |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.6 动物表 (animals)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 动物ID |
| merchant_id | BIGINT | FOREIGN KEY, NOT NULL | 关联的农场商家ID |
| name | VARCHAR(50) | NOT NULL | 动物名称 |
| species | VARCHAR(50) | NOT NULL | 动物种类 |
| breed | VARCHAR(50) | | 品种 |
| birth_date | DATE | | 出生日期 |
| personality | TEXT | | 性格特点 |
| farm_location | VARCHAR(255) | | 农场位置 |
| images | JSON | | 动物图片列表 |
| price | DECIMAL(10,2) | NOT NULL | 认领价格 |
| claim_count | INT | DEFAULT 0 | 认领次数 |
| status | VARCHAR(20) | DEFAULT 'available' | 状态(available/claimed/unavailable) |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.7 动物认领表 (animal_claims)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 认领ID |
| user_id | BIGINT | FOREIGN KEY, NOT NULL | 用户ID |
| animal_id | BIGINT | FOREIGN KEY, NOT NULL | 动物ID |
| price_paid | DECIMAL(10,2) | NOT NULL | 支付金额 |
| agreement_url | VARCHAR(255) | | 电子协议URL |
| status | VARCHAR(20) | DEFAULT 'active' | 认领状态(active/ended/cancelled) |
| claimed_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 认领时间 |
| ended_at | TIMESTAMP | | 结束时间 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.8 送花商品表 (flower_products)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 商品ID |
| merchant_id | BIGINT | FOREIGN KEY, NOT NULL | 商家ID |
| name | VARCHAR(100) | NOT NULL | 商品名称 |
| description | TEXT | | 商品描述 |
| price | DECIMAL(10,2) | NOT NULL | 商品价格 |
| original_price | DECIMAL(10,2) | | 原价 |
| images | JSON | | 商品图片列表 |
| category | VARCHAR(50) | NOT NULL | 商品分类 |
| sales_count | INT | DEFAULT 0 | 销售数量 |
| rating | DECIMAL(3,2) | DEFAULT 0 | 评分 |
| status | VARCHAR(20) | DEFAULT 'active' | 商品状态(active/inactive/deleted) |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.9 送花订单表 (flower_orders)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 订单ID |
| user_id | BIGINT | FOREIGN KEY, NOT NULL | 用户ID |
| product_id | BIGINT | FOREIGN KEY, NOT NULL | 商品ID |
| order_number | VARCHAR(50) | UNIQUE, NOT NULL | 订单编号 |
| quantity | INT | NOT NULL | 数量 |
| total_amount | DECIMAL(15,2) | NOT NULL | 订单总金额 |
| recipient_info | JSON | | 收花人信息 |
| delivery_date | DATE | | 配送日期 |
| message | VARCHAR(500) | | 祝福语 |
| status | VARCHAR(20) | DEFAULT 'pending' | 订单状态(pending/paid/shipped/completed/cancelled) |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.10 旅行邀请表 (travel_invitations)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 邀请ID |
| travel_plan_id | BIGINT | FOREIGN KEY, NOT NULL | 旅行计划ID |
| inviter_id | BIGINT | FOREIGN KEY, NOT NULL | 邀请人ID |
| invitee_id | BIGINT | FOREIGN KEY, NOT NULL | 被邀请人ID |
| message | VARCHAR(500) | | 邀请消息 |
| status | VARCHAR(20) | DEFAULT 'pending' | 邀请状态(pending/accepted/rejected/cancelled) |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.11 旅行匹配表 (travel_matches)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 匹配ID |
| plan_id | BIGINT | FOREIGN KEY, NOT NULL | 旅行计划ID |
| matched_plan_id | BIGINT | FOREIGN KEY, NOT NULL | 匹配的旅行计划ID |
| match_score | DECIMAL(5,4) | NOT NULL | 匹配分数 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
### 2.12 旅行计划表 (travel_plans)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 计划ID |
| user_id | BIGINT | FOREIGN KEY, NOT NULL | 用户ID |
| destination | VARCHAR(100) | NOT NULL | 目的地 |
| start_date | DATE | NOT NULL | 开始日期 |
| end_date | DATE | NOT NULL | 结束日期 |
| budget | DECIMAL(10,2) | | 预算 |
| interests | TEXT | | 兴趣偏好 |
| description | TEXT | | 描述 |
| visibility | VARCHAR(20) | DEFAULT 'public' | 可见范围(public/friends/private) |
| status | VARCHAR(20) | DEFAULT 'active' | 状态(active/completed/cancelled) |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.13 推广活动表 (promotion_activities)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 活动ID |
| name | VARCHAR(100) | NOT NULL | 活动名称 |
| description | TEXT | | 活动描述 |
| reward_type | VARCHAR(20) | | 奖励类型(cash/coupon/points) |
| reward_amount | DECIMAL(10,2) | | 奖励金额 |
| status | VARCHAR(20) | DEFAULT 'active' | 活动状态(active/inactive/expired) |
| start_time | TIMESTAMP | | 开始时间 |
| end_time | TIMESTAMP | | 结束时间 |
| max_participants | INT | | 最大参与人数 |
| current_participants | INT | DEFAULT 0 | 当前参与人数 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
### 2.14 奖励记录表 (reward_records)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 记录ID |
| user_id | BIGINT | | 用户ID |
| user_name | VARCHAR(50) | | 用户姓名 |
| user_phone | VARCHAR(20) | | 用户手机号 |
| activity_id | BIGINT | | 活动ID |
| activity_name | VARCHAR(100) | | 活动名称 |
| reward_type | VARCHAR(20) | | 奖励类型 |
| reward_amount | DECIMAL(10,2) | | 奖励金额 |
| status | VARCHAR(20) | DEFAULT 'pending' | 状态(pending/issued/cancelled) |
| issued_at | TIMESTAMP | | 发放时间 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
### 2.15 管理员操作日志表 (admin_operation_logs)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 日志ID |
| admin_id | BIGINT | FOREIGN KEY REFERENCES admins(id), NOT NULL | 操作管理员ID |
| admin_name | VARCHAR(50) | NOT NULL | 管理员名称 |
| action_type | VARCHAR(50) | NOT NULL | 操作类型 |
| target_type | VARCHAR(50) | | 目标类型 |
| target_id | BIGINT | | 目标ID |
| target_name | VARCHAR(100) | | 目标名称 |
| old_value | TEXT | | 操作前值 |
| new_value | TEXT | | 操作后值 |
| ip_address | VARCHAR(45) | | 操作IP地址 |
| user_agent | VARCHAR(500) | | 用户代理信息 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
## 3. 微服务API接口规范
### 3.1 接口统一格式
#### 请求格式
- **Base URL**: http://localhost:8080/api/
- **认证**: Bearer Token (需要认证的接口)
- **Content-Type**: application/json
#### 响应格式
```json
{
"code": 200,
"message": "操作成功",
"data": {
// 具体数据
},
"pagination": {
// 分页信息(列表接口)
}
}
```
### 3.2 通用状态码
| 状态码 | 描述 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
### 3.3 认证接口
#### 3.3.1 微信用户登录
- **Endpoint**: POST /auth/wechat-login
- **认证要求**: 无
- **请求体**:
```json
{
"code": "string, required",
"userInfo": {
"nickName": "string, required",
"avatarUrl": "string, required",
"gender": "number, optional",
"province": "string, optional",
"city": "string, optional"
}
}
```
#### 3.3.2 获取用户信息
- **Endpoint**: GET /users/profile
- **认证要求**: Bearer Token
### 3.4 用户管理接口
#### 3.4.1 获取用户列表
- **Endpoint**: GET /admin/users
- **认证要求**: Bearer Token
- **查询参数**: page, limit, username, status
#### 3.4.2 获取用户详情
- **Endpoint**: GET /admin/users/{id}
- **认证要求**: Bearer Token
#### 3.4.3 更新用户状态
- **Endpoint**: PUT /admin/users/{id}/status
- **认证要求**: Bearer Token
### 3.5 商家管理接口
#### 3.5.1 获取商家列表
- **Endpoint**: GET /admin/merchants
- **认证要求**: Bearer Token
- **查询参数**: page, limit, business_name, status
#### 3.5.2 审核商家申请
- **Endpoint**: PUT /admin/merchants/{id}/approve
- **认证要求**: Bearer Token
#### 3.5.3 拒绝商家申请
- **Endpoint**: PUT /admin/merchants/{id}/reject
- **认证要求**: Bearer Token
### 3.6 订单管理接口
#### 3.6.1 获取订单列表
- **Endpoint**: GET /admin/orders
- **认证要求**: Bearer Token
- **查询参数**: page, limit, order_no, status
#### 3.6.2 更新订单状态
- **Endpoint**: PUT /admin/orders/{id}/status
- **认证要求**: Bearer Token
### 3.7 推广活动接口
#### 3.7.1 获取推广活动列表
- **Endpoint**: GET /admin/promotions
- **认证要求**: Bearer Token
- **查询参数**: page, limit, name, status
#### 3.7.2 创建推广活动
- **Endpoint**: POST /admin/promotions
- **认证要求**: Bearer Token
#### 3.7.3 更新推广活动
- **Endpoint**: PUT /admin/promotions/{id}
- **认证要求**: Bearer Token
## 4. 数据库初始化脚本
### 4.1 创建数据库和表
```sql
-- 创建数据库
CREATE DATABASE IF NOT EXISTS jiebanke CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE jiebanke;
-- 创建管理员表
CREATE TABLE IF NOT EXISTS admins (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(50) NOT NULL UNIQUE,
password VARCHAR(255) NOT NULL,
email VARCHAR(100),
role VARCHAR(20) DEFAULT 'admin',
status VARCHAR(20) DEFAULT 'active',
last_login TIMESTAMP NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
-- 创建用户表
CREATE TABLE IF NOT EXISTS users (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(50) NOT NULL UNIQUE,
password VARCHAR(255) NOT NULL,
email VARCHAR(100) UNIQUE,
phone VARCHAR(20),
real_name VARCHAR(100),
id_card VARCHAR(20),
status VARCHAR(20) DEFAULT 'active',
balance DECIMAL(15,2) DEFAULT 0.00,
credit_score INT DEFAULT 100,
last_login TIMESTAMP NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
-- 创建订单表
CREATE TABLE IF NOT EXISTS orders (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
user_id BIGINT NOT NULL,
order_no VARCHAR(50) NOT NULL UNIQUE,
amount DECIMAL(15,2) NOT NULL,
status VARCHAR(20) DEFAULT 'pending',
type VARCHAR(20) NOT NULL,
description TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
-- 创建旅行计划表
CREATE TABLE IF NOT EXISTS travel_plans (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
user_id BIGINT NOT NULL,
destination VARCHAR(100) NOT NULL,
start_date DATE NOT NULL,
end_date DATE NOT NULL,
budget DECIMAL(10,2),
interests TEXT,
description TEXT,
visibility VARCHAR(20) DEFAULT 'public',
status VARCHAR(20) DEFAULT 'active',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
-- 创建动物表
CREATE TABLE IF NOT EXISTS animals (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
merchant_id BIGINT NOT NULL,
name VARCHAR(50) NOT NULL,
species VARCHAR(50) NOT NULL,
breed VARCHAR(50),
birth_date DATE,
personality TEXT,
farm_location VARCHAR(255),
price DECIMAL(10,2) NOT NULL,
claim_count INT DEFAULT 0,
status VARCHAR(20) DEFAULT 'available',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
-- 创建推广活动表
CREATE TABLE IF NOT EXISTS promotion_activities (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
description TEXT,
reward_type VARCHAR(20),
reward_amount DECIMAL(10,2),
status VARCHAR(20) DEFAULT 'active',
start_time TIMESTAMP,
end_time TIMESTAMP,
max_participants INT,
current_participants INT DEFAULT 0,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
-- 创建奖励记录表
CREATE TABLE IF NOT EXISTS reward_records (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
user_id BIGINT,
user_name VARCHAR(50),
user_phone VARCHAR(20),
activity_id BIGINT,
activity_name VARCHAR(100),
reward_type VARCHAR(20),
reward_amount DECIMAL(10,2),
status VARCHAR(20) DEFAULT 'pending',
issued_at TIMESTAMP,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### 4.2 插入默认数据
```sql
-- 插入默认管理员账号
INSERT INTO admins (username, password, email, role) VALUES
('admin', '$2a$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi', 'admin@jiebanke.com', 'super_admin'),
('manager', '$2a$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi', 'manager@jiebanke.com', 'admin');
-- 插入测试用户账号
INSERT INTO users (username, password, email, phone, real_name, id_card, balance, credit_score) VALUES
('user1', '$2a$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi', 'user1@jiebanke.com', '13800138001', '张三', '110101199001011234', 1000.00, 95),
('user2', '$2a$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi', 'user2@jiebanke.com', '13800138002', '李四', '110101199002022345', 500.00, 85);
```
### 4.3 创建索引
```sql
-- 创建索引
CREATE INDEX idx_admins_username ON admins(username);
CREATE INDEX idx_admins_email ON admins(email);
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_phone ON users(phone);
CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_order_no ON orders(order_no);
CREATE INDEX idx_orders_status ON orders(status);
CREATE INDEX idx_travel_plans_user_id ON travel_plans(user_id);
CREATE INDEX idx_travel_plans_destination ON travel_plans(destination);
CREATE INDEX idx_animals_species ON animals(species);
CREATE INDEX idx_animals_status ON animals(status);
CREATE INDEX idx_promotion_activities_status ON promotion_activities(status);
CREATE INDEX idx_reward_records_user_id ON reward_records(user_id);
CREATE INDEX idx_reward_records_activity_id ON reward_records(activity_id);
```
## 5. 数据库维护
### 5.1 备份策略
- 每日全量备份
- 每小时增量备份
- 备份保留30天
### 5.2 性能优化
- 为常用查询字段创建索引
- 定期分析慢查询日志
- 数据库连接池配置优化
### 5.3 安全措施
- 定期更换数据库密码
- 限制数据库访问IP
- 启用SSL加密连接
## 6. 微服务数据分片建议
### 6.1 用户服务数据表
- users
- user_profiles
- user_settings
### 6.2 旅行服务数据表
- travel_plans
- travel_invitations
- travel_matches
### 6.3 动物服务数据表
- animals
- animal_claims
- animal_updates
### 6.4 订单服务数据表
- orders
- order_items
- payments
### 6.5 推广服务数据表
- promotion_activities
- reward_records
- participant_records
---
*最后更新: 2025年* 📅

498
docs/database-design.md
View File

@@ -1,498 +0,0 @@
# 结伴客系统数据库设计文档
## 1. 数据库概览
### 1.1 数据库配置
#### 测试环境
- **主机**: 192.168.0.240
- **端口**: 3306
- **用户名**: root
- **密码**: aiot$Aiot123
- **数据库**: jiebandata
#### 生产环境
- **主机**: 129.211.213.226
- **端口**: 9527
- **用户名**: root
- **密码**: aiotAiot123!
- **数据库**: jiebandata
### 1.2 ER图
```mermaid
erDiagram
USERS ||--o{ TRAVEL_PLANS : creates
USERS ||--o{ ANIMAL_CLAIMS : claims
USERS ||--o{ MESSAGES : sends
USERS ||--o{ ORDERS : places
USERS ||--o{ REVIEWS : writes
MERCHANTS ||--o{ PRODUCTS : sells
MERCHANTS ||--o{ ORDERS : processes
MERCHANTS ||--o{ ACTIVITIES : organizes
MERCHANTS ||--o{ ANIMALS : manages
TRAVEL_PLANS ||--o{ TRAVEL_MATCHES : matches
ANIMALS ||--o{ ANIMAL_CLAIMS : claimed
ANIMALS ||--o{ ANIMAL_UPDATES : updates
PRODUCTS ||--o{ ORDER_ITEMS : contains
ORDERS ||--o{ ORDER_ITEMS : contains
ORDERS ||--o{ PAYMENTS : has
ACTIVITIES ||--o{ ACTIVITY_REGISTRATIONS : registers
ADMINS ||--o{ ADMIN_LOGS : creates
USERS {
int id PK
string openid
string nickname
string avatar
string gender
date birthday
string phone
string email
datetime created_at
datetime updated_at
}
ADMINS {
int id PK
string username
string password
string email
string nickname
string avatar
enum role
tinyint status
timestamp last_login
timestamp created_at
timestamp updated_at
}
MERCHANTS {
int id PK
int user_id FK
string merchant_type
string business_name
string business_license
string contact_person
string contact_phone
string address
string description
string status
datetime created_at
datetime updated_at
}
TRAVEL_PLANS {
int id PK
int user_id FK
string destination
date start_date
date end_date
decimal budget
string interests
string visibility
datetime created_at
datetime updated_at
}
ANIMALS {
int id PK
int merchant_id FK
string name
string species
string breed
date birth_date
string personality
string farm_location
decimal price
string status
datetime created_at
datetime updated_at
}
ORDERS {
int id PK
int user_id FK
int merchant_id FK
string order_number
decimal total_amount
string status
string delivery_address
datetime ordered_at
datetime completed_at
}
PRODUCTS {
int id PK
int merchant_id FK
string name
string description
decimal price
string image_url
string category
string status
datetime created_at
datetime updated_at
}
```
## 2. 核心表结构设计
### 2.1 用户表 (users)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 用户ID |
| openid | VARCHAR(64) | UNIQUE, NOT NULL | 微信openid |
| nickname | VARCHAR(50) | NOT NULL | 用户昵称 |
| avatar | VARCHAR(255) | | 用户头像URL |
| gender | ENUM('male', 'female', 'other') | | 性别 |
| birthday | DATE | | 生日 |
| phone | VARCHAR(20) | UNIQUE | 手机号码 |
| email | VARCHAR(100) | UNIQUE | 邮箱地址 |
| travel_count | INT | DEFAULT 0 | 旅行结伴次数 |
| animal_claim_count | INT | DEFAULT 0 | 动物认领次数 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 2.2 管理员表 (admins)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 管理员ID |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 管理员用户名 |
| password | VARCHAR(255) | NOT NULL | 密码(bcrypt加密) |
| email | VARCHAR(100) | UNIQUE | 邮箱地址 |
| nickname | VARCHAR(100) | | 昵称 |
| avatar | VARCHAR(255) | | 头像URL |
| role | ENUM('super_admin', 'admin', 'operator') | NOT NULL | 角色 |
| status | TINYINT | DEFAULT 1 | 状态(1:启用, 0:禁用) |
| last_login | TIMESTAMP | | 最后登录时间 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
**注意**: 管理员默认密码为 'admin123'，使用 bcrypt 加密存储
### 2.3 商家表 (merchants)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 商家ID |
| user_id | INT | FOREIGN KEY, NOT NULL | 关联的用户ID |
| merchant_type | ENUM('flower_shop', 'activity_organizer', 'farm_owner') | NOT NULL | 商家类型 |
| business_name | VARCHAR(100) | NOT NULL | 商家名称 |
| business_license | VARCHAR(255) | | 营业执照图片URL |
| contact_person | VARCHAR(50) | NOT NULL | 联系人 |
| contact_phone | VARCHAR(20) | NOT NULL | 联系电话 |
| address | VARCHAR(255) | | 地址 |
| description | TEXT | | 商家介绍 |
| status | ENUM('pending', 'approved', 'rejected', 'suspended') | NOT NULL | 商家状态 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 2.4 订单表 (orders)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 订单ID |
| user_id | INT | FOREIGN KEY, NOT NULL | 用户ID |
| merchant_id | INT | FOREIGN KEY, NOT NULL | 商家ID |
| order_number | VARCHAR(50) | UNIQUE, NOT NULL | 订单编号 |
| total_amount | DECIMAL(10,2) | NOT NULL | 订单总金额 |
| status | ENUM('pending', 'paid', 'shipped', 'completed', 'cancelled') | NOT NULL | 订单状态 |
| delivery_address | VARCHAR(255) | | 配送地址 |
| ordered_at | DATETIME | NOT NULL | 下单时间 |
| completed_at | DATETIME | | 完成时间 |
### 2.5 商品表 (products)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 商品ID |
| merchant_id | INT | FOREIGN KEY, NOT NULL | 商家ID |
| name | VARCHAR(100) | NOT NULL | 商品名称 |
| description | TEXT | | 商品描述 |
| price | DECIMAL(10,2) | NOT NULL | 商品价格 |
| image_url | VARCHAR(255) | | 商品图片URL |
| category | VARCHAR(50) | NOT NULL | 商品分类 |
| status | ENUM('active', 'inactive', 'deleted') | NOT NULL | 商品状态 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 2.6 动物表 (animals)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 动物ID |
| merchant_id | INT | FOREIGN KEY, NOT NULL | 关联的农场商家ID |
| name | VARCHAR(50) | NOT NULL | 动物名称 |
| species | VARCHAR(50) | NOT NULL | 动物种类 |
| breed | VARCHAR(50) | | 品种 |
| birth_date | DATE | | 出生日期 |
| personality | TEXT | | 性格特点 |
| farm_location | VARCHAR(255) | | 农场位置 |
| images | JSON | | 动物图片列表 |
| price | DECIMAL(10,2) | NOT NULL | 认领价格 |
| claim_count | INT | DEFAULT 0 | 认领次数 |
| status | ENUM('available', 'claimed', 'unavailable') | NOT NULL | 状态 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 2.7 动物认领表 (animal_claims)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 认领ID |
| user_id | INT | FOREIGN KEY, NOT NULL | 用户ID |
| animal_id | INT | FOREIGN KEY, NOT NULL | 动物ID |
| price_paid | DECIMAL(10,2) | NOT NULL | 支付金额 |
| agreement_url | VARCHAR(255) | | 电子协议URL |
| status | ENUM('active', 'ended', 'cancelled') | NOT NULL | 认领状态 |
| claimed_at | DATETIME | NOT NULL | 认领时间 |
| ended_at | DATETIME | | 结束时间 |
### 2.8 送花商品表 (flower_products)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 商品ID |
| merchant_id | INT | FOREIGN KEY, NOT NULL | 商家ID |
| name | VARCHAR(100) | NOT NULL | 商品名称 |
| description | TEXT | | 商品描述 |
| price | DECIMAL(10,2) | NOT NULL | 商品价格 |
| original_price | DECIMAL(10,2) | | 原价 |
| images | JSON | | 商品图片列表 |
| category | VARCHAR(50) | NOT NULL | 商品分类 |
| sales_count | INT | DEFAULT 0 | 销售数量 |
| rating | DECIMAL(3,2) | DEFAULT 0 | 评分 |
| status | ENUM('active', 'inactive', 'deleted') | NOT NULL | 商品状态 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 2.9 送花订单表 (flower_orders)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 订单ID |
| user_id | INT | FOREIGN KEY, NOT NULL | 用户ID |
| product_id | INT | FOREIGN KEY, NOT NULL | 商品ID |
| order_number | VARCHAR(50) | UNIQUE, NOT NULL | 订单编号 |
| quantity | INT | NOT NULL | 数量 |
| total_amount | DECIMAL(10,2) | NOT NULL | 订单总金额 |
| recipient_info | JSON | | 收花人信息 |
| delivery_date | DATE | | 配送日期 |
| message | VARCHAR(500) | | 祝福语 |
| status | ENUM('pending', 'paid', 'shipped', 'completed', 'cancelled') | NOT NULL | 订单状态 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 2.10 旅行邀请表 (travel_invitations)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 邀请ID |
| travel_plan_id | INT | FOREIGN KEY, NOT NULL | 旅行计划ID |
| inviter_id | INT | FOREIGN KEY, NOT NULL | 邀请人ID |
| invitee_id | INT | FOREIGN KEY, NOT NULL | 被邀请人ID |
| message | VARCHAR(500) | | 邀请消息 |
| status | ENUM('pending', 'accepted', 'rejected', 'cancelled') | NOT NULL | 邀请状态 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 2.11 旅行匹配表 (travel_matches)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 匹配ID |
| plan_id | INT | FOREIGN KEY, NOT NULL | 旅行计划ID |
| matched_plan_id | INT | FOREIGN KEY, NOT NULL | 匹配的旅行计划ID |
| match_score | DECIMAL(5,4) | NOT NULL | 匹配分数 |
| created_at | DATETIME | NOT NULL | 创建时间 |
### 2.12 旅行计划表 (travel_plans)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 计划ID |
| user_id | INT | FOREIGN KEY, NOT NULL | 用户ID |
| destination | VARCHAR(100) | NOT NULL | 目的地 |
| start_date | DATE | NOT NULL | 开始日期 |
| end_date | DATE | NOT NULL | 结束日期 |
| budget | DECIMAL(10,2) | NOT NULL | 预算 |
| interests | TEXT | | 兴趣偏好 |
| visibility | ENUM('public', 'friends', 'private') | NOT NULL | 可见范围 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
## 3. 后台管理系统API接口规范
### 3.1 接口统一格式
#### 请求格式
- **Base URL**: https://www.jiebanke.com/api/v1
- **认证**: Bearer Token (需要认证的接口)
- **Content-Type**: application/json
#### 响应格式
```json
{
"success": true,
"code": 200,
"message": "操作成功",
"data": {
// 具体数据
},
"pagination": {
// 分页信息(列表接口)
}
}
```
### 3.2 通用状态码
| 状态码 | 描述 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
### 3.3 管理员接口
#### 3.3.1 管理员登录
- **Endpoint**: POST /admin/auth/login
- **认证要求**: 无
- **请求体**:
```json
{
"username": "admin",
"password": "password123"
}
```
#### 3.3.2 获取管理员信息
- **Endpoint**: GET /admin/auth/profile
- **认证要求**: Bearer Token
#### 3.3.3 更新管理员信息
- **Endpoint**: PUT /admin/auth/profile
- **认证要求**: Bearer Token
#### 3.3.4 修改密码
- **Endpoint**: PUT /admin/auth/password
- **认证要求**: Bearer Token
### 3.4 用户管理接口
#### 3.4.1 获取用户列表
- **Endpoint**: GET /admin/users
- **认证要求**: Bearer Token
- **查询参数**: page, limit, username, user_type, status
#### 3.4.2 获取用户详情
- **Endpoint**: GET /admin/users/{id}
- **认证要求**: Bearer Token
#### 3.4.3 更新用户状态
- **Endpoint**: PUT /admin/users/{id}/status
- **认证要求**: Bearer Token
### 2.13 管理员操作日志表 (admin_operation_logs)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 日志ID |
| admin_id | INT | FOREIGN KEY REFERENCES admins(id), NOT NULL | 操作管理员ID |
| admin_name | VARCHAR(50) | NOT NULL | 管理员名称 |
| action_type | VARCHAR(50) | NOT NULL | 操作类型 |
| target_type | VARCHAR(50) | | 目标类型 |
| target_id | INT | | 目标ID |
| target_name | VARCHAR(100) | | 目标名称 |
| old_value | TEXT | | 操作前值 |
| new_value | TEXT | | 操作后值 |
| ip_address | VARCHAR(45) | | 操作IP地址 |
| user_agent | VARCHAR(500) | | 用户代理信息 |
| created_at | DATETIME | NOT NULL | 创建时间 |
### 2.14 管理员权限表 (admin_permissions)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 权限ID |
| code | VARCHAR(50) | UNIQUE, NOT NULL | 权限代码 |
| name | VARCHAR(100) | NOT NULL | 权限名称 |
| description | VARCHAR(255) | | 权限描述 |
| created_at | DATETIME | NOT NULL | 创建时间 |
| updated_at | DATETIME | NOT NULL | 更新时间 |
### 2.15 管理员角色权限关联表 (admin_role_permissions)
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 关联ID |
| admin_id | INT | FOREIGN KEY REFERENCES admins(id), NOT NULL | 管理员ID |
| permission_code | VARCHAR(50) | FOREIGN KEY REFERENCES admin_permissions(code), NOT NULL | 权限代码 |
| created_at | DATETIME | NOT NULL | 创建时间 |
### 3.5 商家管理接口
#### 3.5.1 获取商家列表
- **Endpoint**: GET /admin/merchants
- **认证要求**: Bearer Token
- **查询参数**: page, limit, business_name, status
#### 3.5.2 审核商家申请
- **Endpoint**: PUT /admin/merchants/{id}/approve
- **认证要求**: Bearer Token
#### 3.5.3 拒绝商家申请
- **Endpoint**: PUT /admin/merchants/{id}/reject
- **认证要求**: Bearer Token
### 3.6 订单管理接口
#### 3.6.1 获取订单列表
- **Endpoint**: GET /admin/orders
- **认证要求**: Bearer Token
- **查询参数**: page, limit, order_no, status
#### 3.6.2 更新订单状态
- **Endpoint**: PUT /admin/orders/{id}/status
- **认证要求**: Bearer Token
## 4. 数据库初始化脚本
### 4.1 创建管理员用户
```sql
INSERT INTO admins (username, password, email, nickname, role, status)
VALUES
('superadmin', '$2b$10$rOzJq...', 'superadmin@jiebanke.com', '超级管理员', 'super_admin', 1),
('admin', '$2b$10$rOzJq...', 'admin@jiebanke.com', '管理员', 'admin', 1),
('operator', '$2b$10$rOzJq...', 'operator@jiebanke.com', '操作员', 'operator', 1);
```
### 4.2 创建测试用户
```sql
INSERT INTO users (openid, nickname, gender, phone, email)
VALUES
('wx1234567890', '测试用户1', 'male', '13800138000', 'test1@jiebanke.com'),
('wx0987654321', '测试用户2', 'female', '13800138001', 'test2@jiebanke.com');
```
### 4.3 创建测试商家
```sql
INSERT INTO merchants (user_id, merchant_type, business_name, contact_person, contact_phone, status)
VALUES
(1, 'flower_shop', '鲜花小店', '张老板', '13800138002', 'approved'),
(2, 'farm_owner', '快乐农场', '李农场主', '13800138003', 'approved');
```
## 5. 数据库维护
### 5.1 备份策略
- 每日全量备份
- 每小时增量备份
- 备份保留30天
### 5.2 性能优化
- 为常用查询字段创建索引
- 定期分析慢查询日志
- 数据库连接池配置优化
### 5.3 安全措施
- 定期更换数据库密码
- 限制数据库访问IP
- 启用SSL加密连接

1004
docs/detailed_design.md
View File

File diff suppressed because it is too large Load Diff

357
docs/development_plan.md
View File

@@ -1,357 +0,0 @@
# 开发计划
## 1. 任务分解 (WBS)
### 1.1 后端开发任务
#### 1.1.1 基础服务搭建
- 用户认证服务 (JWT Token管理)
- API网关配置
- 微服务间通信机制 (gRPC/消息队列)
- 统一配置中心
- 日志收集与监控系统
#### 1.1.2 核心业务服务开发
- 用户管理服务 (用户注册、登录、信息管理)
- 旅行计划服务 (创建、查询、更新旅行计划)
- 旅行匹配服务 (基于兴趣和时间的匹配算法)
- 动物认领服务 (动物信息管理、认领流程)
- 社交互动服务 (消息发送、通知推送)
#### 1.1.3 商家服务开发
- 商家认证与管理服务
- 商品/服务管理服务
- 订单处理服务
- 评价与反馈服务
#### 1.1.4 支付与安全服务
- 支付服务集成 (微信支付)
- 数据加密与安全传输
- API访问控制与权限管理
### 1.2 前端开发任务
#### 1.2.1 基础框架搭建
- 微信小程序基础框架搭建
- UI组件库集成
- 状态管理配置 (Redux/Vuex类似)
- 网络请求封装
#### 1.2.2 用户端功能开发
- 用户登录/注册页面
- 个人中心页面
- 旅行计划创建与浏览页面
- 旅行伙伴匹配页面
- 动物认领浏览与认领页面
- 消息通知页面
#### 1.2.3 商家端功能开发
- 商家注册与认证页面
- 商家中心首页
- 商品/服务管理页面
- 订单管理页面
- 评价管理页面
### 1.3 数据库开发任务
#### 1.3.1 数据库设计与创建
- 核心表结构创建 (用户、商家、旅行计划等)
- 索引优化
- 数据库分表分库设计
#### 1.3.2 数据库初始化
- 初始化数据脚本编写
- 数据迁移脚本
### 1.4 运维部署任务
#### 1.4.1 基础设施搭建
- Kubernetes集群搭建
- Redis集群部署
- RabbitMQ部署
- 数据库主从复制配置
#### 1.4.2 CI/CD流程配置
- Jenkins/GitLab CI配置
- 自动化测试集成
- 自动化部署脚本
#### 1.4.3 监控与日志
- Prometheus监控配置
- Grafana仪表板配置
- ELK日志收集系统配置
### 1.5 官网系统开发任务
#### 1.5.1 官网基础框架搭建
- Nuxt.js 3框架搭建
- TypeScript配置
- Tailwind CSS集成
- Pinia状态管理配置
- API客户端封装
#### 1.5.2 官网页面开发
- 官网首页开发
- 商家合作页面开发
- 成功案例页面开发
- 关于我们页面开发
- 联系我们页面开发
#### 1.5.3 官网功能开发
- 商家入驻申请功能
- 成功案例展示功能
- 表单验证与提交功能
- 响应式布局适配
#### 1.5.4 官网SEO优化
- 页面SEO元信息配置
- 站点地图生成
- 搜索引擎优化配置
## 2. 工时估算
### 2.1 后端开发工时
#### 2.1.1 基础服务搭建 (15人日)
- 用户认证服务: 3人日
- API网关配置: 2人日
- 微服务间通信机制: 4人日
- 统一配置中心: 3人日
- 日志收集与监控系统: 3人日
#### 2.1.2 核心业务服务开发 (25人日)
- 用户管理服务: 4人日
- 旅行计划服务: 5人日
- 旅行匹配服务: 6人日
- 动物认领服务: 5人日
- 社交互动服务: 5人日
#### 2.1.3 商家服务开发 (20人日)
- 商家认证与管理服务: 5人日
- 商品/服务管理服务: 5人日
- 订单处理服务: 5人日
- 评价与反馈服务: 5人日
#### 2.1.4 支付与安全服务 (10人日)
- 支付服务集成: 5人日
- 数据加密与安全传输: 3人日
- API访问控制与权限管理: 2人日
#### 2.1.5 管理员后台服务 (15人日)
- 用户管理服务: 3人日
- 内容审核服务: 4人日
- 数据统计服务: 4人日
- 权限管理服务: 4人日
**后端开发总工时: 85人日**
### 2.2 前端开发工时
#### 2.2.1 基础框架搭建 (10人日)
- 微信小程序基础框架搭建 (uni-app): 4人日
- UI组件库集成: 2人日
- 状态管理配置 (Pinia): 2人日
- 网络请求封装 (axios): 2人日
#### 2.2.2 用户端功能开发 (25人日)
- 用户登录/注册页面: 3人日
- 个人中心页面: 4人日
- 旅行计划创建与浏览页面: 5人日
- 旅行伙伴匹配页面: 6人日
- 动物认领浏览与认领页面: 4人日
- 消息通知页面: 3人日
#### 2.2.3 商家端功能开发 (20人日)
- 商家注册与认证页面: 4人日
- 商家中心首页: 4人日
- 商品/服务管理页面: 5人日
- 订单管理页面: 4人日
- 评价管理页面: 3人日
#### 2.2.4 管理员后台功能开发 (25人日)
- 管理员登录页面 (Vue 3 + Ant Design): 2人日
- 用户管理页面: 5人日
- 内容管理页面: 5人日
- 数据统计页面: 6人日
- 权限管理页面: 7人日
**前端开发总工时: 80人日**
**项目开发总工时: 85 + 80 + 10 + 27 + 31 = 233人日**
### 2.3 数据库开发工时
#### 2.3.1 数据库设计与创建 (8人日)
- 核心表结构创建: 5人日
- 索引优化: 2人日
- 数据库分表分库设计: 1人日
#### 2.3.2 数据库初始化 (2人日)
- 初始化数据脚本编写: 1人日
- 数据迁移脚本: 1人日
**数据库开发总工时: 10人日**
### 2.4 运维部署工时
#### 2.4.1 基础设施搭建 (15人日)
- Kubernetes集群搭建: 5人日
- Redis集群部署: 3人日
- RabbitMQ部署: 3人日
- 数据库主从复制配置: 4人日
#### 2.4.2 CI/CD流程配置 (8人日)
- Jenkins/GitLab CI配置: 3人日
- 自动化测试集成: 3人日
- 自动化部署脚本: 2人日
#### 2.4.3 监控与日志 (4人日)
- Prometheus监控配置: 2人日
- Grafana仪表板配置: 1人日
- ELK日志收集系统配置: 1人日
**运维部署总工时: 27人日**
### 2.5 官网系统开发工时
#### 2.5.1 官网基础框架搭建 (8人日)
- Nuxt.js 3框架搭建: 3人日
- TypeScript配置: 1人日
- Tailwind CSS集成: 2人日
- Pinia状态管理配置: 1人日
- API客户端封装: 1人日
#### 2.5.2 官网页面开发 (12人日)
- 官网首页开发: 3人日
- 商家合作页面开发: 3人日
- 成功案例页面开发: 2人日
- 关于我们页面开发: 2人日
- 联系我们页面开发: 2人日
#### 2.5.3 官网功能开发 (8人日)
- 商家入驻申请功能: 3人日
- 成功案例展示功能: 2人日
- 表单验证与提交功能: 2人日
- 响应式布局适配: 1人日
#### 2.5.4 官网SEO优化 (3人日)
- 页面SEO元信息配置: 1人日
- 站点地图生成: 1人日
- 搜索引擎优化配置: 1人日
**官网系统开发总工时: 31人日**
## 3. 开发里程碑
### 3.1 第一阶段：基础框架搭建 (预计4周)
- **时间**: 第1-4周
- **目标**: 完成技术架构搭建和基础服务开发
- **交付物**:
- 微服务架构搭建完成
- API网关配置完成
- 用户认证服务上线
- 数据库环境搭建完成
- 基础前端框架搭建完成
- **关键任务**:
- 后端基础设施搭建 (15人日)
- 数据库设计与创建 (8人日)
- 前端基础框架搭建 (10人日)
- 运维环境搭建 (15人日)
### 3.2 第二阶段：核心功能开发 (预计6周)
- **时间**: 第5-10周
- **目标**: 完成用户端核心功能开发
- **交付物**:
- 用户管理功能上线
- 旅行计划功能上线
- 旅行匹配功能上线
- 动物认领功能上线
- 社交互动功能上线
- **关键任务**:
- 后端核心业务服务开发 (25人日)
- 前端用户端功能开发 (25人日)
- 支付服务集成 (5人日)
- 管理员后台服务开发 (8人日)
### 3.3 第三阶段：商家功能开发 (预计5周)
- **时间**: 第11-15周
- **目标**: 完成商家端功能开发和管理员后台功能开发
- **交付物**:
- 商家认证功能上线
- 商品/服务管理功能上线
- 订单处理功能上线
- 评价反馈功能上线
- 管理员后台功能上线
- **关键任务**:
- 后端商家服务开发 (20人日)
- 前端商家端功能开发 (20人日)
- 安全服务完善 (5人日)
- 管理员后台服务开发 (7人日)
- 管理员后台前端开发 (25人日)
### 3.4 第四阶段：官网系统开发 (预计4周)
- **时间**: 第16-19周
- **目标**: 完成官网系统开发和部署
- **交付物**:
- 官网系统上线
- 商家入驻申请功能上线
- 成功案例展示功能上线
- **关键任务**:
- 官网基础框架搭建 (8人日)
- 官网页面开发 (12人日)
- 官网功能开发 (8人日)
- 官网SEO优化 (3人日)
### 3.5 第五阶段：测试与优化 (预计3周)
- **时间**: 第20-22周
- **目标**: 完成系统测试和性能优化
- **交付物**:
- 系统测试报告
- 性能优化报告
- 安全审计报告
- 上线部署包
- **关键任务**:
- 功能测试 (10人日)
- 性能测试与优化 (8人日)
- 安全测试 (5人日)
- 用户验收测试 (5人日)
- 部署上线 (5人日)
## 4. 资源分配建议
### 4.1 人员配置
- **后端开发工程师**: 3人 (其中1人专注管理员后台API开发)
- **前端开发工程师**: 4人 (2人负责小程序前端，1人负责官网前端，1人负责管理员后台前端)
- **数据库工程师**: 1人
- **运维工程师**: 1人
- **测试工程师**: 2人
- **产品经理**: 1人
- **UI/UX设计师**: 2人 (1人负责小程序UI/UX设计，1人负责管理员后台UI/UX设计)
### 4.2 技术资源
- **开发环境**: macOS/Linux开发机 x 8
- **测试环境**: 腾讯云服务器 (2核4GB) x 3
- **生产环境**: 腾讯云服务器 (4核8GB) x 4
- **开发工具**: VS Code, IntelliJ IDEA, Docker, Kubernetes
- **项目管理**: Jira + Confluence
### 4.3 时间安排建议
- **总开发周期**: 25周 (约6个月，增加3周用于管理员后台开发)
- **并行开发**: 后端与前端可并行开发，管理员后台开发与核心功能开发并行
- **迭代周期**: 每2周一个迭代，每周进行代码评审
- **里程碑评审**: 每个阶段结束后进行里程碑评审
### 4.4 风险控制
- **技术风险**: 微服务架构复杂度高，需提前进行技术预研
- **人员风险**: 关键岗位需有备份人员，特别是管理员后台开发人员
- **进度风险**: 预留3周缓冲时间应对不可预见问题（因新增管理员后台功能）
- **质量风险**: 引入自动化测试，保证代码质量，特别是权限管理模块
- **权限安全风险**: RBAC权限模型配置复杂，需严格测试权限控制逻辑
- **官网系统风险**:
- SEO优化效果不达预期
- 浏览器兼容性问题
- 响应式布局在不同设备上显示异常
- **管理员后台风险**:
- 权限控制漏洞可能导致数据泄露
- 操作日志记录不完整影响审计
- 数据统计准确性需要验证

746
docs/requirements.md
View File

@@ -1,746 +0,0 @@
# 结伴客小程序需求文档
## 1. 产品概述
### 1.1 产品名称
结伴客
### 1.2 产品定位
结伴客是一款专注于结伴旅行活动的小程序，与其他交友平台不同的是，它包含了目的地牛、羊、猪、鸡等动物的认领功能，为用户提供独特的旅行体验。
### 1.3 目标用户
#### 普通用户
- 热爱旅行的年轻人
- 希望通过旅行结识新朋友的用户
- 对农场生活和动物互动感兴趣的用户
#### 商家用户
- 花店老板：提供鲜花产品和服务
- 活动组织者：组织各类结伴活动
- 农场老板：提供动物认领和农场体验服务
### 1.4 核心价值
- 为用户提供安全、便捷的结伴旅行服务
- 通过动物认领功能，增加旅行的趣味性和独特性
- 促进用户之间的社交互动，建立旅行伙伴关系
## 2. 功能需求
### 2.1 用户管理
#### 普通用户
- 用户注册/登录
- 个人信息完善（头像、昵称、性别、年龄、兴趣爱好等）
- 个人主页展示
#### 商家用户
- 商家注册/登录（需要资质审核）
- 商家信息完善（店铺名称、营业执照、联系方式、服务介绍等）
- 商家主页展示（包含服务项目、评价等）
### 2.2 旅行结伴
- 发布旅行计划（目的地、时间、天数、预算、兴趣偏好等）
- 浏览和搜索其他用户的旅行计划
- 根据条件匹配相似行程的用户
- 发起结伴邀请
- 接受/拒绝结伴邀请
- 发起和参与其他结伴活动（看电影、拼饭、桌游等）
- 基于定位查看周围或某个区域的目的地信息
### 2.3 动物认领
- 浏览可认领的动物（牛、羊、猪、鸡等）
- 查看动物详情（品种、年龄、性格特点、所在农场等）
- 认领动物（支付认领费用、签订电子协议）
- 查看认领的动物状态（生长记录、健康状况等）
- 与认领的动物互动（视频监控、喂养记录等）
### 2.4 社交互动
- 用户之间发送消息
- 评论和点赞功能
- 分享旅行经历和动物认领体验
### 2.5 安全保障
- 用户评价体系
- 紧急联系功能
- 举报和投诉机制
### 2.6 用户推广奖励机制
- 用户可以通过分享小程序获得推广链接
- 新用户通过推广链接注册可获得奖励
- 推广者根据推广效果获得相应奖励
- 用户分享活动可获得奖励
- 用户分享认养可获得奖励
- 邀请多人认养一个动物可获得奖励
- 推广数据统计和奖励发放机制
- 推广奖励提现功能
### 2.7 送花服务
#### 普通用户功能
- 浏览合作花店的鲜花产品
- 在线选择并订购鲜花
- 选择送花对象（结伴伙伴或特定用户）
- 跟踪送花订单状态
#### 商家用户（花店老板）功能
- 管理鲜花产品（添加、编辑、删除商品信息）
- 管理订单（查看、处理、更新订单状态）
- 设置配送范围和时间
- 查看销售数据和收益统计
### 2.8 官网功能
#### 普通用户功能
- 浏览官网首页，了解平台介绍和核心功能
- 查看成功案例和用户评价
- 浏览动物认领和旅行结伴相关资讯
- 通过官网直接跳转至小程序
#### 商家用户功能
- 通过官网了解平台商业模式和收益机制
- 查看商家合作政策和入驻流程
- 在线提交商家入驻申请（API: POST /api/v1/website/merchant/apply）
- 查看商家成功案例和收益数据（API: GET /api/v1/website/cases）
## 3. 用户故事
### 3.1 旅行结伴功能
#### 故事1：发布旅行计划
**As a** 旅行爱好者
**I want to** 发布我的旅行计划
**So that** 其他用户可以看到我的行程并申请结伴
**验收标准：**
- 用户可以填写目的地、时间、天数、预算等信息
- 用户可以设置行程的可见范围
- 发布成功后，其他用户可以搜索到该行程
### 3.8 官网功能
#### 故事22：浏览官网了解平台信息
**As a** 潜在用户
**I want to** 通过官网了解平台信息
**So that** 我可以更好地了解平台功能并决定是否使用
**验收标准：**
- 用户可以访问官网首页
- 用户可以浏览平台介绍和核心功能
- 用户可以查看成功案例和用户评价
- 用户可以通过官网直接跳转至小程序
#### 故事23：商家通过官网了解合作政策
**As a** 潜在商家
**I want to** 通过官网了解商家合作政策
**So that** 我可以了解入驻条件和收益机制
**验收标准：**
- 商家可以访问官网商家合作页面
- 商家可以查看合作政策和入驻流程
- 商家可以在线提交入驻申请
- 商家可以查看成功案例和收益数据
#### 故事2：寻找结伴伙伴
**As a** 旅行者
**I want to** 根据条件搜索和匹配相似行程的用户
**So that** 我能找到合适的结伴伙伴
**验收标准：**
- 用户可以根据目的地、时间等条件筛选行程
- 系统能推荐匹配度高的行程
- 用户可以查看其他用户的详细信息和评价
#### 故事3：发起结伴邀请
**As a** 旅行者
**I want to** 向匹配的用户发起结伴邀请
**So that** 我可以与他们一起旅行
**验收标准：**
- 用户可以向其他用户发送结伴邀请
- 被邀请用户可以接受或拒绝邀请
- 双方接受邀请后建立结伴关系
#### 故事4：基于定位查看目的地信息
**As a** 旅行者
**I want to** 基于我的位置查看周围的目的地信息
**So that** 我可以发现附近有趣的旅行地点
**验收标准：**
- 用户可以授权小程序获取当前位置
- 系统根据用户位置显示附近的目的地信息
- 用户可以查看目的地的详细信息（距离、评分、特色等）
- 用户可以根据距离、评分等条件筛选目的地
- 用户可以将感兴趣的目的地添加到旅行计划中
#### 故事12：发起其他结伴活动
**As a** 用户
**I want to** 发起看电影、拼饭、桌游等结伴活动
**So that** 我可以与志趣相投的伙伴一起享受休闲时光
**验收标准：**
- 用户可以选择活动类型（看电影、拼饭、桌游等）
- 用户可以设置活动时间、地点、人数要求等信息
- 其他用户可以浏览和申请参加活动
- 发起者可以接受或拒绝参与申请
### 3.2 动物认领功能
#### 故事4：浏览可认领动物
**As a** 对农场生活感兴趣的用户
**I want to** 浏览可认领的动物
**So that** 我可以选择自己喜欢的动物进行认领
**验收标准：**
- 用户可以查看所有可认领的动物列表
- 每个动物都有详细的介绍（品种、年龄、性格特点等）
- 用户可以根据动物类型进行筛选
#### 故事5：认领动物
**As a** 用户
**I want to** 认领我喜欢的动物
**So that** 我可以体验农场生活并与动物互动
**验收标准：**
- 用户可以选择动物并支付认领费用
- 系统生成电子协议供用户签署
- 认领成功后，用户可以在个人中心查看认领的动物
#### 故事6：与认领动物互动
**As a** 动物认领者
**I want to** 通过视频监控和喂养记录与认领的动物互动
**So that** 我可以随时了解动物的状态并参与其成长过程
**验收标准：**
- 用户可以实时查看动物的视频监控
- 用户可以记录喂养情况
- 系统会推送动物的生长记录和健康状况
### 3.3 社交互动功能
#### 故事7：发送消息
**As a** 用户
**I want to** 与其他用户发送消息
**So that** 我可以与他们沟通旅行细节
**验收标准：**
- 用户可以向其他用户发送文本消息
- 用户可以查看聊天记录
- 支持消息提醒功能
#### 故事8：分享旅行经历
**As a** 旅行者
**I want to** 分享我的旅行经历和动物认领体验
**So that** 其他用户可以了解我的旅行故事
**验收标准：**
- 用户可以发布图文动态
- 其他用户可以点赞和评论
- 动态会显示在用户的个人主页
### 3.4 送花服务功能
#### 故事9：浏览并订购鲜花
**As a** 用户
**I want to** 浏览合作花店的鲜花产品并在线订购
**So that** 我可以向结伴伙伴或特定用户表达心意
**验收标准：**
- 用户可以浏览合作花店的鲜花产品
- 用户可以选择鲜花并添加到购物车
- 用户可以完成在线支付
- 系统将订单信息同步至实体花店
#### 故事10：选择送花对象
**As a** 用户
**I want to** 选择送花对象
**So that** 我可以将鲜花送给特定的人
**验收标准：**
- 用户可以从结伴伙伴列表中选择送花对象
- 用户可以通过搜索选择其他用户作为送花对象
- 系统会显示送花对象的基本信息
#### 故事11：跟踪送花订单
**As a** 用户
**I want to** 跟踪送花订单状态
**So that** 我可以了解鲜花送达情况
**验收标准：**
- 用户可以在个人中心查看送花订单列表
- 用户可以查看每个订单的当前状态（已下单、已接单、配送中、已完成）
- 系统会在订单状态更新时推送通知
#### 故事18：管理鲜花产品
**As a** 花店老板
**I want to** 管理我的鲜花产品
**So that** 我可以向用户提供最新的产品信息
**验收标准：**
- 商家可以添加新的鲜花产品（图片、名称、价格、描述等）
- 商家可以编辑现有产品信息
- 商家可以删除下架的产品
- 用户可以浏览到更新后的产品信息
#### 故事19：管理订单
**As a** 花店老板
**I want to** 管理用户的送花订单
**So that** 我可以及时处理订单并提供配送服务
**验收标准：**
- 商家可以在商家中心查看所有订单
- 商家可以更新订单状态（已接单、配送中、已完成）
- 系统会向用户推送订单状态更新通知
- 商家可以查看订单统计信息
### 3.5 用户推广奖励机制
#### 故事12：获取推广链接
**As a** 用户
**I want to** 获取专属推广链接
**So that** 我可以分享给朋友并获得奖励
**验收标准：**
- 用户可以在个人中心找到推广功能入口
- 系统为每个用户生成唯一的推广链接
- 用户可以通过多种方式分享推广链接（微信、朋友圈等）
#### 故事13：查看推广数据和奖励
**As a** 用户
**I want to** 查看我的推广数据和奖励情况
**So that** 我可以了解推广效果和收益
**验收标准：**
- 用户可以在个人中心查看推广数据（推广人数、成功注册数等）
- 用户可以查看累计获得的奖励金额
- 用户可以查看奖励发放记录
#### 故事14：提现推广奖励
**As a** 用户
**I want to** 提现我的推广奖励
**So that** 我可以将奖励转换为实际收益
**验收标准：**
- 用户可以在个人中心申请提现
- 用户需要绑定提现账户（微信钱包等）
- 系统处理提现申请并在规定时间内到账
### 3.6 活动分享奖励
#### 故事15：分享活动获得奖励
**As a** 用户
**I want to** 分享我参与的活动
**So that** 我可以获得奖励并邀请更多人参与
**验收标准：**
- 用户可以分享自己参与的结伴活动
- 系统记录分享行为并给予相应奖励
- 被邀请用户通过分享链接参与活动时，分享者可获得额外奖励
### 3.7 认养分享奖励
#### 故事16：分享认养获得奖励
**As a** 用户
**I want to** 分享我的动物认养
**So that** 我可以获得奖励并让更多人了解认养
**验收标准：**
- 用户可以分享自己认养的动物信息
- 系统记录分享行为并给予相应奖励
- 其他用户通过分享链接认养动物时，分享者可获得额外奖励
### 3.8 多人认养奖励
#### 故事17：邀请多人认养一个动物
**As a** 用户
**I want to** 邀请朋友一起认养一个动物
**So that** 我可以与朋友共同体验认养乐趣并获得奖励
**验收标准：**
- 用户可以邀请朋友共同认养一个动物
- 系统支持多人认养同一个动物
- 成功邀请朋友认养后，邀请者可获得奖励
### 3.9 活动组织者功能
#### 故事20：发布和管理结伴活动
**As a** 活动组织者
**I want to** 发布和管理结伴活动
**So that** 我可以为用户提供丰富的活动选择
**验收标准：**
- 活动组织者可以发布新的结伴活动（类型、时间、地点、费用等）
- 活动组织者可以编辑已发布的活动信息
- 活动组织者可以查看活动报名情况
- 活动组织者可以取消活动并通知报名用户
### 3.10 农场老板功能
#### 故事21：管理动物认领信息
**As a** 农场老板
**I want to** 管理农场动物认领信息
**So that** 我可以为用户提供准确的认领服务
**验收标准：**
- 农场老板可以添加新的可认领动物
- 农场老板可以更新动物状态信息（生长记录、健康状况等）
- 农场老板可以查看认领情况和认领者信息
- 农场老板可以设置认领费用和条件
### 3.11 管理员后台功能
#### 故事24：用户管理
**As a** 系统管理员
**I want to** 管理平台用户信息
**So that** 我可以维护平台用户质量和安全
**验收标准：**
- 管理员可以查看所有用户列表
- 管理员可以搜索和筛选用户（按注册时间、状态等）
- 管理员可以禁用/启用用户账号
- 管理员可以查看用户详细信息（注册信息、活动记录等）
- 管理员可以导出用户数据报表
#### 故事25：商家审核
**As a** 系统管理员
**I want to** 审核商家入驻申请
**So that** 我可以确保商家资质合规
**验收标准：**
- 管理员可以查看待审核的商家申请列表
- 管理员可以查看商家提交的资质证明材料
- 管理员可以批准或拒绝商家申请
- 系统会向商家发送审核结果通知
- 审核通过的商家账号自动激活
#### 故事26：内容审核
**As a** 系统管理员
**I want to** 审核用户发布的内容
**So that** 我可以维护平台内容质量
**验收标准：**
- 管理员可以查看待审核的内容列表（旅行计划、动态、评论等）
- 管理员可以审核并通过合规内容
- 管理员可以拒绝或删除违规内容
- 系统会记录审核操作日志
- 用户会收到内容审核结果通知
#### 故事27：数据统计
**As a** 系统管理员
**I want to** 查看平台运营数据
**So that** 我可以监控平台运营状况
**验收标准：**
- 管理员可以查看用户注册趋势图表
- 管理员可以查看订单和交易统计
- 管理员可以查看各功能模块使用情况
- 管理员可以导出数据报表
- 系统提供数据可视化仪表盘
#### 故事28：权限管理
**As a** 系统管理员
**I want to** 管理管理员账号权限
**So that** 我可以控制不同管理员的访问权限
**验收标准：**
- 管理员可以创建和管理其他管理员账号
- 管理员可以分配不同的权限角色
- 系统支持RBAC权限控制模型
- 权限变更会记录操作日志
- 管理员只能访问其权限范围内的功能
## 4. 非功能性需求
### 4.1 性能需求
- 页面加载时间不超过3秒
- 支持同时在线用户数1000人
- 商家服务页面加载时间不超过2秒
### 4.2 安全需求
- 用户数据加密存储
- 敏感操作需要二次确认
- 防止SQL注入和XSS攻击
- 商家资质信息加密存储
- 商家与用户交易记录加密存储
- 商家服务评价数据防篡改
### 4.3 兼容性需求
- 支持微信小程序平台
- 兼容不同屏幕尺寸的移动设备
- 管理员后台支持主流浏览器（Chrome、Firefox、Safari、Edge）
### 4.4 管理员后台特殊需求
#### 4.4.1 安全需求
- 管理员操作需要双重身份验证
- 敏感操作（用户封禁、资金操作等）需要二次确认
- 管理员登录IP地址限制和异常登录检测
- 操作日志完整记录且不可篡改
- 权限分级管理，不同角色管理员拥有不同操作权限
#### 4.4.2 性能需求
- 管理员后台页面加载时间不超过2秒
- 大数据量查询响应时间不超过5秒
- 支持同时在线管理员用户数50人
- 批量操作处理能力（如批量审核、批量导出）
#### 4.4.3 可靠性需求
- 关键管理操作支持事务回滚
- 系统异常时自动保存操作进度
- 数据备份和恢复机制
- 7×24小时运维监控
## 5. 优先级建议
### 5.1 功能优先级（MoSCoW模型）
**Must Have（必须有）：**
- 用户注册/登录
- 发布和浏览旅行计划
- 基本的结伴匹配功能
- 动物认领核心功能
**Should Have（应该有）：**
- 用户评价体系
- 消息发送功能
- 动物状态查看
- 其他结伴活动功能
- 用户推广奖励机制
- 活动分享奖励功能
- 认养分享奖励功能
- 多人认养奖励功能
- 商家用户管理功能
- 花店商家功能
- 活动组织者功能
- 农场老板功能
- 官网功能
- 管理员后台基础功能（用户管理、内容审核）
**Could Have（可以有）：**
- 视频监控功能
- 个性化推荐算法
- 社区动态分享
- 送花服务基础功能
- 基于定位查看目的地信息功能
**Won't Have（不会有）：**
- 虚拟现实农场体验
- AI智能行程规划
- 虚拟送花效果预览
## 6. 原型构思
### 6.1 主要界面
#### 首页
- 顶部搜索栏（搜索目的地、用户、动物）
- 轮播图展示热门旅行路线和动物认领活动
- 两个主要功能入口："找搭子"和"认领动物"
- 推荐的旅行计划列表
#### 旅行计划页面
- 发布旅行计划按钮
- 筛选条件（目的地、时间、预算等）
- 旅行计划卡片列表（显示基本信息和匹配度）
#### 结伴活动页面
- 发布结伴活动按钮
- 活动类型筛选（看电影、拼饭、桌游等）
- 活动卡片列表（显示活动类型、时间、地点、参与人数等信息）
#### 动物认领页面
- 动物分类筛选
- 动物卡片列表（显示动物图片、基本信息）
- 认领排行榜（最受欢迎的动物）
#### 个人中心
- 用户头像和基本信息
- 我的旅行计划
- 我认领的动物
- 我的送花记录
- 我的推广奖励
- 我的活动分享
- 我的认养分享
- 多人认养邀请
- 消息通知
- 设置选项
#### 送花服务页面
- 鲜花产品展示（图片、价格、花语介绍）
- 分类筛选（节日、用途、价格区间等）
- 购物车功能
- 订单确认页面（选择送花对象、填写祝福语、选择配送时间）
#### 推广奖励页面
- 推广链接展示和复制功能
- 二维码推广海报生成
- 推广数据统计图表（推广人数、注册人数、收益等）
- 奖励明细列表
- 提现功能入口
#### 定位功能页面
- 基于用户当前位置显示附近的目的地
- 地图视图展示目的地位置
- 目的地列表视图（包含距离、评分等信息）
- 筛选功能（按距离、评分、特色等条件筛选）
- 搜索功能（搜索特定区域或目的地）
#### 活动分享页面
- 用户参与的活动列表
- 活动分享按钮和分享统计
- 分享奖励记录
#### 认养分享页面
- 用户认养的动物列表
- 动物分享按钮和分享统计
- 分享奖励记录
#### 多人认养邀请页面
- 可邀请的动物列表
- 邀请好友功能
- 邀请记录和奖励明细
#### 商家中心首页
- 商家信息展示
- 服务概览（订单数、收益、评价等）
- 快捷操作入口（发布产品、查看订单等）
#### 官网首页
- 平台介绍和核心功能展示
- 成功案例和用户评价展示
- 动物认领和旅行结伴相关资讯
- 小程序跳转入口
#### 商家合作页面
- 平台商业模式和收益机制介绍
- 商家合作政策和入驻流程
- 在线入驻申请表单
- 商家成功案例和收益数据展示
#### 管理员登录页面
- 管理员账号密码登录
- 双重身份验证
- 忘记密码功能
- 安全登录提示
#### 管理员仪表盘
- 平台运营数据概览（用户数、订单数、交易额等）
- 实时数据图表展示
- 待处理事项提醒（待审核商家、待审核内容等）
- 系统状态监控
#### 用户管理页面
- 用户列表展示（支持搜索和筛选）
- 用户详细信息查看
- 账号状态管理（启用/禁用）
- 用户行为记录查看
- 数据导出功能
#### 商家审核页面
- 待审核商家列表
- 商家资质材料查看
- 审核操作（通过/拒绝）
- 审核意见填写
- 审核历史记录
#### 内容审核页面
- 待审核内容列表（旅行计划、动态、评论等）
- 内容详情查看
- 批量审核功能
- 审核标准说明
- 违规内容处理记录
#### 数据统计页面
- 用户增长趋势图表
- 订单和交易统计分析
- 各功能模块使用情况统计
- 自定义报表生成
- 数据导出和下载
#### 权限管理页面
- 管理员账号列表
- 角色权限配置
- 操作日志查看
- 权限变更记录
#### 商品管理页面
- 商品列表展示
- 添加/编辑商品功能
- 商品状态管理（上架/下架）
#### 订单管理页面
- 订单列表展示
- 订单状态更新功能
- 订单详情查看
#### 活动管理页面
- 活动列表展示
- 发布/编辑活动功能
- 活动报名情况查看
#### 动物管理页面
- 可认领动物列表
- 添加/编辑动物信息功能
- 动物状态更新功能
### 6.2 核心流程
#### 结伴流程：
1. 用户发布旅行计划
2. 系统匹配相似行程
3. 用户发起结伴邀请
4. 被邀请用户接受邀请
5. 双方建立结伴关系，开始沟通
#### 认领流程：
1. 用户浏览可认领动物
2. 选择心仪动物
3. 支付认领费用
4. 签署电子协议
5. 开始与动物互动
#### 商家服务流程：
1. 商家注册并完善信息
2. 商家发布服务/产品
3. 用户浏览并选择服务/产品
4. 用户下单并支付
5. 商家处理订单
6. 服务完成，用户评价
#### 管理员审核流程：
1. 商家/用户提交申请或内容
2. 系统将待审核项加入审核队列
3. 管理员登录后台查看待处理事项
4. 管理员审核申请/内容
5. 系统记录审核结果并通知申请人
6. 审核通过的内容/申请正式生效
#### 权限管理流程：
1. 超级管理员创建新的管理员账号
2. 分配相应的权限角色
3. 管理员使用分配的权限登录后台
4. 系统根据权限控制功能访问范围
5. 所有操作记录日志供审计使用
## 7. 验收标准
### 7.1 功能验收
- 所有用户故事的验收标准均已满足
- 功能测试通过率达到95%以上
- 用户界面符合设计要求
### 7.2 性能验收
- 页面加载时间符合要求
- 系统稳定性测试通过
- 压力测试达到预期指标
### 7.3 安全验收
- 安全测试通过
- 用户隐私保护符合法规要求
- 管理员后台权限控制符合RBAC模型要求
- 操作日志完整且不可篡改
- 敏感操作二次确认机制正常工作
### 7.4 管理员后台专项验收
- 所有管理员功能用户故事验收标准均已满足
- 后台页面加载性能符合要求（≤2秒）
- 大数据量查询响应时间符合要求（≤5秒）
- 批量操作功能正常工作
- 数据导出功能完整可用
- 权限分级控制准确无误

339
docs/website_requirements.md
View File

@@ -1,339 +0,0 @@
# 结伴客官网产品需求文档
## 版本历史
| 版本 | 日期 | 作者 | 描述 |
|------|------|------|------|
| v1.0 | 2024-01-15 | 产品经理 | 初始版本，定义官网核心需求 |
| v1.1 | 2024-01-16 | 产品经理 | 补充SEO优化和性能需求 |
## 1. 项目概述
### 1.1 项目背景
结伴客是一个专注于结伴旅行和动物认领的创新平台，官网作为品牌展示和用户转化的重要渠道，需要提供专业、可信的线上门户。
### 1.2 项目目标
- **品牌展示**：建立专业、可信的品牌形象
- **用户转化**：引导用户下载和使用小程序
- **商家合作**：吸引优质商家入驻平台
- **信息传递**：清晰传达平台价值和服务内容
### 1.3 成功标准
- **访问量指标**：月均PV ≥ 50,000，UV ≥ 10,000
- **转化率指标**：小程序跳转转化率 ≥ 15%
- **商家入驻**：月均商家入驻申请 ≥ 20家
- **SEO表现**：核心关键词搜索引擎排名前3页
- **性能指标**：页面加载时间 ≤ 2秒，首屏时间 ≤ 1秒
## 2. 用户角色与用例
### 2.1 目标用户群体
#### 2.1.1 普通用户（C端用户）
- **特征**：18-45岁，热爱旅行，对新鲜事物感兴趣
- **使用场景**：了解平台功能，寻找旅行伙伴，体验动物认领
- **核心需求**：快速了解平台价值，便捷跳转小程序
#### 2.1.2 商家用户（B端用户）
- **特征**：花店老板、农场主、活动组织者
- **使用场景**：了解合作政策，提交入驻申请
- **核心需求**：清晰的合作流程，便捷的申请入口
#### 2.1.3 潜在投资者
- **特征**：投资机构、个人投资者
- **使用场景**：了解商业模式，评估投资价值
- **核心需求**：专业的品牌形象，清晰的商业模式展示
### 2.2 用户用例图
```mermaid
graph TB
A[普通用户] --> B[浏览官网首页]
A --> C[查看成功案例]
A --> D[跳转小程序]
E[商家用户] --> F[查看合作政策]
E --> G[提交入驻申请]
E --> H[查看收益数据]
I[潜在投资者] --> J[了解商业模式]
I --> K[查看团队介绍]
I --> L[联系商务合作]
```
## 3. 功能需求
### 3.1 官网首页模块
#### 用户故事1：浏览官网首页
**As a** 新用户
**I want to** 快速了解平台核心价值
**So that** 我可以决定是否使用结伴客平台
**验收标准：**
- **Given** 用户访问官网首页
- **When** 页面加载完成
- **Then** 显示平台品牌Logo和slogan
- **And** 展示核心功能区块（旅行结伴、动物认领、送花服务）
- **And** 显示小程序跳转入口
- **And** 提供商家合作入口
#### 用户故事2：查看平台介绍
**As a** 潜在用户
**I want to** 详细了解平台功能特色
**So that** 我可以全面了解平台价值
**验收标准：**
- **Given** 用户在首页
- **When** 滚动浏览功能介绍区块
- **Then** 展示动态交互效果
- **And** 每个功能区块包含图标、标题和详细描述
- **And** 提供数据统计展示（用户数、成功案例数等）
### 3.2 成功案例模块
#### 用户故事3：浏览成功案例
**As a** 犹豫用户
**I want to** 查看其他用户的真实体验
**So that** 我可以增强对平台的信任
**验收标准：**
- **Given** 用户访问成功案例页面
- **When** 页面加载完成
- **Then** 显示分类筛选（旅行结伴、动物认领、送花服务）
- **And** 展示案例卡片，包含用户头像、故事摘要、成果数据
- **And** 支持分页加载，每页显示12个案例
- **And** 提供案例详情查看功能
#### 用户故事4：分享成功案例
**As a** 满意用户
**I want to** 分享我的成功故事
**So that** 我可以帮助平台吸引更多用户
**验收标准：**
- **Given** 用户在案例详情页
- **When** 点击分享按钮
- **Then** 弹出分享选项（微信、朋友圈、QQ、微博）
- **And** 生成带参数的分享链接
- **And** 记录分享行为用于数据统计
### 3.3 商家合作模块
#### 用户故事5：了解合作政策
**As a** 潜在商家
**I want to** 详细了解合作政策和收益模式
**So that** 我可以评估入驻价值
**验收标准：**
- **Given** 用户访问商家合作页面
- **When** 页面加载完成
- **Then** 显示合作流程图表
- **And** 展示收益计算器和案例数据
- **And** 提供不同商家类型（花店、农场、活动组织者）的专属政策
- **And** 显示入驻要求和资质说明
#### 用户故事6：提交入驻申请
**As a** 商家用户
**I want to** 在线提交入驻申请
**So that** 我可以快速启动合作流程
**验收标准：**
- **Given** 用户在商家合作页面
- **When** 点击"立即申请"按钮
- **Then** 弹出入驻申请表单
- **And** 表单包含必填字段：商家类型、联系人、电话、营业执照等
- **And** 支持图片上传功能
- **And** 提交后显示成功提示
- **And** 系统自动发送确认邮件
### 3.4 关于我们模块
#### 用户故事7：了解公司信息
**As a** 关注用户
**I want to** 了解公司背景和团队信息
**So that** 我可以建立对品牌的信任
**验收标准：**
- **Given** 用户访问关于我们页面
- **When** 页面加载完成
- **Then** 显示公司发展历程时间轴
- **And** 展示核心团队介绍（CEO、CTO、COO、CMO）
- **And** 提供联系方式和企业地址
- **And** 显示合作伙伴logo墙
### 3.5 小程序导流模块
#### 用户故事8：跳转小程序
**As a** 官网访客
**I want to** 快速跳转到小程序
**So that** 我可以立即体验平台功能
**验收标准：**
- **Given** 用户在官网任意页面
- **When** 点击小程序跳转按钮
- **Then** 显示小程序二维码
- **And** 提供"打开小程序"深度链接
- **And** 引导用户保存二维码
- **And** 记录跳转转化数据
## 4. 非功能需求
### 4.1 性能需求
- **页面加载**：首屏加载时间 ≤ 1秒，完全加载时间 ≤ 2秒
- **响应时间**：API接口响应时间 ≤ 200ms
- **并发支持**：支持1000并发用户访问
- **资源优化**：图片懒加载，资源压缩，CDN加速
### 4.2 安全需求
- **数据安全**：敏感信息加密传输，防止XSS和CSRF攻击
- **表单安全**：入驻申请表单防垃圾提交，验证码保护
- **权限控制**：后台管理接口权限验证
- **日志审计**：关键操作日志记录
### 4.3 兼容性需求
- **浏览器兼容**：Chrome 80+、Firefox 75+、Safari 13+、Edge 80+
- **设备兼容**：支持桌面端、平板、手机响应式布局
- **分辨率适配**：支持1920px、1366px、768px、375px等常见分辨率
### 4.4 SEO优化需求
- **元标签优化**：每个页面独立的title、description、keywords
- **结构化数据**：使用Schema.org标记关键内容
- **站点地图**：自动生成XML sitemap
- **页面速度**：Google PageSpeed Insights评分 ≥ 90
- **移动友好**：通过Google移动友好测试
### 4.5 可维护性需求
- **代码规范**：遵循HTML5语义化标签和Bootstrap最佳实践
- **模块化开发**：基于文件目录结构的模块分离
- **文档完整**：页面结构和组件说明文档齐全
- **浏览器兼容**：确保主流浏览器兼容性测试
## 5. 原型与交互设计
### 5.1 页面结构
#### 首页布局
```
┌─────────────────────────────────────┐
│ Header │
│ - Logo + Brand Name │
│ - Navigation Menu │
│ - CTA Buttons (小程序/商家入驻) │
├─────────────────────────────────────┤
│ Hero Section │
│ - 主标题和副标题 │
│ - 数据统计展示 │
│ - 主要行动按钮 │
├─────────────────────────────────────┤
│ Features Section │
│ - 三大核心功能展示 │
│ - 图标+标题+描述 │
│ - 交互式动画效果 │
├─────────────────────────────────────┤
│ Success Stories │
│ - 精选案例展示 │
│ - 用户头像和评价 │
│ - 查看全部案例链接 │
├─────────────────────────────────────┤
│ Call to Action │
│ - 强化转化提示 │
│ - 多渠道入口 │
├─────────────────────────────────────┤
│ Footer │
│ - 网站地图链接 │
│ - 社交媒体链接 │
│ - 联系信息和备案号 │
└─────────────────────────────────────┘
```
#### 商家合作页面关键元素
- **价值主张**：清晰展示合作收益和优势
- **流程可视化**：使用时间轴或流程图展示合作步骤
- **数据证明**：展示成功商家案例和收益数据
- **表单设计**：分步表单，减少用户填写压力
- **信任要素**：资质认证、安全保障说明
### 5.2 交互设计原则
- **简洁明了**：信息层级清晰，重点突出
- **引导性强**：明确的行动号召和转化路径
- **反馈及时**：操作反馈和状态提示明确
- **移动优先**：优先保证移动端体验
- **无障碍设计**：支持键盘导航和屏幕阅读器
## 6. 技术架构
### 6.1 前端技术栈
- **核心技术**：HTML5 + CSS3 + JavaScript (ES6+)
- **UI框架**：Bootstrap 5.3.0
- **图标库**：Font Awesome 6.7.2
- **动画效果**：AOS (Animate On Scroll) 2.3.4
- **交互增强**：jQuery 3.6.0
- **表单验证**：原生JavaScript验证 + Bootstrap表单组件
- **响应式设计**：Bootstrap网格系统 + 媒体查询
### 6.2 后端集成
- **API接口**：RESTful API规范
- **认证方式**：JWT Token认证
- **数据格式**：JSON格式数据交换
- **错误处理**：统一错误码和消息格式
### 6.3 部署架构
- **静态资源**：Nginx静态文件服务 + CDN加速分发
- **构建部署**：直接文件部署，无需构建过程
- **环境配置**：多环境配置文件管理
- **缓存策略**：浏览器缓存 + CDN缓存优化
- **监控告警**：基础性能监控 + 错误日志监控
## 7. 项目计划
### 7.1 开发阶段
| 阶段 | 时间 | 主要任务 | 交付物 |
|------|------|---------|--------|
| 需求确认 | 第1周 | 需求评审，原型确认 | PRD文档，原型设计 |
| 技术设计 | 第2周 | 技术方案设计，环境搭建 | 技术设计文档 |
| 开发实现 | 第3-6周 | 前端开发，后端接口联调 | 可运行版本 |
| 测试验收 | 第7周 | 功能测试，性能测试 | 测试报告 |
| 上线部署 | 第8周 | 生产部署，监控配置 | 线上环境 |
### 7.2 资源分配
- **前端开发**：1-2人（3周）
- **后端支持**：1人（1周，主要处理表单提交接口）
- **测试验证**：1人（1周）
- **项目管理**：1人（全程）
## 8. 风险控制
### 8.1 技术风险
- **浏览器兼容性**：制定兼容性矩阵，优先支持现代浏览器
- **性能瓶颈**：提前进行性能预估和优化方案设计
- **第三方依赖**：选择稳定版本，制定降级方案
### 8.2 项目风险
- **需求变更**：建立变更控制流程
- **进度延迟**：设置缓冲时间，定期进度检查
- **质量风险**：代码审查，自动化测试覆盖
### 8.3 运营风险
- **SEO效果**：持续优化和内容更新
- **转化率**：A/B测试优化转化路径
- **安全漏洞**：定期安全扫描和漏洞修复
## 9. 附录
### 9.1 名词解释
- **PV（Page View）**：页面浏览量
- **UV（Unique Visitor）**：独立访客数
- **转化率**：完成目标动作的用户比例
- **CDN**：内容分发网络
- **JWT**：JSON Web Token认证方式
### 9.2 相关文档
- [系统架构文档](./architecture.md)
- [API接口文档](./API_DOCS.md)
- [数据库设计文档](./database-design.md)
- [开发指南](./DEVELOPMENT_GUIDE.md)
### 9.3 修订记录
| 日期 | 版本 | 修订内容 | 修订人 |
|------|------|---------|--------|
| 2024-01-15 | v1.0 | 创建初始版本 | 产品经理 |
| 2024-01-16 | v1.1 | 补充SEO和性能指标 | 产品经理 |

996
docs/开发指南.md Normal file
View File

@@ -0,0 +1,996 @@
# 🚀 结伴客开发指南
## 📋 项目概述
结伴客是一个基于微信小程序的结伴旅行和动物认领平台。本开发指南旨在帮助开发者快速上手项目开发，理解项目架构，并遵循统一的开发规范。
## 🛠️ 开发环境搭建
### 系统要求
#### 前端开发环境
- **Node.js**: 16.0+ (推荐使用 18.x LTS)
- **npm**: 8.0+ 或 **yarn**: 1.22+
- **微信开发者工具**: 最新稳定版
- **IDE**: VS Code (推荐) / WebStorm
- **Git**: 2.30+
#### 后端开发环境
- **JDK**: Java 17 (推荐使用 OpenJDK)
- **Maven**: 3.6+
- **IDE**: IntelliJ IDEA (推荐) / Eclipse / VS Code
- **数据库**: MySQL 8.0+
- **缓存**: Redis 6.0+
- **消息队列**: RabbitMQ 3.8+
- **容器化**: Docker 20.10+ 和 Docker Compose 1.29+
### 环境安装
#### macOS 环境安装
```bash
# 使用 Homebrew 安装开发工具
# 安装 Node.js
brew install node
# 安装 Java 17
brew install openjdk@17
# 安装 Maven
brew install maven
# 安装 Docker
brew install docker docker-compose
# 安装 MySQL
brew install mysql
# 安装 Redis
brew install redis
```
#### Windows 环境安装
1. **Node.js**: 从 [官网](https://nodejs.org/) 下载安装
2. **JDK 17**: 从 [Adoptium](https://adoptium.net/) 下载安装
3. **Maven**: 从 [官网](https://maven.apache.org/) 下载配置
4. **Docker Desktop**: 从 [官网](https://www.docker.com/products/docker-desktop) 下载安装
5. **微信开发者工具**: 从 [官网](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html) 下载安装
#### Ubuntu/Debian 环境安装
```bash
# 更新包管理器
sudo apt update
# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# 安装 Java 17
sudo apt install openjdk-17-jdk
# 安装 Maven
sudo apt install maven
# 安装 Docker
sudo apt install docker.io docker-compose
# 安装 MySQL
sudo apt install mysql-server
# 安装 Redis
sudo apt install redis-server
```
### 环境验证
```bash
# 验证 Node.js 和 npm
node --version
npm --version
# 验证 Java 和 Maven
java -version
mvn -version
# 验证 Docker
docker --version
docker-compose --version
# 验证数据库连接
mysql --version
redis-cli --version
```
## 🏗️ 项目架构
### 整体架构
```mermaid
graph TB
A[微信小程序前端] --> B[API网关]
C[管理后台前端] --> B
D[官网前端] --> B
B --> E[认证服务]
B --> F[用户服务]
B --> G[旅行服务]
B --> H[动物服务]
B --> I[订单服务]
B --> J[商家服务]
E --> K[MySQL数据库]
F --> K
G --> K
H --> K
I --> K
J --> K
E --> L[Redis缓存]
F --> L
G --> L
H --> L
subgraph "服务注册与发现"
M[Eureka Server]
end
E --> M
F --> M
G --> M
H --> M
I --> M
J --> M
```
### 目录结构
```
jiebanke/
├── frontend/ # 前端项目
│ ├── miniprogram/ # 微信小程序
│ ├── admin-web/ # 管理后台
│ └── website/ # 官方网站
├── backend-java/ # Java后端服务
│ ├── eureka-server/ # 服务注册中心
│ ├── gateway-service/ # API网关
│ ├── auth-service/ # 认证服务
│ ├── user-service/ # 用户服务
│ ├── travel-service/ # 旅行服务
│ ├── animal-service/ # 动物服务
│ ├── order-service/ # 订单服务
│ ├── merchant-service/ # 商家服务
│ └── common/ # 公共模块
├── docs/ # 项目文档
├── scripts/ # 部署脚本
└── docker-compose.yml # Docker编排文件
```
## 📝 开发规范
### 1. 代码规范
#### 前端代码规范
##### JavaScript/TypeScript 规范
```javascript
// ✅ 推荐写法
const getUserInfo = async (userId) => {
try {
const response = await api.get(`/users/${userId}`);
return response.data;
} catch (error) {
console.error('获取用户信息失败:', error);
throw error;
}
};
// ❌ 不推荐写法
function getUserInfo(userId) {
return new Promise((resolve, reject) => {
api.get('/users/' + userId).then(res => {
resolve(res.data);
}).catch(err => {
reject(err);
});
});
}
```
##### Vue 组件规范
```vue
<template>
<div class="user-profile">
<div class="user-avatar">
<image :src="userInfo.avatar" mode="aspectFill" />
</div>
<div class="user-info">
<text class="username">{{ userInfo.nickname }}</text>
<text class="user-desc">{{ userInfo.description }}</text>
</div>
</div>
</template>
<script>
export default {
name: 'UserProfile',
props: {
userInfo: {
type: Object,
required: true,
default: () => ({})
}
},
data() {
return {
// 组件内部状态
};
},
computed: {
// 计算属性
},
methods: {
// 组件方法
}
};
</script>
<style scoped>
.user-profile {
display: flex;
align-items: center;
padding: 20rpx;
}
.user-avatar {
width: 100rpx;
height: 100rpx;
border-radius: 50%;
overflow: hidden;
margin-right: 20rpx;
}
.user-info {
flex: 1;
}
.username {
font-size: 32rpx;
font-weight: bold;
color: #333;
}
.user-desc {
font-size: 28rpx;
color: #666;
margin-top: 10rpx;
}
</style>
```
#### 后端代码规范
##### Java 命名规范
```java
// ✅ 推荐写法
public class UserService {
private static final int MAX_RETRY_COUNT = 3;
private final UserMapper userMapper;
/**
* 根据用户ID获取用户信息
*
* @param userId 用户ID
* @return 用户信息
* @throws BusinessException 当用户不存在时抛出
*/
public UserDTO getUserById(Long userId) {
if (userId == null || userId <= 0) {
throw new IllegalArgumentException("用户ID不能为空或小于等于0");
}
User user = userMapper.selectById(userId);
if (user == null) {
throw new BusinessException(ErrorCode.USER_NOT_FOUND, "用户不存在");
}
return UserConverter.toDTO(user);
}
}
// ❌ 不推荐写法
public class userservice {
public Object getuser(Object id) {
return userMapper.selectById((Long)id);
}
}
```
##### Spring Boot 控制器规范
```java
@RestController
@RequestMapping("/api/v1/users")
@Validated
@Slf4j
public class UserController {
private final UserService userService;
public UserController(UserService userService) {
this.userService = userService;
}
@GetMapping("/{id}")
@Operation(summary = "获取用户信息", description = "根据用户ID获取用户详细信息")
public ApiResponse<UserDTO> getUserById(
@PathVariable @Min(1) Long id) {
log.info("获取用户信息, userId: {}", id);
try {
UserDTO user = userService.getUserById(id);
return ApiResponse.success(user);
} catch (BusinessException e) {
log.warn("获取用户信息失败, userId: {}, error: {}", id, e.getMessage());
return ApiResponse.error(e.getCode(), e.getMessage());
} catch (Exception e) {
log.error("获取用户信息系统错误, userId: {}", id, e);
return ApiResponse.error(ErrorCode.SYSTEM_ERROR, "系统错误");
}
}
}
```
### 2. 数据库规范
#### 表设计规范
```sql
-- ✅ 推荐的表结构设计
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
openid VARCHAR(100) UNIQUE NOT NULL COMMENT '微信openid',
nickname VARCHAR(50) NOT NULL COMMENT '用户昵称',
avatar VARCHAR(255) COMMENT '头像URL',
gender ENUM('male', 'female', 'unknown') DEFAULT 'unknown' COMMENT '性别',
phone VARCHAR(20) UNIQUE COMMENT '手机号码',
status ENUM('active', 'inactive', 'banned') DEFAULT 'active' COMMENT '用户状态',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
INDEX idx_openid (openid),
INDEX idx_phone (phone),
INDEX idx_status (status),
INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户基础信息表';
```
#### SQL 查询规范
```sql
-- ✅ 推荐的查询写法
SELECT
u.id,
u.nickname,
u.avatar,
u.created_at
FROM users u
WHERE u.status = 'active'
AND u.created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)
ORDER BY u.created_at DESC
LIMIT 20;
-- ❌ 不推荐的查询写法
select * from users where status='active' order by created_at desc;
```
### 3. API 接口规范
#### RESTful API 设计
```javascript
// ✅ 推荐的API设计
GET /api/v1/users // 获取用户列表
GET /api/v1/users/{id} // 获取单个用户
POST /api/v1/users // 创建用户
PUT /api/v1/users/{id} // 更新用户
DELETE /api/v1/users/{id} // 删除用户
GET /api/v1/users/{id}/travels // 获取用户的旅行计划
POST /api/v1/travels // 创建旅行计划
// ❌ 不推荐的API设计
GET /api/getUserList
POST /api/createUser
GET /api/user_travels?userId=123
```
#### 统一响应格式
```json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"nickname": "张三",
"avatar": "https://example.com/avatar.jpg"
},
"timestamp": "2025-01-15T10:30:00Z"
}
```
#### 错误响应格式
```json
{
"code": 400,
"message": "参数错误",
"data": null,
"errors": [
{
"field": "phone",
"message": "手机号格式不正确"
}
],
"timestamp": "2025-01-15T10:30:00Z"
}
```
### 4. Git 工作流规范
#### 分支管理
```bash
# 主要分支
main # 生产环境分支
develop # 开发环境分支
release/* # 发布分支
hotfix/* # 热修复分支
# 功能分支
feature/user-management # 用户管理功能
feature/travel-booking # 旅行预订功能
feature/animal-adoption # 动物认领功能
# 修复分支
bugfix/login-issue # 登录问题修复
bugfix/payment-error # 支付错误修复
```
#### 提交信息规范
```bash
# 提交信息格式
<type>(<scope>): <subject>
<body>
<footer>
# 示例
feat(user): 添加用户注册功能
- 实现微信授权登录
- 添加用户信息完善页面
- 集成短信验证码功能
Closes #123
# 类型说明
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建工具或辅助工具的变动
```
## 🧪 测试规范
### 1. 前端测试
#### 单元测试 (Jest)
```javascript
// utils/formatDate.test.js
import { formatDate } from './formatDate';
describe('formatDate', () => {
test('应该正确格式化日期', () => {
const date = new Date('2025-01-15T10:30:00Z');
const result = formatDate(date, 'YYYY-MM-DD');
expect(result).toBe('2025-01-15');
});
test('应该处理无效日期', () => {
const result = formatDate(null, 'YYYY-MM-DD');
expect(result).toBe('');
});
});
```
#### 组件测试 (Vue Test Utils)
```javascript
// components/UserProfile.test.js
import { mount } from '@vue/test-utils';
import UserProfile from './UserProfile.vue';
describe('UserProfile', () => {
test('应该正确显示用户信息', () => {
const userInfo = {
nickname: '张三',
avatar: 'https://example.com/avatar.jpg'
};
const wrapper = mount(UserProfile, {
props: { userInfo }
});
expect(wrapper.find('.username').text()).toBe('张三');
expect(wrapper.find('image').attributes('src')).toBe('https://example.com/avatar.jpg');
});
});
```
### 2. 后端测试
#### 单元测试 (JUnit 5)
```java
@ExtendWith(MockitoExtension.class)
class UserServiceTest {
@Mock
private UserMapper userMapper;
@InjectMocks
private UserService userService;
@Test
@DisplayName("根据ID获取用户信息 - 成功")
void getUserById_Success() {
// Given
Long userId = 1L;
User mockUser = User.builder()
.id(userId)
.nickname("张三")
.status(UserStatus.ACTIVE)
.build();
when(userMapper.selectById(userId)).thenReturn(mockUser);
// When
UserDTO result = userService.getUserById(userId);
// Then
assertThat(result).isNotNull();
assertThat(result.getId()).isEqualTo(userId);
assertThat(result.getNickname()).isEqualTo("张三");
verify(userMapper).selectById(userId);
}
@Test
@DisplayName("根据ID获取用户信息 - 用户不存在")
void getUserById_UserNotFound() {
// Given
Long userId = 999L;
when(userMapper.selectById(userId)).thenReturn(null);
// When & Then
assertThatThrownBy(() -> userService.getUserById(userId))
.isInstanceOf(BusinessException.class)
.hasMessage("用户不存在");
}
}
```
#### 集成测试 (Spring Boot Test)
```java
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Transactional
class UserControllerIntegrationTest {
@Autowired
private TestRestTemplate restTemplate;
@Autowired
private UserMapper userMapper;
@Test
@DisplayName("获取用户信息接口测试")
void getUserById_Integration() {
// Given - 准备测试数据
User user = User.builder()
.openid("test_openid")
.nickname("测试用户")
.status(UserStatus.ACTIVE)
.build();
userMapper.insert(user);
// When - 调用接口
ResponseEntity<ApiResponse<UserDTO>> response = restTemplate.exchange(
"/api/v1/users/" + user.getId(),
HttpMethod.GET,
null,
new ParameterizedTypeReference<ApiResponse<UserDTO>>() {}
);
// Then - 验证结果
assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
assertThat(response.getBody()).isNotNull();
assertThat(response.getBody().getCode()).isEqualTo(200);
assertThat(response.getBody().getData().getNickname()).isEqualTo("测试用户");
}
}
```
## 🚀 开发流程
### 1. 功能开发流程
#### 步骤1: 需求分析
1. 阅读产品需求文档
2. 理解业务逻辑和用户场景
3. 确认技术实现方案
4. 评估开发工作量
#### 步骤2: 技术设计
1. 设计数据库表结构
2. 设计API接口
3. 设计前端页面结构
4. 确定技术选型
#### 步骤3: 开发实现
```bash
# 1. 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/user-profile
# 2. 后端开发
# - 创建实体类和DTO
# - 实现数据访问层
# - 实现业务逻辑层
# - 实现控制器层
# - 编写单元测试
# 3. 前端开发
# - 创建页面组件
# - 实现业务逻辑
# - 调用后端API
# - 编写组件测试
# 4. 联调测试
# - 启动后端服务
# - 启动前端应用
# - 测试完整功能流程
# 5. 提交代码
git add .
git commit -m "feat(user): 实现用户个人资料功能"
git push origin feature/user-profile
```
#### 步骤4: 代码审查
1. 创建Pull Request
2. 同事进行代码审查
3. 修复审查意见
4. 合并到develop分支
#### 步骤5: 测试验证
1. 部署到测试环境
2. 执行功能测试
3. 执行回归测试
4. 修复发现的问题
### 2. 本地开发环境启动
#### 后端服务启动
```bash
# 1. 启动基础服务
docker-compose up -d mysql redis rabbitmq
# 2. 启动微服务 (按顺序启动)
cd backend-java
# 启动服务注册中心
cd eureka-server
mvn spring-boot:run &
# 等待Eureka启动完成，然后启动其他服务
cd ../gateway-service
mvn spring-boot:run &
cd ../auth-service
mvn spring-boot:run &
cd ../user-service
mvn spring-boot:run &
# 或者使用脚本一键启动
./start-services.sh
```
#### 前端应用启动
```bash
# 1. 启动微信小程序
cd frontend/miniprogram
npm install
npm run dev
# 2. 启动管理后台
cd ../admin-web
npm install
npm run serve
# 3. 启动官方网站
cd ../website
npm install
npm run dev
```
### 3. 调试技巧
#### 后端调试
```java
// 使用日志进行调试
@Slf4j
@Service
public class UserService {
public UserDTO getUserById(Long userId) {
log.debug("开始获取用户信息, userId: {}", userId);
User user = userMapper.selectById(userId);
log.debug("查询到用户信息: {}", user);
if (user == null) {
log.warn("用户不存在, userId: {}", userId);
throw new BusinessException(ErrorCode.USER_NOT_FOUND);
}
UserDTO result = UserConverter.toDTO(user);
log.debug("转换后的用户信息: {}", result);
return result;
}
}
```
#### 前端调试
```javascript
// 使用console进行调试
const getUserInfo = async (userId) => {
console.log('开始获取用户信息, userId:', userId);
try {
const response = await api.get(`/users/${userId}`);
console.log('获取用户信息成功:', response.data);
return response.data;
} catch (error) {
console.error('获取用户信息失败:', error);
throw error;
}
};
// 使用微信开发者工具调试
wx.request({
url: 'https://api.jiebanke.com/users/1',
success: (res) => {
console.log('请求成功:', res);
},
fail: (err) => {
console.error('请求失败:', err);
}
});
```
## 📦 构建与部署
### 1. 本地构建
#### 前端构建
```bash
# 微信小程序构建
cd frontend/miniprogram
npm run build
# 管理后台构建
cd ../admin-web
npm run build
# 官方网站构建
cd ../website
npm run build
```
#### 后端构建
```bash
# Maven构建
cd backend-java
mvn clean package -DskipTests
# Docker构建
./build-services.sh
```
### 2. 容器化部署
```bash
# 构建Docker镜像
docker-compose build
# 启动所有服务
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看服务日志
docker-compose logs -f user-service
```
## 🔧 开发工具配置
### 1. VS Code 配置
#### 推荐插件
```json
{
"recommendations": [
"ms-vscode.vscode-typescript-next",
"vue.volar",
"esbenp.prettier-vscode",
"dbaeumer.vscode-eslint",
"ms-vscode.vscode-json",
"redhat.java",
"vscjava.vscode-spring-boot-dashboard",
"ms-python.python"
]
}
```
#### 工作区设置
```json
{
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"eslint.workingDirectories": [
"frontend/miniprogram",
"frontend/admin-web",
"frontend/website"
],
"java.configuration.workspaces": [
"backend-java"
]
}
```
### 2. IntelliJ IDEA 配置
#### 代码格式化
1. 导入项目代码风格配置
2. 启用自动格式化
3. 配置Import优化
#### 插件推荐
- Lombok
- MyBatis Log Plugin
- RestfulTool
- Maven Helper
- Git Commit Template
## 📚 学习资源
### 官方文档
- [微信小程序开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
- [Vue.js 官方文档](https://vuejs.org/)
- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [MyBatis 官方文档](https://mybatis.org/mybatis-3/)
### 推荐书籍
- 《JavaScript高级程序设计》
- 《Vue.js设计与实现》
- 《Spring Boot实战》
- 《Java并发编程实战》
### 在线课程
- [Vue.js 从入门到精通](https://example.com)
- [Spring Boot 微服务开发](https://example.com)
- [MySQL 数据库优化](https://example.com)
## 🤝 团队协作
### 1. 代码审查清单
#### 前端代码审查
- [ ] 代码格式是否符合规范
- [ ] 组件是否可复用
- [ ] 是否有内存泄漏风险
- [ ] 错误处理是否完善
- [ ] 用户体验是否良好
#### 后端代码审查
- [ ] 业务逻辑是否正确
- [ ] 异常处理是否完善
- [ ] 数据库操作是否高效
- [ ] 安全性是否考虑
- [ ] 日志记录是否完整
### 2. 沟通协作
#### 日常沟通
- 每日站会：同步开发进度和问题
- 技术分享：定期分享技术心得
- 代码审查：互相学习和改进
#### 文档维护
- 及时更新API文档
- 记录重要的技术决策
- 维护常见问题解答
## 🆘 常见问题
### 1. 环境问题
**Q: Node.js 版本不兼容怎么办？**
A: 使用 nvm 管理 Node.js 版本
```bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 安装并使用指定版本
nvm install 18
nvm use 18
```
**Q: Java 版本冲突怎么办？**
A: 使用 JAVA_HOME 环境变量指定版本
```bash
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
export PATH=$JAVA_HOME/bin:$PATH
```
### 2. 开发问题
**Q: 微信小程序真机调试问题？**
A: 检查以下几点：
1. 确认服务器域名已配置
2. 检查HTTPS证书是否有效
3. 确认API接口返回格式正确
**Q: 后端服务启动失败？**
A: 常见原因和解决方案：
1. 端口被占用：`lsof -i :8080` 查看占用进程
2. 数据库连接失败：检查数据库配置和网络
3. 依赖冲突：清理Maven缓存重新构建
### 3. 部署问题
**Q: Docker 容器启动失败？**
A: 查看容器日志定位问题
```bash
docker logs container_name
docker-compose logs service_name
```
**Q: 数据库迁移问题？**
A: 使用Flyway进行版本化管理
```sql
-- V1__Create_users_table.sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
nickname VARCHAR(50) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
## 📞 技术支持
### 联系方式
- **技术负责人**: tech-lead@jiebanke.com
- **开发团队**: dev@jiebanke.com
- **技术文档**: https://docs.jiebanke.com
- **问题反馈**: https://github.com/jiebanke/issues
### 紧急联系
- **生产环境问题**: 24小时技术热线
- **安全问题**: security@jiebanke.com
- **数据问题**: dba@jiebanke.com
---
*文档版本：v1.0*
*最后更新：2025年1月*
*维护团队：结伴客技术团队*

731
docs/数据库设计文档.md Normal file
View File

@@ -0,0 +1,731 @@
# 🗄️ 结伴客数据库设计文档
## 📋 数据库概述
结伴客系统采用MySQL 8.0作为主要数据存储，设计了完整的数据库架构来支持结伴旅行、动物认领、商家服务等核心业务功能。数据库设计遵循第三范式，确保数据一致性和完整性。
## 🔧 数据库配置
### 环境配置
#### 开发环境
- **主机**：localhost
- **端口**：3306
- **数据库名**：jiebandata_dev
- **字符集**：utf8mb4
- **排序规则**：utf8mb4_unicode_ci
#### 测试环境
- **主机**：192.168.0.240
- **端口**：3306
- **用户名**：root
- **密码**：aiot$Aiot123
- **数据库名**：jiebandata_test
#### 生产环境
- **主机**：129.211.213.226
- **端口**：9527
- **用户名**：root
- **密码**：aiotAiot123!
- **数据库名**：jiebandata
### 数据库架构
#### 主从复制架构
```mermaid
graph LR
A[应用服务器] --> B[MySQL主库<br/>写操作]
B --> C[MySQL从库1<br/>读操作]
B --> D[MySQL从库2<br/>读操作]
A --> C
A --> D
E[备份服务器] --> B
F[监控系统] --> B
F --> C
F --> D
```
## 📊 数据库ER图
```mermaid
erDiagram
USERS ||--o{ TRAVEL_PLANS : creates
USERS ||--o{ TRAVEL_MATCHES : participates
USERS ||--o{ ANIMAL_CLAIMS : claims
USERS ||--o{ ORDERS : places
USERS ||--o{ REVIEWS : writes
USERS ||--o{ MESSAGES : sends
USERS ||--o{ USER_INTERESTS : has
MERCHANTS ||--o{ ANIMALS : manages
MERCHANTS ||--o{ PRODUCTS : sells
MERCHANTS ||--o{ ACTIVITIES : organizes
MERCHANTS ||--o{ ORDERS : receives
TRAVEL_PLANS ||--o{ TRAVEL_MATCHES : generates
TRAVEL_PLANS ||--o{ TRAVEL_INVITATIONS : has
ANIMALS ||--o{ ANIMAL_CLAIMS : claimed_by
ANIMALS ||--o{ ANIMAL_UPDATES : has
PRODUCTS ||--o{ ORDER_ITEMS : contains
ORDERS ||--o{ ORDER_ITEMS : includes
ORDERS ||--o{ PAYMENTS : has
ACTIVITIES ||--o{ ACTIVITY_REGISTRATIONS : registers
ADMINS ||--o{ ADMIN_LOGS : creates
USERS {
int id PK
string openid UK
string nickname
string avatar
enum gender
date birthday
string phone UK
string email UK
int travel_count
int animal_claim_count
enum status
timestamp created_at
timestamp updated_at
}
MERCHANTS {
int id PK
int user_id FK
enum merchant_type
string business_name
string business_license UK
string contact_person
string contact_phone
text address
text description
enum status
timestamp created_at
timestamp updated_at
}
TRAVEL_PLANS {
int id PK
int user_id FK
string destination
date start_date
date end_date
decimal budget
text interests
text description
enum visibility
int max_participants
int current_participants
enum status
timestamp created_at
timestamp updated_at
}
ANIMALS {
int id PK
int merchant_id FK
string name
enum type
string breed
int age
enum gender
text description
json images
decimal price
string farm_location
enum status
int claim_count
timestamp created_at
timestamp updated_at
}
ORDERS {
int id PK
string order_number UK
int user_id FK
int merchant_id FK
enum order_type
decimal total_amount
enum status
json delivery_info
timestamp ordered_at
timestamp completed_at
timestamp created_at
timestamp updated_at
}
```
## 📋 核心表结构设计
### 1. 用户管理模块
#### 1.1 用户表 (users)
```sql
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
openid VARCHAR(100) UNIQUE NOT NULL COMMENT '微信openid',
unionid VARCHAR(100) COMMENT '微信unionid',
nickname VARCHAR(50) NOT NULL COMMENT '用户昵称',
avatar VARCHAR(255) COMMENT '头像URL',
gender ENUM('male', 'female', 'unknown') DEFAULT 'unknown' COMMENT '性别',
birthday DATE COMMENT '生日',
phone VARCHAR(20) UNIQUE COMMENT '手机号码',
email VARCHAR(100) UNIQUE COMMENT '邮箱地址',
province VARCHAR(50) COMMENT '省份',
city VARCHAR(50) COMMENT '城市',
travel_count INT DEFAULT 0 COMMENT '旅行次数',
animal_claim_count INT DEFAULT 0 COMMENT '认领动物数量',
points INT DEFAULT 0 COMMENT '积分',
level ENUM('bronze', 'silver', 'gold', 'platinum') DEFAULT 'bronze' COMMENT '用户等级',
status ENUM('active', 'inactive', 'banned') DEFAULT 'active' COMMENT '用户状态',
last_login_at TIMESTAMP COMMENT '最后登录时间',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
INDEX idx_openid (openid),
INDEX idx_phone (phone),
INDEX idx_email (email),
INDEX idx_status (status),
INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户基础信息表';
```
#### 1.2 用户兴趣表 (user_interests)
```sql
CREATE TABLE user_interests (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '兴趣ID',
user_id INT NOT NULL COMMENT '用户ID',
interest_name VARCHAR(50) NOT NULL COMMENT '兴趣名称',
interest_type ENUM('travel', 'food', 'sports', 'culture', 'nature') COMMENT '兴趣类型',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
UNIQUE KEY uk_user_interest (user_id, interest_name),
INDEX idx_user_id (user_id),
INDEX idx_interest_type (interest_type)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户兴趣表';
```
### 2. 商家管理模块
#### 2.1 商家表 (merchants)
```sql
CREATE TABLE merchants (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '商家ID',
user_id INT NOT NULL COMMENT '关联用户ID',
merchant_type ENUM('flower_shop', 'farm', 'activity_organizer', 'travel_agency') NOT NULL COMMENT '商家类型',
business_name VARCHAR(100) NOT NULL COMMENT '商家名称',
business_license VARCHAR(50) UNIQUE NOT NULL COMMENT '营业执照号',
contact_person VARCHAR(50) NOT NULL COMMENT '联系人姓名',
contact_phone VARCHAR(20) NOT NULL COMMENT '联系电话',
address TEXT COMMENT '经营地址',
description TEXT COMMENT '商家描述',
business_hours VARCHAR(100) COMMENT '营业时间',
rating DECIMAL(3,2) DEFAULT 5.00 COMMENT '商家评分',
review_count INT DEFAULT 0 COMMENT '评价数量',
status ENUM('pending', 'approved', 'rejected', 'suspended') DEFAULT 'pending' COMMENT '审核状态',
verified_at TIMESTAMP COMMENT '认证时间',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
UNIQUE KEY uk_business_license (business_license),
INDEX idx_user_id (user_id),
INDEX idx_merchant_type (merchant_type),
INDEX idx_status (status),
INDEX idx_rating (rating)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='商家信息表';
```
### 3. 旅行结伴模块
#### 3.1 旅行计划表 (travel_plans)
```sql
CREATE TABLE travel_plans (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '旅行计划ID',
user_id INT NOT NULL COMMENT '发起用户ID',
title VARCHAR(100) NOT NULL COMMENT '旅行标题',
destination VARCHAR(100) NOT NULL COMMENT '目的地',
start_date DATE NOT NULL COMMENT '开始日期',
end_date DATE NOT NULL COMMENT '结束日期',
budget DECIMAL(10,2) COMMENT '预算金额',
interests TEXT COMMENT '兴趣偏好',
description TEXT COMMENT '行程描述',
requirements TEXT COMMENT '同行要求',
visibility ENUM('public', 'friends', 'private') DEFAULT 'public' COMMENT '可见性',
max_participants INT DEFAULT 4 COMMENT '最大参与人数',
current_participants INT DEFAULT 1 COMMENT '当前参与人数',
gender_preference ENUM('male', 'female', 'mixed', 'no_preference') DEFAULT 'no_preference' COMMENT '性别偏好',
age_min INT COMMENT '最小年龄要求',
age_max INT COMMENT '最大年龄要求',
status ENUM('active', 'full', 'completed', 'cancelled') DEFAULT 'active' COMMENT '计划状态',
view_count INT DEFAULT 0 COMMENT '浏览次数',
like_count INT DEFAULT 0 COMMENT '点赞次数',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
INDEX idx_user_id (user_id),
INDEX idx_destination (destination),
INDEX idx_date_range (start_date, end_date),
INDEX idx_status (status),
INDEX idx_budget (budget),
INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='旅行计划表';
```
#### 3.2 旅行匹配表 (travel_matches)
```sql
CREATE TABLE travel_matches (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '匹配ID',
travel_plan_id INT NOT NULL COMMENT '旅行计划ID',
user_id INT NOT NULL COMMENT '申请用户ID',
message TEXT COMMENT '申请留言',
status ENUM('pending', 'approved', 'rejected', 'cancelled') DEFAULT 'pending' COMMENT '申请状态',
applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '申请时间',
responded_at TIMESTAMP COMMENT '响应时间',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
FOREIGN KEY (travel_plan_id) REFERENCES travel_plans(id) ON DELETE CASCADE,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
UNIQUE KEY uk_plan_user (travel_plan_id, user_id),
INDEX idx_travel_plan_id (travel_plan_id),
INDEX idx_user_id (user_id),
INDEX idx_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='旅行匹配申请表';
```
### 4. 动物认领模块
#### 4.1 动物信息表 (animals)
```sql
CREATE TABLE animals (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '动物ID',
merchant_id INT NOT NULL COMMENT '所属商家ID',
name VARCHAR(50) NOT NULL COMMENT '动物名称',
type ENUM('cow', 'sheep', 'pig', 'chicken', 'duck', 'goat', 'rabbit') NOT NULL COMMENT '动物类型',
breed VARCHAR(50) COMMENT '品种',
age INT COMMENT '年龄（月）',
gender ENUM('male', 'female') COMMENT '性别',
weight DECIMAL(5,2) COMMENT '体重（公斤）',
color VARCHAR(50) COMMENT '毛色',
personality TEXT COMMENT '性格特点',
description TEXT COMMENT '动物描述',
images JSON COMMENT '动物图片数组',
videos JSON COMMENT '动物视频数组',
price DECIMAL(10,2) NOT NULL COMMENT '认领价格（月）',
farm_location VARCHAR(100) COMMENT '农场位置',
farm_environment TEXT COMMENT '农场环境描述',
feeding_info TEXT COMMENT '喂养信息',
health_status ENUM('healthy', 'sick', 'recovering') DEFAULT 'healthy' COMMENT '健康状态',
vaccination_record JSON COMMENT '疫苗接种记录',
status ENUM('available', 'claimed', 'unavailable', 'sold') DEFAULT 'available' COMMENT '动物状态',
claim_count INT DEFAULT 0 COMMENT '被认领次数',
rating DECIMAL(3,2) DEFAULT 5.00 COMMENT '动物评分',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
FOREIGN KEY (merchant_id) REFERENCES merchants(id) ON DELETE CASCADE,
INDEX idx_merchant_id (merchant_id),
INDEX idx_type (type),
INDEX idx_status (status),
INDEX idx_price (price),
INDEX idx_age (age),
INDEX idx_rating (rating)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='动物信息表';
```
#### 4.2 动物认领表 (animal_claims)
```sql
CREATE TABLE animal_claims (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '认领ID',
user_id INT NOT NULL COMMENT '认领用户ID',
animal_id INT NOT NULL COMMENT '动物ID',
claim_name VARCHAR(50) COMMENT '认领后的动物名称',
duration INT NOT NULL COMMENT '认领时长（月）',
monthly_price DECIMAL(10,2) NOT NULL COMMENT '月费用',
total_amount DECIMAL(10,2) NOT NULL COMMENT '总金额',
start_date DATE NOT NULL COMMENT '认领开始日期',
end_date DATE NOT NULL COMMENT '认领结束日期',
auto_renew BOOLEAN DEFAULT FALSE COMMENT '是否自动续费',
visit_count INT DEFAULT 0 COMMENT '探访次数',
last_visit_date DATE COMMENT '最后探访日期',
status ENUM('active', 'expired', 'cancelled', 'completed') DEFAULT 'active' COMMENT '认领状态',
message TEXT COMMENT '认领留言',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
FOREIGN KEY (animal_id) REFERENCES animals(id) ON DELETE CASCADE,
INDEX idx_user_id (user_id),
INDEX idx_animal_id (animal_id),
INDEX idx_status (status),
INDEX idx_date_range (start_date, end_date)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='动物认领表';
```
#### 4.3 动物更新记录表 (animal_updates)
```sql
CREATE TABLE animal_updates (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '更新记录ID',
animal_id INT NOT NULL COMMENT '动物ID',
claim_id INT COMMENT '认领ID',
update_type ENUM('growth', 'health', 'feeding', 'activity', 'photo', 'video') NOT NULL COMMENT '更新类型',
title VARCHAR(100) NOT NULL COMMENT '更新标题',
content TEXT COMMENT '更新内容',
images JSON COMMENT '图片数组',
videos JSON COMMENT '视频数组',
weight DECIMAL(5,2) COMMENT '体重记录',
health_note TEXT COMMENT '健康备注',
created_by ENUM('system', 'merchant', 'admin') DEFAULT 'merchant' COMMENT '创建者类型',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
FOREIGN KEY (animal_id) REFERENCES animals(id) ON DELETE CASCADE,
FOREIGN KEY (claim_id) REFERENCES animal_claims(id) ON DELETE SET NULL,
INDEX idx_animal_id (animal_id),
INDEX idx_claim_id (claim_id),
INDEX idx_update_type (update_type),
INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='动物更新记录表';
```
### 5. 商品订单模块
#### 5.1 商品表 (products)
```sql
CREATE TABLE products (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '商品ID',
merchant_id INT NOT NULL COMMENT '商家ID',
category_id INT COMMENT '分类ID',
name VARCHAR(100) NOT NULL COMMENT '商品名称',
description TEXT COMMENT '商品描述',
price DECIMAL(10,2) NOT NULL COMMENT '商品价格',
original_price DECIMAL(10,2) COMMENT '原价',
stock INT DEFAULT 0 COMMENT '库存数量',
min_order_quantity INT DEFAULT 1 COMMENT '最小起订量',
max_order_quantity INT COMMENT '最大订购量',
images JSON COMMENT '商品图片数组',
specifications JSON COMMENT '商品规格',
tags VARCHAR(255) COMMENT '商品标签',
weight DECIMAL(8,3) COMMENT '商品重量（公斤）',
dimensions VARCHAR(50) COMMENT '商品尺寸',
shelf_life INT COMMENT '保质期（天）',
storage_conditions TEXT COMMENT '储存条件',
delivery_info TEXT COMMENT '配送信息',
rating DECIMAL(3,2) DEFAULT 5.00 COMMENT '商品评分',
review_count INT DEFAULT 0 COMMENT '评价数量',
sales_count INT DEFAULT 0 COMMENT '销售数量',
status ENUM('active', 'inactive', 'out_of_stock', 'discontinued') DEFAULT 'active' COMMENT '商品状态',
sort_order INT DEFAULT 0 COMMENT '排序权重',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
FOREIGN KEY (merchant_id) REFERENCES merchants(id) ON DELETE CASCADE,
INDEX idx_merchant_id (merchant_id),
INDEX idx_category_id (category_id),
INDEX idx_price (price),
INDEX idx_status (status),
INDEX idx_rating (rating),
INDEX idx_sales_count (sales_count)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='商品信息表';
```
#### 5.2 订单表 (orders)
```sql
CREATE TABLE orders (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '订单ID',
order_number VARCHAR(32) UNIQUE NOT NULL COMMENT '订单号',
user_id INT NOT NULL COMMENT '用户ID',
merchant_id INT NOT NULL COMMENT '商家ID',
order_type ENUM('product', 'animal_claim', 'activity', 'service') NOT NULL COMMENT '订单类型',
total_amount DECIMAL(10,2) NOT NULL COMMENT '订单总金额',
discount_amount DECIMAL(10,2) DEFAULT 0.00 COMMENT '优惠金额',
shipping_fee DECIMAL(10,2) DEFAULT 0.00 COMMENT '运费',
final_amount DECIMAL(10,2) NOT NULL COMMENT '实付金额',
payment_method ENUM('wechat', 'alipay', 'bank_card', 'points') COMMENT '支付方式',
payment_status ENUM('pending', 'paid', 'failed', 'refunded', 'partial_refund') DEFAULT 'pending' COMMENT '支付状态',
order_status ENUM('pending', 'confirmed', 'processing', 'shipped', 'delivered', 'completed', 'cancelled') DEFAULT 'pending' COMMENT '订单状态',
delivery_info JSON COMMENT '配送信息',
remark TEXT COMMENT '订单备注',
cancel_reason TEXT COMMENT '取消原因',
refund_reason TEXT COMMENT '退款原因',
ordered_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '下单时间',
paid_at TIMESTAMP COMMENT '支付时间',
shipped_at TIMESTAMP COMMENT '发货时间',
delivered_at TIMESTAMP COMMENT '收货时间',
completed_at TIMESTAMP COMMENT '完成时间',
cancelled_at TIMESTAMP COMMENT '取消时间',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
FOREIGN KEY (merchant_id) REFERENCES merchants(id) ON DELETE CASCADE,
UNIQUE KEY uk_order_number (order_number),
INDEX idx_user_id (user_id),
INDEX idx_merchant_id (merchant_id),
INDEX idx_order_type (order_type),
INDEX idx_payment_status (payment_status),
INDEX idx_order_status (order_status),
INDEX idx_ordered_at (ordered_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单主表';
```
#### 5.3 订单明细表 (order_items)
```sql
CREATE TABLE order_items (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '订单明细ID',
order_id INT NOT NULL COMMENT '订单ID',
product_id INT COMMENT '商品ID',
animal_id INT COMMENT '动物ID（动物认领订单）',
activity_id INT COMMENT '活动ID（活动报名订单）',
item_name VARCHAR(100) NOT NULL COMMENT '商品/服务名称',
item_description TEXT COMMENT '商品/服务描述',
unit_price DECIMAL(10,2) NOT NULL COMMENT '单价',
quantity INT NOT NULL COMMENT '数量',
total_price DECIMAL(10,2) NOT NULL COMMENT '小计金额',
specifications JSON COMMENT '规格信息',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
INDEX idx_order_id (order_id),
INDEX idx_product_id (product_id),
INDEX idx_animal_id (animal_id),
INDEX idx_activity_id (activity_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单明细表';
```
### 6. 活动管理模块
#### 6.1 活动表 (activities)
```sql
CREATE TABLE activities (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '活动ID',
merchant_id INT NOT NULL COMMENT '组织商家ID',
title VARCHAR(100) NOT NULL COMMENT '活动标题',
description TEXT COMMENT '活动描述',
activity_type ENUM('travel', 'farm_visit', 'workshop', 'exhibition', 'social', 'other') NOT NULL COMMENT '活动类型',
location VARCHAR(200) NOT NULL COMMENT '活动地点',
address TEXT COMMENT '详细地址',
latitude DECIMAL(10,8) COMMENT '纬度',
longitude DECIMAL(11,8) COMMENT '经度',
start_time DATETIME NOT NULL COMMENT '开始时间',
end_time DATETIME NOT NULL COMMENT '结束时间',
registration_start DATETIME COMMENT '报名开始时间',
registration_end DATETIME COMMENT '报名结束时间',
max_participants INT COMMENT '最大参与人数',
current_participants INT DEFAULT 0 COMMENT '当前参与人数',
min_participants INT DEFAULT 1 COMMENT '最少参与人数',
price DECIMAL(10,2) DEFAULT 0.00 COMMENT '活动费用',
age_min INT COMMENT '最小年龄限制',
age_max INT COMMENT '最大年龄限制',
gender_requirement ENUM('male', 'female', 'mixed', 'no_requirement') DEFAULT 'no_requirement' COMMENT '性别要求',
requirements TEXT COMMENT '参与要求',
includes TEXT COMMENT '费用包含',
excludes TEXT COMMENT '费用不含',
notes TEXT COMMENT '注意事项',
images JSON COMMENT '活动图片',
contact_info JSON COMMENT '联系方式',
status ENUM('draft', 'published', 'full', 'ongoing', 'completed', 'cancelled') DEFAULT 'draft' COMMENT '活动状态',
featured BOOLEAN DEFAULT FALSE COMMENT '是否推荐',
view_count INT DEFAULT 0 COMMENT '浏览次数',
like_count INT DEFAULT 0 COMMENT '点赞次数',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
FOREIGN KEY (merchant_id) REFERENCES merchants(id) ON DELETE CASCADE,
INDEX idx_merchant_id (merchant_id),
INDEX idx_activity_type (activity_type),
INDEX idx_location (location),
INDEX idx_start_time (start_time),
INDEX idx_status (status),
INDEX idx_featured (featured)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='活动信息表';
```
### 7. 系统管理模块
#### 7.1 管理员表 (admins)
```sql
CREATE TABLE admins (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '管理员ID',
username VARCHAR(50) UNIQUE NOT NULL COMMENT '用户名',
password VARCHAR(255) NOT NULL COMMENT '密码哈希',
email VARCHAR(100) UNIQUE NOT NULL COMMENT '邮箱',
nickname VARCHAR(50) COMMENT '昵称',
avatar VARCHAR(255) COMMENT '头像',
role ENUM('super_admin', 'admin', 'moderator', 'customer_service') NOT NULL COMMENT '角色',
permissions JSON COMMENT '权限列表',
status ENUM('active', 'inactive', 'locked') DEFAULT 'active' COMMENT '状态',
last_login_at TIMESTAMP COMMENT '最后登录时间',
last_login_ip VARCHAR(45) COMMENT '最后登录IP',
login_count INT DEFAULT 0 COMMENT '登录次数',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
UNIQUE KEY uk_username (username),
UNIQUE KEY uk_email (email),
INDEX idx_role (role),
INDEX idx_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='管理员表';
```
#### 7.2 系统配置表 (system_configs)
```sql
CREATE TABLE system_configs (
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '配置ID',
config_key VARCHAR(100) UNIQUE NOT NULL COMMENT '配置键',
config_value TEXT COMMENT '配置值',
config_type ENUM('string', 'number', 'boolean', 'json', 'text') DEFAULT 'string' COMMENT '配置类型',
description TEXT COMMENT '配置描述',
category VARCHAR(50) COMMENT '配置分类',
is_public BOOLEAN DEFAULT FALSE COMMENT '是否公开',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
UNIQUE KEY uk_config_key (config_key),
INDEX idx_category (category),
INDEX idx_is_public (is_public)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='系统配置表';
```
## 🔍 索引优化策略
### 主键索引
所有表都使用自增整型主键，确保插入性能和唯一性。
### 唯一索引
- `users.openid` - 微信用户唯一标识
- `users.phone` - 用户手机号
- `merchants.business_license` - 商家营业执照号
- `orders.order_number` - 订单号
### 复合索引
```sql
-- 旅行计划查询优化
ALTER TABLE travel_plans ADD INDEX idx_destination_date (destination, start_date, status);
-- 动物搜索优化
ALTER TABLE animals ADD INDEX idx_type_status_price (type, status, price);
-- 订单查询优化
ALTER TABLE orders ADD INDEX idx_user_status_time (user_id, order_status, created_at);
```
### 覆盖索引
```sql
-- 用户列表查询覆盖索引
ALTER TABLE users ADD INDEX idx_status_created_cover (status, created_at, id, nickname, avatar);
-- 商品列表查询覆盖索引
ALTER TABLE products ADD INDEX idx_merchant_status_cover (merchant_id, status, id, name, price, images);
```
## 🔄 数据库维护
### 分区策略
#### 按时间分区（订单表）
```sql
-- 按月分区订单表
ALTER TABLE orders PARTITION BY RANGE (YEAR(created_at) * 100 + MONTH(created_at)) (
PARTITION p202501 VALUES LESS THAN (202502),
PARTITION p202502 VALUES LESS THAN (202503),
PARTITION p202503 VALUES LESS THAN (202504),
-- ... 更多分区
PARTITION p_future VALUES LESS THAN MAXVALUE
);
```
### 数据归档策略
#### 日志表归档
```sql
-- 创建归档表
CREATE TABLE admin_logs_archive LIKE admin_logs;
-- 归档6个月前的日志
INSERT INTO admin_logs_archive
SELECT * FROM admin_logs
WHERE created_at < DATE_SUB(NOW(), INTERVAL 6 MONTH);
-- 删除已归档的数据
DELETE FROM admin_logs
WHERE created_at < DATE_SUB(NOW(), INTERVAL 6 MONTH);
```
### 备份策略
#### 全量备份脚本
```bash
#!/bin/bash
# 数据库全量备份脚本
BACKUP_DIR="/opt/backups/mysql"
DATE=$(date +%Y%m%d_%H%M%S)
DB_NAME="jiebandata"
# 创建备份目录
mkdir -p $BACKUP_DIR
# 执行备份
mysqldump -h localhost -u backup_user -p$BACKUP_PASSWORD \
--single-transaction \
--routines \
--triggers \
--events \
$DB_NAME > $BACKUP_DIR/jiebandata_$DATE.sql
# 压缩备份文件
gzip $BACKUP_DIR/jiebandata_$DATE.sql
# 删除7天前的备份
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete
echo "数据库备份完成: jiebandata_$DATE.sql.gz"
```
## 📊 性能监控
### 慢查询监控
```sql
-- 开启慢查询日志
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;
SET GLOBAL log_queries_not_using_indexes = 'ON';
```
### 表空间监控
```sql
-- 查看表大小
SELECT
table_name,
ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)'
FROM information_schema.tables
WHERE table_schema = 'jiebandata'
ORDER BY (data_length + index_length) DESC;
```
### 索引使用情况
```sql
-- 查看未使用的索引
SELECT
t.table_schema,
t.table_name,
s.index_name,
s.cardinality
FROM information_schema.tables t
LEFT JOIN information_schema.statistics s ON t.table_name = s.table_name
WHERE t.table_schema = 'jiebandata'
AND s.index_name IS NOT NULL
AND s.index_name != 'PRIMARY';
```
---
*文档版本：v1.0*
*最后更新：2025年1月*

527
docs/系统架构文档.md Normal file
View File

@@ -0,0 +1,527 @@
# 🏗️ 结伴客系统架构文档
## 📋 项目概述
结伴客是一个综合性的社交旅行平台，采用现代化的微服务架构设计，包含后台管理系统、微信小程序和官方网站三个主要模块。系统支持结伴旅行、动物认领、商家服务等核心业务功能。
## 🎯 技术选型
### 前端技术栈
#### 微信小程序
- **开发框架**：原生微信小程序
- **UI组件库**：Vant Weapp
- **状态管理**：原生状态管理
- **网络请求**：wx.request封装
- **构建工具**：微信开发者工具
#### 后台管理系统
- **开发框架**：Vue 3 + TypeScript
- **UI组件库**：Element Plus
- **状态管理**：Pinia
- **路由管理**：Vue Router 4
- **HTTP客户端**：Axios
- **构建工具**：Vite
#### 官方网站
- **开发框架**：Vue 3 + JavaScript
- **UI框架**：自定义CSS + 响应式设计
- **路由管理**：Vue Router
- **构建工具**：Vite
- **SEO优化**：Vue Meta
### 后端技术栈
#### Node.js版本（主要）
- **运行环境**：Node.js 16.x+
- **Web框架**：Express.js
- **数据库ORM**：Sequelize
- **认证授权**：JWT + bcrypt
- **参数验证**：Joi
- **日志管理**：Winston
- **进程管理**：PM2
#### Java微服务版本（备选）
- **开发框架**：Spring Boot 2.7+
- **微服务框架**：Spring Cloud
- **数据库ORM**：MyBatis Plus
- **服务注册**：Eureka Server
- **API网关**：Spring Cloud Gateway
- **配置中心**：Spring Cloud Config
### 数据存储
#### 关系型数据库
- **主数据库**：MySQL 8.0
- **连接池**：HikariCP
- **数据迁移**：Sequelize Migrations
- **备份策略**：定时全量备份 + 增量备份
#### 缓存系统
- **内存缓存**：Redis 6.0+
- **缓存策略**：LRU淘汰策略
- **数据类型**：String、Hash、List、Set
- **持久化**：RDB + AOF
#### 文件存储
- **对象存储**：MinIO / 阿里云OSS
- **CDN加速**：阿里云CDN
- **图片处理**：ImageMagick
- **文件类型**：图片、文档、视频
### 开发工具
#### 版本控制
- **代码仓库**：Git
- **分支策略**：Git Flow
- **代码审查**：Pull Request
#### 代码质量
- **代码规范**：ESLint + Prettier
- **类型检查**：TypeScript
- **单元测试**：Jest + Supertest
- **集成测试**：Postman + Newman
#### 容器化部署
- **容器技术**：Docker
- **编排工具**：Docker Compose
- **镜像仓库**：Docker Hub / 阿里云容器镜像服务
## 🏢 系统架构设计
### 整体架构图
```mermaid
graph TB
subgraph "客户端层"
A[微信小程序]
B[后台管理系统]
C[官方网站]
end
subgraph "网关层"
D[Nginx负载均衡]
E[API网关]
end
subgraph "应用服务层"
F[用户服务]
G[旅行服务]
H[动物服务]
I[商家服务]
J[订单服务]
K[消息服务]
end
subgraph "数据存储层"
L[MySQL主库]
M[MySQL从库]
N[Redis缓存]
O[MinIO对象存储]
end
subgraph "基础设施层"
P[监控系统]
Q[日志系统]
R[配置中心]
end
A --> D
B --> D
C --> D
D --> E
E --> F
E --> G
E --> H
E --> I
E --> J
E --> K
F --> L
G --> L
H --> L
I --> L
J --> L
K --> L
L --> M
F --> N
G --> N
H --> N
I --> O
F --> P
G --> Q
H --> R
```
### 微服务架构（Java版本）
```mermaid
graph TB
subgraph "服务注册中心"
A[Eureka Server]
end
subgraph "API网关"
B[Gateway Service]
end
subgraph "业务服务"
C[用户服务 User Service]
D[认证服务 Auth Service]
E[旅行服务 Travel Service]
F[动物服务 Animal Service]
G[订单服务 Order Service]
H[推广服务 Promotion Service]
end
subgraph "数据层"
I[MySQL集群]
J[Redis集群]
K[消息队列 RabbitMQ]
end
B --> A
C --> A
D --> A
E --> A
F --> A
G --> A
H --> A
B --> C
B --> D
B --> E
B --> F
B --> G
B --> H
C --> I
D --> I
E --> I
F --> I
G --> I
H --> I
C --> J
E --> J
F --> J
G --> K
H --> K
```
## 🗄️ 数据库设计
### 数据库架构
#### 主从复制架构
```mermaid
graph LR
A[应用服务器] --> B[MySQL主库]
B --> C[MySQL从库1]
B --> D[MySQL从库2]
A --> C
A --> D
```
#### 分库分表策略
- **用户表**：按用户ID取模分表
- **订单表**：按时间分表（月表）
- **日志表**：按日期分表（日表）
### 核心表结构
#### 用户相关表
```sql
-- 用户基础信息表
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT,
openid VARCHAR(100) UNIQUE NOT NULL COMMENT '微信openid',
nickname VARCHAR(50) NOT NULL COMMENT '用户昵称',
avatar VARCHAR(255) COMMENT '头像URL',
gender ENUM('male', 'female', 'unknown') DEFAULT 'unknown',
birthday DATE COMMENT '生日',
phone VARCHAR(20) COMMENT '手机号',
email VARCHAR(100) COMMENT '邮箱',
travel_count INT DEFAULT 0 COMMENT '旅行次数',
animal_claim_count INT DEFAULT 0 COMMENT '认领动物数量',
status ENUM('active', 'inactive', 'banned') DEFAULT 'active',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_openid (openid),
INDEX idx_phone (phone),
INDEX idx_status (status)
);
```
#### 旅行相关表
```sql
-- 旅行计划表
CREATE TABLE travel_plans (
id INT PRIMARY KEY AUTO_INCREMENT,
user_id INT NOT NULL,
destination VARCHAR(100) NOT NULL COMMENT '目的地',
start_date DATE NOT NULL COMMENT '开始日期',
end_date DATE NOT NULL COMMENT '结束日期',
budget DECIMAL(10,2) COMMENT '预算',
interests TEXT COMMENT '兴趣偏好',
description TEXT COMMENT '行程描述',
visibility ENUM('public', 'friends', 'private') DEFAULT 'public',
max_participants INT DEFAULT 4 COMMENT '最大参与人数',
current_participants INT DEFAULT 1 COMMENT '当前参与人数',
status ENUM('active', 'completed', 'cancelled') DEFAULT 'active',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id),
INDEX idx_destination (destination),
INDEX idx_date_range (start_date, end_date),
INDEX idx_status (status)
);
```
#### 动物认领表
```sql
-- 动物信息表
CREATE TABLE animals (
id INT PRIMARY KEY AUTO_INCREMENT,
merchant_id INT NOT NULL,
name VARCHAR(50) NOT NULL COMMENT '动物名称',
type ENUM('cow', 'sheep', 'pig', 'chicken') NOT NULL COMMENT '动物类型',
breed VARCHAR(50) COMMENT '品种',
age INT COMMENT '年龄（月）',
gender ENUM('male', 'female') COMMENT '性别',
description TEXT COMMENT '动物描述',
images JSON COMMENT '动物图片',
price DECIMAL(10,2) NOT NULL COMMENT '认领价格',
farm_location VARCHAR(100) COMMENT '农场位置',
status ENUM('available', 'claimed', 'unavailable') DEFAULT 'available',
claim_count INT DEFAULT 0 COMMENT '被认领次数',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (merchant_id) REFERENCES merchants(id),
INDEX idx_type (type),
INDEX idx_status (status),
INDEX idx_price (price)
);
```
## 🔐 安全架构
### 认证授权机制
#### JWT Token认证
```mermaid
sequenceDiagram
participant C as 客户端
participant A as 认证服务
participant S as 业务服务
participant D as 数据库
C->>A: 微信登录请求
A->>D: 验证用户信息
D-->>A: 返回用户数据
A-->>C: 返回JWT Token
C->>S: 携带Token请求业务接口
S->>S: 验证Token有效性
S->>D: 查询业务数据
D-->>S: 返回业务数据
S-->>C: 返回业务响应
```
#### 权限控制
- **角色定义**：普通用户、商家用户、管理员
- **权限粒度**：接口级权限控制
- **权限验证**：中间件统一验证
### 数据安全
#### 数据加密
- **传输加密**：HTTPS/TLS 1.3
- **存储加密**：敏感数据AES-256加密
- **密码加密**：bcrypt哈希算法
#### 数据脱敏
- **手机号脱敏**：中间4位显示为*
- **身份证脱敏**：中间部分显示为*
- **银行卡脱敏**：只显示后4位
## 🚀 性能优化
### 缓存策略
#### Redis缓存设计
```mermaid
graph TB
A[客户端请求] --> B{缓存命中?}
B -->|是| C[返回缓存数据]
B -->|否| D[查询数据库]
D --> E[更新缓存]
E --> F[返回数据]
```
#### 缓存层级
- **L1缓存**：应用内存缓存（Node.js内存）
- **L2缓存**：Redis分布式缓存
- **L3缓存**：CDN边缘缓存
### 数据库优化
#### 索引策略
- **主键索引**：所有表必须有主键
- **唯一索引**：唯一字段建立唯一索引
- **复合索引**：多字段查询建立复合索引
- **覆盖索引**：高频查询建立覆盖索引
#### 查询优化
- **分页查询**：使用LIMIT + OFFSET
- **批量操作**：使用批量插入/更新
- **读写分离**：读操作走从库，写操作走主库
## 📊 监控运维
### 系统监控
#### 监控指标
- **系统指标**：CPU、内存、磁盘、网络
- **应用指标**：QPS、响应时间、错误率
- **业务指标**：用户活跃度、订单量、收入
#### 监控工具
- **系统监控**：Prometheus + Grafana
- **应用监控**：APM工具
- **日志监控**：ELK Stack
### 日志管理
#### 日志分类
- **访问日志**：记录所有API请求
- **错误日志**：记录系统异常和错误
- **业务日志**：记录关键业务操作
- **审计日志**：记录敏感操作
#### 日志格式
```json
{
"timestamp": "2025-01-01T12:00:00.000Z",
"level": "info",
"service": "user-service",
"traceId": "abc123",
"userId": 1001,
"action": "login",
"message": "用户登录成功",
"duration": 150,
"ip": "192.168.1.100"
}
```
## 🔄 部署架构
### 容器化部署
#### Docker容器设计
```dockerfile
# Node.js应用容器
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
```
#### Docker Compose编排
```yaml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
depends_on:
- mysql
- redis
environment:
- NODE_ENV=production
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
volumes:
- mysql_data:/var/lib/mysql
redis:
image: redis:6-alpine
volumes:
- redis_data:/data
volumes:
mysql_data:
redis_data:
```
### 负载均衡
#### Nginx配置
```nginx
upstream backend {
server app1:3000 weight=1;
server app2:3000 weight=1;
server app3:3000 weight=1;
}
server {
listen 80;
server_name api.jiebanke.com;
location / {
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
```
## 📈 扩展性设计
### 水平扩展
#### 应用层扩展
- **无状态设计**：应用服务无状态，支持水平扩展
- **负载均衡**：通过负载均衡器分发请求
- **自动扩缩容**：基于CPU/内存使用率自动扩缩容
#### 数据层扩展
- **读写分离**：主库写入，从库读取
- **分库分表**：按业务或数据量分库分表
- **缓存集群**：Redis集群模式
### 垂直扩展
#### 服务拆分
- **按业务拆分**：用户服务、订单服务、支付服务
- **按功能拆分**：认证服务、通知服务、文件服务
- **按数据拆分**：用户数据、业务数据、日志数据
## 🔮 技术演进规划
### 短期规划（3-6个月）
- 完善监控告警系统
- 优化数据库性能
- 增强安全防护机制
### 中期规划（6-12个月）
- 微服务架构改造
- 引入消息队列
- 实现服务治理
### 长期规划（1-2年）
- 云原生架构转型
- 大数据分析平台
- AI智能推荐系统
---
*文档版本：v1.0*
*最后更新：2025年1月*

708
docs/部署指南.md Normal file
View File

@@ -0,0 +1,708 @@
# 📦 结伴客系统部署指南
## 📋 部署概述
本文档详细说明了结伴客项目的完整部署流程，包括开发环境、测试环境和生产环境的部署配置。项目采用容器化部署方式，支持快速部署和弹性扩容。
## 🛠️ 环境要求
### 系统要求
- **操作系统**：Ubuntu 20.04+ / CentOS 7+ / macOS 10.15+
- **CPU**：最低2核，推荐4核+
- **内存**：最低4GB，推荐8GB+
- **存储**：最低20GB可用空间，推荐50GB+
- **网络**：稳定的互联网连接，带宽10Mbps+
### 软件依赖
#### 基础软件
- **Node.js**：16.x 或 18.x LTS版本
- **npm**：8.x+ 或 yarn 1.22+
- **Git**：2.30+
- **Docker**：20.10+
- **Docker Compose**：2.0+
#### 数据库
- **MySQL**：8.0+
- **Redis**：6.0+（可选，用于缓存）
#### 其他工具
- **Nginx**：1.18+（用于反向代理）
- **PM2**：5.0+（用于进程管理）
- **微信开发者工具**：最新版本
## 🚀 快速部署
### 一键部署脚本
```bash
#!/bin/bash
# 快速部署脚本 - deploy.sh
echo "开始部署结伴客项目..."
# 1. 克隆项目
git clone https://github.com/your-org/jiebanke.git
cd jiebanke
# 2. 安装依赖
echo "安装项目依赖..."
npm install
# 3. 配置环境变量
echo "配置环境变量..."
cp .env.example .env
# 4. 初始化数据库
echo "初始化数据库..."
npm run db:migrate
npm run db:seed
# 5. 构建项目
echo "构建项目..."
npm run build
# 6. 启动服务
echo "启动服务..."
npm run start:prod
echo "部署完成！访问 http://localhost:3000"
```
### Docker一键部署
```bash
# 使用Docker Compose一键部署
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
```
## 🏗️ 开发环境部署
### 1. 环境准备
#### 安装Node.js
```bash
# 使用nvm安装Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18
```
#### 安装MySQL
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install mysql-server
# macOS
brew install mysql
brew services start mysql
# 创建数据库
mysql -u root -p
CREATE DATABASE jiebandata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'jieban'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON jiebandata.* TO 'jieban'@'localhost';
FLUSH PRIVILEGES;
```
### 2. 项目配置
#### 克隆项目代码
```bash
git clone https://github.com/your-org/jiebanke.git
cd jiebanke
```
#### 安装项目依赖
```bash
# 后端依赖
cd backend
npm install
# 前端管理系统依赖
cd ../admin-system
npm install
# 小程序依赖
cd ../mini-program
npm install
# 官网依赖
cd ../website
npm install
```
#### 配置环境变量
```bash
# 复制环境变量模板
cd backend
cp .env.example .env
# 编辑环境变量
vim .env
```
**环境变量配置示例：**
```env
# 应用配置
NODE_ENV=development
PORT=3000
APP_NAME=结伴客
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=jiebandata
DB_USER=jieban
DB_PASSWORD=password
# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
# JWT配置
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=7d
# 微信小程序配置
WECHAT_APP_ID=your-wechat-app-id
WECHAT_APP_SECRET=your-wechat-app-secret
# 文件上传配置
UPLOAD_PATH=./uploads
MAX_FILE_SIZE=10485760
# 邮件配置
SMTP_HOST=smtp.qq.com
SMTP_PORT=587
SMTP_USER=your-email@qq.com
SMTP_PASS=your-email-password
```
### 3. 数据库初始化
```bash
# 运行数据库迁移
cd backend
npm run db:migrate
# 运行数据库种子文件
npm run db:seed
# 或者直接执行SQL文件
mysql -u jieban -p jiebandata < scripts/init-database.sql
```
### 4. 启动开发服务
```bash
# 启动后端服务
cd backend
npm run dev
# 启动前端管理系统（新终端）
cd admin-system
npm run dev
# 启动官网（新终端）
cd website
npm run dev
```
### 5. 验证部署
访问以下地址验证部署是否成功：
- 后端API：http://localhost:3000/api/health
- 管理系统：http://localhost:8080
- 官网：http://localhost:8081
## 🧪 测试环境部署
### 1. 服务器配置
#### 服务器信息
- **主机**：192.168.0.240
- **操作系统**：Ubuntu 20.04
- **用户**：deploy
- **部署路径**：/var/www/jiebanke
#### 环境变量配置
```env
NODE_ENV=testing
PORT=3000
DB_HOST=192.168.0.240
DB_PORT=3306
DB_NAME=jiebandata_test
DB_USER=jieban_test
DB_PASSWORD=test_password
```
### 2. 自动化部署脚本
```bash
#!/bin/bash
# 测试环境部署脚本 - deploy-test.sh
SERVER_HOST="192.168.0.240"
SERVER_USER="deploy"
DEPLOY_PATH="/var/www/jiebanke"
echo "开始部署到测试环境..."
# 1. 构建项目
echo "构建项目..."
npm run build
# 2. 打包文件
echo "打包部署文件..."
tar -czf jiebanke-$(date +%Y%m%d-%H%M%S).tar.gz \
backend/ admin-system/dist/ website/dist/ \
package.json docker-compose.yml
# 3. 上传到服务器
echo "上传文件到服务器..."
scp jiebanke-*.tar.gz $SERVER_USER@$SERVER_HOST:$DEPLOY_PATH/
# 4. 远程部署
echo "执行远程部署..."
ssh $SERVER_USER@$SERVER_HOST << 'EOF'
cd /var/www/jiebanke
tar -xzf jiebanke-*.tar.gz
docker-compose down
docker-compose up -d --build
docker-compose ps
EOF
echo "测试环境部署完成！"
```
## 🌐 生产环境部署
### 1. 服务器配置
#### 服务器信息
- **主机**：129.211.213.226
- **端口**：9527
- **操作系统**：CentOS 7
- **用户**：root
- **部署路径**：/opt/jiebanke
#### 高可用架构
```mermaid
graph TB
A[负载均衡器 Nginx] --> B[应用服务器1]
A --> C[应用服务器2]
A --> D[应用服务器3]
B --> E[MySQL主库]
C --> E
D --> E
E --> F[MySQL从库1]
E --> G[MySQL从库2]
B --> H[Redis集群]
C --> H
D --> H
```
### 2. Docker容器化部署
#### Dockerfile配置
```dockerfile
# 后端服务Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
USER node
CMD ["npm", "start"]
```
#### Docker Compose配置
```yaml
version: '3.8'
services:
# 后端API服务
api:
build:
context: ./backend
dockerfile: Dockerfile
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- DB_HOST=mysql
- REDIS_HOST=redis
depends_on:
- mysql
- redis
restart: unless-stopped
networks:
- jiebanke-network
# 前端管理系统
admin:
build:
context: ./admin-system
dockerfile: Dockerfile
ports:
- "8080:80"
restart: unless-stopped
networks:
- jiebanke-network
# MySQL数据库
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
MYSQL_DATABASE: jiebandata
MYSQL_USER: jieban
MYSQL_PASSWORD: ${MYSQL_PASSWORD}
volumes:
- mysql_data:/var/lib/mysql
- ./scripts/init-database.sql:/docker-entrypoint-initdb.d/init.sql
ports:
- "3306:3306"
restart: unless-stopped
networks:
- jiebanke-network
# Redis缓存
redis:
image: redis:6-alpine
command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD}
volumes:
- redis_data:/data
ports:
- "6379:6379"
restart: unless-stopped
networks:
- jiebanke-network
# Nginx反向代理
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf
- ./nginx/ssl:/etc/nginx/ssl
depends_on:
- api
- admin
restart: unless-stopped
networks:
- jiebanke-network
volumes:
mysql_data:
redis_data:
networks:
jiebanke-network:
driver: bridge
```
### 3. Nginx配置
```nginx
# nginx.conf
upstream api_backend {
server api:3000;
}
upstream admin_backend {
server admin:80;
}
# API服务器配置
server {
listen 80;
server_name api.jiebanke.com;
# 重定向到HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name api.jiebanke.com;
# SSL证书配置
ssl_certificate /etc/nginx/ssl/api.jiebanke.com.crt;
ssl_certificate_key /etc/nginx/ssl/api.jiebanke.com.key;
# SSL安全配置
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
# 安全头
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
# API代理
location /api/ {
proxy_pass http://api_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 超时配置
proxy_connect_timeout 30s;
proxy_send_timeout 30s;
proxy_read_timeout 30s;
}
# 文件上传大小限制
client_max_body_size 10M;
}
# 管理系统配置
server {
listen 443 ssl http2;
server_name admin.jiebanke.com;
ssl_certificate /etc/nginx/ssl/admin.jiebanke.com.crt;
ssl_certificate_key /etc/nginx/ssl/admin.jiebanke.com.key;
location / {
proxy_pass http://admin_backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### 4. 生产环境部署脚本
```bash
#!/bin/bash
# 生产环境部署脚本 - deploy-prod.sh
set -e
PROD_SERVER="129.211.213.226"
PROD_USER="root"
DEPLOY_PATH="/opt/jiebanke"
BACKUP_PATH="/opt/backups"
echo "开始生产环境部署..."
# 1. 备份当前版本
echo "备份当前版本..."
ssh $PROD_USER@$PROD_SERVER << EOF
if [ -d "$DEPLOY_PATH" ]; then
sudo mkdir -p $BACKUP_PATH
sudo tar -czf $BACKUP_PATH/jiebanke-backup-$(date +%Y%m%d-%H%M%S).tar.gz -C $DEPLOY_PATH .
fi
EOF
# 2. 构建生产版本
echo "构建生产版本..."
NODE_ENV=production npm run build
# 3. 创建部署包
echo "创建部署包..."
tar -czf jiebanke-prod-$(date +%Y%m%d-%H%M%S).tar.gz \
backend/ admin-system/dist/ website/dist/ \
docker-compose.prod.yml nginx/ scripts/
# 4. 上传到生产服务器
echo "上传到生产服务器..."
scp jiebanke-prod-*.tar.gz $PROD_USER@$PROD_SERVER:$DEPLOY_PATH/
# 5. 执行部署
echo "执行生产部署..."
ssh $PROD_USER@$PROD_SERVER << 'EOF'
cd /opt/jiebanke
tar -xzf jiebanke-prod-*.tar.gz
# 停止旧服务
docker-compose -f docker-compose.prod.yml down
# 启动新服务
docker-compose -f docker-compose.prod.yml up -d --build
# 等待服务启动
sleep 30
# 检查服务状态
docker-compose -f docker-compose.prod.yml ps
# 健康检查
curl -f http://localhost:3000/api/health || exit 1
echo "生产环境部署成功！"
EOF
echo "部署完成！"
```
## 🔍 部署验证
### 健康检查
```bash
# API健康检查
curl -X GET http://localhost:3000/api/health
# 数据库连接检查
curl -X GET http://localhost:3000/api/health/db
# Redis连接检查
curl -X GET http://localhost:3000/api/health/redis
```
### 性能测试
```bash
# 使用Apache Bench进行压力测试
ab -n 1000 -c 10 http://localhost:3000/api/health
# 使用wrk进行性能测试
wrk -t12 -c400 -d30s http://localhost:3000/api/health
```
## 📊 监控配置
### 系统监控
#### Prometheus配置
```yaml
# prometheus.yml
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'jiebanke-api'
static_configs:
- targets: ['localhost:3000']
metrics_path: '/metrics'
```
#### Grafana仪表板
- **系统指标**：CPU、内存、磁盘使用率
- **应用指标**：QPS、响应时间、错误率
- **业务指标**：用户注册量、订单量、收入
### 日志管理
#### 日志收集配置
```yaml
# filebeat.yml
filebeat.inputs:
- type: log
enabled: true
paths:
- /opt/jiebanke/logs/*.log
fields:
service: jiebanke
environment: production
output.elasticsearch:
hosts: ["elasticsearch:9200"]
```
## 🚨 故障排除
### 常见问题
#### 1. 数据库连接失败
```bash
# 检查数据库服务状态
docker-compose ps mysql
# 查看数据库日志
docker-compose logs mysql
# 测试数据库连接
mysql -h localhost -u jieban -p jiebandata
```
#### 2. Redis连接失败
```bash
# 检查Redis服务状态
docker-compose ps redis
# 测试Redis连接
redis-cli -h localhost -p 6379 ping
```
#### 3. 应用启动失败
```bash
# 查看应用日志
docker-compose logs api
# 检查环境变量
docker-compose exec api env
# 进入容器调试
docker-compose exec api sh
```
### 回滚操作
```bash
#!/bin/bash
# 回滚脚本 - rollback.sh
BACKUP_FILE=$1
DEPLOY_PATH="/opt/jiebanke"
if [ -z "$BACKUP_FILE" ]; then
echo "请指定备份文件名"
exit 1
fi
echo "开始回滚到版本: $BACKUP_FILE"
# 停止当前服务
docker-compose down
# 恢复备份
tar -xzf /opt/backups/$BACKUP_FILE -C $DEPLOY_PATH
# 启动服务
docker-compose up -d
echo "回滚完成！"
```
## 📞 技术支持
### 联系方式
- **技术支持邮箱**：tech-support@jiebanke.com
- **紧急联系电话**：400-xxx-xxxx
- **技术文档**：https://docs.jiebanke.com
### 支持时间
- **工作日**：9:00 - 18:00
- **紧急故障**：7×24小时响应
---
*文档版本：v1.0*
*最后更新：2025年1月*

109
docs/项目概述.md Normal file
View File

@@ -0,0 +1,109 @@
# 结伴客项目概述
## 📋 项目简介
结伴客是一个创新的社交旅行平台，专注于为用户提供结伴旅行服务，并融入了独特的动物认领功能。该项目包含微信小程序、后台管理系统和官方网站三个核心模块，为用户和商家提供完整的服务生态。
## 🎯 产品定位
结伴客不仅仅是一个旅行社交平台，更是一个融合了农场体验、动物互动的创新服务平台。通过结合传统的结伴旅行功能与现代的动物认领体验，为用户创造独特的旅行记忆。
## 👥 目标用户
### 普通用户
- 热爱旅行的年轻人群
- 希望通过旅行结识新朋友的用户
- 对农场生活和动物互动感兴趣的用户
- 追求个性化旅行体验的用户
### 商家用户
- **花店商家**：提供鲜花产品和相关服务
- **活动组织者**：组织各类结伴活动和旅行项目
- **农场主**：提供动物认领和农场体验服务
- **旅行服务商**：提供专业的旅行规划和服务
## 🌟 核心功能
### 结伴旅行
- 智能匹配系统，根据兴趣爱好和行程安排匹配旅伴
- 多样化的活动类型：旅行、看电影、聚餐、桌游等
- 基于地理位置的本地化服务推荐
### 动物认领
- 提供牛、羊、猪、鸡等多种动物的认领服务
- 实时动物状态更新和成长记录
- 农场实地探访和互动体验
### 商家服务
- 完善的商家入驻和管理系统
- 多元化的产品和服务展示平台
- 订单管理和客户服务支持
## 🏗️ 技术架构
### 前端技术栈
- **微信小程序**：原生小程序开发 + Vant Weapp UI组件
- **后台管理系统**：Vue 3 + TypeScript + Element Plus
- **官方网站**：Vue 3 + Vue Router + 响应式设计
### 后端技术栈
- **Node.js版本**：Express.js + Sequelize ORM + MySQL
- **Java微服务版本**：Spring Boot + Spring Cloud + MyBatis Plus
- **数据存储**：MySQL 8.0 + Redis缓存
- **认证授权**：JWT Token + 微信OAuth
### 部署架构
- **容器化部署**：Docker + Docker Compose
- **负载均衡**：Nginx反向代理
- **数据库**：MySQL主从复制
- **缓存系统**：Redis集群
## 📁 项目结构
```
jiebanke/
├── mini-program/ # 微信小程序
├── admin-system/ # 后台管理系统
├── website/ # 官方网站
├── backend/ # Node.js后端服务
├── backend-java/ # Java微服务后端
├── fastapi-backend/ # FastAPI后端（实验性）
├── docs/ # 项目文档
└── scripts/ # 部署和工具脚本
```
## 🚀 快速开始
### 环境要求
- Node.js 16.x 或更高版本
- MySQL 8.0+
- Redis 6.0+（可选）
- 微信开发者工具
### 安装步骤
1. 克隆项目代码
2. 安装项目依赖
3. 配置数据库连接
4. 启动开发服务器
详细的安装和部署说明请参考 [部署指南](./部署指南.md)
## 📚 文档导航
- [产品需求文档](./产品需求文档.md) - 详细的功能需求和业务逻辑
- [系统架构文档](./系统架构文档.md) - 技术架构和系统设计
- [API接口文档](./API接口文档.md) - 完整的API接口说明
- [数据库设计文档](./数据库设计文档.md) - 数据库表结构和关系
- [部署指南](./部署指南.md) - 系统部署和运维说明
- [开发指南](./开发指南.md) - 开发规范和最佳实践
## 📞 联系我们
如有任何问题或建议，请通过以下方式联系我们：
- 项目仓库：[GitHub Repository]
- 技术支持：[技术支持邮箱]
- 产品反馈：[产品反馈渠道]
---
*最后更新时间：2025年1月*