diff --git a/docs/API-README.md b/docs/API-README.md deleted file mode 100644 index cdf3a91..0000000 --- a/docs/API-README.md +++ /dev/null @@ -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 \ No newline at end of file diff --git a/docs/API_DOCS.md b/docs/API_DOCS.md deleted file mode 100644 index 2101487..0000000 --- a/docs/API_DOCS.md +++ /dev/null @@ -1,531 +0,0 @@ -# 📚 结伴客API接口文档 - -## 📋 文档说明 -本文档详细描述了结伴客项目的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。 - -## 🔐 认证方式 - -### JWT Token 认证 -所有需要认证的API必须在请求头中携带Token： -``` -Authorization: Bearer -``` - -### 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 -``` - -**响应示例:** -```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 -``` - -**请求参数:** -```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 -``` - -**查询参数:** -``` -?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 -``` - -**请求参数:** -```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 -``` - -**请求参数:** -```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 -``` - -**请求参数:** -```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 " -``` - -### 使用Postman测试 -1. 导入Postman集合文件 -2. 设置环境变量（base_url, token等） -3. 运行测试用例 - -## 📝 更新日志 - -### v1.0.0 (2024-01-01) -- 微信用户登录接口 -- 旅行结伴管理接口 -- 动物认领管理接口 -- 送花服务接口 -- 基础认证系统 - ---- -*最后更新: 2024年* 📅 \ No newline at end of file diff --git a/docs/API_DOCS_JAVA.md b/docs/API_DOCS_JAVA.md deleted file mode 100644 index 067d5cc..0000000 --- a/docs/API_DOCS_JAVA.md +++ /dev/null @@ -1,617 +0,0 @@ -# 📚 结伴客Java微服务API接口文档 - -## 📋 文档说明 -本文档详细描述了结伴客项目Java微服务架构的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。 - -## 🔐 认证方式 - -### JWT Token 认证 -所有需要认证的API必须在请求头中携带Token： -``` -Authorization: Bearer -``` - -### 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 -``` - -**响应示例:** -```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 -``` - -**请求参数:** -```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 -``` - -**查询参数:** -``` -?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 -``` - -**请求参数:** -```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 -``` - -**请求参数:** -```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 -``` - -**请求参数:** -```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 -``` - -**请求参数:** -```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 " -``` - -### 使用Postman测试 -1. 导入Postman集合文件 -2. 设置环境变量（base_url, token等） -3. 运行测试用例 - -## 📝 更新日志 - -### v1.0.0 (2025-09-10) -- 微信用户登录接口 -- 旅行结伴管理接口 -- 动物认领管理接口 -- 送花服务接口 -- 推广活动接口 -- 基础认证系统 - ---- -*最后更新: 2025年* 📅 \ No newline at end of file diff --git a/docs/API接口文档.md b/docs/API接口文档.md new file mode 100644 index 0000000..eb0a34c --- /dev/null +++ b/docs/API接口文档.md @@ -0,0 +1,466 @@ +# 📚 结伴客API接口文档 + +## 📋 文档说明 + +本文档详细描述了结伴客项目的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。 + +**基础信息：** +- 基础URL：`https://api.jiebanke.com` +- API版本：`v1` +- 数据格式：`JSON` +- 字符编码：`UTF-8` + +## 🔐 认证方式 + +### JWT Token 认证 +所有需要认证的API必须在请求头中携带Token： +```http +Authorization: Bearer +``` + +### 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 +``` + +**响应示例：** +```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月* \ No newline at end of file diff --git a/docs/CHANGELOG_JAVA.md b/docs/CHANGELOG_JAVA.md deleted file mode 100644 index 8b278bb..0000000 --- a/docs/CHANGELOG_JAVA.md +++ /dev/null @@ -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日* 📅 \ No newline at end of file diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md deleted file mode 100644 index 26eb5cd..0000000 --- a/docs/DEPLOYMENT.md +++ /dev/null @@ -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 -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 -``` - -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 缓存热点数据 diff --git a/docs/DEPLOYMENT_JAVA.md b/docs/DEPLOYMENT_JAVA.md deleted file mode 100644 index ace0261..0000000 --- a/docs/DEPLOYMENT_JAVA.md +++ /dev/null @@ -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 -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 -``` - -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 - -# 重新构建容器 -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年* 📅 \ No newline at end of file diff --git a/docs/DEVELOPMENT_GUIDE_JAVA.md b/docs/DEVELOPMENT_GUIDE_JAVA.md deleted file mode 100644 index b528600..0000000 --- a/docs/DEVELOPMENT_GUIDE_JAVA.md +++ /dev/null @@ -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 -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 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> response = restTemplate.getForEntity( - "/api/users/1", - new ParameterizedTypeReference>() {} - ); - - // 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 -# 提交信息格式 -(): - -# 示例 -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 -``` - -### 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年* 📅 \ No newline at end of file diff --git a/docs/PERFORMANCE_OPTIMIZATION_JAVA.md b/docs/PERFORMANCE_OPTIMIZATION_JAVA.md deleted file mode 100644 index 95b1993..0000000 --- a/docs/PERFORMANCE_OPTIMIZATION_JAVA.md +++ /dev/null @@ -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 redisTemplate(RedisConnectionFactory connectionFactory) { - RedisTemplate 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 redisTemplate; - - // 本地缓存（Caffeine） - private Cache 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 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 - - - - logs/application.log - - logs/application.%d{yyyy-MM-dd}.%i.log - - 100MB - - 30 - 10GB - - - %d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n - - - - - - - -``` - -## 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年* 📅 \ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index f031b2a..0000000 --- a/docs/README.md +++ /dev/null @@ -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日* 📅 \ No newline at end of file diff --git a/docs/admin-design.md b/docs/admin-design.md deleted file mode 100644 index f3eb9fe..0000000 --- a/docs/admin-design.md +++ /dev/null @@ -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 | 优化数据统计功能 | \ No newline at end of file diff --git a/docs/api-documentation.md b/docs/api-documentation.md deleted file mode 100644 index b521244..0000000 --- a/docs/api-documentation.md +++ /dev/null @@ -1,3433 +0,0 @@ -# 结伴客系统 API 接口文档 - -## 基础信息 - -**Base URL**: `https://www.jiebanke.com/api/v1` - -**认证方式**: Bearer Token (JWT) - -**响应格式**: JSON - -**API版本**: v1 - -**开发状态**: 开发中 - -## 响应格式 - -### 成功响应 -```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" -} -``` - -## 通用状态码 - -| 状态码 | 说明 | -|--------|------| -| 200 | 请求成功 | -| 201 | 创建成功 | -| 400 | 请求参数错误 | -| 401 | 未授权访问 | -| 403 | 权限不足 | -| 404 | 资源不存在 | -| 429 | 请求过于频繁 | -| 500 | 服务器内部错误 | - -## 认证接口 - -### 1. 用户注册 - -**Endpoint**: `POST /auth/register` - -**描述**: 创建新用户账号 - -**请求体**: -```json -{ - "username": "string, required, 用户名(4-20字符)", - "password": "string, required, 密码(6-20字符)", - "nickname": "string, optional, 昵称", - "email": "string, optional, 邮箱", - "phone": "string, optional, 手机号", - "gender": "string, optional, 性别(male/female/unknown)", - "birthday": "string, optional, 生日(YYYY-MM-DD)" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "注册成功", - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@jiebanke.com", - "phone": "13800138000", - "avatar": "", - "gender": "unknown", - "points": 0, - "level": 1, - "status": "active", - "created_at": "2025-01-01T00:00:00.000Z" - }, - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." - } -} -``` - -### 2. 用户登录 - -**Endpoint**: `POST /auth/login` - -**描述**: 用户登录获取访问令牌 - -**请求体**: -```json -{ - "username": "string, required, 用户名/邮箱/手机号", - "password": "string, required, 密码" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "登录成功", - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@jiebanke.com", - "phone": "13800138000", - "avatar": "", - "gender": "unknown", - "points": 100, - "level": 2, - "status": "active", - "last_login_at": "2025-01-01T00:00:00.000Z" - }, - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." - } -} -``` - -### 3. 获取当前用户信息 - -**Endpoint**: `GET /auth/me` - -**认证**: 需要Bearer Token - -**描述**: 获取当前登录用户信息 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@jiebanke.com", - "phone": "13800138000", - "avatar": "https://www.jiebanke.com/avatar.jpg", - "gender": "male", - "birthday": "1990-01-01", - "points": 1000, - "level": 3, - "balance": 500.00, - "travel_count": 5, - "animal_adopt_count": 2, - "flower_order_count": 3, - "status": "active", - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z", - "last_login_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -### 4. 更新用户信息 - -**Endpoint**: `PUT /auth/profile` - -**认证**: 需要Bearer Token - -**描述**: 更新用户个人信息 - -**请求体**: -```json -{ - "nickname": "string, optional, 昵称", - "avatar": "string, optional, 头像URL", - "gender": "string, optional, 性别(male/female/other)", - "birthday": "string, optional, 生日(YYYY-MM-DD)" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "用户信息更新成功", - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "新昵称", - "avatar": "https://www.jiebanke.com/new-avatar.jpg", - "gender": "male", - "birthday": "1990-01-01", - "updated_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -### 5. 微信登录 - -**Endpoint**: `POST /auth/wechat-login` - -**描述**: 微信授权登录 - -**请求体**: -```json -{ - "code": "string, required, 微信授权码", - "userInfo": { - "nickName": "string, optional, 微信昵称", - "avatarUrl": "string, optional, 微信头像", - "gender": "number, optional, 性别(0:未知,1:男,2:女)" - } -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "微信登录成功", - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "avatar": "https://www.jiebanke.com/avatar.jpg", - "gender": "male", - "points": 100, - "level": 2, - "status": "active", - "last_login_at": "2025-01-01T00:00:00.000Z" - }, - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." - } -} -``` - -### 4. 获取当前用户信息 - -**Endpoint**: `GET /auth/me` - -**认证**: 需要Bearer Token - -**描述**: 获取当前登录用户信息 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@example.com", - "phone": "13800138000", - "avatar": "https://www.jiebanke.com/avatar.jpg", - "gender": "male", - "birthday": "1990-01-01", - "points": 1000, - "level": 3, - "balance": 500.00, - "travel_count": 5, - "animal_adopt_count": 2, - "flower_order_count": 3, - "status": "active", - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z", - "last_login_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -### 6. 更新用户信息 - -**Endpoint**: `PUT /auth/profile` - -**认证**: 需要Bearer Token - -**描述**: 更新用户个人信息 - -**请求体**: -```json -{ - "nickname": "string, optional, 昵称", - "avatar": "string, optional, 头像URL", - "gender": "string, optional, 性别(male/female/other)", - "birthday": "string, optional, 生日(YYYY-MM-DD)" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "用户信息更新成功", - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "新昵称", - "avatar": "https://example.com/new-avatar.jpg", - "gender": "male", - "birthday": "1990-01-01", - "updated_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 用户服务接口 - -### 1. 获取用户列表 - -**Endpoint**: `GET /users` - -**认证**: 需要Bearer Token - -**描述**: 获取用户列表（管理员权限） - -**查询参数**: -- `page` (可选): 页码，默认1 -- `limit` (可选): 每页数量，默认20 -- `username` (可选): 用户名模糊搜索 -- `status` (可选): 状态过滤 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "users": [ - { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@example.com", - "phone": "13800138000", - "avatar": "https://www.jiebanke.com/avatar.jpg", - "gender": "male", - "points": 100, - "level": 2, - "status": "active", - "created_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 100, - "page": 1, - "limit": 20, - "pages": 5 - } - } -} -``` - -### 2. 获取用户详情 - -**Endpoint**: `GET /users/{id}` - -**认证**: 需要Bearer Token - -**描述**: 获取指定用户的详细信息 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@example.com", - "phone": "13800138000", - "avatar": "https://www.jiebanke.com/avatar.jpg", - "gender": "male", - "birthday": "1990-01-01", - "points": 1000, - "level": 3, - "balance": 500.00, - "travel_count": 5, - "animal_adopt_count": 2, - "flower_order_count": 3, - "status": "active", - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 8. 管理员接口 - -### 8.1 管理员登录 -- **Endpoint**: POST /api/v1/admin/login -- **认证要求**: 无 -- **描述**: 管理员登录系统 -- **请求体**: -```json -{ - "username": "admin", - "password": "password123" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "登录成功", - "data": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", - "admin": { - "id": 1, - "username": "admin", - "email": "admin@jiebanke.com", - "nickname": "超级管理员", - "avatar": "https://example.com/avatar.jpg", - "role": "super_admin", - "status": 1, - "last_login": "2024-01-15T10:30:00.000Z" - } - } -} -``` - -### 8.2 获取管理员信息 -- **Endpoint**: GET /api/v1/admin/profile -- **认证要求**: Bearer Token -- **描述**: 获取当前登录管理员信息 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "nickname": "超级管理员", - "avatar": "https://example.com/avatar.jpg", - "role": "super_admin", - "status": 1, - "last_login": "2024-01-15T10:30:00.000Z", - "created_at": "2024-01-01T00:00:00.000Z", - "updated_at": "2024-01-15T10:30:00.000Z" - } -} -``` - -### 8.3 更新管理员信息 -- **Endpoint**: PUT /api/v1/admin/profile -- **认证要求**: Bearer Token -- **描述**: 更新当前登录管理员信息 -- **请求体**: -```json -{ - "nickname": "新昵称", - "email": "newemail@example.com", - "avatar": "https://example.com/new-avatar.jpg" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "更新成功", - "data": { - "id": 1, - "username": "admin", - "email": "newemail@example.com", - "nickname": "新昵称", - "avatar": "https://example.com/new-avatar.jpg", - "role": "super_admin", - "status": 1 - } -} -``` - -### 8.4 修改密码 -- **Endpoint**: PUT /api/v1/admin/password -- **认证要求**: Bearer Token -- **描述**: 修改当前登录管理员密码 -- **请求体**: -```json -{ - "old_password": "oldpassword123", - "new_password": "newpassword456" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "密码修改成功" -} -``` - -### 7. 获取管理员信息 - -**Endpoint**: `GET /auth/admin/me` - -**认证**: 需要Bearer Token - -**描述**: 获取当前登录管理员信息及权限 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "user": { - "id": 1, - "username": "admin", - "email": "admin@jiebanke.com", - "real_name": "管理员", - "avatar": "", - "status": "active", - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z", - "last_login_at": "2025-01-01T00:00:00.000Z" - }, - "roles": [ - { - "id": 2, - "name": "admin", - "description": "普通管理员" - } - ], - "permissions": [ - "user:manage", - "content:review", - "content:publish", - "data:view", - "data:export" - ] - } -} -``` - -### 9. 管理员后台接口 - -#### 9.1 用户管理接口 - -##### 9.1.1 获取用户列表 -- **Endpoint**: GET /api/v1/admin/users -- **认证要求**: Bearer Token，需要user:manage权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - `username` (可选): 用户名模糊搜索 - - `user_type` (可选): 用户类型过滤（normal/merchant/farmer/organizer） - - `status` (可选): 状态过滤（active/inactive/banned） - - `start_date` (可选): 注册开始时间 - - `end_date` (可选): 注册结束时间 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "users": [ - { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@example.com", - "phone": "13800138000", - "user_type": "normal", - "status": "active", - "points": 100, - "level": 2, - "travel_count": 5, - "animal_adopt_count": 2, - "flower_order_count": 3, - "created_at": "2025-01-01T00:00:00.000Z", - "last_login_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 100, - "page": 1, - "limit": 20, - "pages": 5 - }, - "statistics": { - "total_users": 100, - "active_users": 80, - "new_users_today": 5, - "merchant_users": 15, - "farmer_users": 10 - } - } -} -``` - -##### 9.1.2 获取用户详情 -- **Endpoint**: GET /api/v1/admin/users/{id} -- **认证要求**: Bearer Token，需要user:manage权限 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@example.com", - "phone": "13800138000", - "avatar": "https://example.com/avatar.jpg", - "gender": "male", - "birthday": "1990-01-01", - "user_type": "normal", - "status": "active", - "points": 1000, - "level": 3, - "balance": 500.00, - "travel_count": 5, - "animal_adopt_count": 2, - "flower_order_count": 3, - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z", - "last_login_at": "2025-01-01T00:00:00.000Z" - }, - "activity_stats": { - "last_7_days_login_count": 5, - "total_travel_plans": 3, - "total_animal_claims": 2, - "total_flower_orders": 1 - } - } -} -``` - -##### 9.1.3 更新用户状态 -- **Endpoint**: PUT /api/v1/admin/users/{id}/status -- **认证要求**: Bearer Token，需要user:manage权限 -- **请求体**: -```json -{ - "status": "banned", - "reason": "违反平台规则" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "用户状态更新成功" -} -``` - -##### 9.1.4 导出用户数据 -- **Endpoint**: GET /api/v1/admin/users/export -- **认证要求**: Bearer Token，需要user:manage权限 -- **查询参数**: - - `format` (可选): 导出格式（csv/excel），默认csv - - `start_date` (可选): 注册开始时间 - - `end_date` (可选): 注册结束时间 - - `user_type` (可选): 用户类型过滤 -- **响应**: 返回文件下载流 - -#### 9.2 商家审核接口 - -##### 9.2.1 获取待审核商家列表 -- **Endpoint**: GET /api/v1/admin/merchants/pending -- **认证要求**: Bearer Token，需要merchant:review权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - `merchant_type` (可选): 商家类型（flower_shop/farm/activity_organizer） -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "merchants": [ - { - "id": 1, - "user_id": 2, - "shop_name": "鲜花小店", - "merchant_type": "flower_shop", - "contact_name": "张老板", - "contact_phone": "13800138001", - "business_license": "https://www.jiebanke.com/license.jpg", - "status": "pending", - "apply_reason": "希望加入平台提供鲜花服务", - "created_at": "2025-01-01T00:00:00.000Z", - "user_info": { - "username": "merchant1", - "nickname": "花店老板", - "email": "merchant@jiebanke.com" - } - } - ], - "pagination": { - "total": 10, - "page": 1, - "limit": 20, - "pages": 1 - } - } -} -``` - -##### 9.2.2 审核商家申请 -- **Endpoint**: POST /api/v1/admin/merchants/{id}/review -- **认证要求**: Bearer Token，需要merchant:review权限 -- **请求体**: -```json -{ - "action": "approve", - "review_notes": "资质齐全，符合要求", - "reject_reason": "" -} -``` -或者 -```json -{ - "action": "reject", - "review_notes": "营业执照不清晰", - "reject_reason": "营业执照图片模糊，无法辨认" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "商家审核完成" -} -``` - -##### 9.2.3 获取商家列表 -- **Endpoint**: GET /api/v1/admin/merchants -- **认证要求**: Bearer Token，需要merchant:manage权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - "shop_name" (可选): 店铺名称模糊搜索 - - "merchant_type" (可选): 商家类型 - - "status" (可选): 状态（active/inactive/rejected） -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "merchants": [ - { - "id": 1, - "user_id": 2, - "shop_name": "鲜花小店", - "merchant_type": "flower_shop", - "contact_name": "张老板", - "contact_phone": "13800138001", - "business_license": "https://www.jiebanke.com/license.jpg", - "status": "active", - "total_products": 15, - "total_orders": 120, - "total_revenue": 5000.00, - "avg_rating": 4.8, - "created_at": "2025-01-01T00:00:00.000Z", - "approved_at": "2025-01-02T00:00:00.000Z" - } - ], - "pagination": { - "total": 50, - "page": 1, - "limit": 20, - "pages": 3 - }, - "statistics": { - "total_merchants": 50, - "active_merchants": 45, - "flower_shops": 20, - "farms": 15, - "organizers": 15, - "pending_reviews": 5 - } - } -} -``` - -#### 9.3 内容审核接口 - -##### 9.3.1 获取待审核内容列表 -- **Endpoint**: GET /api/v1/admin/content/pending -- **认证要求**: Bearer Token，需要content:review权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - `content_type` (可选): 内容类型（travel_plan/dynamic/comment） -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "contents": [ - { - "id": 1, - "type": "travel_plan", - "title": "云南大理之旅", - "content": "计划去大理游玩5天，寻找同行伙伴...", - "author_id": 3, - "author_name": "旅行爱好者", - "status": "pending", - "created_at": "2025-01-01T00:00:00.000Z", - "review_count": 0 - }, - { - "id": 2, - "type": "dynamic", - "title": "", - "content": "今天认领了一只可爱的小羊！", - "images": ["https://www.jiebanke.com/sheep.jpg"], - "author_id": 4, - "author_name": "动物爱好者", - "status": "pending", - "created_at": "2025-01-01T00:00:00.000Z", - "review_count": 0 - } - ], - "pagination": { - "total": 25, - "page": 1, - "limit": 20, - "pages": 2 - } - } -} -``` - -##### 9.3.2 审核内容 -- **Endpoint**: POST /api/v1/admin/content/{id}/review -- **认证要求**: Bearer Token，需要content:review权限 -- **请求体**: -```json -{ - "action": "approve", - "review_notes": "内容符合规范" -} -``` -或者 -```json -{ - "action": "reject", - "review_notes": "包含不当内容", - "reject_reason": "包含联系方式" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "内容审核完成" -} -``` - -##### 9.3.3 获取内容统计 -- **Endpoint**: GET /api/v1/admin/content/statistics -- **认证要求**: Bearer Token，需要content:review权限 -- **查询参数**: - - `days` (可选): 统计天数，默认7 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "total_contents": 1000, - "pending_review": 25, - "approved": 900, - "rejected": 75, - "daily_stats": [ - { - "date": "2025-01-01", - "total": 50, - "approved": 45, - "rejected": 5 - } - ], - "by_type": { - "travel_plan": 300, - "dynamic": 500, - "comment": 200 - } - } -} -``` - -#### 9.4 数据统计接口 - -##### 9.4.1 获取平台概览数据 -- **Endpoint**: GET /api/v1/admin/dashboard/overview -- **认证要求**: Bearer Token，需要data:view权限 -- **查询参数**: - - `days` (可选): 统计天数，默认30 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "user_stats": { - "total_users": 10000, - "new_users_today": 50, - "new_users_7d": 300, - "new_users_30d": 1200, - "active_users_7d": 2000, - "active_users_30d": 6000 - }, - "order_stats": { - "total_orders": 5000, - "today_orders": 25, - "revenue_today": 1250.00, - "revenue_7d": 8500.00, - "revenue_30d": 35000.00, - "avg_order_value": 70.00 - }, - "content_stats": { - "total_travel_plans": 2000, - "total_animal_claims": 800, - "total_flower_orders": 1200, - "total_dynamics": 3000 - }, - "merchant_stats": { - "total_merchants": 150, - "active_merchants": 120, - "flower_shops": 60, - "farms": 50, - "organizers": 40 - } - } -} -``` - -##### 9.4.2 获取用户增长图表 -- **Endpoint**: GET /api/v1/admin/dashboard/user-growth -- **认证要求**: Bearer Token，需要data:view权限 -- **查询参数**: - - `days` (可选): 统计天数，默认30 - - `group_by` (可选): 分组方式（day/week/month），默认day -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "chart_data": [ - { - "date": "2025-01-01", - "new_users": 45, - "total_users": 10045 - }, - { - "date": "2025-01-02", - "new_users": 52, - "total_users": 10097 - } - ], - "summary": { - "total_new_users": 1200, - "growth_rate": 12.5, - "avg_daily_new_users": 40 - } - } -} -``` - -##### 9.4.3 获取订单统计图表 -- **Endpoint**: GET /api/v1/admin/dashboard/order-stats -- **认证要求**: Bearer Token，需要data:view权限 -- **查询参数**: - - `days` (可选): 统计天数，默认30 - - `order_type` (可选): 订单类型（flower/animal/travel） -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "chart_data": [ - { - "date": "2025-01-01", - "total_orders": 28, - "total_revenue": 1960.00, - "flower_orders": 15, - "animal_orders": 8, - "travel_orders": 5 - } - ], - "summary": { - "total_revenue": 35000.00, - "avg_daily_revenue": 1166.67, - "order_conversion_rate": 8.5 - } - } -} -``` - -##### 9.4.4 导出数据报表 -- **Endpoint**: GET /api/v1/admin/dashboard/export -- **认证要求**: Bearer Token，需要data:export权限 -- **查询参数**: - - `report_type` (必选): 报表类型（users/orders/contents/merchants） - - `format` (可选): 格式（csv/excel），默认csv - - `start_date` (可选): 开始时间 - - `end_date` (可选): 结束时间 -- **响应**: 返回文件下载流 - -#### 9.5 权限管理接口 - -##### 9.5.1 获取管理员列表 -- **Endpoint**: GET /api/v1/admin/administrators -- **认证要求**: Bearer Token，需要admin:manage权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - `username` (可选): 用户名模糊搜索 - - `role` (可选): 角色过滤 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "admins": [ - { - "id": 1, - "username": "admin", - "email": "admin@example.com", - "nickname": "超级管理员", - "avatar": "https://example.com/avatar.jpg", - "role": "super_admin", - "status": 1, - "last_login": "2025-01-15T10:30:00.000Z", - "created_at": "2025-01-01T00:00:00.000Z", - "permissions": ["user:manage", "content:review", "data:view", "data:export"] - } - ], - "pagination": { - "total": 10, - "page": 1, - "limit": 20, - "pages": 1 - } - } -} -``` - -##### 9.5.2 创建管理员账号 -- **Endpoint**: POST /api/v1/admin/administrators -- **认证要求**: Bearer Token，需要admin:manage权限 -- **请求体**: -```json -{ - "username": "newadmin", - "password": "password123", - "email": "newadmin@example.com", - "nickname": "新管理员", - "role": "content_admin", - "permissions": ["content:review", "content:publish"] -} -``` -- **响应**: -```json -{ - "success": true, - "code": 201, - "message": "管理员创建成功", - "data": { - "id": 2, - "username": "newadmin", - "email": "newadmin@example.com", - "nickname": "新管理员", - "role": "content_admin", - "status": 1, - "created_at": "2025-01-01T00:00:00.000Z" - } -} -``` - -##### 9.5.3 更新管理员权限 -- **Endpoint**: PUT /api/v1/admin/administrators/{id}/permissions -- **认证要求**: Bearer Token，需要admin:manage权限 -- **请求体**: -```json -{ - "permissions": ["content:review", "content:publish", "data:view"] -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "权限更新成功" -} -``` - -##### 9.5.4 禁用/启用管理员账号 -- **Endpoint**: PUT /api/v1/admin/administrators/{id}/status -- **认证要求**: Bearer Token，需要admin:manage权限 -- **请求体**: -```json -{ - "status": 0 -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "管理员状态更新成功" -} -``` - -##### 9.5.5 获取权限列表 -- **Endpoint**: GET /api/v1/admin/permissions -- **认证要求**: Bearer Token，需要admin:manage权限 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "permissions": [ - { - "code": "user:manage", - "name": "用户管理", - "description": "管理用户账号和状态" - }, - { - "code": "content:review", - "name": "内容审核", - "description": "审核用户发布的内容" - }, - { - "code": "content:publish", - "name": "内容发布", - "description": "发布和管理平台内容" - }, - { - "code": "data:view", - "name": "数据查看", - "description": "查看平台统计数据" - }, - { - "code": "data:export", - "name": "数据导出", - "description": "导出数据报表" - }, - { - "code": "merchant:review", - "name": "商家审核", - "description": "审核商家入驻申请" - }, - { - "code": "merchant:manage", - "name": "商家管理", - "description": "管理商家账号和信息" - }, - { - "code": "admin:manage", - "name": "管理员管理", - "description": "管理其他管理员账号" - } - ] - } -} -``` - -#### 9.6 操作日志接口 - -##### 9.6.1 获取操作日志列表 -- **Endpoint**: GET /api/v1/admin/operation-logs -- **认证要求**: Bearer Token，需要admin:manage权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - `admin_id` (可选): 操作管理员ID - - `action_type` (可选): 操作类型 - - `start_date` (可选): 开始时间 - - `end_date` (可选): 结束时间 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "logs": [ - { - "id": 1, - "admin_id": 1, - "admin_name": "超级管理员", - "action_type": "user_status_update", - "target_type": "user", - "target_id": 5, - "target_name": "testuser", - "old_value": "active", - "new_value": "banned", - "ip_address": "192.168.1.100", - "user_agent": "Mozilla/5.0...", - "created_at": "2025-01-01T10:30:00.000Z" - } - ], - "pagination": { - "total": 1000, - "page": 1, - "limit": 20, - "pages": 50 - } - } -} -``` - -##### 9.6.2 导出操作日志 -- **Endpoint**: GET /api/v1/admin/operation-logs/export -- **认证要求**: Bearer Token，需要admin:manage权限 -- **查询参数**: - - `format` (可选): 格式（csv/excel），默认csv - - `start_date` (可选): 开始时间 - - `end_date` (可选): 结束时间 -- **响应**: 返回文件下载流 - ], - "pagination": { - "total": 100, - "page": 1, - "limit": 20, - "pages": 5 - } - } -} -``` - -#### 9.2 获取用户详情 -- **Endpoint**: GET /api/v1/users/{id} -- **认证要求**: Bearer Token，需要user:manage权限 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@example.com", - "phone": "13800138000", - "user_type": "farmer", - "status": "active", - "points": 100, - "level": 2, - "created_at": "2025-01-01T00:00:00.000Z", - "last_login_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -#### 9.3 更新用户状态 -- **Endpoint**: PUT /api/v1/users/{id}/status -- **认证要求**: Bearer Token，需要user:manage权限 -- **请求体**: -```json -{ - "status": "active" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "用户状态更新成功" -} -``` - -#### 9.4 删除用户 -- **Endpoint**: DELETE /api/v1/users/{id} -- **认证要求**: Bearer Token，需要user:manage权限 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "用户删除成功" -} -``` - -### 10. 系统管理接口 - -#### 10.1 获取系统信息 -- **Endpoint**: GET /api/v1/admin/system/info -- **认证要求**: Bearer Token，需要system:view权限 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "system": { - "version": "1.0.0", - "node_version": "v18.17.0", - "platform": "linux", - "arch": "x64", - "uptime": 123456, - "memory_usage": { - "total": 17179869184, - "used": 8589934592, - "free": 8589934592 - }, - "cpu_usage": 25.5 - } - } -} -``` - -#### 10.2 获取系统服务列表 -- **Endpoint**: GET /api/v1/admin/system/services -- **认证要求**: Bearer Token，需要system:manage权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - `type` (可选): 服务类型(database/cache/mq) - - `status` (可选): 服务状态(running/stopped) -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "services": [ - { - "id": "mysql", - "name": "MySQL数据库", - "type": "database", - "status": "running", - "host": "mysql.jiebanke.com", - "port": 3306, - "description": "主数据库服务", - "created_at": "2024-01-01T00:00:00.000Z", - "updated_at": "2024-01-15T10:30:00.000Z" - } - ], - "pagination": { - "total": 5, - "page": 1, - "limit": 20, - "pages": 1 - } - } -} -``` - -#### 10.3 更新服务状态 -- **Endpoint**: PUT /api/v1/admin/system/services/{id}/status -- **认证要求**: Bearer Token，需要system:manage权限 -- **请求体**: -```json -{ - "status": "stopped" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "服务状态更新成功" -} -``` - -#### 10.4 获取系统配置 -- **Endpoint**: GET /api/v1/admin/system/configs -- **认证要求**: Bearer Token，需要system:config权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - `group` (可选): 配置分组 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "configs": [ - { - "id": "site_name", - "name": "网站名称", - "value": "结伴客", - "type": "string", - "group": "basic", - "description": "网站显示名称", - "created_at": "2024-01-01T00:00:00.000Z", - "updated_at": "2024-01-15T10:30:00.000Z" - } - ], - "pagination": { - "total": 10, - "page": 1, - "limit": 20, - "pages": 1 - } - } -} -``` - -#### 10.5 更新系统配置 -- **Endpoint**: PUT /api/v1/admin/system/configs/{id} -- **认证要求**: Bearer Token，需要system:config权限 -- **请求体**: -```json -{ - "value": "新网站名称" -} -``` -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "配置更新成功" -} -``` - -### 11. 内容管理接口 - -#### 11.1 获取内容列表 -- **Endpoint**: GET /admin/contents -- **认证要求**: Bearer Token，需要content:review权限 -- **查询参数**: - - `page` (可选): 页码，默认1 - - `limit` (可选): 每页数量，默认20 - - `type` (可选): 内容类型 - - `status` (可选): 审核状态 -- **响应**: -```json -{ - "success": true, - "code": 200, - "message": "获取成功", - "data": { - "contents": [ - { - "id": 1, - "title": "测试内容", - "type": "article", - "author": "测试用户", - "status": "pending", - "created_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 50, - "page": 1, - "limit": 20, - "pages": 3 - } - } -} -``` - -#### 9.2 获取内容详情 - -**Endpoint**: `GET /admin/contents/{id}` - -**认证**: 需要Bearer Token，需要content:review权限 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "content": { - "id": 1, - "title": "测试内容", - "type": "article", - "content": "详细内容文本...", - "author": { - "id": 1, - "username": "testuser", - "nickname": "测试用户" - }, - "images": ["https://www.jiebanke.com/image1.jpg"], - "status": "pending", - "created_at": "2025-01-01T12:00:00.000Z", - "updated_at": "2025-01-01T12:00:00.000Z" - } - } -} -``` - -#### 9.3 审核内容 - -**Endpoint**: `PUT /admin/contents/{id}/review` - -**认证**: 需要Bearer Token，需要content:review权限 - -**请求体**: -```json -{ - "status": "string, required, 审核状态(approved/rejected)", - "review_comment": "string, optional, 审核意见" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "内容审核完成" -} -``` - -#### 9.4 批量审核内容 - -**Endpoint**: `POST /admin/contents/batch-review` - -**认证**: 需要Bearer Token，需要content:review权限 - -**请求体**: -```json -{ - "content_ids": ["number, required, 内容ID列表"], - "status": "string, required, 审核状态(approved/rejected)", - "review_comment": "string, optional, 审核意见" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "批量审核完成", - "data": { - "success_count": 5, - "failed_count": 0 - } -} -``` - -### 13. 商家管理接口 - -#### 13.1 获取商家申请列表 - -**Endpoint**: `GET /admin/merchant-applications` - -**认证**: 需要Bearer Token，需要merchant:approve权限 - -**查询参数**: -- `page` (可选): 页码，默认1 -- `limit` (可选): 每页数量，默认20 -- `status` (可选): 状态过滤(pending/approved/rejected) -- `business_name` (可选): 商家名称搜索 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "applications": [ - { - "id": 1, - "user_id": 1, - "business_name": "XX农场", - "contact_person": "张三", - "contact_phone": "13800138000", - "merchant_type": "farm_owner", - "status": "pending", - "created_at": "2025-01-01T12:00:00.000Z", - "updated_at": "2025-01-01T12:00:00.000Z" - } - ], - "pagination": { - "total": 15, - "page": 1, - "limit": 20, - "pages": 1 - } - } -} -``` - -#### 13.2 审核商家申请 - -**Endpoint**: `PUT /admin/merchant-applications/{id}/review` - -**认证**: 需要Bearer Token，需要merchant:approve权限 - -**请求体**: -```json -{ - "status": "string, required, 审核状态(approved/rejected)", - "review_comment": "string, optional, 审核意见" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "商家申请审核完成" -} -``` - -#### 13.3 获取商家列表 - -**Endpoint**: `GET /admin/merchants` - -**认证**: 需要Bearer Token，需要merchant:view权限 - -**查询参数**: -- `page` (可选): 页码，默认1 -- `limit` (可选): 每页数量，默认20 -- `merchant_type` (可选): 商家类型过滤 -- `status` (可选): 状态过滤(active/inactive) -- `business_name` (可选): 商家名称搜索 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "merchants": [ - { - "id": 1, - "user_id": 1, - "business_name": "XX农场", - "merchant_type": "farm_owner", - "contact_person": "张三", - "contact_phone": "13800138000", - "status": "active", - "product_count": 5, - "order_count": 20, - "total_revenue": 50000.00, - "created_at": "2025-01-01T12:00:00.000Z", - "updated_at": "2025-01-01T12:00:00.000Z" - } - ], - "pagination": { - "total": 25, - "page": 1, - "limit": 20, - "pages": 2 - } - } -} -``` - -#### 13.4 更新商家状态 - -**Endpoint**: `PUT /admin/merchants/{id}/status` - -**认证**: 需要Bearer Token，需要merchant:manage权限 - -**请求体**: -```json -{ - "status": "string, required, 状态(active/inactive)" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "商家状态更新成功" -} -``` - -### 14. 系统配置接口 - -#### 14.1 获取系统配置 - -**Endpoint**: `GET /admin/system-configs` - -**认证**: 需要Bearer Token，需要system:config权限 - -**查询参数**: -- `group` (可选): 配置组过滤 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "configs": [ - { - "id": "site_name", - "name": "网站名称", - "value": "结伴客", - "type": "string", - "group": "general", - "description": "网站显示的名称", - "created_at": "2025-01-01T12:00:00.000Z", - "updated_at": "2025-01-01T12:00:00.000Z" - }, - { - "id": "site_description", - "name": "网站描述", - "value": "专业的旅行结伴和动物认领平台", - "type": "text", - "group": "general", - "description": "网站的简要描述", - "created_at": "2025-01-01T12:00:00.000Z", - "updated_at": "2025-01-01T12:00:00.000Z" - }, - { - "id": "max_file_size", - "name": "最大文件大小", - "value": "10", - "type": "number", - "group": "upload", - "description": "允许上传的最大文件大小(MB)", - "created_at": "2025-01-01T12:00:00.000Z", - "updated_at": "2025-01-01T12:00:00.000Z" - } - ] - } -} -``` - -#### 14.2 更新系统配置 - -**Endpoint**: `PUT /admin/system-configs/{id}` - -**认证**: 需要Bearer Token，需要system:config权限 - -**请求体**: -```json -{ - "value": "string, required, 配置值" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "配置更新成功" -} -``` - -#### 14.3 批量更新系统配置 - -**Endpoint**: `POST /admin/system-configs/batch-update` - -**认证**: 需要Bearer Token，需要system:config权限 - -**请求体**: -```json -{ - "configs": [ - { - "id": "site_name", - "value": "新网站名称" - }, - { - "id": "site_description", - "value": "新的网站描述" - } - ] -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "批量配置更新成功", - "data": { - "success_count": 2, - "failed_count": 0 - } -} -``` - -### 10. 数据统计接口 - -#### 10.1 获取系统统计数据 - -**Endpoint**: `GET /admin/statistics` - -**认证**: 需要Bearer Token，需要data:view权限 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "user_count": 1000, - "active_user_count": 500, - "new_user_today": 20, - "order_count": 300, - "revenue_today": 5000.00, - "content_count": 200, - "pending_review_count": 15, - "animal_claim_count": 150, - "travel_plan_count": 80, - "flower_order_count": 120, - "merchant_count": 25, - "pending_merchant_approval_count": 8 - } -} -``` - -#### 10.2 获取数据趋势图表 - -**Endpoint**: `GET /admin/statistics/trend` - -**认证**: 需要Bearer Token，需要data:view权限 - -**查询参数**: -- `type` (必选): 数据类型(user/order/revenue/content) -- `days` (可选): 天数，默认7天 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "labels": ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04", "2025-01-05", "2025-01-06", "2025-01-07"], - "datasets": [ - { - "label": "用户增长", - "data": [100, 120, 150, 180, 200, 220, 250], - "borderColor": "rgb(75, 192, 192)" - } - ] - } -} -``` - -#### 10.3 导出数据 - -**Endpoint**: `GET /admin/export/{type}` - -**认证**: 需要Bearer Token，需要data:export权限 - -**查询参数**: -- `start_date` (可选): 开始日期 -- `end_date` (可选): 结束日期 -- `format` (可选): 导出格式(csv/excel)，默认csv - -**响应**: 返回CSV或Excel文件下载 - -### 11. 权限管理接口 - -#### 11.1 获取角色列表 - -**Endpoint**: `GET /admin/roles` - -**认证**: 需要Bearer Token，需要role:manage权限 - -**查询参数**: -- `page` (可选): 页码，默认1 -- `limit` (可选): 每页数量，默认20 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "roles": [ - { - "id": 1, - "name": "super_admin", - "description": "超级管理员", - "permission_count": 20, - "user_count": 3, - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z" - }, - { - "id": 2, - "name": "content_admin", - "description": "内容管理员", - "permission_count": 8, - "user_count": 5, - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 10, - "page": 1, - "limit": 20, - "pages": 1 - } - } -} -``` - -#### 11.2 创建角色 - -**Endpoint**: `POST /admin/roles` - -**认证**: 需要Bearer Token，需要role:manage权限 - -**请求体**: -```json -{ - "name": "string, required, 角色名称", - "description": "string, required, 角色描述", - "permissions": ["string, required, 权限列表"] -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "角色创建成功", - "data": { - "role": { - "id": 3, - "name": "data_admin", - "description": "数据管理员", - "permissions": ["data:view", "data:export"], - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -#### 11.3 更新角色权限 - -**Endpoint**: `PUT /admin/roles/{id}` - -**认证**: 需要Bearer Token，需要role:manage权限 - -**请求体**: -```json -{ - "description": "string, optional, 角色描述", - "permissions": ["string, required, 权限列表"] -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "角色更新成功" -} -``` - -#### 11.4 删除角色 - -**Endpoint**: `DELETE /admin/roles/{id}` - -**认证**: 需要Bearer Token，需要role:manage权限 - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "角色删除成功" -} -``` - -#### 11.5 获取权限列表 - -**Endpoint**: `GET /admin/permissions` - -**认证**: 需要Bearer Token，需要role:manage权限 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "permissions": [ - { - "id": "user:view", - "name": "查看用户", - "description": "允许查看用户列表和详情", - "category": "用户管理" - }, - { - "id": "user:manage", - "name": "管理用户", - "description": "允许修改用户状态和信息", - "category": "用户管理" - }, - { - "id": "content:review", - "name": "审核内容", - "description": "允许审核用户发布的内容", - "category": "内容管理" - }, - { - "id": "content:publish", - "name": "发布内容", - "description": "允许发布系统公告和内容", - "category": "内容管理" - }, - { - "id": "data:view", - "name": "查看数据", - "description": "允许查看系统统计数据", - "category": "数据统计" - }, - { - "id": "data:export", - "name": "导出数据", - "description": "允许导出系统数据", - "category": "数据统计" - }, - { - "id": "role:manage", - "name": "管理角色", - "description": "允许管理角色和权限", - "category": "权限管理" - }, - { - "id": "merchant:approve", - "name": "审核商家", - "description": "允许审核商家入驻申请", - "category": "商家管理" - }, - { - "id": "system:config", - "name": "系统配置", - "description": "允许修改系统配置参数", - "category": "系统管理" - } - ] - } -} -``` - -#### 11.6 分配用户角色 - -**Endpoint**: `POST /admin/users/{userId}/roles` - -**认证**: 需要Bearer Token，需要role:manage权限 - -**请求体**: -```json -{ - "roleIds": ["number, required, 角色ID列表"] -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "角色分配成功" -} -``` - -### 12. 操作日志接口 - -#### 12.1 获取操作日志列表 - -**Endpoint**: `GET /admin/operation-logs` - -**认证**: 需要Bearer Token，需要audit:view权限 - -**查询参数**: -- `page` (可选): 页码，默认1 -- `limit` (可选): 每页数量，默认20 -- `admin_id` (可选): 管理员ID过滤 -- `module` (可选): 操作模块过滤 -- `operation` (可选): 操作类型过滤 -- `target_type` (可选): 目标对象类型过滤 -- `status` (可选): 操作状态过滤(success/failed) -- `start_date` (可选): 开始日期 -- `end_date` (可选): 结束日期 -- `keyword` (可选): 关键词搜索(管理员姓名/操作描述) - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "logs": [ - { - "id": 1, - "admin_id": 1, - "admin_name": "管理员A", - "module": "用户管理", - "operation": "user:update", - "operation_name": "更新用户", - "target_id": "2", - "target_type": "user", - "target_name": "用户B", - "request_method": "PUT", - "request_url": "/admin/users/2", - "request_params": "{\"status\":\"inactive\"}", - "ip_address": "192.168.1.100", - "user_agent": "Mozilla/5.0...", - "status": "success", - "execution_time": 150, - "created_at": "2025-01-01T12:00:00.000Z" - }, - { - "id": 2, - "admin_id": 2, - "admin_name": "管理员B", - "module": "内容审核", - "operation": "content:review", - "operation_name": "审核内容", - "target_id": "5", - "target_type": "content", - "target_name": "测试文章", - "request_method": "PUT", - "request_url": "/admin/contents/5/review", - "request_params": "{\"status\":\"approved\",\"review_comment\":\"内容符合规范\"}", - "ip_address": "192.168.1.101", - "user_agent": "Mozilla/5.0...", - "status": "success", - "execution_time": 200, - "created_at": "2025-01-01T12:30:00.000Z" - } - ], - "pagination": { - "total": 1000, - "page": 1, - "limit": 20, - "pages": 50 - } - } -} -``` - -#### 12.2 获取操作日志详情 - -**Endpoint**: `GET /admin/operation-logs/{id}` - -**认证**: 需要Bearer Token，需要audit:view权限 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "log": { - "id": 1, - "admin_id": 1, - "admin_name": "管理员A", - "module": "用户管理", - "operation": "user:update", - "operation_name": "更新用户", - "target_id": "2", - "target_type": "user", - "target_name": "用户B", - "request_method": "PUT", - "request_url": "/admin/users/2", - "request_params": { - "status": "inactive" - }, - "request_headers": { - "authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", - "user-agent": "Mozilla/5.0...", - "accept": "application/json" - }, - "ip_address": "192.168.1.100", - "user_agent": "Mozilla/5.0...", - "status": "success", - "error_message": null, - "execution_time": 150, - "created_at": "2025-01-01T12:00:00.000Z" - } - } -} -``` - -#### 12.3 导出操作日志 - -**Endpoint**: `GET /admin/operation-logs/export` - -**认证**: 需要Bearer Token，需要audit:export权限 - -**查询参数**: -- `start_date` (可选): 开始日期 -- `end_date` (可选): 结束日期 -- `module` (可选): 操作模块过滤 -- `operation` (可选): 操作类型过滤 -- `status` (可选): 操作状态过滤 -- `format` (可选): 导出格式(csv/excel)，默认csv - -**响应**: 返回CSV或Excel文件下载 - -#### 12.4 获取操作统计 - -**Endpoint**: `GET /admin/operation-logs/statistics` - -**认证**: 需要Bearer Token，需要audit:view权限 - -**查询参数**: -- `start_date` (可选): 开始日期 -- `end_date` (可选): 结束日期 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "total_operations": 1250, - "success_count": 1200, - "failed_count": 50, - "avg_execution_time": 180, - "top_modules": [ - {"module": "用户管理", "count": 450, "percentage": 36.0}, - {"module": "内容审核", "count": 300, "percentage": 24.0}, - {"module": "数据统计", "count": 200, "percentage": 16.0}, - {"module": "系统配置", "count": 150, "percentage": 12.0}, - {"module": "权限管理", "count": 100, "percentage": 8.0}, - {"module": "其他", "count": 50, "percentage": 4.0} - ], - "top_operations": [ - {"operation": "user:update", "count": 200, "percentage": 16.0}, - {"operation": "content:review", "count": 180, "percentage": 14.4}, - {"operation": "data:view", "count": 150, "percentage": 12.0}, - {"operation": "user:create", "count": 120, "percentage": 9.6}, - {"operation": "system:config", "count": 100, "percentage": 8.0} - ], - "top_admins": [ - {"admin_id": 1, "admin_name": "管理员A", "count": 500, "percentage": 40.0}, - {"admin_id": 2, "admin_name": "管理员B", "count": 400, "percentage": 32.0}, - {"admin_id": 3, "admin_name": "管理员C", "count": 350, "percentage": 28.0} - ] - } -} -``` - -## 旅行结伴接口 - -### 11. 发布旅行计划 - -**Endpoint**: `POST /travel/plans` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "title": "string, required, 计划标题", - "description": "string, required, 计划描述", - "destination": "string, required, 目的地", - "start_date": "string, required, 开始日期(YYYY-MM-DD)", - "end_date": "string, required, 结束日期(YYYY-MM-DD)", - "max_members": "number, required, 最大参与人数", - "budget": "number, optional, 预算金额", - "tags": "array, optional, 标签数组", - "images": "array, optional, 图片URL数组" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "旅行计划发布成功", - "data": { - "plan": { - "id": 1, - "title": "周末杭州西湖游", - "description": "寻找志同道合的伙伴一起游玩西湖", - "destination": "杭州西湖", - "start_date": "2025-01-15", - "end_date": "2025-01-16", - "max_members": 6, - "current_members": 1, - "budget": 500, - "status": "recruiting", - "tags": ["休闲", "摄影", "美食"], - "images": [], - "creator_id": 1, - "created_at": "2025-01-01T00:00:00.000Z", - "updated_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -### 12. 获取旅行计划列表 - -**Endpoint**: `GET /travel/plans` - -**查询参数**: -- `page` (可选): 页码，默认1 -- `limit` (可选): 每页数量，默认20 -- `destination` (可选): 目的地搜索 -- `start_date` (可选): 开始日期筛选 -- `end_date` (可选): 结束日期筛选 -- `status` (可选): 状态筛选(recruiting/in_progress/completed/cancelled) -- `sort` (可选): 排序方式(created_at/start_date) - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "plans": [ - { - "id": 1, - "title": "周末杭州西湖游", - "destination": "杭州西湖", - "start_date": "2025-01-15", - "end_date": "2025-01-16", - "max_members": 6, - "current_members": 3, - "budget": 500, - "status": "recruiting", - "tags": ["休闲", "摄影", "美食"], - "creator": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "avatar": "" - }, - "created_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 50, - "page": 1, - "limit": 20, - "pages": 3 - } - } -} -``` - -### 13. 加入旅行计划 - -**Endpoint**: `POST /travel/plans/{id}/join` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "message": "string, optional, 加入留言" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "成功加入旅行计划", - "data": { - "membership": { - "id": 1, - "plan_id": 1, - "user_id": 2, - "status": "pending", - "message": "希望能一起游玩", - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 动物认领接口 - -### 14. 获取可认领动物列表 - -**Endpoint**: `GET /animals/adoptable` - -**查询参数**: -- `page` (可选): 页码，默认1 -- `limit` (可选): 每页数量，默认20 -- `type` (可选): 动物类型 -- `breed` (可选): 品种筛选 -- `age_min` (可选): 最小年龄 -- `age_max` (可选): 最大年龄 -- `location` (可选): 地理位置 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "animals": [ - { - "id": 1, - "name": "小白", - "type": "dog", - "breed": "中华田园犬", - "age": 2, - "gender": "male", - "description": "温顺可爱的狗狗，寻找有爱心的主人", - "vaccination_status": "vaccinated", - "sterilization_status": "sterilized", - "location": "北京市朝阳区", - "images": ["https://www.jiebanke.com/animal1.jpg"], - "status": "available", - "shelter": { - "id": 1, - "name": "爱心动物救助站", - "contact": "13800138000" - }, - "created_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 30, - "page": 1, - "limit": 20, - "pages": 2 - } - } -} -``` - -### 15. 申请认领动物 - -**Endpoint**: `POST /animals/{id}/adopt` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "application_reason": "string, required, 申请理由", - "living_environment": "string, required, 居住环境描述", - "experience": "string, optional, 养宠经验", - "contact_info": "string, required, 联系方式" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "认领申请已提交", - "data": { - "application": { - "id": 1, - "animal_id": 1, - "applicant_id": 1, - "status": "pending", - "application_reason": "非常喜欢狗狗，有养宠经验", - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 花卉订购接口 - -### 16. 获取花卉商品列表 - -**Endpoint**: `GET /flowers/products` - -**查询参数**: -- `page` (可选): 页码，默认1 -- `limit` (可选): 每页数量，默认20 -- `category" (可选): 分类筛选 -- "min_price" (可选): 最低价格 -- "max_price" (可选): 最高价格 -- "sort" (可选): 排序方式(price/created_at/sales) - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "products": [ - { - "id": 1, - "name": "玫瑰花束", - "description": "新鲜玫瑰花束，适合送礼", - "category": "鲜花", - "price": 99.00, - "original_price": 129.00, - "stock": 50, - "sales": 120, - "images": ["https://www.jiebanke.com/rose.jpg"], - "merchant": { - "id": 1, - "name": "花语花店", - "rating": 4.8 - }, - "created_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 100, - "page": 1, - "limit": 20, - "pages": 5 - } - } -} -``` - -### 17. 创建花卉订单 - -**Endpoint**: `POST /flowers/orders` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "items": [ - { - "product_id": 1, - "quantity": 2, - "message": "string, optional, 留言卡片内容" - } - ], - "shipping_address": { - "recipient": "string, required, 收货人", - "phone": "string, required, 联系电话", - "address": "string, required, 详细地址", - "postal_code": "string, optional, 邮政编码" - }, - "delivery_date": "string, required, 配送日期(YYYY-MM-DD)", - "delivery_time": "string, required, 配送时间段" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "订单创建成功", - "data": { - "order": { - "id": 1, - "order_number": "F202501010001", - "total_amount": 198.00, - "status": "pending", - "items": [ - { - "product_id": 1, - "product_name": "玫瑰花束", - "quantity": 2, - "price": 99.00, - "subtotal": 198.00 - } - ], - "shipping_address": { - "recipient": "张三", - "phone": "13800138000", - "address": "北京市朝阳区某某街道123号" - }, - "delivery_date": "2025-01-15", - "delivery_time": "14:00-16:00", - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 社交互动接口 - -### 18. 发布动态 - -**Endpoint**: `POST /social/posts` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "content": "string, required, 动态内容", - "images": "array, optional, 图片URL数组", - "visibility": "string, optional, 可见性(public/friends/private)", - "location": "string, optional, 位置信息" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "动态发布成功", - "data": { - "post": { - "id": 1, - "content": "今天去了西湖，风景真美！", - "images": ["https://www.jiebanke.com/westlake.jpg"], - "visibility": "public", - "location": "杭州西湖", - "like_count": 0, - "comment_count": 0, - "author": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "avatar": "" - }, - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -### 19. 点赞动态 - -**Endpoint**: `POST /social/posts/{id}/like` - -**认证**: 需要Bearer Token - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "点赞成功", - "data": { - "like_count": 15 - } -} -``` - -### 20. 评论动态 - -**Endpoint**: `POST /social/posts/{id}/comments` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "content": "string, required, 评论内容", - "parent_id": "number, optional, 父评论ID" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "评论成功", - "data": { - "comment": { - "id": 1, - "content": "照片拍得真漂亮！", - "author": { - "id": 2, - "username": "user2", - "nickname": "用户二", - "avatar": "" - }, - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 错误码说明 - -| 错误码 | 说明 | -|--------|------| -| 200 | 成功 | -| 201 | 创建成功 | -| 400 | 请求参数错误 | -| 401 | 未授权 | -| 403 | 权限不足 | -| 404 | 资源不存在 | -| 500 | 服务器内部错误 | - -**Endpoint**: `PUT /auth/profile` - -**认证**: 需要Bearer Token - -**描述**: 更新用户个人信息 - -**请求体**: -```json -{ - "nickname": "string, optional, 昵称", - "avatar": "string, optional, 头像URL", - "gender": "string, optional, 性别(male/female/unknown)", - "birthday": "string, optional, 生日(YYYY-MM-DD)" -} -``` - -**响应**: 同获取用户信息接口 - -### 6. 修改密码 - -**Endpoint**: `PUT /auth/password` - -**认证**: 需要Bearer Token - -**描述**: 修改用户密码 - -**请求体**: -```json -{ - "currentPassword": "string, required, 当前密码", - "newPassword": "string, required, 新密码(6-20字符)" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "密码修改成功" -} -``` - -### 7. 退出登录 - -**Endpoint**: `POST /auth/logout` - -**认证**: 需要Bearer Token - -**描述**: 用户退出登录，使token失效 - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "退出登录成功" -} -``` - -### 8. 刷新token - -**Endpoint**: `POST /auth/refresh` - -**认证**: 需要Bearer Token - -**描述**: 刷新访问令牌 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." - } -} -``` - -## 用户接口 - -### 1. 获取用户列表 - -**Endpoint**: `GET /users` - -**认证**: 需要Bearer Token (管理员权限) - -**查询参数**: -- `page`: number, optional, 页码 (默认: 1) -- `pageSize`: number, optional, 每页数量 (默认: 20) -- `search`: string, optional, 搜索关键词 -- `status`: string, optional, 状态过滤(active/inactive/banned) - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "users": [ - { - "id": 1, - "username": "user1", - "nickname": "用户1", - "email": "user1@jiebanke.com", - "phone": "13800138001", - "status": "active", - "level": 2, - "created_at": "2025-01-01极速版T00:00:00.000Z" - } - ], - "pagination": { - "total": 100, - "page": 1, - "pageSize": 20, - "totalPages": 5 - } - } -} -``` - -### 2. 获取用户详情 - -**Endpoint**: `GET /users/:id` - -**认证**: 需要Bearer Token - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "user": { - "id": 1, - "username": "testuser", - "nickname": "测试用户", - "email": "test@example.com", - "phone": "13800138000", - "avatar": "https://example.com/avatar.jpg", - "gender": "male", - "points": 1000, - "level": 3, - "status": "active", - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 旅行接口 - -### 1. 创建旅行计划 - -**Endpoint**: `POST /travel/plans` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "destination": "string, required, 目的地", - "start_date": "string, required, 开始日期(YYYY-MM-DD)", - "end_date": "string, required, 结束日期(YYYY-MM-DD)", - "budget": "number, required, 预算", - "interests": "string, optional, 兴趣偏好", - "visibility": "string, optional, 可见范围(public/friends/private)" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "旅行计划创建成功", - "data": { - "plan": { - "id": 1, - "title": "西藏自驾游", - "description": "寻找志同道合的旅友一起探索西藏", - "destination": "西藏", - "start_date": "2025-07-01", - "end_date": "2025-07-15", - "budget": 5000, - "max_members": 4, - "current_members": 1, - "status": "recruiting", - "tags": ["自驾", "摄影", "探险"], - "creator_id": 1, - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -### 2. 获取旅行计划列表 - -**Endpoint**: `GET /travel/plans` - -**查询参数**: -- `page`: number, optional, 页码 -- `pageSize`: number, optional, 每页数量 -- `destination`: string, optional, 目的地搜索 -- `start_date`: string, optional, 开始日期之后 -- `end_date`: string, optional, 结束日期之前 -- `status`: string, optional, 状态(recruiting/in_progress/completed/cancelled) -- `tags`: string, optional, 标签过滤(多个用逗号分隔) - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "plans": [ - { - "id": 1, - "destination": "西藏", - "start_date": "2025-07-01", - "end_date": "2025-07-15", - "budget": 5000.00, - "interests": "自驾,摄影,探险", - "visibility": "public", - "creator": { - "id": 1, - "nickname": "旅行达人", - "avatar": "https://example.com/avatar.jpg" - }, - "created_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 50, - "page": 1, - "pageSize": 20, - "totalPages": 3 - } - } -} -``` - -### 3. 匹配旅行伙伴 - -**Endpoint**: `GET /travel/matches` - -**认证**: 需要Bearer Token - -**查询参数**: -- `plan_id`: number, required, 旅行计划ID -- `page`: number, optional, 页码 -- `pageSize`: number, optional, 每页数量 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "list": [ - { - "id": 2, - "destination": "西藏", - "start_date": "2025-07-02", - "end_date": "2025-07-08", - "budget": 4500.00, - "interests": "徒步,美食", - "match_score": 0.85, - "user": { - "id": 2, - "nickname": "旅行伙伴", - "avatar": "https://www.jiebanke.com/avatar2.jpg" - } - } - ], - "pagination": { - "page": 1, - "size": 10, - "total": 1 - } - } -} -``` - -## 动物认领接口 - -### 1. 发布动物认领 - -**Endpoint**: `POST /animals` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "name": "string, required, 动物名称", - "species": "string, required, 物种", - "breed": "string, optional, 品种", - "age": "number, optional, 年龄", - "gender": "string, optional, 性别(male/female/unknown)", - "description": "string, required, 描述", - "location": "string, required, 位置", - "images": "array, optional, 图片URL数组", - "vaccination_status": "string, optional, 疫苗接种情况", - "sterilization_status": "string, optional, 绝育情况" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "动物认领发布成功", - "data": { - "animal": { - "id": 1, - "name": "小白", - "species": "猫", - "breed": "中华田园猫", - "age": 2, - "gender": "male", - "description": "非常温顺的猫咪，寻找有爱心的主人", - "location": "北京市朝阳区", - "status": "available", - "images": ["https://www.jiebanke.com/cat1.jpg"], - "creator_id": 1, - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 商家服务接口 - -### 1. 商家注册 - -**Endpoint**: `POST /merchants/register` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "merchant_type": "string, required, 商家类型(flower_shop/activity_organizer/farm_owner)", - "business_name": "string, required, 商家名称", - "business_license": "string, optional, 营业执照URL", - "contact_person": "string, required, 联系人", - "contact_phone": "string, required, 联系电话", - "address": "string, optional, 地址", - "description": "string, optional, 商家介绍" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "商家注册申请已提交", - "data": { - "merchant": { - "id": 1, - "user_id": 1, - "merchant_type": "farm_owner", - "business_name": "XX农场", - "business_license": "https://example.com/license.jpg", - "contact_person": "张三", - "contact_phone": "13800138000", - "address": "北京市朝阳区XX路XX号", - "description": "专业养殖羊驼的农场", - "status": "pending", - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -### 2. 发布商品/服务 - -**Endpoint**: `POST /merchants/products` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "name": "string, required, 商品名称", - "description": "string, required, 商品描述", - "price": "number, required, 价格", - "image_url": "string, optional, 图片URL", - "category": "string, required, 商品类别", - "status": "string, optional, 状态(available/unavailable)" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "商品发布成功", - "data": { - "product": { - "id": 1, - "merchant_id": 1, - "name": "羊驼认领体验", - "description": "提供一个月的羊驼认领体验服务", - "price": 1000.00, - "image_url": "https://www.jiebanke.com/product.jpg", - "category": "animal_claim", - "status": "available", - "created_at": "202极速版5-01-01T00:00:00.000Z" - } - } -} -``` - -### 3. 获取商家订单 - -**Endpoint**: `GET /merchants/orders` - -**认证**: 需要Bearer Token - -**查询参数**: -- `page`: number, optional, 页码 -- `pageSize`: number, optional, 每页数量 -- `status`: string, optional, 订单状态 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "orders": [ - { - "id": 1, - "user_id": 2, - "order_number": "ORD202501010001", - "total_amount": 1000.00, - "status": "paid", - "ordered_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 50, - "page": 1, - "pageSize": 20, - "totalPages": 3 - } - } -} -``` - -## 鲜花订购接口 - -### 1. 创建鲜花订单 - -**Endpoint**: `POST /flowers/orders` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "product_id": "number, required, 商品ID", - "quantity": "number, required, 数量", - "recipient_name": "string, required, 收花人姓名", - "recipient_phone": "string, required, 收花人电话", - "delivery_address": "string, required, 配送地址", - "delivery_date": "string, required, 配送日期(YYYY-MM-DD)", - "delivery_time": "string, required, 配送时间段", - "message": "string, optional, 祝福语", - "special_instructions": "string, optional, 特殊说明" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "订单创建成功", - "data": { - "order": { - "极速版id": 1, - "order_number": "F202501010001", - "product_id": 1, - "quantity": 1, - "total_amount": 199.00, - "status": "pending", - "recipient_name": "张三", - "recipient_phone": "13800138000", - "delivery_address": "北京市朝阳区xxx路xxx号", - "delivery_date": "2025-01-01", - "delivery_time": "09:00-12:00", - "created_at": "2025-01-01T00:00:00.000Z" - } - } -} -``` - -## 推广奖励接口 - -### 1. 获取推广链接 - -**Endpoint**: `GET /promotion/link` - -**认证**: 需要Bearer Token - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "promotion_link": "https://www.jiebanke.com/promotion?ref=user123", -"qr_code": "https://www.jiebanke.com/qrcode.png" - } -} -``` - -### 2. 获取推广数据 - -**Endpoint**: `GET /promotion/stats` - -**认证**: 需要Bearer Token - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "total_referrals": 50, - "successful_registrations": 25, - "total_rewards": 500.00, - "available_rewards": 300.00, - "withdrawn_rewards": 200.00 - } -} -``` - -### 3. 申请提现 - -**Endpoint**: `POST /promotion/withdraw` - -**认证**: 需要Bearer Token - -**请求体**: -```json -{ - "amount": "number, required, 提现金额", - "payment_method": "string, required, 支付方式(wechat/alipay)" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 200, - "message": "提现申请已提交", - "data": { - "withdrawal_id": "WD202501010001", - "status": "processing" - } -} -``` - -## 系统接口 - -### 1. 健康检查 - -**Endpoint**: `GET /health` - -**描述**: 检查服务健康状态 - -**响应**: -```json -{ - "status": "OK", - "timestamp": "2025-01-01T00:00:00.000Z", - "uptime": 12345.67, - "environment": "development", - "services": { - "database": "connected", - "redis": "disconnected", - "rabbitmq": "disconnected" - } -} -``` - -## 官网接口 - -### 1. 提交商家入驻申请 - -**Endpoint**: `POST /website/merchant/apply` - -**请求体**: -```json -{ - "business_name": "string, required, 商家名称", - "contact_person": "string, required, 联系人", - "contact_phone": "string, required, 联系电话", - "email": "string, optional, 邮箱", - "description": "string, optional, 商家描述" -} -``` - -**响应**: -```json -{ - "success": true, - "code": 201, - "message": "入驻申请已提交", - "data": { - "application_id": 1, - "status": "pending" - } -} -``` - -### 2. 获取成功案例列表 - -**Endpoint**: `GET /website/cases` - -**查询参数**: -- `page`: number, optional, 页码 -- `pageSize`: number, optional, 每页数量 - -**响应**: -```json -{ - "success": true, - "code": 200, - "data": { - "cases": [ - { - "id": 1, - "title": "XX农场成功入驻案例", - "description": "XX农场通过平台实现了数字化转型", - "image_url": "https://www.jiebanke.com/case1.jpg", - "created_at": "2025-01-01T00:00:00.000Z" - } - ], - "pagination": { - "total": 50, - "page": 1, - "pageSize": 20, - "totalPages": 3 - } - } -} -``` - -## 错误码说明 - -| 错误码 | 说明 | 处理建议 | -|--------|------|----------| -| 200 | 成功 | 操作成功 | -| 201 | 创建成功 | 资源创建成功 | -| 400 | 请求错误 | 检查请求参数 | -| 401 | 未授权 | 需要登录认证 | -| 403 | 禁止访问 | 权限不足 | -| 404 | 资源不存在 | 检查资源ID | -| 409 | 资源冲突 | 资源已存在 | -| 429 | 请求过多 | 降低请求频率 | -| 500 | 服务器错误 | 联系管理员 | - -## 版本历史 - -| 版本 | 日期 | 说明 | -|------|------|------| -| v1.0 | 2025-01-01 | 初始版本发布 | -| v1.1 | 2025-02-01 | 新增微信登录接口 | -| v1.2 | 2025-03-01 | 优化错误处理机制 | - -## 注意事项 - -1. 所有时间格式均为 ISO 8601 格式 (YYYY-MM-DDTHH:mm:ss.sssZ) -2. 金额单位为元，保留两位小数 -3. 图片URL需要支持HTTPS -4. 敏感操作需要二次验证 -5. API调用频率限制为每分钟100次 \ No newline at end of file diff --git a/docs/architecture-java.md b/docs/architecture-java.md deleted file mode 100644 index 8421a85..0000000 --- a/docs/architecture-java.md +++ /dev/null @@ -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 ` -- **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年* 📅 \ No newline at end of file diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 26fbc12..0000000 --- a/docs/architecture.md +++ /dev/null @@ -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 ` -- **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年* 📅 \ No newline at end of file diff --git a/docs/database-design-java.md b/docs/database-design-java.md deleted file mode 100644 index a71361b..0000000 --- a/docs/database-design-java.md +++ /dev/null @@ -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年* 📅 \ No newline at end of file diff --git a/docs/database-design.md b/docs/database-design.md deleted file mode 100644 index 1ba8138..0000000 --- a/docs/database-design.md +++ /dev/null @@ -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加密连接 \ No newline at end of file diff --git a/docs/detailed_design.md b/docs/detailed_design.md deleted file mode 100644 index 4d22cea..0000000 --- a/docs/detailed_design.md +++ /dev/null @@ -1,1004 +0,0 @@ -# 结伴客系统详细设计文档 - -## 2.3 数据库配置 - -### 2.3.1 测试环境 -- **主机**: 192.168.0.240 (MySQL主机地址) -- **端口**: 3306 (MySQL端口) -- **用户名**: root -- **密码**: aiot$Aiot123 -- **数据库**: jiebandata - -### 2.3.2 生产环境 -- **主机**: 129.211.213.226 -- **端口**: 9527 -- **用户名**: root -- **密码**: aiotAiot123! -- **数据库**: jiebandata - -**注意**: 管理员默认账号为 admin，默认密码为 admin123 -## 1. 数据库设计 - -### 1.1 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 - - USERS { - int id PK - string openid - string nickname - string avatar - string gender - date birthday - string phone - string email - datetime created_at - datetime 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 - } - - TRAVEL_MATCHES { - int id PK - int plan_id FK - int matched_plan_id FK - decimal match_score - datetime created_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 - } - - ANIMAL_CLAIMS { - int id PK - int user_id FK - int animal_id FK - decimal price_paid - string agreement_url - string status - datetime claimed_at - datetime ended_at - } - - ANIMAL_UPDATES { - int id PK - int animal_id FK - string update_type - string content - string media_url - datetime created_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 - } - - 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 - } - - ORDER_ITEMS { - int id PK - int order_id FK - int product_id FK - int quantity - decimal unit_price - } - - PAYMENTS { - int id PK - int order_id FK - string payment_method - string transaction_id - decimal amount - string status - datetime paid_at - } - - MESSAGES { - int id PK - int sender_id FK - int receiver_id FK - string content - string status - datetime sent_at - } - - REVIEWS { - int id PK - int user_id FK - int merchant_id FK - int order_id FK - int rating - string comment - datetime created_at - } - - ACTIVITIES { - int id PK - int merchant_id FK - string title - string description - string activity_type - datetime start_time - datetime end_time - string location - decimal fee - int max_participants - string status - datetime created_at - datetime updated_at - } - - ACTIVITY_REGISTRATIONS { - int id PK - int activity_id FK - int user_id FK - string status - datetime registered_at - } -``` - -### 1.2 核心表结构设计 - -#### 用户表 (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 | 邮箱地址 | -| created_at | DATETIME | NOT NULL | 创建时间 | -| updated_at | DATETIME | NOT NULL | 更新时间 | - -### 管理员相关表 - -#### ROLES 表（角色表） - -| 字段名 | 类型 | 约束 | 描述 | -|--------|------|------|------| -| id | INT | PRIMARY KEY, AUTO_INCREMENT | 角色ID | -| name | VARCHAR(50) | UNIQUE, NOT NULL | 角色名称 | -| description | TEXT | | 角色描述 | -| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | -| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 | - -**数据示例**: -- super_admin: 超级管理员，拥有系统所有权限 -- admin: 普通管理员，拥有部分管理权限 -- content_manager: 内容管理员，负责内容审核和管理 - -#### PERMISSIONS 表（权限表） - -| 字段名 | 类型 | 约束 | 描述 | -|--------|------|------|------| -| id | INT | PRIMARY KEY, AUTO_INCREMENT | 权限ID | -| name | VARCHAR(100) | UNIQUE, NOT NULL | 权限名称 | -| description | TEXT | | 权限描述 | -| module | VARCHAR(50) | NOT NULL | 所属模块 | -| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | -| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 | - -**权限列表**: -- user:manage - 用户管理权限 -- role:manage - 角色管理权限 -- permission:manage - 权限管理权限 -- content:review - 内容审核权限 -- content:publish - 内容发布权限 -- data:view - 数据查看权限 -- data:export - 数据导出权限 -- system:config - 系统配置权限 - -#### ROLE_PERMISSIONS 表（角色权限关联表） - -| 字段名 | 类型 | 约束 | 描述 | -|--------|------|------|------| -| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 关联ID | -| role_id | INT | FOREIGN KEY REFERENCES roles(id) | 角色ID | -| permission_id | INT | FOREIGN KEY REFERENCES permissions(id) | 权限ID | -| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | - -#### USER_ROLES 表（用户角色关联表） - -| 字段名 | 类型 | 约束 | 描述 | -|--------|------|------|------| -| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 关联ID | -| user_id | BIGINT | FOREIGN KEY REFERENCES users(id) | 用户ID | -| role_id | INT | FOREIGN KEY REFERENCES roles(id) | 角色ID | -| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 | - -### 权限分配关系 - -```mermaid -erDiagram - USERS ||--o{ USER_ROLES : has - ROLES ||--o{ USER_ROLES : assigned_to - ROLES ||--o{ ROLE_PERMISSIONS : has - PERMISSIONS ||--o{ ROLE_PERMISSIONS : granted_to - - USERS { - bigint id - varchar username - varchar email - enum status - timestamp created_at - } - - ROLES { - int id - varchar name - text description - timestamp created_at - } - - PERMISSIONS { - int id - varchar name - varchar module - text description - timestamp created_at - } - - USER_ROLES { - bigint id - bigint user_id - int role_id - timestamp created_at - } - - ROLE_PERMISSIONS { - bigint id - int role_id - int permission_id - timestamp created_at - } -``` - -### 管理员功能说明 - -1. **用户管理模块**: 查看用户列表、管理用户状态、用户数据分析 -2. **内容管理模块**: 内容审核、内容发布管理、违规内容处理 -3. **数据统计模块**: 系统数据查看、数据导出、运营报表生成 -4. **权限管理模块**: 角色管理、权限分配、用户权限设置 - -### 安全设计 - -- 管理员登录采用JWT令牌认证 -- 接口权限基于RBAC模型控制 -- 敏感操作记录审计日志 -- 密码采用bcrypt加密存储 - -#### 商家表 (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 | 更新时间 | - -#### 旅行计划表 (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 | 更新时间 | - -#### 动物表 (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) | | 农场位置 | -| price | DECIMAL(10,2) | NOT NULL | 认领价格 | -| status | ENUM('available', 'claimed', 'unavailable') | NOT NULL | 状态 | -| created_at | DATETIME | NOT NULL | 创建时间 | -| updated_at | DATETIME | NOT NULL | 更新时间 | - -#### 动物认领表 (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 | | 结束时间 | - -#### 管理员操作日志表 (admin_operation_logs) -| 字段名 | 类型 | 约束 | 描述 | -|--------|------|------|------| -| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 日志ID | -| admin_id | BIGINT | FOREIGN KEY REFERENCES users(id), NOT NULL | 管理员ID | -| admin_name | VARCHAR(50) | NOT NULL | 管理员姓名 | -| module | VARCHAR(50) | NOT NULL | 操作模块 | -| operation | VARCHAR(100) | NOT NULL | 操作类型 | -| target_id | VARCHAR(100) | | 目标对象ID | -| target_type | VARCHAR(50) | | 目标对象类型 | -| request_method | VARCHAR(10) | | 请求方法 | -| request_url | VARCHAR(500) | | 请求URL | -| request_params | TEXT | | 请求参数 | -| ip_address | VARCHAR(45) | | IP地址 | -| user_agent | VARCHAR(500) | | 用户代理 | -| status | ENUM('success', 'failed') | NOT NULL | 操作状态 | -| error_message | TEXT | | 错误信息 | -| execution_time | INT | | 执行时间(ms) | -| created_at | DATETIME | NOT NULL | 创建时间 | - -**操作类型示例**: -- user:create - 创建用户 -- user:update - 更新用户 -- user:delete - 删除用户 -- role:create - 创建角色 -- role:update - 更新角色 -- role:delete - 删除角色 -- permission:assign - 分配权限 -- content:review - 内容审核 -- content:publish - 内容发布 -- data:export - 数据导出 -- system:config - 系统配置 - -**目标对象类型示例**: -- user - 用户 -- role - 角色 -- permission - 权限 -- content - 内容 -- merchant - 商家 -- animal - 动物 -- travel_plan - 旅行计划 -- order - 订单 - -## 2. API设计 - -### 2.1 用户服务API - -#### 用户登录 -- **URL**: `POST /api/v1/users/login` -- **请求参数**: - ```json - { - "code": "微信登录凭证" - } - ``` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "token": "用户token", - "user": { - "id": 1, - "openid": "openid", - "nickname": "用户昵称", - "avatar": "头像URL" - } - } - } - ``` - -#### 获取用户信息 -- **URL**: `GET /api/v1/users/profile` -- **请求头**: `Authorization: Bearer {token}` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "id": 1, - "openid": "openid", - "nickname": "用户昵称", - "avatar": "头像URL", - "gender": "male", - "birthday": "1990-01-01", - "phone": "13800138000", - "email": "user@jiebanke.com" - } - } - ``` - -#### 更新用户信息 -- **URL**: `PUT /api/v1/users/profile` -- **请求头**: `Authorization: Bearer {token}` -- **请求参数**: - ```json - { - "nickname": "新昵称", - "gender": "female", - "birthday": "1995-01-01", - "phone": "13900139000", - "email": "new@jiebanke.com" - } - ``` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": {} - } - ``` - -### 2.2 旅行服务API - -#### 创建旅行计划 -- **URL**: `POST /api/v1/travels/plans` -- **请求头**: `Authorization: Bearer {token}` -- **请求参数**: - ```json - { - "destination": "目的地", - "start_date": "2023-10-01", - "end_date": "2023-10-07", - "budget": 5000.00, - "interests": "徒步,摄影", - "visibility": "public" - } - ``` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "id": 1, - "user_id": 1, - "destination": "目的地", - "start_date": "2023-10-01", - "end_date": "2023-10-07", - "budget": 5000.00, - "interests": "徒步,摄影", - "visibility": "public", - "created_at": "2023-09-01T12:00:00Z" - } - } - ``` - -#### 获取旅行计划列表 -- **URL**: `GET /api/v1/travels/plans` -- **请求头**: `Authorization: Bearer {token}` -- **查询参数**: `page=1&size=10&visibility=public` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "list": [ - { - "id": 1, - "user_id": 1, - "destination": "目的地", - "start_date": "2023-10-01", - "end_date": "2023-10-07", - "budget": 5000.00, - "interests": "徒步,摄影", - "visibility": "public", - "created_at": "2023-09-01T12:00:00Z" - } - ], - "pagination": { - "page": 1, - "size": 10, - "total": 1 - } - } - } - ``` - -#### 匹配旅行伙伴 -- **URL**: `GET /api/v1/travels/matches` -- **请求头**: `Authorization: Bearer {token}` -- **查询参数**: `plan_id=1&page=1&size=10` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "list": [ - { - "id": 2, - "user_id": 2, - "destination": "目的地", - "start_date": "2023-10-02", - "end_date": "2023-10-08", - "budget": 4500.00, - "interests": "徒步,美食", - "match_score": 0.85 - } - ], - "pagination": { - "page": 1, - "size": 10, - "total": 1 - } - } - } - ``` - -### 2.3 动物认领服务API - -#### 获取可认领动物列表 -- **URL**: `GET /api/v1/animals` -- **请求头**: `Authorization: Bearer {token}` -- **查询参数**: `page=1&size=10&species=羊驼` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "list": [ - { - "id": 1, - "merchant_id": 1, - "name": "小羊驼", - "species": "羊驼", - "breed": "苏利羊驼", - "birth_date": "2020-01-01", - "personality": "温顺可爱", - "farm_location": "XX农场", - "price": 1000.00, - "status": "available" - } - ], - "pagination": { - "page": 1, - "size": 10, - "total": 1 - } - } - } - ``` - -#### 认领动物 -- **URL**: `POST /api/v1/animals/{id}/claim` -- **请求头**: `Authorization: Bearer {token}` -- **请求参数**: - ```json - { - "price_paid": 1000.00 - } - ``` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "id": 1, - "user_id": 1, - "animal_id": 1, - "price_paid": 1000.00, - "agreement_url": "https://www.jiebanke.com/agreement.pdf", - "status": "active", - "claimed_at": "2023-09-01T12:00:00Z" - } - } - ``` - -#### 获取认领记录 -- **URL**: `GET /api/v1/animals/claims` -- **请求头**: `Authorization: Bearer {token}` -- **查询参数**: `page=1&size=10&status=active` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "list": [ - { - "id": 1, - "user_id": 1, - "animal_id": 1, - "animal_name": "小羊驼", - "price_paid": 1000.00, - "status": "active", - "claimed_at": "2023-09-01T12:00:00Z" - } - ], - "pagination": { - "page": 1, - "size": 10, - "total": 1 - } - } - } - ``` - -### 2.4 商家服务API - -#### 商家注册 -- **URL**: `POST /api/v1/merchants/register` -- **请求头**: `Authorization: Bearer {token}` -- **请求参数**: - ```json - { - "merchant_type": "farm_owner", - "business_name": "XX农场", - "business_license": "https://www.jiebanke.com/license.jpg", - "contact_person": "张三", - "contact_phone": "13800138000", - "address": "北京市朝阳区XX路XX号", - "description": "专业养殖羊驼的农场" - } - ``` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "id": 1, - "user_id": 1, - "merchant_type": "farm_owner", - "business_name": "XX农场", - "business_license": "https://example.com/license.jpg", - "contact_person": "张三", - "contact_phone": "13800138000", - "address": "北京市朝阳区XX路XX号", - "description": "专业养殖羊驼的农场", - "status": "pending", - "created_at": "2023-09-01T12:00:00Z" - } - } - ``` - -#### 发布商品/服务 -- **URL**: `POST /api/v1/merchants/products` -- **请求头**: `Authorization: Bearer {token}` -- **请求参数**: - ```json - { - "name": "羊驼认领体验", - "description": "提供一个月的羊驼认领体验服务", - "price": 1000.00, - "image_url": "https://www.jiebanke.com/product.jpg", - "category": "animal_claim", - "status": "available" - } - ``` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "id": 1, - "merchant_id": 1, - "name": "羊驼认领体验", - "description": "提供一个月的羊驼认领体验服务", - "price": 1000.00, - "image_url": "https://www.jiebanke.com/product.jpg", - "category": "animal_claim", - "status": "available", - "created_at": "2023-09-01T12:00:00Z" - } - } - ``` - -#### 获取商家订单 -- **URL**: `GET /api/v1/merchants/orders` -- **请求头**: `Authorization: Bearer {token}` -- **查询参数**: `page=1&size=10&status=paid` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "list": [ - { - "id": 1, - "user_id": 2, - "order_number": "ORD202309010001", - "total_amount": 1000.00, - "status": "paid", - "ordered_at": "2023-09-01T12:00:00Z" - } - ], - "pagination": { - "page": 1, - "size": 10, - "total": 1 - } - } - } - ``` - -### 2.5 官网系统API - -#### 提交商家入驻申请 -- **URL**: `POST /api/v1/website/merchant/apply` -- **请求参数**: - ```json - { - "business_name": "XX农场", - "contact_person": "张三", - "contact_phone": "13800138000", - "email": "zhangsan@jiebanke.com", - "description": "专业养殖羊驼的农场" - } - ``` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "id": 1, - "business_name": "XX农场", - "contact_person": "张三", - "contact_phone": "13800138000", - "email": "zhangsan@example.com", - "description": "专业养殖羊驼的农场", - "status": "pending", - "created_at": "2023-09-01T12:00:00Z" - } - } - ``` - -#### 获取成功案例列表 -- **URL**: `GET /api/v1/website/cases` -- **查询参数**: `page=1&size=10` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "list": [ - { - "id": 1, - "title": "XX农场成功入驻案例", - "description": "XX农场通过平台实现了数字化转型", - "image_url": "https://www.jiebanke.com/case1.jpg", - "created_at": "2023-09-01T12:00:00Z" - } - ], - "pagination": { - "page": 1, - "size": 10, - "total": 1 - } - } - } - ``` - "image_url": "https://example.com/product.jpg", - "category": "animal_claim", - "status": "available", - "created_at": "2023-09-01T12:00:00Z" - } - } - ``` - -#### 获取商家订单 -- **URL**: `GET /api/v1/merchants/orders` -- **请求头**: `Authorization: Bearer {token}` -- **查询参数**: `page=1&size=10&status=paid` -- **响应**: - ```json - { - "code": 0, - "message": "success", - "data": { - "list": [ - { - "id": 1, - "user_id": 2, - "order_number": "ORD202309010001", - "total_amount": 1000.00, - "status": "paid", - "ordered_at": "2023-09-01T12:00:00Z" - } - ], - "pagination": { - "page": 1, - "size": 10, - "total": 1 - } - } - } - ``` - -## 3. 核心业务逻辑设计 - -### 3.1 旅行结伴流程 - -```mermaid -sequenceDiagram - participant U as 用户 - participant TP as 旅行计划服务 - participant TM as 旅行匹配服务 - participant N as 通知服务 - - U->>TP: 创建旅行计划 - TP->>TP: 保存计划 - TP-->>U: 返回计划详情 - - U->>TM: 请求匹配旅行伙伴 - TM->>TM: 根据条件匹配 - TM-->>U: 返回匹配结果 - - U->>U: 选择合适的伙伴 - U->>N: 发送结伴邀请 - N->>N: 发送通知给被邀请用户 - - Note over U,N: 被邀请用户接受邀请后， - Note over U,N: 系统创建结伴关系 -``` - -### 3.2 动物认领流程 - -```mermaid -sequenceDiagram - participant U as 用户 - participant A as 动物服务 - participant M as 商家服务 - participant P as 支付服务 - participant N as 通知服务 - - U->>A: 浏览可认领动物 - A-->>U: 返回动物列表 - - U->>A: 选择动物并认领 - A->>P: 创建支付订单 - P-->>U: 返回支付信息 - - U->>P: 完成支付 - P->>P: 验证支付结果 - P->>A: 通知支付成功 - - A->>A: 更新动物状态为已认领 - A->>M: 通知商家有新认领 - A->>N: 发送认领成功通知给用户 - - M->>M: 更新商家统计信息 - N->>N: 发送通知 -``` - -### 3.3 商家服务流程 - -```mermaid -sequenceDiagram - participant U as 用户 - participant M as 商家服务 - participant P as 商品服务 - participant O as 订单服务 - participant Pay as 支付服务 - participant N as 通知服务 - - U->>M: 申请成为商家 - M->>M: 审核商家资质 - M-->>U: 返回审核结果 - - alt 审核通过 - U->>P: 发布商品/服务 - P->>P: 保存商品信息 - P-->>U: 返回商品详情 - end - - U->>P: 浏览商品 - P-->>U: 返回商品列表 - - U->>O: 下单购买 - O->>Pay: 创建支付订单 - Pay-->>U: 返回支付信息 - - U->>Pay: 完成支付 - Pay->>Pay: 验证支付结果 - Pay->>O: 通知支付成功 - - O->>O: 更新订单状态 - O->>M: 通知商家有新订单 - O->>N: 发送购买成功通知给用户 - - M->>M: 处理订单 - N->>N: 发送通知 -``` \ No newline at end of file diff --git a/docs/development_plan.md b/docs/development_plan.md deleted file mode 100644 index ab52cca..0000000 --- a/docs/development_plan.md +++ /dev/null @@ -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优化效果不达预期 - - 浏览器兼容性问题 - - 响应式布局在不同设备上显示异常 -- **管理员后台风险**: - - 权限控制漏洞可能导致数据泄露 - - 操作日志记录不完整影响审计 - - 数据统计准确性需要验证 \ No newline at end of file diff --git a/docs/requirements.md b/docs/requirements.md deleted file mode 100644 index 5a510e1..0000000 --- a/docs/requirements.md +++ /dev/null @@ -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秒） -- 批量操作功能正常工作 -- 数据导出功能完整可用 -- 权限分级控制准确无误 \ No newline at end of file diff --git a/docs/website_requirements.md b/docs/website_requirements.md deleted file mode 100644 index 9277f81..0000000 --- a/docs/website_requirements.md +++ /dev/null @@ -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和性能指标 | 产品经理 | \ No newline at end of file diff --git a/docs/开发指南.md b/docs/开发指南.md new file mode 100644 index 0000000..79e8519 --- /dev/null +++ b/docs/开发指南.md @@ -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 + + + + + +``` + +#### 后端代码规范 + +##### 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 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 +# 提交信息格式 +(): + + + +