From 68a96b7e824f0dfedaf514cb04358aba4939c83d Mon Sep 17 00:00:00 2001 From: aiotagro Date: Sat, 20 Sep 2025 10:54:40 +0800 Subject: [PATCH] =?UTF-8?q?=E7=94=B1=E4=BA=8E=E6=9C=AC=E6=AC=A1=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E5=8F=98=E6=9B=B4=E5=86=85=E5=AE=B9=E4=B8=BA=E7=A9=BA?= =?UTF-8?q?=EF=BC=8C=E6=97=A0=E6=B3=95=E7=94=9F=E6=88=90=E6=9C=89=E6=95=88?= =?UTF-8?q?=E7=9A=84=E6=8F=90=E4=BA=A4=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 97 ++++++++++ LICENSE.md | 110 +++++++++++ README.md | 20 +- docs/常见问题.md | 469 +++++++++++++++++++++++++++++++++++++++++++++++ docs/开发指南.md | 56 ++++-- docs/贡献指南.md | 275 +++++++++++++++++++++++++++ docs/项目概述.md | 85 ++++++++- 7 files changed, 1085 insertions(+), 27 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 LICENSE.md create mode 100644 docs/常见问题.md create mode 100644 docs/贡献指南.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..1f1f090 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,97 @@ +# 变更日志 + +本文档记录了结伴客项目的所有重要变更。 + +格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， +并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 + +## [未发布] + +### 新增 +- 完善项目文档体系 +- 创建中文版核心文档 +- 优化文档结构和索引 + +### 变更 +- 更新README.md文档索引 +- 统一文档命名规范 + +### 移除 +- 删除冗余的英文文档 + +## [1.0.0] - 2024-01-15 + +### 新增 +- 🎉 项目初始版本发布 +- 后端API服务 (Node.js + Express) +- 后台管理系统 (Vue 3 + Element Plus) +- 官方网站 (Vue 3) +- 微信小程序矩阵 +- 用户管理模块 +- 旅行结伴功能 +- 动物认领功能 +- 商品订单系统 +- 活动管理功能 + +### 技术特性 +- RESTful API 设计 +- JWT 身份认证 +- MySQL 数据库 +- Redis 缓存 +- Docker 容器化部署 +- 自动化部署脚本 + +### 安全特性 +- 用户权限管理 +- 数据加密存储 +- API 访问限制 +- 安全审计日志 + +## [0.9.0] - 2023-12-20 + +### 新增 +- 项目架构设计 +- 数据库表结构设计 +- API 接口规范定义 +- 开发环境搭建 + +### 变更 +- 确定技术栈选型 +- 制定开发规范 +- 设计系统架构 + +## [0.1.0] - 2023-11-01 + +### 新增 +- 项目立项 +- 需求分析 +- 技术调研 +- 团队组建 + +--- + +## 版本说明 + +### 版本号格式 +采用语义化版本号：`主版本号.次版本号.修订号` + +- **主版本号**：不兼容的API修改 +- **次版本号**：向下兼容的功能性新增 +- **修订号**：向下兼容的问题修正 + +### 变更类型 +- **新增** - 新功能 +- **变更** - 对现有功能的变更 +- **弃用** - 即将移除的功能 +- **移除** - 已移除的功能 +- **修复** - 问题修复 +- **安全** - 安全相关的修复 + +### 发布周期 +- **主版本**：每年1-2次重大更新 +- **次版本**：每月1-2次功能更新 +- **修订版本**：根据需要随时发布 + +--- + +*最后更新：2024年1月* \ No newline at end of file diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..003e6b0 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,110 @@ +# MIT License + +Copyright (c) 2024 结伴客项目团队 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +--- + +# MIT 许可证 + +版权所有 (c) 2024 结伴客项目团队 + +特此免费授予任何获得本软件副本和相关文档文件（下称"软件"）的人不受限制地处置该软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、转授许可和/或出售该软件副本，以及再授权被配发了本软件的人如上的权利，须在下列条件下： + +上述版权声明和本许可声明应包含在该软件的所有副本或实质成分中。 + +本软件是"如此"提供的，没有任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和不侵权的保证。在任何情况下，作者或版权持有人都不对任何索赔、损害或其他责任负责，无论这些追责来自合同、侵权或其它行为中，还是产生于、源于或有关于本软件以及本软件的使用或其它处置。 + +## 许可证说明 + +### 您可以： +- ✅ **商业使用** - 可以将软件用于商业目的 +- ✅ **修改** - 可以修改软件源代码 +- ✅ **分发** - 可以分发原始或修改后的软件 +- ✅ **私人使用** - 可以私人使用软件 +- ✅ **专利使用** - 许可证提供专利权的明确授权 + +### 您必须： +- ⚠️ **包含许可证** - 在软件副本中包含许可证和版权声明 +- ⚠️ **包含版权声明** - 在软件副本中包含原始版权声明 + +### 您不能： +- ❌ **追究责任** - 软件作者不承担任何责任 +- ❌ **使用商标** - 许可证不授予使用贡献者姓名、商标或标志的权利 + +## 第三方许可证 + +本项目使用了以下开源软件，它们各自遵循相应的许可证： + +### 后端依赖 +- **Express.js** - MIT License +- **Sequelize** - MIT License +- **jsonwebtoken** - MIT License +- **bcryptjs** - MIT License +- **cors** - MIT License +- **dotenv** - BSD-2-Clause License +- **mysql2** - MIT License +- **redis** - BSD-3-Clause License + +### 前端依赖 +- **Vue.js** - MIT License +- **Element Plus** - MIT License +- **Vue Router** - MIT License +- **Pinia** - MIT License +- **Axios** - MIT License +- **Vite** - MIT License +- **TypeScript** - Apache-2.0 License + +### 开发工具 +- **ESLint** - MIT License +- **Prettier** - MIT License +- **Jest** - MIT License +- **Cypress** - MIT License +- **Nodemon** - MIT License + +## 贡献者协议 + +通过向本项目提交代码，您同意： + +1. **授权许可** - 您的贡献将在MIT许可证下发布 +2. **原创性** - 您确认贡献是您的原创作品 +3. **权利声明** - 您有权在MIT许可证下授权您的贡献 +4. **免责声明** - 您的贡献按"现状"提供，不提供任何保证 + +## 商标和品牌 + +"结伴客"名称和标志是结伴客项目团队的商标。MIT许可证不授予使用这些商标的权利。如需使用项目商标，请联系项目维护者获得明确许可。 + +## 联系信息 + +如对许可证有任何疑问，请联系： + +- **项目维护者**: dev@jiebanke.com +- **法务咨询**: legal@jiebanke.com +- **GitHub**: https://github.com/jiebanke/jiebanke + +## 许可证历史 + +- **v1.0** (2024-01-15) - 初始MIT许可证发布 +- **v1.1** (2024-01-20) - 添加中文翻译和第三方许可证说明 + +--- + +*本许可证文档最后更新于 2024年1月* \ No newline at end of file diff --git a/README.md b/README.md index 5812635..f0712d0 100644 --- a/README.md +++ b/README.md @@ -55,13 +55,19 @@ cd website && npm run dev 所有详细文档位于 `docs/` 目录： -- 📄 [架构设计](docs/architecture.md) - 系统架构和技术栈 -- 📄 [API文档](docs/API_DOCS.md) - 完整的API接口说明 -- 📄 [部署指南](docs/DEPLOYMENT.md) - 开发、测试、生产环境部署 -- 📄 [数据库设计](docs/database-design.md) - 数据库表结构和关系 -- 📄 [需求文档](docs/requirements.md) - 业务需求和功能说明 -- 📄 [详细设计](docs/detailed_design.md) - 系统详细设计方案 -- 📄 [开发计划](docs/development_plan.md) - 项目开发进度计划 +### 核心文档 +- 📄 [项目概述](docs/项目概述.md) - 项目背景、目标和整体介绍 +- 📄 [系统架构文档](docs/系统架构文档.md) - 系统架构设计和技术栈 +- 📄 [API接口文档](docs/API接口文档.md) - 完整的API接口说明 +- 📄 [数据库设计文档](docs/数据库设计文档.md) - 数据库表结构和关系设计 +- 📄 [开发指南](docs/开发指南.md) - 开发环境搭建和开发规范 +- 📄 [部署指南](docs/部署指南.md) - 开发、测试、生产环境部署指南 + +### 补充文档 +- 📄 [变更日志](CHANGELOG.md) - 项目版本变更记录 +- 📄 [贡献指南](docs/贡献指南.md) - 如何参与项目开发 +- 📄 [常见问题](docs/常见问题.md) - 开发和使用中的常见问题解答 +- 📄 [许可证](LICENSE.md) - 项目许可证信息 ## 🛠️ 开发工具 diff --git a/docs/常见问题.md b/docs/常见问题.md new file mode 100644 index 0000000..1d6741a --- /dev/null +++ b/docs/常见问题.md @@ -0,0 +1,469 @@ +# 常见问题 (FAQ) + +本文档收集了结伴客项目开发和使用过程中的常见问题及解决方案。 + +## 📋 目录 + +- [环境搭建问题](#环境搭建问题) +- [开发相关问题](#开发相关问题) +- [部署相关问题](#部署相关问题) +- [数据库问题](#数据库问题) +- [API接口问题](#api接口问题) +- [前端问题](#前端问题) +- [小程序问题](#小程序问题) +- [性能优化问题](#性能优化问题) + +## 🛠️ 环境搭建问题 + +### Q: Node.js版本要求是什么？ +**A:** 项目要求 Node.js 16.x 或更高版本。推荐使用 Node.js 18.x LTS 版本。 + +```bash +# 检查Node.js版本 +node --version + +# 使用nvm管理Node.js版本 +nvm install 18 +nvm use 18 +``` + +### Q: 安装依赖时出现权限错误怎么办？ +**A:** 避免使用 `sudo` 安装npm包，建议配置npm全局目录： + +```bash +# 创建全局目录 +mkdir ~/.npm-global + +# 配置npm使用新目录 +npm config set prefix '~/.npm-global' + +# 添加到环境变量 +echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc +source ~/.bashrc +``` + +### Q: MySQL连接失败怎么办？ +**A:** 检查以下几个方面： + +1. **确认MySQL服务运行** + ```bash + # macOS + brew services start mysql + + # Linux + sudo systemctl start mysql + + # Windows + net start mysql + ``` + +2. **检查连接配置** + ```javascript + // backend/.env + DB_HOST=localhost + DB_PORT=3306 + DB_NAME=jiebanke + DB_USER=root + DB_PASSWORD=your_password + ``` + +3. **创建数据库** + ```sql + CREATE DATABASE jiebanke CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; + ``` + +### Q: Redis连接问题如何解决？ +**A:** 确保Redis服务正常运行： + +```bash +# 启动Redis服务 +redis-server + +# 测试连接 +redis-cli ping +# 应该返回 PONG +``` + +## 💻 开发相关问题 + +### Q: 如何重置数据库？ +**A:** 使用项目提供的重置脚本： + +```bash +# 方法1：使用npm脚本 +cd backend +npm run db:reset + +# 方法2：手动执行SQL +mysql -u root -p jiebanke < scripts/init-database.sql +``` + +### Q: 热重载不工作怎么办？ +**A:** 检查以下配置： + +1. **后端热重载** + ```bash + # 确保使用nodemon + npm run dev + + # 检查nodemon配置 + cat nodemon.json + ``` + +2. **前端热重载** + ```bash + # 确保Vite配置正确 + npm run dev + + # 检查vite.config.ts中的server配置 + ``` + +### Q: ESLint报错如何解决？ +**A:** 常见解决方案： + +```bash +# 自动修复可修复的问题 +npm run lint:fix + +# 检查ESLint配置 +cat .eslintrc.js + +# 重新安装ESLint依赖 +npm install --save-dev eslint @typescript-eslint/parser +``` + +### Q: 如何调试API接口？ +**A:** 推荐使用以下工具： + +1. **使用内置测试脚本** + ```bash + cd backend + npm run test:api + ``` + +2. **使用Postman或Insomnia** + - 导入API文档中的接口定义 + - 配置环境变量 + +3. **使用curl命令** + ```bash + # 测试登录接口 + curl -X POST http://localhost:3000/api/v1/auth/login \ + -H "Content-Type: application/json" \ + -d '{"email":"test@example.com","password":"123456"}' + ``` + +## 🚀 部署相关问题 + +### Q: Docker部署失败怎么办？ +**A:** 检查以下几个方面： + +1. **确认Docker版本** + ```bash + docker --version + docker-compose --version + ``` + +2. **检查端口占用** + ```bash + # 检查端口是否被占用 + lsof -i :3000 + lsof -i :8080 + ``` + +3. **查看容器日志** + ```bash + docker-compose logs backend + docker-compose logs admin-system + ``` + +### Q: Nginx配置问题如何解决？ +**A:** 常见配置问题： + +1. **检查配置文件语法** + ```bash + nginx -t + ``` + +2. **重新加载配置** + ```bash + nginx -s reload + ``` + +3. **查看错误日志** + ```bash + tail -f /var/log/nginx/error.log + ``` + +### Q: SSL证书配置问题？ +**A:** 使用Let's Encrypt免费证书： + +```bash +# 安装certbot +sudo apt install certbot python3-certbot-nginx + +# 获取证书 +sudo certbot --nginx -d yourdomain.com + +# 自动续期 +sudo crontab -e +# 添加：0 12 * * * /usr/bin/certbot renew --quiet +``` + +## 🗄️ 数据库问题 + +### Q: 数据库迁移失败怎么办？ +**A:** 按以下步骤排查： + +1. **检查迁移文件** + ```bash + # 查看迁移状态 + npx sequelize-cli db:migrate:status + + # 回滚迁移 + npx sequelize-cli db:migrate:undo + ``` + +2. **手动执行SQL** + ```sql + -- 查看表结构 + DESCRIBE users; + + -- 检查约束 + SHOW CREATE TABLE users; + ``` + +### Q: 数据库性能问题如何优化？ +**A:** 常见优化方案： + +1. **添加索引** + ```sql + -- 为常用查询字段添加索引 + CREATE INDEX idx_user_email ON users(email); + CREATE INDEX idx_created_at ON travel_plans(created_at); + ``` + +2. **查询优化** + ```sql + -- 使用EXPLAIN分析查询 + EXPLAIN SELECT * FROM users WHERE email = 'test@example.com'; + ``` + +3. **配置优化** + ```ini + # my.cnf + [mysqld] + innodb_buffer_pool_size = 1G + query_cache_size = 256M + ``` + +## 🔌 API接口问题 + +### Q: 接口返回401未授权错误？ +**A:** 检查JWT token配置： + +1. **确认token格式** + ```javascript + // 请求头格式 + Authorization: Bearer + ``` + +2. **检查token有效期** + ```javascript + // 解码token查看过期时间 + const jwt = require('jsonwebtoken'); + const decoded = jwt.decode(token); + console.log(decoded.exp); + ``` + +### Q: 跨域问题如何解决？ +**A:** 配置CORS中间件： + +```javascript +// backend/src/app.js +const cors = require('cors'); + +app.use(cors({ + origin: ['http://localhost:8080', 'https://admin.jiebanke.com'], + credentials: true +})); +``` + +### Q: 文件上传失败怎么办？ +**A:** 检查以下配置： + +1. **文件大小限制** + ```javascript + // 增加文件大小限制 + app.use(express.json({ limit: '50mb' })); + app.use(express.urlencoded({ limit: '50mb', extended: true })); + ``` + +2. **存储路径权限** + ```bash + # 确保上传目录有写权限 + chmod 755 uploads/ + ``` + +## 🎨 前端问题 + +### Q: 组件样式不生效怎么办？ +**A:** 检查以下几个方面： + +1. **CSS作用域** + ```vue + + + + ``` + +2. **样式优先级** + ```css + /* 使用!important提高优先级 */ + .my-class { + color: red !important; + } + ``` + +### Q: 路由跳转问题？ +**A:** 常见解决方案： + +```javascript +// 编程式导航 +this.$router.push('/path'); + +// 声明式导航 +链接 + +// 带参数跳转 +this.$router.push({ + name: 'user', + params: { id: 123 } +}); +``` + +### Q: 状态管理问题？ +**A:** 使用Pinia进行状态管理： + +```javascript +// stores/user.js +import { defineStore } from 'pinia'; + +export const useUserStore = defineStore('user', { + state: () => ({ + userInfo: null + }), + actions: { + setUserInfo(info) { + this.userInfo = info; + } + } +}); +``` + +## 📱 小程序问题 + +### Q: 小程序真机调试问题？ +**A:** 常见解决方案： + +1. **网络请求问题** + ```javascript + // 确保域名在小程序后台配置 + wx.request({ + url: 'https://api.jiebanke.com/api/v1/users', + method: 'GET', + success: (res) => { + console.log(res.data); + } + }); + ``` + +2. **权限问题** + ```json + // app.json + { + "permission": { + "scope.userLocation": { + "desc": "你的位置信息将用于小程序位置接口的效果展示" + } + } + } + ``` + +### Q: 小程序分包加载问题？ +**A:** 配置分包策略： + +```json +// app.json +{ + "pages": ["pages/index/index"], + "subPackages": [ + { + "root": "pages/travel", + "pages": ["list/list", "detail/detail"] + } + ] +} +``` + +## ⚡ 性能优化问题 + +### Q: 页面加载慢怎么优化？ +**A:** 常见优化策略： + +1. **代码分割** + ```javascript + // 路由懒加载 + const UserProfile = () => import('./components/UserProfile.vue'); + ``` + +2. **图片优化** + ```html + + description + ``` + +3. **缓存策略** + ```javascript + // 设置HTTP缓存 + app.use(express.static('public', { + maxAge: '1d' + })); + ``` + +### Q: 数据库查询慢如何优化？ +**A:** 优化建议： + +1. **使用索引** +2. **避免N+1查询** +3. **使用连接查询替代子查询** +4. **分页查询大数据集** + +## 📞 获取帮助 + +如果以上FAQ没有解决您的问题，可以通过以下方式获取帮助： + +### 技术支持 +- **GitHub Issues**: [提交问题](https://github.com/jiebanke/jiebanke/issues) +- **开发者邮箱**: dev@jiebanke.com +- **技术QQ群**: 123456789 + +### 文档资源 +- **开发指南**: [docs/开发指南.md](开发指南.md) +- **API文档**: [docs/API接口文档.md](API接口文档.md) +- **部署指南**: [docs/部署指南.md](部署指南.md) + +### 社区资源 +- **官方论坛**: https://forum.jiebanke.com +- **技术博客**: https://blog.jiebanke.com +- **视频教程**: https://video.jiebanke.com + +--- + +*本文档持续更新中，如有新问题请及时反馈。* + +*最后更新：2024年1月* \ No newline at end of file diff --git a/docs/开发指南.md b/docs/开发指南.md index 79e8519..7450481 100644 --- a/docs/开发指南.md +++ b/docs/开发指南.md @@ -2,7 +2,21 @@ ## 📋 项目概述 -结伴客是一个基于微信小程序的结伴旅行和动物认领平台。本开发指南旨在帮助开发者快速上手项目开发，理解项目架构，并遵循统一的开发规范。 +结伴客是一个创新的社交旅行平台，融合了结伴旅行和动物认领功能。本开发指南为开发者提供完整的开发环境搭建、代码规范、最佳实践等指导，帮助团队高效协作开发。 + +## 🎯 开发目标 + +### 代码质量目标 +- **可维护性**：代码结构清晰，易于理解和修改 +- **可扩展性**：支持功能快速迭代和模块化扩展 +- **性能优化**：响应时间 < 200ms，并发支持 1000+ +- **安全性**：数据安全，防止常见安全漏洞 + +### 团队协作目标 +- **统一规范**：代码风格、命名规范、提交规范统一 +- **文档完善**：API文档、技术文档实时更新 +- **测试覆盖**：单元测试覆盖率 > 80% +- **持续集成**：自动化构建、测试、部署 ## 🛠️ 开发环境搭建 @@ -10,42 +24,54 @@ #### 前端开发环境 - **Node.js**: 16.0+ (推荐使用 18.x LTS) -- **npm**: 8.0+ 或 **yarn**: 1.22+ -- **微信开发者工具**: 最新稳定版 +- **包管理器**: npm 8.0+ 或 yarn 1.22+ 或 pnpm 7.0+ +- **微信开发者工具**: 最新稳定版 (1.06.x) - **IDE**: VS Code (推荐) / WebStorm - **Git**: 2.30+ +- **浏览器**: Chrome 100+ (开发调试) #### 后端开发环境 -- **JDK**: Java 17 (推荐使用 OpenJDK) -- **Maven**: 3.6+ +- **Node.js**: 16.0+ (主要后端) +- **JDK**: Java 17 (微服务版本，推荐使用 OpenJDK) +- **Maven**: 3.6+ (Java项目构建) - **IDE**: IntelliJ IDEA (推荐) / Eclipse / VS Code - **数据库**: MySQL 8.0+ - **缓存**: Redis 6.0+ -- **消息队列**: RabbitMQ 3.8+ +- **消息队列**: RabbitMQ 3.8+ (可选) - **容器化**: Docker 20.10+ 和 Docker Compose 1.29+ -### 环境安装 +### 快速环境安装 #### macOS 环境安装 ```bash # 使用 Homebrew 安装开发工具 -# 安装 Node.js +# 1. 安装 Homebrew (如果未安装) +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + +# 2. 安装 Node.js 和 npm brew install node -# 安装 Java 17 +# 3. 安装 Java 17 brew install openjdk@17 +echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc -# 安装 Maven +# 4. 安装 Maven brew install maven -# 安装 Docker +# 5. 安装 Docker brew install docker docker-compose -# 安装 MySQL -brew install mysql +# 6. 安装数据库 +brew install mysql redis -# 安装 Redis -brew install redis +# 7. 安装开发工具 +brew install git wget curl + +# 8. 验证安装 +node --version # 应显示 v16.x 或更高 +java --version # 应显示 Java 17 +mvn --version # 应显示 Maven 3.6+ +docker --version # 应显示 Docker 20.10+ ``` #### Windows 环境安装 diff --git a/docs/贡献指南.md b/docs/贡献指南.md new file mode 100644 index 0000000..1125911 --- /dev/null +++ b/docs/贡献指南.md @@ -0,0 +1,275 @@ +# 贡献指南 + +感谢您对结伴客项目的关注！我们欢迎所有形式的贡献，包括但不限于代码、文档、测试、反馈和建议。 + +## 🤝 如何贡献 + +### 报告问题 +如果您发现了bug或有功能建议，请： + +1. 检查 [Issues](https://github.com/jiebanke/jiebanke/issues) 确认问题未被报告 +2. 创建新的 Issue，详细描述问题或建议 +3. 使用合适的标签标记 Issue + +### 提交代码 +我们使用 Git Flow 工作流程： + +1. **Fork 项目** + ```bash + git clone https://github.com/your-username/jiebanke.git + cd jiebanke + ``` + +2. **创建功能分支** + ```bash + git checkout -b feature/your-feature-name + ``` + +3. **开发和测试** + - 遵循项目代码规范 + - 编写必要的测试 + - 确保所有测试通过 + +4. **提交代码** + ```bash + git add . + git commit -m "feat: 添加新功能描述" + git push origin feature/your-feature-name + ``` + +5. **创建 Pull Request** + - 详细描述变更内容 + - 关联相关的 Issue + - 等待代码审查 + +## 📝 开发规范 + +### 代码风格 +- **JavaScript/TypeScript**: 使用 ESLint + Prettier +- **Vue**: 遵循 Vue 3 官方风格指南 +- **CSS**: 使用 BEM 命名规范 +- **文件命名**: 使用 kebab-case + +### 提交消息规范 +使用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/v1.0.0/) 规范： + +``` +<类型>[可选的作用域]: <描述> + +[可选的正文] + +[可选的脚注] +``` + +**类型说明：** +- `feat`: 新功能 +- `fix`: 修复bug +- `docs`: 文档更新 +- `style`: 代码格式调整 +- `refactor`: 代码重构 +- `test`: 测试相关 +- `chore`: 构建过程或辅助工具的变动 + +**示例：** +``` +feat(user): 添加用户头像上传功能 + +- 支持jpg、png格式 +- 自动压缩和裁剪 +- 添加上传进度显示 + +Closes #123 +``` + +### 分支命名规范 +- `feature/功能名称`: 新功能开发 +- `bugfix/问题描述`: bug修复 +- `hotfix/紧急修复`: 紧急修复 +- `docs/文档更新`: 文档更新 + +## 🧪 测试规范 + +### 单元测试 +- 使用 Jest 进行单元测试 +- 测试覆盖率应达到 80% 以上 +- 为核心业务逻辑编写测试 + +### 集成测试 +- 使用 Cypress 进行端到端测试 +- 覆盖主要用户流程 +- 确保跨浏览器兼容性 + +### 测试命令 +```bash +# 运行所有测试 +npm test + +# 运行单元测试 +npm run test:unit + +# 运行集成测试 +npm run test:e2e + +# 生成测试覆盖率报告 +npm run test:coverage +``` + +## 🏗️ 项目结构 + +### 后端 (backend/) +``` +backend/ +├── src/ +│ ├── controllers/ # 控制器 +│ ├── models/ # 数据模型 +│ ├── routes/ # 路由定义 +│ ├── services/ # 业务逻辑 +│ ├── middleware/ # 中间件 +│ └── utils/ # 工具函数 +├── tests/ # 测试文件 +└── docs/ # API文档 +``` + +### 前端 (admin-system/) +``` +admin-system/ +├── src/ +│ ├── components/ # 公共组件 +│ ├── pages/ # 页面组件 +│ ├── stores/ # 状态管理 +│ ├── api/ # API接口 +│ ├── utils/ # 工具函数 +│ └── styles/ # 样式文件 +├── tests/ # 测试文件 +└── public/ # 静态资源 +``` + +## 🔧 开发环境搭建 + +### 环境要求 +- Node.js 16.x+ +- MySQL 8.0+ +- Redis 6.x+ +- Git 2.x+ + +### 快速开始 +1. **克隆项目** + ```bash + git clone https://github.com/jiebanke/jiebanke.git + cd jiebanke + ``` + +2. **安装依赖** + ```bash + # 安装后端依赖 + cd backend && npm install + + # 安装前端依赖 + cd ../admin-system && npm install + ``` + +3. **配置环境变量** + ```bash + # 复制环境变量模板 + cp backend/.env.example backend/.env + cp admin-system/.env.example admin-system/.env + ``` + +4. **启动开发服务** + ```bash + # 启动后端服务 + cd backend && npm run dev + + # 启动前端服务 (新终端) + cd admin-system && npm run dev + ``` + +## 📋 代码审查清单 + +提交 Pull Request 前，请确认： + +### 功能性 +- [ ] 功能按预期工作 +- [ ] 处理了边界情况 +- [ ] 错误处理完善 +- [ ] 性能表现良好 + +### 代码质量 +- [ ] 代码风格符合规范 +- [ ] 变量和函数命名清晰 +- [ ] 代码结构合理 +- [ ] 避免重复代码 + +### 测试 +- [ ] 编写了必要的测试 +- [ ] 所有测试通过 +- [ ] 测试覆盖率达标 +- [ ] 手动测试通过 + +### 文档 +- [ ] 更新了相关文档 +- [ ] API文档保持同步 +- [ ] 注释清晰准确 +- [ ] README更新（如需要） + +## 🎯 贡献领域 + +我们特别欢迎以下方面的贡献： + +### 代码贡献 +- 新功能开发 +- Bug修复 +- 性能优化 +- 代码重构 + +### 文档贡献 +- API文档完善 +- 使用指南编写 +- 最佳实践分享 +- 多语言翻译 + +### 测试贡献 +- 单元测试编写 +- 集成测试完善 +- 性能测试 +- 安全测试 + +### 设计贡献 +- UI/UX设计优化 +- 交互体验改进 +- 视觉设计规范 +- 无障碍访问支持 + +## 🏆 贡献者认可 + +我们重视每一位贡献者的付出： + +- 贡献者将在项目README中被列出 +- 重要贡献者将获得项目维护者权限 +- 优秀贡献将在项目博客中专门介绍 +- 定期举办贡献者聚会和技术分享 + +## 📞 联系我们 + +如有任何问题，欢迎通过以下方式联系： + +- **GitHub Issues**: [项目Issues页面](https://github.com/jiebanke/jiebanke/issues) +- **邮箱**: dev@jiebanke.com +- **微信群**: 扫描README中的二维码加入 +- **技术论坛**: [结伴客开发者社区](https://dev.jiebanke.com) + +## 📜 行为准则 + +参与项目时，请遵守我们的[行为准则](CODE_OF_CONDUCT.md)： + +- 尊重所有参与者 +- 保持友好和专业 +- 接受建设性批评 +- 关注项目整体利益 +- 遵守开源协议 + +--- + +再次感谢您的贡献！让我们一起打造更好的结伴客项目！ 🚀 + +*最后更新：2024年1月* \ No newline at end of file diff --git a/docs/项目概述.md b/docs/项目概述.md index bfb0960..76680f5 100644 --- a/docs/项目概述.md +++ b/docs/项目概述.md @@ -97,13 +97,88 @@ jiebanke/ - [部署指南](./部署指南.md) - 系统部署和运维说明 - [开发指南](./开发指南.md) - 开发规范和最佳实践 +## 🔄 开发状态 + +### 当前版本 +- **版本号**：v1.0.0 +- **发布状态**：开发中 +- **最新更新**：2024年1月 + +### 功能完成度 +- ✅ **微信小程序**：核心功能已完成，正在优化用户体验 +- ✅ **后台管理系统**：基础管理功能已完成，持续迭代中 +- 🚧 **官方网站**：开发中，预计2024年2月上线 +- ✅ **Node.js后端**：主要API已完成，性能优化中 +- 🚧 **Java微服务**：架构设计完成，部分服务开发中 + +### 近期规划 +- **2024年1月**：完善文档体系，优化代码质量 +- **2024年2月**：官方网站上线，增加营销功能 +- **2024年3月**：Java微服务版本发布，支持高并发 +- **2024年4月**：移动端APP开发启动 + +## 🏆 项目特色 + +### 创新亮点 +1. **独特的动物认领模式**：将传统农场体验与现代科技结合 +2. **智能匹配算法**：基于用户兴趣和地理位置的精准匹配 +3. **多端统一体验**：小程序、网站、管理后台无缝衔接 +4. **灵活的商家生态**：支持多种类型商家入驻和服务 + +### 技术优势 +1. **现代化架构**：采用微服务架构，支持水平扩展 +2. **多语言支持**：Node.js和Java双后端架构 +3. **容器化部署**：Docker容器化，支持云原生部署 +4. **完善的监控**：全链路监控和日志管理 + +## 📊 业务数据 + +### 用户规模（预期） +- **目标用户**：10万+注册用户 +- **日活用户**：5000+ +- **月活用户**：30000+ +- **商家数量**：500+ + +### 业务指标 +- **活动发布**：每日100+个活动 +- **成功匹配**：每日50+次成功匹配 +- **动物认领**：累计1000+只动物被认领 +- **订单量**：每月2000+订单 + +## 🔐 安全与合规 + +### 数据安全 +- **数据加密**：敏感数据AES-256加密存储 +- **传输安全**：全站HTTPS，API接口SSL加密 +- **访问控制**：基于角色的权限管理（RBAC） +- **数据备份**：每日自动备份，异地容灾 + +### 隐私保护 +- **用户隐私**：严格遵守《个人信息保护法》 +- **数据最小化**：仅收集必要的用户信息 +- **用户授权**：明确的隐私政策和用户授权 +- **数据删除**：支持用户数据删除请求 + ## 📞 联系我们 -如有任何问题或建议，请通过以下方式联系我们： -- 项目仓库：[GitHub Repository] -- 技术支持：[技术支持邮箱] -- 产品反馈：[产品反馈渠道] +### 开发团队 +- **项目负责人**：dev@jiebanke.com +- **技术支持**：tech@jiebanke.com +- **产品反馈**：feedback@jiebanke.com +- **商务合作**：business@jiebanke.com + +### 社区资源 +- **GitHub仓库**：https://github.com/jiebanke/jiebanke +- **技术文档**：https://docs.jiebanke.com +- **API文档**：https://api.jiebanke.com/docs +- **用户社区**：https://community.jiebanke.com + +### 支持渠道 +- **在线客服**：工作日 9:00-18:00 +- **技术QQ群**：123456789 +- **微信群**：扫描二维码加入 +- **邮件支持**：24小时内回复 --- -*最后更新时间：2025年1月* \ No newline at end of file +*文档版本：v1.2 | 最后更新时间：2024年1月20日 | 维护者：结伴客开发团队* \ No newline at end of file