# 后端开发文档 ## 版本历史 | 版本 | 日期 | 作者 | 变更说明 | |------|------|------|----------| | 1.0 | 2024-01-20 | 后端开发团队 | 初始版本 | | 1.1 | 2024-09-21 | 后端开发团队 | 更新技术栈，与实际项目保持一致 | ## 1. 项目概述 ### 1.1 项目介绍 畜牧养殖管理平台后端服务，采用微服务架构，为官网、管理后台、小程序APP提供统一的API服务。 ### 1.2 技术栈 - **开发语言**: Node.js (JavaScript) - **Web框架**: Express.js - **数据库**: MySQL 8.0 + Redis (缓存) - **认证**: JWT - **文档**: 接口设计文档 - **测试**: 手动测试 + API测试 - **部署**: 云服务器 + PM2 - **监控**: 日志监控 ### 1.3 项目结构 ``` backend/ ├── api/ # API服务 │ ├── routes/ # 路由定义 │ ├── server.js # 服务器入口 │ ├── package.json # 依赖管理 │ └── .env.example # 环境配置示例 ├── database/ # 数据库管理 │ ├── init_tables.sql # 数据库表结构 │ ├── init_data.sql # 初始数据 │ ├── setup-database.js # 数据库初始化脚本 │ └── database-manager.js # 数据库管理工具 ├── services/ # 业务服务 │ └── README.md └── utils/ # 工具类 └── README.md ``` ## 2. 开发环境搭建 ### 2.1 环境要求 - Node.js >= 16.0.0 - npm >= 8.0.0 - MySQL >= 8.0 - Redis >= 6.0 - MongoDB >= 4.4 ### 2.2 安装步骤 ```bash # 1. 克隆项目 git clone cd backend # 2. 安装依赖 npm install # 3. 配置环境变量 cp .env.example .env # 编辑 .env 文件，配置数据库连接等信息 # 4. 初始化数据库 npm run db:migrate npm run db:seed # 5. 启动开发服务器 npm run dev ``` ### 2.3 开发工具配置 - **VSCode插件**: TypeScript, ESLint, Prettier, REST Client - **代码规范**: ESLint + Prettier - **Git钩子**: Husky + lint-staged - **调试工具**: VSCode Debugger ## 3. 开发计划 ### 3.1 第一阶段：基础架构搭建（1-2周） #### 3.1.1 项目初始化 **任务**: 搭建基础项目结构 **负责人**: 架构师 **工期**: 2天 **详细任务**: - [ ] 创建项目目录结构 - [ ] 配置TypeScript环境 - [ ] 配置ESLint和Prettier - [ ] 配置Git钩子和代码规范 - [ ] 创建基础的package.json和依赖管理 #### 3.1.2 数据库设计与连接 **任务**: 设计数据库结构并建立连接 **负责人**: 数据库工程师 **工期**: 3天 **详细任务**: - [ ] 设计MySQL数据库表结构 - [ ] 配置TypeORM连接和实体模型 - [ ] 设计Redis缓存结构 - [ ] 配置MongoDB连接和集合设计 - [ ] 编写数据库迁移脚本 - [ ] 创建初始化数据种子 #### 3.1.3 基础中间件开发 **任务**: 开发通用中间件 **负责人**: 后端工程师A **工期**: 3天 **详细任务**: - [ ] 开发日志中间件 - [ ] 开发错误处理中间件 - [ ] 开发CORS中间件 - [ ] 开发请求限流中间件 - [ ] 开发参数验证中间件 - [ ] 开发响应格式化中间件 #### 3.1.4 认证授权系统 **任务**: 实现JWT认证和权限控制 **负责人**: 后端工程师B **工期**: 4天 **详细任务**: - [ ] 实现JWT Token生成和验证 - [ ] 开发用户认证中间件 - [ ] 实现基于角色的权限控制(RBAC) - [ ] 开发微信小程序登录集成 - [ ] 实现Token刷新机制 - [ ] 开发权限验证装饰器 ### 3.2 第二阶段：核心业务模块（3-4周） #### 3.2.1 用户管理模块 **任务**: 实现用户相关功能 **负责人**: 后端工程师A **工期**: 5天 **详细任务**: - [ ] 用户注册和登录API - [ ] 用户信息管理API - [ ] 实名认证功能 - [ ] 用户头像上传 - [ ] 密码重置功能 - [ ] 用户状态管理 **接口列表**: ``` POST /api/auth/register # 用户注册 POST /api/auth/login # 用户登录 POST /api/auth/wechat/login # 微信登录 POST /api/auth/refresh # 刷新Token GET /api/users/profile # 获取用户信息 PUT /api/users/profile # 更新用户信息 POST /api/users/avatar # 上传头像 POST /api/users/verification # 实名认证 GET /api/users/verification # 获取认证状态 ``` #### 3.2.2 养殖场管理模块 **任务**: 实现养殖场相关功能 **负责人**: 后端工程师B **工期**: 6天 **详细任务**: - [ ] 养殖场CRUD操作 - [ ] 养殖场审核流程 - [ ] 养殖场统计数据 - [ ] 养殖场图片管理 - [ ] 养殖场地理位置服务 - [ ] 养殖场权限控制 **接口列表**: ``` GET /api/farms # 获取养殖场列表 POST /api/farms # 创建养殖场 GET /api/farms/:id # 获取养殖场详情 PUT /api/farms/:id # 更新养殖场信息 DELETE /api/farms/:id # 删除养殖场 GET /api/farms/:id/statistics # 获取养殖场统计 POST /api/farms/:id/approve # 审核养殖场 ``` #### 3.2.3 动物管理模块 **任务**: 实现动物档案管理 **负责人**: 后端工程师C **工期**: 7天 **详细任务**: - [ ] 动物档案CRUD操作 - [ ] 动物健康记录管理 - [ ] 动物生长记录跟踪 - [ ] 动物疫苗接种管理 - [ ] 动物繁殖记录 - [ ] 动物统计分析 **接口列表**: ``` GET /api/animals # 获取动物列表 POST /api/animals # 添加动物 GET /api/animals/:id # 获取动物详情 PUT /api/animals/:id # 更新动物信息 DELETE /api/animals/:id # 删除动物 GET /api/animals/:id/health # 获取健康记录 POST /api/animals/:id/health # 添加健康记录 GET /api/animals/:id/growth # 获取生长记录 POST /api/animals/:id/growth # 添加生长记录 ``` #### 3.2.4 交易管理模块 **任务**: 实现商品交易功能 **负责人**: 后端工程师D **工期**: 8天 **详细任务**: - [ ] 商品发布和管理 - [ ] 商品搜索和筛选 - [ ] 订单创建和管理 - [ ] 支付集成(微信支付) - [ ] 物流跟踪 - [ ] 交易评价系统 **接口列表**: ``` GET /api/products # 获取商品列表 POST /api/products # 发布商品 GET /api/products/:id # 获取商品详情 PUT /api/products/:id # 更新商品信息 DELETE /api/products/:id # 删除商品 POST /api/orders # 创建订单 GET /api/orders # 获取订单列表 GET /api/orders/:id # 获取订单详情 PUT /api/orders/:id/status # 更新订单状态 POST /api/payments # 创建支付 GET /api/payments/:id/status # 查询支付状态 ``` ### 3.3 第三阶段：高级功能开发（2-3周） #### 3.3.1 文件上传服务 **任务**: 实现文件上传和管理 **负责人**: 后端工程师A **工期**: 3天 **详细任务**: - [ ] 图片上传接口 - [ ] 文件类型验证 - [ ] 图片压缩和缩略图生成 - [ ] CDN集成 - [ ] 文件安全检查 - [ ] 批量上传支持 #### 3.3.2 消息通知系统 **任务**: 实现消息推送功能 **负责人**: 后端工程师B **工期**: 4天 **详细任务**: - [ ] 系统消息管理 - [ ] 微信小程序消息推送 - [ ] 短信通知集成 - [ ] 邮件通知功能 - [ ] 消息模板管理 - [ ] 消息统计分析 #### 3.3.3 数据统计分析 **任务**: 实现数据统计功能 **负责人**: 后端工程师C **工期**: 5天 **详细任务**: - [ ] 用户行为统计 - [ ] 养殖数据分析 - [ ] 交易数据统计 - [ ] 财务报表生成 - [ ] 数据可视化接口 - [ ] 定时统计任务 #### 3.3.4 系统管理功能 **任务**: 实现系统管理接口 **负责人**: 后端工程师D **工期**: 4天 **详细任务**: - [ ] 系统配置管理 - [ ] 日志查询接口 - [ ] 系统监控接口 - [ ] 数据备份恢复 - [ ] 系统健康检查 - [ ] 性能监控 ### 3.4 第四阶段：测试与优化（1-2周） #### 3.4.1 单元测试 **任务**: 编写单元测试 **负责人**: 全体后端工程师 **工期**: 3天 **详细任务**: - [ ] 编写Service层单元测试 - [ ] 编写Controller层单元测试 - [ ] 编写工具函数测试 - [ ] 编写中间件测试 - [ ] 测试覆盖率达到80%以上 #### 3.4.2 集成测试 **任务**: 编写集成测试 **负责人**: 测试工程师 **工期**: 3天 **详细任务**: - [ ] API接口集成测试 - [ ] 数据库操作测试 - [ ] 第三方服务集成测试 - [ ] 端到端测试场景 - [ ] 性能测试 #### 3.4.3 性能优化 **任务**: 系统性能优化 **负责人**: 架构师 **工期**: 4天 **详细任务**: - [ ] 数据库查询优化 - [ ] 缓存策略优化 - [ ] 接口响应时间优化 - [ ] 内存使用优化 - [ ] 并发处理优化 ## 4. 开发规范 ### 4.1 代码规范 - **命名规范**: 使用驼峰命名法，类名首字母大写 - **文件命名**: 使用kebab-case命名法 - **注释规范**: 使用JSDoc格式注释 - **代码格式**: 使用Prettier自动格式化 - **代码检查**: 使用ESLint进行代码检查 ### 4.2 API设计规范 - **RESTful设计**: 遵循REST API设计原则 - **HTTP状态码**: 正确使用HTTP状态码 - **响应格式**: 统一的JSON响应格式 - **错误处理**: 统一的错误码和错误信息 - **版本控制**: API版本控制策略 ### 4.3 数据库规范 - **表命名**: 使用snake_case命名法 - **字段命名**: 使用snake_case命名法 - **索引设计**: 合理设计数据库索引 - **外键约束**: 正确使用外键约束 - **数据迁移**: 使用迁移脚本管理数据库变更 ### 4.4 Git工作流 - **分支策略**: 使用Git Flow分支策略 - **提交规范**: 使用Conventional Commits规范 - **代码审查**: 所有代码必须经过Code Review - **合并策略**: 使用Squash and Merge策略 ## 5. 部署配置 ### 5.1 环境配置 ```javascript // config/database.js module.exports = { development: { host: 'localhost', port: 3306, username: 'root', password: 'password', database: 'xlxumu_dev' }, production: { host: process.env.DB_HOST, port: process.env.DB_PORT, username: process.env.DB_USERNAME, password: process.env.DB_PASSWORD, database: process.env.DB_DATABASE } } ``` ### 5.2 Docker配置 ```dockerfile # Dockerfile FROM node:16-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . EXPOSE 3000 CMD ["npm", "start"] ``` ### 5.3 PM2配置 ```javascript // ecosystem.config.js module.exports = { apps: [{ name: 'xlxumu-backend', script: './dist/app.js', instances: 'max', exec_mode: 'cluster', env: { NODE_ENV: 'production', PORT: 3000 } }] } ``` ## 6. 监控与日志 ### 6.1 日志配置 ```javascript // config/logger.js const winston = require('winston'); const logger = winston.createLogger({ level: 'info', format: winston.format.combine( winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json() ), transports: [ new winston.transports.File({ filename: 'logs/error.log', level: 'error' }), new winston.transports.File({ filename: 'logs/combined.log' }) ] }); ``` ### 6.2 性能监控 - **响应时间监控**: 监控API响应时间 - **错误率监控**: 监控API错误率 - **数据库性能**: 监控数据库查询性能 - **内存使用**: 监控应用内存使用情况 - **CPU使用**: 监控CPU使用率 ### 6.3 告警配置 - **错误告警**: API错误率超过阈值时告警 - **性能告警**: 响应时间超过阈值时告警 - **资源告警**: 内存或CPU使用率过高时告警 - **业务告警**: 关键业务指标异常时告警 ## 7. 安全措施 ### 7.1 认证安全 - **JWT安全**: 使用强密钥和合适的过期时间 - **密码安全**: 使用bcrypt加密存储密码 - **会话管理**: 实现安全的会话管理机制 - **多因素认证**: 支持短信验证码等多因素认证 ### 7.2 数据安全 - **输入验证**: 严格验证所有输入参数 - **SQL注入防护**: 使用参数化查询防止SQL注入 - **XSS防护**: 对输出内容进行转义 - **CSRF防护**: 实现CSRF Token验证 ### 7.3 传输安全 - **HTTPS**: 强制使用HTTPS传输 - **数据加密**: 敏感数据加密存储 - **API限流**: 实现API调用频率限制 - **IP白名单**: 关键接口实现IP白名单控制 ## 8. 测试策略 ### 8.1 测试类型 - **单元测试**: 测试单个函数或方法 - **集成测试**: 测试模块间的集成 - **端到端测试**: 测试完整的业务流程 - **性能测试**: 测试系统性能和负载能力 - **安全测试**: 测试系统安全性 ### 8.2 测试工具 - **Jest**: 单元测试框架 - **Supertest**: HTTP接口测试 - **Artillery**: 性能测试工具 - **OWASP ZAP**: 安全测试工具 - **Postman**: API测试工具 ### 8.3 测试数据 - **测试数据库**: 独立的测试数据库环境 - **Mock数据**: 使用Mock数据进行测试 - **数据清理**: 测试后自动清理测试数据 - **数据隔离**: 确保测试数据不影响生产环境 ## 9. 文档管理 ### 9.1 API文档 - **Swagger**: 使用Swagger生成API文档 - **接口说明**: 详细的接口参数和返回值说明 - **示例代码**: 提供接口调用示例 - **错误码**: 完整的错误码说明 - **版本管理**: API版本变更记录 ### 9.2 开发文档 - **架构文档**: 系统架构设计文档 - **数据库文档**: 数据库设计文档 - **部署文档**: 部署和运维文档 - **开发指南**: 开发环境搭建和开发规范 - **故障排查**: 常见问题和解决方案 ## 10. 质量保证 ### 10.1 代码质量 - **代码审查**: 强制代码审查流程 - **静态分析**: 使用SonarQube进行代码质量分析 - **测试覆盖率**: 要求测试覆盖率达到80%以上 - **性能基准**: 建立性能基准和监控 - **技术债务**: 定期清理技术债务 ### 10.2 发布流程 - **持续集成**: 使用CI/CD自动化构建和测试 - **灰度发布**: 实现灰度发布机制 - **回滚策略**: 快速回滚机制 - **发布检查**: 发布前的检查清单 - **发布通知**: 发布状态通知机制 ## 11. 团队协作 ### 11.1 团队结构 - **架构师**: 负责系统架构设计和技术选型 - **后端工程师**: 负责具体功能开发 - **数据库工程师**: 负责数据库设计和优化 - **测试工程师**: 负责测试用例编写和执行 - **运维工程师**: 负责部署和运维 ### 11.2 沟通机制 - **每日站会**: 每日进度同步和问题讨论 - **周会**: 每周工作总结和计划 - **技术分享**: 定期技术分享和学习 - **代码审查**: 代码审查和技术讨论 - **文档协作**: 使用协作工具维护文档 ## 12. 风险管理 ### 12.1 技术风险 - **技术选型风险**: 评估新技术的成熟度和风险 - **性能风险**: 提前进行性能测试和优化 - **安全风险**: 定期进行安全评估和测试 - **依赖风险**: 管理第三方依赖的版本和安全性 - **数据风险**: 建立数据备份和恢复机制 ### 12.2 项目风险 - **进度风险**: 合理评估开发工期和资源需求 - **质量风险**: 建立完善的测试和质量保证机制 - **人员风险**: 知识共享和文档化减少人员依赖 - **需求风险**: 及时沟通需求变更和影响评估 - **集成风险**: 提前进行系统集成测试 ## 13. 总结 本开发文档详细规划了畜牧养殖管理平台后端服务的开发计划，包括： ### 13.1 开发亮点 - **微服务架构**: 采用模块化的微服务架构设计 - **TypeScript**: 使用TypeScript提升代码质量和开发效率 - **完善的测试**: 建立完整的测试体系保证代码质量 - **自动化部署**: 使用Docker和CI/CD实现自动化部署 - **监控告警**: 完善的监控和告警机制 ### 13.2 技术特色 - **高性能**: 通过缓存和数据库优化提升性能 - **高可用**: 集群部署和故障转移机制 - **安全性**: 多层次的安全防护措施 - **可扩展**: 模块化设计支持功能扩展 - **易维护**: 规范的代码和完善的文档 ### 13.3 开发保障 - **团队协作**: 明确的角色分工和协作机制 - **质量控制**: 严格的代码审查和测试要求 - **风险管控**: 全面的风险识别和应对措施 - **进度管理**: 详细的任务分解和时间规划 - **文档完善**: 完整的开发和API文档 ### 13.4 后续优化 - **性能优化**: 持续的性能监控和优化 - **功能扩展**: 根据业务需求扩展新功能 - **技术升级**: 跟进技术发展升级技术栈 - **用户体验**: 根据用户反馈优化接口设计 - **运维自动化**: 进一步提升运维自动化水平